tapimo 0.0.0 → 0.0.2

package/src/ApiKeySource.ts

@@ -0,0 +1,303 @@
+/**
+ * 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}`
+}

package/src/App.test-d.ts

@@ -0,0 +1,38 @@
+import type { App, Auth } from 'cadent'
+
+describe('App.Endpoint', () => {
+  // Smoke-test that `App.Endpoint` narrows to the inferred route surface so
+  // `Auth.middleware.Options<App.Endpoint>.overrides` keys are typed against
+  // actual mounted routes.
+  test('includes mounted routes and rejects unknown ones', () => {
+    expectTypeOf<'GET /v1/tokens'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/tokens/:token'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/tokens/:symbol'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/addresses/:address/balances'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/blocks'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/blocks/:block'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/exchange/pairs'>().toExtend<App.Endpoint>()
+    expectTypeOf<'GET /v1/indexer/query'>().toExtend<App.Endpoint>()
+    expectTypeOf<'POST /rpc/:chain'>().toExtend<App.Endpoint>()
+
+    expectTypeOf<'GET /v1/bogus'>().not.toExtend<App.Endpoint>()
+    // The mounted routes are GET-only; other verbs must not appear.
+    expectTypeOf<'POST /v1/tokens'>().not.toExtend<App.Endpoint>()
+    expectTypeOf<'DELETE /v1/tokens/:token'>().not.toExtend<App.Endpoint>()
+  })
+
+  test('flows through `Auth.middleware.Options.overrides` keys', () => {
+    // `satisfies` gives a compile error if a route name is misspelled,
+    // removed, or refers to an HTTP method the route doesn't declare.
+    const _options = {
+      overrides: {
+        'GET /v1/tokens': { public: false },
+        'GET /v1/tokens/:symbol': { public: false },
+        'GET /v1/tokens/:token': { public: false },
+        'GET /v1/indexer/query': { apiKey: { scopes: ['indexer:query'] } },
+        'POST /rpc/:chain': { apiKey: { scopes: ['data:read'] } },
+      },
+    } satisfies Auth.middleware.Options<App.Endpoint>
+    void _options
+  })
+})