feat/one-api

No backward-compat fallback for missing `scopes` claim — all existing tokens get 401 on prod merge

packages/api/src/auth/public-jwt.ts

verifyBatuJwt returns err({_tag:'PublicJwtClaimsInvalid', statusCode:401}) when payload.scopes is absent. Tokens minted on main (before W2) have no scopes claim. Unlike the actor claim — which defaults to 'machine' for old tokens — scopes has no fallback. On prod deploy every in-flight customer token will be rejected until re-exchanged. Fix: `const scopes = Array.isArray(payload.scopes) ? payload.scopes.filter((s): s is string => typeof s === 'string') : ['*'];` — old tokens had full access, so ['*'] is the correct default. Only reject when !apiKeyId.

`revokeApiKeyShell` drops .catch — DB errors now escape as thrown Promises, violating FCIS contract

domains/core/src/api-key/api-key.shells.ts

The .catch handler was removed along with the cascade, but updateWithVersion and outboxQueries.insert can still throw (network errors, constraint violations, postgres.js boundary rethrows). The original comment in the removed .catch said: 'postgres.js rethrows the recorded error at the boundary, so without this the shell would throw a PostgresError out of a Promise<Result<…>> at a caller with no try.' That hazard is unchanged by simplifying the body. Fix: reinstate .catch((e: unknown) => { log.error('Revoke failed', e); return err(ApiKeyErrors.databaseError('update')); }) on the db.transaction() call.

`actorType !== 'user'` scope-check bypass is fragile against future actor types

apps/platform/src/api/utils/public-v1-meta-gate.ts:106

The gate condition `auth.actorType !== 'user'` means any future actor type added to AuthContext (e.g. 'webhook', 'internal') would bypass the scope check without an explicit decision. Consider a positive allowlist `(auth.actorType === 'machine' || auth.actorType === 'service')` to make the invariant structurally explicit.

Broad shorthand scopes ('read', 'write') grant cross-capability access with no creation-time warning

packages/api/src/auth/public-jwt.ts

A key created with scopes=['read'] satisfies any cap:read requirement (bills:read, files:read, assets:read, etc.) via scopeSatisfied. This is correct per the grammar but creates a surprising credential: a customer who intends a narrowly scoped key for one integration gets a read-key for the entire API surface. Consider surfacing this in the creation response or UI — no code change required now, but note it for the key management UX work.

Stale JSDoc 'v1 only allows the wildcard scope' contradicts the implemented scope grammar

domains/core/src/api-key/api-key.decisions.ts:44

Two consecutive JSDoc blocks precede SCOPE_PATTERN. The first ('v1 only allows the wildcard scope. Future expansion adds entries here.') directly contradicts the regex below it, which already accepts the full grammar (bills:read, monitoring:write, etc.). A developer reading it would wrongly conclude non-wildcard scopes are not yet live. Remove the first JSDoc block — the second one is the accurate description.

`cascadedFrom` removed from ApiKeyRevokedEvent — verify no external EventBridge consumers

domains/core/src/events/api-key.events.ts:60

cascadedFrom?: string was removed from ApiKeyRevokedEvent.eventData and its Zod schema. Grep inside the monorepo shows zero remaining references. Confirm no external Lambda ARNs or analytics pipelines subscribed to core.api_key.revoked rely on this field — they would silently receive undefined without breaking deserialization (field was optional).

`reveal` route removed — confirm no UI hooks still call POST .../reveal

apps/platform/src/api/contracts/api-keys.contract.ts

POST /organizations/:orgId/api-keys/:publicId/reveal removed from the contract. The diff removes RevealApiKeyResponseSchema import. Grep confirms no useApiKeys hooks or page components call it. Clean inside the monorepo — ensure any external Postman collections or docs referencing this endpoint are updated.

No test for `verifyBatuJwt` with a pre-W2 token (no `scopes` claim) — critical finding has no regression guard

packages/api/src/auth/__tests__/public-jwt.test.ts

Finding #1 (scopes backward compat) has no corresponding test. A test signing a minimal JWT without scopes and asserting the verify path (whether it should return err or default to ['*']) would pin the invariant and prevent it silently regressing. Given that the fix is one line, the test is also one test — add both.

No test for `revokeApiKeyShell` DB error path after .catch removal

domains/core/src/api-key/__tests__/api-key.shells.test.ts

After the .catch is reinstated (finding #2), a test that mocks db.transaction to throw and asserts the shell returns err(databaseError('update')) would pin the shell's never-throw contract. Without it, a future refactor can remove the catch again and CI won't catch it.

No test for ApiKeyCreatedEventSchema rejecting a payload without the new required `scopes` field

domains/core/src/events/api-key.events.ts:129

scopes: z.array(z.string()) was added as a required field to ApiKeyCreatedEventSchema. A parse test with scopes omitted would confirm the schema enforces the new field. Minor — type safety mostly covers this via the satisfies constraint, but a runtime Zod parse test at the schema layer is good practice for event contracts.

Empty 'Helpers' section divider is dead scaffolding after isUniqueViolation moved inline

domains/core/src/api-key/api-key.shells.ts:61

The '// Helpers' section comment block is now empty — isUniqueViolation moved to a local function inside the service-key block. Remove the empty section header to reduce noise.

Stale 'argon2id' references in comments and test fixtures — actual algorithm is scrypt

domains/core/src/api-key/api-key.shells.ts:10

Module doc says 'argon2id hash' and test fixtures use '$argon2id$' prefix. The actual hash in api-key.lib.ts is Node's crypto.scrypt (not argon2id). The fixture strings never flow through verifySecret so there's no runtime bug, but security-critical comments should name the right algorithm. Change comments and fixture prefixes to 'scrypt:'.

Handler pre-flight findByPublicId causes a double-read on every mutating operation

apps/platform/src/api/handlers/api-keys.handler.ts

revoke, rotate, and delete handlers each call findByPublicId outside the transaction for org-ownership validation, then the shell calls it again inside the transaction. Two round-trips for the same row. The shell could accept a callerOrgId guard and return ApiKeyOrgMismatch — one read instead of two. Low priority; note for when the shell surface stabilises.