tapimo 0.0.0 → 0.0.2

package/src/ApiKey.test.ts

@@ -0,0 +1,91 @@
+import * as ApiKeySource from './ApiKeySource.js'
+import * as ApiKey from './ApiKey.js'
+import * as Store from './internal/Store.js'
+
+describe('schema.ApiKey', () => {
+  test('environment defaults to production when omitted', () => {
+    const parsed = ApiKey.schema.ApiKey.parse({
+      id: 'key_test',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+    })
+    expect(parsed.environment).toMatchInlineSnapshot(`"production"`)
+  })
+
+  test('accepts an explicit sandbox environment', () => {
+    const parsed = ApiKey.schema.ApiKey.parse({
+      environment: 'sandbox',
+      id: 'key_test',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+    })
+    expect(parsed.environment).toMatchInlineSnapshot(`"sandbox"`)
+  })
+
+  test('rejects an unknown environment', () => {
+    expect(
+      ApiKey.schema.ApiKey.safeParse({
+        environment: 'staging',
+        id: 'key_test',
+        orgId: 'org_test',
+        scopes: ['data:read'],
+      }).success,
+    ).toBe(false)
+  })
+})
+
+describe('redact', () => {
+  test('masks tokens anywhere in a string', () => {
+    const token = `tempo:sk:${'a'.repeat(48)}`
+    expect(ApiKey.redact(`auth failed for ${token} on /tokens`)).toMatchInlineSnapshot(
+      `"auth failed for tempo:sk:… on /tokens"`,
+    )
+  })
+
+  test('masks sandbox tokens, preserving their prefix', () => {
+    const token = `tempo_sandbox:sk:${'a'.repeat(48)}`
+    expect(ApiKey.redact(`auth failed for ${token} on /tokens`)).toMatchInlineSnapshot(
+      `"auth failed for tempo_sandbox:sk:… on /tokens"`,
+    )
+  })
+
+  test('masks deprecated v1 tokens', () => {
+    const token = `tempo_${'a'.repeat(40)}`
+    expect(ApiKey.redact(`auth failed for ${token} on /tokens`)).toMatchInlineSnapshot(
+      `"auth failed for tempo_… on /tokens"`,
+    )
+  })
+
+  test('leaves non-token text untouched', () => {
+    expect(ApiKey.redact('nothing secret here')).toMatchInlineSnapshot(`"nothing secret here"`)
+  })
+})
+
+// The wire layout (record prefix + token hash) is the contract every persisted
+// key is stored under; the resolver and every source's `mint` must agree on it.
+// These assertions pin it so an accidental change fails loudly.
+describe('keyFor', () => {
+  test('pins the record prefix and token hash (sha256 of UTF-8 bytes, hex)', () => {
+    expect(ApiKey.recordPrefix).toMatchInlineSnapshot(`"apikey:"`)
+    expect(ApiKey.keyFor('tempo:sk:test')).toMatchInlineSnapshot(
+      `"apikey:9e11781fc2ea4581de193fc7fde09dda7c01151785cdcf2f5fbef52125b225b8"`,
+    )
+  })
+
+  test('reader resolves a record written with the documented wire layout', async () => {
+    const token = `tempo:sk:${'a'.repeat(48)}`
+    const record = {
+      createdAt: '2026-01-01T00:00:00.000Z',
+      id: 'key_smoke',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+      tokenLast4: token.slice(-4),
+    }
+    const store = Store.memory({ entries: [[ApiKey.keyFor(token), JSON.stringify(record)]] })
+    expect(await ApiKeySource.store(store).resolve(token)).toMatchObject({
+      id: 'key_smoke',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+    })
+  })
+})

package/src/ApiKey.ts

@@ -0,0 +1,122 @@
+/**
+ * The resolved API-key resource and the reusable credential primitives every
+ * source backend shares.
+ *
+ * Holds the resolved {@link ApiKey} type and its {@link schema}, the token
+ * format/generation ({@link generateToken}/{@link generateId}), the storage-key
+ * derivation ({@link keyFor}/{@link recordPrefix}), and log {@link redact}ion.
+ * These live here — not in a single source — so every `ApiKeySource` backend
+ * (the built-in store, a future D1/Postgres source) issues and parses
+ * byte-identical credentials and cannot drift. The persisted record/mint-input
+ * shapes and provisioning (mint/list/revoke) belong to the
+ * `ApiKeySource.Source` contract, which composes these primitives with its own
+ * persistence.
+ */
+
+import { nanoid } from 'nanoid'
+import { Hash, Hex } from 'ox'
+import * as z from 'zod/mini'
+
+import * as RateLimit from './internal/RateLimit.js'
+import * as Scope from './Scope.js'
+
+/** Zod schemas owned by the API-key module. */
+export namespace schema {
+  /**
+   * Canonical schema for resolved API-key metadata, and the single source of
+   * truth for the {@link ApiKey} type. `ApiKeySource` derives its persisted
+   * `Record` and `MintInput` schemas from this one, so the resolved and
+   * persisted shapes cannot drift.
+   */
+  export const ApiKey = z.object({
+    environment: z
+      ._default(z.enum(['production', 'sandbox']), 'production')
+      .check(z.describe('Key environment.')),
+    id: z.string().check(z.describe('Stable key id.')),
+    name: z.optional(z.string()).check(z.describe('Human-readable key name.')),
+    orgId: z.string().check(z.describe('Owning organization id.')),
+    rateLimits: z
+      .optional(z.record(z.string(), RateLimit.schema.Limit))
+      .check(
+        z.describe(
+          "Per-key quota overrides keyed by quota scope. The reserved '*' entry is the per-key default; any other key overrides that scope. Omit to inherit server config. The most specific match wins.",
+        ),
+      ),
+    scopes: z
+      .readonly(z.array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard])))
+      .check(z.describe("Granted scopes. '*' grants all scopes.")),
+  })
+}
+
+/** API-key metadata resolved by an auth source. */
+export type ApiKey = z.output<typeof schema.ApiKey>
+
+/**
+ * Replaces every issued token in a string with a masked placeholder so secrets
+ * never reach logs. Apply to anything that may embed a credential — error
+ * stacks, request dumps, and the values of the `tempo-api-key` and
+ * `Authorization` headers (whose tokens match the issued-token pattern).
+ */
+export function redact(text: string): string {
+  return text
+    .replace(tokenPattern(), (match) => `${match.split('sk:')[0]}sk:…`)
+    .replace(legacyTokenPattern(), 'tempo_…')
+}
+
+/**
+ * Token prefix per environment. The prefix encodes the environment so a leaked
+ * sandbox token is visibly distinct from a production one; otherwise there is a
+ * single token kind. Prefixes exist purely for recognizability and leak
+ * detection (CI secret scanning, log redaction — see {@link redact}).
+ */
+const tokenPrefix = {
+  production: 'tempo:sk:',
+  sandbox: 'tempo_sandbox:sk:',
+} as const
+
+/**
+ * Greppable pattern matching an issued token (`tempo:sk:`/`tempo_sandbox:sk:` +
+ * 48–64 lowercase hex chars), suitable for CI secret scanning and log
+ * redaction. A fresh instance is returned on each call so callers never share
+ * `lastIndex` state.
+ */
+function tokenPattern(): RegExp {
+  return /tempo(_sandbox)?:sk:[a-f0-9]{48,64}/g
+}
+
+/**
+ * Greppable pattern matching a deprecated v1 token (`tempo_` + 40 lowercase hex
+ * chars), kept so legacy credentials are redacted from logs with the same
+ * guarantees as current tokens. A fresh instance is returned on each call so
+ * callers never share `lastIndex` state.
+ */
+function legacyTokenPattern(): RegExp {
+  return /tempo_[a-f0-9]{40}/g
+}
+
+/**
+ * Generates a new plaintext token (environment prefix + 48 lowercase hex chars
+ * / 192 bits). Shared by every source backend so issued tokens are
+ * format-identical.
+ */
+export function generateToken(environment: ApiKey['environment'] = 'production'): string {
+  return `${tokenPrefix[environment]}${Hex.random(24).slice(2)}`
+}
+
+/** Generates a stable, opaque key id (`key_…`). */
+export function generateId(): string {
+  return `key_${nanoid()}`
+}
+
+/** Storage-key prefix under which key records are persisted, keyed by token hash. */
+export const recordPrefix = 'apikey:'
+
+/** Hashes a plaintext token to its at-rest lookup hash (lowercase hex, no `0x`). */
+function hash(token: string): string {
+  return Hash.sha256(Hex.fromString(token)).slice(2)
+}
+
+/** Storage key under which the record for a plaintext token is persisted. */
+export function keyFor(token: string): string {
+  return `${recordPrefix}${hash(token)}`
+}

package/src/ApiKeySource.test-d.ts

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,295 @@
+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 }
+}