fix(auth): TOTP enrollment names the deployment app name as its issuer, not Better Auth

[objectstack-fleet]

Fixes #21731

Clause-②: no

A TOTP enrollment now names the deployment, not the auth library. /two-factor/enable and /two-factor/get-totp-uri answered otpauth://totp/Better%20Auth:...&issuer=Better+Auth. They now carry the deployment's app name: OS_APP_NAME, else the configured app name, else ObjectStack. An explicitly set branding.workspace_name still outranks it. Existing enrollments keep working, because the issuer is a display label beside an unchanged secret.

What changed

• @objectstack/plugin-auth. AuthManager.createAuthInstance() passes getAppName() to better-auth as its appName. That is the one app-name authority every auth email already reads. No second read was added, and twoFactor({ issuer }) is left unset (see the better-auth reading below).
• @objectstack/cli (producer side). objectstack serve constructs AuthPlugin with appName: resolveDeploymentAppName(...). resolveDeploymentAppName is the email capability's existing chain (OS_APP_NAME > config.email.appName > config.email.defaultTemplateContext.appName > config.appName > ObjectStack), factored out of resolveEmailCapabilityArg unchanged. Both consumers now call that one resolver with the same arguments.
• Docs. The OS_APP_NAME row in content/docs/deployment/environment-variables.mdx now says what the variable names. It used to say "the OAuth app display name", which was never true.
• Changeset. .changeset/21731-totp-issuer-app-name.md, patch for both packages. It says that an existing enrollment keeps working.

Why the landing reaches packages/cli: the triage premise was false under serve

The card and triage both assumed that getAppName() honours OS_APP_NAME. Under objectstack serve it did not. serve built AuthPlugin with no appName, so getAppName() answered ObjectStack. Auth emails hid this: their own appName outranks the email service's template context (plugin-email/src/email-service.ts, the { ...defaultTemplateContext, ...input.data } merge), and the template context was the only place that carried OS_APP_NAME.

These readings come from the public door, an os dev boot (pnpm dev:todo -- --fresh, OS_AUTH_TWO_FACTOR=true, OS_APP_NAME='Acme Ops', seeded admin, secrets redacted):

build	POST /api/v1/auth/two-factor/enable totpURI	password-reset email subject (sys_email)
the serve.ts line ablated, auth-manager.ts fix in place	otpauth://totp/ObjectStack:admin%40objectos.ai?...&issuer=ObjectStack	Reset your ObjectStack password
this PR	otpauth://totp/Acme%20Ops:admin%40objectos.ai?...&issuer=Acme+Ops	(see the liveness table)

Without the serve half, the card's first pin (the issuer equals OS_APP_NAME) fails at the public door. The same root cause also fixes the auth emails' {{appName}} under serve.

better-auth 1.7.3, read off its dist

• appName is read once, at init: dist/context/create-context.mjs:131, appName: options.appName || "Better Auth".
• That context value is read in exactly two places, both otpauth URIs:
  • dist/plugins/two-factor/index.mjs:170 (enable): issuer || options?.issuer || ctx.context.appName. The first term is the request body's own issuer.
  • dist/plugins/two-factor/totp/index.mjs:133 (get-totp-uri): options?.issuer || ctx.context.appName. Here options is totpOptions, and its type omits issuer (dist/plugins/two-factor/types.d.mts:25 declares totpOptions as TOTPOptions with issuer omitted).
• No other runtime read of appName exists in better-auth, @better-auth/core, sso, scim, oauth-provider, telemetry or kysely-adapter. core has 3 hits and all of them are .d.mts docs. The other packages have 0.
• No stored or wire identifier changes. The cookie prefix is the literal "better-auth" (dist/cookies/index.mjs:28). The core type doc says the prefix defaults from appName, but in 1.7.3 it does not. better-auth reads no APP_NAME env either.
• So appName is the one typed key that names both routes. twoFactor({ issuer }) alone would leave get-totp-uri on Better Auth, so the triage condition for setting it explicitly does not hold.

Liveness: what follows a branding change

reading (public door)	result
boot with OS_BRANDING_WORKSPACE_NAME='Env Brand' and OS_APP_NAME='Acme Ops', first enable	issuer=Env+Brand: the boot-time branding value reaches the issuer
after boot, PUT /api/settings/branding {"workspace_name":"Renamed Co"} (200), then enable and get-totp-uri	both still issuer=Acme+Ops
same process, password-reset email	subject Reset your Renamed Co password

ctx.context.appName is fixed when the better-auth instance is built. A rename after that reaches the issuer at the next rebuild (a restart, or an auth-settings change that calls applyConfigPatch). Auth emails follow it on the next send. No route in auth-manager.ts follows the live value on both TOTP routes without rebuilding the instance: a getter-backed twoFactor({ issuer }) would follow it on enable only. The divergence is recorded in the report's open question for the PM, and the code comment and changeset state it.

Tests (HEAD e7e32f4f)

• packages/plugins/plugin-auth/src/two-factor-totp-issuer.test.ts (new, real better-auth pipeline through AuthManager.handleRequest, on the in-memory engine the sibling 2FA suites use):
  • the configured app name is the issuer and the label prefix on enable, and ObjectStack when unset;
  • get-totp-uri names the same issuer for the same secret;
  • a branding override set before the instance is built outranks the configured name;
  • still-works: an enrollment made under the Better Auth label and confirmed is then served by a process configured as Acme Ops over the same store. The codes from the OLD URI's secret complete a sign-in challenge, and get-totp-uri returns the same secret relabelled. The stored row does not contain the label.
• packages/cli/src/commands/serve-auth-app-name.contract.test.ts (new, unit tier):
  • resolveDeploymentAppName equals the email chain's answer on all five rungs;
  • a comment-masked scan of serve.ts finds exactly one new AuthPlugin( call, passing appName: resolveDeploymentAppName(...) with the same argument text as the one resolveEmailCapabilityArg(...) call.
• pnpm --filter @objectstack/plugin-auth exec vitest run --maxWorkers=2: 119 files, 2509 passed, 10 skipped.
• pnpm --filter @objectstack/plugin-auth typecheck: exit 0. It includes check:test-typecheck, and the new file compiles clean, with no ledger entry.
• pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 258 files, 3777 passed. The integration tier is left to CI, because the diff touches no spawn entry and no integration-tier file.
• pnpm --filter @objectstack/cli typecheck: exit 0.

Ablations (each through scripts/ablation-replace.mjs, restore proven blob == HEAD)

• auth-manager.ts without the appName line: all 5 new plugin-auth tests turn red, for example expected { labelIssuer: 'Better Auth', ... } to match object { labelIssuer: 'Acme Ops', ... }. Restored to blob a6696db0, which equals HEAD.
• serve.ts without the AuthPlugin appName line: the construction scan turns red (AuthPlugin must receive appName from resolveDeploymentAppName: expected +0 to be 1). Restored to blob 121c8125, which equals HEAD.
• The same serve.ts mutation was rebuilt into packages/cli/dist and booted (ablation-dist-preflight --absent passed). The result is the ObjectStack row in the first table. The restore leg rebuilt dist and the preflight found the marker present again, with a clean tree.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 99 commands from this branch, and every one exited 0. --ran reports: 99 derived, 99 run, 0 NOT-MEASURED, 0 UNRUN. ESLint (--no-inline-config) on the 4 changed TS files reports 0 errors and 0 warnings. That run covers only the changed files. eslint.config.mjs lints **/*.{ts,...} and never enables type-aware linting, so this diff cannot move a verdict on an untouched file.

Acceptance notes

• AuthPluginOptions does not declare appName, although AuthPlugin forwards it to AuthManager by spread. serve imports the plugin through a variable specifier, so the call is untyped. A typed host writing new AuthPlugin({ appName }) gets a loud excess-property error, not a silent drop. Declaring it would widen a published type, so it is left out of this PR, which is Clause-②: no. Carrier: none.
• Watch item for a better-auth upgrade: if a later version makes the cookie prefix default from appName, as its type doc already claims, the appName passed here would rename session cookies on upgrade. Re-check dist/cookies when bumping. Carrier: whoever bumps better-auth.
• plugin-dev and the verify harness construct AuthPlugin without appName. Neither reads OS_APP_NAME anywhere, so no surface there disagrees with another. Noted only.
• /two-factor/enable accepts a request-body issuer (vendor behaviour, first term above). It only relabels the caller's own enrollment and is display-only. Noted only.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/plugin-auth, touching 5 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/contracts/auth-service.mdx (via AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx (via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AuthManager (symbol, a top-level class))

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os serve (command, 30 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 35 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json ea7ff394b6d802de9ad0448130bef86d4407760d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 2e95b03c8ce44ebb0efb2d64e51dfee7d0455317 — the merge of head e7e32f4f140686fa59eb74bd772d35ff73a5c5dc into base ea7ff394b6d802de9ad0448130bef86d4407760d, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2e95b03c8ce44ebb0efb2d64e51dfee7d0455317 && git checkout 2e95b03c8ce44ebb0efb2d64e51dfee7d0455317
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ea7ff394b6d802de9ad0448130bef86d4407760d e7e32f4f140686fa59eb74bd772d35ff73a5c5dc && git checkout -B drift-repro ea7ff394b6d802de9ad0448130bef86d4407760d && git merge --no-ff e7e32f4f140686fa59eb74bd772d35ff73a5c5dc

node scripts/docs-audit/affected-docs.mjs --json ea7ff394b6d802de9ad0448130bef86d4407760d

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ea7ff394b6d802de9ad0448130bef86d4407760d → pass the list as
args.docs, on the commit named under Which tree this was computed on.