@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/src/middleware/auth.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Context, MiddlewareHandler, Next } from 'hono';
+import { getCookie } from 'hono/cookie';
 
 import type { ReviewerRole } from '@kindgi/authz';
 import type { ApiTokenId, SessionId, TenantId, UserId } from '@kindgi/types';
@@ -49,11 +50,27 @@ export interface TokenResolution {
    */
   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')`.
+   * The id of a durable API key (`POST /v1/tokens`), surfaced as
+   * `c.get('tokenId')`. The caller is the key's principal: `userId` for a
+   * person's key, `serviceAccountId` for a service account's. A key with
+   * neither (a store built before principals) is its own service account,
+   * `service_account:<tokenId>`.
    */
   readonly tokenId?: ApiTokenId;
+  /** The service account an API key acts for (`service_account:<id>`). */
+  readonly serviceAccountId?: string;
+  /**
+   * An API key's role: the most it may do, under its principal's grants.
+   * A `member` key is refused tenant-admin actions even when its principal
+   * is an admin.
+   */
+  readonly tokenRole?: 'admin' | 'member';
+  /**
+   * The project an API key is narrowed to. A request naming another
+   * project is refused (`key-project-mismatch`), and so is an `admin`
+   * action on the tenant.
+   */
+  readonly tokenProjectId?: string;
   /**
    * Optional session id. Populated by the session-token verifier path
    * (`kgi_sk_*` tokens) so `/v1/identity/whoami` and `/v1/auth/logout`
@@ -115,10 +132,45 @@ export interface TokenResolution {
 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.
+ * The cookie a browser carries its session token in, when the deployment
+ * turns cookie sessions on (`SessionConfig.cookie`). `__Host-`: Secure,
+ * Path=/, no Domain, so it's sent only to the origin that set it.
+ */
+export const SESSION_COOKIE_NAME = '__Host-kindgi_session' as const;
+
+/**
+ * Cookie sessions: where the middleware reads a browser's session token
+ * when the request has no `Authorization` header.
+ */
+export interface SessionCookieOptions {
+  /** The cookie's name. Default `SESSION_COOKIE_NAME`. */
+  readonly name?: string;
+  /**
+   * The origins a cookie-authenticated request may come from (the
+   * console's origin, e.g. `https://kindgi.example.com`). An unsafe method
+   * (anything but GET, HEAD and OPTIONS) authenticated by the cookie must
+   * carry one of them in `Origin`, else 403 `csrf-origin-mismatch`; so
+   * must a request with no `Origin` at all. Bearer requests are unaffected.
+   */
+  readonly allowedOrigins: readonly string[];
+  /**
+   * Also accept an `Origin` naming the host the request was sent to (its
+   * `Host`, or `X-Forwarded-Host` behind a proxy that sets it): the
+   * console served from the runtime itself, wherever it's reached. For a
+   * deployment that doesn't know its public URL. A cross-site page can't
+   * forge `Origin`, nor add `X-Forwarded-Host` without a CORS preflight.
+   */
+  readonly sameOrigin?: boolean;
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * The older session token, `kgi_sk_<sessionId>`, for a session store
+ * without `resolveToken`. A store with it mints its own token
+ * (`SessionCreateOutput.token`), and the routes hand that out instead.
+ * Session tokens are opaque to clients: never parse one outside the
+ * middleware or the store that minted it.
  */
 export function encodeSessionToken(sessionId: SessionId): string {
   return `${SESSION_TOKEN_PREFIX}${sessionId as unknown as string}`;
@@ -150,6 +202,12 @@ export interface BearerAuthMiddlewareOptions {
    * fewer writes but coarser inactivity enforcement. Defaults to 60s.
    */
   readonly touchThrottleMs?: number;
+  /**
+   * Read a session token from a cookie when the request carries no
+   * `Authorization` header (browser sessions). Only `kgi_sk_` tokens are
+   * taken from it, and only with a `sessionStore`.
+   */
+  readonly sessionCookie?: SessionCookieOptions;
   /**
    * Accept public run tokens (`kgi_pt_…`), verified against
    * `signingKey`, on the routes `isAllowed` admits (every other route
@@ -169,9 +227,9 @@ const DEFAULT_TOUCH_THROTTLE_MS = 60_000;
  * 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.
+ * - `kgi_sk_…` — session tokens. Verified by the session store
+ *   (`resolveToken`, or `get` for an older store); 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.
  */
@@ -186,36 +244,13 @@ export function bearerAuthMiddleware(
   // 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);
-    }
-
+  // Everything after the token is found: the header's or the cookie's.
+  const authenticate = async (
+    c: Context,
+    next: Next,
+    token: string,
+    requestId: string,
+  ): Promise<Response | undefined> => {
     if (token.startsWith(PUBLIC_RUN_TOKEN_PREFIX)) {
       return authenticatePublicRunToken(c, next, token, requestId, options.publicRunTokens);
     }
@@ -297,6 +332,18 @@ export function bearerAuthMiddleware(
     if (resolution.tokenId !== undefined) {
       c.set('tokenId', resolution.tokenId);
     }
+    if (resolution.serviceAccountId !== undefined) {
+      c.set('serviceAccountId', resolution.serviceAccountId);
+    }
+    if (resolution.tokenRole !== undefined) {
+      c.set('tokenRole', resolution.tokenRole);
+    }
+    if (resolution.tokenProjectId !== undefined) {
+      c.set('tokenProjectId', resolution.tokenProjectId);
+    }
+    if (resolution.expiresAt !== undefined && !isSessionToken) {
+      c.set('tokenExpiresAt', resolution.expiresAt);
+    }
     if (resolution.sessionId !== undefined) {
       c.set('sessionId', resolution.sessionId);
     }
@@ -337,6 +384,45 @@ export function bearerAuthMiddleware(
     await next();
     return;
   };
+  return async (c, next) => {
+    const requestId = c.get('requestId') as string;
+    const header = c.req.header('authorization');
+    if (header === undefined || header.length === 0) {
+      const fromCookie = sessionCookieToken(c, sessionStore, options.sessionCookie);
+      if (fromCookie !== undefined) {
+        const refusal = csrfRefusal(c, options.sessionCookie as SessionCookieOptions, requestId);
+        if (refusal !== undefined) return refusal;
+        c.set('sessionCookieName', options.sessionCookie?.name ?? SESSION_COOKIE_NAME);
+        return authenticate(c, next, fromCookie, requestId);
+      }
+      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);
+    }
+
+    return authenticate(c, next, token, requestId);
+  };
 }
 
 /**
@@ -345,31 +431,20 @@ export function bearerAuthMiddleware(
  * 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.
+ * A store with `resolveToken` gets the whole token: it reads the tenant
+ * from it, looks only in that tenant and compares a hash, so nothing is
+ * read across tenants before the token is authenticated. The session it
+ * returns is authoritative for `tenantId`.
  *
- * 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.
+ * A store without it gets the older lookup: the token's remainder is the
+ * session id, read with `get({ tenantId: MULTI_TENANT_LOOKUP, sessionId })`,
+ * which such stores must honor by skipping the tenant filter.
  */
 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,
-  });
+  const session = await findSession(sessionStore, token);
   if (session === null) return null;
   return {
     tenantId: session.tenantId,
@@ -386,12 +461,93 @@ async function resolveSessionToken(
   };
 }
 
+/**
+ * The session token in the request's cookie, when cookie sessions are on
+ * and the cookie holds a session token; `undefined` otherwise (an API
+ * key or any other token is never taken from a cookie).
+ */
+function sessionCookieToken(
+  c: Context,
+  sessionStore: SessionStoreBinding | undefined,
+  cookie: SessionCookieOptions | undefined,
+): string | undefined {
+  if (cookie === undefined || sessionStore === undefined) return undefined;
+  const value = getCookie(c, cookie.name ?? SESSION_COOKIE_NAME)?.trim();
+  if (value === undefined || !value.startsWith(SESSION_TOKEN_PREFIX)) return undefined;
+  return value;
+}
+
+/**
+ * A cookie-authenticated unsafe request must come from an allowed origin:
+ * a browser always sends `Origin` on such requests, and a cross-site page
+ * can't forge it. A missing `Origin` is refused too.
+ */
+function csrfRefusal(
+  c: Context,
+  cookie: SessionCookieOptions,
+  requestId: string,
+): Response | undefined {
+  if (SAFE_METHODS.has(c.req.method)) return undefined;
+  const origin = c.req.header('origin');
+  if (origin !== undefined && cookie.allowedOrigins.includes(origin)) return undefined;
+  if (origin !== undefined && cookie.sameOrigin === true && isSameHost(c, origin)) return undefined;
+  const body = toWireError(
+    {
+      code: 'csrf-origin-mismatch',
+      message:
+        origin === undefined
+          ? 'A request signed in by the session cookie must say where it comes from (Origin)'
+          : `A request signed in by the session cookie can't come from ${origin}`,
+    },
+    requestId,
+  );
+  return c.json(body, statusFor('csrf-origin-mismatch') as never);
+}
+
+/**
+ * Whether `origin` names the host this request was sent to, over https (or
+ * plain http on loopback, for local development). The session cookie is
+ * `__Host-` and Secure, so a browser holding it is on https: a plain-http
+ * page on the same host (an on-path attacker's) is not the same origin.
+ */
+function isSameHost(c: Context, origin: string): boolean {
+  let host: string;
+  try {
+    const url = new URL(origin);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback(url.hostname))) {
+      return false;
+    }
+    host = url.host;
+  } catch {
+    return false;
+  }
+  // The request's own URL carries its Host (the Node server builds it from it).
+  const sentTo = [
+    new URL(c.req.url).host,
+    c.req.header('host'),
+    c.req.header('x-forwarded-host')?.split(',')[0]?.trim(),
+  ];
+  return sentTo.some((h) => h !== undefined && h !== '' && h.toLowerCase() === host.toLowerCase());
+}
+
+async function findSession(sessionStore: SessionStoreBinding, token: string) {
+  if (sessionStore.resolveToken !== undefined) {
+    return sessionStore.resolveToken({ token });
+  }
+  const sessionIdStr = token.slice(SESSION_TOKEN_PREFIX.length);
+  if (sessionIdStr.length === 0) return null;
+  return sessionStore.get({
+    tenantId: MULTI_TENANT_LOOKUP,
+    sessionId: sessionIdStr as unknown as SessionId,
+  });
+}
+
 /**
  * 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.
+ * id without knowing the tenant in advance: only for a store without
+ * `resolveToken`. Such stores MUST honor it 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;
 
@@ -436,3 +592,13 @@ async function authenticatePublicRunToken(
   await next();
   return undefined;
 }
+
+/** `localhost`, `127.0.0.0/8` or `::1`. */
+function isLoopback(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname === '[::1]' ||
+    hostname === '::1' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)
+  );
+}

package/src/middleware/authorize.ts

@@ -23,6 +23,8 @@ import {
   type Action,
   type AuthzCheckBinding,
   type Decision,
+  OBJECT_ACTIONS,
+  type ObjectType,
   type Principal,
   type ResourceRef,
   denyPayload,
@@ -57,9 +59,37 @@ export interface Authorizer {
     items: readonly T[],
     refFn: (item: T) => ResourceRef,
   ) => Promise<T[]>;
+  /**
+   * The ids of every object of `type` the caller may `action`
+   * (`AuthzCheckBinding.listObjects`); `undefined` when the binding
+   * can't list, so the caller falls back to `filterByCan`.
+   */
+  readonly listObjects?: (
+    c: Context<AppEnv>,
+    action: Action,
+    type: ResourceRef['type'],
+  ) => Promise<readonly string[] | undefined>;
 }
 
 export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
+  /**
+   * Whether a resource is inside the project the caller's API key is
+   * limited to (always, for a caller with no such key). The tenant, orgs,
+   * teams and projects are held by `keyCeilingDeny`; anything else must
+   * belong to the key's project, as the store says (`inProject`). Without
+   * that answer, the key reaches no other resource.
+   */
+  async function inKeyProject(
+    c: Context<AppEnv>,
+    principal: Principal,
+    resource: ResourceRef,
+  ): Promise<boolean> {
+    const keyProject = c.get('tokenProjectId');
+    if (keyProject === undefined || STRUCTURAL.has(resource.type)) return true;
+    if (binding.inProject === undefined) return false;
+    return binding.inProject(principal, resource, keyProject);
+  }
+
   async function checkInternal(
     c: Context<AppEnv>,
     action: Action,
@@ -79,6 +109,17 @@ export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
         },
       };
     }
+    const undefinedPair = undefinedRelation(action, resource);
+    if (undefinedPair !== undefined) return undefinedPair;
+    const ceiling = keyCeilingDeny(c, action, resource);
+    if (ceiling !== undefined) return ceiling;
+    if (!(await inKeyProject(c, principal, resource))) {
+      return keyDecision(
+        action,
+        resource,
+        `the API key is limited to project ${c.get('tokenProjectId')}`,
+      );
+    }
     const requestId = c.get('requestId');
     const ctx =
       typeof requestId === 'string' && requestId.length > 0
@@ -124,7 +165,19 @@ export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
       if (items.length === 0) return [];
       const principal = c.get('principal') as Principal | undefined;
       if (principal === undefined) return [];
-      const refs = items.map(refFn);
+      // What the model can't answer, or the key itself rules out, never
+      // reaches the store.
+      const allowedByKey = await Promise.all(
+        items.map(
+          async (item) =>
+            undefinedRelation(action, refFn(item)) === undefined &&
+            keyCeilingDeny(c, action, refFn(item)) === undefined &&
+            (await inKeyProject(c, principal, refFn(item))),
+        ),
+      );
+      const open = items.filter((_, i) => allowedByKey[i]);
+      if (open.length === 0) return [];
+      const refs = open.map(refFn);
       const requestId = c.get('requestId');
       const ctx =
         typeof requestId === 'string' && requestId.length > 0
@@ -132,10 +185,93 @@ export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
           : 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]);
+      for (let i = 0; i < open.length; i++) {
+        if (decisions[i]?.allowed) out.push(open[i] as (typeof items)[number]);
       }
       return out;
     },
+    async listObjects(c, action, type) {
+      if (binding.listObjects === undefined) return undefined;
+      const principal = c.get('principal') as Principal | undefined;
+      if (principal === undefined) return [];
+      const requestId = c.get('requestId');
+      const ctx =
+        typeof requestId === 'string' && requestId.length > 0
+          ? { correlationId: requestId }
+          : undefined;
+      return binding.listObjects(principal, action, type, ctx);
+    },
   };
 }
+
+/**
+ * A check must name a relation the authorization model defines for the
+ * resource's type (`OBJECT_ACTIONS`, kept equal to the runtime's model by
+ * its tests). Any other pair is a bug in the route: the PDP rejects it
+ * for everyone, the seed admin included, and only with authorization on,
+ * so it's refused here, naming the pair, and logged.
+ */
+function undefinedRelation(action: Action, resource: ResourceRef): Decision | undefined {
+  const defined = OBJECT_ACTIONS[resource.type as ObjectType] as readonly Action[] | undefined;
+  if (defined?.includes(action) === true) return undefined;
+  const reason = `the authorization model has no \`${action}\` on \`${resource.type}\` (a check that can never pass: a bug in the route)`;
+  console.error(`[authz] ${reason}`);
+  return {
+    allowed: false,
+    failing: 'invalid-action',
+    reason,
+    evidence: {
+      action,
+      relation: '',
+      resource: `${resource.type}:${resource.id}`,
+      actorSubject: '',
+    },
+  };
+}
+
+/** Types a key's project limit is checked on directly, not through `inProject`. */
+const STRUCTURAL: ReadonlySet<string> = new Set(['tenant', 'org', 'team', 'project']);
+
+function keyDecision(action: Action, resource: ResourceRef, reason: string): Decision {
+  return {
+    allowed: false,
+    failing: 'scope',
+    reason,
+    evidence: {
+      action,
+      relation: '',
+      resource: `${resource.type}:${resource.id}`,
+      actorSubject: '',
+    },
+  };
+}
+
+/**
+ * What an API key itself rules out, before the principal's grants are
+ * asked: a key can do less than its principal, never more.
+ *
+ * - A `member` key takes no `admin` action on the tenant, even for a
+ *   principal who is a tenant admin: a day-to-day key can't change keys,
+ *   grants or policies. Below the tenant, its principal's roles hold: a
+ *   project admin's member key administers that project.
+ * - A key limited to a project acts on no other project, and takes no
+ *   `admin` action on the tenant, an org or a team. Other resources must
+ *   be in its project (`inKeyProject`).
+ */
+function keyCeilingDeny(
+  c: Context<AppEnv>,
+  action: Action,
+  resource: ResourceRef,
+): Decision | undefined {
+  if (action === 'admin' && resource.type === 'tenant' && c.get('tokenRole') === 'member') {
+    return keyDecision(action, resource, 'a member API key takes no admin action on the tenant');
+  }
+  const keyProject = c.get('tokenProjectId');
+  if (keyProject === undefined) return undefined;
+  const otherProject = resource.type === 'project' && resource.id !== keyProject;
+  const aboveIt =
+    resource.type !== 'project' && STRUCTURAL.has(resource.type) && action === 'admin';
+  return otherProject || aboveIt
+    ? keyDecision(action, resource, `the API key is limited to project ${keyProject}`)
+    : undefined;
+}

package/src/middleware/error-mapper.ts

@@ -22,6 +22,11 @@ import { statusFor, toWireError } from '../errors.js';
  *
  * The requestId embedded in the response body matches
  * `middleware/request-id.ts`, so a caller can correlate.
+ *
+ * A failed database query's message carries its SQL and its parameters
+ * (Drizzle's `Failed query: … params: …`), which can be a person's email or
+ * address: the body says only that a query failed, and the log keeps the
+ * whole error.
  */
 export function mapThrownError(cause: Error, c: Context): Response {
   if ('getResponse' in cause && typeof cause.getResponse === 'function') {
@@ -34,10 +39,19 @@ export function mapThrownError(cause: Error, c: Context): Response {
   const body = toWireError(
     {
       code: 'internal-server-error',
-      message: cause.message.length > 0 ? cause.message : 'Unhandled server error',
+      message: isQueryError(cause)
+        ? 'A database query failed.'
+        : cause.message.length > 0
+          ? cause.message
+          : 'Unhandled server error',
     },
     requestId,
   );
   c.status(statusFor('internal-server-error') as never);
   return c.json(body);
 }
+
+/** Drizzle's wrapper around a failed query, whose message is the SQL and its values. */
+function isQueryError(cause: Error): boolean {
+  return cause.name === 'DrizzleQueryError' || cause.message.startsWith('Failed query: ');
+}