tapimo 0.0.2 → 0.1.0

package/src/ApiKeys.test.ts

@@ -0,0 +1,175 @@
+import * as ApiKeys from './ApiKeys.js'
+import * as Store from './internal/Store.js'
+
+describe('resolve', () => {
+  test('resolves an unknown token to null', async () => {
+    expect(await ApiKeys.resolve(Store.memory(), 'tempo:sk:missing')).toBeNull()
+  })
+
+  test('resolves before expiry, rejects after', async () => {
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') })
+    try {
+      const state = Store.memory()
+      const { token } = await ApiKeys.mint(state, {
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        orgId: 'org_a',
+        scopes: ['data:read'],
+      })
+
+      expect((await ApiKeys.resolve(state, token))?.orgId).toBe('org_a')
+
+      // Advance the clock past the expiry.
+      vi.setSystemTime(new Date('2026-01-01T00:02:00.000Z'))
+      expect(await ApiKeys.resolve(state, token)).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('treats a corrupt record as absent', async () => {
+    const state = Store.memory()
+    const { token } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+    // Overwrite the stored record (keyed by token hash) with invalid JSON.
+    const { keys } = await state.list({ prefix: 'apikey:' })
+    await state.put(keys[0]!.name, 'not json')
+    expect(await ApiKeys.resolve(state, token)).toBeNull()
+  })
+
+  test('rejects a record with an unknown scope', async () => {
+    const state = Store.memory()
+    const { token } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+    const { keys } = await state.list({ prefix: 'apikey:' })
+    await state.put(
+      keys[0]!.name,
+      JSON.stringify({
+        createdAt: '2026-01-01T00:00:00.000Z',
+        id: 'key_x',
+        orgId: 'org_a',
+        scopes: ['data:read', 'totally:made-up'],
+        tokenLast4: 'xxxx',
+      }),
+    )
+    expect(await ApiKeys.resolve(state, token)).toBeNull()
+  })
+})
+
+// Mock the system clock so timestamps are deterministic without injecting a
+// clock into the module.
+describe('mint', () => {
+  beforeEach(() => vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') }))
+  afterEach(() => vi.useRealTimers())
+
+  test('mints a key and resolves it', async () => {
+    const state = Store.memory()
+
+    const { record, token } = await ApiKeys.mint(state, {
+      createdBy: 'admin@tempo.xyz',
+      name: 'CI key',
+      orgId: 'org_acme',
+      scopes: ['data:read', 'webhooks:write'],
+    })
+
+    expect(token).toMatch(/^tempo:sk:[a-f0-9]{48}$/)
+    expect(record.tokenLast4).toBe(token.slice(-4))
+    expect({ ...record, id: '<id>', tokenLast4: '<last4>' }).toMatchInlineSnapshot(`
+      {
+        "createdAt": "2026-01-01T00:00:00.000Z",
+        "createdBy": "admin@tempo.xyz",
+        "environment": "production",
+        "id": "<id>",
+        "name": "CI key",
+        "orgId": "org_acme",
+        "scopes": [
+          "data:read",
+          "webhooks:write",
+        ],
+        "tokenLast4": "<last4>",
+      }
+    `)
+
+    const resolved = await ApiKeys.resolve(state, token)
+    expect(resolved?.orgId).toBe('org_acme')
+    expect(resolved?.scopes).toEqual(['data:read', 'webhooks:write'])
+  })
+
+  test('rejects an unknown scope at the write boundary', async () => {
+    await expect(
+      ApiKeys.mint(Store.memory(), { orgId: 'org_a', scopes: ['totally:made-up' as never] }),
+    ).rejects.toThrowError(/invalid API key input/)
+  })
+})
+
+describe('list', () => {
+  beforeEach(() => vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') }))
+  afterEach(() => vi.useRealTimers())
+
+  test('lists keys newest first, filtered by org', async () => {
+    const state = Store.memory()
+
+    // Advance the clock between mints so their createdAt timestamps differ and
+    // "newest first" is well-defined.
+    await ApiKeys.mint(state, { name: 'a', orgId: 'org_a', scopes: ['data:read'] })
+    vi.setSystemTime(new Date('2026-01-01T00:00:01.000Z'))
+    await ApiKeys.mint(state, { name: 'b', orgId: 'org_b', scopes: ['data:read'] })
+
+    const all = await ApiKeys.list(state)
+    expect(all.map((record) => record.name)).toMatchInlineSnapshot(`
+      [
+        "b",
+        "a",
+      ]
+    `)
+
+    const scoped = await ApiKeys.list(state, { orgId: 'org_b' })
+    expect(scoped.map((record) => record.orgId)).toMatchInlineSnapshot(`
+      [
+        "org_b",
+      ]
+    `)
+  })
+
+  test('excludes a key past its expiry', async () => {
+    const state = Store.memory()
+
+    await ApiKeys.mint(state, {
+      expiresAt: '2026-01-01T00:00:30.000Z',
+      name: 'short-lived',
+      orgId: 'org_a',
+      scopes: ['data:read'],
+    })
+
+    expect((await ApiKeys.list(state)).map((record) => record.name)).toMatchInlineSnapshot(`
+      [
+        "short-lived",
+      ]
+    `)
+
+    // Advance the clock past the expiry.
+    vi.setSystemTime(new Date('2026-01-01T00:01:00.000Z'))
+    expect(await ApiKeys.list(state)).toMatchInlineSnapshot(`[]`)
+  })
+})
+
+describe('revoke', () => {
+  test('revokes a key by id', async () => {
+    const state = Store.memory()
+
+    const { record, token } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+
+    expect(await ApiKeys.revoke(state, record.id)).toBe(true)
+    expect(await ApiKeys.resolve(state, token)).toBeNull()
+    expect(await ApiKeys.revoke(state, record.id)).toBe(false)
+  })
+
+  test('revoke is O(1): deletes the record without scanning the prefix', async () => {
+    const state = Store.memory()
+
+    const { record } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+
+    // The id index entry maps id -> record key; revoke uses it directly.
+    expect(await ApiKeys.revoke(state, record.id)).toBe(true)
+    // Both the record and its id index entry are gone.
+    const { keys } = await state.list({ prefix: 'apikey' })
+    expect(keys).toMatchInlineSnapshot(`[]`)
+  })
+})

package/src/ApiKeys.ts

@@ -0,0 +1,205 @@
+/**
+ * API-key persistence over the app's KV state store (`App.create({ kv })`).
+ *
+ * Records are keyed by token hash (`ApiKey.keyFor`) — the plaintext token is
+ * never stored — and validated against the scope catalog on read; unknown,
+ * corrupt, expired, or invalid records resolve to `null`. An `id → recordKey`
+ * index makes revoke-by-id O(1). The persisted {@link Record}/{@link
+ * MintInput} shapes live here (derived from `ApiKey.schema` so they cannot
+ * drift from the resolved shape), while the shared credential primitives
+ * (token format/generation, storage-key derivation, redaction) live in
+ * `./ApiKey.js`.
+ */
+
+import * as z from 'zod/mini'
+
+import * as ApiKey from './ApiKey.js'
+import type * as Store from './internal/Store.js'
+
+/** Zod schemas owned by the API-keys module. */
+export namespace schema {
+  /**
+   * Fields accepted when minting a key, and the single source of truth for the
+   * {@link MintInput} type and `mint` validation. Derived from the resolved
+   * `ApiKey.schema` (minus the generated `id`) so the scope vocabulary stays in
+   * lockstep with the resolved shape.
+   */
+  export const MintInput = z.extend(z.omit(ApiKey.schema.ApiKey, { id: true }), {
+    createdBy: z
+      .optional(z.string())
+      .check(z.describe('Identity creating the key (e.g. admin email), recorded for audit.')),
+    expiresAt: z
+      .optional(z.string())
+      .check(z.describe('ISO 8601 expiry timestamp. Omit for a non-expiring key.')),
+    // TODO: make required once orgs exist.
+    orgId: z.optional(z.string()).check(z.describe('Owning organization id.')),
+  })
+
+  /**
+   * A persisted API-key record: the resolved `ApiKey.schema` plus
+   * persistence/display fields. Extending the resolved schema keeps the resolved
+   * and persisted shapes in lockstep.
+   */
+  export const Record = z.extend(ApiKey.schema.ApiKey, {
+    createdAt: z.string().check(z.describe('ISO 8601 creation timestamp.')),
+    createdBy: z.optional(z.string()).check(z.describe('Identity that created the key.')),
+    expiresAt: z.optional(z.string()).check(z.describe('ISO 8601 expiry timestamp.')),
+    tokenLast4: z.string().check(z.describe('Last 4 chars of the plaintext token.')),
+  })
+}
+
+/**
+ * A durable API-key record as persisted. A superset of the resolved
+ * `ApiKey.ApiKey` with provisioning/display metadata. The plaintext token is
+ * never stored — records are keyed by its hash (`ApiKey.keyFor`) and carry only
+ * `tokenLast4` for display.
+ */
+export type Record = z.output<typeof schema.Record>
+
+/**
+ * Fields accepted when minting a key via {@link mint}. Uses the schema's
+ * *input* type so defaulted fields (e.g. `environment`) are optional for
+ * callers — the default is applied during `mint`'s validation.
+ */
+export type MintInput = z.input<typeof schema.MintInput>
+
+/** Result of {@link mint}: the persisted record and its one-time token. */
+export type MintResult = {
+  /** The persisted key record (metadata only — never the token). */
+  record: Record
+  /** The plaintext token, shown once and unrecoverable afterward. */
+  token: string
+}
+
+/**
+ * Mints a key: validates the input (e.g. rejects an unknown scope at the write
+ * boundary), persists its hashed record, and returns the record plus the
+ * one-time plaintext token (shown once, unrecoverable afterward).
+ *
+ * @param state - The KV state store holding key records.
+ * @param input - The key to mint.
+ * @returns The persisted record and its one-time token.
+ */
+export async function mint(state: Store.State, input: MintInput): Promise<MintResult> {
+  const valid = schema.MintInput.safeParse(input)
+  if (!valid.success) throw new Error(`invalid API key input: ${z.prettifyError(valid.error)}`)
+  const data = valid.data
+
+  const time = new Date()
+  const token = ApiKey.generateToken(data.environment)
+  const recordKey = ApiKey.keyFor(token)
+  const id = ApiKey.generateId()
+  const record: Record = {
+    createdAt: time.toISOString(),
+    environment: data.environment,
+    id,
+    // TODO: drop fallback once a real org concept exists.
+    orgId: data.orgId ?? id,
+    scopes: data.scopes,
+    tokenLast4: token.slice(-4),
+    ...(data.createdBy === undefined ? {} : { createdBy: data.createdBy }),
+    ...(data.expiresAt === undefined ? {} : { expiresAt: data.expiresAt }),
+    ...(data.name === undefined ? {} : { name: data.name }),
+    ...(data.rateLimits === undefined ? {} : { rateLimits: data.rateLimits }),
+  }
+
+  // Bound the stored record by its expiry so the backend evicts it natively.
+  const ttl =
+    data.expiresAt === undefined
+      ? undefined
+      : Math.max(1, Date.parse(data.expiresAt) - time.getTime())
+  await state.put(recordKey, JSON.stringify(record), { ttl })
+  // Index `id → recordKey` so revoke-by-id is O(1) (records are keyed by
+  // token hash, unrecoverable from the id alone). Shares the record's TTL so
+  // both entries expire together.
+  await state.put(idKeyFor(record.id), recordKey, { ttl })
+  return { record, token }
+}
+
+/**
+ * Resolves a plaintext API key token to its metadata, or `null`. Expiry is
+ * enforced on read — not just via the store's native TTL — so it holds on
+ * backends that evict lazily and regardless of TTL granularity.
+ *
+ * @param state - The KV state store holding key records.
+ * @param token - The presented plaintext token.
+ * @returns The resolved key metadata, or `null`.
+ */
+export async function resolve(state: Store.State, token: string): Promise<ApiKey.ApiKey | null> {
+  return read(state, ApiKey.keyFor(token), Date.now())
+}
+
+/**
+ * Lists key records (metadata only — never tokens), newest first. Expired or
+ * catalog-invalid records are skipped.
+ *
+ * @param state - The KV state store holding key records.
+ * @param options - Optional owner filter.
+ * @returns The records.
+ */
+export async function list(
+  state: Store.State,
+  options: list.Options = {},
+): Promise<readonly Record[]> {
+  const { keys } = await state.list({ prefix: ApiKey.recordPrefix })
+  const records: Record[] = []
+  for (const { name } of keys) {
+    const record = await read(state, name, Date.now())
+    if (record && (!options.orgId || record.orgId === options.orgId)) records.push(record)
+  }
+  // Newest first; ids are random, so sort by creation time.
+  return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+export declare namespace list {
+  /** Options for {@link list}. */
+  type Options = {
+    /** Restrict results to keys owned by this organization. */
+    orgId?: string | undefined
+  }
+}
+
+/**
+ * Revokes a key by id, deleting its record and index entry.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @returns Whether a matching record was deleted.
+ */
+export async function revoke(state: Store.State, id: string): Promise<boolean> {
+  const recordKey = await state.get(idKeyFor(id))
+  if (!recordKey) return false
+  await state.delete(recordKey)
+  await state.delete(idKeyFor(id))
+  return true
+}
+
+/**
+ * Reads and validates a stored record by storage key. Invalid, corrupt, or
+ * expired records (`expiresAt <= now`) resolve to `null`.
+ */
+async function read(state: Store.State, key: string, now: number): Promise<Record | null> {
+  const raw = await state.get(key)
+  if (!raw) return null
+  const value = (() => {
+    try {
+      return JSON.parse(raw) as unknown
+    } catch {
+      return undefined
+    }
+  })()
+  if (value === undefined) return null
+  const parsed = schema.Record.safeParse(value)
+  if (!parsed.success) return null
+  const record = parsed.data
+  if (record.expiresAt !== undefined && Date.parse(record.expiresAt) <= now) return null
+  return record
+}
+
+/** Storage-key prefix for the `id → recordKey` index. */
+const idPrefix = 'apikey_id:'
+
+/** Storage key under which a key's `id → recordKey` index entry is persisted. */
+function idKeyFor(id: string): string {
+  return `${idPrefix}${id}`
+}

package/src/App.test-d.ts

@@ -1,4 +1,4 @@
-import type { App, Auth } from 'cadent'
+import type { App, Auth } from 'tapimo'
 
 describe('App.Endpoint', () => {
   // Smoke-test that `App.Endpoint` narrows to the inferred route surface so