tapimo 0.4.4 → 0.5.1

package/src/apps/relay/App.test.ts

@@ -1,11 +1,12 @@
 import { nanoid } from 'nanoid'
-import { Hash, Secp256k1 } from 'ox'
+import { Hash, Hex, Secp256k1 } from 'ox'
+import { ZoneRpcAuthentication } from 'ox/tempo'
 import { createClient, http } from 'viem'
 import { prepareTransactionRequest, sendRawTransactionSync, signTransaction } from 'viem/actions'
 import { Account as TempoAccount, Actions, Transaction, withRelay } from 'viem/tempo'
 
 import * as TestApp from '../../../test/App.js'
-import { startTempo } from '../../../test/containers.js'
+import * as Containers from '../../../test/containers.js'
 import * as Relay from '../../../test/Relay.js'
 import * as Runtime from '../../../test/runtime.js'
 import * as Tempo from '../../../test/Tempo.js'
@@ -25,6 +26,12 @@ const runtime = Runtime.get()
 
 const feePayerAccount = Tempo.accounts[10]!
 const senderAccount = Tempo.accounts[9]!
+const zone = runtime.zone.chainId
+const zoneScope = `zone:${zone}:read` as const
+const zoneOptions = {
+  chainId: zone,
+  forwardRpcUrl: runtime.zone.forwardRpcUrl,
+}
 
 /** Super admin secret configured on the end-to-end billing app. */
 const superAdminSecret = 'tempo:sk:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
@@ -71,6 +78,22 @@ const keys = [
     scopes: ['rpc-relay:read'],
     token: 'secret_unscoped',
   },
+  {
+    id: 'key_zone_relay',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read', zoneScope],
+    token: 'secret_zone_relay',
+  },
+  {
+    id: 'key_zone_sponsor',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:sponsor', zoneScope],
+    token: 'secret_zone_sponsor',
+  },
   {
     id: 'key_unattributed',
     orgId: 'org_1',
@@ -80,6 +103,303 @@ const keys = [
   },
 ] as const satisfies readonly TestApp.kvStore.Key[]
 
+describe('behavior: Zone chain routing', () => {
+  const zoneSelectors = [
+    ['relay', 'path'],
+    ['relay', 'body'],
+    ['sponsor', 'path'],
+    ['sponsor', 'body'],
+  ] as const
+  // Prool's default Zone dev key.
+  const privateKey = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+
+  function app() {
+    return TestApp.create({
+      auth: { keys },
+      zones: [zoneOptions],
+    })
+  }
+
+  function token() {
+    const issuedAt = Math.floor(Date.now() / 1000)
+    const authentication = ZoneRpcAuthentication.from({
+      chainId: zone,
+      expiresAt: issuedAt + 300,
+      issuedAt,
+      zoneId: 1,
+    })
+    return ZoneRpcAuthentication.serialize(authentication, {
+      signature: Secp256k1.sign({
+        payload: ZoneRpcAuthentication.getSignPayload(authentication),
+        privateKey,
+      }),
+    })
+  }
+
+  async function request(
+    app: ReturnType<typeof TestApp.create>,
+    options: {
+      apiKey?: string | undefined
+      basePath?: string | undefined
+      body: object | readonly object[]
+      mount: 'relay' | 'sponsor'
+      pathChainId?: number | undefined
+      zoneToken?: string | undefined
+    },
+  ) {
+    const apiKey =
+      options.apiKey ?? (options.mount === 'relay' ? 'secret_unscoped' : 'secret_sponsor')
+    const path = `${options.basePath ?? ''}/rpc/${options.mount}${options.pathChainId ? `/${options.pathChainId}` : ''}`
+    const response = await app.fetch(
+      new Request(`http://tempo-api.test${path}`, {
+        body: JSON.stringify(options.body),
+        headers: {
+          'content-type': 'application/json',
+          'tempo-api-key': apiKey,
+          ...(options.zoneToken ? { [ZoneRpcAuthentication.headerName]: options.zoneToken } : {}),
+        },
+        method: 'POST',
+      }),
+    )
+    return await response.json()
+  }
+
+  test.each(zoneSelectors)('rejects an unscoped Zone on %s via %s', async (mount, selector) => {
+    const body = await request(app(), {
+      body: {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: selector === 'body' ? [{ chainId: zone }] : [],
+      },
+      mount,
+      ...(selector === 'path' ? { pathChainId: zone } : {}),
+    })
+    expect(body).toMatchObject({
+      error: {
+        code: -32602,
+        data: { code: 'api_key_forbidden' },
+        message: expect.stringContaining(zoneScope),
+      },
+    })
+  })
+
+  test.each(zoneSelectors)('allows a Zone token on %s via %s', async (mount, selector) => {
+    const body = await request(app(), {
+      body: {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: selector === 'body' ? [{ chainId: zone }] : [],
+      },
+      mount,
+      ...(selector === 'path' ? { pathChainId: zone } : {}),
+      zoneToken: token(),
+    })
+
+    expect(body).toMatchObject({ result: `0x${zone.toString(16)}` })
+  })
+
+  test('allows a Zone token on the default chain', async () => {
+    const api = TestApp.create({
+      auth: { keys },
+      defaultChainId: zone,
+      zones: [zoneOptions],
+    })
+    const body = await request(api, {
+      body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+      mount: 'relay',
+      zoneToken: token(),
+    })
+
+    expect(body).toMatchObject({ result: `0x${zone.toString(16)}` })
+  })
+
+  test('allows a Zone token in a batch', async () => {
+    const body = (await request(app(), {
+      body: [
+        { id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+        { id: 2, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+      ],
+      mount: 'relay',
+      zoneToken: token(),
+    })) as { result?: string }[]
+
+    expect(body.map((entry) => entry.result)).toEqual([
+      `0x${zone.toString(16)}`,
+      `0x${zone.toString(16)}`,
+    ])
+  })
+
+  test.each([
+    ['relay', 'secret_zone_relay'],
+    ['sponsor', 'secret_zone_sponsor'],
+  ] as const)('allows a Zone-scoped key on %s', async (mount, apiKey) => {
+    const body = await request(app(), {
+      apiKey,
+      body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+      mount,
+    })
+
+    expect(body).toMatchObject({ result: `0x${zone.toString(16)}` })
+  })
+
+  test('forwards RPC basic auth to a Zone internal RPC', async () => {
+    const authorization: (string | null)[] = []
+    const server = await Relay.createServer(
+      RequestListener.fromFetchHandler(async (request) => {
+        authorization.push(request.headers.get('authorization'))
+        return Response.json({ id: 1, jsonrpc: '2.0', result: Hex.fromNumber(zone) })
+      }),
+    )
+    try {
+      const api = TestApp.create({
+        auth: { keys },
+        rpc: ({ chainId }) =>
+          chainId === zone ? { basicAuth: 'rpc-secret', url: server.url } : {},
+        zones: [zoneOptions],
+      })
+      const body = await request(api, {
+        apiKey: 'secret_zone_relay',
+        body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+        mount: 'relay',
+      })
+
+      expect(body).toMatchObject({ result: Hex.fromNumber(zone) })
+      expect(authorization).toEqual(['Basic cnBjLXNlY3JldA=='])
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('rejects a blank Zone token', async () => {
+    const body = await request(app(), {
+      body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+      mount: 'relay',
+      zoneToken: '   ',
+    })
+
+    expect(body).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
+  })
+
+  test('does not forward a Zone token to a non-Zone RPC', async () => {
+    const tokens: (string | null)[] = []
+    const server = await Relay.createServer(
+      RequestListener.fromFetchHandler(async (request) => {
+        tokens.push(request.headers.get(ZoneRpcAuthentication.headerName))
+        return Response.json({ id: 1, jsonrpc: '2.0', result: Hex.fromNumber(runtime.chainId) })
+      }),
+    )
+    try {
+      const api = TestApp.create({
+        auth: { keys },
+        rpc: { url: () => server.url },
+        zones: [zoneOptions],
+      })
+      const body = await request(api, {
+        body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+        mount: 'relay',
+        pathChainId: runtime.chainId,
+        zoneToken: token(),
+      })
+
+      expect(body).toMatchObject({ result: Hex.fromNumber(runtime.chainId) })
+      expect(tokens).toEqual([null])
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('rejects conflicting path and body chain ids', async () => {
+    const body = await request(app(), {
+      body: {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_chainId',
+        params: [{ chainId: zone }],
+      },
+      mount: 'relay',
+      pathChainId: runtime.chainId,
+    })
+    expect(body).toMatchObject({ error: { code: -32602, message: 'Conflicting chain ids.' } })
+  })
+
+  test('rejects every Zone request in a batch', async () => {
+    const body = (await request(app(), {
+      body: [
+        { id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+        { id: 2, jsonrpc: '2.0', method: 'eth_chainId', params: [{ chainId: zone }] },
+      ],
+      mount: 'relay',
+    })) as { error?: { data?: { code?: string } } }[]
+
+    expect(body).toHaveLength(2)
+    expect(body.every((entry) => entry.error?.data?.code === 'api_key_forbidden')).toBe(true)
+  })
+
+  test('rejects a Zone configured as the default chain', async () => {
+    const api = TestApp.create({
+      auth: { keys },
+      defaultChainId: zone,
+      zones: [zoneOptions],
+    })
+    const body = await request(api, {
+      body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+      mount: 'relay',
+    })
+
+    expect(body).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
+  })
+
+  test('rejects Zone selectors under a base path', async () => {
+    const api = TestApp.create({
+      auth: { keys },
+      path: '/api',
+      zones: [zoneOptions],
+    })
+    const body = await request(api, {
+      basePath: '/api',
+      body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+      mount: 'relay',
+      pathChainId: zone,
+    })
+
+    expect(body).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
+  })
+
+  test('requires Zone authorization for an embedded signed transaction', async () => {
+    const api = TestApp.create({
+      auth: { keys },
+      relay: { feePayer: { account: feePayerAccount } },
+      zones: [zoneOptions],
+    })
+    const serialized = await senderAccount.signTransaction({
+      chainId: zone,
+      feePayer: true,
+      gas: 100_000n,
+      maxFeePerGas: 1_000_000n,
+      maxPriorityFeePerGas: 0n,
+      nonce: 0,
+      to: Tempo.accounts[8]!.address,
+      value: 0n,
+    })
+    const rpc = {
+      body: {
+        id: 1,
+        jsonrpc: '2.0',
+        method: 'eth_signRawTransaction',
+        params: [serialized],
+      },
+      mount: 'sponsor',
+    } as const
+    const refused = await request(api, rpc)
+    const authorized = await request(api, { ...rpc, zoneToken: token() })
+
+    expect(refused).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
+    expect(authorized).toMatchObject({ result: expect.stringMatching(/^0x/) })
+  })
+})
+
 describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
   test('behavior: scoped keys sponsor, recorded with attribution', async () => {
     const db = TestApp.database()
@@ -130,7 +450,7 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
       `)
   })
 
-  test('behavior: production keys record billable rows', async () => {
+  test('behavior: non-mainnet production keys record billable rows', async () => {
     const db = TestApp.database()
     const app = TestApp.create({
       auth: { keys },
@@ -821,15 +1141,15 @@ describe.runIf(TestStripe.secretKey)(
   () => {
     // prettier-ignore
     const webhookSecret = `whsec_${'c'.repeat(32)}`
-    let node: Awaited<ReturnType<typeof startTempo>> | undefined
+    let node: Awaited<ReturnType<typeof Containers.tempo>> | undefined
 
     beforeAll(async () => {
-      node = await startTempo({ chainId: Viem.chainId.mainnet })
+      node = await Containers.tempo({ chainId: Viem.chainId.mainnet })
     }, 240_000)
 
     afterAll(async () => {
       await TestStripe.sweep()
-      await node?.container.stop()
+      await node?.stop()
     })
 
     test(
@@ -837,7 +1157,8 @@ describe.runIf(TestStripe.secretKey)(
       { retry: 0, timeout: 300_000 },
       async () => {
         // prettier-ignore
-        const { url } = node!
+        const endpoint = node!.endpoints.default
+        const url = `http://${endpoint.host}:${endpoint.port}`
         const stripe = TestStripe.client()
         const db = TestApp.database()
         // The key attributes to org_1; the row must exist for the usage read.

package/src/apps/relay/App.ts

@@ -1,6 +1,7 @@
 import { Hono } from 'hono'
 import { createMiddleware } from 'hono/factory'
 import { RpcResponse } from 'ox'
+import { ZoneRpcAuthentication } from 'ox/tempo'
 import { Addresses, TokenId, Transaction } from 'viem/tempo'
 
 import type * as App from '../../App.js'
@@ -19,8 +20,8 @@ import * as Scope from '../../Scope.js'
 
 /**
  * The relay route group exposes wallet features at `/rpc/relay` and fee
- * sponsorship at `/rpc/sponsor`. Mount it after `data()`, which publishes
- * chain clients and supported chains.
+ * sponsorship at `/rpc/sponsor`. Mount it after `data()`, which publishes the
+ * verified-token and zone context used by relay handlers.
  *
  * ```ts
  * App.create(options).route('/', data()).route('/', relay())
@@ -79,11 +80,13 @@ function middleware(options: middleware.Options) {
     ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
     : 0n
   return createMiddleware<App.Environment>(async (c) => {
+    const principal = Auth.getPrincipal(c)
     const verifiedTokens = c.get('verifiedTokens')
+    const zoneToken_header = c.req.header(ZoneRpcAuthentication.headerName)
+    const zoneToken = zoneToken_header?.trim() ? zoneToken_header : undefined
 
     const feePayer = (() => {
       if (!options.feePayer) return undefined
-      const principal = Auth.getPrincipal(c)
       const attribution =
         principal?.type === 'api_key' && principal.projectId !== undefined
           ? {
@@ -224,13 +227,46 @@ function middleware(options: middleware.Options) {
       } satisfies Handler.relay.Options['feePayer']
     })()
 
+    const authorizeChainId = (chainId: number | undefined) => {
+      const resolved = chainId ?? c.get('chainId')
+      if (!c.get('supportedChainIds').has(resolved))
+        throw new RpcResponse.InvalidParamsError({ message: 'Unsupported chain id.' })
+      if (c.get('zones').has(resolved)) {
+        const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
+        const allowed =
+          scopes?.includes(Scope.wildcard) ||
+          scopes?.includes(`zone:${resolved}:read`) ||
+          zoneToken !== undefined
+        if (allowed) return resolved
+        throw new RpcResponse.InvalidParamsError({
+          data: { code: 'api_key_forbidden' },
+          message: `Chain id ${resolved} is a zone. Use an API key granting \`zone:${resolved}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`,
+        })
+      }
+      return resolved
+    }
+    const zoneClients = new Map<number, Viem.getClient.ReturnType>()
+    const getClient = (chainId: number | undefined) => {
+      const resolved = authorizeChainId(chainId) as Viem.ChainId
+      const zone = c.get('zones').get(resolved)
+      if (!zone || !zoneToken) return c.get('getClient')(resolved)
+      const existing = zoneClients.get(resolved)
+      if (existing) return existing
+      const client = Viem.getClient({
+        chainId: resolved,
+        principal,
+        rpc: { url: () => zone.forwardRpcUrl },
+        zoneToken,
+      })
+      zoneClients.set(resolved, client)
+      return client
+    }
     // Dispatching a standalone Hono via `fetch(c.req.raw)` bypasses Hono's
-    // mount-path stripping, so its internal routes register at the request's
-    // full external path (`basePath` + the RPC mount).
+    // mount-path stripping, so its routes use the full external path.
     const handler = Handler.relay({
       cache: c.get('store'),
       ...(options.features ? { features: options.features } : {}),
-      getClient: (chainId) => c.get('getClient')(chainId as Viem.ChainId | undefined),
+      getClient,
       path: Path.join(c.get('basePath'), options.path),
       ...(feePayer ? { feePayer } : {}),
       ...(verifiedTokens

package/src/apps/relay/Sponsorships.test.ts

@@ -2,12 +2,12 @@ import { nanoid } from 'nanoid'
 import { TxEnvelopeTempo } from 'ox/tempo'
 import type { Client } from 'viem'
 
-import { postgresUrl } from '../../../test/containers.js'
+import * as Runtime from '../../../test/runtime.js'
 import * as Db from '../../db/Db.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Sponsorships from './Sponsorships.js'
 
-const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
 
 /** Baseline insert input; tests override per case. */
 const input = {

package/src/db/Db.test.ts

@@ -1,10 +1,10 @@
 import { nanoid } from 'nanoid'
 
-import { postgresUrl } from '../../test/containers.js'
+import * as Runtime from '../../test/runtime.js'
 import * as Db from './Db.js'
 import * as Organizations from './tables/organizations.js'
 
-const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
 
 describe('postgres', () => {
   test('behavior: migrate is idempotent', async () => {
@@ -16,7 +16,7 @@ describe('postgres', () => {
   })
 
   test('behavior: creates a Postgres db without schema scoping', async () => {
-    const db = Db.postgres({ connectionString: postgresUrl })
+    const db = Db.postgres({ connectionString: Runtime.postgresUrl })
     await db.close()
   })
 
@@ -24,14 +24,14 @@ describe('postgres', () => {
     const schema = `t_${nanoid()}`
     // Pre-create the schema so concurrent migrate races only on the
     // `migrations` ledger, not `CREATE SCHEMA`.
-    const seed = Db.postgres({ connectionString: postgresUrl, schema })
+    const seed = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
     await Organizations.get(seed, 'x').catch(() => {})
     await seed.close()
 
     // Several runners migrate the same fresh schema at once (mirrors parallel
     // deploys). The session advisory lock serializes them; none throw.
     const dbs = Array.from({ length: 5 }, () =>
-      Db.postgres({ connectionString: postgresUrl, schema }),
+      Db.postgres({ connectionString: Runtime.postgresUrl, schema }),
     )
     await Promise.all(dbs.map((db) => db.migrate()))
     const created = await Organizations.create(dbs[0]!, { id: 'org_race', name: 'Race' })

package/src/db/Db.ts

@@ -13,6 +13,7 @@ import * as pg from 'pg'
 import type * as AdminAuditLogs from './tables/adminAuditLogs.js'
 import type * as BillingSettings from './tables/billingSettings.js'
 import type * as Invitations from './tables/invitations.js'
+import type * as InviteLinks from './tables/inviteLinks.js'
 import type * as Memberships from './tables/memberships.js'
 import type * as Organizations from './tables/organizations.js'
 import type * as Projects from './tables/projects.js'
@@ -32,6 +33,8 @@ export type Database = {
   admin_audit_logs: AdminAuditLogs.Table
   billing_settings: BillingSettings.Table
   invitations: Invitations.Table
+  invite_link_redemptions: InviteLinks.RedemptionTable
+  invite_links: InviteLinks.Table
   memberships: Memberships.Table
   migrations: {
     appliedAt: string
@@ -576,6 +579,68 @@ export const migrations: readonly Migration[] = [
         .on('adminAuditLogs')
         .columns(['createdAt', 'id']),
   },
+  {
+    name: '0053_invite_links',
+    up: (db) =>
+      db.schema
+        .createTable('inviteLinks')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('token', 'text', (c) => c.notNull().unique())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('role', 'text', (c) => c.notNull())
+        .addColumn('maxUses', 'integer')
+        .addColumn('useCount', 'integer', (c) => c.notNull().defaultTo(0))
+        .addColumn('expiresAt', 'text')
+        .addColumn('enabled', 'boolean', (c) => c.notNull().defaultTo(true))
+        .addColumn('createdBy', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('lastUsedAt', 'text')
+        .addColumn('updatedAt', 'text', (c) => c.notNull())
+        .addColumn('deletedAt', 'text'),
+  },
+  {
+    name: '0054_invite_links_org_index',
+    up: (db) =>
+      db.schema
+        .createIndex('invite_links_org_idx')
+        .ifNotExists()
+        .on('inviteLinks')
+        .columns(['orgId', 'createdAt']),
+  },
+  {
+    name: '0055_invite_link_redemptions',
+    up: (db) =>
+      db.schema
+        .createTable('inviteLinkRedemptions')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('inviteLinkId', 'text', (c) => c.notNull())
+        .addColumn('inviteLinkName', 'text', (c) => c.notNull())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('userId', 'text', (c) => c.notNull())
+        .addColumn('email', 'text', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0056_invite_link_redemptions_org_index',
+    up: (db) =>
+      db.schema
+        .createIndex('invite_link_redemptions_org_idx')
+        .ifNotExists()
+        .on('inviteLinkRedemptions')
+        .columns(['orgId', 'createdAt']),
+  },
+  {
+    name: '0057_invite_link_redemptions_link_index',
+    up: (db) =>
+      db.schema
+        .createIndex('invite_link_redemptions_link_idx')
+        .ifNotExists()
+        .on('inviteLinkRedemptions')
+        .columns(['inviteLinkId', 'createdAt']),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -81,6 +81,45 @@ export const Invitation = z.object({
 /** Columns of the `invitations` table. */
 export type Invitation = z.output<typeof Invitation>
 
+/** A reusable bearer link granting organization membership. */
+export const InviteLink = z.object({
+  createdAt: z.string().check(z.describe('When the link was created (ISO 8601).')),
+  createdBy: z.string().check(z.describe('User id that created the link, or `super_admin`.')),
+  deletedAt: z.nullable(z.string()).check(z.describe('When the link was soft deleted, or null.')),
+  enabled: z.boolean().check(z.describe('Whether the link is enabled.')),
+  expiresAt: z.nullable(z.string()).check(z.describe('When the link expires, or null.')),
+  id: z.string().check(z.describe('Opaque invite-link resource id (`iln_…`).')),
+  lastUsedAt: z
+    .nullable(z.string())
+    .check(z.describe('When the link last created a membership, or null.')),
+  maxUses: z
+    .nullable(z.number().check(z.int(), z.positive()))
+    .check(z.describe('Maximum redemptions, or null.')),
+  name: z.string().check(z.describe('Link name.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`).')),
+  role: z.literal('member').check(z.describe('Non-privileged role granted by the link.')),
+  token: z.string().check(z.describe('Opaque invite-link bearer token (`lnk_…`).')),
+  updatedAt: z.string().check(z.describe('When the link was last changed (ISO 8601).')),
+  useCount: z.number().check(z.int(), z.nonnegative(), z.describe('Successful redemption count.')),
+})
+
+/** Columns of the `invite_links` table. */
+export type InviteLink = z.output<typeof InviteLink>
+
+/** An audit record for one membership created through an invite link. */
+export const InviteLinkRedemption = z.object({
+  createdAt: z.string().check(z.describe('When the link was redeemed (ISO 8601).')),
+  email: z.string().check(z.describe('Verified email used for redemption.')),
+  id: z.string().check(z.describe('Opaque redemption id (`ilr_…`).')),
+  inviteLinkId: z.string().check(z.describe('Invite-link id.')),
+  inviteLinkName: z.string().check(z.describe('Invite-link name at redemption time.')),
+  orgId: z.string().check(z.describe('Organization id.')),
+  userId: z.string().check(z.describe('Redeeming user id.')),
+})
+
+/** Columns of the `invite_link_redemptions` table. */
+export type InviteLinkRedemption = z.output<typeof InviteLinkRedemption>
+
 /** A user's role within an organization. */
 export const Membership = z.object({
   createdAt: z.string().check(z.describe('When the membership was created (ISO 8601).')),

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

@@ -1,10 +1,10 @@
 import { nanoid } from 'nanoid'
 
-import { postgresUrl } from '../../../test/containers.js'
+import * as Runtime from '../../../test/runtime.js'
 import * as Db from '../Db.js'
 import * as BillingSettings from './billingSettings.js'
 
-const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
 
 /** Redacts nondeterministic row fields (timestamps). */
 function redact(record: BillingSettings.Record) {