tapimo 0.15.1 → 0.18.1

package/src/cli/Cli.ts

@@ -1,33 +1,91 @@
-import { Cli as incur_Cli, Fetch, type Openapi } from 'incur'
+import * as path from 'node:path'
+import { Cli as incur_Cli, type Fetch, Openapi } from 'incur'
 
 import type { mcp } from '../apps/mcp.js'
-import * as Admin from './commands/admin.js'
+import * as Client from '../Client.js'
+import * as ApiKeys from './ApiKeys.js'
+import * as Auth from './commands/auth.js'
+import * as Keys from './commands/keys.js'
+import * as Credentials from './Credentials.js'
+import * as Spec from './Spec.js'
 
-/** Tool patterns hidden from MCP clients: super admin, partner-shaped gecko mirrors, browser session flows. */
-const excludedTools = ['admin_*', 'gecko_*', 'v1_auth_*']
+/** Tool patterns hidden from MCP clients: super admin, partner-shaped gecko mirrors, browser and interactive session flows. */
+const excludedTools = ['admin_*', 'gecko_*', 'login', 'logout', 'v1_auth_*']
+
+// Commands cover the versioned API; partner mirrors, `/rpc`, and `/mcp` stay reachable through the raw gateway.
+const openapiConfig: Openapi.Config = {
+  groups: { v1: 'Call any Tempo API endpoint.' },
+  include: ({ path }) => path.startsWith('/v1/'),
+  mode: 'namespace',
+}
 
 /** Usage guidance surfaced to MCP clients on initialize (`<cli> --mcp`). */
 const instructions =
-  'Tempo MCP provides access to the hosted Tempo API and documentation. Authenticated tools accept an `authorization` input (`Bearer <api key>`). List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation.'
+  'Tempo MCP provides access to the hosted Tempo API and documentation. Authenticated tools accept an `authorization` input (`Bearer <api key>`); after `login`, management tools use the stored CLI session and protected API tools infer scoped project credentials. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation.'
+
+// Explicit credentials always win over stored ones.
+const credentialHeaders = ['authorization', 'cookie', 'tempo-api-key', 'x-api-key']
+const credentialQuery = 'key'
 
 /**
- * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
- * commands (`<cli> admin …`) and the remote Tempo docs tools (`<cli> docs …`).
+ * Creates an incur CLI backed by a hosted Tempo API: generated API commands,
+ * session commands (`login`, `logout`, `whoami`), `keys create`, and the remote
+ * Tempo docs tools (`<cli> docs …`).
  */
 export function from(url: string | URL, options: from.Options = {}) {
   const {
+    apiKey,
+    credentials = Credentials.store(),
     description = 'Tempo API CLI',
     docs = 'https://mcp.tempo.xyz/mcp',
+    environment,
+    fetch = (request) => globalThis.fetch(request),
     name = 'tapimo',
     openapi = 'openapi.json',
+    orgId,
+    projectId,
     request,
+    sourceKeyId,
+    update,
     version = '0.0.0',
   } = options
+  const apiUrl = new URL(url)
+  const send = (incoming: Request) => {
+    const { headers: configuredHeaders, ...options } = request ?? {}
+    const headers = new Headers(configuredHeaders)
+    // Gateway headers accompany prerequisite requests, but credentials belong to each operation.
+    for (const name of credentialHeaders) headers.delete(name)
+    incoming.headers.forEach((value, key) => headers.set(key, value))
+    return fetch(new Request(incoming, { ...options, headers }))
+  }
+  const context: Auth.Context = {
+    api: Client.create({
+      fetch: (input: Request | string | URL, init?: RequestInit) => send(new Request(input, init)),
+      url: apiUrl.href.replace(/\/$/, ''),
+    }),
+    apiUrl,
+    credentials,
+    fetch: send,
+    name: `${name} ${version}`,
+  }
 
   const cli = incur_Cli
     .create(name, {
       description,
-      fetch: Fetch.fromRequest(url, request),
+      fetch: source({
+        apiKey,
+        apiUrl,
+        context,
+        credentials,
+        environment,
+        fetch,
+        name,
+        openapi,
+        orgId,
+        projectId,
+        request,
+        sourceKeyId,
+      }),
       mcp: {
         instructions,
         name: 'tempo',
@@ -35,31 +93,241 @@ export function from(url: string | URL, options: from.Options = {}) {
         tools: { exclude: excludedTools },
       },
       openapi,
-      openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
+      openapiConfig: options.openapiConfig ?? openapiConfig,
+      ...(update === undefined ? {} : { update }),
       version,
     })
-    .command(Admin.admin)
+    .command(Auth.login(context))
+    .command(Auth.logout(context))
+    .command(Auth.whoami(context))
+    .command(Keys.keys(context))
   if (docs !== false)
     cli.command('docs', { description: 'Search the Tempo documentation.', mcp: docs })
   return cli
 }
 
+/**
+ * Creates the CLI for the API at `TEMPO_API_URL` (default: hosted), sending
+ * `TEMPO_API_KEY` where sessions do not apply and storing sessions under `TEMPO_HOME`.
+ */
+export async function fromEnv(env: fromEnv.Env, options: from.Options = {}) {
+  if (env.TEMPO_API_ENV && env.TEMPO_API_ENV !== 'production' && env.TEMPO_API_ENV !== 'sandbox')
+    throw new Error('TEMPO_API_ENV must be production or sandbox.')
+  const url = env.TEMPO_API_URL || Client.defaultUrl
+  const credentialsFile = Credentials.defaultFile({ home: env.TEMPO_HOME })
+  // Loaded once, from a revalidated disk cache, so generated commands and session
+  // attachment share it and unchanged documents cost a 304. A supplied document skips it.
+  const openapi =
+    options.openapi ??
+    (await (async () => {
+      const spec = await Spec.load({
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        file: Spec.cacheFile({ directory: path.join(path.dirname(credentialsFile), 'cache'), url }),
+        url,
+      })
+      if (spec.status !== 'current') {
+        const reason = spec.error instanceof Error ? spec.error.message : String(spec.error)
+        // Unreachable: help, version, and session commands still work, plus cached API commands.
+        process.stderr.write(
+          spec.status === 'cached'
+            ? `Could not reach ${url} (${reason}); using cached API commands.\n`
+            : `Could not load API commands from ${url}: ${reason}\n`,
+        )
+      }
+      return spec.document
+    })())
+  return from(url, {
+    ...(env.TEMPO_API_KEY ? { apiKey: env.TEMPO_API_KEY } : {}),
+    environment: env.TEMPO_API_ENV as 'production' | 'sandbox' | undefined,
+    orgId: env.TEMPO_API_ORG,
+    projectId: env.TEMPO_API_PROJECT,
+    sourceKeyId: env.TEMPO_API_SOURCE_KEY,
+    credentials: Credentials.store({ file: credentialsFile }),
+    ...options,
+    openapi,
+  })
+}
+
+export declare namespace fromEnv {
+  /** Environment variables the CLI reads; any other variables are ignored. */
+  type Env = Record<string, string | undefined> & {
+    /** Environment for inferred project credentials. */
+    TEMPO_API_ENV?: string | undefined
+    /** Explicit API key sent where sessions do not apply. */
+    TEMPO_API_KEY?: string | undefined
+    /** Organization for inferred project credentials. */
+    TEMPO_API_ORG?: string | undefined
+    /** Project for inferred project credentials. */
+    TEMPO_API_PROJECT?: string | undefined
+    /** Approved key to derive restricted scopes from. */
+    TEMPO_API_SOURCE_KEY?: string | undefined
+    /** Tempo API origin. @default 'https://api.tempo.xyz' */
+    TEMPO_API_URL?: string | undefined
+    /** Tempo CLI home directory. @default '~/.tempo' */
+    TEMPO_HOME?: string | undefined
+  }
+}
+
 export declare namespace from {
   /** Options for creating a Tempo API CLI from a hosted API. */
   type Options = {
+    /** API key sent on operations that do not accept the stored CLI session. */
+    apiKey?: string | undefined
+    /** Stored CLI sessions. @default Credentials.store() */
+    credentials?: Credentials.Store | undefined
     /** CLI description. */
     description?: string | undefined
     /** Remote docs MCP source mounted as the `docs` command group, or `false` to omit it. @default 'https://mcp.tempo.xyz/mcp' */
     docs?: mcp.Source | false | undefined
+    /** Environment for inferred project credentials. Defaults to production. */
+    environment?: 'production' | 'sandbox' | undefined
+    /** Sends requests to the Tempo API, such as an in-process app. @default globalThis.fetch */
+    fetch?: ((request: Request) => Promise<Response>) | undefined
     /** CLI name. */
     name?: string | undefined
-    /** OpenAPI document source. Relative paths resolve from the API URL. */
+    /** OpenAPI document or its source. Pass a resolved document to avoid fetching it twice. */
     openapi?: Openapi.OpenAPISource | undefined
-    /** OpenAPI command generation configuration. Defaults to namespace mode. */
+    /** OpenAPI command generation configuration. Defaults to namespace-mode commands for the `/v1` API. */
     openapiConfig?: Openapi.Config | undefined
+    /** Organization for inferred project credentials. */
+    orgId?: string | undefined
+    /** Project for inferred project credentials. */
+    projectId?: string | undefined
     /** Request options applied to API calls. */
     request?: Fetch.fromRequest.Options | undefined
+    /** Approved source key when multiple restricted-scope grants exist. */
+    sourceKeyId?: string | undefined
+    /** How `--update` installs a new version and whether to check for one. @default npm, inferred from the installed package */
+    update?: incur_Cli.create.Options['update']
     /** CLI version. */
     version?: string | undefined
   }
 }
+
+/**
+ * Hosted request source for generated commands. Operations whose OpenAPI
+ * security accepts a session get the stored CLI session, and those accepting
+ * API keys get the configured key or scoped credentials inferred from login.
+ * Sign-in-only operations fail locally when signed out.
+ */
+function source(parameters: source.Parameters): Fetch.RequestSource {
+  const {
+    apiKey,
+    apiUrl,
+    context,
+    credentials,
+    environment,
+    fetch,
+    name,
+    openapi,
+    orgId,
+    projectId,
+    request = {},
+    sourceKeyId,
+  } = parameters
+  const { headers: defaultHeaders, ...init } = request
+  // Resolved once; a document that fails to load leaves every operation unknown.
+  const lanesFor = (async () =>
+    operationLanes(await Openapi.resolve(openapi, { baseUrl: apiUrl })))().catch(
+    () => () => undefined,
+  )
+
+  return {
+    url: apiUrl,
+    async fetch(incoming) {
+      const { pathname, search } = new URL(incoming.url)
+      const target = new URL(apiUrl)
+      target.pathname = `${apiUrl.pathname.replace(/\/$/, '')}${pathname}`
+      target.search = search
+      const headers = new Headers(defaultHeaders)
+      incoming.headers.forEach((value, key) => headers.set(key, value))
+      const explicit =
+        credentialHeaders.some((name) => headers.has(name)) ||
+        target.searchParams.has(credentialQuery)
+      if (!explicit) {
+        const lanes = (await lanesFor)(incoming.method, pathname)
+        const session = lanes?.session ? await credentials.get(apiUrl) : undefined
+        if (session) headers.set('authorization', `Bearer ${session.token}`)
+        // Unknown operations still get the key and let the API decide.
+        else if (apiKey && (lanes?.apiKey ?? true)) headers.set('tempo-api-key', apiKey)
+        else if (lanes?.apiKey && !lanes.public) {
+          const inferred = await ApiKeys.resolve(context, {
+            environment,
+            orgId,
+            projectId,
+            scopes: lanes.scopes,
+            sourceKeyId,
+          })
+          if (inferred && typeof inferred !== 'string') return inferred as Response
+          if (inferred) headers.set('tempo-api-key', inferred)
+        }
+        // Sending nothing (or an API key) would earn an unhelpful 401 or 403.
+        else if (lanes?.session && !lanes.apiKey && !lanes.public) {
+          const message = `Not signed in, or the session expired. Run \`${name} login\`.`
+          return Response.json({ error: { code: 'not_signed_in', message } }, { status: 401 })
+        }
+      }
+      return fetch(new Request(new Request(target, incoming), { ...init, headers }))
+    },
+  }
+}
+
+declare namespace source {
+  type Parameters = {
+    apiKey: string | undefined
+    apiUrl: URL
+    context: Auth.Context
+    credentials: Credentials.Store
+    environment: 'production' | 'sandbox' | undefined
+    fetch: (request: Request) => Promise<Response>
+    name: string
+    openapi: Openapi.OpenAPISource
+    orgId: string | undefined
+    projectId: string | undefined
+    request: Fetch.fromRequest.Options | undefined
+    sourceKeyId: string | undefined
+  }
+}
+
+/** Builds a lookup of the credentials each operation accepts, from its OpenAPI security requirements. */
+function operationLanes(spec: Openapi.OpenAPISpec) {
+  type Operation = {
+    security?: readonly Record<string, unknown>[] | undefined
+    'x-required-scopes'?: readonly string[] | undefined
+  }
+  const paths = (spec.paths ?? {}) as Record<string, Record<string, Operation>>
+  const operations = Object.entries(paths).flatMap(([path, item]) =>
+    Object.entries(item).map(([method, operation]) => {
+      const requirements = operation.security ?? spec.security ?? []
+      const has = (scheme: string) => requirements.some((requirement) => scheme in requirement)
+      return {
+        lanes: {
+          apiKey: has('apiKey') || has('queryApiKey'),
+          // An empty requirement (or none at all) admits anonymous callers.
+          public:
+            requirements.length === 0 ||
+            requirements.some((requirement) => Object.keys(requirement).length === 0),
+          session: has('session'),
+          scopes: operation['x-required-scopes'] ?? ['*'],
+        },
+        method: method.toUpperCase(),
+        pattern: pathPattern(path),
+        templated: path.split('{').length - 1,
+      }
+    }),
+  )
+  // Literal paths win over templated ones (`/v1/webhooks/event-types` over `/v1/webhooks/{id}`).
+  operations.sort((a, b) => a.templated - b.templated)
+  return (method: string, pathname: string) =>
+    operations.find((operation) => operation.method === method && operation.pattern.test(pathname))
+      ?.lanes
+}
+
+// `/v1/orgs/{orgId}` matches `/v1/orgs/org_123`.
+function pathPattern(path: string) {
+  const source = path
+    .split(/(\{[^}]+\})/)
+    .map((part) => (part.startsWith('{') ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    .join('')
+  return new RegExp(`^${source}$`)
+}

package/src/cli/Credentials.test.ts

@@ -0,0 +1,122 @@
+import * as child_process from 'node:child_process'
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as util from 'node:util'
+
+import * as Credentials from './Credentials.js'
+
+const session = {
+  email: 'dev@example.com',
+  expiresAt: '2099-01-01T00:00:00.000Z',
+  token: `tempo:cli:${'ab'.repeat(32)}`,
+  userId: 'usr_1a2b3c4d5e6f7g8h9j0k1m2n',
+}
+
+async function temporaryFile() {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'tapimo-credentials-'))
+  return path.join(directory, 'nested', 'credentials.json')
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('store', () => {
+  test('round-trips a session per API origin in a private file', async () => {
+    const file = await temporaryFile()
+    const store = Credentials.store({ file })
+    await store.set('https://api.tempo.xyz/', session)
+
+    expect(await store.get('https://api.tempo.xyz')).toEqual(session)
+    expect(await store.get('https://api.tempo-dev.workers.dev')).toBeUndefined()
+    expect((await fs.stat(file)).mode & 0o777).toBe(0o600)
+    expect((await fs.stat(path.dirname(file))).mode & 0o777).toBe(0o700)
+  })
+
+  test('treats a missing or unreadable file as signed out', async () => {
+    const file = await temporaryFile()
+    expect(await Credentials.store({ file }).get('https://api.tempo.xyz')).toBeUndefined()
+    await fs.mkdir(path.dirname(file), { recursive: true })
+    await fs.writeFile(file, '{"version":2}')
+    expect(await Credentials.store({ file }).get('https://api.tempo.xyz')).toBeUndefined()
+    await fs.writeFile(file, '{not json')
+    expect(await Credentials.store({ file }).get('https://api.tempo.xyz')).toBeUndefined()
+  })
+
+  test('hides expired sessions', async () => {
+    vi.useFakeTimers({ now: new Date('2099-01-01T00:00:00.000Z') })
+    const store = Credentials.store({ file: await temporaryFile() })
+    await store.set('https://api.tempo.xyz', session)
+    expect(await store.get('https://api.tempo.xyz')).toBeUndefined()
+  })
+
+  test('removes one origin and keeps the rest', async () => {
+    const store = Credentials.store({ file: await temporaryFile() })
+    await store.set('https://api.tempo.xyz', session)
+    await store.set('https://api.tempo-dev.workers.dev', session)
+    await store.remove('https://api.tempo.xyz')
+    expect(await store.get('https://api.tempo.xyz')).toBeUndefined()
+    expect(await store.get('https://api.tempo-dev.workers.dev')).toEqual(session)
+  })
+
+  test('serializes read-modify-write transactions across separate processes', async () => {
+    const file = await temporaryFile()
+    const store = Credentials.store({ file })
+    await store.set('https://api.tempo.xyz', { ...session, scopes: [] })
+    const execute = util.promisify(child_process.execFile)
+    const script = `
+      import * as Credentials from ${JSON.stringify(path.join(import.meta.dirname, 'Credentials.ts'))};
+      const store = Credentials.store({ file: ${JSON.stringify(file)} });
+      await store.withLock(async (credentials) => {
+        const session = await credentials.get('https://api.tempo.xyz');
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        await credentials.set('https://api.tempo.xyz', {
+          ...session, scopes: [...session.scopes, process.argv[1]],
+        });
+      });
+    `
+    await Promise.all(
+      ['data:read', 'routes:read', 'rpc-relay:read'].map((scope) =>
+        execute(process.execPath, [
+          '--experimental-transform-types',
+          '--input-type=module',
+          '-e',
+          script,
+          scope,
+        ]),
+      ),
+    )
+    expect((await store.get('https://api.tempo.xyz'))?.scopes?.sort()).toEqual([
+      'data:read',
+      'routes:read',
+      'rpc-relay:read',
+    ])
+    expect((await fs.stat(file)).mode & 0o777).toBe(0o600)
+    expect(await fs.readdir(path.dirname(file))).toEqual(['credentials.json'])
+  })
+
+  test('releases the credentials lock after a transaction fails', async () => {
+    const file = await temporaryFile()
+    const first = Credentials.store({ file })
+    await expect(
+      first.withLock!(async () => {
+        throw new Error('Failed transaction')
+      }),
+    ).rejects.toThrow('Failed transaction')
+    const second = Credentials.store({ file })
+    await second.set('https://api.tempo.xyz', session)
+    expect(await first.get('https://api.tempo.xyz')).toEqual(session)
+  })
+})
+
+describe('defaultFile', () => {
+  test('lives under the Tempo home directory', () => {
+    expect(Credentials.defaultFile({ home: '/tmp/tempo-home' })).toBe(
+      '/tmp/tempo-home/api/credentials.json',
+    )
+    expect(Credentials.defaultFile()).toBe(
+      path.join(os.homedir(), '.tempo', 'api', 'credentials.json'),
+    )
+  })
+})

package/src/cli/Credentials.ts

@@ -0,0 +1,144 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as lockfile from 'proper-lockfile'
+import * as z from 'zod/mini'
+
+/** Stored CLI credentials: one CLI session per API origin. */
+export type Store = {
+  /** Reads the unexpired session for an API URL. */
+  get: (apiUrl: string | URL) => Promise<Session | undefined>
+  /** Forgets the session for an API URL. */
+  remove: (apiUrl: string | URL) => Promise<void>
+  /** Saves the session for an API URL. */
+  set: (apiUrl: string | URL, session: Session) => Promise<void>
+  /** Serializes credential operations across processes, passing an unlocked store to the callback. */
+  withLock?: (<result>(fn: (store: Store) => Promise<result>) => Promise<result>) | undefined
+}
+
+/** Storage schemas for the credentials file. */
+export namespace schema {
+  /** A project API key inferred from the approved CLI session. */
+  export const ApiKey = z.object({
+    environment: z.enum(['production', 'sandbox']),
+    expiresAt: z.optional(z.string()),
+    id: z.string(),
+    orgId: z.string(),
+    projectId: z.string(),
+    scopes: z.array(z.string()),
+    sourceKeyId: z.optional(z.string()),
+    token: z.string(),
+  })
+  /** A signed-in CLI session. */
+  export const Session = z.object({
+    apiKeys: z.optional(z.array(ApiKey)),
+    email: z.optional(z.string()),
+    expiresAt: z.string(),
+    scopes: z.optional(z.array(z.string())),
+    token: z.string(),
+    userId: z.string(),
+  })
+
+  /** The credentials file. */
+  export const File = z.object({
+    sessions: z.record(z.string(), Session),
+    version: z.literal(1),
+  })
+}
+
+/** A signed-in CLI session. */
+export type Session = z.output<typeof schema.Session>
+
+type File = z.output<typeof schema.File>
+
+/** Default credentials file: `<home>/api/credentials.json`, with `home` defaulting to `~/.tempo`. */
+export function defaultFile(options: defaultFile.Options = {}): string {
+  return path.join(options.home || path.join(os.homedir(), '.tempo'), 'api', 'credentials.json')
+}
+
+export declare namespace defaultFile {
+  /** Options for {@link defaultFile}. */
+  type Options = {
+    /** Tempo CLI home directory. @default '~/.tempo' */
+    home?: string | undefined
+  }
+}
+
+/** Creates a credentials store backed by a private JSON file. */
+export function store(options: store.Options = {}): Store {
+  const { file = defaultFile() } = options
+
+  async function read(): Promise<File> {
+    const text = await fs.readFile(file, 'utf8').catch((error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return undefined
+      throw error
+    })
+    if (text === undefined) return { sessions: {}, version: 1 }
+    // An unreadable file is treated as signed out rather than blocking every command.
+    const parsed = (() => {
+      try {
+        return schema.File.safeParse(JSON.parse(text))
+      } catch {
+        return undefined
+      }
+    })()
+    return parsed?.success ? parsed.data : { sessions: {}, version: 1 }
+  }
+
+  async function write(value: File) {
+    await fs.mkdir(path.dirname(file), { mode: 0o700, recursive: true })
+    // Write then rename so a crash never leaves a truncated file; 0600 keeps tokens private.
+    const temporary = `${file}.${process.pid}.tmp`
+    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+    await fs.rename(temporary, file)
+  }
+
+  const unlocked: Store = {
+    async get(apiUrl) {
+      const session = (await read()).sessions[new URL(apiUrl).origin]
+      if (!session || Date.parse(session.expiresAt) <= Date.now()) return undefined
+      return session
+    },
+    async remove(apiUrl) {
+      const value = await read()
+      const origin = new URL(apiUrl).origin
+      if (!(origin in value.sessions)) return
+      delete value.sessions[origin]
+      await write(value)
+    },
+    async set(apiUrl, session) {
+      const value = await read()
+      value.sessions[new URL(apiUrl).origin] = session
+      await write(value)
+    },
+  }
+
+  async function withLock<result>(fn: (store: Store) => Promise<result>): Promise<result> {
+    await fs.mkdir(path.dirname(file), { mode: 0o700, recursive: true })
+    const directory = await fs.realpath(path.dirname(file))
+    const release = await lockfile.lock(path.join(directory, path.basename(file)), {
+      realpath: false,
+      retries: { factor: 1, maxTimeout: 100, minTimeout: 100, retries: 600 },
+    })
+    try {
+      return await fn(unlocked)
+    } finally {
+      await release()
+    }
+  }
+
+  return {
+    get: unlocked.get,
+    remove: (apiUrl) => withLock((store) => store.remove(apiUrl)),
+    set: (apiUrl, session) => withLock((store) => store.set(apiUrl, session)),
+    withLock,
+  }
+}
+
+export declare namespace store {
+  /** Options for {@link store}. */
+  type Options = {
+    /** Credentials file path. @default defaultFile() */
+    file?: string | undefined
+  }
+}