@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/routes/public-run-tokens.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import { ref } from '@kindgi/authz';
+import type { RunBinding } from '@kindgi/runtime';
+import type { RunId, TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import { MAX_PUBLIC_RUN_TOKEN_RUNS, type MintPublicRunTokenResult } from '../public-run-token.js';
+import type { AppEnv } from '../types.js';
+
+export interface PublicRunTokenIssuer {
+  readonly mint: (
+    tenantId: TenantId,
+    runIds: readonly RunId[],
+    ttlSeconds: number,
+  ) => MintPublicRunTokenResult;
+  readonly defaultTtlSeconds: number;
+  readonly maxTtlSeconds: number;
+}
+
+const BODY_FIELDS = new Set(['runIds', 'expiresInSeconds']);
+
+/**
+ * `POST /v1/tokens/public`: mint a public run token for runs the caller
+ * may read. The token itself can't reach this route.
+ */
+export function publicRunTokensRouter(
+  runBinding: RunBinding,
+  issuer: PublicRunTokenIssuer,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const error = (code: string, message: string, details: Record<string, unknown> = {}) => {
+      c.status(statusFor(code) as never);
+      return c.json(toWireError({ code, message, ...details }, requestId));
+    };
+
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return error('bad-input', 'Request body must be valid JSON');
+    }
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+      return error('bad-input', 'Request body must be a JSON object');
+    }
+    const fields = body as Record<string, unknown>;
+    const unknown = Object.keys(fields).find((key) => !BODY_FIELDS.has(key));
+    if (unknown !== undefined) return error('unknown-field', `Unknown field \`${unknown}\``);
+
+    const runIds = fields.runIds;
+    if (
+      !Array.isArray(runIds) ||
+      runIds.length === 0 ||
+      runIds.length > MAX_PUBLIC_RUN_TOKEN_RUNS ||
+      !runIds.every((id) => typeof id === 'string' && id.length > 0)
+    ) {
+      return error(
+        'bad-input',
+        `\`runIds\` must be 1–${MAX_PUBLIC_RUN_TOKEN_RUNS} non-empty run ids`,
+      );
+    }
+    const ttl = fields.expiresInSeconds ?? issuer.defaultTtlSeconds;
+    if (!Number.isInteger(ttl) || (ttl as number) < 1 || (ttl as number) > issuer.maxTtlSeconds) {
+      return error(
+        'bad-input',
+        `\`expiresInSeconds\` must be an integer in 1–${issuer.maxTtlSeconds}`,
+      );
+    }
+
+    const unique = [...new Set(runIds as string[])] as RunId[];
+    for (const runId of unique) {
+      const row = await runBinding.getRun(tenantId, runId);
+      if (row === null) {
+        return error('run-not-found', `No run with id ${runId}`, { runId });
+      }
+      if (
+        authorizer !== undefined &&
+        !(await authorizer.can(c, 'read', ref('project', row.projectId as unknown as string)))
+      ) {
+        return error('permission-denied', `Not allowed to read run ${runId}`, { runId });
+      }
+    }
+
+    const minted = issuer.mint(tenantId, unique, ttl as number);
+    if (minted.kind === 'err') return error('token-mint-failed', minted.message);
+    c.status(201);
+    return c.json({
+      token: minted.token,
+      expiresAt: minted.expiresAt.toISOString(),
+      runIds: unique,
+    });
+  });
+
+  return r;
+}

package/src/routes/retention.ts

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import { ref } from '@kindgi/authz';
+import { RETENTION_DOMAINS, type RetentionDomain } from '@kindgi/policy-contract';
+import type { TenantId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { RetentionBinding } from '../retention-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Retention resource routes — admin surface for the retention
+ * pipeline.
+ *
+ *   - `GET  /v1/retention/scheduled`      tombstoned rows scheduled for deletion
+ *                                         (`?pastGraceOnly=true`: only what a
+ *                                         sweep would purge now)
+ *   - `POST /v1/retention/sweep`          "purge every past-grace tombstone in this tenant"
+ *   - `POST /v1/retention/sweep/:domain`  same but narrowed to one domain
+ *
+ * PEP: reads and writes both require `admin` on `tenant:<tenantId>`,
+ * matching how the other tenant-scoped admin knobs gate.
+ */
+export function retentionRouter(binding: RetentionBinding, authorizer?: Authorizer): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  // Every retention op is tenant-admin only.
+  if (authorizer !== undefined) {
+    r.use('/*', async (c, next) => {
+      const tenantId = c.get('tenantId') as TenantId;
+      const mw = authorizer.authorize('admin', async () =>
+        ref('tenant', tenantId as unknown as string),
+      );
+      return mw(c, next);
+    });
+  }
+
+  r.get('/scheduled', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const url = new URL(c.req.url);
+
+    const domain = parseDomain(url.searchParams.get('domain'));
+    if (domain === 'invalid') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`domain\` must be one of: ${RETENTION_DOMAINS.join(', ')}`,
+          },
+          requestId,
+        ),
+      );
+    }
+
+    const limit = clampLimit(url.searchParams.get('limit') ?? undefined);
+    const pastGraceRaw = url.searchParams.get('pastGraceOnly');
+    const pastGraceOnly = pastGraceRaw === 'true';
+
+    const page = await binding.scheduled({
+      tenantId,
+      limit,
+      pastGraceOnly,
+      ...(domain !== undefined && { domain }),
+    });
+
+    return c.json(page);
+  });
+
+  r.post('/sweep', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    let body: unknown = {};
+    try {
+      const raw = await c.req.text();
+      if (raw.length > 0) body = 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 (typeof body !== 'object' || body === null) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: 'Request body must be an object' }, requestId),
+      );
+    }
+    const parsed = parseSweepBody(body as Record<string, unknown>);
+    if (parsed.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: parsed.message }, requestId));
+    }
+
+    const result = await binding.sweep({
+      tenantId,
+      ...(parsed.value.domain !== undefined && { domain: parsed.value.domain }),
+      ...(parsed.value.maxPerDomain !== undefined && { maxPerDomain: parsed.value.maxPerDomain }),
+    });
+    return c.json(result);
+  });
+
+  r.post('/sweep/:domain', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const domain = parseDomain(c.req.param('domain'));
+    if (domain === undefined || domain === 'invalid') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`:domain\` must be one of: ${RETENTION_DOMAINS.filter((d) => d !== '*').join(', ')}`,
+          },
+          requestId,
+        ),
+      );
+    }
+
+    let body: unknown = {};
+    try {
+      const raw = await c.req.text();
+      if (raw.length > 0) body = 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 (typeof body !== 'object' || body === null) body = {};
+
+    const parsed = parseSweepBody(body as Record<string, unknown>);
+    if (parsed.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: parsed.message }, requestId));
+    }
+
+    const result = await binding.sweep({
+      tenantId,
+      domain,
+      ...(parsed.value.maxPerDomain !== undefined && { maxPerDomain: parsed.value.maxPerDomain }),
+    });
+    return c.json(result);
+  });
+
+  return r;
+}
+
+function parseDomain(raw: string | null | undefined): RetentionDomain | 'invalid' | undefined {
+  if (raw === null || raw === undefined || raw === '') return undefined;
+  if ((RETENTION_DOMAINS as readonly string[]).includes(raw)) return raw as RetentionDomain;
+  return 'invalid';
+}
+
+function parseSweepBody(body: Record<string, unknown>):
+  | {
+      readonly kind: 'ok';
+      readonly value: {
+        readonly domain?: RetentionDomain;
+        readonly maxPerDomain?: number;
+      };
+    }
+  | { readonly kind: 'err'; readonly message: string } {
+  const value: { domain?: RetentionDomain; maxPerDomain?: number } = {};
+  if ('domain' in body) {
+    const parsed = parseDomain(String(body.domain));
+    if (parsed === 'invalid') {
+      return {
+        kind: 'err',
+        message: `\`domain\` must be one of: ${RETENTION_DOMAINS.join(', ')}`,
+      };
+    }
+    if (parsed !== undefined) value.domain = parsed;
+  }
+  if ('maxPerDomain' in body) {
+    const n = body.maxPerDomain;
+    if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0 || n > 10_000) {
+      return {
+        kind: 'err',
+        message: '`maxPerDomain` must be a positive integer ≤ 10000',
+      };
+    }
+    value.maxPerDomain = n;
+  }
+  return { kind: 'ok', value };
+}

package/src/routes/reviewers.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type { Cursor, ReviewerId, TenantId, UserId } from '@kindgi/types';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { ReviewerRecord, ReviewerRegistryBinding } from '../reviewer-binding.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+
+/**
+ * Reviewer roster routes — sub-resource under
+ * `/v1/approvals/reviewers`. Roster management is caller-plugged via
+ * `ReviewerRegistryBinding`; the API package does NOT own persistence.
+ *
+ * The routes deliberately live OUTSIDE the reviewer-role gate applied
+ * inside `approvalsRouter`: registering a reviewer is an admin surface
+ * action, not a reviewer-only one, so requiring a `reviewerRole` on the
+ * caller would be circular ("only reviewers can appoint reviewers").
+ * The caller still needs a valid bearer token — the `/v1/*` auth chain
+ * covers that upstream.
+ *
+ * Mounted BEFORE `approvalsRouter` on the parent `/v1` router so path
+ * matching resolves `/v1/approvals/reviewers/*` here rather than being
+ * captured by the `/:approvalId` param inside the approvals router.
+ */
+const ROLE_VALUES: ReadonlySet<ReviewerRole> = new Set(['standard', 'senior', 'admin']);
+
+export function reviewersRouter(binding: ReviewerRegistryBinding): 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 roleRaw = c.req.query('role');
+
+    let roleFilter: ReviewerRole | undefined;
+    if (roleRaw !== undefined && roleRaw.length > 0) {
+      if (!ROLE_VALUES.has(roleRaw as ReviewerRole)) {
+        c.status(statusFor('bad-input') as never);
+        return c.json(
+          toWireError(
+            { code: 'bad-input', message: `Unknown \`role\` value: ${roleRaw}` },
+            requestId,
+          ),
+        );
+      }
+      roleFilter = roleRaw as ReviewerRole;
+    }
+
+    const page = await binding.list({
+      tenantId,
+      limit,
+      ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw as Cursor }),
+      ...(roleFilter !== undefined && { role: roleFilter }),
+    });
+    return c.json({
+      data: page.data.map(serializeReviewer),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:reviewerId ----------
+  r.get('/:reviewerId', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const reviewerId = c.req.param('reviewerId') as ReviewerId;
+
+    const reviewer = await binding.get({ tenantId, reviewerId });
+    if (reviewer === null) {
+      c.status(statusFor('reviewer-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'reviewer-not-found',
+            message: `No reviewer registered with id "${reviewerId as unknown as string}"`,
+            reviewerId: reviewerId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json(serializeReviewer(reviewer));
+  });
+
+  // ---------- POST / (register) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+
+    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 = parseRegisterBody(body);
+    if (parsed.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: parsed.message }, requestId));
+    }
+
+    const outcome = await binding.register({
+      tenantId,
+      userId: parsed.value.userId,
+      role: parsed.value.role,
+      ...(parsed.value.displayName !== undefined && { displayName: parsed.value.displayName }),
+    });
+    c.status(201);
+    return c.json(serializeReviewer(outcome.reviewer));
+  });
+
+  // ---------- POST /:reviewerId/unregister ----------
+  r.post('/:reviewerId/unregister', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const reviewerId = c.req.param('reviewerId') as ReviewerId;
+
+    const outcome = await binding.unregister({ tenantId, reviewerId });
+    if (!outcome.unregistered) {
+      c.status(statusFor('reviewer-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'reviewer-not-found',
+            message: `No reviewer "${reviewerId as unknown as string}" to unregister`,
+            reviewerId: reviewerId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    return c.json({
+      reviewerId: reviewerId as unknown as string,
+      unregistered: true,
+    });
+  });
+
+  return r;
+}
+
+function serializeReviewer(r: ReviewerRecord): Record<string, unknown> {
+  return {
+    id: r.id as unknown as string,
+    tenantId: r.tenantId as unknown as string,
+    userId: r.userId as unknown as string,
+    role: r.role,
+    ...(r.displayName !== undefined && { displayName: r.displayName }),
+    createdAt: r.createdAt as unknown as string,
+    ...(r.deactivatedAt !== undefined && {
+      deactivatedAt: r.deactivatedAt as unknown as string,
+    }),
+  };
+}
+
+type ParsedRegister = {
+  readonly userId: UserId;
+  readonly role: ReviewerRole;
+  readonly displayName?: string;
+};
+
+function parseRegisterBody(
+  body: unknown,
+):
+  | { readonly kind: 'ok'; readonly value: ParsedRegister }
+  | { readonly kind: 'err'; readonly message: string } {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { kind: 'err', message: 'Request body must be an object' };
+  }
+  const b = body as Record<string, unknown>;
+  const userId = b.userId;
+  if (typeof userId !== 'string' || userId.length === 0) {
+    return { kind: 'err', message: 'Field `userId` must be a non-empty string' };
+  }
+  const role = b.role;
+  if (typeof role !== 'string' || !ROLE_VALUES.has(role as ReviewerRole)) {
+    return { kind: 'err', message: 'Field `role` must be one of: standard, senior, admin' };
+  }
+  const displayNameRaw = b.displayName;
+  let displayName: string | undefined;
+  if (displayNameRaw !== undefined) {
+    if (typeof displayNameRaw !== 'string' || displayNameRaw.length === 0) {
+      return {
+        kind: 'err',
+        message: 'Field `displayName` must be a non-empty string when present',
+      };
+    }
+    displayName = displayNameRaw;
+  }
+  return {
+    kind: 'ok',
+    value: {
+      userId: userId as UserId,
+      role: role as ReviewerRole,
+      ...(displayName !== undefined && { displayName }),
+    },
+  };
+}