tapimo 0.5.2 → 0.6.0

package/src/apps/data/routes/webhooks.ts

@@ -21,7 +21,7 @@ import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
 
-/** Default cap on active subscriptions per owner, overridable via `webhook.maxPerOwner`. */
+/** Default cap on live subscriptions per owner, overridable via `webhook.maxPerOwner`. */
 const defaultMaxPerOwner = 100
 
 /**
@@ -1317,10 +1317,13 @@ export function webhooks(options: webhooks.Options = {}) {
           responses: OpenApi.responses({
             errors: {
               400: {
-                codes: ['chain_id_unsupported'],
-                description: 'Webhook subscriptions do not support Zone chains.',
+                codes: ['body_invalid', 'chain_id_unsupported', 'filters_invalid', 'url_invalid'],
+                description: 'The request, destination, filters, or chain are invalid.',
+              },
+              403: {
+                codes: ['limit_exceeded'],
+                description: 'You have reached the webhook subscription limit.',
               },
-              403: 'You have reached the webhook subscription limit.',
             },
             success: {
               description:
@@ -1347,12 +1350,9 @@ export function webhooks(options: webhooks.Options = {}) {
 
           const body = c.req.valid('json')
           const chainId = body.chainId ?? c.get('chainId')
-          if (c.get('zones').has(chainId))
-            return Response.error(c, {
-              code: 'chain_id_unsupported',
-              message: 'Webhook subscriptions do not support Zone chains.',
-              status: 400,
-            })
+          const supportedChainIds = new Set(webhook.supportedChainIds)
+          if (!supportedChainIds.has(chainId))
+            return Response.unsupportedChainId(c, chainId, supportedChainIds)
 
           try {
             const subscription = await Webhooks.createSubscription(
@@ -1373,7 +1373,7 @@ export function webhooks(options: webhooks.Options = {}) {
               200,
             )
           } catch (cause) {
-            return mutationError(c, cause)
+            return createMutationError(c, cause)
           }
         },
       )
@@ -1747,6 +1747,16 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'updateWebhook',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: [
+                  'body_invalid',
+                  'destination_transition_invalid',
+                  'filters_invalid',
+                  'param_invalid',
+                  'url_invalid',
+                ],
+                description: 'The update, destination, or filters are invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
                 codes: ['webhook_not_found'],
@@ -1798,7 +1808,7 @@ export function webhooks(options: webhooks.Options = {}) {
               200,
             )
           } catch (cause) {
-            return mutationError(c, cause)
+            return updateMutationError(c, cause)
           }
         },
       )
@@ -1987,13 +1997,14 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
       let accepted: readonly [number, number] | undefined
       let failed = false
       for (const item of page.items) {
-        // Enrich `token:transfer` rows with best-effort token metadata so
-        // downstream destinations (Slack human amounts, richer `url`/`betterstack`
-        // payloads) can render `amount` in token units. Non-fatal on failure.
+        // Token metadata is best-effort for webhooks: transfers use it for display,
+        // while transactions expose fee-token references without blocking delivery.
         const data =
           eventType === 'token:transfer'
             ? await withTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
-            : item.data
+            : eventType === 'transaction:included'
+              ? await withFeeTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
+              : item.data
         const envelope = Webhooks.buildEnvelope({
           blockNumber: item.cursor[0],
           createdAt: now(),
@@ -2106,27 +2117,45 @@ async function withTokenMetadata(
   const address = (data as Record<string, unknown>)['address']
   if (typeof address !== 'string') return data
   const token = await resolveTokenMetadata(address, deps)
-  return token ? { ...(data as Record<string, unknown>), token } : data
+  return token
+    ? {
+        ...(data as Record<string, unknown>),
+        token: { decimals: token.decimals, symbol: token.symbol },
+      }
+    : data
+}
+
+/** Core RPC metadata needed by a humanized token reference. */
+type TokenMetadata = {
+  currency: string
+  decimals: number
+  name: string
+  symbol: string
 }
 
 /**
- * Resolves a token's `{ symbol, decimals }` via `token.getMetadata`, memoized per
+ * Resolves core token metadata via `token.getMetadata`, memoized per
  * `(chainId, address)` with a short TTL so a busy transfer stream shares one RPC
- * lookup per token. Returns `undefined` on any failure — metadata is a rendering
+ * lookup per token. Returns `undefined` on any failure; metadata is a rendering
  * nicety, never a delivery blocker.
  */
 async function resolveTokenMetadata(
   address: string,
   deps: { cache: Store.Store; chainId: number; client: Viem.getClient.ReturnType },
-): Promise<{ decimals: number; symbol: string } | undefined> {
+): Promise<TokenMetadata | undefined> {
   try {
     return await Store.memoize(
       async () => {
         const meta = await deps.client.token.getMetadata({ token: address as `0x${string}` })
-        return { decimals: meta.decimals, symbol: meta.symbol }
+        return {
+          currency: meta.currency,
+          decimals: meta.decimals,
+          name: meta.name,
+          symbol: meta.symbol,
+        }
       },
       {
-        key: `webhook:token-meta:v1:${deps.chainId}:${address}`,
+        key: `webhook:token-meta:v2:${deps.chainId}:${address}`,
         store: deps.cache,
         ttl: Ttl.minutes(5),
       },
@@ -2137,6 +2166,69 @@ async function resolveTokenMetadata(
   }
 }
 
+/** Returns the address from an unenriched or enriched fee-token value. */
+function feeTokenAddress(value: unknown) {
+  if (typeof value === 'string') return value
+  if (typeof value !== 'object' || value === null) return undefined
+  const address = (value as Record<string, unknown>)['address']
+  return typeof address === 'string' ? address : undefined
+}
+
+/** Replaces an address-valued fee token with its resolved reference, or omits it on failure. */
+function withResolvedFeeToken(data: Record<string, unknown>, metadata: Map<string, TokenMetadata>) {
+  const address = feeTokenAddress(data['feeToken'])
+  if (!address) return data
+  const result = { ...data }
+  delete result['feeToken']
+  const token = metadata.get(address.toLowerCase())
+  if (token) result['feeToken'] = { address, ...token }
+  return result
+}
+
+/** Adds best-effort fee-token references to a transaction and its embedded receipt. */
+async function withFeeTokenMetadata(
+  data: unknown,
+  deps: {
+    cache: Store.Store
+    chainId: number
+    client: Viem.getClient.ReturnType
+  },
+): Promise<unknown> {
+  if (typeof data !== 'object' || data === null) return data
+  const transaction = data as Record<string, unknown>
+  const meta = transaction['meta']
+  const receipt =
+    typeof meta === 'object' && meta !== null
+      ? (meta as Record<string, unknown>)['receipt']
+      : undefined
+  const addresses = new Set<string>()
+  const transactionAddress = feeTokenAddress(transaction['feeToken'])
+  if (transactionAddress) addresses.add(transactionAddress.toLowerCase())
+  if (typeof receipt === 'object' && receipt !== null) {
+    const receiptAddress = feeTokenAddress((receipt as Record<string, unknown>)['feeToken'])
+    if (receiptAddress) addresses.add(receiptAddress.toLowerCase())
+  }
+  if (addresses.size === 0) return data
+
+  const resolved = await Promise.all(
+    [...addresses].map(
+      async (address) => [address, await resolveTokenMetadata(address, deps)] as const,
+    ),
+  )
+  const metadata = new Map(
+    resolved.filter((entry): entry is readonly [string, TokenMetadata] => entry[1] !== undefined),
+  )
+  const result = withResolvedFeeToken(transaction, metadata)
+  if (typeof receipt !== 'object' || receipt === null) return result
+  return {
+    ...result,
+    meta: {
+      ...(meta as Record<string, unknown>),
+      receipt: withResolvedFeeToken(receipt as Record<string, unknown>, metadata),
+    },
+  }
+}
+
 /** Returns the live RPC head block number for the chain. */
 export async function getRpcHead(client: Viem.getClient.ReturnType): Promise<number> {
   return Number(await client.getBlockNumber())
@@ -2883,8 +2975,8 @@ const txFields = {
  * Scans included transactions over the confirmed window. Each block is fetched
  * with full transactions via `eth_getBlockByNumber(n, true)`; receipts are
  * fetched lazily (only when a `status`/`gasUsed`/`feePayer` filter needs them).
- * The delivered payload reuses `Transactions.humanizeTransaction`, so it is
- * byte-identical to the read endpoint.
+ * The delivered payload starts from `Transactions.humanizeTransaction`; the
+ * poller then resolves its fee-token references.
  */
 async function scanTxs(options: {
   cache: ChainCache
@@ -2921,13 +3013,19 @@ async function scanTxs(options: {
       if (!matchesTx(tx, f, includeCalls, receipt, timestamp, n)) continue
       const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx)
       if (!parsed.success) continue
-      let data = Transactions.humanizeTransaction(parsed.data)
+      let data: Record<string, unknown> = Transactions.humanizeTransaction(parsed.data)
       // Embed the humanized receipt under `meta.receipt`, matching the read
       // endpoint's `include=receipt` shape so `data` stays a valid envelope.
       if (includeReceipt && receipt) {
         const r = Receipts.schema.Rpc.Receipt.safeParse(receipt)
         if (r.success)
-          data = { ...data, meta: { ...data.meta, receipt: Receipts.humanizeReceipt(r.data) } }
+          data = {
+            ...data,
+            meta: {
+              ...(data['meta'] as Record<string, unknown>),
+              receipt: Receipts.humanizeReceipt(r.data),
+            },
+          }
       }
       items.push({ cursor: [n, index], data })
     }
@@ -3040,7 +3138,7 @@ function redactDestination(destination: WebhookDestination.Destination) {
   return destination
 }
 
-function mutationError(c: Context<App.Environment>, cause: unknown) {
+function createMutationError(c: Context<App.Environment>, cause: unknown) {
   if (cause instanceof Webhooks.InvalidUrlError)
     return Response.error(c, { code: 'url_invalid', message: cause.message, status: 400 })
   if (cause instanceof Webhooks.InvalidFilterError)
@@ -3055,6 +3153,25 @@ function mutationError(c: Context<App.Environment>, cause: unknown) {
   return Response.upstream(c, cause)
 }
 
+function updateMutationError(c: Context<App.Environment>, cause: unknown) {
+  if (cause instanceof Webhooks.InvalidDestinationTransitionError)
+    return Response.error(c, {
+      code: 'destination_transition_invalid',
+      message: cause.message,
+      status: 400,
+    })
+  if (cause instanceof Webhooks.InvalidUrlError)
+    return Response.error(c, { code: 'url_invalid', message: cause.message, status: 400 })
+  if (cause instanceof Webhooks.InvalidFilterError)
+    return Response.error(c, {
+      code: 'filters_invalid',
+      details: cause.details,
+      message: cause.message,
+      status: 400,
+    })
+  return Response.upstream(c, cause)
+}
+
 function notFound(c: Context<App.Environment>) {
   return Response.error(c, {
     code: 'webhook_not_found',

package/src/apps/index.ts

@@ -1,4 +1,4 @@
-export { data, FundingQuoteProviders } from './data/index.js'
+export { data, FundingQuoteProviders, FxOracle } from './data/index.js'
 export { management } from './management/index.js'
 export { mcp } from './mcp.js'
 export { relay } from './relay/index.js'

package/src/apps/management/App.ts

@@ -6,6 +6,7 @@ import * as Metadata from '../metadata.js'
 
 import { apiKeys } from './routes/api-keys.js'
 import { billing } from './routes/billing.js'
+import { faucet } from './routes/faucet.js'
 import { invitations } from './routes/invitations.js'
 import { inviteLinks } from './routes/invite-links.js'
 import { me } from './routes/me.js'
@@ -14,6 +15,8 @@ import { orgs } from './routes/orgs.js'
 import { projects } from './routes/projects.js'
 import { scopes } from './routes/scopes.js'
 import { usage } from './routes/usage.js'
+import { verifiedTokenRequests } from './routes/verified-token-requests.js'
+import { webhooks } from './routes/webhooks.js'
 
 /**
  * Minimal transactional email sender. Cloudflare deployments wrap the Email
@@ -105,6 +108,7 @@ export function management(options: management.Options = {}) {
     })
     .route('/', apiKeys({ enabled: options.apiKeys !== false }))
     .route('/', billing())
+    .route('/', faucet())
     .route('/', invitations())
     .route('/', inviteLinks())
     .route('/', me())
@@ -113,6 +117,8 @@ export function management(options: management.Options = {}) {
     .route('/', projects())
     .route('/', scopes())
     .route('/', usage())
+    .route('/', verifiedTokenRequests())
+    .route('/', webhooks({ webhook: options.webhook === false ? undefined : options.webhook }))
   return Metadata.attach(app, openapi)
 }
 
@@ -125,6 +131,8 @@ export declare namespace management {
     billing?: Billing | undefined
     /** Transactional email sender for management emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
     email?: Email | undefined
+    /** Webhook capability shared with the data group and host poller; omit or pass false to disable management. */
+    webhook?: App.Webhook | false | undefined
   }
 }
 
@@ -145,6 +153,7 @@ const openapi = {
   tags: [
     { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
     { name: 'Billing', description: 'Organization billing backed by Stripe.' },
+    { name: 'Faucet', description: 'Test token funding for Tempo testnet accounts.' },
     { name: 'Invitations', description: 'Pending organization invitations.' },
     { name: 'Invite Links', description: 'Reusable organization invite links.' },
     { name: 'Members', description: 'Organization team membership.' },
@@ -152,6 +161,8 @@ const openapi = {
     { name: 'Projects', description: 'Application workspaces within an organization.' },
     { name: 'Usage', description: 'Request and sponsorship usage for organizations.' },
     { name: 'Users', description: 'Users on the Tempo Platform.' },
+    { name: 'Verified Token Requests', description: 'Organization requests to add tokens to the curated verified list.' }, // prettier-ignore
+    { name: 'Webhooks', description: 'Organization webhook subscriptions.' },
   ],
   'x-tagGroups': [
     {
@@ -167,6 +178,8 @@ const openapi = {
         'Projects',
         'Usage',
         'Users',
+        'Verified Token Requests',
+        'Webhooks',
       ],
     },
   ],

package/src/apps/management/routes/api-keys.test.ts

@@ -5,7 +5,9 @@ import * as Auth from '../../../internal/Auth.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Scope from '../../../Scope.js'
 import * as TestApp from '../../../../test/App.js'
+import * as EarlyAccess from '../../../db/tables/earlyAccess.js'
 import * as Memberships from '../../../db/tables/memberships.js'
+import * as Users from '../../../db/tables/users.js'
 import * as Keys from './api-keys.js'
 import * as Me from './me.js'
 import * as Orgs from './orgs.js'
@@ -43,6 +45,7 @@ function createApp(
     db?: ReturnType<typeof TestApp.database>
     kv?: { store: State }
     scopes?: readonly Scope.Entry[]
+    tmp_earlyAccess?: boolean
   } = {},
 ) {
   return TestApp.create({
@@ -51,6 +54,7 @@ function createApp(
     ...(options.kv ? { kv: options.kv } : {}),
     ...(options.scopes ? { scopes: options.scopes } : {}),
     session: { wallet: { origin } },
+    ...(options.tmp_earlyAccess === undefined ? {} : { tmp_earlyAccess: options.tmp_earlyAccess }),
   })
 }
 
@@ -671,3 +675,86 @@ describe('keys', () => {
     expect(response.status).toBe(403)
   })
 })
+
+describe('early access', () => {
+  test('rejects mints from non-early-access sessions', async () => {
+    const app = createApp({ tmp_earlyAccess: true })
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const denied = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['data:read'] }),
+    )
+    expect(denied.status).toBe(403)
+    const { requestId, ...body } = (await denied.json()) as { requestId?: string }
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "early_access_required",
+          "message": "Requires early access. Ask a teammate with access to invite you by email, or contact Tempo.",
+        },
+      }
+    `)
+  })
+
+  test('the gate precedes membership resolution', async () => {
+    // The gate depends only on the caller, so it leaks nothing about the
+    // project; early-access strangers still get the membership 404.
+    const db = TestApp.database()
+    const app = createApp({ db, tmp_earlyAccess: true })
+    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+
+    const other = await session(app)
+    const gated = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', other, { scopes: ['data:read'] }),
+    )
+    expect(gated.status).toBe(403)
+    expect(((await gated.json()) as { error: { code: string } }).error.code).toBe('early_access_required') // prettier-ignore
+
+    const granted = await session(app)
+    const me = await app.request('/v1/me', { headers: { cookie: granted } })
+    const { id: userId } = (await me.json()) as { id: string }
+    await Users.setEmail(db, userId, 'stranger@example.org')
+    const denied = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', granted, { scopes: ['data:read'] }),
+    )
+    expect(denied.status).toBe(404)
+  })
+
+  test('lets early-access sessions mint', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db, tmp_earlyAccess: true })
+    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
+    const cookie = await session(app)
+    const user = await TestApp.json(
+      await app.request('/v1/me', { headers: { cookie } }),
+      Me.schema.User,
+    )
+    await Users.setEmail(db, user.id, 'dev@example.org')
+    const { org, project } = await fixture(app, cookie)
+
+    const minted = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['data:read'] }),
+    )
+    expect(minted.status).toBe(200)
+  })
+
+  test('lets the super admin mint', async () => {
+    const app = createApp({ tmp_earlyAccess: true })
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const minted = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      superAdminJson('POST', { scopes: ['data:read'] }),
+    )
+    expect(minted.status).toBe(200)
+  })
+})

package/src/apps/management/routes/api-keys.ts

@@ -225,7 +225,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
   return new Hono<App.Environment>()
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys',
-      Auth.policy({ session: true }),
+      Auth.policy({ session: true, tmp_earlyAccess: true }),
       Auth.ensureOrg({ role: 'admin' }),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.Params, {
@@ -243,8 +243,8 @@ export function apiKeys(options: apiKeys.Options = {}) {
         responses: OpenApi.responses({
           errors: {
             403: {
-              codes: ['scope_not_issuable'],
-              description: 'The requested scopes are not issuable.',
+              codes: ['scope_not_issuable', 'early_access_required'],
+              description: 'The requested scopes are not issuable, or the caller lacks early access.', // prettier-ignore
             },
             404: 'No accessible project was found for this id.',
           },
@@ -259,6 +259,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
       async (c) => {
         if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (Auth.tmp_narrowEarlyAccess) return Auth.tmp_ensureEarlyAccessError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',

package/src/apps/management/routes/billing.test.ts

@@ -2,11 +2,14 @@ import { nanoid } from 'nanoid'
 import Stripe from 'stripe'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
+import * as ApiKeys from '../../../ApiKeys.js'
 import * as TestApp from '../../../../test/App.js'
 import * as TestStripe from '../../../../test/Stripe.js'
+import * as EarlyAccess from '../../../db/tables/earlyAccess.js'
 import * as Memberships from '../../../db/tables/memberships.js'
 import * as SponsoredTransactions from '../../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../../db/tables/stripeCustomers.js'
+import * as Users from '../../../db/tables/users.js'
 import * as Viem from '../../../internal/Viem.js'
 import * as core_Billing from '../Billing.js'
 import type * as App from '../../../App.js'
@@ -59,14 +62,21 @@ function billingWithSandbox(): App.Billing {
 }
 
 function createApp(
-  options: { billing?: App.Billing | undefined; db?: TestApp.create.Options['db'] } = {},
+  options: {
+    billing?: App.Billing | undefined
+    db?: TestApp.create.Options['db']
+    kv?: { store: ReturnType<typeof TestApp.kvStore> }
+    tmp_earlyAccess?: boolean
+  } = {},
 ) {
   // prettier-ignore
   return TestApp.create({
     auth: { superAdmin: { secret } },
     billing: options.billing ?? billing(),
     db: options.db ?? TestApp.database(),
+    ...(options.kv ? { kv: options.kv } : {}),
     session: { wallet: { origin } },
+    ...(options.tmp_earlyAccess === undefined ? {} : { tmp_earlyAccess: options.tmp_earlyAccess }),
   })
 }
 
@@ -356,6 +366,107 @@ describe('POST /orgs/:orgId/billing/stripe/checkout', () => {
   })
 })
 
+describe('early access', () => {
+  test('behavior: checkout requires early access', async () => {
+    const app = createApp({ tmp_earlyAccess: true })
+    const { cookie, orgId } = await seeded(app)
+    const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
+    expect(response.status).toBe(403)
+    const { requestId, ...body } = (await response.json()) as { requestId?: string }
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "early_access_required",
+          "message": "Requires early access. Ask a teammate with access to invite you by email, or contact Tempo.",
+        },
+      }
+    `)
+  })
+
+  test('behavior: the gate precedes membership resolution', async () => {
+    // The gate depends only on the caller, so it leaks nothing about the org;
+    // early-access strangers still get the membership 404.
+    const db = TestApp.database()
+    const app = createApp({ db, tmp_earlyAccess: true })
+    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
+    const { orgId } = await seeded(app)
+
+    const other = await session(app)
+    const gated = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(other))
+    expect(gated.status).toBe(403)
+    expect(((await gated.json()) as { error: { code: string } }).error.code).toBe('early_access_required') // prettier-ignore
+
+    const granted = await session(app)
+    const me = await app.request('/v1/me', { headers: { cookie: granted } })
+    const { id: userId } = (await me.json()) as { id: string }
+    await Users.setEmail(db, userId, 'stranger@example.org')
+    expect(
+      (await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(granted))).status,
+    ).toBe(404)
+  })
+
+  test('behavior: the gate precedes the owner-role check', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db, tmp_earlyAccess: true })
+    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
+    const { orgId } = await seeded(app)
+    const member = await session(app)
+    const me = await app.request('/v1/me', { headers: { cookie: member } })
+    const { id: userId } = (await me.json()) as { id: string }
+    await Memberships.create(db, { orgId, role: 'member', userId })
+
+    const gated = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(member))
+    expect(gated.status).toBe(403)
+    expect(((await gated.json()) as { error: { code: string } }).error.code).toBe('early_access_required') // prettier-ignore
+
+    // Early-access members still fail the owner-role check.
+    await Users.setEmail(db, userId, 'member@example.org')
+    const write = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(member))
+    expect(write.status).toBe(403)
+    expect(((await write.json()) as { error: { code: string } }).error.code).toBe('forbidden')
+  })
+
+  test('behavior: early-access owners pass the gate', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db, tmp_earlyAccess: true })
+    await EarlyAccess.add(db, { createdBy: 'test', entry: 'example.org' })
+    const { cookie, orgId } = await seeded(app)
+    const me = await app.request('/v1/me', { headers: { cookie } })
+    const { id: userId } = (await me.json()) as { id: string }
+    await Users.setEmail(db, userId, 'dev@example.org')
+
+    // The unreachable Stripe upstream (502) proves the request passed the gate.
+    const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, post(cookie))
+    expect(response.status).toBe(502)
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('upstream_error') // prettier-ignore
+  })
+
+  test('behavior: management keys pass the gate', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ tmp_earlyAccess: true, kv: { store } })
+    const { orgId } = await seeded(app)
+    const { token } = await ApiKeys.mint(store, { orgId, scopes: ['management:write'] })
+
+    const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, {
+      headers: { 'tempo-api-key': token },
+      method: 'POST',
+    })
+    expect(response.status).toBe(502)
+  })
+
+  test('behavior: the super admin passes the gate', async () => {
+    const app = createApp({ tmp_earlyAccess: true })
+    const { orgId } = await seeded(app)
+
+    const response = await app.request(`/v1/orgs/${orgId}/billing/stripe/checkout`, {
+      ...as(secret),
+      method: 'POST',
+    })
+    expect(response.status).toBe(502)
+  })
+})
+
 describe('POST /orgs/:orgId/billing/stripe/manage', () => {
   test('behavior: 404 before any billing exists', async () => {
     const app = createApp()

package/src/apps/management/routes/billing.ts

@@ -380,7 +380,7 @@ export function billing() {
     )
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/checkout',
-      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true, tmp_earlyAccess: true }), // prettier-ignore
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -394,7 +394,10 @@ export function billing() {
         operationId: 'createStripeCheckout',
         responses: OpenApi.responses({
           errors: {
-            403: 'Requires the owner role.',
+            403: {
+              codes: ['api_key_forbidden', 'early_access_required', 'forbidden'],
+              description: 'Requires the owner role and early access.',
+            },
             404: 'No accessible organization was found for this id.',
             501: 'Billing is not configured on this deployment.',
           },
@@ -409,6 +412,8 @@ export function billing() {
       async (c) => {
         if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (Auth.narrowOrgRole) return Auth.ensureOrgRoleError(c)
+        if (Auth.tmp_narrowEarlyAccess) return Auth.tmp_ensureEarlyAccessError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',