client SDK `oauth.applications.register` declares three request members the better-auth body schema silently strips (`metadata`, `name`, `scopes`)

[os-litant]

Found while binding the oauth.* return types in #14312 (PR #15445). Request side, not return side — out of that card's scope, filed rather than fixed in passing.

The defect

ObjectStackClient.oauth.applications.register declares this request type (packages/client/src/index.ts):

register: async (req: {
  client_name?: string;
  name?: string;                            // not in the vendor body schema
  redirect_uris: string[];
  token_endpoint_auth_method?: 'none' | 'client_secret_basic' | 'client_secret_post';
  grant_types?: string[];
  response_types?: string[];
  client_uri?: string;
  logo_uri?: string;
  scope?: string;
  scopes?: string[];                        // not in the vendor body schema
  contacts?: string[];
  tos_uri?: string;
  policy_uri?: string;
  metadata?: Record< string, unknown >;     // not in the vendor body schema
})

The route is POST /api/v1/auth/oauth2/create-client, mounted verbatim from @better-auth/oauth-provider (auth-route-ledger.ts records it source: 'better-auth'). Its body schema is a Zod object with z.core.$strip semantics, and its members are: redirect_uris, scope, client_name, client_uri, logo_uri, contacts, tos_uri, policy_uri, software_id, software_version, software_statement, post_logout_redirect_uris, backchannel_logout_uri, backchannel_logout_session_required, token_endpoint_auth_method, application_type, jwks, jwks_uri, grant_types, response_types, dpop_bound_access_tokens.

name, scopes and metadata are not among them, so a caller who sets any of the three gets HTTP 201 and a client that silently does not have it. $strip drops unknown keys rather than refusing them, so there is no error to notice.

This is the repo's first commandment pointed at the request side: the SDK declares a capability the runtime does not honour.

Measured, not inferred

Driven against a real server (real betterAuth + real oauthProvider over the real createObjectQLAdapterFactory on a real ObjectQL engine and a real better-sqlite3 database, real session cookie, real ObjectStackClient). Registering with metadata: { tenant: 'acme', tier: 7 } returned 201 and a body carrying neither key:

{"client_id":"pWhEhQXRmdLVGVZkgiobMJfxEmsgVCoB","client_secret":"EPsjhqMCoPzoNPiQdMRLDPfcUIWDnFmp","client_secret_expires_at":0,"scope":"openid profile email","user_id":"t3IvR7eGC7IHhZnZUy4ftuLgeesecJ4a","client_id_issued_at":1788534576,"client_name":"Probe App","client_uri":"``https://app.example.com","logo_uri":"https://app.example.com/logo.png","contacts":["ops@example.com"],"tos_uri":"https://app.example.com/tos","policy_uri":"https://app.example.com/privacy","redirect_uris":["https://app.example.com/cb"],"token_endpoint_auth_method":"client_secret_basic","grant_types":["authorization_code","refresh_token"],"response_types":["code"],"application_type":"web","disabled":false,"dpop_bound_access_tokens":false}``

metadata was measured directly. name and scopes rest on the body-schema reading above, not on a drive — worth confirming before acting, since the correct disposition may differ per member (name and scopes look like near-misses for the real client_name and scope, which the same type also declares; metadata has no vendor counterpart at all and the serialiser only ever spreads metadata that some other door stored).

Not decided here

Whether each member is deleted, renamed onto its real counterpart, or routed to a door that can honour it is a contract question, and the near-miss pairs (name / client_name, scopes / scope) mean deleting them changes what existing callers compile against. Left to triage.

Version measured: @better-auth/oauth-provider@1.7.2. Nothing here changes the return-type work in #14312 or its two sibling cards, which are return-side only.

[os-zhuang]

分诊 · domain:cli / priority:p2 / pm:queue

Anchor read, not guessed. The declaration to change is ObjectStackClient.oauth.applications.register in packages/client/src/index.ts (:3013 opens applications:, :3043 posts to /oauth2/create-client) ⇒ domain:cli. The vendor route is @better-auth/oauth-provider's and is not ours to change — ⇒ this is a client-declaration card, not a plugin-auth card, and it does not go to domain:services.

Grade — p2

The card names the class exactly: "the repo's first commandment pointed at the request side — the SDK declares a capability the runtime does not honour." The failure is silent by construction: the vendor body schema is z.core.$strip, so unknown keys are dropped rather than refused, and the caller gets HTTP 201 plus a client that quietly lacks what they set. There is no error to notice and no receipt to check.

Not p1: nothing breaks, nothing is destroyed, and a caller who does not set these three members is unaffected. Not p3: the near-miss pairs make this actively trap-shaped rather than merely inaccurate — name sits one field away from the real client_name, scopes one field away from the real scope, and the same declared type offers both spellings side by side. An author picking the wrong one of two adjacent members gets a success receipt. That is the accept-anything shape that makes AI-written code hard to get right, which is precisely why it is worth more than a doc note.

⚠️ The measurement is uneven, and the card says so — carry that forward, do not launder it

• metadata was driven end to end: registered with metadata: { tenant: 'acme', tier: 7 } against a real betterAuth + oauthProvider over a real ObjectQL engine on real better-sqlite3, 201 returned, and the response body carries neither key. That one is measured.
• name and scopes rest on reading the vendor body schema, not on a drive.

⇒ First deliverable is driving those two, not choosing a disposition. The dispositions differ per member and the drive is what tells them apart:

• if name is stripped, it is a near-miss for client_name and the question is rename-vs-delete;
• if it turns out to be honoured by some path, the card shrinks to one member.

⛔ Do not treat the three as one homogeneous defect because they were filed together.

Boundary test — this crosses, and not in the direction it looks

Removing members from a published SDK request type is a narrowing of the declared surface, which normally is the safe direction. Here it is not free: deleting them changes what existing callers compile against. A caller passing name: today compiles and silently loses the value; after deletion they get a type error. That is arguably the correct outcome — a loud failure replacing a silent one — but it is a BREAKING change to a published type and needs the categorisation and changeset that go with it. ⇒ manual floor: the disposition (delete / rename onto the real counterpart / route to a door that can honour it) is a contract decision, ⛔ not a dev's to pick mid-PR.

The three plausible shapes, stated so the ruler does not have to re-derive them:

1. Delete all three. Honest, loud, breaking for anyone currently passing them (who is currently getting nothing anyway).
2. Rename name → client_name, scopes → scope, delete metadata. ⚠️ Not type-compatible: scopes is string[], scope is string. A rename here is a signature change, not an alias.
3. Keep and honour — client-side maps name→client_name and scopes→scope.join(' ') before posting, deletes metadata. Preserves compilation for existing callers and makes the declaration true. ⚠️ But it puts translation logic in the SDK for a vendor route, which is a maintenance burden the next @better-auth/oauth-provider bump can break silently.

⛔ Triage is not choosing among these.

Sequencing — same hard serial as #15451

⚠️ packages/client/src/index.ts is the #12104 family's measured hard serial, released on MERGE. This card and #15451 (oauth.applications.delete, graded p1 this round) touch the same file and the same applications block within ~50 lines of each other. ⇒ They should be considered together by the domain:cli seat (#6024): landing them as one PR is likely cheaper than two passes through a serial queue, provided the p1 is not delayed by this card's ruling. If the ruling is not quick, ⛔ ship #15451 alone rather than letting a p2 contract question hold a p1 fix.

Version pin for the re-check: @better-auth/oauth-provider@1.7.2. The vendor is on its own release cadence — this repo already chased better-auth 1.7 column drift in #3624 / #3647 — so re-read the body schema at pickup rather than trusting the member list transcribed on this card.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code

[os-litant]

Measurement round — name and scopes are now DRIVEN

Dispatched by the domain:cli seat (#6024) under the bound in 5547794993. No code changed, no branch, no PR. ⛔ No recommendation among triage's three shapes — that is the maintainer's.

What was measured at

repo head	7beaaa32ccb1295eeaec73bdca4aea36e713232d (origin/main, 2026-09-06 12:06 UTC)
@better-auth/oauth-provider	1.7.2 (installed, read off the resolved package — matches triage's pin)
better-auth	1.7.2 · better-call 1.4.0 · zod 4.4.3
rig	bootStack(@objectstack/example-showcase) → real betterAuth + real oauthProvider over the real ObjectQL engine, real TCP socket (HonoServerPlugin port 0 → getPort()), driven through the real ObjectStackClient with the real globalThis.fetch and a real session
⚠️ deviation from the card's earlier rig	the datasource is sqlite-wasm (bootStack's pure-JS WASM SQLite), not better-sqlite3. Named because the card's metadata drive said better-sqlite3. It does not touch this verdict — every strip happens in the route's Zod body parse, before any driver is reached — but the DB read-backs below are real rows out of a real SQL database either way.

Throwaway worktree, torn down; the shared checkout was never edited.

---

⭐ Per-member verdict

member	driven?	result	what that implies for its disposition
name	✅ yes, this round	stripped on the route register posts to — but the spelling is honoured on a different, ObjectStack-owned door	It is not simply a dead member. POST /api/v1/auth/sys-oauth-application/register (auth-plugin.ts, ledger disposition: 'server-only') reads a body member spelled exactly name and maps it onto client_name — i.e. the repo already implements triage's shape 3, server-side, for this exact member. So "delete" removes a spelling the platform honours elsewhere; "rename onto client_name" is a pure string→string rename (driven ✅).
scopes	✅ yes, this round	stripped, on every door in the surface	No endpoint anywhere in the vendor plugin declares scopes — not create, not DCR register, not oauth2/update-client, not the admin update. And a mechanical rename onto scope is driven-refused (below). This is the member with no counterpart reachable by a rename.
metadata	✅ re-driven (positive control)	stripped at create — the card's finding reproduces exactly. Also stripped by the mounted POST /oauth2/update-client. Honoured only by PATCH /admin/oauth2/update-client, which is SERVER_ONLY and therefore not mounted over HTTP at all.	"Route it to a door that can honour it" has a sharper meaning than it looked: the honouring door is not an HTTP route. better-call's router does if (endpoint.options?.metadata?.SERVER_ONLY) continue (router.mjs:22), and the drive confirms it — 404, zero-byte body. It is reachable only in-process (authApi.adminUpdateOAuthClient), which the drive shows does persist the value. An SDK method cannot reach it without a new ObjectStack mount — the same gap-closing move already made for admin/oauth2/toggle-disabled.

⛔ Not one homogeneous defect. Three different answers.

---

The drives

All through client.oauth.applications.register(...), real socket, real session. Status + full body verbatim.

name alone — 201, and the body carries neither name nor client_name:

{"client_id":"GshJvINrsShauIzjLxjKpcCtxsYjoOxP","client_secret":"aLPpOONfpGeJymAExjukigaMaxNLvpjt","client_secret_expires_at":0,"user_id":"omZi2cU2XEbvXSLAjFY5AUMJww1DrRYj","client_id_issued_at":1788699309,"redirect_uris":["``https://probe-15447.example.com/cb"],"token_endpoint_auth_method":"client_secret_basic","grant_types":["authorization_code"],"response_types":["code"],"application_type":"web","disabled":false,"dpop_bound_access_tokens":false}``

scopes alone — 201, and the body carries neither scopes nor scope:

{"client_id":"ptjtapeKlDWMSfaIQfEShBJHlXvwrZpO","client_secret":"KMTZRWsGRklnrbIhhHdOfCCPghFdJCni","client_secret_expires_at":0,"user_id":"omZi2cU2XEbvXSLAjFY5AUMJww1DrRYj","client_id_issued_at":1788699309,"redirect_uris":["``https://probe-15447.example.com/cb"],"token_endpoint_auth_method":"client_secret_basic","grant_types":["authorization_code"],"response_types":["code"],"application_type":"web","disabled":false,"dpop_bound_access_tokens":false}``

metadata: { tenant: 'acme', tier: 7 } — 201, neither key present. The card's measurement reproduces at this head.

⭐ Read back through every other door — the value survived nowhere

The response body is not the only place a value could land, so all four doors were checked per client:

probe	response body	oauth.applications.get	oauth.applications.list	sys_oauth_application row (ObjectQL, system read)
client_name: 'CTRL-…' (control)	client_name ✅	client_name ✅	✅	name column = "CTRL-CLIENT-NAME-15447"
name: 'PROBE-…'	absent	absent	absent	name column = null
scope: 'openid profile email' (control)	scope ✅	scope ✅	✅	scopes column = ["openid","profile","email"]
scopes: ['openid','profile','email']	absent	absent	absent	scopes column = null
metadata: {…}	absent	absent	absent	metadata column = null

The two control rows are the sharp edge of this card. client_name writes the DB column literally named name; scope (one space-delimited string) writes the DB column literally named scopes, as a JSON array. The SDK's stripped members are spelled in the vendor's record vocabulary while the route speaks its wire vocabulary — and the method's own return type (OAuthApplication, bound in #14312) is purely wire-spelled: it declares client_name and scope?: string, and no name, scopes or metadata. The request and return types of the same method disagree on which vocabulary they speak.

The doors that DO honour a spelling — both driven

• name → POST /api/v1/auth/sys-oauth-application/register (ObjectStack mount): { name: 'WRAPPER-NAME-15447', redirectURLs: '…', type: 'web' } → 200, client_name: "WRAPPER-NAME-15447", DB name column set. Ledger records it server-only — no SDK method builds this URL.
• metadata → PATCH /admin/oauth2/update-client: over HTTP → 404, zero bytes (SERVER_ONLY, unmounted; the repo's own admin-route-nonadmin-refusal.dogfood.test.ts already records it bucket: 'not-mounted'). In-process with a real session → persists: DB metadata = {"tenant":"acme-adminUpdateOAuthClient","tier":7}. Once stored, every read door spreads it as top-level members — a later applications.get returned {"tenant":"acme-…","tier":7,"client_id":…} — which is the card's "the serialiser only ever spreads metadata that some other door stored", confirmed.
• No ObjectStack mount and no vendor endpoint reads scopes at all. The only two ObjectStack oauth mounts are admin/oauth2/toggle-disabled and sys-oauth-application/register; neither touches it.

---

⭐ scopes → scope is NOT type-compatible — refuted by drive, not by reading

Triage flagged this; it is now measured. The mechanical rename, posted to the real route:

POST /api/v1/auth/oauth2/create-client   { client_name: '…', scope: ['openid','profile'], redirect_uris: [...] }
→ 400 {"message":"[body.scope] Invalid input: expected string, received array","code":"VALIDATION_ERROR"}

Through the SDK it surfaces as Error: [body.scope] Invalid input: expected string, received array. The translated form is what passes: scope: ['openid','profile'].join(' ') → 201, "scope":"openid profile". So scopes→scope is a signature change requiring a value transform, not an alias — exactly as triage said. By contrast name→client_name is string→string: driven, 201, no transform.

⚠️ And note the asymmetry the drive exposes: scope is validated — an unregistered value answers 400 {"error":"invalid_scope","error_description":"cannot request scope probe15447:gamma"} — while scopes carrying the same values sails through at 201 and is discarded. The real member refuses bad input; the near-miss accepts anything.

---

⭐ Vendor body schema re-read at the installed version

Read off @better-auth/oauth-provider@1.7.2 as resolved in this checkout, and additionally introspected at runtime (instantiate oauthProvider(), walk endpoints, read options.body) rather than transcribed. The card's member list is accurate — no drift at 1.7.2. POST /oauth2/create-client, 21 members:

member	type
redirect_uris	optional<array<string>> ⚠️ optional here; the SDK declares it required
scope	optional<string>
client_name	optional<string>
client_uri, logo_uri, tos_uri, policy_uri	optional<string>
contacts	optional<array<string>>
software_id, software_version, software_statement	optional<string>
post_logout_redirect_uris	optional<array<string>>
backchannel_logout_uri	optional<string>
backchannel_logout_session_required	optional<boolean>
token_endpoint_auth_method	optional<string>
application_type	optional<enum<["web","native"]>>
jwks	optional<object> · jwks_uri optional<string>
grant_types	optional<array<string>>
response_types	optional<array<enum<["code"]>>>
dpop_bound_access_tokens	optional<boolean>

No catchall is set, so the object is zod's default strip. Parsing a body carrying all three disputed members succeeds (ok: true) and reports droppedKeys: ["name","scopes","metadata"] — the $strip claim, confirmed at the schema level.

Two further schema facts that bear on disposition:

1. A second, independent barrier stands behind the strip. The handler does const { client_credentials_scopes, ...metadata } = ctx.body and funnels the rest of the parsed body into the opaque metadata envelope — so an unknown key that survived parsing would still be dropped by stripReservedOAuthClientMetadataExtensions, because name, scopes and metadata are all in OAUTH_CLIENT_RECORD_FIELD_NAMES ⊂ OPAQUE_METADATA_RESERVED_FIELDS. Loosening the SDK alone could never make these three arrive.
2. metadata appears in exactly one body schema in the whole plugin: PATCH /admin/oauth2/update-client's update object (record<string, unknown>) — the unmounted SERVER_ONLY door. The DCR POST /oauth2/register schema has none of the three either, so the legacy endpoint is not an escape hatch.

---

Evidence ledger — schema reads vs drives, kept apart

Schema reads (evidence about the schema only): the 21-member list and its types; catchall absent ⇒ strip; the reserved-field second barrier; metadata present only on the admin update body; better-call router skipping SERVER_ONLY; sys-oauth-application/register reading a member spelled name.

Drives (evidence about behaviour): every status and body above; all four read-back doors per client; the DB column contents; the 404 on the unmounted admin door; the in-process metadata persist; the 400 on scope: string[]; the 201 on scope: joined; the 200 on the ObjectStack name wrapper.

Nothing in the per-member verdict table rests on a reading alone.

---

Generated by Claude Code

[os-litant]

维护者速读 — the measurement triage asked for is done. Three members, three different answers, and one of triage's three shapes is already implemented.

domain:cli execution PM seat (#6024). State transition, one stroke: pm:dispatched off, pm:awaiting-maintainer on. ⛔ Measurement only — no code changed, no branch, no commit, no PR. ⛔ This seat makes no recommendation among triage's three shapes; the disposition is the manual floor triage placed it behind.

Triage's bound was "First deliverable is driving those two, not choosing a disposition" and "⛔ Do not treat the three as one homogeneous defect because they were filed together." Driven, that warning was exactly right.

The three answers

member	verdict	what it means for its disposition
name	stripped by the vendor route — but honoured by a different path	⭐ POST /api/v1/auth/sys-oauth-application/register, an ObjectStack-owned mount (ledger server-only, no SDK method builds it), reads a body member spelled exactly name and maps it onto client_name. Driven: 200, DB name set. ⇒ the repo already implements triage's shape 3 for this member, server-side.
scopes	stripped, everywhere	No vendor endpoint (create, DCR register, oauth2/update-client, admin update) and no ObjectStack mount declares it. DB column null.
metadata	stripped at create; honoured only by a door that is not an HTTP route	PATCH /admin/oauth2/update-client is the sole body schema carrying metadata, and it is SERVER_ONLY — better-call's router skips it. Over HTTP: 404, zero bytes. In-process: persists. ⇒ "route it to a door that can honour it" would require a new ObjectStack mount.

The type-compatibility question triage raised — refuted by drive, as they suspected

scopes → scope is not a rename. Driven: scope: ['openid','profile'] → 400 [body.scope] Invalid input: expected string, received array; scope: [...].join(' ') → 201. name → client_name is string→string, driven 201.

Vendor drift — none

@better-auth/oauth-provider@1.7.2 (better-auth 1.7.2, better-call 1.4.0, zod 4.4.3). Re-read at that version and introspected at runtime rather than trusting the transcription: the card's 21-member list is accurate. No catchall ⇒ zod default strip; parsing all three disputed members returns ok: true with droppedKeys: ["name","scopes","metadata"].

⭐ Two facts the card did not have, and both bear on the ruling

1. A second, independent barrier stands behind the strip. The handler funnels the parsed body's rest into the opaque metadata envelope, but name, scopes and metadata are all in OPAQUE_METADATA_RESERVED_FIELDS. ⇒ loosening the SDK alone could never make them arrive. Any shape that tries to "keep and honour" has two gates to pass, not one.

2. The request and return types speak different vocabularies, and the collision is inverted. The stripped members are the vendor's record spellings — client_name writes the DB column named name, and scope writes the DB column named scopes — while OAuthApplication, the return type bound in #14312, is purely wire-spelled.

⚠️ That inverts the "near miss" reading this card was filed on. name and scopes are not obvious typos for client_name and scope; they are the column names those wire fields write to. Whoever declared them may have been reaching for the record vocabulary deliberately. ⇒ a ruling that treats them as misspellings should say so knowingly.

Also measured: scope is validated (an unknown value → 400 invalid_scope) while scopes sails through at 201 and is silently discarded — the two adjacent spellings differ not only in type but in whether the server checks them at all.

Rig, and one honest deviation

bootStack(@objectstack/example-showcase) — real betterAuth + real oauthProvider over the real ObjectQL engine, on a real TCP socket, driven through the real ObjectStackClient with real fetch and a real session. ⚠️ Datasource is sqlite-wasm, not better-sqlite3 as in the card's earlier rig — named rather than smoothed over, and immaterial here because every strip happens in the route's Zod body parse, before any driver is touched.

Worktree torn down; /home/user/objectstack verified clean and unmoved.

⛔ Triage's three shapes stand as they wrote them. This comment adds evidence, not a preference — but note that shape 3 is now partly a description of what already exists rather than a proposal, and that shape 2 is refuted for scopes on type grounds.

---

Generated by Claude Code

[huangyiirene]

状态转换：pm:awaiting-maintainer → pm:queue（2026-09-09）

维护者回批逐字：「C 桶那 24 张的批量转 pm:queue 同意」。

判据：⭐ 本卡命中 SKILL.md:720 元判据①：「静默丢弃的声明并入既有拒收集；新支复用母单裁决直接入队，真实语义差异才重开。」client SDK 的 oauth.applications.register 声明了三个 better-auth body schema 静默丢弃的成员（metadata、name、scopes）—— 与 #12034 同族（同族母单已于本日裁定收敛到生产方实际形状）。⇒ ⛔ 本就不该进任何箱。

同笔清 assignee（SKILL.md:104）。bug、domain:cli、finding、priority:p2 留下。

⚠️ 根因见 #17017。

---

Generated by Claude Code