create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/routes/consent/account.ts

@@ -1,268 +0,0 @@
-/**
- * The sign-up agreements: their evidence, and the account-level reading
- * (#8765, spec docs/specs/8765-sign-up-refuses-without-the-spec.md D2, D5).
- *
- *   GET  /v1/consent/sign-up?locale=
- *       Anonymous. `{ workspaceId, agreements: [{ purposeId,
- *       policyVersion, locale, statement, statementHash }] }` — one entry per
- *       `signUp` agreement of the site registry, its statement resolved by
- *       `resolveConsentStatement` for `locale` (default `en`) and hashed by
- *       `consentStatementHash`: the same evidence `recordPersonConsent`
- *       stamps, from the same functions. `Cache-Control: no-store`.
- *   GET  /v1/consent/account?locale=
- *       The caller's sign-up agreements: `{ agreements: [{ id, statement,
- *       policyVersion, acceptedVersion, acceptedAt, current }], complete }`,
- *       folded from the caller's `user`-subject rows (`userPlatformRows`).
- *       `acceptedVersion`/`acceptedAt` come from the newest row when it is a
- *       grant, else `null`; `current` is a grant at the registry's version;
- *       `complete` is every entry current.
- *   POST /v1/consent/account
- *       `{ purposeIds, locale? }` — every id must be a `signUp` agreement
- *       (`404 purpose_unknown` with NOTHING written, all ids checked before
- *       any write); each is written through `recordPersonConsent` against
- *       subject `user` / the caller, no Person, source `account_settings`,
- *       with `sourceRef: spoke:<id>` for a hub credential (SEC-8765-A). A
- *       grant already at the current version adds nothing. Answers the GET
- *       body.
- *
- * The agreement belongs to the User account, a login shared by every site
- * that signs in through this hub (C3), so the workspace is ALWAYS
- * `resolveSiteWorkspaceId()` — the deployment's own site, where its `User`
- * rows live — never a key, body or query value; `null` is
- * `503 tenant_unresolved`. One row there answers the hub and every spoke.
- *
- * Callers. The evidence route: the web's own server, stamping the grant it
- * writes inside Better Auth's sign-up transaction (`apps/web/lib/
- * sign-up-agreements.ts`, D3, D4). Registered at the top level in its own
- * rate-limited scope (`signupevidence`), outside every module gate; a call
- * presenting a valid site key is counted per key there, any other per IP
- * (#8805, `server.ts`) — the key never chooses the workspace. The
- * account pair: `memberCaller` — the hub's own cookie session or a hub
- * credential (the account layout's interstitial, D7); a personal `ApiToken`
- * is `401 unauthorized`. There is no verified-email floor: the agreement is
- * about the `User` row, and no Person is read or created. Registered in
- * `authScope` unconditionally (auth and consent are never-gate surfaces),
- * and both are in `HUB_SESSION_ROUTES`. Logs `{ event: "account-agreements",
- * outcome }` only.
- *
- * MCP parity note: no MCP twin — the evidence route is part of the sign-up
- * flow and the account pair is identity-bound; the anonymous MCP surface is
- * identity-blind (tests/parity/README.md).
- */
-import {
-  accountAgreementsBodySchema,
-  accountAgreementsQuerySchema,
-  accountAgreementsResponseSchema,
-  consentSignUpQuerySchema,
-  consentSignUpResponseSchema,
-  resolveConsentStatement,
-  signUpAgreements,
-  type AccountAgreementsResponse,
-  type SiteConsentConfig,
-} from "@working-theory/validation";
-import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
-import type { z } from "zod";
-
-import { userPlatformRows } from "../../lib/consent-store.js";
-import { resolveSiteWorkspaceId } from "../../lib/site.js";
-import { memberCaller } from "../../middleware/auth.js";
-import {
-  consentConfigForSite,
-  consentStatementHash,
-  recordPersonConsent,
-} from "../../services/consent.js";
-
-const EVENT = "account-agreements";
-
-function refuse(
-  reply: FastifyReply,
-  status: number,
-  code: string,
-  message: string,
-) {
-  return reply.status(status).send({ ok: false, error: { code, message } });
-}
-
-function send<T extends z.ZodTypeAny>(
-  reply: FastifyReply,
-  schema: T,
-  data: unknown,
-) {
-  const parsed = schema.safeParse(data);
-  if (!parsed.success) {
-    return refuse(
-      reply,
-      500,
-      "internal_error",
-      "Response failed contract validation",
-    );
-  }
-  return reply.send({ ok: true, data: parsed.data });
-}
-
-function log(request: FastifyRequest, outcome: string): void {
-  if (outcome === "saved" || outcome === "unchanged") {
-    request.log.info({ event: EVENT, outcome }, "[consent] account agreements");
-  } else {
-    request.log.warn({ event: EVENT, outcome }, "[consent] refused");
-  }
-}
-
-function refuseUnresolved(request: FastifyRequest, reply: FastifyReply) {
-  log(request, "tenant_unresolved");
-  return refuse(
-    reply,
-    503,
-    "tenant_unresolved",
-    "This site cannot take this request.",
-  );
-}
-
-/** The caller's sign-up agreements in the site workspace (D5). */
-async function accountReading(
-  workspaceId: string,
-  userId: string,
-  config: SiteConsentConfig,
-  locale: string,
-): Promise<AccountAgreementsResponse> {
-  const rows = await userPlatformRows(workspaceId, userId);
-  const newest = new Map(rows.map((row) => [row.purposeId, row]));
-  const agreements = signUpAgreements(config).map((purpose) => {
-    const row = newest.get(purpose.id);
-    const grant = row?.granted === true ? row : null;
-    return {
-      id: purpose.id,
-      statement: resolveConsentStatement(purpose, locale).statement,
-      policyVersion: purpose.policyVersion,
-      acceptedVersion: grant?.policyVersion ?? null,
-      acceptedAt: grant === null ? null : grant.at.toISOString(),
-      current: grant !== null && grant.policyVersion === purpose.policyVersion,
-    };
-  });
-  return { agreements, complete: agreements.every((a) => a.current) };
-}
-
-/** `GET /v1/consent/sign-up` — top level, its own rate-limited scope (D2). */
-export const consentSignUpRoute: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/consent/sign-up", async (request, reply) => {
-    reply.header("Cache-Control", "no-store");
-    const query = consentSignUpQuerySchema.safeParse(request.query);
-    if (!query.success) {
-      return refuse(reply, 400, "invalid_input", "The request was not valid.");
-    }
-    const locale = query.data.locale ?? "en";
-
-    const workspaceId = await resolveSiteWorkspaceId();
-    if (workspaceId === null) return refuseUnresolved(request, reply);
-
-    const config = await consentConfigForSite(workspaceId);
-    const agreements = signUpAgreements(config).map((purpose) => {
-      const resolved = resolveConsentStatement(purpose, locale);
-      return {
-        purposeId: purpose.id,
-        policyVersion: purpose.policyVersion,
-        locale: resolved.locale,
-        statement: resolved.statement,
-        statementHash: consentStatementHash(resolved.statement),
-      };
-    });
-    return send(reply, consentSignUpResponseSchema, {
-      workspaceId,
-      agreements,
-    });
-  });
-};
-
-/** `GET`/`POST /v1/consent/account` — in `authScope`, unconditionally (D5). */
-export const consentAccountRoutes: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/consent/account", async (request, reply) => {
-    const userId = memberCaller(request);
-    if (userId === null) {
-      log(request, "unauthorized");
-      return reply.status(401).send({ error: "unauthorized" });
-    }
-    const query = accountAgreementsQuerySchema.safeParse(request.query);
-    if (!query.success) {
-      log(request, "invalid_input");
-      return refuse(reply, 400, "invalid_input", "The request was not valid.");
-    }
-    const workspaceId = await resolveSiteWorkspaceId();
-    if (workspaceId === null) return refuseUnresolved(request, reply);
-
-    const config = await consentConfigForSite(workspaceId);
-    return send(
-      reply,
-      accountAgreementsResponseSchema,
-      await accountReading(
-        workspaceId,
-        userId,
-        config,
-        query.data.locale ?? "en",
-      ),
-    );
-  });
-
-  fastify.post("/v1/consent/account", async (request, reply) => {
-    const userId = memberCaller(request);
-    if (userId === null) {
-      log(request, "unauthorized");
-      return reply.status(401).send({ error: "unauthorized" });
-    }
-    const body = accountAgreementsBodySchema.safeParse(request.body);
-    if (!body.success) {
-      log(request, "invalid_input");
-      return refuse(reply, 400, "invalid_input", "The request was not valid.");
-    }
-    const locale = body.data.locale ?? "en";
-    const workspaceId = await resolveSiteWorkspaceId();
-    if (workspaceId === null) return refuseUnresolved(request, reply);
-
-    const config = await consentConfigForSite(workspaceId);
-    // Every id is checked before any write, so a refusal writes nothing.
-    const agreementIds = new Set(signUpAgreements(config).map((p) => p.id));
-    const purposeIds = [...new Set(body.data.purposeIds)];
-    if (!purposeIds.every((id) => agreementIds.has(id))) {
-      log(request, "purpose_unknown");
-      return refuse(
-        reply,
-        404,
-        "purpose_unknown",
-        "That agreement can't be accepted here.",
-      );
-    }
-
-    let changed = false;
-    for (const purposeId of purposeIds) {
-      const result = await recordPersonConsent({
-        workspaceId,
-        personId: null,
-        purposeId,
-        granted: true,
-        source: "account_settings",
-        ...(request.hubSession !== undefined && {
-          sourceRef: `spoke:${request.hubSession.spokeId}`,
-        }),
-        locale,
-        config,
-        subject: { subjectType: "user", subjectId: userId },
-      });
-      if (!result.ok) {
-        log(request, result.code);
-        return refuse(
-          reply,
-          result.code === "purpose_unknown" ? 404 : 400,
-          result.code,
-          "That agreement can't be accepted here.",
-        );
-      }
-      changed ||= result.changed;
-    }
-
-    log(request, changed ? "saved" : "unchanged");
-    return send(
-      reply,
-      accountAgreementsResponseSchema,
-      await accountReading(workspaceId, userId, config, locale),
-    );
-  });
-};

package/templates/apps/api/src/routes/consent/cookie.ts

@@ -1,90 +0,0 @@
-/**
- * The cookie banner's log (#8438, spec
- * docs/specs/8438-consent-registry-and-ledger-step-spec.md D5).
- *
- *   POST /v1/consent/cookie
- *       `{ visitorId, choice: "accepted" | "declined", locale }` — one row
- *       in the consent ledger against the visitor id, source
- *       `cookie_banner`. Answers `201 { recorded: true }`, or
- *       `200 { recorded: false }` when the site declares no cookie purpose
- *       or the visitor's newest row already records the same choice.
- *
- * The workspace comes from `resolvePublicWorkspace(request)` — the spoke
- * key, else the one-workspace deployment — and NEVER from the body, which is
- * strict and names no site, workspace, person or user. An unresolved
- * workspace is `503 tenant_unresolved`; no database `503
- * consent_store_unavailable`; a failed write the same.
- *
- * Registered at the top level in its own rate-limited scope, outside every
- * module gate: consent logging is part of the never-gated privacy floor.
- * The browser cookie `ailk-consent` stays the operative switch (C3) — this
- * route only records the choice.
- *
- * Logs carry `{ event, outcome }` only: never a visitor id or a statement.
- *
- * MCP parity note: no MCP twin, a recorded exception — it logs a browser's
- * banner choice against a browser-held id, and an agent holds neither
- * (tests/parity/README.md).
- */
-import { consentCookieBodySchema } from "@working-theory/validation";
-import type { FastifyPluginAsync } from "fastify";
-
-import { recordCookieChoice } from "../../services/consent.js";
-import { resolvePublicWorkspace } from "../../services/public-site-resolver.js";
-
-const EVENT = "consent-cookie";
-
-export const consentCookieRoute: FastifyPluginAsync = async (fastify) => {
-  fastify.post("/v1/consent/cookie", async (request, reply) => {
-    const body = consentCookieBodySchema.safeParse(request.body);
-    if (!body.success) {
-      return reply.status(400).send({
-        error: "invalid_input",
-        message: "The request was not valid.",
-      });
-    }
-    if (!process.env["DATABASE_URL"]) {
-      return reply.status(503).send({
-        error: "consent_store_unavailable",
-        message: "Consent cannot be recorded on this site.",
-      });
-    }
-
-    const site = await resolvePublicWorkspace(request);
-    if (site.kind !== "resolved") {
-      request.log.warn(
-        { event: EVENT, outcome: "tenant_unresolved" },
-        "[consent] refused",
-      );
-      return reply.status(503).send({
-        error: "tenant_unresolved",
-        message: "This site is not configured to record consent.",
-      });
-    }
-
-    try {
-      const result = await recordCookieChoice({
-        workspaceId: site.workspaceId,
-        visitorId: body.data.visitorId,
-        choice: body.data.choice,
-        locale: body.data.locale,
-      });
-      request.log.info(
-        { event: EVENT, outcome: result.recorded ? "recorded" : "unchanged" },
-        "[consent] cookie choice",
-      );
-      return reply
-        .status(result.recorded ? 201 : 200)
-        .send({ recorded: result.recorded });
-    } catch {
-      request.log.error(
-        { event: EVENT, outcome: "failed" },
-        "[consent] cookie choice failed",
-      );
-      return reply.status(503).send({
-        error: "consent_store_unavailable",
-        message: "Consent cannot be recorded right now.",
-      });
-    }
-  });
-};

package/templates/apps/api/src/routes/consent/index.ts

@@ -1,26 +0,0 @@
-/**
- * The consent routes (#8438, spec
- * docs/specs/8438-consent-registry-and-ledger-step-spec.md D5, D8, D9; #8765,
- * spec docs/specs/8765-sign-up-refuses-without-the-spec.md D2, D5).
- *
- *   cookie.ts       POST /v1/consent/cookie       — the banner's log
- *   unsubscribe.ts  POST /v1/consent/unsubscribe  — a signed link's landing
- *   account.ts      GET  /v1/consent/sign-up      — the sign-up agreements'
- *                   evidence (anonymous)
- *                   GET/POST /v1/consent/account  — the caller's account-level
- *                   sign-up agreements (cookie session or hub credential)
- *   platform.ts     GET/POST /v1/consent/platform — the Admin owner's
- *                   consents to Working Theory (multi-tenant module only)
- *
- * The first two and the evidence route are the never-gated floor: registered
- * at the top level, each in its OWN rate-limited scope (`consent`,
- * `unsubscribe`, `signupevidence`) so filling one never blocks another; the
- * first two are also on the forwarded-visitor route list
- * (`middleware/rate-limit.ts`). The account pair registers in `authScope`,
- * unconditionally. This barrel re-exports those four plugins; the platform
- * routes belong to the multi-tenant slice and are loaded only through
- * `server.ts`'s slice table.
- */
-export { consentAccountRoutes, consentSignUpRoute } from "./account.js";
-export { consentCookieRoute } from "./cookie.js";
-export { consentUnsubscribeRoute } from "./unsubscribe.js";

package/templates/apps/api/src/routes/consent/unsubscribe.ts

@@ -1,127 +0,0 @@
-/**
- * The one unsubscribe landing every email link will call (#8438, spec
- * docs/specs/8438-consent-registry-and-ledger-step-spec.md D9, SEC-8438-9).
- *
- *   POST /v1/consent/unsubscribe
- *       `{ token }` — a signed token minted by `consentUnsubscribeToken`.
- *       Withdraws the communications purpose it names for the Person it
- *       names, source `email_unsubscribe`, unless the Person's own and
- *       any-source readings both already say "not granted". Answers `200 { purpose: { id, description },
- *       changed }`; a second click is `changed: false` with nothing written.
- *
- * The token is the only authority: it names no email, and a forged one fails
- * its HMAC. Any defect — a flipped character, another workspace's Person, a
- * purpose that is not a communications consent or preference, a token older
- * than 400 days, a malformed body — is ONE uniform `400 invalid_link`. With
- * `AILK_CONSENT_LINK_SECRET` unset or under 32 bytes the route answers `503
- * link_secret_not_configured` (the 503/400 split tells an outsider only
- * whether the feature is configured, which the absence of links in mail
- * already shows — accepted in SEC-8438-9).
- *
- * Registered at the top level in its own rate-limited scope (`unsubscribe`),
- * outside every module gate, beside the cookie route. The page that calls it
- * (apps/web `/unsubscribe`) performs no write on GET, so a mail scanner's
- * prefetch changes nothing.
- *
- * Logs carry `{ event, outcome }` only: never a token, an id or a statement.
- *
- * MCP parity note: no MCP twin — the route is a capability link's own
- * landing, the `/v1/deliverables/:grantId` footing (tests/parity/README.md).
- */
-import {
-  consentPurposeById,
-  consentPurposeKind,
-  consentUnsubscribeBodySchema,
-  resolveLocalizedString,
-} from "@working-theory/validation";
-import type { FastifyPluginAsync } from "fastify";
-
-import {
-  consentConfigForSite,
-  consentLinkSecretConfigured,
-  consentPersonExists,
-  recordPersonConsent,
-  verifyConsentUnsubscribeToken,
-} from "../../services/consent.js";
-
-const EVENT = "consent-unsubscribe";
-
-const INVALID_LINK = {
-  error: "invalid_link",
-  message: "This link isn't valid.",
-} as const;
-
-export const consentUnsubscribeRoute: FastifyPluginAsync = async (fastify) => {
-  fastify.post("/v1/consent/unsubscribe", async (request, reply) => {
-    if (!consentLinkSecretConfigured()) {
-      request.log.warn(
-        { event: EVENT, outcome: "secret_missing" },
-        "[consent] refused",
-      );
-      return reply.status(503).send({
-        error: "link_secret_not_configured",
-        message: "Unsubscribing isn't available on this site.",
-      });
-    }
-    const refuse = (outcome: string) => {
-      request.log.warn({ event: EVENT, outcome }, "[consent] refused");
-      return reply.status(400).send(INVALID_LINK);
-    };
-
-    const body = consentUnsubscribeBodySchema.safeParse(request.body);
-    if (!body.success) return refuse("invalid_body");
-    const claims = verifyConsentUnsubscribeToken(body.data.token);
-    if (claims === null) return refuse("invalid_token");
-
-    try {
-      const config = await consentConfigForSite(claims.workspaceId);
-      const purpose = consentPurposeById(config, claims.purposeId);
-      if (
-        !purpose ||
-        purpose.area !== "communications" ||
-        consentPurposeKind(purpose) === "agreement"
-      ) {
-        return refuse("purpose_not_unsubscribable");
-      }
-      if (!(await consentPersonExists(claims.workspaceId, claims.personId))) {
-        return refuse("person_unknown");
-      }
-
-      const result = await recordPersonConsent({
-        workspaceId: claims.workspaceId,
-        personId: claims.personId,
-        purposeId: purpose.id,
-        granted: false,
-        source: "email_unsubscribe",
-        locale: "en",
-        config,
-        subject: { subjectType: "person", subjectId: claims.personId },
-      });
-      if (!result.ok) return refuse(result.code);
-
-      request.log.info(
-        { event: EVENT, outcome: result.changed ? "withdrawn" : "unchanged" },
-        "[consent] unsubscribe",
-      );
-      return reply.send({
-        purpose: {
-          id: purpose.id,
-          description:
-            purpose.description === undefined
-              ? purpose.id
-              : resolveLocalizedString(purpose.description, "en", "en"),
-        },
-        changed: result.changed,
-      });
-    } catch {
-      request.log.error(
-        { event: EVENT, outcome: "failed" },
-        "[consent] unsubscribe failed",
-      );
-      return reply.status(503).send({
-        error: "consent_store_unavailable",
-        message: "Unsubscribing isn't available right now.",
-      });
-    }
-  });
-};