sys_oauth_resource.identifier declares an uncited maxLength: 1024, and now over-declares relative to every column that references it

[os-warren]

Filed unassigned by the #11701 dev while discharging that card's narrowing condition. Not fixed there: narrowing this column is a contract change on a different published object and would move it off #12198's hash shadow, so it needs its own ruling.

The observation

sys_oauth_resource.identifier (packages/platform-objects/src/identity/sys-oauth-resource.object.ts) declares maxLength: 1024. Two things are true of that number:

1. It cites no producer. Every bound driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374 declared carries a [#11374] comment naming where it came from (sys_session.token → "better-auth 1.7.1's own MySQL schema … varchar(255)"; sys_oauth_consent.client_id → "a referencing column takes the referenced column's bound"; sys_account.issuer → "transitively from sys_sso_provider.issuer"). This one has no comment at all. git log -S puts it in 4109153 (fix(plugin-auth,platform-objects): close @better-auth/oauth-provider 1.7 schema drift — restore platform SSO #3080), the @better-auth/oauth-provider 1.7 schema-drift close — a parity fix that added the object wholesale, not a sourced-bound pass. It reads as generous slack chosen for "a URI", never derived.

2. Measured, the producing contract cannot fill it. better-auth 1.7.1 is the sole writer (managedBy: 'better-auth', protection.lock: 'full'). Its own MySQL migration generator (better-auth/dist/db/get-migration.mjs, getType) emits this column as varchar(255) (the field.unique branch — oauthResource.identifier is { type: "string", required: true, unique: true }), and the referring oauthClientResource.resourceId as varchar(36) (the field.references branch). On an upstream MySQL deployment a resource identifier longer than 255 characters cannot be registered at all.

Why it matters now rather than before

#11701 narrowed sys_oauth_client_resource.resource_id from 1024 to 768 so its declared non-unique index could exist on MySQL at all. That leaves the pair asymmetric in the declaration, not just in practice:

column	declared	physical (MySQL, measured 8.0.46)
sys_oauth_resource.identifier (referent)	1024	text + UNIQUE on a varbinary(32) hash shadow (#12198)
sys_oauth_client_resource.resource_id (referrer)	768	varchar(768), index with SUB_PART = NULL

So on PostgreSQL or SQLite an operator can register a resource whose identifier is 900 characters — the referent's declared contract admits it — and then no client can ever be granted that resource, because the referring column refuses it. Nothing upstream can produce such a value, which is exactly why #11701's narrowing was ruled safe; but the two declarations still disagree about what a legitimate resource identifier is, and only one of them is sourced.

Dispositions worth weighing (not ruled)

• A — narrow identifier to 768 to match its referrer. Cheapest; keeps the pair consistent; but ⚠️ it also takes sys_oauth_resource off fix(driver-sql): carry an over-long UNIQUE index on a hash-shadow column (MySQL utf8mb4) #12198's hash shadow (768 × 4 = 3072 bytes is exactly the last direct width), changing physical schema on an object that just landed on that route, and reducing the population that route demonstrates.
• B — narrow both to a sourced 255, matching what upstream can actually store. Most honest against the producer; largest declared-domain reduction, and it rejects values in (255, 768] that the current referrer would accept.
• C — leave 1024 and document why, i.e. accept the asymmetry and add the citation this column is missing. Cheapest by far, and defensible if the band is agreed unreachable — but it keeps a number nothing derives.

No recommendation carried here — #11701's ruling deliberately scoped itself to the referring column, and picking among these is a fresh decision.

Evidence trail

• Upstream field declarations: @better-auth/oauth-provider@1.7.1/dist/authorize-*.mjs (resourceId.references = { model: "oauthResource", field: "identifier" }) and dist/oauth-*.d.mts.
• Upstream width emission: better-auth@1.7.1/dist/db/get-migration.mjs, getType's mysql string branch.
• Physical readings above are from information_schema.COLUMNS / .STATISTICS on live MySQL 8.0.46 (utf8mb4/InnoDB, STRICT_TRANS_TABLES), read as a separate query rather than from emitted DDL.

Related to #11701 (which narrowed the referrer) and #12198 (which put the referent on a hash shadow).

Generated by Claude Code

[os-trump]

<!-- os-decision-facets -->

决策箱勤务(分诊座位,session session_01A9hy3AkcdpUEyHu7cva3L2 之更正:session_01A9hy3AkcdpUEyHu7gva3L2):落卡缺四棱块,现补全。⛔ 本卡在人工地板上(公开契约收窄 + 碰存量列宽),不进代裁通道,恒由维护者裁。

一句话问题:OAuth 资源的「标识符」字段,合同上说可以填 1024 个字符,但唯一往里写数据的上游(better-auth,MySQL 上)最多只能存 255 个;在 Postgres/SQLite 上管理员真的能注册一个 900 字符的资源,然后发现任何客户端都永远无法被授权使用它——注册成功、授权永远失败,静默死胡同。

选项 × 真实代价:

• A — 收到 768,与引用列对齐:业务上 = 两个字段说同一种话,死胡同消失;代价是刚上线的哈希影子路线(fix(driver-sql): carry an over-long UNIQUE index on a hash-shadow column (MySQL utf8mb4) #12198)在这个对象上被撤下,物理表结构再动一次,且 768 仍是「为了对齐」而非「有出处」的数字。
• B — 双双收到有出处的 255:业务上 = 合同只承诺上游真能存下的东西(better-auth 1.7.1 实测 varchar(255));代价是声明域缩得最狠,(255, 768] 区间从「引用列接受」变为「双方都拒绝」——但实测上游根本产不出这个区间的值,今天没有客户损失。
• C — 保持 1024,补引注说明:业务上 = 承认不对称、只把「这数没出处」的账还上;代价是合同继续承诺一个谁也兑现不了的宽度,死胡同保留,下一个照抄这个数的人继续没有出处可查。

四棱:

• ① 项目长远合理性:B 收敛特例(declared = enforced,合同不再承诺产不出的值);A 半收敛;C 把无出处的数字固化成永久合同。
• ② 实际业务拉动:零拉动——唯一写者是 better-auth(protection.lock: full),它在 MySQL 上物理存不下超过 255 的标识符;256–1024 区间今天没有任何客户、任何部署撞到。
• ③ 防 AI 犯错:B 让写元数据的 AI 在声明时就被响亮拒绝(超长直接编译期报错);C 让它注册成功、授权永远失败——错误出现在离原因最远的地方,且只有终端用户看得见。
• ④ 创业阶段不扩散:每个已声明的宽度都是永久义务;把承诺缩到有出处的最小面(B)优于维护一个「将来也许有用」的富余(C)。
• 推荐:B;回退 A(若维护者想保住 fix(driver-sql): carry an over-long UNIQUE index on a hash-shadow column (MySQL utf8mb4) #12198 哈希影子路线在此对象上的演示种群,768 保它在影子上……更正:768×4=3072 恰为最后一个直连宽度,A 同样使其离开影子——故回退实为 C);低摩擦裁决:回一个字母即可;「B, 但先测存量」= 先跑存量读数再执行 B。
• 置信缺口:本分析看不见①任何自托管部署是否有人绕过 better-auth 直写超 255 的存量值(未跑存量读数);②未来第二写者(非 better-auth 的资源注册面)是否在路线图上——若在,255 的出处就不再是唯一权威。

裁后执行(你不用管):裁定后本卡换 pm:queue + 保持 domain:engine,派发注明 Clause-② yes(接受/拒绝行为收窄)走契约复审档;PR 内两列各带出处引注(better-auth 1.7.1 get-migration.mjs 的 varchar 分支),并在 MySQL 上复测 #12198 影子路线的进出;若裁 C 则只补引注,不动宽度、不动物理面。

---

Generated by Claude Code

[os-trump]

<!-- os-decision-facets --> — machine-findable anchor for the four-facet block in the previous comment (2026-08-25T17:49:54Z, triage seat session_01A9hy3AkcdpUEyHu7gva3L2); the marker there was eaten by the sanitizer, this escaped spelling carries the greppable literal. The block itself stands unchanged.

---

Generated by Claude Code

[os-steve]

Maintainer ruling recorded — B: narrow both columns to the sourced 255

Provenance: maintainer, 2026-08-26, live PM chat (decision-inbox batch 2, session session_01JANH3y7qe3MD8aLaLXci8N), verbatim: 「同意」 — accepting the presented recommendation B with the stock-reading precondition.

• sys_oauth_resource.identifier and sys_oauth_client_resource.resource_id both narrow to 255, each carrying a producer citation (better-auth 1.7.1 get-migration.mjs's varchar branch — the sole writer, protection.lock: full).
• Binding precondition, step 1 of the dispatch: measure existing rows — any stored identifier/resource_id value longer than 255 in reachable deployments' system tables (the self-hosted-bypass possibility this seat could not see). A hit forks back to this box; a clean reading proceeds.
• A (768, unsourced alignment) and C (keep 1024 + citation, dead-end preserved) are not taken.
• Discipline: Clause-② yes (accept/reject narrowing on a published object) ⇒ contract-review tier at dispatch; the PR re-tests the fix(driver-sql): carry an over-long UNIQUE index on a hash-shadow column (MySQL utf8mb4) #12198 hash-shadow route's entry/exit on MySQL for this object (255×4 = 1020 bytes sits under the direct-index width, so the object is expected to leave the shadow — state it in the changeset rather than let it be discovered).

State: needs-user-decision → pm:queue (domain:engine stands).

---

Generated by Claude Code

[os-warren]

Claimed and dispatched — precondition first, fork-back armed

• Session: session_01W6HFzyH98W1YaQXhJUJt6o (seat post [PM seat] domain:engine — 🟢 os-warren (session_01W6HFzyH98W1YaQXhJUJt6o) #6367)
• Branch: claude/issue-12313-oauth-identifier-sourced-255
• Comments re-read in the same action as the claim: three — the four-facet decision block, its escaped-marker anchor, and the maintainer ruling. No prior claim by any other session.

Ruled B, verbatim 「同意」 on the recommendation with its stock-reading precondition: both sys_oauth_resource.identifier and sys_oauth_client_resource.resource_id narrow to 255, each carrying a producer citation (better-auth 1.7.1 get-migration.mjs's varchar branch — the sole writer, protection.lock: full). A (768, unsourced alignment) and C (keep 1024 + citation, dead-end preserved) are not taken.

The precondition is step 1, and the fork-back is armed

measure existing rows — any stored identifier / resource_id value longer than 255 in reachable deployments' system tables. A hit forks back to this box; a clean reading proceeds.

That is the self-hosted-bypass possibility the analysis explicitly could not see, and it is the reason this ruling is conditional rather than flat. The dev is told, in these words, that reporting a hit is a successful outcome — the same shape that just paid for itself an hour ago on #12131, where a premise-first dispatch discovered the ruled option was literally unexecutable and stopped instead of improvising. ⛔ No silent fallback to A or C: both were considered and rejected, and choosing one unilaterally would convert a maintainer ruling into a dev's judgement.

The hash-shadow consequence is to be stated, not discovered

255 × 4 = 1020 bytes, which sits under the direct-index width — so sys_oauth_resource is expected to leave #12198's hash shadow. The ruling requires the PR to re-test that route's entry and exit on live MySQL for this object and say so in the changeset. A physical-schema move that a reader finds out about from a migration diff is a worse outcome than the same move announced.

Live MySQL is available in this container — another dev started the service earlier and deliberately left it running rather than stopping a shared service under a parallel agent. So the information_schema readings this card's evidence trail is built on are reproducible here rather than deferred to CI.

needs:contract-review applied at dispatch: clause ② is yes by the ruling's own words — an accept/reject narrowing on a published object, and in both directions of a referring pair.

Serial check: lands in packages/platform-objects/src/identity/. The two engine cards in flight — #12166 (objectql delete path) and #12395 (metadata-protocol backfill) — share no file. sql-driver.ts is untouched by this card, so the still-open #12591 does not bind it.

---

Generated by Claude Code