tapimo 0.0.2 → 0.2.0

package/src/ApiKeySource.test-d.ts

@@ -1,11 +0,0 @@
-import type * as ApiKeySource from './ApiKeySource.js'
-
-describe('MintInput.scopes', () => {
-  // The scope union flows from the central `Scope.catalog`, so minting
-  // with an unissuable scope is a compile error.
-  test('accepts catalog scopes and the wildcard, rejects unknown ones', () => {
-    expectTypeOf<['data:read', 'webhooks:write']>().toExtend<ApiKeySource.MintInput['scopes']>()
-    expectTypeOf<['*']>().toExtend<ApiKeySource.MintInput['scopes']>()
-    expectTypeOf<['totally:made-up']>().not.toExtend<ApiKeySource.MintInput['scopes']>()
-  })
-})

package/src/ApiKeySource.test.ts

@@ -1,295 +0,0 @@
-import * as ApiKeySource from './ApiKeySource.js'
-import * as Store from './internal/Store.js'
-
-describe('store', () => {
-  test('resolves an unknown token to null', async () => {
-    const source = ApiKeySource.store(Store.memory())
-    expect(await source.resolve('tempo:sk:missing')).toBeNull()
-  })
-
-  // Mock the system clock so timestamps are deterministic without injecting a
-  // clock into the source.
-  describe('provisioning', () => {
-    beforeEach(() => vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') }))
-    afterEach(() => vi.useRealTimers())
-
-    test('mints a key and resolves it', async () => {
-      const source = ApiKeySource.store(Store.memory())
-
-      const { record, token } = await source.mint({
-        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 source.resolve(token)
-      expect(resolved?.orgId).toBe('org_acme')
-      expect(resolved?.scopes).toEqual(['data:read', 'webhooks:write'])
-    })
-
-    test('lists keys newest first, filtered by org', async () => {
-      const source = ApiKeySource.store(Store.memory())
-
-      // Advance the clock between mints so their createdAt timestamps differ and
-      // "newest first" is well-defined.
-      await source.mint({ name: 'a', orgId: 'org_a', scopes: ['data:read'] })
-      vi.setSystemTime(new Date('2026-01-01T00:00:01.000Z'))
-      await source.mint({ name: 'b', orgId: 'org_b', scopes: ['data:read'] })
-
-      const all = await source.list()
-      expect(all.map((record) => record.name)).toMatchInlineSnapshot(`
-        [
-          "b",
-          "a",
-        ]
-      `)
-
-      const scoped = await source.list({ orgId: 'org_b' })
-      expect(scoped.map((record) => record.orgId)).toMatchInlineSnapshot(`
-        [
-          "org_b",
-        ]
-      `)
-    })
-
-    test('revokes a key by id', async () => {
-      const source = ApiKeySource.store(Store.memory())
-
-      const { record, token } = await source.mint({ orgId: 'org_a', scopes: ['data:read'] })
-
-      expect(await source.revoke(record.id)).toBe(true)
-      expect(await source.resolve(token)).toBeNull()
-      expect(await source.revoke(record.id)).toBe(false)
-    })
-
-    test('revoke is O(1): deletes the record without scanning the prefix', async () => {
-      const store = Store.memory()
-      const source = ApiKeySource.store(store)
-
-      const { record } = await source.mint({ orgId: 'org_a', scopes: ['data:read'] })
-
-      // The id index entry maps id -> record key; revoke uses it directly.
-      expect(await source.revoke(record.id)).toBe(true)
-      // Both the record and its id index entry are gone.
-      const { keys } = await store.list({ prefix: 'apikey' })
-      expect(keys).toMatchInlineSnapshot(`[]`)
-    })
-
-    test('excludes a key past its expiry from list', async () => {
-      const source = ApiKeySource.store(Store.memory())
-
-      await source.mint({
-        expiresAt: '2026-01-01T00:00:30.000Z',
-        name: 'short-lived',
-        orgId: 'org_a',
-        scopes: ['data:read'],
-      })
-
-      expect((await source.list()).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 source.list()).toMatchInlineSnapshot(`[]`)
-    })
-  })
-
-  test('resolves before expiry, rejects after', async () => {
-    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') })
-    try {
-      const source = ApiKeySource.store(Store.memory())
-      const { token } = await source.mint({
-        expiresAt: '2026-01-01T00:01:00.000Z',
-        orgId: 'org_a',
-        scopes: ['data:read'],
-      })
-
-      expect((await source.resolve(token))?.orgId).toBe('org_a')
-
-      // Advance the clock past the expiry.
-      vi.setSystemTime(new Date('2026-01-01T00:02:00.000Z'))
-      expect(await source.resolve(token)).toBeNull()
-    } finally {
-      vi.useRealTimers()
-    }
-  })
-
-  test('treats a corrupt record as absent', async () => {
-    const store = Store.memory()
-    const source = ApiKeySource.store(store)
-    const { token } = await source.mint({
-      orgId: 'org_a',
-      scopes: ['data:read'],
-    })
-    // Overwrite the stored record (keyed by token hash) with invalid JSON.
-    const { keys } = await store.list({ prefix: 'apikey:' })
-    await store.put(keys[0]!.name, 'not json')
-    expect(await source.resolve(token)).toBeNull()
-  })
-
-  test('rejects a record with an unknown scope', async () => {
-    const store = Store.memory()
-    const source = ApiKeySource.store(store)
-    const { token } = await source.mint({
-      orgId: 'org_a',
-      scopes: ['data:read'],
-    })
-    const { keys } = await store.list({ prefix: 'apikey:' })
-    await store.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 source.resolve(token)).toBeNull()
-  })
-})
-
-describe('cached', () => {
-  /** Wraps a source so resolve calls to the backend can be counted. */
-  function counting(source: ApiKeySource.Source) {
-    let resolves = 0
-    return {
-      resolves: () => resolves,
-      source: ApiKeySource.from({
-        ...source,
-        async resolve(token) {
-          resolves++
-          return source.resolve(token)
-        },
-      }),
-    }
-  }
-
-  test('serves repeat resolves from cache until the TTL expires', async () => {
-    const backing = ApiKeySource.store(Store.memory())
-    const { token } = await backing.mint({ orgId: 'org_acme', scopes: ['data:read'] })
-    const { resolves, source } = counting(backing)
-    let time = 0
-    const cached = ApiKeySource.cached(source, { now: () => time })
-
-    const first = await cached.resolve(token)
-    time = 59_999
-    const second = await cached.resolve(token)
-
-    expect(resolves()).toMatchInlineSnapshot(`1`)
-    expect(second).toBe(first)
-    expect({
-      ...first,
-      createdAt: '<createdAt>',
-      id: '<id>',
-      tokenLast4: '<last4>',
-    }).toMatchInlineSnapshot(`
-      {
-        "createdAt": "<createdAt>",
-        "environment": "production",
-        "id": "<id>",
-        "orgId": "org_acme",
-        "scopes": [
-          "data:read",
-        ],
-        "tokenLast4": "<last4>",
-      }
-    `)
-
-    time = 60_000
-    await cached.resolve(token)
-    expect(resolves()).toMatchInlineSnapshot(`2`)
-  })
-
-  test('negative-caches unknown tokens with the shorter TTL', async () => {
-    const { resolves, source } = counting(ApiKeySource.store(Store.memory()))
-    let time = 0
-    const cached = ApiKeySource.cached(source, { now: () => time })
-
-    expect(await cached.resolve('tempo:sk:missing')).toBeNull()
-    time = 9_999
-    expect(await cached.resolve('tempo:sk:missing')).toBeNull()
-    expect(resolves()).toMatchInlineSnapshot(`1`)
-
-    time = 10_000
-    expect(await cached.resolve('tempo:sk:missing')).toBeNull()
-    expect(resolves()).toMatchInlineSnapshot(`2`)
-  })
-
-  test('single-flights concurrent misses for one token', async () => {
-    let calls = 0
-    const pending = deferred<null>()
-    const cached = ApiKeySource.cached(
-      ApiKeySource.from({
-        ...ApiKeySource.noop,
-        async resolve() {
-          calls++
-          return pending.promise
-        },
-      }),
-    )
-
-    const requests = [cached.resolve('tempo:sk:a'), cached.resolve('tempo:sk:a')]
-    pending.resolve(null)
-
-    expect(await Promise.all(requests)).toMatchInlineSnapshot(`
-      [
-        null,
-        null,
-      ]
-    `)
-    expect(calls).toMatchInlineSnapshot(`1`)
-  })
-
-  test('does not cache resolve failures', async () => {
-    let calls = 0
-    const cached = ApiKeySource.cached(
-      ApiKeySource.from({
-        ...ApiKeySource.noop,
-        async resolve() {
-          calls++
-          if (calls === 1) throw new Error('kv unavailable')
-          return null
-        },
-      }),
-    )
-
-    await expect(cached.resolve('tempo:sk:a')).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: kv unavailable]`,
-    )
-    expect(await cached.resolve('tempo:sk:a')).toBeNull()
-    expect(calls).toMatchInlineSnapshot(`2`)
-  })
-})
-
-function deferred<value>() {
-  let reject!: (cause?: unknown) => void
-  let resolve!: (value: PromiseLike<value> | value) => void
-  const promise = new Promise<value>((resolve_, reject_) => {
-    reject = reject_
-    resolve = resolve_
-  })
-  return { promise, reject, resolve }
-}

package/src/ApiKeySource.ts

@@ -1,303 +0,0 @@
-/**
- * Pluggable API-key sources for Tempo API.
- *
- * Every backend implements one shared contract ({@link Source}) covering both
- * the read path ({@link Source.resolve}, wired into `Auth.middleware`'s
- * `apiKey.source`) and the provisioning path ({@link Source.mint}/{@link
- * Source.list}/{@link Source.revoke}), so backends are interchangeable wherever a
- * source is accepted. {@link store} is the built-in store-backed source (e.g. a
- * Cloudflare KV namespace); {@link from} type-checks a bring-your-own backend
- * (D1, Postgres, …) against the contract. 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-key source 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 by a source. 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 Source.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 Source.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
-}
-
-/** Options for {@link Source.list}. */
-export type ListOptions = {
-  /** Restrict results to keys owned by this organization. */
-  orgId?: string | undefined
-}
-
-/**
- * The contract every pluggable API-key source implements — both the read path
- * ({@link Source.resolve}, used by `Auth.middleware`'s `apiKey.source`) and the
- * provisioning path ({@link Source.mint}/{@link Source.list}/{@link
- * Source.revoke}). {@link store} is the built-in store-backed source; future
- * database-backed sources (D1, Postgres, …) implement this same contract, so any
- * backend stays interchangeable wherever a source is accepted.
- */
-export type Source = {
-  /** Lists key records (metadata only — never tokens), newest first. */
-  list(options?: ListOptions): Promise<readonly Record[]>
-  /**
-   * Mints a key: persists its hashed record and returns the record plus the
-   * one-time plaintext token (shown once, unrecoverable afterward).
-   */
-  mint(input: MintInput): Promise<MintResult>
-  /** Resolves a plaintext API key token to its metadata, or `null`. */
-  resolve(token: string): Promise<ApiKey.ApiKey | null>
-  /** Revokes a key by id. Returns whether a matching record was deleted. */
-  revoke(id: string): Promise<boolean>
-}
-
-/**
- * Creates a {@link Source} from a value, type-checking it against the contract.
- * The escape hatch for bringing your own backend (D1, Postgres, …): author the
- * implementation inline and have it validated against {@link Source}.
- */
-export function from<const source extends Source>(source: source): source {
-  return source
-}
-
-/**
- * The default {@link Source} when none is configured: it resolves every token to
- * `null` and lists nothing, so API-key access stays closed until a real source
- * (e.g. {@link store}) is wired in. Its provisioning methods are inert —
- * {@link Source.list} returns `[]`, {@link Source.revoke} returns `false`, and
- * {@link Source.mint} throws, since there is nowhere to persist a key.
- */
-export const noop: Source = {
-  async list() {
-    return []
-  },
-  async mint() {
-    throw new Error('cannot mint: no API-key source is configured')
-  },
-  async resolve() {
-    return null
-  },
-  async revoke() {
-    return false
-  },
-}
-
-/**
- * Creates a store-backed {@link Source} over a {@link Store.State}. Records are
- * persisted keyed by token hash (`ApiKey.keyFor`) 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).
- */
-export function store(state: Store.State): Source {
-  return {
-    async list(options = {}) {
-      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))
-    },
-
-    async mint(input) {
-      // Validate input (e.g. reject an unknown scope) at the write boundary so we
-      // never persist a record the reader would later refuse to resolve.
-      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 }
-    },
-
-    async resolve(token) {
-      return read(state, ApiKey.keyFor(token), Date.now())
-    },
-
-    async revoke(id) {
-      const recordKey = await state.get(idKeyFor(id))
-      if (!recordKey) return false
-      await state.delete(recordKey)
-      await state.delete(idKeyFor(id))
-      return true
-    },
-  }
-}
-
-/**
- * Wraps a source with a short-TTL in-memory cache on the resolve path, so hot
- * keys skip the backend read (e.g. a KV `get`) on every request. Positive
- * results cache for `ttl` (default 60s), negative for `negativeTtl` (default
- * 10s) so a freshly minted key is usable quickly; concurrent misses for one
- * token are single-flighted. Entries are keyed by the token's storage-key
- * derivation (`ApiKey.keyFor`, a sha256) — never the plaintext token.
- *
- * The cache is per-isolate, so a revoked key may stay resolvable elsewhere
- * for up to `ttl` — the accepted trade-off for removing a backend read from
- * the auth path of every request. Provisioning methods pass through uncached.
- */
-export function cached(source: Source, options: cached.Options = {}): Source {
-  const { negativeTtl = 10_000, now = Date.now, ttl = 60_000 } = options
-  type Cell = { expiresAt: number; value: ApiKey.ApiKey | null }
-  const cells = new Map<string, Cell>()
-  const flights = new Map<string, Promise<ApiKey.ApiKey | null>>()
-
-  return {
-    ...source,
-    async resolve(token) {
-      // Versioned so a future record-shape change can't serve stale shapes.
-      const key = `v1:${ApiKey.keyFor(token)}`
-      const cell = cells.get(key)
-      if (cell && cell.expiresAt > now()) return cell.value
-      if (cell) cells.delete(key)
-
-      const existing = flights.get(key)
-      if (existing) return existing
-
-      const flight = (async () => {
-        const value = await source.resolve(token)
-        // Bound the cache: random invalid tokens each add a (negative) entry,
-        // so sweep expired cells at the cap and then drop the oldest.
-        if (cells.size >= cachedMaxEntries) {
-          const time = now()
-          for (const [name, entry] of cells) if (entry.expiresAt <= time) cells.delete(name)
-          while (cells.size >= cachedMaxEntries) cells.delete(cells.keys().next().value as string)
-        }
-        cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
-        return value
-      })()
-      flights.set(key, flight)
-      try {
-        return await flight
-      } finally {
-        flights.delete(key)
-      }
-    },
-  }
-}
-
-export declare namespace cached {
-  /** Options for wrapping a source with a short-TTL resolve cache. */
-  type Options = {
-    /** Time-to-live for negative (`null`) results in milliseconds. */
-    negativeTtl?: number | undefined
-    /** Clock used for expiry. */
-    now?: (() => number) | undefined
-    /** Time-to-live for positive results in milliseconds. */
-    ttl?: number | undefined
-  }
-}
-
-/** Maximum resolve-cache entries held per isolate before eviction. */
-const cachedMaxEntries = 10_000
-
-/**
- * Reads and validates a stored record by storage key. Invalid, corrupt, or
- * expired records (`expiresAt <= now`) resolve to `null`. Expiry is enforced
- * here — not just via the store's native TTL — so it holds on backends that
- * evict lazily and regardless of TTL granularity.
- */
-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 store source's `id → recordKey` index. */
-const idPrefix = 'apikey_id:'
-
-/** Storage key under which the store source's `id → recordKey` index entry is persisted. */
-function idKeyFor(id: string): string {
-  return `${idPrefix}${id}`
-}