@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/reviewer-binding.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type { Cursor, ReviewerId, TenantId, Timestamp, UserId } from '@kindgi/types';
+
+/**
+ * Translates the bearer-token identity (`UserId`) into the `ReviewerId`
+ * that `HitlBinding.submitReview` needs. The API package intentionally does
+ * NOT own the `user ↔ reviewer` mapping — deployments plug that in via
+ * this binding, same pattern as `TokenResolver` (for auth read) and
+ * `TokenAdmin` (for mint/revoke).
+ *
+ * Return `null` when the user has no registered reviewer row for the
+ * tenant (leads to `403 permission-denied` from the approvals route).
+ */
+export interface ReviewerBinding {
+  resolveReviewer(input: ReviewerLookupInput): Promise<ReviewerId | null>;
+}
+
+export interface ReviewerLookupInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+// ================ ReviewerRegistryBinding ================
+
+/**
+ * Caller-plugged surface for the reviewer roster. Same pattern as
+ * `AgentRegistryBinding` / `ToolRegistryBinding`: the API package does
+ * NOT own persistence. Deployments wire the runtime's reviewer store —
+ * or their own — through this binding.
+ *
+ * Distinct from `ReviewerBinding` (which resolves a token's `UserId` to
+ * a `ReviewerId`): a deployment may want a durable registry backend for
+ * the roster surface while keeping the resolver in-process. Callers
+ * mount them independently.
+ */
+export interface ReviewerRegistryBinding {
+  list(input: ReviewerListInput): Promise<ReviewerPage>;
+  get(input: ReviewerGetInput): Promise<ReviewerRecord | null>;
+  register(input: ReviewerRegisterInput): Promise<ReviewerRegisterOutcome>;
+  /**
+   * Unregister a reviewer. Semantic is "soft-delete / deactivate" so
+   * the audit trail survives — reviewer stops receiving approvals but
+   * historical decisions still resolve. Returns
+   * `{ unregistered: false }` when the id is unknown; the route flips
+   * that to `404`.
+   */
+  unregister(input: ReviewerUnregisterInput): Promise<ReviewerUnregisterOutcome>;
+}
+
+export interface ReviewerListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly role?: ReviewerRole;
+}
+
+export interface ReviewerGetInput {
+  readonly tenantId: TenantId;
+  readonly reviewerId: ReviewerId;
+}
+
+export interface ReviewerRegisterInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+  readonly role: ReviewerRole;
+  readonly displayName?: string;
+}
+
+export interface ReviewerUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly reviewerId: ReviewerId;
+}
+
+export interface ReviewerRecord {
+  readonly id: ReviewerId;
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+  readonly role: ReviewerRole;
+  readonly displayName?: string;
+  readonly createdAt: Timestamp;
+  readonly deactivatedAt?: Timestamp;
+}
+
+export interface ReviewerPage {
+  readonly data: readonly ReviewerRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export type ReviewerRegisterOutcome = {
+  readonly kind: 'ok';
+  readonly reviewer: ReviewerRecord;
+};
+
+export type ReviewerUnregisterOutcome = {
+  readonly unregistered: boolean;
+};

package/src/rotation-status-store.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import type { Scope } from '@kindgi/platform';
+import type { EnvName } from '@kindgi/types';
+
+/**
+ * Rotation-status store — durable substrate for the
+ * async-rotation wire. When a
+ * `SecretProviderBinding.rotateSecret` call returns the
+ * `rotation-pending` variant, the HTTP route mints a `rotationId` via
+ * this store, records the pending status, and returns 202 with a
+ * `statusUrl` + `eventsUrl` a caller can poll or subscribe to.
+ *
+ * A background reaper (not owned by this store) drives the pending
+ * rotation to terminal by polling the provider with the recorded
+ * `resumeToken`, then calling `update({ status: 'succeeded' | 'failed',
+ *  … })`. Subscribed SSE streams receive the update via `subscribe`.
+ *
+ * The bundled implementation (`createInMemoryRotationStatusStore`) is
+ * in-memory only (dev + tests). Production deployments plug in a durable
+ * adapter that survives process restarts — an async rotation can take
+ * minutes to hours, so process-local state is not sufficient.
+ */
+export interface RotationStatusStore {
+  /**
+   * Mint a new rotation-status row. Returns the freshly-minted
+   * `rotationId` (UUID) that the wire response echoes back to the
+   * caller. `resumeToken` + `provider` are the opaque provider-side
+   * handles the reaper uses to poll the async workflow; the wire
+   * response NEVER exposes them.
+   */
+  create(input: RotationStatusCreateInput): Promise<{ readonly rotationId: string }>;
+
+  /** Read the current status, or `null` when unknown / cross-scope. */
+  get(input: RotationStatusGetInput): Promise<RotationStatus | null>;
+
+  /**
+   * Terminal-transition write. Called by the reaper (or an explicit
+   * admin op) when the async workflow completes. Publishes to every
+   * live SSE subscription for the `rotationId`.
+   */
+  update(input: RotationStatusUpdateInput): Promise<void>;
+
+  /**
+   * Subscribe to lifecycle updates for a single `rotationId`. Returns
+   * an unsubscribe function that the caller MUST call on stream close
+   * / client disconnect to avoid memory leaks.
+   */
+  subscribe(input: RotationStatusSubscribeInput): () => void;
+}
+
+export interface RotationStatusCreateInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly provider: string;
+  readonly resumeToken: string;
+}
+
+export interface RotationStatusGetInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly rotationId: string;
+}
+
+export interface RotationStatusUpdateInput {
+  readonly rotationId: string;
+  readonly status: 'succeeded' | 'failed';
+  readonly newVersionId?: number;
+  readonly oldVersionId?: number;
+  readonly error?: string;
+}
+
+export interface RotationStatusSubscribeInput {
+  readonly rotationId: string;
+  readonly onUpdate: (status: RotationStatus) => void;
+}
+
+/**
+ * Wire-safe rotation-status shape. `startedAt` + `updatedAt` are ISO
+ * 8601 strings. Terminal states populate `newVersionId` /
+ * `oldVersionId` (on `succeeded`) or `error` (on `failed`); pending
+ * states leave them absent.
+ */
+export interface RotationStatus {
+  readonly rotationId: string;
+  readonly status: 'pending' | 'succeeded' | 'failed';
+  readonly startedAt: string;
+  readonly updatedAt: string;
+  readonly newVersionId?: number;
+  readonly oldVersionId?: number;
+  readonly error?: string;
+}
+
+/**
+ * In-memory reference `RotationStatusStore` — dev + tests only.
+ * Retains a `Map<rotationId, InternalRow>` for the lifetime of the
+ * process; multi-pod deployments MUST plug in a durable adapter (the
+ * rotation-status row must survive between the pod that minted the
+ * `rotationId` and any pod handling a poll or SSE subscribe).
+ */
+export function createInMemoryRotationStatusStore(options?: {
+  readonly now?: () => number;
+}): RotationStatusStore {
+  interface Row {
+    readonly rotationId: string;
+    readonly scopeKey: string;
+    readonly envName: EnvName;
+    readonly name: string;
+    readonly provider: string;
+    readonly resumeToken: string;
+    status: 'pending' | 'succeeded' | 'failed';
+    readonly startedAt: string;
+    updatedAt: string;
+    newVersionId?: number;
+    oldVersionId?: number;
+    error?: string;
+  }
+
+  const rows = new Map<string, Row>();
+  const subscribers = new Map<string, Set<(s: RotationStatus) => void>>();
+  const now = options?.now ?? (() => Date.now());
+
+  const toStatus = (row: Row): RotationStatus => ({
+    rotationId: row.rotationId,
+    status: row.status,
+    startedAt: row.startedAt,
+    updatedAt: row.updatedAt,
+    ...(row.newVersionId !== undefined && { newVersionId: row.newVersionId }),
+    ...(row.oldVersionId !== undefined && { oldVersionId: row.oldVersionId }),
+    ...(row.error !== undefined && { error: row.error }),
+  });
+
+  return {
+    async create(input) {
+      const rotationId = randomUUID();
+      const ts = new Date(now()).toISOString();
+      rows.set(rotationId, {
+        rotationId,
+        scopeKey: scopeKey(input.scope),
+        envName: input.envName,
+        name: input.name,
+        provider: input.provider,
+        resumeToken: input.resumeToken,
+        status: 'pending',
+        startedAt: ts,
+        updatedAt: ts,
+      });
+      return { rotationId };
+    },
+    async get(input) {
+      const row = rows.get(input.rotationId);
+      if (row === undefined) return null;
+      // Cross-scope + cross-name reads return null — a caller looking
+      // for the rotation of secret X in project A cannot inadvertently
+      // observe the rotation of secret Y in project B.
+      if (row.scopeKey !== scopeKey(input.scope)) return null;
+      if (row.envName !== input.envName) return null;
+      if (row.name !== input.name) return null;
+      return toStatus(row);
+    },
+    async update(input) {
+      const row = rows.get(input.rotationId);
+      if (row === undefined) return;
+      row.status = input.status;
+      row.updatedAt = new Date(now()).toISOString();
+      if (input.newVersionId !== undefined) row.newVersionId = input.newVersionId;
+      if (input.oldVersionId !== undefined) row.oldVersionId = input.oldVersionId;
+      if (input.error !== undefined) row.error = input.error;
+      const status = toStatus(row);
+      const subs = subscribers.get(input.rotationId);
+      if (subs !== undefined) {
+        for (const cb of subs) {
+          try {
+            cb(status);
+          } catch {
+            // Subscriber-side crashes MUST NOT poison the store.
+          }
+        }
+      }
+    },
+    subscribe(input) {
+      const set = subscribers.get(input.rotationId) ?? new Set<(s: RotationStatus) => void>();
+      set.add(input.onUpdate);
+      subscribers.set(input.rotationId, set);
+      return () => {
+        const cur = subscribers.get(input.rotationId);
+        if (cur === undefined) return;
+        cur.delete(input.onUpdate);
+        if (cur.size === 0) subscribers.delete(input.rotationId);
+      };
+    },
+  };
+}
+
+function scopeKey(s: Scope): string {
+  switch (s.kind) {
+    case 'tenant':
+      return `tenant:${s.tenantId as unknown as string}`;
+    case 'org':
+      return `org:${s.tenantId as unknown as string}:${s.orgId as unknown as string}`;
+    case 'project':
+      return `project:${s.tenantId as unknown as string}:${s.projectId as unknown as string}`;
+  }
+}

package/src/routes/adapters.ts

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+
+import type { AdapterFactoryRegistry, PrepareEvent } from '@kindgi/capabilities';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import {
+  ADAPTER_KINDS,
+  ADAPTER_STATUSES,
+  type AdapterInfo,
+  type AdapterKind,
+  type AdapterRegistryBinding,
+  type AdapterStatus,
+  type AdapterTestOutcome,
+} from '../adapter-binding.js';
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Adapters resource routes — part of the admin control plane. Unified
+ * surface over every adapter kind the deployment wired: model
+ * providers, embedding providers, blob storage, sandbox providers,
+ * eval judges.
+ *
+ * Read-only over HTTP, plus a smoke-test probe and a prepare stream:
+ *
+ *   - `GET  /v1/adapters`                — cursor-paginated list with
+ *                                          optional `kind` / `status` filters.
+ *   - `GET  /v1/adapters/:adapterId`     — single adapter (404 if unknown).
+ *   - `POST /v1/adapters/:adapterId/test` — probe. Idempotency-Key applies.
+ *   - `POST /v1/adapters/:adapterId/prepare` — SSE stream of the
+ *                                          adapter's `prepare()` events.
+ *
+ * Adapter lifecycle (register / unregister / reconfigure) is a
+ * deployment concern — see `AdapterRegistryBinding` JSDoc. The routes
+ * here never mutate the wired set.
+ *
+ * Probe failures return HTTP 200 with `ok: false` — a failed probe is a
+ * valid observation, not a server error (`docs/API-ROUTE-CONVENTIONS.md` §4).
+ * The route only maps 5xx when the probe machinery itself broke.
+ */
+export function adaptersRouter(
+  binding: AdapterRegistryBinding,
+  factories?: AdapterFactoryRegistry,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- GET / (list, cursor-paginated) ----------
+  r.get('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+
+    const cursorRaw = c.req.query('cursor');
+    const kindRaw = c.req.query('kind');
+    const statusRaw = c.req.query('status');
+
+    let kindFilter: AdapterKind | undefined;
+    if (kindRaw !== undefined && kindRaw.length > 0) {
+      if (!(ADAPTER_KINDS as readonly string[]).includes(kindRaw)) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'bad-input',
+              message: `\`kind\` "${kindRaw}" is not a known adapter kind (one of: ${ADAPTER_KINDS.join(
+                ', ',
+              )})`,
+            },
+            requestId,
+          ),
+        );
+      }
+      kindFilter = kindRaw as AdapterKind;
+    }
+
+    let statusFilter: AdapterStatus | undefined;
+    if (statusRaw !== undefined && statusRaw.length > 0) {
+      if (!(ADAPTER_STATUSES as readonly string[]).includes(statusRaw)) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'bad-input',
+              message: `\`status\` "${statusRaw}" is not a known adapter status (one of: ${ADAPTER_STATUSES.join(
+                ', ',
+              )})`,
+            },
+            requestId,
+          ),
+        );
+      }
+      statusFilter = statusRaw as AdapterStatus;
+    }
+
+    const hasFilter = kindFilter !== undefined || statusFilter !== undefined;
+    const page = await binding.list({
+      tenantId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(hasFilter && {
+        filter: {
+          ...(kindFilter !== undefined && { kind: kindFilter }),
+          ...(statusFilter !== undefined && { status: statusFilter }),
+        },
+      }),
+    });
+    return c.json({
+      data: page.data.map(serializeAdapter),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:adapterId ----------
+  r.get('/:adapterId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const adapterId = c.req.param('adapterId');
+
+    const adapter = await binding.get({ tenantId, adapterId });
+    if (adapter === null) {
+      c.status(statusFor('adapter-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'adapter-not-found',
+            message: `No adapter registered with id "${adapterId}"`,
+            adapterId,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeAdapter(adapter));
+  });
+
+  // ---------- POST /:adapterId/test ----------
+  r.post('/:adapterId/test', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const adapterId = c.req.param('adapterId');
+
+    // Body is optional. Empty body OR `{}` OR omitted body → no
+    // `input` handed to the binding (it picks the default probe).
+    let probeInput: Readonly<Record<string, unknown>> | undefined;
+    const raw = await c.req.text();
+    if (raw.length > 0) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+        );
+      }
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: 'Request body must be a JSON object' },
+            requestId,
+          ),
+        );
+      }
+      probeInput = parsed as Readonly<Record<string, unknown>>;
+    }
+
+    const outcome = await binding.test({
+      tenantId,
+      adapterId,
+      ...(probeInput !== undefined && { input: probeInput }),
+    });
+    if (outcome === null) {
+      c.status(statusFor('adapter-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'adapter-not-found',
+            message: `No adapter registered with id "${adapterId}"`,
+            adapterId,
+          },
+          requestId,
+        ),
+      );
+    }
+    // Probe failure is data — HTTP 200 with `ok: false` in the body.
+    return c.json(serializeTestOutcome(outcome));
+  });
+
+  // ---------- POST /:adapterId/prepare ----------
+  // SSE stream — iterates `entry.prepare(params)` and pushes each
+  // PrepareEvent as an SSE `data:` line. Returns 404 if the adapter
+  // id is unknown to the in-process factory registry, 400 if the
+  // adapter has no `prepare()` (e.g. anthropic — nothing to
+  // download), and 501 if the deployment didn't wire an
+  // `adapterFactories` binding at all.
+  r.post('/:adapterId/prepare', async (c) => {
+    const requestId = c.get('requestId');
+    const adapterId = c.req.param('adapterId');
+
+    if (factories === undefined) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message:
+              'Adapter prepare is not available — this deployment did not wire an adapterFactories binding.',
+          },
+          requestId,
+        ),
+      );
+    }
+
+    const entry = factories.get(adapterId);
+    if (entry === undefined) {
+      c.status(statusFor('adapter-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'adapter-not-found',
+            message: `No adapter registered with id "${adapterId}"`,
+            adapterId,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (entry.prepare === undefined) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `Adapter "${adapterId}" does not require preparation (no prepare() implemented).`,
+          },
+          requestId,
+        ),
+      );
+    }
+
+    // Body carries adapter-specific `params` — passed through
+    // unchanged (e.g. `{model: 'smollm2-360m'}` for in-process).
+    let params: Readonly<Record<string, unknown>> | undefined;
+    const bodyText = await c.req.text();
+    if (bodyText.length > 0) {
+      try {
+        const parsed = JSON.parse(bodyText) as { readonly params?: unknown };
+        if (parsed.params !== undefined) {
+          if (parsed.params === null || typeof parsed.params !== 'object') {
+            c.status(statusFor('bad-input') as never);
+            return c.json(
+              toWireError(
+                { code: 'bad-input', message: '`params` must be an object when present.' },
+                requestId,
+              ),
+            );
+          }
+          params = parsed.params as Readonly<Record<string, unknown>>;
+        }
+      } catch {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: 'Request body must be valid JSON.' },
+            requestId,
+          ),
+        );
+      }
+    }
+
+    const prepareStream = entry.prepare(params);
+
+    return streamSSE(c, async (stream) => {
+      try {
+        for await (const event of prepareStream) {
+          await stream.writeSSE({
+            event: event.kind,
+            data: JSON.stringify(event),
+          });
+          if (event.kind === 'ready' || event.kind === 'error') break;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const errorEvent: PrepareEvent = { kind: 'error', message };
+        await stream.writeSSE({ event: 'error', data: JSON.stringify(errorEvent) });
+      }
+    });
+  });
+
+  return r;
+}
+
+function serializeAdapter(a: AdapterInfo): Record<string, unknown> {
+  return {
+    adapterId: a.adapterId,
+    kind: a.kind,
+    name: a.name,
+    version: a.version,
+    capabilities: a.capabilities,
+    status: a.status,
+    ...(a.config !== undefined && { config: a.config }),
+    ...(a.statusReason !== undefined && { statusReason: a.statusReason }),
+  };
+}
+
+function serializeTestOutcome(o: AdapterTestOutcome): Record<string, unknown> {
+  return {
+    ok: o.ok,
+    latencyMs: o.latencyMs,
+    probe: o.probe,
+  };
+}