create-ailk 0.14.0 → 0.16.0

package/templates/apps/api/src/middleware/__tests__/auth.hub-session-path.test.ts

@@ -0,0 +1,310 @@
+/**
+ * @file auth.hub-session-path.test.ts
+ *
+ * The hub-credential branch of the auth preHandler (#7894, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D6; AC-4, AC-5, AC-7).
+ *
+ * A bearer starting `ailk_hst_` is admitted only beside the SAME spoke's key,
+ * only while its grant is live and its person verified, and only on the four
+ * routes of `HUB_SESSION_ROUTES`. Any other route answers 404 with no handler
+ * run (the status `lib/account-config.ts`'s `read()` already loads as "nothing
+ * for this caller"), never 403.
+ *
+ * Stub routes stand in for #7877's three member reads, which are unmerged; each
+ * one records that its handler ran, so "404 with no handler run" is asserted,
+ * not assumed.
+ *
+ * External dependency boundary mocked:
+ *   - @working-theory/database (via the prisma singleton; __mocks__/prisma.ts)
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+import {
+  installHubSignInFakeDb,
+  seedSpoke,
+  seedUser,
+  type FakeHubDb,
+  type FakeUser,
+  type SeededSpoke,
+} from "../../__tests__/support/hub-sign-in-fake-db.js";
+import { mintCredential, sha256Hex } from "../../lib/hub-sign-in-store.js";
+import { prisma } from "../../lib/prisma.js";
+import { authPreHandlerPlugin, HUB_SESSION_ROUTES } from "../auth.js";
+
+const db = jest.mocked(prisma);
+
+const FRONTEND = "https://app.example.com";
+
+let state: FakeHubDb;
+let app: FastifyInstance;
+let user: FakeUser;
+let spokeA: SeededSpoke;
+let spokeB: SeededSpoke;
+let handlerRuns: string[];
+
+/** A live credential for (user, spoke), stored the way the token route stores it. */
+function grant(
+  s: SeededSpoke,
+  overrides: {
+    expiresAt?: Date;
+    revokedAt?: Date | null;
+    userId?: string;
+  } = {},
+): string {
+  const credential = mintCredential();
+  state.authorizations.push({
+    id: `oautha_${state.authorizations.length + 1}`,
+    userId: overrides.userId ?? user.id,
+    clientId: s.client.id,
+    scopes: ["account"],
+    accessToken: sha256Hex(credential),
+    expiresAt: overrides.expiresAt ?? new Date(Date.now() + 60 * 60 * 1000),
+    revokedAt: overrides.revokedAt ?? null,
+  });
+  return credential;
+}
+
+const headers = (credential: string, s: SeededSpoke = spokeA) => ({
+  authorization: `Bearer ${credential}`,
+  "x-ailk-spoke-key": s.key,
+});
+
+function buildApp(): FastifyInstance {
+  const server = Fastify();
+  server.register(authPreHandlerPlugin, { trustedOrigins: [FRONTEND] });
+
+  const echo =
+    (name: string) => async (req: import("fastify").FastifyRequest) => {
+      handlerRuns.push(name);
+      return {
+        userId: req.userId ?? null,
+        hubSession: req.hubSession ?? null,
+        sessionTenant: req.sessionTenant ?? null,
+        actor: req.actor ?? null,
+      };
+    };
+
+  // The four admitted routes (the member reads are stubs).
+  server.get("/v1/hub-sign-in/me", echo("me"));
+  server.get("/v1/member/pieces", echo("pieces"));
+  server.get("/v1/member/messages", echo("messages"));
+  server.get("/v1/member/messages/:id/file", echo("file"));
+
+  // Everything else the credential must NOT reach.
+  server.get("/v1/member/other", echo("other"));
+  server.get("/v1/member/messages/:id", echo("message-item"));
+  server.get("/v1/waitlist-signups/me", echo("waitlist-signups"));
+  server.get("/v1/flow-checkouts/me", echo("flow-checkouts"));
+  server.get("/v1/subscription/me", echo("subscription"));
+  server.post("/v1/subscription/portal-session", echo("portal"));
+  server.get("/v1/auth/tokens", echo("tokens"));
+  server.patch("/v1/user/profile", echo("profile"));
+  server.post("/v1/hub-sign-in/codes", echo("codes"));
+  return server;
+}
+
+beforeEach(async () => {
+  jest.resetAllMocks();
+  state = installHubSignInFakeDb(db);
+  handlerRuns = [];
+  user = seedUser(state);
+  spokeA = seedSpoke(state, "a.example.com");
+  spokeB = seedSpoke(state, "b.example.com");
+  app = buildApp();
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+});
+
+describe("HUB_SESSION_ROUTES", () => {
+  it("is exactly the four reads, by method and registered URL — never a prefix", () => {
+    expect([...HUB_SESSION_ROUTES]).toEqual([
+      "GET /v1/hub-sign-in/me",
+      "GET /v1/member/pieces",
+      "GET /v1/member/messages",
+      "GET /v1/member/messages/:id/file",
+    ]);
+  });
+});
+
+describe("hub credential — admitted routes", () => {
+  it.each([
+    ["GET", "/v1/hub-sign-in/me", "me"],
+    ["GET", "/v1/member/pieces", "pieces"],
+    ["GET", "/v1/member/messages", "messages"],
+    ["GET", "/v1/member/messages/lead_1/file", "file"],
+  ])(
+    "%s %s is admitted as the credential's person, bound to the spoke",
+    async (method, url, name) => {
+      const credential = grant(spokeA);
+
+      const res = await app.inject({
+        method: method as "GET",
+        url,
+        headers: headers(credential),
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(handlerRuns).toEqual([name]);
+      const body = res.json();
+      expect(body.userId).toBe(user.id);
+      expect(body.hubSession).toEqual({
+        spokeId: spokeA.spoke.id,
+        workspaceId: spokeA.spoke.workspaceId,
+      });
+      // Acts as its person; never carries a cookie session's tenant.
+      expect(body.actor).toEqual({ type: "user", userId: user.id });
+      expect(body.sessionTenant).toBeNull();
+    },
+  );
+});
+
+describe("hub credential — every other route is 404 with no handler run (AC-7)", () => {
+  it.each([
+    ["GET", "/v1/member/other"],
+    ["GET", "/v1/member/messages/lead_1"],
+    ["GET", "/v1/waitlist-signups/me"],
+    ["GET", "/v1/flow-checkouts/me"],
+    ["GET", "/v1/subscription/me"],
+    ["POST", "/v1/subscription/portal-session"],
+    ["GET", "/v1/auth/tokens"],
+    ["PATCH", "/v1/user/profile"],
+    ["POST", "/v1/hub-sign-in/codes"],
+  ])("%s %s", async (method, url) => {
+    const credential = grant(spokeA);
+
+    const res = await app.inject({
+      method: method as "GET",
+      url,
+      headers: headers(credential),
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "not_found", message: "Not found" },
+    });
+    expect(handlerRuns).toEqual([]);
+  });
+
+  it("the list is method-exact: HEAD on an admitted URL is not admitted", async () => {
+    const credential = grant(spokeA);
+    const res = await app.inject({
+      method: "HEAD",
+      url: "/v1/hub-sign-in/me",
+      headers: headers(credential),
+    });
+    expect(res.statusCode).toBe(404);
+    expect(handlerRuns).toEqual([]);
+  });
+});
+
+describe("hub credential — refused with 401 before any route check", () => {
+  const me = (h: Record<string, string>) =>
+    app.inject({ method: "GET", url: "/v1/hub-sign-in/me", headers: h });
+
+  it("AC-4: spoke A's credential sent with spoke B's key", async () => {
+    const credential = grant(spokeA);
+    expect((await me(headers(credential, spokeB))).statusCode).toBe(401);
+    expect(handlerRuns).toEqual([]);
+  });
+
+  it("the credential with no spoke key at all", async () => {
+    const credential = grant(spokeA);
+    expect(
+      (await me({ authorization: `Bearer ${credential}` })).statusCode,
+    ).toBe(401);
+  });
+
+  it("an unknown spoke key, and a revoked spoke", async () => {
+    const credential = grant(spokeA);
+    expect(
+      (
+        await me({
+          authorization: `Bearer ${credential}`,
+          "x-ailk-spoke-key": "ailk_spk_nope",
+        })
+      ).statusCode,
+    ).toBe(401);
+    spokeA.spoke.revokedAt = new Date();
+    expect((await me(headers(credential))).statusCode).toBe(401);
+  });
+
+  it("an unknown credential", async () => {
+    expect((await me(headers(mintCredential()))).statusCode).toBe(401);
+  });
+
+  it("a revoked credential", async () => {
+    const credential = grant(spokeA, { revokedAt: new Date() });
+    expect((await me(headers(credential))).statusCode).toBe(401);
+  });
+
+  it("an expired credential", async () => {
+    const credential = grant(spokeA, {
+      expiresAt: new Date(Date.now() - 1_000),
+    });
+    expect((await me(headers(credential))).statusCode).toBe(401);
+  });
+
+  it("a credential whose client was disabled", async () => {
+    const credential = grant(spokeA);
+    spokeA.client.enabled = false;
+    expect((await me(headers(credential))).statusCode).toBe(401);
+  });
+
+  it("AC-5: a credential whose person's email is no longer verified", async () => {
+    const credential = grant(spokeA);
+    user.emailVerified = false;
+    expect((await me(headers(credential))).statusCode).toBe(401);
+    expect(handlerRuns).toEqual([]);
+  });
+
+  it("answers the preHandler's existing 401 body", async () => {
+    const res = await me(headers(mintCredential()));
+    expect(res.json()).toEqual({ error: "unauthorized" });
+  });
+});
+
+describe("hub credential — it is a bearer and nothing else", () => {
+  it("AC-5: sent as the better-auth session cookie it is 401 (no Session row matches)", async () => {
+    const credential = grant(spokeA);
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/hub-sign-in/me",
+      headers: {
+        cookie: `better-auth.session_token=${credential}`,
+        "x-ailk-spoke-key": spokeA.key,
+      },
+    });
+    expect(res.statusCode).toBe(401);
+    expect(handlerRuns).toEqual([]);
+  });
+
+  it("is not looked up as a personal ApiToken, and takes no part in the agent branch", async () => {
+    const credential = grant(spokeA);
+    await app.inject({
+      method: "GET",
+      url: "/v1/hub-sign-in/me",
+      headers: headers(credential),
+    });
+    expect(db.apiToken.findUnique).not.toHaveBeenCalled();
+    expect(db.agent.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("is never logged: a rejected request leaves the credential out of the body", async () => {
+    const credential = grant(spokeA, { revokedAt: new Date() });
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/hub-sign-in/me",
+      headers: headers(credential),
+    });
+    expect(res.body).not.toContain(credential);
+  });
+});

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

@@ -530,6 +530,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       workspaceId: string;
       organizationId: string;
       responsibleMembershipId: string;
+      grants: string[];
     }> = {},
   ) {
     return {
@@ -539,6 +540,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       responsibleMembershipId: (overrides.responsibleMembershipId ??
         OPERATOR_MEMBERSHIP_ID) as Id<"membership">,
       permissionLevel: "member" as const,
+      grants: overrides.grants ?? [],
     };
   }
 
@@ -582,6 +584,26 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
     await app.close();
   });
 
+  it("a granted agent of the owner-operator carries its grants on the tenant; a forged one is dropped (#7864 D3)", async () => {
+    mockSingleTenantWorkspace();
+    mockOperatorMembership();
+    const app = buildAgentApp(
+      agentBinding({ grants: ["magnets-manage", "agents-manage", "content-edit"] }),
+    );
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().tenant).toEqual({
+      userId: USER_ID,
+      organizationId: DEFAULT_ORG_ID,
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      role: "member",
+      grants: ["content-edit", "magnets-manage"],
+    });
+    await app.close();
+  });
+
   it("reaches the grant through the operator's own reads: the same membership compound key", async () => {
     mockSingleTenantWorkspace();
     mockOperatorMembership();

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

@@ -28,6 +28,16 @@
  *      limited to 60 requests a minute, at most 10 of them writes (any
  *      method but GET and HEAD).
  *
+ *   4. Hub-credential path (#7894) — a bearer starting `ailk_hst_` is a
+ *      credential a spoke holds for a person the hub signed in on its behalf
+ *      (`lib/hub-sign-in-store.ts`). It is admitted only beside the SAME
+ *      spoke's key (`x-ailk-spoke-key`), only while its grant is unrevoked and
+ *      unexpired, its client enabled and its person's email verified, and only
+ *      on `HUB_SESSION_ROUTES` — an exact list of four reads; any other route
+ *      is 404 (never 403, so the account area's `read()` loads "nothing for
+ *      this caller"). It acts as its person (`request.userId`) and carries
+ *      `request.hubSession` — never `request.sessionTenant`.
+ *
  * 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.
@@ -61,7 +71,12 @@ import {
   touchAgentLastActive,
   type AgentGrant,
 } from "../lib/agent-store.js";
+import {
+  findAuthorizationByCredentialHash,
+  HUB_SESSION_PREFIX,
+} from "../lib/hub-sign-in-store.js";
 import { prisma } from "../lib/prisma.js";
+import { findSpokeByKeyHash, hashSpokeKey } from "../lib/spoke-store.js";
 
 /**
  * Better Auth's default cookie names. Both are tried in order so a deployment
@@ -74,6 +89,11 @@ const COOKIE_NAMES = [
 
 const UNAUTHORIZED = { error: "unauthorized" } as const;
 const DATABASE_NOT_CONFIGURED = { error: "database_not_configured" } as const;
+const NOT_FOUND = {
+  ok: false,
+  error: { code: "not_found", message: "Not found" },
+} as const;
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
 const FORBIDDEN = {
   ok: false,
   error: { code: "forbidden", message: "Forbidden" },
@@ -98,6 +118,11 @@ declare module "fastify" {
     agent?: AgentGrant;
     /** Who made the request — set on every authenticated request (#3591 D9). */
     actor?: RequestActor;
+    /**
+     * Set ONLY on the hub-credential path (#7894 D6): the spoke the credential
+     * and the request's spoke key both name, and that spoke's workspace.
+     */
+    hubSession?: HubSession;
   }
   interface FastifyContextConfig {
     /**
@@ -109,6 +134,29 @@ declare module "fastify" {
   }
 }
 
+/** The spoke a hub-issued credential was admitted for (#7894 D6). */
+export type HubSession = {
+  spokeId: Id<"spoke">;
+  workspaceId: Id<"workspace">;
+};
+
+/**
+ * The only routes a hub-issued credential reaches (#7894 D6): an EXACT list of
+ * method + registered URL, never a prefix, so a route added later joins only
+ * by a reviewed edit of this list (SEC-7894-3). The first is the credential's
+ * own `me`; the other three are #7877's member reads. Not admitted,
+ * deliberately: `GET /v1/waitlist-signups/me`, `GET /v1/flow-checkouts/me`,
+ * `GET /v1/subscription/me` and `POST /v1/subscription/portal-session` (they
+ * answer for the HUB's site and the person's platform billing, SEC-7894-1,
+ * -2), and the token and profile routes.
+ */
+export const HUB_SESSION_ROUTES: readonly string[] = [
+  "GET /v1/hub-sign-in/me",
+  "GET /v1/member/pieces",
+  "GET /v1/member/messages",
+  "GET /v1/member/messages/:id/file",
+];
+
 /**
  * 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.
@@ -354,6 +402,9 @@ async function authenticateAgent(
     organizationId: row.organizationId as Id<"organization">,
     responsibleMembershipId: row.responsible.id as Id<"membership">,
     permissionLevel: row.permissionLevel,
+    // #7864 D3 — the one place a missing value becomes none; the tenant
+    // guards keep only the grants its person's role also holds.
+    grants: row.grants ?? [],
   };
   bindActor(request, reply, {
     type: "agent",
@@ -386,6 +437,61 @@ async function authenticateAgent(
   }
 }
 
+/**
+ * The hub-credential path (#7894 D6). The credential is never logged and
+ * never echoed: every refusal is a fixed body. (1)-(3) failing is the one 401;
+ * (4), the route not being on `HUB_SESSION_ROUTES`, is 404 with no handler run.
+ */
+async function authenticateHubSession(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  credential: string,
+  now: number,
+): Promise<void> {
+  // (1) The spoke key resolves to an unrevoked spoke.
+  const rawKey = request.headers[SPOKE_KEY_HEADER];
+  const spokeKey = typeof rawKey === "string" ? rawKey.trim() : "";
+  const spoke = spokeKey
+    ? await findSpokeByKeyHash(hashSpokeKey(spokeKey)).catch(() => null)
+    : null;
+  if (!spoke || spoke.revokedAt) {
+    reply.code(401).send(UNAUTHORIZED);
+    return;
+  }
+
+  // (2) The credential's grant is live, and its client IS this spoke's.
+  // (3) Its person's email is verified (read in the same query).
+  const grant = await findAuthorizationByCredentialHash(
+    hashBearer(credential),
+  ).catch(() => null);
+  if (
+    !grant ||
+    grant.revokedAt ||
+    grant.expiresAt.getTime() <= now ||
+    !grant.client.enabled ||
+    grant.client.clientId !== spoke.id ||
+    grant.user.emailVerified !== true
+  ) {
+    reply.code(401).send(UNAUTHORIZED);
+    return;
+  }
+
+  // (4) Method and registered URL are on the list.
+  const route = `${request.method.toUpperCase()} ${request.routeOptions.url ?? ""}`;
+  if (!HUB_SESSION_ROUTES.includes(route)) {
+    reply.code(404).send(NOT_FOUND);
+    return;
+  }
+
+  // Brand assertion at the Prisma read edge (ADR-0031 rule 5), as above.
+  request.userId = grant.userId as Id<"user">;
+  request.hubSession = {
+    spokeId: spoke.id as Id<"spoke">,
+    workspaceId: spoke.workspaceId as Id<"workspace">,
+  };
+  bindActor(request, reply, { type: "user", userId: request.userId });
+}
+
 export type AuthPreHandlerOptions = {
   /**
    * The browser origins a cookie-authenticated write may come from — exact
@@ -448,6 +554,24 @@ export async function resolveOptionalCookieUser(
   return { kind: "user", userId: session.userId as Id<"user"> };
 }
 
+/**
+ * The person a member read answers for (#7877 D5): the hub's own cookie
+ * session or a hub-issued credential (#7894 D6) — never a personal ApiToken,
+ * never an agent. `null` → the route answers 401 with `UNAUTHORIZED`.
+ *
+ * This is the ONE place the member reads (`services/member-area.ts`) learn
+ * who is calling: a later credential kind joins them by an edit of this
+ * function and nothing in `routes/member/`. An agent never gets here — the
+ * member routes are not tenant-guarded, so this preHandler answers it 403.
+ */
+export function memberCaller(request: FastifyRequest): Id<"user"> | null {
+  if (request.userId === undefined) return null;
+  if (request.sessionTenant !== undefined || request.hubSession !== undefined) {
+    return request.userId;
+  }
+  return null;
+}
+
 /**
  * Fastify preHandler implementing the dual-mode contract.
  *
@@ -497,6 +621,10 @@ export function makeAuthPreHandler(opts: AuthPreHandlerOptions) {
     }
 
     const bearer = readBearer(request);
+    if (bearer?.startsWith(HUB_SESSION_PREFIX)) {
+      await authenticateHubSession(request, reply, bearer, now);
+      return;
+    }
     if (bearer?.startsWith(AGENT_KEY_PREFIX)) {
       await authenticateAgent(request, reply, bearer, now);
       return;
@@ -547,6 +675,7 @@ export const authPreHandlerPlugin: FastifyPluginCallback<
   fastify.decorateRequest("sessionTenant", undefined);
   fastify.decorateRequest("agent", undefined);
   fastify.decorateRequest("actor", undefined);
+  fastify.decorateRequest("hubSession", undefined);
   fastify.addHook("preHandler", handler);
   done();
 };

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -222,6 +222,29 @@ describe("GET /api/openapi.json", () => {
       },
     );
 
+    it("documents /v1/leads/submit's optional Idempotency-Key header and its 422 (#7869)", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      const post = spec.paths["/v1/leads/submit"].post;
+      expect(post.parameters).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "Idempotency-Key",
+            in: "header",
+            required: false,
+          }),
+        ]),
+      );
+      expect(
+        post.responses["422"].content["application/json"].schema.properties.error
+          .enum,
+      ).toEqual(["idempotency_key_reused"]);
+    });
+
     it("no longer describes the API as read-only", async () => {
       const res = await app.inject({
         method: "GET",

package/templates/apps/api/src/openapi/spec.ts

@@ -751,7 +751,25 @@ export function buildOpenApiSpec(
             "only), or, on a deployment with no database, the site operator's inbox " +
             "by email (`persisted: \"email\"`); with a database, the response's " +
             "`email` field reports, best-effort, whether the operator was notified. " +
-            "A lead is never reported captured when nothing stored or delivered it.",
+            "A lead is never reported captured when nothing stored or delivered it. " +
+            "An optional `Idempotency-Key` header makes a retry safe: with a " +
+            "database, a repeat of a stored key in the same workspace with the same " +
+            "`email`, `source` and `payload` writes nothing and answers the first " +
+            "lead's id with a 201; with anything different it is a 422. Keys are " +
+            "scoped per workspace, are first-write-wins, and should be unguessable " +
+            "(a UUID, a Stripe Checkout Session id). Without a database there is no " +
+            "stored lead to match, so the key has no effect.",
+          parameters: [
+            {
+              name: "Idempotency-Key",
+              in: "header",
+              required: false,
+              description:
+                "An unguessable value identifying this lead write, so a retry " +
+                "answers the first lead instead of writing a second (#7869).",
+              schema: { type: "string", pattern: "^[\\x21-\\x7E]{16,255}$" },
+            },
+          ],
           requestBody: {
             required: true,
             content: {
@@ -770,13 +788,31 @@ export function buildOpenApiSpec(
               },
             },
             "400": {
-              description: "Validation error — invalid request body",
+              description:
+                "Validation error — invalid request body, or a malformed Idempotency-Key",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/InvalidInputResponse" },
                 },
               },
             },
+            "422": {
+              description:
+                "The Idempotency-Key was already used in this workspace for a lead " +
+                "with a different email, source or payload; nothing was written",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["error", "message"],
+                    properties: {
+                      error: { type: "string", enum: ["idempotency_key_reused"] },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
             "503": {
               description:
                 "Lead capture unavailable — persistence failed, delivery failed, or " +