@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/src/routes/signing-keys.ts

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Context, Hono } from 'hono';
+
+import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.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';
+
+/**
+ * The tenant's trusted signing keys: the public keys whose signatures
+ * `POST /v1/deployments` accepts.
+ *
+ *   - `POST /v1/signing-keys`                  — trust a key.
+ *   - `GET  /v1/signing-keys`                  — list (active; `includeRevoked=true` for all).
+ *   - `GET  /v1/signing-keys/:keyId`           — one key, revoked or not.
+ *   - `POST /v1/signing-keys/:keyId/revoke`    — stop trusting it.
+ *
+ * A revoked key stays readable, with `revokedAt` and its reason, so a
+ * deployment it signed can still be audited; it no longer verifies new
+ * deployments. Like an API token, a key is revoked, not unregistered.
+ * Rotate by trusting a new `keyId`: a `keyId` is bound to its public key
+ * for good.
+ *
+ * Writes need the `signing-keys:write` capability; reads, the tenant's
+ * bearer.
+ */
+export function signingKeysRouter(binding: SigningKeyBinding): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // ---------- POST / (trust a key) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const denied = requireWrite(c, requestId);
+    if (denied !== undefined) return denied;
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+      );
+    }
+    const parsed = parseAddBody(body);
+    if (parsed.kind === 'err') {
+      c.status(statusFor(parsed.error.code) as never);
+      return c.json(toWireError(parsed.error, requestId));
+    }
+
+    const outcome = await binding.addTrusted({ tenantId, ...parsed.value });
+    switch (outcome.kind) {
+      case 'ok':
+        c.status(201);
+        return c.json(serializeKey(outcome.key));
+      case 'already-trusted':
+        return c.json(serializeKey(outcome.key));
+      case 'key-id-conflict':
+        c.status(statusFor('signing-key-conflict') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'signing-key-conflict',
+              message: `Key id "${parsed.value.keyId as unknown as string}" is already trusted with a different public key. Trust the new key under a new key id.`,
+            },
+            requestId,
+          ),
+        );
+      case 'error':
+        c.status(statusFor(outcome.code) as never);
+        return c.json(toWireError({ code: outcome.code, message: outcome.message }, requestId));
+    }
+  });
+
+  // ---------- GET / (list) ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const limit = clampLimit(c.req.query('limit'));
+    const cursorRaw = c.req.query('cursor');
+    const labelRaw = c.req.query('label');
+    const page = await binding.listTrusted({
+      tenantId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(c.req.query('includeRevoked') === 'true' && { includeRevoked: true }),
+      ...(labelRaw !== undefined && labelRaw.length > 0 && { labelFilter: labelRaw }),
+    });
+    return c.json({
+      data: page.data.map(serializeKey),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:keyId ----------
+  r.get('/:keyId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const keyId = c.req.param('keyId') as SigningKeyId;
+    const key = await binding.getTrusted({ tenantId, keyId });
+    if (key === null) {
+      c.status(statusFor('signing-key-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'signing-key-not-found',
+            message: `No signing key "${keyId as unknown as string}" under this tenant`,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeKey(key));
+  });
+
+  // ---------- POST /:keyId/revoke ----------
+  r.post('/:keyId/revoke', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const denied = requireWrite(c, requestId);
+    if (denied !== undefined) return denied;
+    const keyId = c.req.param('keyId') as SigningKeyId;
+
+    let reason: string | undefined;
+    const text = await c.req.text();
+    if (text.length > 0) {
+      let body: unknown;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
+        );
+      }
+      const raw = (body as { reason?: unknown } | null)?.reason;
+      if (raw !== undefined && typeof raw !== 'string') {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError({ code: 'bad-input', message: '`reason` must be a string' }, requestId),
+        );
+      }
+      reason = raw;
+    }
+
+    const outcome = await binding.revokeTrusted({
+      tenantId,
+      keyId,
+      ...(reason !== undefined && { reason }),
+    });
+    return c.json({ keyId: keyId as unknown as string, revoked: outcome.revoked });
+  });
+
+  return r;
+}
+
+/** A 403 unless the bearer holds `signing-keys:write` (fail-closed). */
+function requireWrite(c: Context<AppEnv>, requestId: string): Response | undefined {
+  if (hasCapability(c, 'signing-keys:write')) return undefined;
+  c.status(statusFor('permission-denied') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'permission-denied',
+        message:
+          'Bearer token is missing the `signing-keys:write` capability required to change the trusted signing keys.',
+      },
+      requestId,
+    ),
+  );
+}
+
+const KEY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const ED25519_PUBLIC_KEY_BYTES = 32;
+
+function parseAddBody(body: unknown):
+  | {
+      readonly kind: 'ok';
+      readonly value: {
+        readonly keyId: SigningKeyId;
+        readonly algorithm: string;
+        readonly publicKey: string;
+        readonly label?: string;
+      };
+    }
+  | { readonly kind: 'err'; readonly error: { readonly code: string; readonly message: string } } {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { kind: 'err', error: { code: 'bad-input', message: 'Request body must be an object' } };
+  }
+  const b = body as Record<string, unknown>;
+  if (typeof b.keyId !== 'string' || !KEY_ID.test(b.keyId)) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'bad-input',
+        message:
+          '`keyId` must be 1–128 characters: letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit',
+      },
+    };
+  }
+  const algorithm = b.algorithm ?? 'ed25519';
+  if (algorithm !== 'ed25519') {
+    return {
+      kind: 'err',
+      error: {
+        code: 'signing-key-algorithm-unsupported',
+        message: `\`algorithm\` must be "ed25519". Got ${JSON.stringify(algorithm)}.`,
+      },
+    };
+  }
+  if (typeof b.publicKey !== 'string' || !isBase64OfLength(b.publicKey, ED25519_PUBLIC_KEY_BYTES)) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'bad-input',
+        message: '`publicKey` must be base64 of the 32 raw bytes of an Ed25519 public key',
+      },
+    };
+  }
+  if (b.label !== undefined && (typeof b.label !== 'string' || b.label.length > 200)) {
+    return {
+      kind: 'err',
+      error: { code: 'bad-input', message: '`label` must be a string of at most 200 characters' },
+    };
+  }
+  return {
+    kind: 'ok',
+    value: {
+      keyId: b.keyId as SigningKeyId,
+      algorithm,
+      publicKey: b.publicKey,
+      ...(typeof b.label === 'string' && { label: b.label }),
+    },
+  };
+}
+
+function isBase64OfLength(value: string, bytes: number): boolean {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return false;
+  return Buffer.from(value, 'base64').length === bytes;
+}
+
+function serializeKey(key: TrustedKey): Record<string, unknown> {
+  return {
+    keyId: key.keyId as unknown as string,
+    tenantId: key.tenantId as unknown as string,
+    algorithm: key.algorithm,
+    publicKey: key.publicKey,
+    ...(key.label !== undefined && { label: key.label }),
+    createdAt: key.createdAt,
+    ...(key.revokedAt !== undefined && { revokedAt: key.revokedAt }),
+    ...(key.revokedReason !== undefined && { revokedReason: key.revokedReason }),
+  };
+}

package/src/routes/sse.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import type { JournalEntry, JournalKind } from '@kindgi/runtime';
+import type { RunId, TenantId } from '@kindgi/types';
+
+/**
+ * Wire-side RunEvent kind — the enum surfaced over SSE.
+ *
+ * Source of truth: `@kindgi/specs/run-event.schema.json`. Names are dotted
+ * `run.<xxx>-<yyy>` (e.g. `run.step-completed`) — matches the
+ * conventions doc §6 example. Internal-only kernel journal kinds
+ * (e.g. `clock.read`) and kinds absent from the wire enum
+ * (`edge.evaluated`) are dropped by the mapper — the journal endpoint
+ * still exposes them.
+ */
+export type RunEventKind =
+  | 'run.started'
+  | 'run.step-started'
+  | 'run.step-completed'
+  | 'run.step-failed'
+  | 'run.step-retry-scheduled'
+  | 'run.iteration-started'
+  | 'run.iteration-completed'
+  | 'run.wait-suspended'
+  | 'run.wait-resumed'
+  | 'run.completed'
+  | 'run.failed'
+  | 'run.cancelled';
+
+const KERNEL_TO_WIRE: Readonly<Partial<Record<JournalKind, RunEventKind>>> = {
+  'run.started': 'run.started',
+  'step.started': 'run.step-started',
+  'step.completed': 'run.step-completed',
+  'step.failed': 'run.step-failed',
+  'step.retry-scheduled': 'run.step-retry-scheduled',
+  'iteration.started': 'run.iteration-started',
+  'iteration.completed': 'run.iteration-completed',
+  'wait.suspended': 'run.wait-suspended',
+  'wait.resumed': 'run.wait-resumed',
+  'run.completed': 'run.completed',
+  'run.failed': 'run.failed',
+  'run.cancelled': 'run.cancelled',
+};
+
+const TERMINAL_KINDS: ReadonlySet<RunEventKind> = new Set([
+  'run.completed',
+  'run.failed',
+  'run.cancelled',
+]);
+
+/**
+ * Project a kernel `JournalEntry` into the wire `RunEvent` shape
+ * consumed over SSE. Returns `null` for kernel kinds not exposed on
+ * the wire (`edge.evaluated`, `clock.read`).
+ */
+export function projectJournalEntry(
+  entry: JournalEntry,
+  runId: RunId,
+  tenantId: TenantId,
+): {
+  wireKind: RunEventKind;
+  event: {
+    eventId: string;
+    runId: RunId;
+    tenantId: TenantId;
+    timestamp: string;
+    kind: RunEventKind;
+    sequence: number;
+    nodeId?: string;
+    payload?: unknown;
+  };
+} | null {
+  const wireKind = KERNEL_TO_WIRE[entry.kind];
+  if (wireKind === undefined) return null;
+  const ts = entry.timestamp as unknown;
+  const timestampIso =
+    ts instanceof Date ? ts.toISOString() : new Date(ts as string | number).toISOString();
+  return {
+    wireKind,
+    event: {
+      eventId: `${runId}:${entry.sequence}`,
+      runId,
+      tenantId,
+      timestamp: timestampIso,
+      kind: wireKind,
+      sequence: entry.sequence,
+      ...(entry.nodeId !== undefined && { nodeId: entry.nodeId as string }),
+      ...(entry.payload !== undefined && { payload: entry.payload }),
+    },
+  };
+}
+
+/** A run event as the progress stream sends it: no payload, no tenant. */
+export function toRunProgressEvent(event: {
+  readonly eventId: string;
+  readonly runId: RunId;
+  readonly timestamp: string;
+  readonly kind: RunEventKind;
+  readonly sequence: number;
+  readonly nodeId?: string;
+}): Record<string, unknown> {
+  return {
+    eventId: event.eventId,
+    runId: event.runId,
+    timestamp: event.timestamp,
+    kind: event.kind,
+    sequence: event.sequence,
+    ...(event.nodeId !== undefined && { nodeId: event.nodeId }),
+  };
+}
+
+export function isTerminalWireKind(kind: RunEventKind): boolean {
+  return TERMINAL_KINDS.has(kind);
+}
+
+/**
+ * Parse `Last-Event-Id` header (format: `<runId>:<sequence>`). Returns
+ * `undefined` on malformed input — caller replays from 0.
+ */
+export function parseLastEventId(header: string | undefined): number | undefined {
+  if (header === undefined || header.length === 0) return undefined;
+  const colonIdx = header.lastIndexOf(':');
+  const seqStr = colonIdx === -1 ? header : header.slice(colonIdx + 1);
+  const n = Number.parseInt(seqStr, 10);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  return n;
+}
+
+/**
+ * Format one SSE event frame as raw bytes per the spec. Multi-line
+ * data payloads are prefixed on every line.
+ */
+export function formatSseFrame(input: { id: string; event: string; data: unknown }): string {
+  const dataJson = JSON.stringify(input.data);
+  const dataLines = dataJson
+    .split('\n')
+    .map((l) => `data: ${l}`)
+    .join('\n');
+  return `id: ${input.id}\nevent: ${input.event}\n${dataLines}\n\n`;
+}
+
+/** Small unique-id helper used by tests that want a deterministic event id shape. */
+export function newSseCorrelationId(): string {
+  return `sse-${randomUUID()}`;
+}