|
| 1 | +--- |
| 2 | +"@objectstack/spec": minor |
| 3 | +--- |
| 4 | + |
| 5 | +feat(spec): retire `ApiKeySchema` — the identity module no longer publishes a second, fictional declaration of `sys_api_key` (#8715, ADR-0049) |
| 6 | + |
| 7 | +<!-- adr-0087: registered identity-api-key-schema-retired --> |
| 8 | + |
| 9 | +**BREAKING** public-surface removal, landing after the v17.0.0 cut (the |
| 10 | +lockstep launch-window convention ships it as `minor`; the migration |
| 11 | +prescription is registered under protocol major 18, where `os migrate meta` |
| 12 | +users will look — the #8586 precedent). |
| 13 | + |
| 14 | +`ApiKeySchema` (and its `ApiKey` / `ApiKeyParsed` types) documented |
| 15 | +better-auth's `apiKey` **plugin** schema — a plugin this platform does not |
| 16 | +load: `start` and `lastRefetchAt` name columns that do not exist; `enabled` |
| 17 | +inverts the real `revoked` column's polarity; `rateLimitEnabled` / |
| 18 | +`rateLimitTimeWindow` / `rateLimitMax` / `remaining` advertise a per-key |
| 19 | +rate-limit capability nothing implements; `permissions` and `metadata` have no |
| 20 | +columns; `organizationId` is camelCase fiction next to the real snake_case |
| 21 | +`active_organization_id`. Zero consumers anywhere in the monorepo outside its |
| 22 | +own unit test — one table had two declarations, and the published one was |
| 23 | +fiction (maintainer-ruled DELETE, 2026-08-15). |
| 24 | + |
| 25 | +**What breaks:** `import { ApiKeySchema, ApiKey, ApiKeyParsed }` from |
| 26 | +`@objectstack/spec` or `@objectstack/spec/identity` is TS2305 after upgrade. |
| 27 | +The generated reference page's `ApiKey` section and the 19 |
| 28 | +`identity/ApiKey:*` authorable-surface keys disappear with the schema. |
| 29 | + |
| 30 | +**What stays:** everything real. The single declaration of `sys_api_key` is |
| 31 | +the ObjectSchema in `@objectstack/platform-objects` |
| 32 | +(`identity/sys-api-key.object.ts`) — columns `name, prefix, user_id, |
| 33 | +active_organization_id, scopes, expires_at, last_used_at, revoked, key, id, |
| 34 | +created_at, updated_at`; rows are minted by `POST /api/v1/keys` and verified |
| 35 | +by `core/src/security/api-key.ts`, keyed by the `osk_` prefix. Neither ever |
| 36 | +read the deleted schema, so runtime behaviour is byte-identical. |
| 37 | +`UserSchema` / `AccountSchema` / `VerificationTokenSchema` and the |
| 38 | +organization module survive unchanged. |
| 39 | + |
| 40 | +The retirement kit: |
| 41 | + |
| 42 | +- schema deleted in place, with the in-module explanatory block naming the |
| 43 | + live declaration (`packages/spec/src/identity/identity.zod.ts`) |
| 44 | +- ADR-0087 registration: retired-def entry `identity/ApiKey` + D3 semantic |
| 45 | + entry `identity-api-key-schema-retired`, both under protocol 18 (route 3 — |
| 46 | + no carrier key and no authored document, so no tombstone and no D2 |
| 47 | + conversion; the registry entries ARE the declaration) |
| 48 | +- pin tests: `identity/api-key-retirement.test.ts` (zero holders on every |
| 49 | + public entry, survivors stand) and platform-objects' |
| 50 | + `sys-api-key-single-declaration.test.ts` (the real column set, spec's |
| 51 | + runtime namespace lost the name) |
| 52 | +- generated baselines regenerated: authorable surface (−19 keys), JSON-schema |
| 53 | + manifest (−1 def), api-surface / export-origins (−3 names), reference docs |
| 54 | +- `cloud/developer-portal.zod.ts` prose corrected: marketplace API keys point |
| 55 | + at the `sys_api_key` object and `POST /api/v1/keys`, not at |
| 56 | + `Identity.ApiKeySchema` (the marketplace-key plan is ruled not live) |
| 57 | + |
| 58 | +## FROM → TO |
| 59 | + |
| 60 | +```ts |
| 61 | +// before — type-checked green against a schema no runtime ever read |
| 62 | +import { ApiKeySchema, type ApiKey } from '@objectstack/spec/identity'; |
| 63 | +const key: ApiKey = { id, name, userId, enabled: true, rateLimitMax: 100, /* … */ }; |
| 64 | + |
| 65 | +// after — read the real table: the sys_api_key ObjectSchema in |
| 66 | +// @objectstack/platform-objects (snake_case, `revoked` not `enabled`); |
| 67 | +// mint via POST /api/v1/keys, verify via core/src/security/api-key.ts. |
| 68 | +import { SysApiKey } from '@objectstack/platform-objects'; |
| 69 | +``` |
0 commit comments