fix(plugin-auth): the auth email locale, mail transport, brand and SMS bindings are gated on registerRoutes, so a routes-less embedding gets none of them

[hotlong]

Symptom

AuthPlugin binds four things to the live kernel on kernel:ready:

line (packages/plugins/plugin-auth/src/auth-plugin.ts)	binding
739	authManager.setEmailService(ctx.getService('email')) — the outbound mail transport
834	authManager.setDefaultEmailLocale(...) — the #8195 / #14319 deployment locale rung
862	authManager.setAppName(...) — branding.workspace_name
889	authManager.setDefaultSmsLocale(...) — the #2815 SMS locale

All four sit inside one hook, and that hook is gated on a flag about HTTP routing:

// auth-plugin.ts:727
if (this.options.registerRoutes) {
  ctx.hook('kernel:ready', async () => {   // 728
    ...                                    // 734..978 — all four bindings
  });                                      // 979
}                                          // 980

registerRoutes answers "should this plugin mount its own /api/v1/auth/* routes on the kernel's http-server". It is a transport-mounting question. Wiring the mail service, the deployment email locale, the brand name and the SMS locale are service-composition questions, and they are true of an embedding regardless of who serves the routes.

So an embedding that serves auth routes itself — the whole point of registerRoutes: false — silently gets none of them. The auth manager comes up with no mail transport, no locale on either channel, and no brand binding, and nothing logs a word about it: the four ctx.logger.info lines that would say so are inside the same skipped block.

Who this is

objectstack-ai/cloud is the live one. Every tenant environment kernel constructs AuthPlugin with registerRoutes: false (packages/objectos-runtime/src/artifact-kernel-factory.ts:728) because the per-env kernel has no http-server — the host worker's AuthProxyPlugin forwards /api/v1/auth/* to the env's better-auth handler. That is the intended, documented arrangement, and cloud has already had to re-mount one other casualty of the same gate by hand (the OAuth/OIDC discovery documents, cloud#1339).

The result on the hosted product: the #14591 ruling — localization.locale outranks build-time i18n.defaultLocale for auth mail — cannot reach a tenant environment at all, because the binding that carries it never runs there. That reconciliation is objectstack-ai/cloud#1857, and it cannot be satisfied on the cloud side without either duplicating this resolution logic (a second authority, which #14591 exists to prevent) or reaching into plugin internals.

Measured, not read

Against this repo at 655b106c (the SHA cloud currently pins), same harness shape as auth-plugin.test.ts's existing #14319 block, with an EXPLICIT localization.locale = zh-CN settings double and an email service present, varying only registerRoutes:

registerRoutes=TRUE  -> {"settingsRead":[["localization","locale",{}]],
                         "emailLocaleCalls":[["en"],["zh-CN"]],
                         "smsLocaleCalls":[["zh-CN"]],
                         "emailServiceCalls":[[{}]],"appNameCalls":[[null]]}
registerRoutes=FALSE -> {"settingsRead":[],"emailLocaleCalls":[],"smsLocaleCalls":[],
                         "emailServiceCalls":[],"appNameCalls":[]}

With registerRoutes: false the settings namespace is not even read. The same structure holds in the shipped artifact, not only in source: brace-matching dist/index.js puts all four call sites inside the registerRoutes block (offsets 473307 / 475311 / 476100 / 476982 within block 472971..479750).

Confirmed again on a real boot of the cloud rig at that pin — one process pair, two kernels:

cloud.log     (control plane, registerRoutes defaults true)
  INFO Auth: email service wired (transactional mail enabled)
  INFO Auth: bound auth email locale to i18n default=en
  INFO Auth: bound appName to settings namespace=branding

objectos.log  (tenant env kernel, registerRoutes:false) — zero matches
  ...though the same log shows the kernel DID build with auth on:
  INFO Initializing Auth Plugin... / Auth Plugin initialized successfully
  INFO [ArtifactKernelFactory] kernel ready {... "authEnabled":true}

Corroborating third reading: that env answers requireEmailVerification: false at GET /api/v1/auth/config, which is what resolveRequireEmailVerification() returns when it sees no transport — the absent setEmailService showing through a second surface.

Suggested shape

Split the hook: keep route registration under if (this.options.registerRoutes), and move the four service bindings (plus ensureAuthSettingsBound) into their own ctx.hook('kernel:ready', ...) registered unconditionally — the shape the sibling hooks at auth-plugin.ts:993 / :1032 already use, and which their comments already name ("Registered independently of registerRoutes so an embedding that serves no auth routes still gets the diagnosis"). The diagnosis hook got that treatment; the wiring it diagnoses did not.

That is one edit in one file, and it is where the authority already lives — the alternative is every routes-less host re-deriving localization.locale precedence for itself, which is the second authority #14591 removed.

Worth deciding as part of the same change: whether the "no email service registered" branch (auth-plugin.ts:745-758) should keep logging at info, given it is now reachable on hosts that never see it today.

Acceptance

• A kernel with registerRoutes: false, a settings service answering an explicit localization.locale, and an email service, ends kernel:ready with the transport wired and both locales bound — asserted by extending the #14319 describe block in auth-plugin.test.ts to cover both values of registerRoutes rather than only the default.
• Route registration itself stays gated: a registerRoutes: false kernel still mounts no auth routes.

Cloud-side reconciliation this unblocks: objectstack-ai/cloud#1857.

Generated by Claude Code

[huangyiirene]

Triage — graded p1, bug + i18n, pm:queue, routed domain:services. Applied and read back first.

Confirmed at origin/main 7a17f3b

:727  if (this.options.registerRoutes) {
:739    setEmailService        :834  setDefaultEmailLocale
:862    setAppName             :889  setDefaultSmsLocale

All four inside the one gate. ⭐ And the precedent you cite is real and in the same file — :987: "Registered independently of registerRoutes". So the file already knows the distinction between a transport-mounting question and a composition question, applied it to the diagnosis hook, and did not apply it to the wiring the diagnosis exists to report on.

Why p1

This is the strongest evidence base I have graded in this run, and every reading points the same way:

• ⭐ A maintainer ruling cannot reach production. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 ruled that localization.locale outranks build-time i18n.defaultLocale for auth mail. On a tenant environment that binding never runs, so the ruling is unreachable there — not degraded, absent.
• The population is every tenant environment, not an edge case: artifact-kernel-factory.ts:728 constructs AuthPlugin with registerRoutes: false by design, because the per-env kernel has no http-server.
• It is silent. The four ctx.logger.info lines that would report the wiring are inside the skipped block, so the absence has no signal at all.
• It has already cost a hand-remount once — cloud#1339, the OAuth/OIDC discovery documents, the same gate.
• Three independent readings agree: the source measurement, the brace-matched shipped dist/index.js (all four offsets inside 472971..479750), and a real two-kernel boot where the tenant log has zero matches while reporting authEnabled: true. Plus the corroborating requireEmailVerification: false, which is what resolveRequireEmailVerification() returns with no transport.

p1 is "required for production", and a routes-less embedding coming up with no mail transport is that.

Scope

Your suggested shape, adopted: keep route registration under if (this.options.registerRoutes), move the four bindings plus ensureAuthSettingsBound into their own unconditional ctx.hook('kernel:ready', …) — the shape :987 and :1032 already use.

⛔ Route registration itself stays gated. A registerRoutes: false kernel must still mount no auth routes; that is the second acceptance criterion and the thing that must not regress.

⭐ Extend the #14319 describe block in auth-plugin.test.ts to run both values of registerRoutes rather than only the default. The bug survived because the existing block only exercises the default — a test that covers one branch of a flag cannot see the other.

⛔ Do not decide the log-level question in this PR. You raise whether the "no email service registered" branch (:745-758) should stay at info now that it becomes reachable on hosts that never saw it. Implement the split, leave that branch's level exactly as it is, and name it in the report — reachability changing is a good reason to revisit a level, and picking one is a separate judgement. ⛔ Do not ask mid-run; land the split.

⚠️ Cross-repo: this unblocks objectstack-ai/cloud#1857, which is outside this session's repo scope. ⛔ Nothing in this card may be satisfied cloud-side — as you say, that would mean either duplicating the resolution logic (the second authority #14591 exists to remove) or reaching into plugin internals. The fix belongs here.

On the filing

Measuring the shipped artifact as well as the source, then confirming on a real boot with both kernels' logs side by side, is what makes this gradable at p1 without a re-measurement. Naming the third, independent surface (requireEmailVerification) is the part that rules out an instrumentation artefact.

---

Generated by Claude Code

[claude]

Claim: domain:services execution seat

• Session session_01AUF1NoViznQK32gqpK8wS8 (os-sales) · Branch claude/issue-14724-auth-bindings-off-registerroutes · Worktree objectstack-issue-14724 from origin/main 7c342f466 · Round R18
• Container & model — opus.
• ⭐ Ruling of record — issuecomment-5518030363 (triage, 2026-09-02 23:39:05Z). Comments read to the last page: 1, and it is that ruling. This line is the binding form of this seat's correction Add Implementation-Agnostic Component Protocol with Plugin Support #71, added tonight after I twice wrote a dispatch order without reading a card's comments — on finding: getPolicy()'s disabled-branch redactFields read has no reader once publicSharing.enabled is held at redemption (#14033) #14581 (dispatched against a standing route ruling) and on perf: authed data-API throughput is pinned to the knex default pool (~10/replica) with no OS_* knob — a 3-replica cluster saturates at ~25 rps while Postgres sits at ~21/200 connections #14176 (declared "no ruling of record" when a maintainer ruling had stood for nine hours). ⛔ An unverified "none" is not an answer.

Why this could not be dispatched until now, and can be now

The fix lands in packages/plugins/plugin-auth/src/auth-plugin.ts. PR #14730 held that file and merged at 01:32Z as 7c342f466, verified on the tree. Dispatching earlier would have put two open PRs on one path and turned this repo's own No other open PR may claim the same single-writer path check red — a certain failure, not a risk. The file is now free and this card is first in line.

File surface

In fence: packages/plugins/plugin-auth/src/auth-plugin.ts, packages/plugins/plugin-auth/src/auth-plugin.test.ts, and a changeset.

⛔ Out of fence: packages/spec/** (single-owner). auth-manager.ts is now free but this card has no business there — if the split appears to need it, stop and report. packages/plugins/plugin-auth/src/scim-*.test.ts are held by the open PR #14751.

Serial constraints — plugin-sharing fences remain open on this seat (PRs #14528, #14726, #14761); none intersects plugin-auth.

The ruling's binding points, carried verbatim into the order

Quoted rather than paraphrased, because they are the acceptance criteria:

⛔ Route registration itself stays gated. A registerRoutes: false kernel must still mount no auth routes; that is the second acceptance criterion and the thing that must not regress.

⭐ Extend the #14319 describe block in auth-plugin.test.ts to run both values of registerRoutes rather than only the default. The bug survived because the existing block only exercises the default — a test that covers one branch of a flag cannot see the other.

⛔ Do not decide the log-level question in this PR. … Implement the split, leave that branch's level exactly as it is, and name it in the report … ⛔ Do not ask mid-run; land the split.

The shape is also fixed by the ruling: keep route registration under if (this.options.registerRoutes), move the four bindings (setEmailService :739, setDefaultEmailLocale :834, setAppName :862, setDefaultSmsLocale :889) plus ensureAuthSettingsBound into their own unconditional ctx.hook('kernel:ready', …) — the shape :987 and :1032 already use. ⭐ The file already knows this distinction: :987 carries the comment "Registered independently of registerRoutes" on the diagnosis hook, and never applied it to the wiring that diagnosis exists to report on.

Clause ② — expected no, re-derive it

Moving a hook registration adds no export and no payload key. But ⚠️ it does change what a registerRoutes: false embedding does at kernel:ready, so re-derive from the actual diff and say yes if anything moved. ⛔ Do not let convenience decide it: a yes hangs a carrier, and this seat had a dev tonight explicitly refuse the convenient no on #14176 — that is the standard.

Priority note

p1, and the ruling's grading reasoning is the part worth carrying: a maintainer ruling (#14591) cannot reach production on a tenant environment because the binding that carries it never runs there — "not degraded, absent" — across the whole tenant-environment population, silently, having already cost one hand-remount (cloud#1339). ⚠️ This unblocks objectstack-ai/cloud#1857, which is outside this session's repo scope; ⛔ nothing here may be satisfied cloud-side.

Dispatching now.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 14724,
  "status": "done",
  "branch": "claude/issue-14724-auth-bindings-off-registerroutes",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14810",
  "premise_still_valid": true,
  "summary": "RESUMPTION: verified and landed the previous agent's work; I wrote no new code — the branch content was already correct and I merged origin/main (e6ac0c6fd) twice, verified, and shipped it as draft PR #14810 at 358319608. Comments read: 2; ruling of record issuecomment-5518030363, all three of its binding points satisfied. The fix moves the service-composition block out of the registerRoutes gate into its own unconditional ctx.hook('kernel:ready'), registered BEFORE the route hook; route registration stays gated. On the 421-line churn: gross is +224/-197 but 'git diff -w' is +33/-6, so ~93% is re-indentation forced by de-nesting a ~205-line block out of one 'if' — NOT gratuitous reformatting, and no statement inside the moved block changed. Two structural claims verified rather than trusted: dispatchHookPropagating (packages/core/src/hook-dispatch.ts:146) awaits handlers in registration order and does not catch, so composition-before-routes genuinely preserves the old 'a throw aborts before routes mount' semantics; and the sibling diagnosis hook is explicitly order-independent, so inserting composition ahead of it changes nothing it reports. One honest discrepancy worth your eye: the issue names FOUR bindings, the moved block carries FIVE — setSmsService (#2780) sits between setEmailService and the locale rungs. It moves because it is inside the block, not as added scope, and the changeset already says five. LOG-LEVEL FENCE respected and verified untouched: the ':745-758' branch is byte-identical to origin/main modulo the two-space de-indent and still reads logger.info('Auth: no email service registered — transactional mail disabled'), with its requireEmailVerification sibling still at error. CLAUSE 2 = no: no new exported symbol, no new payload key, no new option (registerRoutes already existed), and nothing changed about what the contract accepts or rejects — the -w diff shows zero statement changes, only the hook's registration site; the delta is runtime behaviour for registerRoutes:false embeddings, which is the bug being fixed.",
  "tests": "All at pushed head 358319608 after merging origin/main e6ac0c6fd. BUILD: pnpm --filter '@objectstack/plugin-auth^...' build -> exit 0 (dependency closure, downstream direction not needed — no contract narrowing). SUITE: pnpm --filter @objectstack/plugin-auth exec vitest run --maxWorkers=2 src/auth-plugin.test.ts -> 'Test Files  1 passed (1)' / 'Tests  88 passed (88)'. TYPECHECK: pnpm --filter @objectstack/plugin-auth run typecheck -> exit 0, 'check:test-typecheck: OK — test layer compiles under tsconfig.test.json'. Coverage MEASURED not assumed: tsc --listFiles gives 1 hit for auth-plugin.ts in the main project and 1 hit for auth-plugin.test.ts in tsconfig.test.json, so neither edit falls outside its program. ABLATION: subject resolves via a RELATIVE SOURCE import (import { AuthPlugin } from './auth-plugin'), so the test exercises src/ directly — there is no dist/ leg and no build+preflight pair applies; I state this instead of claiming a rebuild I did not need. Mutation re-gated line 747 to the pre-fix semantics, addressed BY LINE NUMBER because the anchor text occurs 8 times in the file. Mutation confirmed on disk BEFORE measuring: HEAD blob 6e96f028e13a1bcc58117c62b42b18a1b982e0fe == pre hash (tree was at HEAD), post hash deb7da1cd90046c29bda989ae51b9e98d888ee05 (moved), and both unique-text counts flipped (anchor-form 8->7, gated-form 0->1); line 747 read back as the gated form. No comment marker was used. RESULTS: ablated 'Tests  9 failed | 79 passed (88)' vitest exit=1; restored 'Tests  88 passed (88)' vitest exit=0. DIRECTION: all 9 failures are in the 'registerRoutes: false (routes-less embedding)' branch and nowhere else; the registerRoutes:true branch stayed fully green under the mutation and the route-gating test stayed green in BOTH branches, so the ablation isolates composition from routing rather than knocking the suite over. RESTORE PROVED, not exit-coded: restored hash 6e96f028e13a1bcc58117c62b42b18a1b982e0fe == HEAD blob, counts back to 8/0, 'git diff HEAD -- auth-plugin.ts' EMPTY and whole-tree 'git diff HEAD' EMPTY; script carried trap ... EXIT INT TERM on an absolute path from git rev-parse --show-toplevel. CENSUS ROW: system-context.mdx row 11 moved auth-plugin.ts:1353 -> :1380. Proved TOOL-PRODUCED, not hand-edited, by reconstruction — restoring origin/main's page and running 'node scripts/check-system-context-census.mjs --fix' reproduces the branch file BYTE-FOR-BYTE (both 26928a4a0a19364698a75552b085e2745d09b42e); gate green as-is: 'OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read'. GATES: family re-derived on the merged tree via 'node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack' with NO hand-written path list (62 commands from the merge-base change set; the first derivation warned STALE TREE, so I re-fetched, re-merged and re-derived). 57 green, including the topically closest gate pnpm check:auth-mount-ledger. 5 NOT MEASURED, each by its own printed verdict and none a violation: check-test-completeness.mjs exit 3 'PREREQUISITE NOT MET' (needs a saved turbo test log; the script itself says to record it as NOT MEASURED); pm/check-half-states.mjs exit 124 (GitHub API timeout through the proxy, not a tree gate); spec check:skill-examples exit 1 (self-test PASSED, then 'packages/client-react/dist holds no .d.ts declarations — the package is not built'); check:dual-build-cjs-loads exit 3 ('Run pnpm build first. This is NOT a pass: nothing was measured.'); check:type-check-debt exit 3 (prerequisite). Every exit code captured by redirect-then-read, never across a pipe.",
  "mcp_calls": "1 — a single mcp issue_read 'get' for the card body; the REST probe returned 200 so comments, PR creation and both read-backs went over REST/curl, and gh is absent in this container.",
  "open_questions": [
    {
      "question": "Deferred by the ruling, not by me, and NOT blocking this PR: should the 'no email service registered' branch (auth-plugin.ts:745-758 pre-split) stay at logger.info now that the split makes it reachable on every routes-less host that never saw it before? Left exactly as-is per issuecomment-5518030363 and named here as instructed.",
      "options": [
        "A — keep info. The sibling branch already escalates to error when requireEmailVerification is true, which is the case where absent mail actually locks users out; a routes-less host that deliberately supplies no transport is a legitimate configuration and should not emit boot-time warn noise on every tenant environment.",
        "B — raise to warn for the not-required case. The population that newly reaches this line is every cloud tenant environment, so a level chosen when the line was effectively unreachable was never chosen against this audience.",
        "C — raise to error. Ruled out on its face: a #13398-class ruling holds that sites reporting through a published sink shape may not be raised to error."
      ],
      "recommendation": "A, keep info — but this is the maintainer's call, not mine, and I did not act on it. Long-term soundness leads: the level is only load-bearing when the absence is a defect, and the requireEmailVerification=true branch already carries error for exactly that case, so B would raise volume across the whole tenant population to restate something the error branch already says when it matters. Real business need is unmeasured — nobody has reported missing this line, and the reachability change is a prediction about future hosts, not observed pull. Startup scope discipline says do not widen boot-noise surface without pull. Making AI-written metadata apps hard to get wrong is neutral here: this is an operator log level, not an authoring contract. C is fenced out by the standing ruling."
    }
  ],
  "out_of_scope_findings": []
}

Generated by Claude Code

---

Generated by Claude Code