plugin-auth: `verify-domain` answers a FAILURE code when domain verification is DISABLED, while its sibling route answers `DOMAIN_VERIFICATION_DISABLED`

[os-warren]

Found while renaming the two lowercase error codes in register-sso-provider.ts (#10716 / PR #10858). Not fixed there: that card is a casing rename, and this is a behaviour change to which code a condition answers with. Filed rather than absorbed.

The inconsistency

The two SSO domain-verification routes handle the same condition — the feature is off for this environment, so the inner @better-auth/sso endpoint is unmounted and answers 404 with no code — and they answer it with different codes.

packages/plugins/plugin-auth/src/register-sso-provider.ts, runRequestDomainVerification:

if (resp.status === 404 && !parsed?.code) {
  return { status: 400, body: { success: false, error: { code: 'DOMAIN_VERIFICATION_DISABLED', message: 'Domain verification is not enabled for this environment (set OS_SSO_DOMAIN_VERIFICATION).' } } };
}

runVerifyDomain, same condition, a few lines later:

let message = parsed?.message || 'Domain verification failed';
if (resp.status === 404 && !parsed?.code) {
  message = 'Domain verification is not enabled for this environment (set OS_SSO_DOMAIN_VERIFICATION).';
}

That branch rewrites only the message. The code falls through to the route's generic default, so the disabled case answers 404 + the generic domain-verification-failure code while carrying the "not enabled" copy. The one machine-readable field says "verification failed"; the human-readable one says "the feature is off". They are different answers and a client can only act on the first.

This predates #10716 and is unchanged by it

Before that PR the default was the bespoke verify_domain_failed; after it, the registered DOMAIN_VERIFICATION_FAILED. Both spell "failed", neither spells "disabled" — so the rename neither introduced nor repaired this. It is named here because the rename makes it easy to see: the same file now has DOMAIN_VERIFICATION_DISABLED and DOMAIN_VERIFICATION_FAILED sitting one function apart, answering one condition two ways.

Why it is worth fixing rather than tolerating

DOMAIN_VERIFICATION_DISABLED is already registered for @objectstack/plugin-auth (packages/spec/src/api/error-code-ledger.zod.ts:340, "domain verification is off on this deployment"), so the correct code exists and costs no ledger change. A caller that wants to say "turn on OS_SSO_DOMAIN_VERIFICATION" rather than "retry, DNS may not have propagated" cannot currently tell those apart on verify-domain, only on request-domain-verification.

Also worth deciding as part of it: whether the status should stay 404 (the sibling rewrites it to 400) — the two routes differ there too, and one answer for one condition is the point.

What it would take

• runVerifyDomain's resp.status === 404 && !parsed?.code branch stamps DOMAIN_VERIFICATION_DISABLED alongside the message it already rewrites.
• Decide the status question above.
• The dogfood probe note at packages/qa/dogfood/test/admin-route-nonadmin-refusal.dogfood.test.ts:252 describes this exact response ("admin passes the gate and lands on 404 … while SSO is off") and would need updating with whatever is decided. ⚠️ That note is documentation, not an assertion — the bucket loop only asserts the code is not PERMISSION_DENIED — so nothing goes red on its own here.
• It is a wire-visible change to a published endpoint, so contract-review tier.

Refs

#10716 · PR #10858 (where this surfaced) · #10534 (the SSO mount documentation card) · ADR-0112

[huangyiirene]

Triage: pm:queue, domain:services, type Bug — triage seat, session session_016N5bHZr1DG4g9RK7v36YtV. Rationale: this is declared≠enforced restoration, not a new contract decision — the ledger already registers DOMAIN_VERIFICATION_DISABLED for @objectstack/plugin-auth with exactly this meaning ("domain verification is off on this deployment"), and runVerifyDomain answers the condition with a code whose registered meaning is a different condition. Pulling the route back to the ledger's declared semantics is queue work, not inbox work.

Notes for the services seat at claim time:

• Clause-②: yes — wire-visible change to a published endpoint (code and possibly status). Dispatch at the contract-review tier per the claim-comment contract; the card cannot enter the queue while flagged without it.
• Status question (404 vs 400): the governing invariant is the filer's own line — one answer for one condition. The sibling route in the same file already answers this condition 400 + DOMAIN_VERIFICATION_DISABLED; parity with the sibling is the default. If the dev measures a reason the two routes must diverge, that is a needs_decision return, not a silent choice.
• Same file as in-flight plugin-auth: register-sso-provider emits two lowercase wire-visible error codes (request_domain_verification_failed, verify_domain_failed) — ADR-0112 violation invisible to the casing gate #10716 / PR fix(plugin-auth): answer a registered ADR-0112 code from the SSO domain-verification routes #10858 (the casing rename) — hot-file serial: land after fix(plugin-auth): answer a registered ADR-0112 code from the SSO domain-verification routes #10858, and re-verify the default-code line on the merged ref (the rename changes the exact identifier this fix sits next to).
• Include the dogfood probe-note update (admin-route-nonadmin-refusal.dogfood.test.ts:252) in the same PR — documentation-only, nothing asserts it.

---

Generated by Claude Code

[os-warren]

Claim: dispatched.

• session: user-29 [974948]
• branch: claude/issue-10859-verify-domain-disabled-code
• worktree: ../objectstack-10859
• Clause-②: YES — the emitted error vocabulary of a published endpoint changes. Develop at claude-opus-5 (this seat's contract-review-tier allocation is exhausted; CONTRACT_REVIEW_TIER reads claude-fable-5 at scripts/pm/dispatch-gates.mjs:1932). PR stays draft; needs:contract-review hung as the compensating control. ⛔ This seat does not clear that label.
• serial constraint: packages/plugins/plugin-auth/src/register-sso-provider.ts. Free — fix(plugin-auth): answer a registered ADR-0112 code from the SSO domain-verification routes #10858 merged at 01:41Z. ⚠️ [security-sensitive] 2FA re-enrollment rotates the TOTP secret in place and keeps verified=1 (integrity/availability) #10700 is in flight in the same package but on the two-factor surface; do not touch it, and expect to share only the changeset directory (one file each, no conflict).

Scope

The card is precise and I am not restating it. Two things I am pinning as PM decisions so they are not re-litigated:

The registered code exists, so this needs no packages/spec change. DOMAIN_VERIFICATION_DISABLED is already registered for @objectstack/plugin-auth (error-code-ledger.zod.ts:340). ⛔ This lane has zero packages/spec ownership — if you conclude a ledger edit is required, stop and report rather than reaching into spec.

The status question is yours to answer with a measurement, not to skip. The card asks whether verify-domain should stay 404 while its sibling rewrites to 400. "One answer for one condition" is the card's point, so answering the code half and leaving the status half unexamined is not a complete discharge. Measure what each route answers today, state what you chose and why. If the evidence does not separate them, report needs_decision — do not pick to make the card closeable.

What the card already measured — do not re-derive it wrong

⚠️ admin-route-nonadmin-refusal.dogfood.test.ts:252 is a note: string — documentation, not an assertion. The bucket loop only asserts the code is not PERMISSION_DENIED and never reads note. So nothing goes red on its own here: change the response and that line goes quietly stale. Update it deliberately. This exact mis-premise was inherited once already on #10858 and caught there; do not re-inherit it.

Pins — both directions

• disabled ⇒ DOMAIN_VERIFICATION_DISABLED, on both routes, with the status you chose. ADR-0112: assert code AND status.
• a genuine verification failure still answers the failure code. An implementation that stamps DISABLED on every 404 would pass a one-directional suite while destroying the diagnosis a caller acts on. This is the load-bearing leg — fix(plugin-auth): answer a registered ADR-0112 code from the SSO domain-verification routes #10858's ② (vendor pass-through preserved) is the precedent.
• the vendor's own parsed?.code pass-through must be preserved untouched on both routes.

Standing proof standard

Ablation with the signature predicted first; restore proved byte-identical by git hash-object. Prove src/ vs dist/ resolution argued from the files — #10954 measured plugin-auth as having no dist/ at all and no vitest alias; re-verify rather than inheriting it. Zero-hit counter-check with a positive control on the same corpus. Gate union derived on the final commit, clean tree, dispatch-gates.mjs with no path arguments, exit codes captured before any pipe. Class #10309 is live — run check:error-code-casing, check:dispatcher-error-vocabulary and check:route-envelope explicitly and say whether the derivation named them. Changeset required. Never git stash. Never report a grep hit count as a fact count.

⛔ No reproduction recipes: this is auth surface. Do not touch content/docs/releases/**.

Refs

#10716 / PR #10858 (where this surfaced; its ② pin is the precedent) · #10534 · ADR-0112

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 10859,
  "status": "done",
  "branch": "claude/issue-10859-verify-domain-disabled-code",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11004",
  "premise_still_valid": true,
  "summary": "Premise re-derived on origin/main 047ac86ee before editing and holds exactly as quoted. BEFORE — request-domain-verification/disabled: 400 DOMAIN_VERIFICATION_DISABLED; verify-domain/disabled: 404 DOMAIN_VERIFICATION_FAILED (the branch rewrote only `message`, the code fell through to the generic default). AFTER — verify-domain/disabled: 400 DOMAIN_VERIFICATION_DISABLED; sibling unchanged; both non-disabled arms of verify-domain unchanged (uncoded failure keeps DOMAIN_VERIFICATION_FAILED at the inner status, vendor-coded failure passes code AND status through untouched). STATUS QUESTION ANSWERED: 400, parity with the sibling — see the four measurements below, not a coin-flip. Dogfood note at line 261 updated deliberately (it is a `note:` string the bucket loop never reads, so nothing went red on its own — confirmed by reading the loop, which asserts only status not-in-[401,403] and code !== PERMISSION_DENIED). No packages/spec change: both codes were already registered. Changeset ships `minor` with the breaking-vs-not call argued in the open, not settled silently. PR is DRAFT and stays draft; needs:contract-review untouched.",
  "tests": "All heavy work through scripts/pm/os-verify-lock.sh; every exit code captured BEFORE any pipe (cmd > file 2>&1; EXIT=$?). Gate union derived on the FINAL commit 93c4f7c9b with a clean tree, `node scripts/pm/dispatch-gates.mjs` NO path args (derived 4 paths vs merge base 047ac86ee; committed 4, working tree 0, untracked 0). PACKAGE SUITES — @objectstack/plugin-auth typecheck EXIT=0; full suite EXIT=0 'Test Files 67 passed (67) / Tests 1406 passed (1406)'; @objectstack/dogfood typecheck EXIT=0 'total error lines: 0'. NOTE on that last one: it first came back EXIT=2 with 227 errors, 9 of them in the file I edited — ALL cascading from one unresolved import because dogfood's dependency closure was unbuilt. Built the closure and it went to zero; the 227 were the unbuilt-closure trap, not my change, and I resolved it by building rather than by arguing. TARGET SUITE 12 tests (6 pre-existing from #10716 + 6 added), all green. GATES, each read from its OWN printed verdict line, never a bare $? — 15 derived: check:changeset-gate-self-tests, spec check:empty-state, spec check:liveness, check:objectui-changeset, check:slot-lookup, spec check:strictness-ledger, check:test-source-alias, check:type-source-resolution, spec check:variant-docs, check-adr-0087-registration ('✓ this PR adds no declared-breaking changeset (1 non-breaking changeset(s) seen)'), check-changeset-no-major ('✓ This diff introduces no `major` bump'), check-ci-filter-parity, check-empty-changeset ('✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added)'), check-plugin-teardown-shape, check-affected-docs — all EXIT=0. 5 convention-triggered (this change adds test code): check:query-options-erasure, check:type-check-coverage, check:engine-double-contract, check:where-matcher, and check:type-check-debt --re-measure run against the BUILT workspace closure (turbo run build exactly as lint.yml does) — '33 ledger entr(ies) re-measured in 339.3s, 1908 raw tsc error(s) total, none above its recorded number'. Plus check:nul-bytes ('OK, scanned 6350 text file(s), no raw ASCII control bytes') and a manual control-byte grep over my 4 files (no hits). CLASS #10309 RUN EXPLICITLY — and the path derivation did NOT name any of the three: check:error-code-casing ('✓ no unlisted lowercase error codes in 4414 scanned file(s)'), check:dispatcher-error-vocabulary ('OK — 21 unregistered code-stamping site(s), all classified'), check:route-envelope ('✓ 4 module(s) discovered and audited'; its 2 ratchet warnings are pre-existing and sit in packages/rest, not my paths). Screened every gate log for 'PREREQUISITE NOT MET' / 'Nothing was checked' / 'Command not found' / zero-match ERR_PNPM: no hits, so no refusal is being read as a pass. ABLATION — predictions written to a file BEFORE either mutation, both legs. Leg A (remove the fix, message-only rewrite): PREDICTED exactly 2 red, the disabled case and the both-routes parity case, 10 green; OBSERVED exactly those 2, 10 green, 'AssertionError: expected DOMAIN_VERIFICATION_FAILED to be DOMAIN_VERIFICATION_DISABLED'. Leg B (over-broad guard `if (resp.status === 404)`, dropping `&& !parsed?.code` — the hazard the PM named): PREDICTED exactly 1 red, the vendor-coded-404 case, 11 green; OBSERVED exactly that 1, 11 green, 'AssertionError: expected DOMAIN_VERIFICATION_DISABLED to be NO_PENDING_VERIFICATION'. Leg B is load-bearing precisely because the pre-existing #10716 pass-through test drives status 400, not 404, so it stays GREEN under that mutation — only the newly added leg catches it. HONEST CORRECTION: my written prediction mis-stated the totals as 10 tests (the suite has 12); I appended the correction to the prediction file when I saw it, and the predicted FAILING SETS — the falsifiable part — were exact on both legs. RESTORE HASHES, byte-identical both times: pristine 429a1399ba1cf23ee5708de0e3aeb2ca1fbbfff2; A mutated 19e47f3a6bd7e704c3227de43bf6ca7410bf399d -> restored 429a1399ba1cf23ee5708de0e3aeb2ca1fbbfff2 (ablation marker count 0); B mutated b155a69cfa25d8678bd6490a7e80664a0ddff008 -> restored 429a1399ba1cf23ee5708de0e3aeb2ca1fbbfff2 (marker count 0); FINAL 429a1399ba1cf23ee5708de0e3aeb2ca1fbbfff2. SRC-vs-DIST PROOF, argued from the files and re-verified rather than inherited from #10954: `ls -d packages/plugins/plugin-auth/dist` -> 'No such file or directory'; its vitest.config.ts contains no resolve.alias at all (whole file is environment+testTimeout); the test imports the subject as the RELATIVE specifier './register-sso-provider.js', which never consults the package exports map (that map points at dist/). So the resolved artifact IS src/ and no rebuild can silently invalidate a leg. Positive control for that claim: both ablations edited ONLY src/, ran NO build, and the suite results changed — which is impossible if the subject came from a dist/ that does not exist. By contrast the same file imports @objectstack/spec/api by PACKAGE specifier, which does resolve through exports to dist/, which is why the dependency closure had to be built first. ZERO-HIT COUNTER-CHECK with a positive control on the same corpus (6277 tracked files, CHANGELOGs excluded): searching for a site still pairing verify-domain's disabled case with 404 + the FAILURE code returns exactly 1 hit, and it is my own deliberately past-tense clause inside the updated dogfood note ('it answered 404 DOMAIN_VERIFICATION_FAILED before') — no live claim survives. Positive control on the identical corpus/tool: bare 'DOMAIN_VERIFICATION_FAILED' returns 9 files, so the zero is a measurement and not a broken search.",
  "open_questions": [
    {
      "question": "Is this `minor` or `major`? I shipped `minor` and argued both sides in the changeset and PR body rather than deciding it silently — it is genuinely a reviewer's call and this is a contract-review-tier PR.",
      "options": [
        "minor (shipped) — the emitted vocabulary gains no member (both codes already registered for @objectstack/plugin-auth), and the old pairing was self-contradictory (a code meaning 'verification failed' under a message saying 'the feature is off') rather than a contract anyone relied on deliberately. Same call #10716 made on these two routes.",
        "major — unlike #10716, whose old spellings were undeclared values no schema admitted, DOMAIN_VERIFICATION_FAILED IS a declared registered code, so a client keyed to it for the disabled case was keyed to something the published contract admitted; and BOTH halves of the answer change here (code 404->400 and status)."
      ],
      "recommendation": "minor, on the #10716 precedent — but I am explicitly NOT treating this as settled. check-changeset-no-major and check-adr-0087-registration both pass either way (they only assert no `major` is present), so no gate will catch this if the reviewer disagrees; it needs a human read during contract review."
    }
  ],
  "out_of_scope_findings": [
    "NOT filed — already open as #10615 ('[finding] @objectstack/plugin-auth's TEST_DEBT records 109 where tsc now reports 98 — an 11-error surplus'). Searched open issues before filing, per the file-first-search rule, and found it. My run re-measures the same standing condition slightly drifted: tsc now reports 97, so the surplus is 12, not 11. Not mine and not introduced here — scripts/check-type-check-coverage.mjs is untouched by this branch and its last three commits are #10896/#10876/#10820. I did not run `--lower`: it fails none of my gates, it is a different defect class from this card, and silently absorbing it would be unreported scope creep."
  ]
}

---

Generated by Claude Code