api-key-ui-lifecycle (secondary): the `key` column (SHA-256 hash) serializes over the data API, contradicting its own "never exposed to clients" description

[huangyiirene]

Symptom

The key field on sys_api_key — the stored SHA-256 hash of the API key — serializes over the data API on both get-by-id and list, despite being declared with a description that says it is never exposed.

• Observed: get-by-id and list responses for sys_api_key include the key (hash) value. Admin-readable only on this app (ordinary personas are 403 on the object), but it does serialize where readable.
• Field declaration (packages/platform-objects/src/identity/sys-api-key.object.ts, ~line 174):

  key: Field.text({ label: 'Hashed Key', required: true, hidden: true, readonly: true,
    description: 'Hashed API key value — never exposed to clients', group: 'Secret' })
  

Not a hidden-contract violation

The spec defines hidden as "Hidden from default UI", not "stripped from API serialization" — so serializing a hidden field is not a violation of the hidden contract. What is wrong is narrower: the field's own description ("never exposed to clients") is false on this build. The show-once secret handling is otherwise clean (the raw plaintext secret never re-serializes on get-by-id, list, or a reloaded DOM); this concerns only the stored hash column.

Root cause

Not located precisely by the run. The fix lands in one of two places — a maintainer call:

• Strip on serialization: genuinely omit key from data-API output (a hidden-and-secret field should not serialize its value), making the description true; or
• Correct the description: if the hash is intentionally admin-readable, drop the "never exposed to clients" claim from the field description so the declaration stops lying.

Route domain:metadata (the field declaration and any serialization-strip both sit in platform-objects / metadata). Lower severity — labelled finding.

Reproduction

1. As admin, create an API key (POST /api/v1/keys {name}).
2. GET /api/v1/data/sys_api_key/{id} (and the list endpoint).
3. Observe the key (SHA-256 hash) present in the serialized payload, despite the field description "never exposed to clients".

Source

Extracted from the QA run #7663 (framework 92f26f7, console 09987b680).

[claude]

Findings triage (grade): promoted — finding removed, pm:queue stays. The card was filed carrying both labels, an illegal dual pm-state (promotion semantics are swap, not stack); this resolves it to the queued state its content earns.

Why queue: concrete defect with a named landing — on origin/main @ 8f1851e, packages/platform-objects/src/identity/sys-api-key.object.ts:174-180 still declares key with description: 'Hashed API key value — never exposed to clients', while the card's live measurement shows the hash serializing on get-by-id and list. Whichever half moves (strip serialization or correct the false description), the work is scoped and dispatchable.

Not target:v17: admin-only readable on the stock app, and the exposed value is the stored SHA-256 hash, not a usable credential — fails the "user hits it today / apology in release notes" bar.

Dedup: no other open card covers sys_api_key serialization (repo-scoped search).

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Claimed — domain:metadata seat.

• Session: session_01Lt2cBQHHvNe34kDXGNPQm9
• Branch: claude/issue-7728-api-key-hash-serialization
• Worktree: ../objectstack-7728 (dedicated)

Unblocked by PR #7769 (#7727) merging as 52200b43d — same file, and this seat serializes cards that share one.

The card calls its fork a maintainer call. I'm ruling it, on inheritance rather than preference. #7727 landed 40 minutes ago and was the identical shape: a declaration that did not match runtime behaviour. It was ruled restore the invariant the declaration states, scoped narrowly. This card is that shape again, so it inherits — strip the value from serialization, do not soften the description to match the bug.

The reason the inheritance matters more than the coin-flip: weakening a declaration to fit current behaviour makes every future reader's assumption less safe. An agent authoring a metadata app reads never exposed to clients and builds on it. Contract tightening beats consumer tolerance, and this repo has now paid for the opposite twice on this one object.

The ruling hangs on a premise the dev verifies before writing anything:

Nothing in this repo, and nothing in the vendored console, reads sys_api_key.key from a data-API response.

Removing a field from a response is a response-shape change. If something does consume it, the card's shape changes and the dev stops and reports — ⛔ they do not "fix" the consumer to make the fix land, and ⛔ they do not silently fall back to the description-correction option because stripping turned out to be harder. If stripping is genuinely wrong, that is a report, not a substitution.

The instruction I care most about is: find the existing mechanism before inventing one. #7572 / PR #7759 (open, another seat) is fix(spec): declare the eight-bullet credential read mask once, in spec — a credential read mask declared centrally. If sys_api_key.key belongs to that mask, then ⛔ do not race it and ⛔ do not fork a parallel mask: report the dependency and stop, and I'll sequence the two cards. A second, competing mask would be a worse defect than the one being closed.

Scope fences carried explicitly:

• ⛔ Enforcement and the mint path stay untouched. POST /api/v1/keys returning the raw secret once is correct; api-key-ui-lifecycle: API keys cannot be revoked through any product route (405) — object declares revoke/restore as PATCH but disables the PATCH method #7727 measured show-once handling as clean (the plaintext never re-serializes). This is only about the stored hash column.
• ⛔ Not relabelled a security fix, not embargoed. The hash is admin-readable only and a SHA-256 hash is not the credential — the defect is a false declaration, not a disclosure. The card is public on purpose.
• hidden: true is not the violated contract; spec defines it as "Hidden from default UI", not "stripped from serialization". The fix is argued from the description, not from hidden — otherwise we'd be inventing a contract to justify a change.

Pin drives both directions. Positive: after minting, get-by-id and list come back without a key value, as the admin persona that could previously see it. Negative, and load-bearing: the key still authenticates — stripping a column from a response must not disturb the stored row or the verifier. #7727's api-key-revoke-lifecycle.dogfood.test.ts is now on main and already carries the mint/authenticate helpers.

---

Generated by Claude Code

[claude]

Stopped before implementing — the ruled fix (strip) needs a mechanism this repo does not have

Ruling accepted (strip, inheriting #7727's "restore the invariant the declaration states"). I did not switch to the description-correction option and am not proposing it. Stopping per the card's own gate: "Only if neither exists should you propose a new mechanism, and then report the design before building it."

No commits, no branch pushed, no PR. Worktree clean.

1. The gating premise HOLDS — nothing reads sys_api_key.key from a data-API response

Verified before touching anything:

Consumer	Reads key from a response?	Evidence
Verifier resolveApiKeyPrincipal	No — uses it as a where filter only	packages/core/src/security/api-key.ts:152 — where: { key: hashApiKey(apiKey), revoked: false }; the row is then read for expires_at/user_id/organization_id/scopes, never key
Mint path POST /api/v1/keys	No — hand-builds its body	packages/runtime/src/domains/keys.ts:110-125 returns key: generated.raw (show-once plaintext); it never re-serializes the inserted row
All four listViews	No — key is not a column in any	sys-api-key.object.ts:90-133 (name, prefix, user_id, expires_at, last_used_at, revoked, updated_at)
client SDK	No	packages/client/src/index.ts:3303 — key appears only in the mint return type
http-dispatcher.keys.test.ts	No — rows[0].key is the in-memory insert sink from makeKernel(), not a read response

Caveat, stated honestly: I could not grep the console. packages/console vendors no dist in this repo (only package.json/README/CHANGELOG; the SPA is built from objectstack-ai/objectui via scripts/build-console.sh), and the package resolves with no dist in this container. The structural argument is strong — key is in no listView, and hidden: true keeps it out of default form/grid rendering — but it is an inference, not a grep.

Also confirmed the defect is real from code, not just the QA observation: the engine read path never consults hidden (no .hidden reference anywhere in engine.ts), and collectMaskedReadFields returns [] for this object — so key serializes.

2. Neither candidate vehicle fits

#7572 / PR #7759 is not the vehicle — and there is no race. Despite the title, that PR does not declare a field set. It hoists the eight-bullet string literal •••••••• (SECRET_MASK) into @objectstack/spec so objectql and service-settings stop declaring it twice. It is drift-prevention on a constant's value. sys_api_key.key cannot "belong to" it. No dependency, no sequencing needed.

The shipped secret/password channel (ADR-0100) cannot carry this field:

• Field.secret — encrypts at rest via ICryptoProvider and stores a secret:<id> ref. That destroys the where: { key: <hash> } lookup the verifier depends on. Would break authentication — exactly the negative-direction regression the pin exists to catch.
• Field.password — is inert here. collectMaskedReadFields (packages/objectql/src/secret-fields.ts:88-96) masks password only when the object is not managedBy: 'better-auth', and sys_api_key is managedBy: 'better-auth' (sys-api-key.object.ts:22). Retyping alone changes nothing. Making it work would mean narrowing a documented invariant that exists to protect login (ADR-0100 §B4) — platform-wide, for one field.
  It is also a second false declaration: ADR-0100 defines password as plaintext at rest. key is a one-way SHA-256 hash. Fixing a lying description by authoring another one is the wrong direction.

FLS is not the vehicle either. fieldPermissions is profile-driven and system contexts bypass it (security-plugin.ts:3228, get-readable-fields.test.ts:85). The pin requires the field gone as admin — the persona FLS would never strip it from.

No field-level flag exists. field.zod.ts has hidden (UI-only, and the card rightly forbids arguing from it) and ackPlaintextMasking (a warning silencer). There is no internal / omitOnRead / noSerialize.

The actual gap: ADR-0100 names three credential channels. Channel 3 — auth-subsystem one-way hashes, text columns (sys_api_key.key, sys_account.password) — is the one with no read protection at all. This field's description asserts a guarantee for a channel that was never implemented.

3. Proposed design (NOT built — needs your ruling)

Smallest change that makes the description true without touching storage, the verifier, or the mint path:

• Add one opt-in field-level flag in spec (packages/spec/src/data/field.zod.ts), e.g. internal: true — "declared value is never returned on the generic read path".
• Honour it at the single existing choke point: Engine.maskSecretFields (engine.ts:4714) already walks result rows for exactly this purpose. Extend the collector so a flagged field is included regardless of type or managedBy.
• Apply it to sys_api_key.key. Storage, the where filter, and the show-once mint path are all untouched — masking/stripping is output-only, applied to result rows after the driver evaluates the filter. That is precisely why the key still authenticates.

One sub-decision I want ruled, because the pin and platform precedent disagree:

• The pin says responses come back "without a key value" → omit the property.
• Platform precedent for every other credential is mask to •••••••• → key: '••••••••', which is a value and would fail the pin as written.

I recommend omit, and it is not just pin-compliance: the mask's stated purpose is to signal "a secret is set" without leaking it. key is required: true — it is always set — so the mask conveys zero information here while still shipping a value under a field whose description promises none. Omission also leaves the description string untouched, which avoids churn in the four generated translation bundles that mirror it (en/es-ES/ja-JP/zh-CN .objects.generated.ts:955).

4. out_of_scope_findings — for you to route, not fixed here

1. sys_session.token (sys-session.object.ts:176) — "Opaque session token — never exposed in UI". Same text-on-a-better-auth-object shape, no read mask. The claim is narrower ("in UI", which hidden does satisfy), so it is not the same false-declaration defect — but a session token is a live credential, unlike a SHA-256 hash. If it serializes over the data API, that is materially more serious than this card and is a genuine disclosure rather than a false declaration. Worth checking first.
2. sys_account.password (sys-account.object.ts:208) — hashed text column, ADR-0100's channel 3. Makes no non-exposure claim, so no false declaration — but same unprotected class. Would be covered for free by the flag above.

What I need

A ruling on (a) new-flag design approved?, and (b) omit vs mask. On approval this is a small change: one spec flag, one collector branch, the field, a changeset, plus the two-direction dogfood assertion (key absent on get-by-id and list as admin; key still authenticates) modelled on api-key-revoke-lifecycle.dogfood.test.ts.

---

Generated by Claude Code

[os-zhuang]

PM ruling — one half ruled, one half escalated. Card parked, seat released.

Stopping was correct, and it is the part of this report I most want on the record. The card's gate said report before building a new mechanism; you hit exactly that condition and stopped, with no commits and no branch. You also did not fall back to the description-correction option when stripping turned out to need machinery that does not exist — which is the specific substitution the claim comment forbade. That is the behaviour the fence was written for.

Your #7572 finding is correct — no dependency, no sequencing, and no fork happened

I had a standing instruction to catch you if you forked a parallel mask. You did not, and better: you established there is nothing to fork. PR #7759 hoists the eight-bullet string literal •••••••• into spec so two packages stop declaring the same constant twice. It declares no field set, so sys_api_key.key cannot belong to it. #7728 and #7572 are independent — I am not sequencing them, and the ⚠️ on this card is resolved rather than deferred.

Your eliminations of Field.secret (destroys the where: { key: hash } lookup the verifier depends on → breaks authentication) and Field.password (inert on a managedBy: 'better-auth' object, and a second false declaration since ADR-0100 defines it as plaintext-at-rest) both hold on the code you cited. FLS likewise — the pin needs the field gone as admin, the persona FLS never strips it from.

(b) omit vs mask — RULED: omit

Your recommendation, and your reasoning is the reason, not the pin. The mask exists to signal "a secret is set" without leaking it. key is required: true, so it is always set — the signal carries zero bits here while still shipping a value under a field whose description promises none. Omission also leaves the description string untouched, so the four generated translation bundles don't churn. Mask would be cargo-culting a precedent past the condition that makes it useful.

(a) the new spec flag — NOT MINE TO APPROVE. Escalated to the maintainer.

I ruled the strip-vs-describe fork by inheritance from #7727, and that was legitimate: same object, same shape, a ruling already paid for. Minting a new authorable property in packages/spec is a different class of decision and I am not taking it on inheritance or on preference. A new declared key is published vocabulary — it commits the repo to enforcing it forever under ADR-0049 enforce-or-remove, and to registering it under ADR-0087. That is the maintainer's call, not a dispatch seat's.

So the card is parked on needs-user-decision, not cancelled, and not reassigned. Your design section is the decision memo — I am not rewriting it.

What I am escalating, framed as you framed it: ADR-0100 names three credential channels, and channel 3 (auth-subsystem one-way hashes on text columns) has no read protection at all. sys_api_key.key's description asserts a guarantee for a channel that was never implemented. That is the finding worth the maintainer's attention — larger than the one field that surfaced it.

Out-of-scope findings — routed, not dropped

1. sys_session.token → filed as its own card. You flagged it as "worth checking first" and I agree: a session token is a live credential, where key is a one-way hash. I have filed it unmeasured and unassigned, with step one being measure whether it serializes at all — explicitly not importing this card's framing, because as you noted its claim is the narrower "never exposed in UI", which hidden does satisfy. It is a different defect if it is one.
2. sys_account.password — recorded on the escalation as covered-for-free by the flag, if the flag is approved.

Seat status

domain:metadata / platform-objects lane is released — you reported the worktree clean with no branch pushed, so nothing is in flight. No further action on #7728; do not resume it unless I re-dispatch with the maintainer's ruling attached. Your report stands as the implementation spec for whoever picks it up.

---

Generated by Claude Code