tapimo 0.14.0 → 0.15.0

package/src/db/tables/apiKeyAdmissionBootstraps.ts

@@ -0,0 +1,4 @@
+import type * as db_Schema from '../Schema.js'
+
+/** Columns recording bounded legacy-key admission reconciliation. */
+export type Table = db_Schema.ApiKeyAdmissionBootstrap

package/src/db/tables/apiKeyAdmissions.ts

@@ -0,0 +1,218 @@
+import { sql } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+import * as ApiKeyRevocations from './apiKeyRevocations.js'
+
+/** Columns of the `api_key_admissions` table. */
+export type Table = db_Schema.ApiKeyAdmission
+
+/** Returns whether an organization completed its bounded legacy-key import. */
+export async function isBootstrapped(db: Db.Db, orgId: string): Promise<boolean> {
+  const record = await db.kysely
+    .selectFrom('api_key_admission_bootstraps')
+    .select('orgId')
+    .where('orgId', '=', orgId)
+    .executeTakeFirst()
+  return record !== undefined
+}
+
+/** Returns whether one key has an authoritative admission row. */
+export async function exists(db: Db.Db, id: string): Promise<boolean> {
+  return (await get(db, id)) !== undefined
+}
+
+/** Reads one authoritative admission row. */
+export async function get(db: Db.Db, id: string): Promise<Table | undefined> {
+  return db.kysely
+    .selectFrom('api_key_admissions')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/** Atomically admits a new key or moves an existing key into an organization. */
+export async function admit(db: Db.Db, options: admit.Options): Promise<boolean> {
+  await lockOrganization(db, options.orgId)
+  await lock(db, options.id)
+  const now = new Date().toISOString()
+  await ApiKeyRevocations.prune(db)
+  if (options.legacy.length > 0)
+    await db.kysely
+      .insertInto('api_key_admissions')
+      .values(
+        options.legacy.map((record) => ({
+          expiresAt: record.expiresAt,
+          id: record.id,
+          orgId: options.orgId,
+          projectId: record.projectId,
+        })),
+      )
+      .onConflict((conflict) => conflict.column('id').doNothing())
+      .execute()
+  if (options.legacyComplete)
+    await db.kysely
+      .insertInto('api_key_admission_bootstraps')
+      .values({ bootstrappedAt: now, orgId: options.orgId })
+      .onConflict((conflict) => conflict.column('orgId').doUpdateSet({ bootstrappedAt: now }))
+      .execute()
+  await db.kysely
+    .deleteFrom('api_key_admissions')
+    .where('orgId', '=', options.orgId)
+    .where('expiresAt', '<=', now)
+    .execute()
+  const existing = await db.kysely
+    .selectFrom('api_key_admissions')
+    .select(['id', 'orgId'])
+    .where('id', '=', options.id)
+    .executeTakeFirst()
+  if (existing?.orgId === options.orgId) {
+    await db.kysely
+      .updateTable('api_key_admissions')
+      .set({ expiresAt: options.expiresAt, projectId: options.projectId })
+      .where('id', '=', options.id)
+      .execute()
+    return true
+  }
+
+  // The ledger wins over KV attribution left by a partially failed external write.
+  const currentOrgId = existing?.orgId ?? options.currentOrgId
+  if (currentOrgId !== options.orgId) {
+    const count = await db.kysely
+      .selectFrom('api_key_admissions')
+      .select((eb) => eb.fn.countAll<number>().as('count'))
+      .where('orgId', '=', options.orgId)
+      .where(
+        'id',
+        'not in',
+        db.kysely
+          .selectFrom('api_key_revocations')
+          .select('id')
+          .where('expiresAt', '>', now)
+          .where('expiresAt', '!=', ApiKeyRevocations.pendingExpiresAt),
+      )
+      .executeTakeFirstOrThrow()
+    if (Number(count.count) >= options.limit) return false
+  }
+
+  if (existing)
+    await db.kysely.deleteFrom('api_key_admissions').where('id', '=', options.id).execute()
+  await db.kysely
+    .insertInto('api_key_admissions')
+    .values({
+      expiresAt: options.expiresAt,
+      id: options.id,
+      orgId: options.orgId,
+      projectId: options.projectId,
+    })
+    .execute()
+  return true
+}
+
+/** Serializes admission and legacy reconciliation for one organization. */
+export async function lockOrganization(db: Db.Db, orgId: string): Promise<void> {
+  await sql`SELECT pg_advisory_xact_lock(hashtextextended(${`api-key-admission-org:${orgId}`}, 0))`.execute(
+    db.kysely,
+  )
+}
+
+export declare namespace admit {
+  /** Key admission inputs. */
+  type Options = {
+    /** Existing organization for attribution moves, if any. */
+    currentOrgId?: string | undefined
+    /** Key expiry, or null for a non-expiring key. */
+    expiresAt: string | null
+    /** Stable API-key id. */
+    id: string
+    /** Maximum live keys across the organization. */
+    limit: number
+    /** Bounded live legacy records used only for the first organization bootstrap. */
+    legacy: readonly Legacy[]
+    /** Whether the legacy scan reached index exhaustion and can complete bootstrap. */
+    legacyComplete: boolean
+    /** Destination organization id. */
+    orgId: string
+    /** Destination project id, or null for an organization-level key. */
+    projectId: string | null
+  }
+
+  /** Existing live key imported during an organization's first admission. */
+  type Legacy = {
+    /** Key expiry, or null for a non-expiring key. */
+    expiresAt: string | null
+    /** Stable API-key id. */
+    id: string
+    /** Project attribution, or null for an organization-level key. */
+    projectId: string | null
+  }
+}
+
+/** Returns whether a ledger-managed key has the supplied attribution. */
+export async function matches(db: Db.Db, owner: matches.Owner): Promise<boolean> {
+  if (await ApiKeyRevocations.exists(db, owner.id)) return false
+  const record = await db.kysely
+    .selectFrom('api_key_admissions')
+    .select(['orgId', 'projectId'])
+    .where('id', '=', owner.id)
+    .executeTakeFirst()
+  if (!record) return !(await isBootstrapped(db, owner.orgId))
+  return record.orgId === owner.orgId && record.projectId === (owner.projectId ?? null)
+}
+
+export declare namespace matches {
+  /** API-key attribution compared with the authoritative ledger. */
+  type Owner = {
+    /** Stable API-key id. */
+    id: string
+    /** Owning organization id. */
+    orgId: string
+    /** Project attribution, when present. */
+    projectId?: string | undefined
+  }
+}
+
+/** Idempotently removes one key's authoritative admission slot. */
+export async function release(db: Db.Db, id: string): Promise<boolean> {
+  await lock(db, id)
+  const result = await db.kysely
+    .deleteFrom('api_key_admissions')
+    .where('id', '=', id)
+    .executeTakeFirst()
+  return result.numDeletedRows > 0n
+}
+
+/** Removes every slot attributed to a deleted organization or project. */
+export async function releaseOwner(db: Db.Db, owner: releaseOwner.Owner): Promise<void> {
+  let query = db.kysely
+    .selectFrom('api_key_admissions')
+    .select('id')
+    .where('orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  const ids = (await query.orderBy('id').execute()).map(({ id }) => id)
+  await ApiKeyRevocations.deletePending(db, ids)
+  if (ids.length > 0)
+    await db.kysely.deleteFrom('api_key_admissions').where('id', 'in', ids).execute()
+  if (owner.projectId === undefined)
+    await db.kysely
+      .deleteFrom('api_key_admission_bootstraps')
+      .where('orgId', '=', owner.orgId)
+      .execute()
+}
+
+export declare namespace releaseOwner {
+  /** Owner whose admitted keys are no longer usable. */
+  type Owner = {
+    /** Owning organization id. */
+    orgId: string
+    /** Deleted project id, or omitted for the whole organization. */
+    projectId?: string | undefined
+  }
+}
+
+/** Serializes admission changes for one stable key id in the caller's transaction. */
+export async function lock(db: Db.Db, id: string): Promise<void> {
+  await sql`SELECT pg_advisory_xact_lock(hashtextextended(${`api-key-admission-id:${id}`}, 0))`.execute(
+    db.kysely,
+  )
+}

package/src/db/tables/apiKeyOwnerAdmissions.ts

@@ -0,0 +1,4 @@
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the migration-compatible `api_key_owner_admissions` table. */
+export type Table = db_Schema.ApiKeyOwnerAdmission

package/src/db/tables/apiKeyOwnerTombstones.ts

@@ -0,0 +1,81 @@
+import { sql } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `api_key_owner_tombstones` table. */
+export type Table = db_Schema.ApiKeyOwnerTombstone
+
+/** Returns whether an organization or its attributed project has been deleted. */
+export async function isDeleted(db: Db.Db, owner: Owner): Promise<boolean> {
+  const keys = ownerKeys(owner)
+  return (
+    (await db.kysely
+      .selectFrom('api_key_owner_tombstones')
+      .select('id')
+      .where('id', 'in', keys)
+      .limit(1)
+      .executeTakeFirst()) !== undefined
+  )
+}
+
+/** Records a permanent owner deletion fence in the caller's transaction. */
+export async function markDeleted(db: Db.Db, owner: Owner): Promise<void> {
+  await lock(db, ownerKeys(owner), 'exclusive')
+  await db.kysely
+    .insertInto('api_key_owner_tombstones')
+    .values({ createdAt: new Date().toISOString(), id: key(owner) })
+    .onConflict((conflict) => conflict.column('id').doNothing())
+    .execute()
+}
+
+/** Holds shared owner locks and returns whether neither owner fence exists. */
+export async function lockActive(db: Db.Db, owner: Owner): Promise<boolean> {
+  return lockActiveMany(db, [owner])
+}
+
+/** Holds shared locks for every owner and returns whether none has a deletion fence. */
+export async function lockActiveMany(db: Db.Db, owners: readonly Owner[]): Promise<boolean> {
+  const keys = [...new Set(owners.flatMap(ownerKeys))].sort()
+  await lock(db, keys, 'shared')
+  return (
+    (await db.kysely
+      .selectFrom('api_key_owner_tombstones')
+      .select('id')
+      .where('id', 'in', keys)
+      .limit(1)
+      .executeTakeFirst()) === undefined
+  )
+}
+
+/** API-key owner attribution checked by the deletion fence. */
+export type Owner = {
+  /** Owning organization id. */
+  orgId: string
+  /** Project id when the fence applies only to one project. */
+  projectId?: string | undefined
+}
+
+/** Builds a collision-free key from typed Tempo resource ids. */
+function key(owner: Owner) {
+  return owner.projectId === undefined
+    ? `organization:${owner.orgId}`
+    : `project:${owner.orgId}:${owner.projectId}`
+}
+
+/** Builds the hierarchical lock keys for an owner. */
+function ownerKeys(owner: Owner) {
+  const keys = [key({ orgId: owner.orgId })]
+  if (owner.projectId !== undefined) keys.push(key(owner))
+  return keys
+}
+
+/** Locks sorted owner keys, preventing mint/delete races without deadlocks. */
+async function lock(db: Db.Db, keys: readonly string[], mode: 'exclusive' | 'shared') {
+  for (const value of keys)
+    if (mode === 'shared')
+      await sql`SELECT pg_advisory_xact_lock_shared(hashtextextended(${value}, 0))`.execute(
+        db.kysely,
+      )
+    else await sql`SELECT pg_advisory_xact_lock(hashtextextended(${value}, 0))`.execute(db.kysely)
+}

package/src/db/tables/apiKeyRevocations.test.ts

@@ -0,0 +1,74 @@
+import { nanoid } from 'nanoid'
+
+import * as TestApp from '../../../test/App.js'
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as ApiKeyRevocations from './apiKeyRevocations.js'
+
+describe('prune', () => {
+  test('qualifies tables in a schema-scoped database', async () => {
+    const schema = `t_${nanoid()}`
+    const migrator = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    await migrator.migrate()
+    await migrator.close()
+
+    // A fresh pool keeps the default search path, matching preview Workers.
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    const expired = '2026-01-01T00:00:00.000Z'
+    await db.kysely
+      .insertInto('api_key_revocations')
+      .values({ expiresAt: expired, id: 'key_scoped', orgId: null, revokedAt: expired })
+      .execute()
+
+    expect(await ApiKeyRevocations.prune(db, new Date('2026-01-02T00:00:00.000Z'))).toBe(1)
+    await db.close()
+  })
+
+  test('concurrent pruners delete admissions for their exact fence batches', async () => {
+    const db = TestApp.database()
+    const count = ApiKeyRevocations.pruneLimit + 1
+    const expiresAt = '2026-01-01T00:00:00.000Z'
+    const ids = Array.from({ length: count }, (_, index) => `key_prune_${index}`)
+    await db.kysely
+      .insertInto('api_key_revocations')
+      .values(
+        ids.map((id) => ({
+          expiresAt,
+          id,
+          orgId: null,
+          revokedAt: expiresAt,
+        })),
+      )
+      .execute()
+    await db.kysely
+      .insertInto('api_key_admissions')
+      .values(
+        ids.map((id) => ({
+          expiresAt: null,
+          id,
+          orgId: 'org_prune',
+          projectId: null,
+        })),
+      )
+      .execute()
+
+    const deleted = await Promise.all([
+      ApiKeyRevocations.prune(db, new Date('2026-01-02T00:00:00.000Z')),
+      ApiKeyRevocations.prune(db, new Date('2026-01-02T00:00:00.000Z')),
+    ])
+
+    expect(deleted.reduce((total, value) => total + value, 0)).toBe(count)
+    const [admissions, revocations] = await Promise.all([
+      db.kysely
+        .selectFrom('api_key_admissions')
+        .select((eb) => eb.fn.countAll<number>().as('count'))
+        .executeTakeFirstOrThrow(),
+      db.kysely
+        .selectFrom('api_key_revocations')
+        .select((eb) => eb.fn.countAll<number>().as('count'))
+        .executeTakeFirstOrThrow(),
+    ])
+    expect(Number(admissions.count)).toBe(0)
+    expect(Number(revocations.count)).toBe(0)
+  })
+})

package/src/db/tables/apiKeyRevocations.ts

@@ -0,0 +1,121 @@
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `api_key_revocations` table. */
+export type Table = db_Schema.ApiKeyRevocation
+
+/** Retains fences beyond KV propagation and the one-minute in-process auth cache. */
+export const retentionMs = 7 * 24 * 60 * 60_000
+
+/** Non-expiring fence used until KV deletion is confirmed. */
+export const pendingExpiresAt = '9999-12-31T23:59:59.999Z'
+
+/** Maximum expired fences reclaimed by one revocation. */
+export const pruneLimit = 1_000
+
+/** Returns whether one stable API-key id has been revoked. */
+export async function exists(db: Db.Db, id: string): Promise<boolean> {
+  return (
+    (await db.kysely
+      .selectFrom('api_key_revocations')
+      .select('id')
+      .where('id', '=', id)
+      .where('expiresAt', '>', new Date().toISOString())
+      .executeTakeFirst()) !== undefined
+  )
+}
+
+/** Fences one API-key id through the propagation window. Rotations use a new id. */
+export async function mark(db: Db.Db, id: string, orgId: string | null): Promise<void> {
+  const time = new Date()
+  await prune(db, time)
+  const organization = orgId
+    ? await db.kysely
+        .selectFrom('organizations')
+        .select('id')
+        .where('id', '=', orgId)
+        .executeTakeFirst()
+    : undefined
+  await db.kysely
+    .insertInto('api_key_revocations')
+    .values({
+      expiresAt: new Date(time.getTime() + retentionMs).toISOString(),
+      id,
+      orgId: organization?.id ?? null,
+      revokedAt: time.toISOString(),
+    })
+    .onConflict((conflict) =>
+      conflict.column('id').doUpdateSet({
+        expiresAt: new Date(time.getTime() + retentionMs).toISOString(),
+      }),
+    )
+    .execute()
+}
+
+/** Fences one API-key id without releasing its slot until KV deletion succeeds. */
+export async function markPending(db: Db.Db, id: string, orgId: string | null): Promise<void> {
+  const time = new Date()
+  const now = time.toISOString()
+  const organization = orgId
+    ? await db.kysely
+        .selectFrom('organizations')
+        .select('id')
+        .where('id', '=', orgId)
+        .executeTakeFirst()
+    : undefined
+  await db.kysely
+    .insertInto('api_key_revocations')
+    .values({
+      expiresAt: pendingExpiresAt,
+      id,
+      orgId: organization?.id ?? null,
+      revokedAt: time.toISOString(),
+    })
+    .onConflict((conflict) =>
+      conflict
+        .column('id')
+        .doUpdateSet({ expiresAt: pendingExpiresAt })
+        .where('api_key_revocations.expiresAt', '<=', now),
+    )
+    .execute()
+}
+
+/** Deletes pending fences whose admission slots are being removed with an owner. */
+export async function deletePending(db: Db.Db, ids: readonly string[]): Promise<void> {
+  if (ids.length === 0) return
+  await db.kysely
+    .deleteFrom('api_key_revocations')
+    .where('id', 'in', ids)
+    .where('expiresAt', '=', pendingExpiresAt)
+    .execute()
+}
+
+/** Reclaims a bounded batch of fences after stale KV and auth entries have expired. */
+export async function prune(db: Db.Db, time = new Date()): Promise<number> {
+  const result = await db.kysely
+    .with(
+      (cte) => cte('expired').materialized(),
+      (qb) =>
+        qb
+          .selectFrom('api_key_revocations')
+          .select('id')
+          .where('expiresAt', '<=', time.toISOString())
+          .orderBy('expiresAt')
+          .orderBy('id')
+          .limit(pruneLimit)
+          .forUpdate()
+          .skipLocked(),
+    )
+    .with('deleted_admissions', (qb) =>
+      qb
+        .deleteFrom('api_key_admissions')
+        .using('expired')
+        .whereRef('api_key_admissions.id', '=', 'expired.id'),
+    )
+    .deleteFrom('api_key_revocations')
+    .using('expired')
+    .whereRef('api_key_revocations.id', '=', 'expired.id')
+    .returning('api_key_revocations.id')
+    .execute()
+  return result.length
+}

package/src/db/tables/authAccounts.ts

@@ -0,0 +1,105 @@
+import type { ColumnType } from 'kysely'
+
+import * as Id from '../../internal/Id.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** A Better Auth `Date` written as canonical ISO text. */
+type Timestamp = ColumnType<string, Date | string, Date | string>
+
+/** Columns of Better Auth's pinned `account` model. */
+export type Table = Omit<
+  db_Schema.AuthAccount,
+  'accessTokenExpiresAt' | 'createdAt' | 'refreshTokenExpiresAt' | 'updatedAt'
+> & {
+  accessTokenExpiresAt: Timestamp | null
+  createdAt: Timestamp
+  refreshTokenExpiresAt: Timestamp | null
+  updatedAt: Timestamp
+}
+
+const walletIssuer = 'tempo:siwe'
+
+/**
+ * Reads the user linked to a SIWE wallet.
+ *
+ * @param db - The database.
+ * @param address - The wallet address.
+ * @returns The linked user id, or `undefined` when absent.
+ */
+export async function getWalletUserId(db: Db.Db, address: string): Promise<string | undefined> {
+  const account = await db.kysely
+    .selectFrom('auth_accounts')
+    .select('userId')
+    .where('accountId', '=', address.toLowerCase())
+    .where('issuer', '=', walletIssuer)
+    .executeTakeFirst()
+  return account?.userId
+}
+
+/**
+ * Reads the wallet linked to a user.
+ *
+ * @param db - The database.
+ * @param userId - The user id.
+ * @returns The linked wallet address, or `undefined` when absent.
+ */
+export async function getWalletAddress(db: Db.Db, userId: string): Promise<string | undefined> {
+  const account = await db.kysely
+    .selectFrom('auth_accounts')
+    .select('accountId')
+    .where('issuer', '=', walletIssuer)
+    .where('userId', '=', userId)
+    .orderBy('createdAt', 'asc')
+    .executeTakeFirst()
+  return account?.accountId
+}
+
+/**
+ * Sets a SIWE wallet's stable user and returns the stored user id.
+ *
+ * @param db - The database.
+ * @param options - Wallet link fields.
+ * @returns The stored user id.
+ */
+export async function setWalletUser(db: Db.Db, options: setWalletUser.Options): Promise<string> {
+  const accountId = options.address.toLowerCase()
+  const now = new Date().toISOString()
+  const account = await db.kysely
+    .insertInto('auth_accounts')
+    .values({
+      accessToken: null,
+      accessTokenExpiresAt: null,
+      accountId,
+      createdAt: now,
+      id: Id.generate('acc'),
+      idToken: null,
+      issuer: walletIssuer,
+      password: null,
+      providerId: 'siwe',
+      refreshToken: null,
+      refreshTokenExpiresAt: null,
+      scope: null,
+      updatedAt: now,
+      userId: options.userId,
+    })
+    .onConflict((oc) =>
+      oc.columns(['issuer', 'accountId']).doUpdateSet({
+        updatedAt: now,
+        userId: options.userId,
+      }),
+    )
+    .returning('userId')
+    .executeTakeFirstOrThrow()
+  return account.userId
+}
+
+export declare namespace setWalletUser {
+  /** Fields accepted when setting a SIWE wallet user. */
+  type Options = {
+    /** Wallet address to link. */
+    address: string
+    /** Stable owning user id. */
+    userId: string
+  }
+}

package/src/db/tables/authSessions.ts

@@ -0,0 +1,13 @@
+import type { ColumnType } from 'kysely'
+
+import type * as db_Schema from '../Schema.js'
+
+/** A Better Auth `Date` written as canonical ISO text. */
+type Timestamp = ColumnType<string, Date, Date>
+
+/** Columns of Better Auth's pinned `session` model. */
+export type Table = Omit<db_Schema.AuthSession, 'createdAt' | 'expiresAt' | 'updatedAt'> & {
+  createdAt: Timestamp
+  expiresAt: Timestamp
+  updatedAt: Timestamp
+}

package/src/db/tables/authVerifications.ts

@@ -0,0 +1,13 @@
+import type { ColumnType } from 'kysely'
+
+import type * as db_Schema from '../Schema.js'
+
+/** A Better Auth `Date` written as canonical ISO text. */
+type Timestamp = ColumnType<string, Date, Date>
+
+/** Columns of Better Auth's pinned `verification` model. */
+export type Table = Omit<db_Schema.AuthVerification, 'createdAt' | 'expiresAt' | 'updatedAt'> & {
+  createdAt: Timestamp
+  expiresAt: Timestamp
+  updatedAt: Timestamp
+}