fix(plugin-auth): phone send-otp with no deliverable SMS service answers 400 SMS_SERVICE_REQUIRED instead of a bare 500

[objectstack-fleet]

Fixes #21793
Clause-②: yes (widening)

What changed

POST /api/v1/auth/phone-number/send-otp on a deployment with phone sign-in on but no SMS service that can deliver a code (none wired, or only the log transport in production) answered 500 with an empty body. It now answers 400 with { "code": "SMS_SERVICE_REQUIRED", "message": "..." }.

• packages/plugins/plugin-auth/src/auth-manager.ts: the no-provider branch of deliverPhoneOtp throws better-auth's APIError('BAD_REQUEST', { message, code: 'SMS_SERVICE_REQUIRED' }), the same construction the sibling refusals in this file use (for example PASSWORD_POLICY_VIOLATION). The message names the missing SMS delivery service and where an administrator configures it (Setup, Settings, SMS Delivery), and points the user at phone and password sign-in. It never carries the one-time code. The quota branch and the delivery path are unchanged. Four doc comments that said NOT_SUPPORTED now name the new answer.
• packages/spec/src/api/error-code-ledger.zod.ts: SMS_SERVICE_REQUIRED is registered for @objectstack/plugin-auth, beside EMAIL_SERVICE_REQUIRED. The reference pages content/docs/references/api/{contract,error-code-ledger}.mdx are regenerated (gen:docs, as check:generated named).
• content/docs/permissions/authentication.mdx: the two passages that said "fails loudly with NOT_SUPPORTED" now state the 400 and the code. The first also says that request-password-reset keeps answering {status:true}.
• docs/qa/platform-checklist/areas/identity-auth.json: identity-auth.auth-method-matrix (revision 5) names the shipped refusal in clause 4, its negative, step 4, the fixtures row and the variant. A bare 500 is now named a FAIL, and the clause cites the door pin.
• Changeset: @objectstack/spec minor (the ledger accepts one more value), @objectstack/plugin-auth patch (the bug fix).

H2: which branch, and the measurement that decided it

Branch (b): a new registered code. No registered code honestly names "phone OTP needs an SMS delivery service" (measured at merge base 6fb71152c):

• @objectstack/plugin-auth's row: EMAIL_SERVICE_REQUIRED names the email service. PHONE_NOT_ENABLED means the phone plugin is off, which is not this case. INVITE_SMS_FAILED is a failed invitation send. No other row is about SMS.
• The standard catalog has no SMS member. SERVICE_UNAVAILABLE and NOT_IMPLEMENTED misname the cause and are 5xx.
• No other package's row names SMS delivery.

The spelling SMS_SERVICE_REQUIRED already exists in this package: sendPhoneInviteSms throws it as a plain-Error prefix for the same condition. So one name now covers one condition. It passes the #8211 synonym rule, because the token SMS is in no standard member. The status is 400, the status of the email sibling (admin-import-users.ts answers EMAIL_SERVICE_REQUIRED with fail(400, ...)).

Mechanism hypotheses, measured

All door readings use the real AuthManager.handleRequest over the installed better-auth 1.7.3 / better-call 1.4.0.

• H1, confirmed. Before the fix, the no-provider branch answered 500, no content-type, body "" (measured under the ablation below). The quota branch answered 429, application/json, {"message":"Too many verification codes requested. Please try again later."}, with no code field. After the fix, no-provider answers 400, application/json, {"message":"Phone verification codes are unavailable: ...","code":"SMS_SERVICE_REQUIRED"}. The quota answer is unchanged.
• H2: see above.
• H3: 400, from the email sibling.
• H4, confirmed at objectui 9dfaca65 (the .objectui-sha pin). packages/auth/src/createAuthClient.ts postPhoneNumberEndpoint reads the top-level payload.code and payload.message of this vendor-shaped body. LoginForm.handleSendOtp shows errorMessages[code] if one is mapped, and the message otherwise. Before the fix the payload was null, so the user saw "Auth request failed with status 500".

Tests

• New packages/plugins/plugin-auth/src/phone-otp-no-sms-service-refusal.test.ts is the door pin. It sends a real request through a real better-auth pipeline and a pinned memory engine. It checks:
  • With no SMS service: 400, code === 'SMS_SERVICE_REQUIRED', and ErrorCode.safeParse(code) succeeds, so the code is registered.
  • The refusal text never contains the OTP that better-auth stored.
  • With NODE_ENV=production and a log-only transport: the same 400 and code, and nothing is sent.
  • request-password-reset for a registered number still answers 200 {status:true}. A pass-through spy proves the route reached the refusing send.
  • Outside production, a log-only transport still delivers.
• In auth-manager.test.ts, the old rejects.toThrow(/NOT_SUPPORTED/) case became two cases on the error object: isAPIError, BAD_REQUEST/400, body.code, and no code in the message.
• Ablation. The plain Error was put back through scripts/ablation-replace.mjs (mutation landed: anchor 1 to 0, blob 9d24bb3f to 9c6b1b90). Result: 5 failed / 282 passed. That is 3 door cases (expected 500 to be 400, and the deliver spy rejects with Error: NOT_SUPPORTED... instead of the 400 shape) and 2 unit cases (isAPIError false, statusCode undefined). The tool's restore leg proved blob == HEAD 9d24bb3f and an empty git diff HEAD. The first attempt was refused by the tool before any test ran, because the replacement text contained the anchor. It was redone with a whole-block anchor.
• pnpm --filter @objectstack/plugin-auth exec vitest run: 120 files, 2515 passed, 10 skipped (at b37edd67). Typecheck exit 0. After the last test-file edit, the two changed files were re-run at 3e8ab846: 286 passed.
• pnpm --filter @objectstack/spec exec vitest run: 668 files, 19286 passed, 1 todo (at b37edd67). Typecheck exit 0 (at 3e8ab846).
• pnpm --filter @objectstack/spec check:generated: all 15 artifacts up to date, after a spec rebuild on the final merge c6b17163.
• Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at c6b17163 derived 124 commands. All 124 were run on that head and exited 0. --ran with the exit codes recorded: 124 derived, 124 run, 0 NOT-MEASURED, 0 UNRUN. On the first pass (at b37edd67), check:engine-double-contract and check:objectql-double-limit were red on the new test's engine double. The double now applies limit/offset by presence, and --write recorded the pinned double (additions only). The local scope is the targeted set above; the rest of the farm is CI's.

Riding comments (domain:spec pointer 5989650462)

These are comment-only edits in error-code-ledger.zod.ts. No code, status or owner moved. Each claim was checked against the tree:

1. DRIVER_UNAVAILABLE (@objectstack/cloud-connection): rewritten. Measured: the only emitter is the purge-sample-data door (marketplace-install-local-plugin.ts, the !ql || !metadata branch, 500, introduced by fix(cloud-connection): install-local purge deletes seed rows through the engine by their seed key #21773). So the comment now states that condition, rather than adding it as an "also".
2. RESEED_SKIPPED: not edited. The claim does not hold on this tree. Since fix(cloud-connection): refuse install-local sample data for a session with no active organization (ADR-0123 D2/D4) #21780 (e09f1aca), a walled session with no active organization gets 403 PERMISSION_DENIED on the purge (and on the reseed), through NO_ACTIVE_ORGANIZATION_CODE. RESEED_SKIPPED is now emitted only by the reseed, for its other declines. The existing comment ("reseed declined to run; message carries why") is accurate.
3. OS_PROTOCOL_INCOMPATIBLE (@objectstack/metadata-core): rewritten to name both doors. POST /api/v1/packages (runtime/src/domains/packages.ts) and, since fix(cloud-connection): install-local runs the ADR-0087 D1 protocol handshake and refuses with the packages door answer (422) #21805, POST /api/v1/marketplace/install-local both answer through the shared protocolIncompatibleAnswer.

Acceptance notes

• The quota branch answers 429 with no code in its body (measured above). This is deliberate: auth-manager.test.ts pins bodyCode: undefined, so both walls look the same from outside. It is untouched here.
• sendPhoneInviteSms still throws a plain Error('SMS_SERVICE_REQUIRED: ...') when no SMS service is wired. No door reaches that throw, because its one caller gates on isSmsServiceAvailable() first. It is the delivery path, so it was out of scope and is unchanged.
• Files outside the expected surface, all made false or required by this change: the checklist item, the two regenerated reference pages, and scripts/engine-double-contract.pinned.json. That last one records the new pinned test double, written by check-engine-double-contract.mjs --write, additions only.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/api/environment-routing.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/api/error-catalog.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/api/error-handling-server.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/getting-started/examples.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/kernel/contracts/auth-service.mdx (via AuthManager (symbol, a top-level class))
• content/docs/kernel/contracts/data-engine.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/kernel/contracts/metadata-service.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/kernel/services-checklist.mdx (via AuthManager (symbol, a top-level class), /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/permissions/authentication.mdx (via AuthManager (symbol, a top-level class), SMS_SERVICE_REQUIRED (literal, a string literal in ERROR_CODE_LEDGER; a string literal in deliverPhoneOtp))
• content/docs/permissions/permission-sets.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/protocol/kernel/error-handling.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/protocol/kernel/http-protocol.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/ui/apps.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object), /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/releases/v17/17-1.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
• content/docs/releases/v17/17-4.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object), /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))
• content/docs/releases/v17/17-5.mdx (via /api/v1/packages (route, a path literal in a comment in ERROR_CODE_LEDGER))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 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 — 142 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 5b2d189e28d5563cbcaa84ac912219017692ea97 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0a698ea89bec8f446e7d9cce098c1a4c636024ac — the merge of head c6b17163b6f5f913d143262621a9e328faede810 into base 5b2d189e28d5563cbcaa84ac912219017692ea97, 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 0a698ea89bec8f446e7d9cce098c1a4c636024ac && git checkout 0a698ea89bec8f446e7d9cce098c1a4c636024ac
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5b2d189e28d5563cbcaa84ac912219017692ea97 c6b17163b6f5f913d143262621a9e328faede810 && git checkout -B drift-repro 5b2d189e28d5563cbcaa84ac912219017692ea97 && git merge --no-ff c6b17163b6f5f913d143262621a9e328faede810

node scripts/docs-audit/affected-docs.mjs --json 5b2d189e28d5563cbcaa84ac912219017692ea97

⚠️ 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 5b2d189e28d5563cbcaa84ac912219017692ea97 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c6b17163b6f5f913d143262621a9e328faede810
Local-runs: none

① Derived judgments

Net diff read three-dot against origin/main (merge-base 27991556): 10 files, +417/−30. Every accept-set or public-surface change it implies, judged:

1. ErrorCode / REGISTERED_ERROR_CODES / ApiErrorSchema.code gain SMS_SERVICE_REQUIRED under @objectstack/plugin-auth (packages/spec/src/api/error-code-ledger.zod.ts:530). This is the one widening: the ledger header itself says registering a code widens the published contract face. Right. (a) No existing row names the condition: in plugin-auth's row EMAIL_SERVICE_REQUIRED is email, PHONE_NOT_ENABLED is the plugin off, INVITE_SMS_FAILED is a failed send; NOT_SUPPORTED (the card's parenthetical) is not a StandardErrorCode member at all, and UNSUPPORTED is registered only under two other packages' rows, so an honest code for this package needs a plugin-auth row either way. (b) [finding] @objectstack/rest registers four generic synonyms the standard catalog already covers (CONFLICT, NOT_FOUND, FORBIDDEN, INTERNAL) — contract call, not a cleanup #8211 synonym rule: standardSynonymOf matches on an HTTP reason phrase or on every token being inside one standard member; SMS_SERVICE_REQUIRED is no reason phrase and the token SMS is in no standard member, so no waiver is owed; the admission suite (error-code-ledger.test.ts) ran green in Test Core. (c) The spelling already existed in this package as the sendPhoneInviteSms plain-Error prefix (auth-manager.ts:5436), so one name now covers one condition. (d) Row placement beside the email sibling rather than sorted: no gate sorts the row and the row was already unsorted (INVALID_REQUEST, OAUTH_REGISTER_FAILED sit out of order on main), acceptable. (e) check:error-code-provenance, check:error-code-casing, check:generated, check:api-surface all green on the head.
2. Wire behaviour of POST /api/v1/auth/phone-number/send-otp with no deliverable SMS service: a 500 with an empty body becomes 400 with body {message, code: "SMS_SERVICE_REQUIRED"}, thrown as better-auth's APIError('BAD_REQUEST', …) (auth-manager.ts:5358-5366), the same construction the quota branch and every other typed refusal in this file use. Right, and it is the card's Done-when verbatim (same typed API error as the quota branch, a pin on status and code). No input is newly accepted, so plugin-auth's accept set is unchanged. The net diff of auth-manager.ts is that one branch plus four comment lines (:740, :3562, :5316, :5333); the quota branch (smsQuotaExceededApiError, 429) and the delivery path below it are byte-unchanged. isPhoneOtpDeliverable() is untouched, so features.phoneNumberOtp in /api/v1/auth/config still reads false on such a deployment and the no-provider vs production-log-only distinction is the existing one.
3. Status 400 (the card asked for "a 4xx"): right, the email sibling answers fail(400, 'EMAIL_SERVICE_REQUIRED', …) in admin-import-users.ts:432.
4. Message text: names the capability, the admin fix and the password fallback; carries no OTP and no tracker number (check:doc-authoring green). Right.
5. request-password-reset: unchanged, still 200 {status:true} with nothing sent; the door pin proves the refusing send was reached for a registered number and the status does not leak existence. Right.
6. Regenerated reference pages (content/docs/references/api/{contract,error-code-ledger}.mdx, one row each, +322 more): generated output of the ledger row, check:generated and Build Docs green. Right.
7. content/docs/permissions/authentication.mdx: the two "fails loudly with NOT_SUPPORTED" passages now state 400 + code; the first also states the reset endpoint's unchanged {status:true}. Right. No other content/docs sentence at the head still names NOT_SUPPORTED for phone OTP.
8. docs/qa/platform-checklist/areas/identity-auth.json (auth-method-matrix rev 5): clause 4, its negative, step 4, the fixtures row and the variant re-pointed, a bare 500 named a FAIL, the verify cites the new door pin. Right (check:platform-checklist green); the clause was literally false after this diff without it.
9. scripts/engine-double-contract.pinned.json: +15/−0, three rows for the new test double's delete/findOne/update, written by the gate's own --write. Right, additions only.
10. Riding comments in the ledger (DRIVER_UNAVAILABLE, OS_PROTOCOL_INCOMPATIBLE): comment-only, no code, status or owner moved, so no surface change. Verified against the head: the only DRIVER_UNAVAILABLE emitter is cloud-connection/src/marketplace-install-local-plugin.ts:1997, the purge-sample-data !ql || !metadata branch at 500; OS_PROTOCOL_INCOMPATIBLE is answered by runtime/src/domains/packages.ts:1300 and marketplace-install-local-plugin.ts:1086, both through protocolIncompatibleAnswer. Right. They exceed the claim's letter ("no spec edit beyond that one ledger line") but carry no contract weight; the card records their acceptance as surface revision 1.
11. Tests: phone-otp-no-sms-service-refusal.test.ts drives real AuthManager.handleRequest over the installed better-auth pipeline and pins 400, the code, ErrorCode.safeParse(code).success, OTP absent from the body, production log-only refused with nothing sent, dev log-only still delivering; auth-manager.test.ts pins isAPIError, BAD_REQUEST/400, body.code at the unit seam. Imports (@objectstack/spec/api, @objectstack/objectql) are declared deps (check:undeclared-dep-imports, check:cross-package-test-inputs green). Right.
12. Residue, no verdict weight: packages/plugins/plugin-auth/src/auth-plugin.ts:805 is a fifth comment that still says "(NOT_SUPPORTED)", in a file the diff did not reach. Same class as the four it rewrote; a one-line follow-up, not a contract matter.

Check-runs on the head, latest run per name, 35 names: 31 success; Console Pin Gate and Packed-tarball smoke (opt-in) skipped by design; Auto Label and Check PR Size skipped on the 09:38 labeled-event run (both succeeded on the 09:32 run; neither is a derived gate family). Check Changeset succeeded on both runs. No red.

② Semver level

Changeset .changeset/21793-phone-otp-no-provider-4xx.md: @objectstack/spec: minor, @objectstack/plugin-auth: patch. Matches what the diff publishes. The widening is the ledger registration (a T4 registration tell), housed in spec, so spec takes at least minor; plugin-auth publishes a bug fix in a released package (a bare 500 becomes a typed 400, nothing newly accepted), so patch, the level the quota-branch fix of the same function took. Not skip-changeset: both packages ship the change. No narrowing: nothing that parsed before is refused, no author-writable spelling is removed or renamed, so no migration and no ADR-0087 marker is owed.

Clause-②: yes (widening) — the PR body's line 2 and the changeset body carry the identical line, well-formed under the closed yes|no + (widening)|(narrowing) spelling. The claim (comment 5989470829) declared no conditionally and pre-authorized this exact amendment for the new-code branch; the card's review (5991880705) amended it in the same act. check-changeset-no-major, check-adr-0087-registration, check-empty-changeset all green in Lint & Repo Gates; check:pm-widening-tells green.

③ Boundary flags

open_questions: empty. Dev deviations, each answered:

1. Files beyond the claim's surface (checklist item, two regenerated reference pages, the pinned-double ledger): each required or made false by the change (①.6–①.9). Answered, accepted.
2. Four comment-only lines in auth-manager.ts outside the no-provider branch: the net diff confirms they are comments naming the new answer, and mergeable_state is clean on the head. Answered.
3. Door pin as a plugin-auth unit-layer file instead of packages/qa/dogfood/test/: the seam is the real handleRequest over the real better-auth router, which is the wire answer the card asked to pin; nothing a dogfood boot would add is in question. Answered; the [PM seat] domain:cli — 🟢 os-elon-musk · session_01BmsuLyUeuG5CNpZFMH1jzS #6024 declaration lapses.
4. Riding comments: two rewritten and verified against the head (①.10); the third (RESEED_SKIPPED) not written, which changes nothing in this diff. Answered.
5. Commit trailers in AGENTS.md's model-free form: not a contract matter, hooks accepted the push. Answered.
6. The objectui read for H4: outside this brief's inputs; the wire body is the vendor-shaped {message, code} the quota branch already answered with, so nothing in the contract turns on it. Answered.
7. Full package suites at b37edd67, gates at c6b17163: superseded by the head's check-runs (Test Core 1/6–6/6 and aggregate, four Type Check jobs, three Dogfood gates, Build Core, Temporal Conformance all green). Answered.

The two out-of-scope findings (quota branch answers 429 without code; sendPhoneInviteSms keeps its plain Error behind the isSmsServiceAvailable() gate) are correctly left out of this diff and recorded in the PR's acceptance notes. Nothing escalated.

Implemented-by: claude/issue-21793-phone-otp-no-provider-4xx
Reviewed-by: session_011K3zqE8Pv1Evw5hc8tZCnN

VERDICT: PASS