@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/middleware/auth.ts

@@ -0,0 +1,437 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type { ApiTokenId, SessionId, TenantId, UserId } from '@kindgi/types';
+
+import type { SigningKeyBinding } from '@kindgi/crypto';
+
+import { statusFor, toWireError } from '../errors.js';
+import { PUBLIC_RUN_TOKEN_PREFIX, verifyPublicRunToken } from '../public-run-token.js';
+import type { SessionStoreBinding } from '../session-store-binding.js';
+
+/**
+ * Resolve an API token → tenant identity. For static bearer tokens this
+ * is a caller-injected function: the platform's actual token store (auth
+ * service, database, …) plugs in. Signature stays stable across
+ * implementations.
+ *
+ * Return `null` for missing / expired / revoked tokens; the middleware
+ * translates to 401 with a specific error code.
+ */
+export type TokenResolver = (token: string) => Promise<TokenResolution | null>;
+
+export interface TokenResolution {
+  readonly tenantId: TenantId;
+  /**
+   * Optional expiration; if set and in the past, the middleware treats
+   * as expired even if the resolver returned a value.
+   */
+  readonly expiresAt?: Date;
+  /** Optional revocation marker; `true` → 401 auth-revoked. */
+  readonly revoked?: boolean;
+  /**
+   * Optional reviewer role granted to this token. When present, the
+   * middleware surfaces it as `c.get('reviewerRole')` and approvals
+   * routes gate visibility / decisions on the `standard < senior < admin`
+   * hierarchy. Absent for tokens that were never provisioned with a
+   * reviewer role — such tokens can still hit `/v1/runs` etc., but any
+   * approvals route returns `403 permission-denied`.
+   */
+  readonly reviewerRole?: ReviewerRole;
+  /**
+   * Optional user identity behind the token. Approvals routes forward
+   * this to a `ReviewerBinding` to translate `UserId → ReviewerId`
+   * before calling `hitl.submitReview` (which needs the reviewer id).
+   */
+  readonly userId?: UserId;
+  /**
+   * The id of a durable API key (`POST /v1/tokens`). The caller is then
+   * the key's service account (`service_account:<tokenId>`), not a user;
+   * the middleware surfaces it as `c.get('tokenId')`.
+   */
+  readonly tokenId?: ApiTokenId;
+  /**
+   * Optional session id. Populated by the session-token verifier path
+   * (`kgi_sk_*` tokens) so `/v1/identity/whoami` and `/v1/auth/logout`
+   * can introspect / revoke the caller's own session without a second
+   * lookup. Absent for static bearer tokens.
+   */
+  readonly sessionId?: SessionId;
+  /**
+   * Optional identity-provider id that authenticated the caller. Only
+   * populated by session-token verification.
+   */
+  readonly providerId?: string;
+  /**
+   * Optional OAuth scopes granted to the session. Only populated by
+   * session-token verification.
+   */
+  readonly scopes?: readonly string[];
+  /**
+   * Optional last-observed-activity timestamp. Populated by
+   * `resolveSessionToken` when the session-store adapter carries
+   * `lastActiveAt` on the row. Used by the middleware to enforce the
+   * `inactivityTimeoutMs` policy. Absent → inactivity check is
+   * skipped.
+   */
+  readonly lastActiveAt?: Date;
+  /**
+   * Optional flag set by `resolveSessionToken` when the session was
+   * revoked specifically via rotation (`POST /v1/auth/refresh`). The
+   * middleware maps this to `401 refresh-token-invalid` instead of
+   * the generic `401 auth-revoked`, matching OAuth 2.1 BCP refresh-
+   * token-reuse semantics.
+   */
+  readonly rotated?: boolean;
+  /**
+   * Optional framework capabilities granted to the bearer. Route
+   * handlers gate write / reveal ops on
+   * specific capability strings (`env:write`, `secrets:write`,
+   * `secrets:rotate`, `secrets:revoke`, `secrets:revoke:hard`,
+   * `secrets:reveal`, `kindgi:system`). Callers that plug their
+   * own resolver populate this list from their token store; deployments
+   * without capability data leave it absent — routes that require a
+   * capability then return 403 `permission-denied`.
+   *
+   * Kindgi's stance: fail-closed on writes when the capability is
+   * unset (a token without an explicit `secrets:write` claim cannot
+   * mutate the secrets store). Deployments that want any authenticated
+   * bearer to be able to write grant the capability on every token.
+   */
+  readonly capabilities?: readonly string[];
+}
+
+/**
+ * Session-token prefix. Framework-issued opaque tokens minted by
+ * `POST /v1/auth/callback/:providerId` carry this prefix so the auth
+ * middleware can route them to the session store instead of the caller-
+ * plugged `TokenResolver`. Distinct prefix means a static bearer token
+ * and a session token can coexist byte-shape-identical on the wire.
+ */
+export const SESSION_TOKEN_PREFIX = 'kgi_sk_' as const;
+
+/**
+ * Compose the on-wire session token from a `SessionId`. Session tokens
+ * are opaque to clients — the shape below is a framework convention,
+ * not part of the wire contract. Do NOT parse it in downstream code
+ * outside the middleware.
+ */
+export function encodeSessionToken(sessionId: SessionId): string {
+  return `${SESSION_TOKEN_PREFIX}${sessionId as unknown as string}`;
+}
+
+/**
+ * Optional wiring for the session-token flavor. Provided to the
+ * middleware via `bearerAuthMiddleware(resolveToken, { sessionStore })`
+ * when the deployment mounts `SessionStoreBinding`. Absent → session-
+ * shape tokens fall through to `TokenResolver` (which will typically
+ * `null` them → 401 auth-missing) so a deployment without a session
+ * store still behaves consistently.
+ */
+export interface BearerAuthMiddlewareOptions {
+  readonly sessionStore?: SessionStoreBinding;
+  /**
+   * Inactivity timeout — sessions whose `lastActiveAt` is older than
+   * `Date.now() - inactivityTimeoutMs` are rejected with 401
+   * `session-inactive`. Absent → inactivity enforcement disabled
+   * (only absolute TTL applies).
+   *
+   * Sensible default: 4 hours (`4 * 60 * 60 * 1000`). Deployments
+   * customize via `CreateAppInput.session.inactivityTimeout`.
+   */
+  readonly inactivityTimeoutMs?: number;
+  /**
+   * How often (per session) the middleware should call
+   * `sessionStore.touch` to bump `lastActiveAt`. Higher throttle ⇒
+   * fewer writes but coarser inactivity enforcement. Defaults to 60s.
+   */
+  readonly touchThrottleMs?: number;
+  /**
+   * Accept public run tokens (`kgi_pt_…`), verified against
+   * `signingKey`, on the routes `isAllowed` admits (every other route
+   * answers 403). Absent → such tokens are not recognized (401).
+   */
+  readonly publicRunTokens?: {
+    readonly signingKey: SigningKeyBinding;
+    readonly isAllowed: (method: string, path: string) => boolean;
+  };
+}
+
+const DEFAULT_TOUCH_THROTTLE_MS = 60_000;
+
+/**
+ * Bearer-token middleware. Fails 401 on missing / malformed / expired /
+ * revoked. On success, sets `c.set('tenantId', tenantId)` for downstream
+ * handlers.
+ *
+ * Two token flavors are accepted:
+ * - `kgi_sk_<sessionId>` — framework-issued OAuth session tokens.
+ *   Verified via `sessionStore.get`; expiration + revocation are pulled
+ *   from the session row.
+ * - anything else — caller-plugged static bearer tokens. Verified via
+ *   `resolveToken`. Byte-shape-identical with the session-less contract.
+ */
+export function bearerAuthMiddleware(
+  resolve: TokenResolver,
+  options: BearerAuthMiddlewareOptions = {},
+): MiddlewareHandler {
+  const { sessionStore, inactivityTimeoutMs } = options;
+  const touchThrottleMs = options.touchThrottleMs ?? DEFAULT_TOUCH_THROTTLE_MS;
+  // Per-process throttle bucket: session id → last touch millis.
+  // A shared Map is fine — session ids are opaque strings and the
+  // bucket is bounded by the number of active sessions the process
+  // has recently observed.
+  const touchBucket = new Map<string, number>();
+  return async (c, next) => {
+    const requestId = c.get('requestId') as string;
+    const header = c.req.header('authorization');
+    if (header === undefined || header.length === 0) {
+      const body = toWireError(
+        { code: 'auth-missing', message: 'Authorization header is required' },
+        requestId,
+      );
+      return c.json(body, statusFor('auth-missing') as never);
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    if (match === null) {
+      const body = toWireError(
+        {
+          code: 'auth-missing',
+          message: 'Authorization header must be "Bearer <token>"',
+        },
+        requestId,
+      );
+      return c.json(body, statusFor('auth-missing') as never);
+    }
+    const token = match[1]?.trim() ?? '';
+    if (token.length === 0) {
+      const body = toWireError(
+        { code: 'auth-missing', message: 'Bearer token is empty' },
+        requestId,
+      );
+      return c.json(body, statusFor('auth-missing') as never);
+    }
+
+    if (token.startsWith(PUBLIC_RUN_TOKEN_PREFIX)) {
+      return authenticatePublicRunToken(c, next, token, requestId, options.publicRunTokens);
+    }
+
+    const isSessionToken = sessionStore !== undefined && token.startsWith(SESSION_TOKEN_PREFIX);
+    const resolution = isSessionToken
+      ? await resolveSessionToken(sessionStore!, token)
+      : await resolve(token);
+    if (resolution === null) {
+      const body = toWireError(
+        { code: 'auth-missing', message: 'Bearer token is not recognized' },
+        requestId,
+      );
+      return c.json(body, statusFor('auth-missing') as never);
+    }
+    if (resolution.revoked === true) {
+      // Rotated sessions surface as `refresh-token-invalid` — OAuth 2.1
+      // BCP reuse detection. The old session token is no longer valid,
+      // but the semantic distinction from an explicit revoke matters
+      // to compliant clients (they retry with the fresh token instead
+      // of prompting the user to re-authenticate).
+      if (resolution.rotated === true) {
+        const body = toWireError(
+          {
+            code: 'refresh-token-invalid',
+            message: 'Session token was rotated — retry with the fresh token from the last refresh',
+          },
+          requestId,
+        );
+        return c.json(body, statusFor('refresh-token-invalid') as never);
+      }
+      const body = toWireError(
+        { code: 'auth-revoked', message: 'Bearer token has been revoked' },
+        requestId,
+      );
+      return c.json(body, statusFor('auth-revoked') as never);
+    }
+    if (resolution.expiresAt !== undefined && resolution.expiresAt.getTime() < Date.now()) {
+      // Session tokens report `session-expired` so callers can
+      // distinguish absolute session TTL from bearer-token expiry.
+      const expiredCode = isSessionToken ? 'session-expired' : 'auth-expired';
+      const expiredMsg = isSessionToken
+        ? 'Session has expired (absolute TTL reached)'
+        : 'Bearer token has expired';
+      const body = toWireError({ code: expiredCode, message: expiredMsg }, requestId);
+      return c.json(body, statusFor(expiredCode) as never);
+    }
+    // Inactivity timeout enforcement. Only applies when the deployment
+    // opted in via `inactivityTimeoutMs` AND the token is a session
+    // token AND the store populated `lastActiveAt`. Skipping the check
+    // preserves the default contract for deployments that don't wire
+    // the config.
+    if (
+      isSessionToken &&
+      inactivityTimeoutMs !== undefined &&
+      inactivityTimeoutMs > 0 &&
+      resolution.lastActiveAt !== undefined
+    ) {
+      const cutoff = Date.now() - inactivityTimeoutMs;
+      if (resolution.lastActiveAt.getTime() < cutoff) {
+        const body = toWireError(
+          {
+            code: 'session-inactive',
+            message: 'Session has been idle beyond the inactivity timeout',
+          },
+          requestId,
+        );
+        return c.json(body, statusFor('session-inactive') as never);
+      }
+    }
+
+    c.set('tenantId', resolution.tenantId);
+    if (resolution.reviewerRole !== undefined) {
+      c.set('reviewerRole', resolution.reviewerRole);
+    }
+    if (resolution.userId !== undefined) {
+      c.set('userId', resolution.userId);
+    }
+    if (resolution.tokenId !== undefined) {
+      c.set('tokenId', resolution.tokenId);
+    }
+    if (resolution.sessionId !== undefined) {
+      c.set('sessionId', resolution.sessionId);
+    }
+    if (resolution.providerId !== undefined) {
+      c.set('providerId', resolution.providerId);
+    }
+    if (resolution.scopes !== undefined) {
+      c.set('scopes', resolution.scopes);
+    }
+    if (resolution.capabilities !== undefined) {
+      c.set('capabilities', resolution.capabilities);
+    }
+
+    // Bump `lastActiveAt` (throttled) so the inactivity timeout has
+    // a fresh signal to compare against. Only meaningful for session
+    // tokens with a wired `touch()`; bearer tokens are skipped.
+    if (isSessionToken && sessionStore?.touch !== undefined && resolution.sessionId !== undefined) {
+      const sid = resolution.sessionId as unknown as string;
+      const last = touchBucket.get(sid) ?? 0;
+      const now = Date.now();
+      if (now - last >= touchThrottleMs) {
+        touchBucket.set(sid, now);
+        // Fire-and-forget; we don't want the write path to hold the
+        // request. Adapter errors surface via observability, not the
+        // hot path (the next check catches a genuinely stale row).
+        void sessionStore
+          .touch({
+            tenantId: resolution.tenantId,
+            sessionId: resolution.sessionId,
+            at: new Date(now),
+          })
+          .catch(() => {
+            // Best-effort — the next request retries.
+          });
+      }
+    }
+
+    await next();
+    return;
+  };
+}
+
+/**
+ * Session-token verification path. Distinct from `TokenResolver` because
+ * a session carries structured OAuth context (userId + providerId +
+ * scopes + expiration + revocation) that the store returns natively —
+ * we don't want to squeeze that shape through the resolver contract.
+ *
+ * Session-token tenant scoping: the stored session is the source of
+ * truth for `tenantId`. We look up ACROSS tenants here — the resolved
+ * `tenantId` is whatever the session was written under, so everything
+ * downstream is scoped to that tenant only. A stolen session token still
+ * can't cross tenants because the session it points to belongs to
+ * exactly one tenant.
+ *
+ * Since `SessionStoreBinding.get` requires `tenantId`, the lookup is:
+ * extract `sessionId` from the token, then call
+ * `sessionStore.get({ tenantId: MULTI_TENANT_LOOKUP, sessionId })`.
+ * Session-store implementations MUST recognize the `MULTI_TENANT_LOOKUP`
+ * sentinel and skip the tenant filter; the `tenantId` on the stored
+ * session is authoritative.
+ */
+async function resolveSessionToken(
+  sessionStore: SessionStoreBinding,
+  token: string,
+): Promise<TokenResolution | null> {
+  const sessionIdStr = token.slice(SESSION_TOKEN_PREFIX.length);
+  if (sessionIdStr.length === 0) return null;
+  const sessionId = sessionIdStr as unknown as SessionId;
+  const session = await sessionStore.get({
+    tenantId: MULTI_TENANT_LOOKUP,
+    sessionId,
+  });
+  if (session === null) return null;
+  return {
+    tenantId: session.tenantId,
+    userId: session.userId as unknown as UserId,
+    sessionId: session.id,
+    providerId: session.providerId,
+    scopes: session.scopes,
+    expiresAt: new Date(session.expiresAt as unknown as string),
+    revoked: session.revokedAt !== undefined,
+    ...(session.rotatedAt !== undefined && { rotated: true }),
+    ...(session.lastActiveAt !== undefined && {
+      lastActiveAt: new Date(session.lastActiveAt as unknown as string),
+    }),
+  };
+}
+
+/**
+ * Sentinel `tenantId` value the middleware passes to
+ * `SessionStoreBinding.get` when it needs to look up a session by its
+ * id without knowing the tenant in advance. Session-store adapters
+ * MUST honor this by skipping the tenant filter — the tenant is not
+ * known until the session row has been read.
+ */
+export const MULTI_TENANT_LOOKUP = '__kindgi_session_multi_tenant_lookup__' as unknown as TenantId;
+
+/**
+ * A public run token: verify it, admit only the routes it may use, and
+ * mark the request so the progress routes check it against the runs
+ * it names.
+ */
+async function authenticatePublicRunToken(
+  c: Context,
+  next: Next,
+  token: string,
+  requestId: string,
+  config: BearerAuthMiddlewareOptions['publicRunTokens'],
+): Promise<Response | undefined> {
+  const verified =
+    config === undefined
+      ? ({ kind: 'err', reason: 'unknown-key' } as const)
+      : verifyPublicRunToken(token, { signingKey: config.signingKey });
+  if (verified.kind === 'err') {
+    const expired = verified.reason === 'expired';
+    const code = expired ? 'auth-expired' : 'auth-missing';
+    const message = expired ? 'Public run token has expired' : 'Bearer token is not recognized';
+    return c.json(toWireError({ code, message }, requestId), statusFor(code) as never);
+  }
+  if (config === undefined || !config.isAllowed(c.req.method, c.req.path)) {
+    return c.json(
+      toWireError(
+        {
+          code: 'permission-denied',
+          message:
+            'A public run token can only follow the runs it names: GET /v1/runs/{runId}/progress and GET /v1/runs/{runId}/progress/stream',
+        },
+        requestId,
+      ),
+      statusFor('permission-denied') as never,
+    );
+  }
+  c.set('tenantId', verified.claims.tenantId);
+  c.set('tokenKind', 'public-run');
+  c.set('publicRunIds', verified.claims.runIds);
+  await next();
+  return undefined;
+}

package/src/middleware/authorize.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// authorize / can — Hono PEP for HTTP routes.
+//
+// createAuthorizer(binding) returns helpers curried against an
+// `AuthzCheckBinding` (the PDP):
+//
+//   authorize(action, resourceGetter)  → Hono middleware, 403s on deny
+//   can(c, action, resource)           → boolean, for conditional logic
+//   check(c, action, resource)         → full Decision, for advanced cases
+//   filterByCan(c, action, items, fn)  → the items the principal may act on
+//
+// Use `authorize` on any mutating route. Use `can` inside handlers when
+// the decision affects response shape (e.g. filter results, include
+// admin-only fields, etc.).
+//
+
+import type { Context, MiddlewareHandler } from 'hono';
+
+import {
+  type Action,
+  type AuthzCheckBinding,
+  type Decision,
+  type Principal,
+  type ResourceRef,
+  denyPayload,
+} from '@kindgi/authz';
+
+import type { AppEnv } from '../types.js';
+
+/**
+ * Callback that produces the resource being acted upon from the Hono
+ * context. Called at request time — can read path params, query, or
+ * body (if already parsed).
+ */
+export type ResourceGetter = (c: Context<AppEnv>) => ResourceRef | Promise<ResourceRef>;
+
+export interface Authorizer {
+  readonly authorize: (action: Action, getResource: ResourceGetter) => MiddlewareHandler<AppEnv>;
+  readonly can: (c: Context<AppEnv>, action: Action, resource: ResourceRef) => Promise<boolean>;
+  readonly check: (c: Context<AppEnv>, action: Action, resource: ResourceRef) => Promise<Decision>;
+  /**
+   * List-filtering helper — takes items + a ref-extractor and returns
+   * only those items where the principal has `action` on the derived
+   * resource. Preserves input order. Empty in → empty out.
+   *
+   * Use in GET-list route handlers after fetching tenant-scoped rows;
+   * strips rows the caller can't read so the response only includes
+   * what they'd be allowed to touch.
+   */
+  readonly filterByCan: <T>(
+    c: Context<AppEnv>,
+    action: Action,
+    items: readonly T[],
+    refFn: (item: T) => ResourceRef,
+  ) => Promise<T[]>;
+}
+
+export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
+  async function checkInternal(
+    c: Context<AppEnv>,
+    action: Action,
+    resource: ResourceRef,
+  ): Promise<Decision> {
+    const principal = c.get('principal') as Principal | undefined;
+    if (principal === undefined) {
+      return {
+        allowed: false,
+        failing: 'actor',
+        reason: 'no principal on request (bearer/principal middleware did not run)',
+        evidence: {
+          action,
+          relation: '',
+          resource: `${resource.type}:${resource.id}`,
+          actorSubject: '',
+        },
+      };
+    }
+    const requestId = c.get('requestId');
+    const ctx =
+      typeof requestId === 'string' && requestId.length > 0
+        ? { correlationId: requestId }
+        : undefined;
+    return binding.check(principal, action, resource, ctx);
+  }
+
+  return {
+    check: checkInternal,
+    async can(c, action, resource) {
+      const d = await checkInternal(c, action, resource);
+      return d.allowed;
+    },
+    authorize(action, getResource) {
+      return async (c, next) => {
+        const resource = await getResource(c);
+        const decision = await checkInternal(c, action, resource);
+        if (!decision.allowed) {
+          const body = denyPayload(action, resource.type, resource.id, decision.reason);
+          c.status(403);
+          return c.json(body);
+        }
+        return next();
+      };
+    },
+    async filterByCan(c, action, items, refFn) {
+      if (items.length === 0) return [];
+      const principal = c.get('principal') as Principal | undefined;
+      if (principal === undefined) return [];
+      const refs = items.map(refFn);
+      const requestId = c.get('requestId');
+      const ctx =
+        typeof requestId === 'string' && requestId.length > 0
+          ? { correlationId: requestId }
+          : undefined;
+      const decisions = await binding.checkBatch(principal, action, refs, ctx);
+      const out: (typeof items)[number][] = [];
+      for (let i = 0; i < items.length; i++) {
+        if (decisions[i]?.allowed) out.push(items[i] as (typeof items)[number]);
+      }
+      return out;
+    },
+  };
+}

package/src/middleware/error-mapper.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from '../errors.js';
+
+/**
+ * Top-level catch-all. Any uncaught exception is translated to a
+ * `500 internal-server-error` wire error. Domain errors returned via
+ * `Result<T, E>` are handled per-route — this middleware only catches
+ * thrown exceptions (framework bugs, DB failures without Result wrap,
+ * etc.).
+ *
+ * The requestId embedded in the response body matches
+ * `middleware/request-id.ts`, so a caller can correlate.
+ */
+export function errorMapperMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    try {
+      await next();
+      return;
+    } catch (cause) {
+      const requestId = (c.get('requestId') as string | undefined) ?? 'req-unknown';
+      const message = cause instanceof Error ? cause.message : String(cause);
+      const body = toWireError(
+        {
+          code: 'internal-server-error',
+          message: message.length > 0 ? message : 'Unhandled server error',
+        },
+        requestId,
+      );
+      c.status(statusFor('internal-server-error') as never);
+      return c.json(body);
+    }
+  };
+}