tapimo 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tapimo",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "./dist/index.js",
   "license": "MIT",
   "bin": {
@@ -15,18 +15,19 @@
   "dependencies": {
     "@hono/node-server": "^2.0.3",
     "@hono/standard-validator": "^0.2.2",
+    "accounts": "^0.14.11",
     "hono": "^4.12.26",
     "hono-openapi": "^1.3.0",
     "incur": "^0.4.7",
     "jose": "^6.2.3",
     "kysely": "^0.29.2",
-    "mppx": "^0.8.4",
+    "mppx": "^0.8.5",
     "nanoid": "^5.1.11",
-    "ox": "0.14.29",
+    "ox": "0.14.30",
     "pg": "^8.22.0",
     "tidx.ts": "^0.1.1",
-    "viem": "2.54.1",
-    "vocs": "^2.2.4",
+    "viem": "2.54.6",
+    "vocs": "^2.3.3",
     "zod": "^4.4.3"
   },
   "sideEffects": false,
@@ -38,6 +39,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./apps": {
+      "src": "./src/apps/index.ts",
+      "types": "./dist/apps/index.d.ts",
+      "default": "./dist/apps/index.js"
+    },
     "./admin": {
       "src": "./src/admin/index.ts",
       "types": "./dist/admin/index.d.ts",
@@ -47,6 +53,26 @@
       "src": "./src/cloudflare.ts",
       "types": "./dist/cloudflare.d.ts",
       "default": "./dist/cloudflare.js"
+    },
+    "./data": {
+      "src": "./src/apps/data/index.ts",
+      "types": "./dist/apps/data/index.d.ts",
+      "default": "./dist/apps/data/index.js"
+    },
+    "./docs": {
+      "src": "./src/apps/docs/index.ts",
+      "types": "./dist/apps/docs/index.d.ts",
+      "default": "./dist/apps/docs/index.js"
+    },
+    "./platform": {
+      "src": "./src/apps/platform/index.ts",
+      "types": "./dist/apps/platform/index.d.ts",
+      "default": "./dist/apps/platform/index.js"
+    },
+    "./relay": {
+      "src": "./src/apps/relay/index.ts",
+      "types": "./dist/apps/relay/index.d.ts",
+      "default": "./dist/apps/relay/index.js"
     }
   }
 }

package/src/ApiKey.ts

@@ -33,6 +33,7 @@ export namespace schema {
     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.')),
+    projectId: z.optional(z.string()).check(z.describe('Owning project id (`prj_…`).')),
     rateLimits: z
       .optional(z.record(z.string(), RateLimit.schema.Limit))
       .check(

package/src/ApiKeys.test.ts

@@ -168,8 +168,111 @@ 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('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

@@ -100,6 +100,7 @@ export async function mint(state: Store.State, input: MintInput): Promise<MintRe
     ...(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 +114,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 +133,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 +177,44 @@ 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 project filter.
+ * @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.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 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 +223,102 @@ 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
+  }
+}
+
+/**
+ * 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 +348,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}`
+}