@kindgi/api 0.1.4 → 0.1.5

package/src/routes/segments.ts

@@ -61,6 +61,17 @@ export function parseSegmentsBody(raw: unknown, field = 'segments'): Parsed {
   return checked(segments, field);
 }
 
+/** Whether a segment path is `prefix` or below it (`company=acme/role=cfo` is in `company=acme`). */
+export function segmentsStartWith(
+  path: readonly ScopeSegment[],
+  prefix: readonly ScopeSegment[],
+): boolean {
+  return (
+    path.length >= prefix.length &&
+    prefix.every((s, i) => path[i]?.key === s.key && path[i]?.value === s.value)
+  );
+}
+
 /** The same from a query: repeated `segment=key:value`, in order. */
 export function parseSegmentsQuery(values: readonly string[]): Parsed {
   const segments: ScopeSegment[] = [];

package/src/routes/service-accounts.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+
+import type { ProjectRole } from '@kindgi/platform';
+import type { Cursor, Result, TenantId } from '@kindgi/types';
+
+import { callerRef, isTenantAdmin } from '../caller.js';
+import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type {
+  ServiceAccount,
+  ServiceAccountBinding,
+  ServiceAccountError,
+  ServiceAccountGrant,
+  ServiceAccountGrantTarget,
+} from '../service-account-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/** Lowercase letters, digits and hyphens, starting with a letter or digit. */
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const MAX_DESCRIPTION_LENGTH = 500;
+const PROJECT_ROLES: readonly ProjectRole[] = ['viewer', 'editor', 'owner', 'admin', 'member'];
+
+/**
+ * Service accounts (`/v1/service-accounts`), for tenant admins:
+ *
+ * - `POST /` creates one, with its first grants: `{name, description?, grants?}`;
+ * - `GET /` lists them, oldest first (`?includeUnregistered=true` for all);
+ * - `GET /:serviceAccountId` reads one, unregistered or not;
+ * - `POST /:serviceAccountId/grant` adds a grant; `/ungrant` removes one;
+ * - `POST /:serviceAccountId/unregister` tombstones it: grants gone, keys dead.
+ *
+ * Keys for an account are minted at `POST /v1/tokens` with `for`.
+ */
+export function serviceAccountsRouter(
+  binding: ServiceAccountBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  r.use('/*', async (c, next) => {
+    if (!(await isTenantAdmin(c, authorizer))) {
+      return fail(c, {
+        code: 'permission-denied',
+        message: 'Only a tenant admin manages service accounts',
+      });
+    }
+    await next();
+    return;
+  });
+
+  r.post('/', async (c) => {
+    const body = await readBody(c);
+    if (body.kind === 'err') return fail(c, body.error);
+    const parsed = parseCreateBody(body.value);
+    if (parsed.kind === 'err') return fail(c, parsed.error);
+    const createdBy = callerRef(c);
+    const created = await binding.create({
+      tenantId: tenantOf(c),
+      ...parsed.value,
+      ...(createdBy !== undefined && { createdBy }),
+    });
+    return respond(c, created, 201);
+  });
+
+  r.get('/', async (c) => {
+    const cursor = c.req.query('cursor');
+    const page = await binding.list({
+      tenantId: tenantOf(c),
+      limit: clampLimit(c.req.query('limit')),
+      ...(cursor !== undefined && cursor !== '' && { cursor: cursor as Cursor }),
+      ...(c.req.query('includeUnregistered') === 'true' && { includeUnregistered: true }),
+    });
+    return c.json({
+      data: page.data.map(toWire),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  r.get('/:serviceAccountId', async (c) => {
+    const serviceAccountId = c.req.param('serviceAccountId');
+    const account = await binding.get({ tenantId: tenantOf(c), serviceAccountId });
+    if (account === null) return fail(c, notFound(serviceAccountId));
+    return c.json(toWire(account));
+  });
+
+  r.post('/:serviceAccountId/grant', async (c) => {
+    const body = await readBody(c);
+    if (body.kind === 'err') return fail(c, body.error);
+    const grant = parseGrant(body.value);
+    if (grant.kind === 'err') return fail(c, grant.error);
+    const serviceAccountId = c.req.param('serviceAccountId');
+    return respond(
+      c,
+      await binding.grant({
+        tenantId: tenantOf(c),
+        serviceAccountId,
+        grant: grant.value,
+        ...byCaller(c),
+      }),
+    );
+  });
+
+  r.post('/:serviceAccountId/ungrant', async (c) => {
+    const body = await readBody(c);
+    if (body.kind === 'err') return fail(c, body.error);
+    const grant = parseGrantTarget(body.value);
+    if (grant.kind === 'err') return fail(c, grant.error);
+    const serviceAccountId = c.req.param('serviceAccountId');
+    return respond(
+      c,
+      await binding.ungrant({
+        tenantId: tenantOf(c),
+        serviceAccountId,
+        grant: grant.value,
+        ...byCaller(c),
+      }),
+    );
+  });
+
+  r.post('/:serviceAccountId/unregister', async (c) => {
+    const serviceAccountId = c.req.param('serviceAccountId');
+    return respond(
+      c,
+      await binding.unregister({ tenantId: tenantOf(c), serviceAccountId, ...byCaller(c) }),
+    );
+  });
+
+  return r;
+}
+
+type WireError = { readonly code: string; readonly message: string };
+type Parsed<T> = { kind: 'ok'; value: T } | { kind: 'err'; error: WireError };
+
+/** Who made the change, for the record. */
+function byCaller(c: Context<AppEnv>): { by?: string } {
+  const by = callerRef(c);
+  return by !== undefined ? { by } : {};
+}
+
+function tenantOf(c: Context<AppEnv>): TenantId {
+  return c.get('tenantId') as TenantId;
+}
+
+function fail(c: Context<AppEnv>, error: WireError): Response {
+  c.status(statusFor(error.code) as never);
+  return c.json(toWireError(error, c.get('requestId')));
+}
+
+function notFound(serviceAccountId: string): WireError {
+  return {
+    code: 'service-account-not-found',
+    message: `No service account with id "${serviceAccountId}" in this tenant`,
+  };
+}
+
+function respond(
+  c: Context<AppEnv>,
+  result: Result<ServiceAccount, ServiceAccountError>,
+  status: 200 | 201 = 200,
+): Response {
+  if (result.kind === 'err') return fail(c, result.error);
+  c.status(status);
+  return c.json(toWire(result.value));
+}
+
+function toWire(a: ServiceAccount): Record<string, unknown> {
+  return {
+    serviceAccountId: a.serviceAccountId,
+    name: a.name,
+    ...(a.description !== undefined && { description: a.description }),
+    grants: a.grants,
+    ...(a.createdBy !== undefined && { createdBy: a.createdBy }),
+    createdAt: a.createdAt,
+    ...(a.unregisteredAt !== undefined && { unregisteredAt: a.unregisteredAt }),
+  };
+}
+
+async function readBody(c: Context<AppEnv>): Promise<Parsed<Record<string, unknown>>> {
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    return badInput('Request body must be a JSON object');
+  }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return badInput('Request body must be a JSON object');
+  }
+  return { kind: 'ok', value: body as Record<string, unknown> };
+}
+
+function badInput(message: string): { kind: 'err'; error: WireError } {
+  return { kind: 'err', error: { code: 'bad-input', message } };
+}
+
+function parseCreateBody(b: Record<string, unknown>): Parsed<{
+  name: string;
+  description?: string;
+  grants: readonly ServiceAccountGrant[];
+}> {
+  if (typeof b.name !== 'string' || !NAME_RE.test(b.name)) {
+    return badInput(
+      '`name` must be 1-63 lowercase letters, digits or hyphens, starting with a letter or digit',
+    );
+  }
+  if (
+    b.description !== undefined &&
+    (typeof b.description !== 'string' || b.description.length > MAX_DESCRIPTION_LENGTH)
+  ) {
+    return badInput(
+      `\`description\` must be a string of at most ${MAX_DESCRIPTION_LENGTH} characters`,
+    );
+  }
+  if (b.grants !== undefined && !Array.isArray(b.grants)) {
+    return badInput('`grants` must be an array of grants');
+  }
+  const grants: ServiceAccountGrant[] = [];
+  for (const raw of (b.grants as unknown[] | undefined) ?? []) {
+    const grant = parseGrant(raw);
+    if (grant.kind === 'err') return grant;
+    grants.push(grant.value);
+  }
+  return {
+    kind: 'ok',
+    value: {
+      name: b.name,
+      ...(typeof b.description === 'string' && { description: b.description }),
+      grants,
+    },
+  };
+}
+
+/** `{kind: 'tenant-admin'}`, `{kind: 'tenant-member'}` or `{kind: 'project', projectId, role}`. */
+function parseGrant(raw: unknown): Parsed<ServiceAccountGrant> {
+  const target = parseGrantTarget(raw);
+  if (target.kind === 'err') return target;
+  if (target.value.kind !== 'project') return { kind: 'ok', value: target.value };
+  const role = (raw as { role?: unknown }).role;
+  if (typeof role !== 'string' || !PROJECT_ROLES.includes(role as ProjectRole)) {
+    return badInput(`A project grant's \`role\` must be one of: ${PROJECT_ROLES.join(', ')}`);
+  }
+  return { kind: 'ok', value: { ...target.value, role: role as ProjectRole } };
+}
+
+/** `{kind: 'tenant-admin'}`, `{kind: 'tenant-member'}` or `{kind: 'project', projectId}`. */
+function parseGrantTarget(raw: unknown): Parsed<ServiceAccountGrantTarget> {
+  const g = (raw ?? {}) as { kind?: unknown; projectId?: unknown };
+  if (g.kind === 'tenant-admin') return { kind: 'ok', value: { kind: 'tenant-admin' } };
+  if (g.kind === 'tenant-member') return { kind: 'ok', value: { kind: 'tenant-member' } };
+  if (g.kind === 'project') {
+    if (typeof g.projectId !== 'string' || g.projectId === '') {
+      return badInput('A project grant needs `projectId`');
+    }
+    return { kind: 'ok', value: { kind: 'project', projectId: g.projectId } };
+  }
+  return badInput("A grant's `kind` must be 'tenant-admin', 'tenant-member' or 'project'");
+}

package/src/routes/sign-in-options.ts

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { IdentityProviderBinding, SignInOption } from '../identity-provider-binding.js';
+import type { AppEnv } from '../types.js';
+
+/**
+ * `GET /v1/auth/sign-in-options?email=`: how a person can sign in, before
+ * anyone is signed in. Mounted outside the auth chain.
+ *
+ * It answers by the email's DOMAIN only, so the answer for two people at
+ * the same domain is the same byte for byte, whether or not either of
+ * them has an account: it can't be used to find out who does. Requests
+ * are rate-limited per client, as a speed bump against scraping.
+ *
+ * Email first: without an email, nothing is offered (an empty list), and
+ * the binding isn't asked. `methods` tells a sign-in page which ways in
+ * there are; always mounted, so with none it says so (both `false`).
+ */
+export interface SignInOptionsRouteOptions {
+  /** Absent: no sign-in with identity providers here (only an API token, if allowed). */
+  readonly identityProvider?: IdentityProviderBinding;
+  /** Whether a person may sign in to the console with an API token here. */
+  readonly tokenSignIn: boolean;
+  /**
+   * The emailed sign-in link, when the deployment offers it: a sign-in page
+   * shows "Email me a sign-in link", with the Turnstile widget when there's
+   * a site key. `allowedFor`: whether it's offered for an email's domain
+   * (say, not where a workspace signs its people in with its own identity
+   * provider). Absent: for every domain.
+   */
+  readonly emailLink?: {
+    readonly captchaSiteKey?: string;
+    readonly allowedFor?: (emailDomain: string) => Promise<boolean>;
+  };
+  readonly rateLimit?: SignInOptionsRateLimit;
+}
+
+export interface SignInOptionsRateLimit {
+  /** Requests per client per window. Default 30. */
+  readonly limit?: number;
+  /** Default 60 000 ms. */
+  readonly windowMs?: number;
+  /**
+   * Who the client is. Default: the nearest `X-Forwarded-For` hop (the
+   * rightmost, written by the proxy in front), else one shared bucket;
+   * never the leftmost, which the client writes. A deployment that knows
+   * its client's address (the socket's, or past its trusted proxies)
+   * passes its own.
+   */
+  readonly clientKey?: (request: Request) => string;
+}
+
+const DEFAULT_LIMIT = 30;
+const DEFAULT_WINDOW_MS = 60_000;
+// The bucket map is pruned once it holds this many clients.
+const MAX_TRACKED_CLIENTS = 10_000;
+
+// One `@`, a non-empty local part, and a domain with a dot.
+const EMAIL_RE = /^[^\s@]+@([^\s@]+\.[^\s@]+)$/;
+
+export function signInOptionsRouter(options: SignInOptionsRouteOptions): Hono<AppEnv> {
+  const { identityProvider } = options;
+  const limit = options.rateLimit?.limit ?? DEFAULT_LIMIT;
+  const windowMs = options.rateLimit?.windowMs ?? DEFAULT_WINDOW_MS;
+  const clientKey = options.rateLimit?.clientKey ?? defaultClientKey;
+  const buckets = new Map<string, { windowStart: number; count: number }>();
+
+  const router = new Hono<AppEnv>();
+  router.get('/', async (c) => {
+    const requestId = c.get('requestId');
+
+    const now = Date.now();
+    const key = clientKey(c.req.raw);
+    const bucket = buckets.get(key);
+    if (bucket === undefined || now - bucket.windowStart >= windowMs) {
+      if (buckets.size >= MAX_TRACKED_CLIENTS) pruneExpired(buckets, now, windowMs);
+      buckets.set(key, { windowStart: now, count: 1 });
+    } else if (bucket.count >= limit) {
+      const retryAfter = Math.ceil((bucket.windowStart + windowMs - now) / 1000);
+      c.header('Retry-After', String(Math.max(retryAfter, 1)));
+      c.status(statusFor('rate-limit-exceeded') as never);
+      return c.json(
+        toWireError(
+          { code: 'rate-limit-exceeded', message: 'Too many sign-in lookups: try again shortly' },
+          requestId,
+        ),
+      );
+    } else {
+      bucket.count += 1;
+    }
+
+    const email = c.req.query('email');
+    let emailDomain: string | undefined;
+    if (email !== undefined) {
+      const match = EMAIL_RE.exec(email.trim());
+      if (match === null) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: '`email` must be an email address' },
+            requestId,
+          ),
+        );
+      }
+      emailDomain = (match[1] as string).toLowerCase();
+    }
+
+    const offered: readonly SignInOption[] =
+      identityProvider?.signInOptions === undefined || emailDomain === undefined
+        ? []
+        : await identityProvider.signInOptions({ emailDomain });
+    const emailLink = options.emailLink;
+    const linkOffered =
+      emailLink !== undefined &&
+      (emailDomain === undefined ||
+        emailLink.allowedFor === undefined ||
+        (await emailLink.allowedFor(emailDomain)));
+    c.header('Cache-Control', 'no-store');
+    return c.json({
+      data: offered.map((o) => ({
+        providerId: o.providerId,
+        displayName: o.displayName,
+        signInUrl: o.signInUrl,
+        ...(o.owner !== undefined && { owner: o.owner }),
+      })),
+      methods: {
+        identityProviders: identityProvider !== undefined,
+        apiToken: options.tokenSignIn,
+        ...(linkOffered && {
+          emailLink: {
+            ...(emailLink.captchaSiteKey !== undefined && {
+              captchaSiteKey: emailLink.captchaSiteKey,
+            }),
+          },
+        }),
+      },
+    });
+  });
+  return router;
+}
+
+function defaultClientKey(request: Request): string {
+  const hops = (request.headers.get('x-forwarded-for') ?? '')
+    .split(',')
+    .map((h) => h.trim())
+    .filter((h) => h !== '');
+  return hops.at(-1) ?? 'shared';
+}
+
+function pruneExpired(
+  buckets: Map<string, { windowStart: number; count: number }>,
+  now: number,
+  windowMs: number,
+): void {
+  for (const [k, b] of buckets) {
+    if (now - b.windowStart >= windowMs) buckets.delete(k);
+  }
+  // Still full: every client is mid-window. Drop the oldest half rather
+  // than grow without bound.
+  if (buckets.size >= MAX_TRACKED_CLIENTS) {
+    const keys = [...buckets.keys()].slice(0, Math.floor(MAX_TRACKED_CLIENTS / 2));
+    for (const k of keys) buckets.delete(k);
+  }
+}

package/src/routes/signing-keys.ts

@@ -6,10 +6,12 @@ import { type Context, Hono } from 'hono';
 import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { SigningKeyBinding, TrustedKey } from '../signing-key-binding.js';
 import type { AppEnv } from '../types.js';
 import { hasCapability } from './env.js';
 import { clampLimit } from './pagination.js';
+import { tenantResourceAccess } from './tenant-access.js';
 
 /**
  * The tenant's trusted signing keys: the public keys whose signatures
@@ -29,8 +31,12 @@ import { clampLimit } from './pagination.js';
  * Writes need the `signing-keys:write` capability; reads, the tenant's
  * bearer.
  */
-export function signingKeysRouter(binding: SigningKeyBinding): Hono<AppEnv> {
+export function signingKeysRouter(
+  binding: SigningKeyBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  r.use('*', tenantResourceAccess(authorizer));
 
   // ---------- POST / (trust a key) ----------
   r.post('/', async (c) => {

package/src/routes/tenant-access.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import { ref } from '@kindgi/authz';
+
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+
+/**
+ * Access to a tenant-wide resource (providers, policies, adapters, …):
+ * reading it needs `read` on the tenant, anything else `admin`. The
+ * authorization model gives a tenant no `write`, so a tenant-wide change
+ * is an admin's. Without an authorizer, nothing is checked (as before).
+ */
+export function tenantResourceAccess(
+  authorizer: Authorizer | undefined,
+): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (authorizer === undefined) return next();
+    const reading = c.req.method === 'GET' || c.req.method === 'HEAD';
+    return authorizer.authorize(reading ? 'read' : 'admin', (ctx) =>
+      ref('tenant', ctx.get('tenantId') as unknown as string),
+    )(c, next);
+  };
+}
+
+/** Access to a tenant setting every call of which is an admin's (webhook endpoints, compliance). */
+export function tenantAdminAccess(authorizer: Authorizer | undefined): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (authorizer === undefined) return next();
+    return authorizer.authorize('admin', (ctx) =>
+      ref('tenant', ctx.get('tenantId') as unknown as string),
+    )(c, next);
+  };
+}

package/src/routes/tenant.ts

@@ -148,6 +148,12 @@ export function tenantRouter(options: TenantRouterOptions): Hono<AppEnv> {
       '*',
       authorizer.authorize('read', (c) => ref('tenant', c.get('tenantId') as unknown as string)),
     );
+    // Changing the config writes the tenant's secrets and env: `admin`
+    // on the tenant (T243 A), as every tenant-wide write.
+    const admin = authorizer.authorize('admin', (c) =>
+      ref('tenant', c.get('tenantId') as unknown as string),
+    );
+    r.use('/config', async (c, next) => (c.req.method === 'PATCH' ? admin(c, next) : next()));
   }
 
   // ---------- GET / ----------

package/src/routes/token-sign-in.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import { Hono } from 'hono';
+import { setCookie } from 'hono/cookie';
+
+import type { AuditEvent, AuditEventBinding } from '@kindgi/audit-events';
+import type { Timestamp } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import { encodeSessionToken } from '../middleware/auth.js';
+import { withholdFromReplay } from '../middleware/idempotency.js';
+import type { SessionStoreBinding } from '../session-store-binding.js';
+import type { AppEnv } from '../types.js';
+
+/**
+ * `POST /v1/auth/token-sign-in`: a person signs in to the console with an
+ * API token. The token comes once, in `Authorization`, and is exchanged for
+ * a browser session in the session cookie (HttpOnly, the same as a sign-in
+ * with an identity provider), so the browser never keeps it.
+ *
+ * Only a person's **full** key opens a session. A service account's key is
+ * for machines, and a narrowed key (a `member` role, or one project) would
+ * be widened to the person's full grants by a session: both are refused,
+ * 403 `token-sign-in-not-allowed`. The session acts as the key did: it
+ * carries the key's scopes (a deployment without an authorizer reads tenant
+ * admin from them; a key's scopes never change after it's minted). It never
+ * outlives the key: it ends when the key expires, and, with a store that has
+ * `revokeByProvider`, when the key is revoked (its `providerId` is
+ * `api-token:<tokenId>`).
+ * Refusals are audited (`sign-in-refused`), as is each sign-in.
+ */
+export type TokenSignInRouteOptions =
+  /** The deployment doesn't allow it, or has no browser sessions: 403 `token-sign-in-off`. */
+  | { readonly enabled: false }
+  | {
+      readonly enabled: true;
+      readonly sessionStore: SessionStoreBinding;
+      /** The session's lifetime, in milliseconds. */
+      readonly ttlMs: number;
+      readonly cookieName: string;
+      /** `signed-in` events, best effort. */
+      readonly auditEvents?: AuditEventBinding;
+    };
+
+export function tokenSignInRouter(options: TokenSignInRouteOptions): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    /** An audit event, best effort: a failure is logged, never the answer. */
+    const auditEvents = options.enabled ? options.auditEvents : undefined;
+    const audit = async (event: Omit<AuditEvent, 'id' | 'timestamp'>) => {
+      if (auditEvents === undefined) return;
+      try {
+        const appended = await auditEvents.append([
+          { ...event, id: randomUUID(), timestamp: new Date().toISOString() as Timestamp },
+        ]);
+        if (appended.kind === 'err') {
+          c.get('log').warn(`${event.kind} audit event failed: ${appended.error.message}`);
+        }
+      } catch (cause) {
+        c.get('log').warn(
+          `${event.kind} audit event failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+    };
+    const refuse = async (code: string, message: string) => {
+      const userId = c.get('userId');
+      const serviceAccountId = c.get('serviceAccountId');
+      await audit({
+        tenantId: c.get('tenantId'),
+        kind: 'sign-in-refused',
+        actor:
+          serviceAccountId !== undefined
+            ? `service_account:${serviceAccountId}`
+            : userId !== undefined
+              ? `user:${userId}`
+              : 'system',
+        outcome: 'denied',
+        payload: { v: 1, doc: { method: 'api-token', reason: code } },
+      });
+      c.status(statusFor(code) as never);
+      return c.json(toWireError({ code, message }, requestId));
+    };
+
+    if (!options.enabled) {
+      return refuse(
+        'token-sign-in-off',
+        "This deployment doesn't allow signing in to the console with an API token. Sign in with your organization's identity provider, or ask whoever runs Kindgi to allow it.",
+      );
+    }
+    if (c.get('sessionId') !== undefined) {
+      return refuse(
+        'token-sign-in-needs-an-api-token',
+        'You are already signed in with a session: token sign-in takes an API token in the Authorization header.',
+      );
+    }
+    const tenantId = c.get('tenantId');
+    const userId = c.get('userId');
+    if (c.get('serviceAccountId') !== undefined || userId === undefined) {
+      return refuse(
+        'token-sign-in-not-allowed',
+        "Only a person's API key can open a console session; a service account's key is for machines.",
+      );
+    }
+    if (c.get('tokenRole') === 'member' || c.get('tokenProjectId') !== undefined) {
+      return refuse(
+        'token-sign-in-not-allowed',
+        "A narrowed key (a member role, or one project) can't open a console session: the session would carry all of your permissions. Use a full key, or sign in with your identity provider.",
+      );
+    }
+
+    const keyExpiresAt = c.get('tokenExpiresAt');
+    const expires = Math.min(
+      Date.now() + options.ttlMs,
+      keyExpiresAt === undefined ? Number.POSITIVE_INFINITY : keyExpiresAt.getTime(),
+    );
+    const tokenId = c.get('tokenId');
+    const created = await options.sessionStore.create({
+      tenantId,
+      userId,
+      providerId: tokenId === undefined ? 'api-token' : `api-token:${tokenId}`,
+      expiresAt: new Date(expires).toISOString() as Timestamp,
+      // What the key may do, so the session acts as it did: with authz off,
+      // an admin key's `tenant-admin` is how the server and console know.
+      scopes: [...(c.get('scopes') ?? [])],
+    });
+    setCookie(c, options.cookieName, created.token ?? encodeSessionToken(created.sessionId), {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'Lax',
+      path: '/',
+      maxAge: Math.max(0, Math.floor((expires - Date.now()) / 1000)),
+    });
+
+    await audit({
+      tenantId,
+      kind: 'signed-in',
+      actor: `user:${userId}`,
+      outcome: 'succeeded',
+      payload: {
+        v: 1,
+        doc: {
+          method: 'api-token',
+          sessionId: created.sessionId,
+          ...(tokenId !== undefined && { tokenId }),
+        },
+      },
+    });
+
+    // The session is in the cookie, which a stored answer doesn't keep: a
+    // repeat with the same Idempotency-Key is refused, not "signed in".
+    withholdFromReplay(c);
+    return c.json({ userId, expiresAt: new Date(expires).toISOString() });
+  });
+
+  return r;
+}