tapimo 0.15.0 → 0.18.0

package/src/cli/commands/auth.ts

@@ -0,0 +1,254 @@
+import * as child_process from 'node:child_process'
+import * as os from 'node:os'
+import { Cli as incur_Cli, z } from 'incur'
+import { Base64, Bytes } from 'ox'
+
+import type * as Client from '../../Client.js'
+import * as CliAuth from '../../internal/CliAuth.js'
+import type * as Credentials from '../Credentials.js'
+import * as ApiKeys from '../ApiKeys.js'
+
+/** Context shared by the session commands. */
+export type Context = {
+  /** Typed Tempo API client. */
+  api: Client.Client
+  /** Tempo API origin; stored sessions are keyed by it. */
+  apiUrl: URL
+  /** Stored CLI sessions. */
+  credentials: Credentials.Store
+  /** Sends a raw request to the Tempo API, for routes outside the typed client. */
+  fetch: (request: Request) => Promise<Response>
+  /** CLI name and version reported to the approving user (`tempo api 0.1.0`). */
+  name: string
+}
+
+/** Signs in by approving this device in the console, then stores the CLI session. */
+export function login(context: login.Options) {
+  const { api, apiUrl, credentials, name, open = openExternal } = context
+  const authorizations = api.v1.cli.authorizations
+  return incur_Cli.create('login', {
+    description: 'Sign in by approving this device in the Tempo console.',
+    options: z.object({
+      browser: z
+        .boolean()
+        .optional()
+        .describe(
+          'Open the approval page in a browser. Defaults to true in a terminal; pass --no-browser on remote hosts.',
+        ),
+    }),
+    async *run(c) {
+      const codeVerifier = Base64.fromBytes(Bytes.random(32), { pad: false, url: true })
+      const started = await authorizations.$post({
+        json: {
+          codeChallenge: CliAuth.challengeFrom(codeVerifier),
+          device: os.hostname().slice(0, 100),
+          name,
+        },
+      })
+      if (started.status !== 200)
+        return c.error({
+          code: 'login_failed',
+          message: await errorMessage(started, 'Could not start sign-in'),
+          retryable: started.status >= 500 || started.status === 429,
+        })
+      const { code, expiresAt, interval, verificationUrl } = await started.json()
+
+      if (c.agent) yield { code, expiresAt, verificationUrl }
+      else yield `Confirm code ${code} at ${verificationUrl}`
+      if (c.options.browser ?? !c.agent) open(verificationUrl)
+      if (!c.agent) yield 'Waiting for approval…'
+
+      const deadline = Date.parse(expiresAt)
+      let delay = interval * 1_000
+      while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, delay))
+        const response = await authorizations[':code{[A-Za-z -]+}'].token.$post({
+          json: { codeVerifier },
+          param: { code },
+        })
+        // Back off when the shared per-IP limit trips instead of failing the sign-in.
+        if (response.status === 429) {
+          delay += 5_000
+          continue
+        }
+        if (response.status === 404) break
+        if (response.status !== 200)
+          return c.error({
+            code: 'login_failed',
+            message: await errorMessage(response, 'Could not complete sign-in'),
+            retryable: response.status >= 500,
+          })
+        const body = await response.json()
+        if (body.status === 'pending') continue
+        if (body.status === 'denied')
+          return c.error({
+            code: 'login_denied',
+            message: 'The sign-in was denied in the console.',
+          })
+
+        const me = await api.v1.me.$get(undefined, bearer(body.token))
+        if (me.status !== 200) {
+          const message = await errorMessage(me, 'Could not load your account')
+          // The new session is live but unsaved, so revoke it rather than leave it behind.
+          await revoke(context, { token: body.token })
+          return c.error({ code: 'login_failed', message, retryable: true })
+        }
+        const user = await me.json()
+        const replace = async (store: Credentials.Store) => {
+          const previous = await store.get(apiUrl)
+          await store.set(apiUrl, {
+            ...(user.email ? { email: user.email } : {}),
+            expiresAt: body.expiresAt,
+            scopes: body.scopes,
+            token: body.token,
+            userId: user.id,
+          })
+          // The replaced session would otherwise stay valid server-side with no local copy to revoke.
+          if (previous) {
+            await ApiKeys.revoke(context, previous)
+            await revoke(context, { token: previous.token })
+          }
+        }
+        await (credentials.withLock ? credentials.withLock(replace) : replace(credentials))
+        // Streaming commands only emit yielded chunks, so the result is the last chunk.
+        if (c.agent)
+          yield {
+            apiUrl: apiUrl.origin,
+            ...(user.email ? { email: user.email } : {}),
+            expiresAt: body.expiresAt,
+          }
+        else yield `Signed in${user.email ? ` as ${user.email}` : ''}.`
+        return c.ok(undefined, {
+          cta: {
+            commands: [
+              { command: 'keys create', description: 'Create an API key' },
+              { command: 'whoami', description: 'Show the signed-in account' },
+            ],
+          },
+        })
+      }
+      return c.error({
+        code: 'login_expired',
+        cta: { commands: [{ command: 'login', description: 'Start a new sign-in' }] },
+        message: 'The sign-in expired before it was approved.',
+      })
+    },
+  })
+}
+
+export declare namespace login {
+  /** Options for {@link login}. */
+  type Options = Context & {
+    /** Opens the approval page. Defaults to the platform browser opener. */
+    open?: ((url: string) => void) | undefined
+  }
+}
+
+/** Revokes and forgets the stored CLI session. */
+export function logout(context: Context) {
+  const { apiUrl, credentials } = context
+  return incur_Cli.create('logout', {
+    description: 'Sign out and revoke the stored CLI session.',
+    async run() {
+      async function remove(store: Credentials.Store) {
+        const session = await store.get(apiUrl)
+        const keysRevoked = session ? await ApiKeys.revoke(context, session) : true
+        const revoked = session ? await revoke(context, { token: session.token }) : false
+        // Forget the token even when revocation fails; it expires server-side on its own.
+        await store.remove(apiUrl)
+        return { apiUrl: apiUrl.origin, keysRevoked, revoked, signedOut: true }
+      }
+      return credentials.withLock ? credentials.withLock(remove) : remove(credentials)
+    },
+  })
+}
+
+/** Shows the account the stored CLI session acts as. */
+export function whoami(context: Context) {
+  const { api, apiUrl, credentials } = context
+  return incur_Cli.create('whoami', {
+    description: 'Show the signed-in account.',
+    async run(c) {
+      const session = await credentials.get(apiUrl)
+      if (!session) return c.error(signedOut())
+      const response = await api.v1.me.$get(undefined, bearer(session.token))
+      if (response.status === 401) {
+        await credentials.remove(apiUrl)
+        return c.error(signedOut())
+      }
+      if (response.status !== 200)
+        return c.error({
+          code: 'request_failed',
+          message: await errorMessage(response, 'Could not load your account'),
+          retryable: response.status >= 500,
+        })
+      const user = await response.json()
+      return {
+        apiUrl: apiUrl.origin,
+        ...(user.email ? { email: user.email } : {}),
+        expiresAt: session.expiresAt,
+        userId: user.id,
+      }
+    },
+  })
+}
+
+/** Error returned when no unexpired CLI session is stored. */
+export function signedOut() {
+  return {
+    code: 'not_signed_in',
+    cta: { commands: [{ command: 'login', description: 'Sign in' }] },
+    message: 'Not signed in, or the session expired.',
+  }
+}
+
+/** Request options carrying a CLI session token. */
+export function bearer(token: string) {
+  return { headers: { authorization: `Bearer ${token}` } }
+}
+
+/** The response surface {@link errorMessage} reads, shared by fetch and typed-client responses. */
+export type ErrorResponse = {
+  /** Parses the body as JSON. */
+  json(): Promise<unknown>
+  /** HTTP status code. */
+  status: number
+}
+
+/** Reads the API error envelope's message, falling back to a status line. */
+export async function errorMessage(response: ErrorResponse, fallback: string) {
+  const body = (await response.json().catch(() => undefined)) as
+    | { error?: { message?: string | undefined } | undefined }
+    | undefined
+  return body?.error?.message ?? `${fallback} (HTTP ${response.status}).`
+}
+
+/** Revokes a CLI session server-side, resolving `true` once the API confirms. */
+async function revoke(context: Context, options: revoke.Options) {
+  const { apiUrl, fetch } = context
+  // The sign-out route is outside the typed client surface; keep any API base path.
+  const url = new URL(apiUrl)
+  url.pathname = `${apiUrl.pathname.replace(/\/$/, '')}/v1/auth/logout`
+  const response = await fetch(
+    new Request(url, { ...bearer(options.token), method: 'POST' }),
+  ).catch(() => undefined)
+  return response?.status === 204
+}
+
+declare namespace revoke {
+  /** Options for {@link revoke}. */
+  type Options = {
+    /** CLI session token to revoke. */
+    token: string
+  }
+}
+
+// Best effort: the URL is already printed, so a missing opener (headless boxes) is not an error.
+function openExternal(url: string) {
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  const child = child_process.spawn(command, args, { detached: true, stdio: 'ignore' })
+  child.on('error', () => undefined)
+  child.unref()
+}

package/src/cli/commands/keys.test.ts

@@ -0,0 +1,68 @@
+import * as TestCli from '../../../test/cli.js'
+
+type Context = Awaited<ReturnType<typeof TestCli.create>>
+
+/** Creates an organization with one project through the console session. */
+async function organization({ app }: Context, cookie: string, name = 'Acme') {
+  const headers = { 'content-type': 'application/json', cookie }
+  const org = (await (
+    await app.request('/v1/orgs', { body: JSON.stringify({ name }), headers, method: 'POST' })
+  ).json()) as { id: string }
+  const project = (await (
+    await app.request(`/v1/orgs/${org.id}/projects`, {
+      body: JSON.stringify({ name: 'Checkout' }),
+      headers,
+      method: 'POST',
+    })
+  ).json()) as { id: string }
+  return { orgId: org.id, projectId: project.id }
+}
+
+describe('keys create', () => {
+  test('creates a production read key for the only project', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context)
+    const { orgId, projectId } = await organization(context, cookie)
+
+    const { code, lines } = await TestCli.serve(context.cli, [
+      'keys',
+      'create',
+      '--name',
+      'Local dev',
+      '--format',
+      'json',
+    ])
+    expect(code).toBe(0)
+    const { cta, id, token, ...key } = JSON.parse(lines.join('\n'))
+    expect(cta.description).toBe('Store the token now; it is not shown again.')
+    expect(id).toMatch(/^key_/)
+    expect(token).toMatch(/^tempo:sk:[a-f0-9]{48}$/)
+    expect(key).toEqual({
+      environment: 'production',
+      name: 'Local dev',
+      orgId,
+      projectId,
+      scopes: ['data:read'],
+    })
+  })
+
+  test('asks for --org when several organizations exist', async () => {
+    const context = await TestCli.create()
+    const { cookie } = await TestCli.login(context)
+    await organization(context, cookie, 'Acme')
+    await organization(context, cookie, 'Globex')
+
+    const { code, lines } = await TestCli.serve(context.cli, ['keys', 'create', '--format', 'json'])
+    expect(code).toBe(1)
+    const error = JSON.parse(lines.join('\n'))
+    expect(error.code).toBe('organization_required')
+    expect(error.message).toMatch(/^Pass --org with one of: org_\S+ \((Acme|Globex)\), org_\S+/)
+  })
+
+  test('asks to sign in when no session is stored', async () => {
+    const { cli } = await TestCli.create()
+    const { code, lines } = await TestCli.serve(cli, ['keys', 'create', '--format', 'json'])
+    expect(code).toBe(1)
+    expect(JSON.parse(lines.join('\n')).code).toBe('not_signed_in')
+  })
+})

package/src/cli/commands/keys.ts

@@ -0,0 +1,125 @@
+import { Cli as incur_Cli, z } from 'incur'
+
+import * as Auth from './auth.js'
+
+/** API-key commands that act through the stored CLI session. */
+export function keys(context: Auth.Context) {
+  const { api, apiUrl, credentials } = context
+
+  // Maps an API failure to a CLI error; an expired session also forgets the stored token.
+  async function failure(response: Auth.ErrorResponse) {
+    if (response.status === 401) {
+      await credentials.remove(apiUrl)
+      return Auth.signedOut()
+    }
+    return {
+      code: 'request_failed',
+      message: await Auth.errorMessage(response, 'The request failed'),
+      retryable: response.status >= 500 || response.status === 429,
+    }
+  }
+
+  return incur_Cli.create('keys', { description: 'Manage API keys.' }).command('create', {
+    description: 'Create an API key for a project. The key is shown once.',
+    examples: [
+      { description: 'Read key for your only project', options: {} },
+      {
+        description: 'Testnet-only sandbox key for a specific project',
+        options: { env: 'sandbox', project: 'prj_123', scopes: ['data:read'] },
+      },
+    ],
+    options: z.object({
+      allowedIps: z
+        .array(z.string())
+        .optional()
+        .describe('Client IP address or CIDR range allowed to use the key. Repeat for more.'),
+      env: z
+        .enum(['production', 'sandbox'])
+        .default('production')
+        .describe(
+          'Key environment. Production keys work on every chain; sandbox keys only on testnets.',
+        ),
+      name: z.string().optional().describe('Human-readable key name.'),
+      org: z
+        .string()
+        .optional()
+        .describe('Organization id (org_…). Defaults to your only organization.'),
+      project: z
+        .string()
+        .optional()
+        .describe('Project id (prj_…). Defaults to the only project in the organization.'),
+      scopes: z
+        .array(z.string())
+        .default(['data:read'])
+        .describe('Scope to grant. Repeat for more.'),
+    }),
+    async run(c) {
+      const session = await credentials.get(apiUrl)
+      if (!session) return c.error(Auth.signedOut())
+      const request = Auth.bearer(session.token)
+
+      const orgs = c.options.org ? undefined : await api.v1.orgs.$get(undefined, request)
+      if (orgs && orgs.status !== 200) return c.error(await failure(orgs))
+      const orgChoices = orgs ? (await orgs.json()).data : []
+      const orgId = c.options.org ?? (orgChoices.length === 1 ? orgChoices[0]!.id : undefined)
+      if (!orgId)
+        return c.error(
+          orgChoices.length === 0
+            ? { code: 'no_organizations', message: 'Create an organization in the Tempo console first.' } // prettier-ignore
+            : { code: 'organization_required', message: `Pass --org with one of: ${describe(orgChoices)}.` }, // prettier-ignore
+        )
+
+      const org = api.v1.orgs[':orgId{org_[A-Za-z0-9_-]+}']
+      const projects = c.options.project
+        ? undefined
+        : await org.projects.$get({ param: { orgId } }, request)
+      if (projects && projects.status !== 200) return c.error(await failure(projects))
+      const projectChoices = projects ? (await projects.json()).data : []
+      const projectId =
+        c.options.project ?? (projectChoices.length === 1 ? projectChoices[0]!.id : undefined)
+      if (!projectId)
+        return c.error(
+          projectChoices.length === 0
+            ? { code: 'no_projects', message: 'Create a project in the Tempo console first.' }
+            : { code: 'project_required', message: `Pass --project with one of: ${describe(projectChoices)}.` }, // prettier-ignore
+        )
+
+      const { allowedIps, env, name, scopes } = c.options
+      const response = await org.projects[':projectId{prj_[A-Za-z0-9_-]+}']['api-keys'].$post(
+        {
+          json: {
+            ...(allowedIps ? { allowedIps } : {}),
+            environment: env,
+            ...(name ? { name } : {}),
+            scopes,
+          },
+          param: { orgId, projectId },
+        },
+        request,
+      )
+      if (response.status !== 200) return c.error(await failure(response))
+      const key = await response.json()
+      return c.ok(
+        {
+          environment: key.environment,
+          id: key.id,
+          ...(key.name ? { name: key.name } : {}),
+          orgId,
+          projectId,
+          scopes: key.scopes,
+          token: key.token,
+        },
+        {
+          cta: {
+            commands: [{ command: 'v1 tokens get', description: 'Call the API with TEMPO_API_KEY set' }], // prettier-ignore
+            description: 'Store the token now; it is not shown again.',
+          },
+        },
+      )
+    },
+  })
+}
+
+function describe(choices: readonly { id: string; name: string }[]) {
+  return choices.map(({ id, name }) => `${id} (${name})`).join(', ')
+}