tapimo 0.5.3 → 0.7.0

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

@@ -656,6 +656,19 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
 // Chain-free (`eth_signRawTransaction` signs locally; the sponsor fee token
 // short-circuits resolution), so the gate matrix runs in every mode.
 describe('behavior: mainnet billing gate', () => {
+  const fill = {
+    calls: [{ to: Tempo.accounts[8]!.address, value: '0x0' }],
+    capabilities: { balanceDiffs: false },
+    chainId: Hex.fromNumber(Viem.chainId.mainnet),
+    feePayer: true,
+    feeToken: '0x20c0000000000000000000000000000000000000',
+    from: senderAccount.address,
+    gas: Hex.fromNumber(100_000),
+    maxFeePerGas: Hex.fromNumber(1_000_000),
+    maxPriorityFeePerGas: '0x0',
+    nonce: '0x0',
+  } as const
+
   function createApp(db: Db.Source = TestApp.database()) {
     return TestApp.create({
       auth: { keys },
@@ -692,6 +705,64 @@ describe('behavior: mainnet billing gate', () => {
     expect(body.error?.data).toStrictEqual({ code: 'billing_required' })
   })
 
+  test('behavior: returns the billing reason for sponsor fills', async () => {
+    const body = await relayRequest(createApp(), {
+      method: 'eth_fillTransaction',
+      params: [fill],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toStrictEqual({
+      code: -32602,
+      data: { code: 'billing_required' },
+      message: 'Billing required.',
+    })
+  })
+
+  test('behavior: relay fills still fall back to self-payment', async () => {
+    const server = await Relay.createServer(
+      RequestListener.fromFetchHandler(async (request) => {
+        type Rpc = {
+          id: number
+          method: string
+          params: readonly [Record<string, unknown>]
+        }
+        const rpc = (await request.json()) as Rpc
+        if (rpc.method !== 'eth_fillTransaction')
+          return Response.json({ id: rpc.id, jsonrpc: '2.0', result: '0x' })
+        return Response.json({
+          id: rpc.id,
+          jsonrpc: '2.0',
+          result: { capabilities: {}, tx: rpc.params[0] },
+        })
+      }),
+    )
+    try {
+      const body = await relayRequest(
+        TestApp.create({
+          auth: { keys },
+          db: TestApp.database(),
+          relay: { feePayer: { account: feePayerAccount } },
+          rpc: { url: () => server.url },
+          supportedChainIds: [Viem.chainId.mainnet],
+        }),
+        {
+          method: 'eth_fillTransaction',
+          mount: 'relay',
+          params: [fill],
+          token: 'secret_wildcard_prod',
+        },
+      )
+      type Result = {
+        capabilities?: { sponsored?: boolean | undefined } | undefined
+      }
+      const result = body.result as unknown as Result
+      expect(body.error).toBeUndefined()
+      expect(result.capabilities?.sponsored).toBe(false)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
   test('behavior: refuses mainnet sponsorship while billing is inactive', async () => {
     const db = TestApp.database()
     await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_gate' })
@@ -1110,13 +1181,10 @@ async function signSponsorable(
   })
 }
 
-/** Posts one JSON-RPC request to the composed app's sponsor mount. */
-async function relayRequest(
-  app: ReturnType<typeof TestApp.create>,
-  options: { method: string; params: readonly unknown[]; token?: string | undefined },
-) {
+/** Posts one JSON-RPC request to a composed relay mount. */
+async function relayRequest(app: ReturnType<typeof TestApp.create>, options: relayRequest.Options) {
   const response = await app.fetch(
-    new Request('http://tempo-api.test/rpc/sponsor', {
+    new Request(`http://tempo-api.test/rpc/${options.mount ?? 'sponsor'}`, {
       body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: options.method, params: options.params }), // prettier-ignore
       headers: {
         'content-type': 'application/json',
@@ -1131,6 +1199,20 @@ async function relayRequest(
   }
 }
 
+declare namespace relayRequest {
+  /** Options for one composed relay request. */
+  type Options = {
+    /** JSON-RPC method. */
+    method: string
+    /** Relay mount to call. */
+    mount?: 'relay' | 'sponsor' | undefined
+    /** JSON-RPC parameters. */
+    params: readonly unknown[]
+    /** API-key credential. */
+    token?: string | undefined
+  }
+}
+
 // The full billing-to-invoice flow with nothing synthetic: a disposable node
 // runs under mainnet's chain id (dev consensus, funded dev alloc), so a real
 // card attach opens the real gate, a real sponsored transaction mines with a

package/src/apps/relay/App.ts

@@ -8,6 +8,7 @@ import type * as App from '../../App.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Fees from '../../internal/Fees.js'
+import * as Log from '../../internal/Log.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
@@ -75,6 +76,9 @@ export declare namespace relay {
 // Builds request-aware RPC middleware. Viem clients are memoized upstream, so
 // constructing `Handler.relay` per request stays cheap.
 function middleware(options: middleware.Options) {
+  // The sponsor mount promises a fee-payer signature. The relay mount may
+  // fall back to self-payment when policy refuses sponsorship.
+  const sponsorshipRequired = options.path === 'rpc/sponsor'
   // Platform-wide per-transaction cap; org settings tighten it, never loosen.
   const txFeeLimit = options.feePayer
     ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
@@ -111,12 +115,20 @@ function middleware(options: middleware.Options) {
           // only mainnet: the relay resolves chainId from the request body, so
           // the query-string chain guard never sees it.
           const id = Number(transaction.chainId)
-          if (!attribution || !sponsorable || !c.get('supportedChainIds').has(id)) return false
+          if (!attribution || !sponsorable || !c.get('supportedChainIds').has(id)) {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+            return false
+          }
           if (!Viem.isMainnet(id)) return true
           // Mainnet is production-only: a sandbox key resolves chainId from the
           // request body, so the auth-layer sandbox/mainnet guard never sees
           // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
-          if (attribution.environment !== 'production') return false
+          if (attribution.environment !== 'production') {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+            return false
+          }
 
           // Enforcement reads hit the primary, never the cached replica: a
           // stale `past_due`, a lowered limit, or another isolate's pending
@@ -127,8 +139,22 @@ function middleware(options: middleware.Options) {
           // `past_due` gets its own reason: the caller must settle an invoice,
           // not attach a card.
           const billing = await Billing.status(db, attribution.orgId)
-          if (billing === 'past_due') return 'billing_past_due'
-          if (billing !== 'active') return 'billing_required'
+          if (billing === 'past_due') {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'billing_past_due' },
+                message: 'Billing past due.',
+              })
+            return 'billing_past_due'
+          }
+          if (billing !== 'active') {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'billing_required' },
+                message: 'Billing required.',
+              })
+            return 'billing_required'
+          }
 
           const feeToken = (() => {
             try {
@@ -144,21 +170,40 @@ function middleware(options: middleware.Options) {
             !verified ||
             verified.currency.toLowerCase() !== 'usd' ||
             verified.decimals !== Fees.tokenDecimals
-          )
-            // prettier-ignore
+          ) {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'fee_token_unsupported' },
+                message: 'Fee token unsupported.',
+              })
             return 'fee_token_unsupported'
+          }
 
           // Fail closed: a transaction whose signed cap cannot be computed
           // cannot be bounded, so it never sponsors on mainnet.
           const feeMax = Fees.maxOf(transaction)
-          if (feeMax === undefined) return 'tx_fee_limit_exceeded'
+          if (feeMax === undefined) {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'tx_fee_limit_exceeded' },
+                message: 'Transaction fee limit exceeded.',
+              })
+            return 'tx_fee_limit_exceeded'
+          }
           const settings = await BillingSettings.get(db, attribution.orgId)
           const cap = (() => {
             if (settings?.txFeeLimit == null) return txFeeLimit
             const org = Billing.toBaseUnits(settings.txFeeLimit)
             return org < txFeeLimit ? org : txFeeLimit
           })()
-          if (feeMax > cap) return 'tx_fee_limit_exceeded'
+          if (feeMax > cap) {
+            if (sponsorshipRequired)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'tx_fee_limit_exceeded' },
+                message: 'Transaction fee limit exceeded.',
+              })
+            return 'tx_fee_limit_exceeded'
+          }
           // The period spend limit is enforced atomically at recording time
           // (`onSponsored` → `SponsoredTransactions.reserve`); a check here
           // would be a check-then-act race a burst could slip through.
@@ -278,7 +323,14 @@ function middleware(options: middleware.Options) {
           }
         : {}),
     })
-    return handler.fetch(c.req.raw)
+    const response = await handler.fetch(c.req.raw)
+    const body: unknown = await response
+      .clone()
+      .json()
+      .catch(() => undefined)
+    const rpc = Log.rpcErrors(body)
+    if (rpc) c.set('rpcResponse', rpc)
+    return response
   })
 }
 

package/src/db/Db.test.ts

@@ -1,7 +1,9 @@
+import { sql } from 'kysely'
 import { nanoid } from 'nanoid'
 
 import * as Runtime from '../../test/runtime.js'
 import * as Db from './Db.js'
+import * as Invitations from './tables/invitations.js'
 import * as Organizations from './tables/organizations.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
@@ -15,6 +17,23 @@ describe('postgres', () => {
     await db.close()
   })
 
+  test('behavior: legacy invitation inserts do not grant early access', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_legacy', name: 'Legacy' })
+    await sql`
+      INSERT INTO invitations (
+        id, org_id, email, role, invited_by, expires_at, accepted_at, revoked_at, created_at
+      ) VALUES (
+        'inv_legacy', 'org_legacy', 'legacy@example.org', 'member', 'usr_legacy',
+        '2027-01-01T00:00:00.000Z', NULL, NULL, '2026-07-20T00:00:00.000Z'
+      )
+    `.execute(db.kysely)
+
+    expect((await Invitations.get(db, 'inv_legacy'))?.grantsEarlyAccess).toBe(false)
+    await db.close()
+  })
+
   test('behavior: creates a Postgres db without schema scoping', async () => {
     const db = Db.postgres({ connectionString: Runtime.postgresUrl })
     await db.close()

package/src/db/Db.ts

@@ -12,6 +12,8 @@ import * as pg from 'pg'
 
 import type * as AdminAuditLogs from './tables/adminAuditLogs.js'
 import type * as BillingSettings from './tables/billingSettings.js'
+import type * as EarlyAccess from './tables/earlyAccess.js'
+import type * as EnabledBillingSources from './tables/enabledBillingSources.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'
@@ -21,6 +23,7 @@ import type * as RequestUsage from './tables/requestUsage.js'
 import type * as SponsoredTransactions from './tables/sponsoredTransactions.js'
 import type * as StripeCustomers from './tables/stripeCustomers.js'
 import type * as Users from './tables/users.js'
+import type * as VerifiedTokenRequests from './tables/verifiedTokenRequests.js'
 import type * as VerifiedTokens from './tables/verifiedTokens.js'
 import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
@@ -32,6 +35,8 @@ import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
 export type Database = {
   admin_audit_logs: AdminAuditLogs.Table
   billing_settings: BillingSettings.Table
+  early_access: EarlyAccess.Table
+  enabled_billing_sources: EnabledBillingSources.Table
   invitations: Invitations.Table
   invite_link_redemptions: InviteLinks.RedemptionTable
   invite_links: InviteLinks.Table
@@ -51,6 +56,7 @@ export type Database = {
   stripe_customers: StripeCustomers.Table
   users: Users.Table
   verified_token_lists: VerifiedTokens.ListTable
+  verified_token_requests: VerifiedTokenRequests.Table
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
   webhook_subscriptions: WebhookSubscriptions.Table
@@ -645,6 +651,125 @@ export const migrations: readonly Migration[] = [
     name: '0058_request_usage_sequence_bigint',
     up: (db) => raw(db, sql`ALTER TABLE request_usage_meter_events ALTER COLUMN sequence TYPE bigint`), // prettier-ignore
   },
+  {
+    name: '0059_verified_token_requests',
+    up: (db) =>
+      db.schema
+        .createTable('verifiedTokenRequests')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('requestedBy', 'text', (c) => c.notNull())
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('address', 'text', (c) => c.notNull())
+        .addColumn('symbol', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('currency', 'text', (c) => c.notNull())
+        .addColumn('decimals', 'integer', (c) => c.notNull())
+        .addColumn('logoUri', 'text')
+        .addColumn('note', 'text')
+        .addColumn('status', 'text', (c) => c.notNull().defaultTo('pending'))
+        .addColumn('reviewNote', 'text')
+        .addColumn('reviewedBy', 'text')
+        .addColumn('reviewedAt', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0060_verified_token_requests_org_index',
+    up: (db) =>
+      db.schema
+        .createIndex('verified_token_requests_org_idx')
+        .ifNotExists()
+        .on('verifiedTokenRequests')
+        .columns(['orgId', 'createdAt']),
+  },
+  {
+    name: '0061_verified_token_requests_pending_unique',
+    // Raw SQL: a partial unique index (snake_case; the CamelCase plugin does
+    // not map raw statements). At most one live pending request per
+    // (chain, address) globally; addresses are stored lowercase.
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE UNIQUE INDEX IF NOT EXISTS verified_token_requests_pending_unique ON verified_token_requests (chain_id, address) WHERE status = 'pending'`,
+      ),
+  },
+  {
+    name: '0062_verified_token_requests_status_index',
+    up: (db) =>
+      db.schema
+        .createIndex('verified_token_requests_status_idx')
+        .ifNotExists()
+        .on('verifiedTokenRequests')
+        .columns(['status', 'createdAt']),
+  },
+  {
+    name: '0063_verified_token_requests_logo',
+    up: (db) => raw(db, sql`ALTER TABLE verified_token_requests ADD COLUMN IF NOT EXISTS logo text`), // prettier-ignore
+  },
+  {
+    name: '0064_invitations_grants_early_access',
+    up: (db) => raw(db, sql`ALTER TABLE invitations ADD COLUMN IF NOT EXISTS grants_early_access boolean NOT NULL DEFAULT false`), // prettier-ignore
+  },
+  {
+    name: '0065_invitations_grants_early_access_backfill',
+    // Pre-gate invitations came from trusted-era users; the fixed cutoff keeps
+    // re-runs (test DBs replay every migration) from flipping newer rows.
+    up: (db) => raw(db, sql`UPDATE invitations SET grants_early_access = true WHERE created_at < '2026-07-20T00:00:00.000Z'`), // prettier-ignore
+  },
+  {
+    name: '0066_early_access',
+    up: (db) =>
+      db.schema
+        .createTable('earlyAccess')
+        .ifNotExists()
+        .addColumn('entry', 'text', (c) => c.primaryKey())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('createdBy', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0067_invitations_grants_early_access_cutover',
+    // Every invitation present at deployment came from a trusted-era user.
+    up: (db) => raw(db, sql`UPDATE invitations SET grants_early_access = true`),
+  },
+  {
+    name: '0068_invitations_grants_early_access_legacy_default',
+    // Old workers omit this column during deploy; new writes set it explicitly.
+    up: (db) => raw(db, sql`ALTER TABLE invitations ALTER COLUMN grants_early_access SET DEFAULT true`), // prettier-ignore
+  },
+  {
+    name: '0069_invite_links_allowed_email_domains',
+    up: (db) => raw(db, sql`ALTER TABLE invite_links ADD COLUMN IF NOT EXISTS allowed_email_domains jsonb`), // prettier-ignore
+  },
+  {
+    name: '0070_enabled_billing_sources',
+    up: (db) =>
+      db.schema
+        .createTable('enabledBillingSources')
+        .ifNotExists()
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('createdBy', 'text', (c) => c.notNull())
+        .addColumn('orgId', 'text', (c) => c.notNull())
+        .addColumn('source', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('enabled_billing_sources_pkey', ['orgId', 'source']),
+  },
+  {
+    name: '0071_enabled_billing_sources_stripe_backfill',
+    up: (db) => raw(db, sql`INSERT INTO enabled_billing_sources (created_at, created_by, org_id, source) SELECT min(created_at), 'migration', org_id, 'stripe' FROM stripe_customers GROUP BY org_id ON CONFLICT DO NOTHING`), // prettier-ignore
+  },
+  {
+    name: '0072_enabled_billing_sources_stripe_catch_up',
+    up: (db) => raw(db, sql`INSERT INTO enabled_billing_sources (created_at, created_by, org_id, source) SELECT min(created_at), 'migration', org_id, 'stripe' FROM stripe_customers GROUP BY org_id ON CONFLICT DO NOTHING`), // prettier-ignore
+  },
+  {
+    name: '0073_enabled_billing_sources_early_access_backfill',
+    up: (db) => raw(db, sql`INSERT INTO enabled_billing_sources (created_at, created_by, org_id, source) SELECT organizations.created_at, 'migration', organizations.id, 'stripe' FROM organizations INNER JOIN users ON users.id = organizations.user_id WHERE users.email IS NOT NULL AND EXISTS (SELECT 1 FROM early_access WHERE early_access.entry IN (lower(btrim(users.email)), regexp_replace(lower(btrim(users.email)), '^.*@', ''))) ON CONFLICT DO NOTHING`), // prettier-ignore
+  },
+  {
+    name: '0074_invitations_early_access_default',
+    up: (db) => raw(db, sql`ALTER TABLE invitations ALTER COLUMN grants_early_access SET DEFAULT false`), // prettier-ignore
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -52,6 +52,35 @@ export const BillingSettings = z.object({
 /** Columns of the `billing_settings` table. */
 export type BillingSettings = z.output<typeof BillingSettings>
 
+/** An early-access allowlist entry: a lowercase domain or exact email. */
+export const EarlyAccessEntry = z.object({
+  createdAt: z.string().check(z.describe('When the entry was added (ISO 8601).')),
+  createdBy: z
+    .string()
+    .check(z.describe('Admin email that added the entry, or `migration` for seeded rows.')),
+  entry: z
+    .string()
+    .check(z.describe('Lowercase domain or exact email (contains `@`) granted early access.')),
+})
+
+/** Columns of the `early_access` table. */
+export type EarlyAccessEntry = z.output<typeof EarlyAccessEntry>
+
+/** One billing-source type enabled for an organization. */
+export const EnabledBillingSource = z.object({
+  createdAt: z.string().check(z.describe('When the billing source was enabled (ISO 8601).')),
+  createdBy: z
+    .string()
+    .check(z.describe('Identity that enabled the source, or `migration` for backfilled rows.')),
+  orgId: z.string().check(z.describe('Organization id (`org_…`) this source is enabled for.')),
+  source: z
+    .enum(['stripe', 'tempo'])
+    .check(z.describe('Enabled billing-source type; `stripe` or `tempo`.')),
+})
+
+/** Columns of the `enabled_billing_sources` table. */
+export type EnabledBillingSource = z.output<typeof EnabledBillingSource>
+
 /** A pending, expiring offer of organization membership. */
 export const Invitation = z.object({
   acceptedAt: z
@@ -62,6 +91,9 @@ export const Invitation = z.object({
     .string()
     .check(z.describe('Invitee email (stored lowercase); matched against verified emails.')),
   expiresAt: z.string().check(z.describe('When the invitation expires (ISO 8601).')),
+  grantsEarlyAccess: z
+    .boolean()
+    .check(z.describe("Whether the invitation grants early access; stamped from the inviter's own access at creation.")), // prettier-ignore
   id: z
     .string()
     .check(
@@ -83,6 +115,9 @@ export type Invitation = z.output<typeof Invitation>
 
 /** A reusable bearer link granting organization membership. */
 export const InviteLink = z.object({
+  allowedEmailDomains: z
+    .nullable(z.readonly(z.array(z.string())))
+    .check(z.describe('Lowercase email domains allowed to redeem, or null for unrestricted.')),
   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.')),
@@ -363,6 +398,39 @@ export const VerifiedTokenList = z.object({
 /** Columns of the `verified_token_lists` table. */
 export type VerifiedTokenList = z.output<typeof VerifiedTokenList>
 
+/**
+ * An organization's request to add a token to the curated verified list.
+ * Addresses are stored lowercase; a partial unique index allows at most one
+ * pending request per (chain, address) globally.
+ */
+export const VerifiedTokenRequest = z.object({
+  address: z.string().check(z.describe('Requested TIP-20 token contract address (lowercase).')),
+  chainId: z.number().check(z.int(), z.describe('Chain the token belongs to.')),
+  createdAt: z.string().check(z.describe('When the request was created (ISO 8601).')),
+  currency: z.string().check(z.describe('Display currency, e.g. `USD`.')),
+  decimals: z.number().check(z.int(), z.describe('Decimal precision.')),
+  id: z.string().check(z.describe('Opaque request id (`vtr_…`).')),
+  logo: z
+    .nullable(z.string())
+    .check(z.describe('Inline SVG logo markup uploaded by the requester, or null.')),
+  logoUri: z.nullable(z.string()).check(z.describe('HTTPS logo URL from chain metadata, or null.')),
+  name: z.string().check(z.describe('Display name.')),
+  note: z.nullable(z.string()).check(z.describe('Requester note to reviewers, or null.')),
+  orgId: z.string().check(z.describe('Requesting organization id (`org_…`).')),
+  requestedBy: z
+    .string()
+    .check(z.describe('User id that submitted the request, or `super_admin`.')),
+  reviewNote: z.nullable(z.string()).check(z.describe('Reviewer note shown on denial, or null.')),
+  reviewedAt: z.nullable(z.string()).check(z.describe('When the request was reviewed, or null.')),
+  reviewedBy: z.nullable(z.string()).check(z.describe('Reviewing admin email, or null.')),
+  status: z.enum(['approved', 'denied', 'pending']).check(z.describe('Review status.')),
+  symbol: z.string().check(z.describe('Ticker symbol.'), z.meta({ examples: ['USDC'] })),
+  updatedAt: z.string().check(z.describe('When the request was last changed (ISO 8601).')),
+})
+
+/** Columns of the `verified_token_requests` table. */
+export type VerifiedTokenRequest = z.output<typeof VerifiedTokenRequest>
+
 /**
  * A webhook subscription. The `Webhooks.Owner` union maps to (`ownerType`,
  * `ownerId`); jsonb object columns round-trip as parsed values. `pollerCursor`

package/src/db/tables/earlyAccess.ts

@@ -0,0 +1,86 @@
+import type { Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `early_access` table, derived from `Schema.EarlyAccessEntry`. */
+export type Table = db_Schema.EarlyAccessEntry
+
+/** A stored early-access allowlist row. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts an allowlist entry (a domain or exact email, normalized lowercase).
+ * Returns the stored record, or `undefined` when the entry already exists.
+ *
+ * @param db - The database.
+ * @param input - The entry to insert.
+ * @returns The stored record, or `undefined` when already present.
+ */
+export function add(db: Db.Db, input: add.Input): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('early_access')
+    .values({
+      createdAt: new Date().toISOString(),
+      createdBy: input.createdBy,
+      entry: input.entry.trim().toLowerCase(),
+    })
+    .onConflict((oc) => oc.column('entry').doNothing())
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace add {
+  /** Fields accepted when inserting an allowlist entry. */
+  type Input = {
+    /** Admin email adding the entry, or `migration` for seeded rows. */
+    createdBy: string
+    /** Domain or exact email to grant early access; normalized lowercase. */
+    entry: string
+  }
+}
+
+/**
+ * Lists all allowlist entries, ordered by entry.
+ *
+ * @param db - The database.
+ * @returns The records.
+ */
+export function list(db: Db.Db): Promise<Record[]> {
+  return db.kysely.selectFrom('early_access').selectAll().orderBy('entry', 'asc').execute()
+}
+
+/**
+ * Removes an allowlist entry.
+ *
+ * @param db - The database.
+ * @param entry - The entry to remove (matched lowercase).
+ * @returns The removed record, or `undefined` when absent.
+ */
+export function remove(db: Db.Db, entry: string): Promise<Record | undefined> {
+  return db.kysely
+    .deleteFrom('early_access')
+    .where('entry', '=', entry.trim().toLowerCase())
+    .returningAll()
+    .executeTakeFirst()
+}
+
+/**
+ * Whether an allowlist entry matches `email`: the exact email or its domain.
+ * Two primary-key lookups via `IN`.
+ *
+ * @param db - The database.
+ * @param email - The email to match (case-insensitive).
+ * @returns Whether an entry matches.
+ */
+export async function matches(db: Db.Db, email: string): Promise<boolean> {
+  const normalized = email.trim().toLowerCase()
+  const domain = normalized.slice(normalized.lastIndexOf('@') + 1)
+  const row = await db.kysely
+    .selectFrom('early_access')
+    .select('entry')
+    .where('entry', 'in', [normalized, domain])
+    .limit(1)
+    .executeTakeFirst()
+  return row !== undefined
+}