tapimo 0.15.0 → 0.18.0

package/src/cli/ApiKeys.test.ts

@@ -0,0 +1,265 @@
+import * as TestApp from '../../test/App.js'
+import * as TestCli from '../../test/cli.js'
+import * as core_ApiKeys from '../ApiKeys.js'
+import * as Client from '../Client.js'
+import * as Memberships from '../db/tables/memberships.js'
+import * as CliAuth from '../internal/CliAuth.js'
+import * as Store from '../internal/Store.js'
+import * as ApiKeys from './ApiKeys.js'
+
+describe('resolve', () => {
+  test('infers a project key, caches it privately, and expires it with the session', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context)
+    const owner = await organization(context.app, cookie)
+    const request = auth(context)
+    const [credential, concurrent, separate] = await Promise.all([
+      ApiKeys.resolve(request, { scopes: ['routes:read'] }),
+      ApiKeys.resolve(auth(context), { scopes: ['routes:read'] }),
+      ApiKeys.resolve(request, { scopes: ['routes:read'] }),
+    ])
+    expect(typeof credential).toBe('string')
+    expect(concurrent).toBe(credential)
+    expect(separate).toBe(credential)
+    expect(await ApiKeys.resolve(auth(context), { scopes: ['routes:read'] })).toBe(credential)
+    const session = (await context.credentials.get(TestCli.origin))!
+    expect(session.apiKeys).toHaveLength(1)
+    expect(session.apiKeys![0]).toMatchObject({
+      ...owner,
+      environment: 'production',
+      expiresAt: session.expiresAt,
+      scopes: ['routes:read'],
+    })
+    const listed = await context.app.request(
+      `/v1/orgs/${owner.orgId}/projects/${owner.projectId}/api-keys?include=`,
+      { headers: { cookie } },
+    )
+    const { data } = await listed.json()
+    expect(data[0].expiresAt).toBe(session.expiresAt)
+    const { code, lines } = await TestCli.serve(context.cli, [
+      'v1',
+      'routes',
+      'transfers',
+      'get',
+      '--format',
+      'json',
+    ])
+    expect(code).toBe(0)
+    expect(JSON.parse(lines.join('\n'))).toMatchObject({ data: [] })
+    await context.credentials.set(TestCli.origin, {
+      ...session,
+      apiKeys: session.apiKeys!.map((key) => ({ ...key, expiresAt: new Date(0).toISOString() })),
+    })
+    expect(await ApiKeys.resolve(auth(context), { scopes: ['routes:read'] })).not.toBe(credential)
+  })
+
+  test('requires fresh consent for legacy local and server sessions', async () => {
+    const store = Store.memory()
+    const context = await TestCli.create({ app: TestApp.create({ kv: { store } }) })
+    const { cookie } = await TestCli.login(context)
+    const owner = await organization(context.app, cookie)
+    const current = (await context.credentials.get(TestCli.origin))!
+    const { scopes: _scopes, ...legacy } = current
+    await context.credentials.set(TestCli.origin, legacy)
+    const denied = await ApiKeys.resolve(auth(context), { scopes: ['data:read'] })
+    expect(denied instanceof Response && (await denied.json())).toMatchObject({
+      error: { code: 'scope_not_approved' },
+    })
+    const { token } = await CliAuth.mint(store, { client: {}, userId: current.userId })
+    expect(
+      (
+        await context.app.request('/v1/me', {
+          headers: { authorization: `Bearer ${token}` },
+        })
+      ).status,
+    ).toBe(200)
+    const response = await context.app.request(
+      `/v1/orgs/${owner.orgId}/projects/${owner.projectId}/api-keys`,
+      {
+        body: JSON.stringify({ scopes: ['data:read'] }),
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+        method: 'POST',
+      },
+    )
+    expect(response.status).toBe(403)
+    expect(await response.json()).toMatchObject({ error: { code: 'scope_not_issuable' } })
+  })
+
+  test('requires owner membership to derive or rotate Routes write keys', async () => {
+    const db = TestApp.database()
+    const store = Store.memory()
+    const context = await TestCli.create({ app: TestApp.create({ db, kv: { store } }) })
+    const ownerCookie = await TestCli.consoleSession(context.app)
+    const owner = await organization(context.app, ownerCookie)
+    await TestCli.login(context)
+    const session = (await context.credentials.get(TestCli.origin))!
+    await Memberships.create(db, { orgId: owner.orgId, role: 'admin', userId: session.userId })
+    const { record } = await core_ApiKeys.mintBounded(db, store, {
+      ...owner,
+      environment: 'production',
+      scopes: ['routes:read', 'routes:write'],
+    })
+    const denied = await ApiKeys.resolve(auth(context), {
+      ...owner,
+      scopes: ['routes:write'],
+      sourceKeyId: record.id,
+    })
+    expect(denied instanceof Response && denied.status).toBe(403)
+    expect(denied instanceof Response && (await denied.json())).toMatchObject({
+      error: { code: 'scope_not_issuable' },
+    })
+    const rotated = await context.app.request(
+      `/v1/orgs/${owner.orgId}/projects/${owner.projectId}/api-keys/${record.id}/rotate`,
+      { headers: { authorization: `Bearer ${session.token}` }, method: 'POST' },
+    )
+    expect(rotated.status).toBe(403)
+    expect(await rotated.json()).toMatchObject({ error: { code: 'scope_not_issuable' } })
+    expect((await context.credentials.get(TestCli.origin))?.apiKeys).toBeUndefined()
+    expect(await core_ApiKeys.get(store, record.id)).not.toBeNull()
+  })
+
+  test('rejects operations outside approved scopes without minting a key', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context, { scopes: [] })
+    const result = await ApiKeys.resolve(auth(context), { scopes: ['routes:write'] })
+    expect(result instanceof Response && (await result.json())).toMatchObject({
+      error: { code: 'scope_not_approved' },
+    })
+    expect((await context.credentials.get(TestCli.origin))?.apiKeys).toBeUndefined()
+    const owner = await organization(context.app, cookie)
+    const session = (await context.credentials.get(TestCli.origin))!
+    const denied = await context.app.request(
+      `/v1/orgs/${owner.orgId}/projects/${owner.projectId}/api-keys`,
+      {
+        body: JSON.stringify({ scopes: ['data:read'] }),
+        headers: { authorization: `Bearer ${session.token}`, 'content-type': 'application/json' },
+        method: 'POST',
+      },
+    )
+    expect(denied.status).toBe(403)
+    expect(await denied.json()).toMatchObject({ error: { code: 'scope_not_issuable' } })
+  })
+
+  test('requires selection when organization ownership is ambiguous', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context)
+    const owner = await organization(context.app, cookie)
+    await organization(context.app, cookie)
+    const result = await ApiKeys.resolve(auth(context), { scopes: ['routes:read'] })
+    expect(result instanceof Response && (await result.json())).toMatchObject({
+      error: { code: 'organization_required' },
+    })
+    expect((await context.credentials.get(TestCli.origin))?.apiKeys).toBeUndefined()
+    await context.app.request(`/v1/orgs/${owner.orgId}/projects`, {
+      body: JSON.stringify({ name: 'Another project' }),
+      headers: { 'content-type': 'application/json', cookie },
+      method: 'POST',
+    })
+    const ambiguous = await ApiKeys.resolve(auth(context), {
+      orgId: owner.orgId,
+      scopes: ['routes:read'],
+    })
+    expect(ambiguous instanceof Response && (await ambiguous.json())).toMatchObject({
+      error: { code: 'project_required' },
+    })
+    expect(
+      typeof (await ApiKeys.resolve(auth(context), { ...owner, scopes: ['routes:read'] })),
+    ).toBe('string')
+  })
+
+  test.each([{ scopes: ['routes:read', 'routes:write'] }, { scopes: ['*'] }])(
+    'derives Routes writes from approved scopes $scopes without rotating the source',
+    async ({ scopes }) => {
+      const db = TestApp.database()
+      const store = Store.memory()
+      const context = await TestCli.create({ app: TestApp.create({ db, kv: { store } }) })
+      const { cookie } = await TestCli.login(context)
+      const owner = await organization(context.app, cookie)
+      const denied = await ApiKeys.resolve(auth(context), { scopes: ['routes:write'] })
+      expect(denied instanceof Response && (await denied.json())).toMatchObject({
+        error: { code: 'api_key_required' },
+      })
+      const { record } = await core_ApiKeys.mintBounded(db, store, {
+        ...owner,
+        allowedIps: ['203.0.113.7'],
+        environment: 'production',
+        expiresAt: new Date(Date.now() + 60_000).toISOString(),
+        scopes,
+      })
+      expect(typeof (await ApiKeys.resolve(auth(context), { scopes: ['routes:write'] }))).toBe(
+        'string',
+      )
+      const cached = (await context.credentials.get(TestCli.origin))!.apiKeys![0]!
+      const derived = await core_ApiKeys.get(store, cached.id)
+      expect(derived?.expiresAt).toBe(record.expiresAt)
+      expect(derived?.scopes).toEqual(['routes:write', 'routes:read'])
+      expect(derived?.allowedIps).toEqual(record.allowedIps)
+      expect(await core_ApiKeys.get(store, record.id)).not.toBeNull()
+      const first = await ApiKeys.resolve(auth(context), { scopes: ['routes:write'] })
+      expect(first).toBe(cached.token)
+      const second = await core_ApiKeys.mintBounded(db, store, {
+        ...owner,
+        environment: 'production',
+        scopes: ['routes:read', 'routes:write'],
+      })
+      const ambiguous = await ApiKeys.resolve(auth(context), { scopes: ['routes:write'] })
+      expect(ambiguous instanceof Response && (await ambiguous.json())).toMatchObject({
+        error: { code: 'api_key_required' },
+      })
+      expect(
+        await ApiKeys.resolve(auth(context), {
+          scopes: ['routes:write'],
+          sourceKeyId: record.id,
+        }),
+      ).toBe(cached.token)
+      expect((await context.credentials.get(TestCli.origin))?.apiKeys).toHaveLength(1)
+      expect(
+        await ApiKeys.resolve(auth(context), {
+          scopes: ['routes:write'],
+          sourceKeyId: second.record.id,
+        }),
+      ).not.toBe(cached.token)
+      const keys = (await context.credentials.get(TestCli.origin))!.apiKeys!
+      expect(keys).toHaveLength(2)
+      expect(keys[1]?.sourceKeyId).toBe(second.record.id)
+      expect(
+        await ApiKeys.revoke(auth(context), (await context.credentials.get(TestCli.origin))!),
+      ).toBe(true)
+      expect(await core_ApiKeys.get(store, cached.id)).toBeNull()
+      expect(await core_ApiKeys.get(store, keys[1]!.id)).toBeNull()
+      expect(await core_ApiKeys.get(store, record.id)).not.toBeNull()
+    },
+  )
+})
+
+function auth(context: Awaited<ReturnType<typeof TestCli.create>>) {
+  return {
+    api: Client.create({
+      fetch: async (input: Request | string | URL, init?: RequestInit) =>
+        context.app.fetch(new Request(input, init)),
+      url: TestCli.origin,
+    }),
+    apiUrl: new URL(TestCli.origin),
+    credentials: context.credentials,
+    fetch: async (request: Request) => context.app.fetch(request),
+    name: 'tapimo',
+  }
+}
+
+async function organization(app: ReturnType<typeof TestApp.create>, cookie: string) {
+  const headers = { 'content-type': 'application/json', cookie }
+  const created = await app.request('/v1/orgs', {
+    body: JSON.stringify({ name: 'CLI project' }),
+    headers,
+    method: 'POST',
+  })
+  const org = await created.json()
+  const project = await (
+    await app.request(`/v1/orgs/${org.id}/projects`, {
+      body: JSON.stringify({ name: 'CLI' }),
+      headers,
+      method: 'POST',
+    })
+  ).json()
+  return { orgId: org.id as string, projectId: project.id as string }
+}

package/src/cli/ApiKeys.ts

@@ -0,0 +1,189 @@
+import * as Scope from '../Scope.js'
+import type * as Auth from './commands/auth.js'
+import type * as Credentials from './Credentials.js'
+
+const resolutions = new WeakMap<Auth.Context, Promise<unknown>>()
+
+/** Resolves a private, session-bound API key without replacing explicit credentials. */
+export function resolve(context: Auth.Context, options: resolve.Options) {
+  const previous = resolutions.get(context) ?? Promise.resolve()
+  const pending = previous
+    .catch(() => undefined)
+    .then(() =>
+      context.credentials.withLock
+        ? context.credentials.withLock((credentials) =>
+            resolveKey({ ...context, credentials }, options),
+          )
+        : resolveKey(context, options),
+    )
+  resolutions.set(context, pending)
+  return pending.finally(() => {
+    if (resolutions.get(context) === pending) resolutions.delete(context)
+  })
+}
+
+async function resolveKey(context: Auth.Context, options: resolve.Options) {
+  const { api, apiUrl, credentials } = context
+  const session = await credentials.get(apiUrl)
+  if (!session) return undefined
+  const approved = session.scopes
+  if (!approved || !options.scopes.every((scope) => approved.includes(scope)))
+    return failure(
+      'scope_not_approved',
+      'Run login again and enable the required scopes under “Modify auth scopes”.',
+    )
+  const request = { headers: { authorization: `Bearer ${session.token}` } }
+  const me = await api.v1.me.$get(undefined, request)
+  if (me.status !== 200) return me
+  const orgs = await api.v1.orgs.$get(undefined, request)
+  if (orgs.status !== 200) return orgs
+  const organizations = (await orgs.json()).data
+  const orgId = options.orgId ?? (organizations.length === 1 ? organizations[0]!.id : undefined)
+  if (!orgId)
+    return failure(
+      'organization_required',
+      `Set TEMPO_API_ORG to one of: ${describe(organizations)}.`,
+    )
+  const org = api.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']
+  const projects = await org.projects.$get({ param: { orgId } }, request)
+  if (projects.status !== 200) return projects
+  const choices = (await projects.json()).data
+  const projectId = options.projectId ?? (choices.length === 1 ? choices[0]!.id : undefined)
+  if (!projectId)
+    return failure('project_required', `Set TEMPO_API_PROJECT to one of: ${describe(choices)}.`)
+  if (!choices.some(({ id }) => id === projectId))
+    return failure(
+      'project_not_found',
+      'The selected project does not belong to this organization.',
+    )
+  const environment = options.environment ?? 'production'
+  const catalog = await api.v1.scopes.$get({}, request)
+  if (catalog.status !== 200) return catalog
+  const entries = (await catalog.json()).data
+  const selfServe = entries.filter(({ selfServe }) => selfServe).map(({ scope }) => scope)
+  const scopes = [...new Set(options.scopes)]
+  if (
+    scopes.includes('routes:write') &&
+    !scopes.includes('routes:read') &&
+    approved.includes('routes:read')
+  )
+    scopes.push('routes:read')
+  const project = org.projects[':projectId{prj_[A-Za-z0-9_-]+}']
+  const restricted = scopes.filter((scope) => !selfServe.includes(scope))
+  const sourceKeyId = await (async () => {
+    if (restricted.length === 0 && !options.sourceKeyId) return undefined
+    const listed = await project['api-keys'].$get(
+      { param: { orgId, projectId }, query: { environment, include: '' } },
+      request,
+    )
+    if (listed.status !== 200) return listed
+    // Locally inferred credentials are destinations, not additional provisioned source choices.
+    const inferredIds = new Set(session.apiKeys?.map(({ id }) => id))
+    const sources = (await listed.json()).data.filter(
+      (key) =>
+        !inferredIds.has(key.id) &&
+        restricted.every(
+          (scope) => key.scopes.includes(scope) || key.scopes.includes(Scope.wildcard),
+        ),
+    )
+    const source = options.sourceKeyId
+      ? sources.find(({ id }) => id === options.sourceKeyId)
+      : sources.length === 1
+        ? sources[0]
+        : undefined
+    if (!source)
+      return failure(
+        'api_key_required',
+        sources.length === 0
+          ? 'This project needs a Tempo-approved key with the required scopes. Set TEMPO_API_KEY to an approved key, or ask Tempo to provision this project.'
+          : `Set TEMPO_API_SOURCE_KEY to one of: ${sources.map(({ id }) => id).join(', ')}.`,
+      )
+    return source.id
+  })()
+  if (sourceKeyId && typeof sourceKeyId !== 'string') return sourceKeyId
+  // Resolve the live source grant before reusing a key so caching never hides new ambiguity.
+  const cached = session.apiKeys?.find(
+    (key) =>
+      key.orgId === orgId &&
+      key.projectId === projectId &&
+      key.environment === environment &&
+      (!key.expiresAt || Date.parse(key.expiresAt) > Date.now()) &&
+      (!sourceKeyId || key.sourceKeyId === sourceKeyId) &&
+      options.scopes.every((scope) => key.scopes.includes(scope)),
+  )
+  if (cached) return cached.token
+  const minted = await project['api-keys'].$post(
+    {
+      json: { environment, name: 'Tempo CLI', scopes, ...(sourceKeyId ? { sourceKeyId } : {}) },
+      param: { orgId, projectId },
+    },
+    request,
+  )
+  if (minted.status !== 200) return minted
+  const key = await minted.json()
+  await credentials.set(apiUrl, {
+    ...session,
+    apiKeys: [
+      ...(session.apiKeys ?? []),
+      {
+        environment,
+        ...(key.expiresAt ? { expiresAt: key.expiresAt } : {}),
+        id: key.id,
+        orgId,
+        projectId,
+        scopes: key.scopes,
+        ...(sourceKeyId ? { sourceKeyId } : {}),
+        token: key.token,
+      },
+    ],
+  })
+  return key.token
+}
+
+export declare namespace resolve {
+  /** Context and permissions required by the generated operation. */
+  type Options = {
+    /** API-key environment. Defaults to production. */
+    environment?: 'production' | 'sandbox' | undefined
+    /** Owning organization; inferred only when unambiguous. */
+    orgId?: string | undefined
+    /** Attributed project; inferred only when unambiguous. */
+    projectId?: string | undefined
+    /** Scopes required by the operation. */
+    scopes: readonly string[]
+    /** Approved source key when more than one can delegate the required scopes. */
+    sourceKeyId?: string | undefined
+  }
+}
+
+/** Revokes inferred keys before forgetting or replacing a CLI session. */
+export async function revoke(context: Auth.Context, session: Credentials.Session) {
+  const keys = session.apiKeys ?? []
+  const request = { headers: { authorization: `Bearer ${session.token}` } }
+  const results = await Promise.all(
+    keys.map(async (key) => {
+      const response = await context.api.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}'].projects[
+        ':projectId{prj_[A-Za-z0-9_-]+}'
+      ]['api-keys'][':keyId{key_[A-Za-z0-9_-]+}']
+        .$delete(
+          {
+            param: { keyId: key.id, orgId: key.orgId, projectId: key.projectId },
+          },
+          request,
+        )
+        .catch(() => undefined)
+      return response?.status === 200 || response?.status === 404
+    }),
+  )
+  return results.every(Boolean)
+}
+
+function failure(code: string, message: string) {
+  return Response.json({ error: { code, message } }, { status: 403 })
+}
+
+function describe(choices: readonly { id: string; name: string }[]) {
+  return choices.length
+    ? choices.map(({ id, name }) => `${id} (${name})`).join(', ')
+    : 'none; create one in the Tempo console first'
+}

package/src/cli/Cli.test.ts

@@ -1,7 +1,13 @@
+import * as fs from 'node:fs/promises'
+import * as http from 'node:http'
+import type * as net from 'node:net'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import { Cli as incur_Cli, z } from 'incur'
 import { Cli } from 'tapimo/server'
 
 import * as TestApp from '../../test/App.js'
+import * as TestCli from '../../test/cli.js'
 import * as Runtime from '../../test/runtime.js'
 
 const apiUrl = 'https://api.tempo-api.test'
@@ -83,6 +89,188 @@ describe('from', () => {
       fetch.mockRestore()
     }
   })
+
+  test('generates commands for the v1 API only', async () => {
+    const context = await TestCli.create()
+    const spec = (await (await context.app.request('/openapi.json')).json()) as {
+      paths: Record<string, unknown>
+    }
+    const groups = new Set(Object.keys(spec.paths).map((path) => path.split('/')[1]))
+    expect(groups).toEqual(new Set(['gecko', 'rpc', 'v1']))
+
+    const { lines } = await TestCli.serve(context.cli, ['--help'])
+    const commands = lines
+      .slice(lines.indexOf('Commands:') + 1, lines.indexOf('Integrations:'))
+      .map((line) => line.trim())
+    expect(commands).toContain('v1      Call any Tempo API endpoint.')
+    for (const name of ['gecko', 'rpc'])
+      expect(commands.some((line) => line.startsWith(`${name} `))).toBe(false)
+  })
+
+  test('sends the CLI session to session operations and the API key elsewhere', async () => {
+    const context = await TestCli.create({ apiKey: TestApp.key.token })
+    await TestCli.login(context)
+    const { token } = (await context.credentials.get(TestCli.origin))!
+    const sent = (pathname: string) =>
+      context.requests.findLast((request) => new URL(request.url).pathname === pathname)!.headers
+
+    expect((await TestCli.serve(context.cli, ['v1', 'orgs', 'get', '--format', 'json'])).code).toBe(
+      0,
+    )
+    expect(sent('/v1/orgs').get('authorization')).toBe(`Bearer ${token}`)
+    expect(sent('/v1/orgs').has('tempo-api-key')).toBe(false)
+
+    await TestCli.serve(context.cli, ['v1', 'tokens', 'get', '--format', 'json'])
+    expect(sent('/v1/tokens').get('tempo-api-key')).toBe(TestApp.key.token)
+    expect(sent('/v1/tokens').has('authorization')).toBe(false)
+
+    // Explicit credentials always win over stored ones.
+    await TestCli.serve(context.cli, ['v1', 'orgs', 'get', '--authorization', 'Bearer explicit'])
+    expect(sent('/v1/orgs').get('authorization')).toBe('Bearer explicit')
+
+    // Including the `key` query credential, which the API reads after `Authorization`.
+    await TestCli.serve(context.cli, ['/v1/orgs', '--key', TestApp.key.token])
+    const request = context.requests.at(-1)!
+    expect(new URL(request.url).searchParams.get('key')).toBe(TestApp.key.token)
+    expect(request.headers.has('authorization')).toBe(false)
+    expect(request.headers.has('tempo-api-key')).toBe(false)
+  })
+
+  test('preserves an explicit compatibility API key without inferring credentials', async () => {
+    const context = await TestCli.create({
+      request: { headers: { 'x-api-key': TestApp.key.token } },
+    })
+    await TestCli.login(context)
+    await TestCli.serve(context.cli, ['v1', 'routes', 'transfers', 'get', '--format', 'json'])
+    const request = context.requests.findLast(
+      (request) => new URL(request.url).pathname === '/v1/routes/transfers',
+    )!
+    expect(request.headers.get('x-api-key')).toBe(TestApp.key.token)
+    expect(request.headers.has('tempo-api-key')).toBe(false)
+    expect(request.headers.has('authorization')).toBe(false)
+    expect((await context.credentials.get(TestCli.origin))?.apiKeys).toBeUndefined()
+    expect(
+      context.requests.some(
+        (request) => request.method === 'POST' && request.url.endsWith('/api-keys'),
+      ),
+    ).toBe(false)
+  })
+
+  test('forwards gateway request defaults to login, inference, and revocation', async () => {
+    const context = await TestCli.create({
+      request: {
+        headers: {
+          'cf-access-client-id': 'gateway-client',
+          'cf-access-client-secret': 'gateway-secret',
+        },
+        redirect: 'manual',
+      },
+    })
+    const { cookie } = await TestCli.login(context)
+    const created = await context.app.request('/v1/orgs', {
+      body: JSON.stringify({ name: 'Gateway project' }),
+      headers: { 'content-type': 'application/json', cookie },
+      method: 'POST',
+    })
+    const org = await created.json()
+    await context.app.request(`/v1/orgs/${org.id}/projects`, {
+      body: JSON.stringify({ name: 'Gateway' }),
+      headers: { 'content-type': 'application/json', cookie },
+      method: 'POST',
+    })
+    const result = await TestCli.serve(context.cli, [
+      'v1',
+      'routes',
+      'transfers',
+      'get',
+      '--format',
+      'json',
+    ])
+    expect(result.code).toBe(0)
+    expect((await context.credentials.get(TestCli.origin))?.apiKeys).toHaveLength(1)
+    expect((await TestCli.serve(context.cli, ['logout', '--format', 'json'])).code).toBe(0)
+    expect(context.requests.some((request) => new URL(request.url).pathname === '/v1/scopes')).toBe(
+      true,
+    )
+    expect(
+      context.requests.some(
+        (request) => request.method === 'POST' && request.url.endsWith('/api-keys'),
+      ),
+    ).toBe(true)
+    expect(context.requests.some((request) => request.method === 'DELETE')).toBe(true)
+    for (const request of context.requests) {
+      expect(request.headers.get('cf-access-client-id')).toBe('gateway-client')
+      expect(request.headers.get('cf-access-client-secret')).toBe('gateway-secret')
+      expect(request.redirect).toBe('manual')
+    }
+  })
+
+  test('sends the API key only to operations that accept one', async () => {
+    const context = await TestCli.create({ apiKey: TestApp.key.token })
+    const sent = (pathname: string) =>
+      context.requests.findLast((request) => new URL(request.url).pathname === pathname)
+
+    // Sign-in-only operations stop before sending, so an API key cannot earn a misleading 403.
+    const invitations = await TestCli.serve(context.cli, [
+      'v1',
+      'invitations',
+      'get',
+      '--format',
+      'json',
+    ])
+    expect(invitations.code).toBe(1)
+    expect(JSON.parse(invitations.lines.join('\n'))).toMatchObject({
+      code: 'not_signed_in',
+      message: 'Not signed in, or the session expired. Run `tapimo login`.',
+    })
+    expect(sent('/v1/invitations')).toBeUndefined()
+
+    // Public operations go out without credentials.
+    await TestCli.serve(context.cli, [
+      'v1',
+      'auth',
+      'siwe',
+      'challenge',
+      'post',
+      '--format',
+      'json',
+    ])
+    expect(sent('/v1/auth/siwe/challenge')?.headers.has('tempo-api-key')).toBe(false)
+  })
+})
+
+describe('fromEnv', () => {
+  test('keeps session commands usable when the API document cannot load', async () => {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-home-'))
+    // Port 9 (discard) refuses connections, so the document fetch fails fast.
+    const cli = await Cli.fromEnv(
+      { TEMPO_API_URL: 'http://127.0.0.1:9', TEMPO_HOME: home },
+      { docs: false },
+    )
+    const { code, lines } = await TestCli.serve(cli, ['whoami', '--format', 'json'])
+    expect(code).toBe(1)
+    expect(JSON.parse(lines.join('\n')).code).toBe('not_signed_in')
+  })
+
+  test('skips fetching the API document when one is supplied', async () => {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-home-'))
+    let requests = 0
+    const server = http.createServer((_, response) => {
+      requests += 1
+      response.end('{}')
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as net.AddressInfo
+    try {
+      await Cli.fromEnv(
+        { TEMPO_API_URL: `http://127.0.0.1:${port}`, TEMPO_HOME: home },
+        { docs: false, openapi: { paths: {} } },
+      )
+      expect(requests).toBe(0)
+    } finally {
+      server.close()
+    }
+  })
 })
 
 function mockHostedApi(app = TestApp.create()) {