create-ailk 0.12.1 → 0.13.0

package/templates/apps/api/src/middleware/__tests__/rate-limit.test.ts

@@ -18,6 +18,7 @@ import {
   rateLimitMiddleware,
   __resetBuckets,
   __bucketCount,
+  FORWARDED_VISITOR_ROUTES,
   buildTrustedKeyDigests,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
   resolveRateLimitIdentity,
@@ -764,6 +765,81 @@ describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394
     });
   });
 
+  // #7633 conductor amendment (the relay's security review, #7644): once a
+  // site relays its visitors' booking calls, every one reaches the hub from
+  // the site's server. The two relayed schedule routes join the keyed-visitor
+  // list, each under its own method only.
+  describe("the two relayed schedule routes count each keyed visitor separately (#7633)", () => {
+    const AVAILABILITY = "/v1/schedule/availability";
+    const BOOK = "/v1/schedule/book";
+    const EVENT_META = "/v1/schedule/event-meta";
+
+    /** A schedule-shaped scope: the four routes, each under GET and POST. */
+    function scheduleApp(): FastifyInstance {
+      const instance = Fastify({ trustProxy: true });
+      instance.register(rateLimitMiddleware, {
+        scope: "schedule",
+        perIpPerMinute: 10,
+        perKeyPerMinute: 300,
+        trustedKeyDigests: digests(),
+      });
+      for (const url of [AVAILABILITY, BOOK, EVENT_META, "/v1/schedule/meeting-types"]) {
+        instance.get(url, async () => ({ ok: true }));
+        instance.post(url, async () => ({ ok: true }));
+      }
+      return instance;
+    }
+
+    async function call(
+      method: "GET" | "POST",
+      url: string,
+      headers: Record<string, string>,
+    ): Promise<number> {
+      if (!app) throw new Error("no app");
+      const res = await app.inject({ method, url, headers });
+      return res.statusCode;
+    }
+
+    it.each<["GET" | "POST", string]>([
+      ["GET", AVAILABILITY],
+      ["POST", BOOK],
+    ])("%s %s: two visitors behind one site key are counted separately", async (method, url) => {
+      app = scheduleApp();
+      await app.ready();
+      for (let i = 0; i < 10; i++) {
+        expect(await call(method, url, keyed("203.0.113.1"))).toBe(200);
+      }
+      expect(await call(method, url, keyed("203.0.113.1"))).toBe(429);
+      expect(await call(method, url, keyed("203.0.113.2"))).toBe(200);
+    });
+
+    it.each<["GET" | "POST", string]>([
+      ["POST", AVAILABILITY],
+      ["GET", BOOK],
+      ["GET", EVENT_META],
+      ["GET", "/v1/schedule/meeting-types"],
+    ])("%s %s is not on the list: the key is ignored and the eleventh distinct visitor is 429", async (method, url) => {
+      app = scheduleApp();
+      await app.ready();
+      const codes: number[] = [];
+      for (let i = 1; i <= 11; i++) {
+        codes.push(await call(method, url, keyed(`203.0.113.${i}`)));
+      }
+      expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+      expect(codes[10]).toBe(429);
+    });
+
+    it("lists each route under its own method", () => {
+      expect(FORWARDED_VISITOR_ROUTES).toEqual([
+        { method: "POST", url: "/v1/leads/submit" },
+        { method: "POST", url: "/v1/leads/subscribe" },
+        { method: "POST", url: "/v1/leads/callback" },
+        { method: "GET", url: AVAILABILITY },
+        { method: "POST", url: BOOK },
+      ]);
+    });
+  });
+
   describe("AC-5 — visitor IP validation and normalisation", () => {
     function identityApp(): FastifyInstance {
       const instance = Fastify({ trustProxy: true });

package/templates/apps/api/src/middleware/auth.ts

@@ -17,6 +17,22 @@
  *      and matched against `ApiToken.token` (stored as hash). Revoked / expired
  *      tokens fail closed; lastUsedAt is bumped on a successful hit.
  *
+ *   3. Agent path (#3591) — a bearer starting `ailk_agt_` is an agent's key
+ *      (`lib/agent-store.ts`). Its digest must match an enabled `Agent` whose
+ *      key-holder still holds a membership; anything else is the same 401.
+ *      The request acts as the agent's person (`request.userId`) and carries
+ *      `request.agent` — never `request.sessionTenant`, which stays the
+ *      cookie-only signal. An agent reaches ONLY routes a tenant guard tagged
+ *      (`config.tenantGuarded`, set by both guards' `onRoute` hook) and is 403
+ *      everywhere else; inside them the guard clamps its role. Each agent is
+ *      limited to 60 requests a minute, at most 10 of them writes (any
+ *      method but GET and HEAD).
+ *
+ * Every authenticated request carries `request.actor` — the person, or the
+ * agent and the person it acts for — and its request/reply loggers are
+ * rebound to name it, so Fastify's "request completed" line says who acted.
+ * No log line carries a credential.
+ *
  * Decision matrix (per spec §3):
  *   - Cookie valid                    → cookie path wins. Bearer ignored.
  *   - Cookie absent, bearer valid     → bearer path; CSRF skipped.
@@ -38,6 +54,13 @@ import type {
   FastifyRequest,
 } from "fastify";
 
+import {
+  AGENT_KEY_PREFIX,
+  findAgentByKeyHash,
+  hashAgentKey,
+  touchAgentLastActive,
+  type AgentGrant,
+} from "../lib/agent-store.js";
 import { prisma } from "../lib/prisma.js";
 
 /**
@@ -51,21 +74,57 @@ const COOKIE_NAMES = [
 
 const UNAUTHORIZED = { error: "unauthorized" } as const;
 const DATABASE_NOT_CONFIGURED = { error: "database_not_configured" } as const;
+const FORBIDDEN = {
+  ok: false,
+  error: { code: "forbidden", message: "Forbidden" },
+} as const;
+/**
+ * How stale `Agent.lastActiveAt` may be before an admitted request writes it
+ * again: the column is "active within the last minute", not a request log,
+ * so a busy agent costs one UPDATE a minute rather than one per request.
+ */
+const AGENT_ACTIVITY_WRITE_INTERVAL_MS = 60_000;
+
+const RATE_LIMITED = {
+  ok: false,
+  error: { code: "rate_limited", message: "Too many requests" },
+} as const;
 
 declare module "fastify" {
   interface FastifyRequest {
     userId?: Id<"user">;
     sessionTenant?: SessionTenant;
+    /** Set ONLY on the agent path (#3591 D4). */
+    agent?: AgentGrant;
+    /** Who made the request — set on every authenticated request (#3591 D9). */
+    actor?: RequestActor;
+  }
+  interface FastifyContextConfig {
+    /**
+     * Set by both tenant guards' `onRoute` hook on every route registered
+     * after them in their scope (#3591 D6). An agent is refused on any route
+     * without it.
+     */
+    tenantGuarded?: boolean;
   }
 }
 
+/**
+ * Who made a request (#3591 D9). A cookie session and a personal `ApiToken`
+ * act as their person; an agent acts on behalf of its responsible person.
+ */
+export type RequestActor =
+  | { type: "user"; userId: Id<"user"> }
+  | { type: "agent"; agentId: Id<"agent">; onBehalfOfUserId: Id<"user"> };
+
 /**
  * Active tenant context carried by a cookie session (multi-tenant module).
- * Set ONLY on the cookie path — bearer tokens carry no workspace binding yet
- * (#3591 tracks tenant-scoped agent auth), so bearer-authenticated requests
- * are denied by the tenant guard (default-deny), never silently granted a
- * tenant. `sessionRowId` is the Session PK, used by the workspace-switch
- * service to update the active tenant server-side.
+ * Set ONLY on the cookie path — a personal `ApiToken` carries no workspace
+ * binding, and an agent carries its own (`request.agent`, #3591), so neither
+ * ever sets this. Code that needs a cookie session (the billing portal, the
+ * workspace switch) can rely on its presence. `sessionRowId` is the Session
+ * PK, used by the workspace-switch service to update the active tenant
+ * server-side.
  */
 export type SessionTenant = {
   sessionRowId: Id<"session">;
@@ -181,6 +240,152 @@ async function resolveBearerToken(
   return row ?? undefined;
 }
 
+/**
+ * Decorate `request.actor` and rebind the request and reply loggers to name
+ * it (#3591 D9). Fastify writes its "request completed" line through
+ * `reply.log`, so that line carries the actor too.
+ */
+function bindActor(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  actor: RequestActor,
+): void {
+  request.actor = actor;
+  request.log = request.log.child(
+    actor.type === "agent"
+      ? {
+          actorType: "agent",
+          agentId: actor.agentId,
+          onBehalfOfUserId: actor.onBehalfOfUserId,
+        }
+      : { actorType: "user" },
+  );
+  reply.log = request.log;
+}
+
+// ── The per-agent limit (#3591 D4 step 5, SEC-3591-04/-14) ─────────────────
+//
+// In the handler, not `onRequest`: the shared limiter runs before any
+// identity exists, and a bucket must only ever be keyed on a VERIFIED agent
+// id, so an invented key never gets one. The shape of
+// `routes/subscription/portal.ts`'s per-user budget.
+
+const AGENT_WINDOW_MS = 60_000;
+const AGENT_REQUESTS_PER_WINDOW = 60;
+const AGENT_WRITES_PER_WINDOW = 10;
+/** Cap on distinct buckets — the oldest is evicted at capacity (DEF-011's shape). */
+const MAX_AGENT_BUCKETS = 5_000;
+
+type AgentBucket = { windowStartMs: number; requests: number; writes: number };
+const agentBuckets = new Map<string, AgentBucket>();
+
+/** Test-only reset. Not intended for production use. */
+export function __resetAgentRateBuckets(): void {
+  agentBuckets.clear();
+}
+
+function isWrite(method: string): boolean {
+  const m = method.toUpperCase();
+  return m !== "GET" && m !== "HEAD";
+}
+
+/** `undefined` when admitted; the seconds to wait when the agent is over budget. */
+function chargeAgentRateLimit(
+  agentId: string,
+  method: string,
+  now: number,
+): number | undefined {
+  let bucket = agentBuckets.get(agentId);
+  if (!bucket || now - bucket.windowStartMs >= AGENT_WINDOW_MS) {
+    if (!agentBuckets.has(agentId) && agentBuckets.size >= MAX_AGENT_BUCKETS) {
+      for (const [id, b] of agentBuckets) {
+        if (now - b.windowStartMs >= AGENT_WINDOW_MS) agentBuckets.delete(id);
+      }
+      if (agentBuckets.size >= MAX_AGENT_BUCKETS) {
+        const oldest = agentBuckets.keys().next().value;
+        if (oldest !== undefined) agentBuckets.delete(oldest);
+      }
+    }
+    // Re-insert, so Map order stays oldest-window-first for the eviction above.
+    agentBuckets.delete(agentId);
+    bucket = { windowStartMs: now, requests: 0, writes: 0 };
+    agentBuckets.set(agentId, bucket);
+  }
+  bucket.requests += 1;
+  if (isWrite(method)) bucket.writes += 1;
+  if (
+    bucket.requests > AGENT_REQUESTS_PER_WINDOW ||
+    bucket.writes > AGENT_WRITES_PER_WINDOW
+  ) {
+    return Math.max(
+      1,
+      Math.ceil((bucket.windowStartMs + AGENT_WINDOW_MS - now) / 1_000),
+    );
+  }
+  return undefined;
+}
+
+/**
+ * The agent path (#3591 D4, D6). The key is never logged and never echoed:
+ * every refusal is a fixed body.
+ */
+async function authenticateAgent(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  key: string,
+  now: number,
+): Promise<void> {
+  const row = await findAgentByKeyHash(hashAgentKey(key)).catch(() => null);
+  // Unknown, switched off, or its key-holder has left the organization (the
+  // FK set the column null) — one body for each, so none is an oracle.
+  if (!row || !row.enabled || !row.keyIssuedToMembershipId) {
+    reply.code(401).send(UNAUTHORIZED);
+    return;
+  }
+
+  // Brand assertion at the Prisma read edge (ADR-0031 rule 5): the agents
+  // table's format CHECKs guarantee these columns hold well-formed ids.
+  const agentId = row.id as Id<"agent">;
+  const personId = row.responsible.userId as Id<"user">;
+  request.userId = personId;
+  request.agent = {
+    agentId,
+    workspaceId: row.workspaceId as Id<"workspace">,
+    organizationId: row.organizationId as Id<"organization">,
+    responsibleMembershipId: row.responsible.id as Id<"membership">,
+    permissionLevel: row.permissionLevel,
+  };
+  bindActor(request, reply, {
+    type: "agent",
+    agentId,
+    onBehalfOfUserId: personId,
+  });
+
+  const retryAfter = chargeAgentRateLimit(agentId, request.method, now);
+  if (retryAfter !== undefined) {
+    reply.code(429).header("Retry-After", String(retryAfter)).send(RATE_LIMITED);
+    return;
+  }
+
+  // D6 — an agent reaches only routes a tenant guard runs on. Every other
+  // route in the auth scope (tokens, user data, `/me` reads, the leads union,
+  // the workspace switcher), and any route added outside a tenant scope
+  // later, is closed to it by default.
+  if (request.routeOptions.config?.tenantGuarded !== true) {
+    reply.code(403).send(FORBIDDEN);
+    return;
+  }
+
+  // Best-effort, as the token path bumps lastUsedAt: a failure never 401s.
+  // Only an admitted request writes, and only when the stamp is a minute old.
+  if (
+    !row.lastActiveAt ||
+    now - row.lastActiveAt.getTime() >= AGENT_ACTIVITY_WRITE_INTERVAL_MS
+  ) {
+    touchAgentLastActive(agentId, new Date(now)).catch(() => undefined);
+  }
+}
+
 export type AuthPreHandlerOptions = {
   /**
    * The browser origins a cookie-authenticated write may come from — exact
@@ -283,6 +488,7 @@ export function makeAuthPreHandler(opts: AuthPreHandlerOptions) {
           activeOrganizationId: session.activeOrganizationId as Id<"organization"> | null,
           activeWorkspaceId: session.activeWorkspaceId as Id<"workspace"> | null,
         };
+        bindActor(request, reply, { type: "user", userId: request.userId });
         return;
       }
       // Cookie present but invalid / expired → 401 (no silent bearer fallback).
@@ -291,6 +497,10 @@ export function makeAuthPreHandler(opts: AuthPreHandlerOptions) {
     }
 
     const bearer = readBearer(request);
+    if (bearer?.startsWith(AGENT_KEY_PREFIX)) {
+      await authenticateAgent(request, reply, bearer, now);
+      return;
+    }
     if (bearer) {
       const row = await resolveBearerToken(bearer).catch(() => undefined);
       if (!row) {
@@ -306,6 +516,8 @@ export function makeAuthPreHandler(opts: AuthPreHandlerOptions) {
         return;
       }
       request.userId = row.userId as Id<"user">;
+      // A personal token acts as its person, as before (#3591 D9).
+      bindActor(request, reply, { type: "user", userId: request.userId });
       // Best-effort: bump lastUsedAt. Failure here MUST NOT 401 — the caller
       // is already authenticated. Swallow the error and continue.
       prisma.apiToken
@@ -333,6 +545,8 @@ export const authPreHandlerPlugin: FastifyPluginCallback<
   const handler = makeAuthPreHandler(opts);
   fastify.decorateRequest("userId", undefined);
   fastify.decorateRequest("sessionTenant", undefined);
+  fastify.decorateRequest("agent", undefined);
+  fastify.decorateRequest("actor", undefined);
   fastify.addHook("preHandler", handler);
   done();
 };

package/templates/apps/api/src/middleware/default-tenant.ts

@@ -16,7 +16,10 @@
  * Default-deny — every branch that is not an explicit grant is a denial:
  *
  *   - unauthenticated                                    → 401
- *   - bearer-authenticated (no cookie session — #3591)   → 403
+ *   - a personal ApiToken (no cookie session, no agent)  → 403
+ *   - an agent (#3591) whose person is not the operator,
+ *     or not bound to the default workspace under the
+ *     operator's own Membership                          → 403
  *   - AILK_OPERATOR_EMAIL is unset                       → 403
  *   - the caller's email is not the pinned one           → 403
  *   - the deployment is not unambiguously single-tenant  → 403
@@ -57,6 +60,7 @@ import type {
 } from "fastify";
 
 import {
+  resolveDefaultTenantForAgent,
   resolveDefaultTenantForOperator,
   type TenantContext,
 } from "../services/default-tenant.js";
@@ -90,14 +94,20 @@ export async function defaultTenantPreHandler(
     return;
   }
 
-  // Bearer tokens carry no workspace binding (#3591) — denied here, the same
-  // default-deny `resolveActiveTenant` applies on the multi-tenant path.
-  if (!request.sessionTenant) {
+  // An agent (#3591 D5) goes through the same operator resolution, bound to
+  // its own workspace and Membership, with its role clamped. Any other caller
+  // without a cookie session — a personal ApiToken — carries no workspace
+  // binding and is denied, the same default-deny `resolveActiveTenant`
+  // applies on the multi-tenant path.
+  let tenant: TenantContext | null;
+  if (request.agent) {
+    tenant = await resolveDefaultTenantForAgent(userId, request.agent);
+  } else if (!request.sessionTenant) {
     reply.code(403).send(FORBIDDEN);
     return;
+  } else {
+    tenant = await resolveDefaultTenantForOperator(userId);
   }
-
-  const tenant = await resolveDefaultTenantForOperator(userId);
   if (!tenant) {
     reply.code(403).send(FORBIDDEN);
     return;
@@ -116,8 +126,18 @@ export async function defaultTenantPreHandler(
 }
 
 /**
- * Plugin form, mirroring `tenantPreHandlerPlugin`: skip-override so the hook
- * propagates to sibling route plugins registered in the same scope.
+ * Tag a route as tenant-guarded (#3591 D6). Both guard plugins add this as an
+ * `onRoute` hook, so it reaches exactly the routes their `preHandler` does:
+ * every route registered after the plugin in its scope. The auth preHandler
+ * refuses an agent on any route without the tag.
+ */
+export function tagTenantGuarded(routeOptions: { config?: object }): void {
+  routeOptions.config = { ...routeOptions.config, tenantGuarded: true };
+}
+
+/**
+ * Plugin form, mirroring `tenantPreHandlerPlugin`: skip-override so the hooks
+ * propagate to sibling route plugins registered in the same scope.
  */
 export const defaultTenantPreHandlerPlugin: FastifyPluginCallback = (
   fastify,
@@ -125,6 +145,7 @@ export const defaultTenantPreHandlerPlugin: FastifyPluginCallback = (
   done,
 ) => {
   fastify.decorateRequest("tenant", undefined);
+  fastify.addHook("onRoute", tagTenantGuarded);
   fastify.addHook("preHandler", defaultTenantPreHandler);
   done();
 };

package/templates/apps/api/src/middleware/rate-limit.ts

@@ -49,7 +49,13 @@
  * Per-visitor lead writes from a keyed spoke (#7394): a spoke's lead writes
  * carry the visitor's IP in `x-ailk-visitor-ip`, which this middleware
  * believes only alongside a hub-issued key in `x-ailk-visitor-forward-key`,
- * and only on the three `FORWARDED_VISITOR_ROUTES`. A believed visitor is
+ * and only on the `FORWARDED_VISITOR_ROUTES`: the three lead writes, and
+ * since #7633 the two schedule calls a site's same-origin relay forwards
+ * (#7644) — `GET /v1/schedule/availability` and `POST /v1/schedule/book`. The
+ * global limiter (`server.ts`) passes the hub's digests, so a listed call is
+ * counted per visitor there; a scope's own limiter does so only when its
+ * registration passes `trustedKeyDigests` too, as the leads and schedule
+ * scopes do. A believed visitor is
  * counted as `v<n>,<ip>` (n = the key's position in
  * `AILK_VISITOR_FORWARD_KEYS`), and every such request also counts against
  * its key's own `key,<n>` bucket. Both forms contain a comma, which `req.ip`
@@ -142,14 +148,28 @@ export const DEFAULT_PER_IP_PER_MINUTE_STRICT = 10;
 export const MAX_BUCKETS = 10_000;
 
 /**
- * The only routes on which a forwarded visitor IP is believed (#7394 DD-2):
- * the three lead writes. Matched against `req.routeOptions.url`, the
+ * The schedule scope's per-forwarding-key ceiling (#7633): well below the
+ * lead routes' 300, because a booking is a real booking at the provider.
+ * `AILK_RATE_LIMIT_SCHEDULE_PER_KEY_PER_MINUTE` overrides it.
+ */
+export const DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE = 60;
+
+/**
+ * The only (method, route) pairs on which a forwarded visitor IP is believed
+ * (#7394 DD-2): the three lead writes, and the two schedule calls a site's
+ * relay forwards on its visitors' behalf (#7633, the relay's security
+ * review). Matched against `req.method` and `req.routeOptions.url`, the
  * registered route pattern.
  */
-export const FORWARDED_VISITOR_ROUTES: readonly string[] = [
-  "/v1/leads/submit",
-  "/v1/leads/subscribe",
-  "/v1/leads/callback",
+export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
+  method: "GET" | "POST";
+  url: string;
+}>[] = [
+  { method: "POST", url: "/v1/leads/submit" },
+  { method: "POST", url: "/v1/leads/subscribe" },
+  { method: "POST", url: "/v1/leads/callback" },
+  { method: "GET", url: "/v1/schedule/availability" },
+  { method: "POST", url: "/v1/schedule/book" },
 ];
 
 const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
@@ -250,8 +270,9 @@ function normaliseVisitorIp(raw: string): string | null {
 }
 
 /**
- * The rate-limit identity of a request (#7394 DD-2). A `POST` to one of
- * `FORWARDED_VISITOR_ROUTES`, presenting a key whose digest matches a
+ * The rate-limit identity of a request (#7394 DD-2). A request matching one
+ * of `FORWARDED_VISITOR_ROUTES` by method and route, presenting a key whose
+ * digest matches a
  * non-null slot, with a valid `x-ailk-visitor-ip`, is `v<n>,<ip>` where `n`
  * is the first matching slot. Everything else is `req.ip`. Every slot is
  * compared, in constant time per slot, without stopping at the first match.
@@ -262,10 +283,11 @@ export function resolveRateLimitIdentity(
 ): { identity: string; keyIndex: number | null } {
   const fallback = { identity: req.ip, keyIndex: null };
   if (!trustedKeyDigests.some((digest) => digest !== null)) return fallback;
-  if (req.method !== "POST") return fallback;
-  if (!FORWARDED_VISITOR_ROUTES.includes(req.routeOptions.url ?? "")) {
-    return fallback;
-  }
+  const url = req.routeOptions.url ?? "";
+  const listed = FORWARDED_VISITOR_ROUTES.some(
+    (route) => route.method === req.method && route.url === url,
+  );
+  if (!listed) return fallback;
 
   const presented = req.headers[FORWARD_KEY_HEADER];
   if (typeof presented !== "string" || presented === "") return fallback;