tapimo 0.1.0 → 0.3.0

package/src/ApiKeys.test.ts

@@ -168,8 +168,162 @@ describe('revoke', () => {
 
     // 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.
+    // The record and both index entries are gone.
     const { keys } = await state.list({ prefix: 'apikey' })
     expect(keys).toMatchInlineSnapshot(`[]`)
   })
 })
+
+describe('get', () => {
+  test('reads a record by id, null when absent', async () => {
+    const state = Store.memory()
+    const { record } = await ApiKeys.mint(state, {
+      orgId: 'org_a',
+      projectId: 'prj_a',
+      scopes: ['data:read'],
+    })
+
+    expect((await ApiKeys.get(state, record.id))?.projectId).toBe('prj_a')
+    expect(await ApiKeys.get(state, 'key_missing')).toBeNull()
+  })
+})
+
+describe('listByOrg', () => {
+  beforeEach(() => vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') }))
+  afterEach(() => vi.useRealTimers())
+
+  test('lists through the org index, newest first, filtered by project', async () => {
+    const state = Store.memory()
+
+    await ApiKeys.mint(state, { name: 'a', orgId: 'org_a', projectId: 'prj_a', scopes: ['data:read'] }) // prettier-ignore
+    vi.setSystemTime(new Date('2026-01-01T00:00:01.000Z'))
+    await ApiKeys.mint(state, { name: 'b', orgId: 'org_a', projectId: 'prj_b', scopes: ['data:read'] }) // prettier-ignore
+    await ApiKeys.mint(state, { name: 'c', orgId: 'org_b', scopes: ['data:read'] })
+
+    expect((await ApiKeys.listByOrg(state, 'org_a')).map((record) => record.name))
+      .toMatchInlineSnapshot(`
+        [
+          "b",
+          "a",
+        ]
+      `)
+    expect(
+      (await ApiKeys.listByOrg(state, 'org_a', { projectId: 'prj_b' })).map(
+        (record) => record.name,
+      ),
+    ).toMatchInlineSnapshot(`
+      [
+        "b",
+      ]
+    `)
+  })
+
+  test('skips and lazily cleans dangling index entries', async () => {
+    const state = Store.memory()
+    await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+
+    // Simulate a record evicted out-of-band (e.g. native TTL), leaving the
+    // index entry behind.
+    const recordKey = (await state.list({ prefix: 'apikey:' })).keys[0]!.name
+    await state.delete(recordKey)
+
+    expect(await ApiKeys.listByOrg(state, 'org_a')).toEqual([])
+    expect((await state.list({ prefix: 'apikey_org:' })).keys).toMatchInlineSnapshot(`[]`)
+  })
+})
+
+describe('attribute', () => {
+  test('re-attributes org and project, moving the org index', async () => {
+    const state = Store.memory()
+    const { record, token } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+
+    const updated = await ApiKeys.attribute(state, record.id, {
+      orgId: 'org_b',
+      projectId: 'prj_b',
+    })
+    expect(updated?.orgId).toBe('org_b')
+    expect(updated?.projectId).toBe('prj_b')
+
+    // The original token keeps resolving, now carrying the attribution.
+    const resolved = await ApiKeys.resolve(state, token)
+    expect(resolved?.orgId).toBe('org_b')
+    expect(resolved?.projectId).toBe('prj_b')
+
+    expect(await ApiKeys.listByOrg(state, 'org_a')).toEqual([])
+    expect((await ApiKeys.listByOrg(state, 'org_b')).map(({ id }) => id)).toEqual([record.id])
+
+    expect(await ApiKeys.attribute(state, 'key_missing', { projectId: 'prj_x' })).toBeNull()
+  })
+})
+
+describe('setBillingActive', () => {
+  test('stamps billingActive onto the org keys in the target environment only', async () => {
+    const state = Store.memory()
+    const { token: sandboxToken } = await ApiKeys.mint(state, {
+      environment: 'sandbox',
+      orgId: 'org_a',
+      scopes: ['data:read'],
+    })
+    const { token: prodToken } = await ApiKeys.mint(state, {
+      environment: 'production',
+      orgId: 'org_a',
+      scopes: ['data:read'],
+    })
+    const { token: otherToken } = await ApiKeys.mint(state, {
+      environment: 'sandbox',
+      orgId: 'org_b',
+      scopes: ['data:read'],
+    })
+
+    const updated = await ApiKeys.setBillingActive(state, {
+      active: true,
+      environment: 'sandbox',
+      orgId: 'org_a',
+    })
+
+    expect(updated).toBe(1)
+    expect((await ApiKeys.resolve(state, sandboxToken))?.billingActive).toBe(true)
+    // The production key and another org's sandbox key are untouched.
+    expect((await ApiKeys.resolve(state, prodToken))?.billingActive).toBeUndefined()
+    expect((await ApiKeys.resolve(state, otherToken))?.billingActive).toBeUndefined()
+  })
+
+  test('skips records already carrying the target value', async () => {
+    const state = Store.memory()
+    await ApiKeys.mint(state, {
+      billingActive: true,
+      environment: 'sandbox',
+      orgId: 'org_a',
+      scopes: ['data:read'],
+    })
+
+    expect(
+      await ApiKeys.setBillingActive(state, {
+        active: true,
+        environment: 'sandbox',
+        orgId: 'org_a',
+      }),
+    ).toBe(0)
+  })
+})
+
+describe('backfill', () => {
+  test('rebuilds index entries for legacy records', async () => {
+    const state = Store.memory()
+    const { record, token } = await ApiKeys.mint(state, { orgId: 'org_a', scopes: ['data:read'] })
+
+    // Legacy state: records exist, index entries do not.
+    for (const { name } of (await state.list({ prefix: 'apikey_id:' })).keys)
+      await state.delete(name)
+    for (const { name } of (await state.list({ prefix: 'apikey_org:' })).keys)
+      await state.delete(name)
+    expect(await ApiKeys.listByOrg(state, 'org_a')).toEqual([])
+
+    expect(await ApiKeys.backfill(state)).toEqual({ indexed: 1, scanned: 1 })
+
+    expect((await ApiKeys.listByOrg(state, 'org_a')).map(({ id }) => id)).toEqual([record.id])
+    expect(await ApiKeys.resolve(state, token)).not.toBeNull()
+    // The id index is restored, so revoke-by-id works again.
+    expect(await ApiKeys.revoke(state, record.id)).toBe(true)
+  })
+})

package/src/ApiKeys.ts

@@ -97,9 +97,11 @@ export async function mint(state: Store.State, input: MintInput): Promise<MintRe
     orgId: data.orgId ?? id,
     scopes: data.scopes,
     tokenLast4: token.slice(-4),
+    ...(data.billingActive === undefined ? {} : { billingActive: data.billingActive }),
     ...(data.createdBy === undefined ? {} : { createdBy: data.createdBy }),
     ...(data.expiresAt === undefined ? {} : { expiresAt: data.expiresAt }),
     ...(data.name === undefined ? {} : { name: data.name }),
+    ...(data.projectId === undefined ? {} : { projectId: data.projectId }),
     ...(data.rateLimits === undefined ? {} : { rateLimits: data.rateLimits }),
   }
 
@@ -113,6 +115,9 @@ export async function mint(state: Store.State, input: MintInput): Promise<MintRe
   // 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 })
+  // Index `org → recordKey` (one entry per key, so concurrent mints never
+  // race a shared value) backing org-scoped listing without a full scan.
+  await state.put(orgKeyFor(record.orgId, record.id), recordKey, { ttl })
   return { record, token }
 }
 
@@ -129,6 +134,19 @@ export async function resolve(state: Store.State, token: string): Promise<ApiKey
   return read(state, ApiKey.keyFor(token), Date.now())
 }
 
+/**
+ * Reads a key record by id (metadata only — never the token), or `null`.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @returns The record, or `null`.
+ */
+export async function get(state: Store.State, id: string): Promise<Record | null> {
+  const recordKey = await state.get(idKeyFor(id))
+  if (!recordKey) return null
+  return read(state, recordKey, Date.now())
+}
+
 /**
  * Lists key records (metadata only — never tokens), newest first. Expired or
  * catalog-invalid records are skipped.
@@ -160,7 +178,47 @@ export declare namespace list {
 }
 
 /**
- * Revokes a key by id, deleting its record and index entry.
+ * Lists an organization's key records through the org index (no full scan),
+ * newest first. Dangling index entries (revoked or expired records) are
+ * skipped and lazily deleted.
+ *
+ * @param state - The KV state store holding key records.
+ * @param orgId - The owning organization id (`org_…`).
+ * @param options - Optional environment/project filters.
+ * @returns The records.
+ */
+export async function listByOrg(
+  state: Store.State,
+  orgId: string,
+  options: listByOrg.Options = {},
+): Promise<readonly Record[]> {
+  const { keys } = await state.list({ prefix: `${orgPrefix}${orgId}:` })
+  const records: Record[] = []
+  for (const { name } of keys) {
+    const recordKey = await state.get(name)
+    const record = recordKey ? await read(state, recordKey, Date.now()) : null
+    if (!record) {
+      await state.delete(name)
+      continue
+    }
+    if (options.environment && record.environment !== options.environment) continue
+    if (!options.projectId || record.projectId === options.projectId) records.push(record)
+  }
+  return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+export declare namespace listByOrg {
+  /** Options for {@link listByOrg}. */
+  type Options = {
+    /** Restrict results to keys in this environment. */
+    environment?: 'production' | 'sandbox' | undefined
+    /** Restrict results to keys attributed to this project. */
+    projectId?: string | undefined
+  }
+}
+
+/**
+ * Revokes a key by id, deleting its record and index entries.
  *
  * @param state - The KV state store holding key records.
  * @param id - The key id (`key_…`).
@@ -169,11 +227,147 @@ export declare namespace list {
 export async function revoke(state: Store.State, id: string): Promise<boolean> {
   const recordKey = await state.get(idKeyFor(id))
   if (!recordKey) return false
+  // Parse loosely for the org index entry: even a record the catalog no
+  // longer validates must clean up its index on revoke.
+  const raw = await state.get(recordKey)
+  const orgId = (() => {
+    try {
+      return raw ? (JSON.parse(raw) as { orgId?: string }).orgId : undefined
+    } catch {
+      return undefined
+    }
+  })()
   await state.delete(recordKey)
   await state.delete(idKeyFor(id))
+  if (orgId) await state.delete(orgKeyFor(orgId, id))
   return true
 }
 
+/**
+ * Re-attributes a key to an organization and/or project, rewriting its record
+ * in place (same token hash) and moving the org index entry when the org
+ * changes. The backfill path for legacy keys.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @param input - The attribution to apply.
+ * @returns The updated record, or `null` when the key is absent.
+ */
+export async function attribute(
+  state: Store.State,
+  id: string,
+  input: attribute.Input,
+): Promise<Record | null> {
+  const recordKey = await state.get(idKeyFor(id))
+  if (!recordKey) return null
+  const record = await read(state, recordKey, Date.now())
+  if (!record) return null
+
+  const updated: Record = {
+    ...record,
+    ...(input.orgId === undefined ? {} : { orgId: input.orgId }),
+    ...(input.projectId === undefined ? {} : { projectId: input.projectId }),
+  }
+  const ttl =
+    updated.expiresAt === undefined
+      ? undefined
+      : Math.max(1, Date.parse(updated.expiresAt) - Date.now())
+  await state.put(recordKey, JSON.stringify(updated), { ttl })
+  if (updated.orgId !== record.orgId) await state.delete(orgKeyFor(record.orgId, id))
+  await state.put(orgKeyFor(updated.orgId, id), recordKey, { ttl })
+  return updated
+}
+
+export declare namespace attribute {
+  /** Attribution applied by {@link attribute}; omitted fields keep their current value. */
+  type Input = {
+    /** New owning organization id (`org_…`). */
+    orgId?: string | undefined
+    /** New owning project id (`prj_…`). */
+    projectId?: string | undefined
+  }
+}
+
+/**
+ * Stamps `billingActive` onto every key an organization owns in an environment,
+ * re-syncing the snapshot the auth path reads when billing flips (activation or
+ * lapse). Called off the request path from the billing writer, so the hot path
+ * never reads billing state. Records already carrying the target value are left
+ * untouched.
+ *
+ * @param state - The KV state store holding key records.
+ * @param options - Owner, environment, and the new billing-active value.
+ * @returns The number of records updated.
+ */
+export async function setBillingActive(
+  state: Store.State,
+  options: setBillingActive.Options,
+): Promise<number> {
+  const { active, environment, orgId } = options
+  const records = await listByOrg(state, orgId, { environment })
+  let updated = 0
+  for (const record of records) {
+    if (record.billingActive === active) continue
+    const recordKey = await state.get(idKeyFor(record.id))
+    if (!recordKey) continue
+    const next: Record = { ...record, billingActive: active }
+    const ttl =
+      next.expiresAt === undefined
+        ? undefined
+        : Math.max(1, Date.parse(next.expiresAt) - Date.now())
+    await state.put(recordKey, JSON.stringify(next), { ttl })
+    updated += 1
+  }
+  return updated
+}
+
+export declare namespace setBillingActive {
+  /** Options for {@link setBillingActive}. */
+  type Options = {
+    /** The new billing-active value to stamp. */
+    active: boolean
+    /** Environment whose keys are re-stamped. */
+    environment: 'production' | 'sandbox'
+    /** Owning organization id (`org_…`). */
+    orgId: string
+  }
+}
+
+/**
+ * Rebuilds the `id` and `org` index entries for every stored record — the
+ * run-once backfill making legacy keys visible to org-scoped listing. Records
+ * themselves are never modified, so existing tokens keep resolving.
+ *
+ * @param state - The KV state store holding key records.
+ * @returns Scanned and indexed record counts.
+ */
+export async function backfill(state: Store.State): Promise<backfill.Result> {
+  const { keys } = await state.list({ prefix: ApiKey.recordPrefix })
+  let indexed = 0
+  for (const { name } of keys) {
+    const record = await read(state, name, Date.now())
+    if (!record) continue
+    const ttl =
+      record.expiresAt === undefined
+        ? undefined
+        : Math.max(1, Date.parse(record.expiresAt) - Date.now())
+    await state.put(idKeyFor(record.id), name, { ttl })
+    await state.put(orgKeyFor(record.orgId, record.id), name, { ttl })
+    indexed += 1
+  }
+  return { indexed, scanned: keys.length }
+}
+
+export declare namespace backfill {
+  /** Result of {@link backfill}. */
+  type Result = {
+    /** Records whose index entries were written. */
+    indexed: number
+    /** Stored records scanned (including invalid or expired ones, skipped). */
+    scanned: number
+  }
+}
+
 /**
  * Reads and validates a stored record by storage key. Invalid, corrupt, or
  * expired records (`expiresAt <= now`) resolve to `null`.
@@ -203,3 +397,11 @@ const idPrefix = 'apikey_id:'
 function idKeyFor(id: string): string {
   return `${idPrefix}${id}`
 }
+
+/** Storage-key prefix for the per-key `org → recordKey` listing index. */
+const orgPrefix = 'apikey_org:'
+
+/** Storage key under which a key's org index entry is persisted. */
+function orgKeyFor(orgId: string, id: string): string {
+  return `${orgPrefix}${orgId}:${id}`
+}