create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/lib/deliverable-asset-store.ts

@@ -1,96 +0,0 @@
-// oss: false
-/**
- * The magnet-deliverable Asset store's data-access boundary (#6310 D16).
- *
- * `deliverable-fulfillment.ts` resolves `deliverables.assets[].assetKey`
- * against the workspace-scoped `Asset` model before falling back to the
- * legacy `DeliverableAsset` store (D1/D2), and the download route
- * (`routes/deliverables/index.ts`) serves an `asset_`-class grant's bytes
- * from the same model (D6). Neither caller may run a raw `prisma.asset`
- * query directly — that access is banned by the tenant-scope
- * `forbidden_pattern` in architecture.yaml — and neither is `lib/asset-store.ts`
- * a fit: it is `workspace`/`multi-tenant`-owned (`MODULE_SLICES`), so a
- * `signal-collectors` file (the route) cannot import it, and
- * `deliverable-fulfillment.ts` ships in every scaffold regardless of module
- * selection. This file is its own named boundary instead — modelled
- * line-for-line on `lib/asset-store.ts` — exporting exactly two scoped
- * reads and nothing else:
- *
- *   - `findDeliverableAssetIdByKey(workspaceId, key)` — the mint-time
- *     resolution (D2): does an `Asset` exist at this workspace's `key`?
- *   - `readDeliverableAsset(assetId, workspaceId)` — the serve-time read
- *     (D6): the bytes, scoped by the `workspaceId` the grant carries
- *     (D15), so a rewritten or mis-set grant can never serve another
- *     workspace's bytes.
- *
- * Neither ever resolves a client file (SEC-7877-A, #7877): an asset tagged
- * `private`, one a member-area message attaches, or one a delivered piece
- * version names (#8171 D3), is the same `null` a miss is — so a magnet pointed at a client file's key mints nothing and a
- * grant minted before the file became one serves nothing.
- *
- * No write, no `findMany`, no list, no unscoped read — both functions take
- * a `workspaceId` the caller resolved server-side, never a client-supplied
- * value, so neither can enumerate or cross a tenant boundary (NFR3).
- */
-import { PRIVATE_ASSET_TAG } from "@working-theory/validation";
-
-import { prisma } from "./prisma.js";
-
-/** A client file (SEC-7877-A) — `private`-tagged, attached to a message, or a version's file (#8171 D3). */
-async function isClientFile(
-  assetId: string,
-  workspaceId: string,
-  tags: string[],
-): Promise<boolean> {
-  if (tags.includes(PRIVATE_ASSET_TAG)) return true;
-  if ((await prisma.interaction.count({ where: { assetId, workspaceId } })) > 0) return true;
-  return (await prisma.pieceVersion.count({ where: { assetId, workspaceId } })) > 0;
-}
-
-/** What the mint-time resolution needs, and nothing more. */
-export async function findDeliverableAssetIdByKey(
-  workspaceId: string,
-  key: string,
-): Promise<string | null> {
-  const row = await prisma.asset.findFirst({
-    where: { workspaceId, key },
-    select: { id: true, tags: true },
-  });
-  if (!row || (await isClientFile(row.id, workspaceId, row.tags))) return null;
-  return row.id;
-}
-
-/** What the serve path needs, and deliberately nothing more (no key, no workspace). */
-export type DeliverableAssetBytes = {
-  filename: string;
-  contentType: string;
-  bytes: Buffer;
-};
-
-/**
- * Resolve one asset's bytes by id, scoped by `workspaceId` (D15). A foreign-
- * workspace id — or any other miss — returns `null`; the caller turns that
- * into the same uniform 404 an unknown grant gets (D6/FR5).
- */
-export async function readDeliverableAsset(
-  assetId: string,
-  workspaceId: string | null,
-): Promise<DeliverableAssetBytes | null> {
-  if (workspaceId === null) return null;
-
-  const row = await prisma.asset.findFirst({
-    where: { id: assetId, workspaceId },
-    select: { filename: true, contentType: true, bytes: true, tags: true },
-  });
-  if (!row || (await isClientFile(assetId, workspaceId, row.tags))) return null;
-
-  return {
-    filename: row.filename,
-    contentType: row.contentType,
-    // Prisma maps a `Bytes` column to `Uint8Array`, and Fastify treats only
-    // a `Buffer` as a raw payload — this wraps rather than copies
-    // (`Buffer.from(buffer, byteOffset, length)` is a view), mirroring
-    // `asset-store.ts`'s own identical wrap.
-    bytes: Buffer.from(row.bytes.buffer, row.bytes.byteOffset, row.bytes.byteLength),
-  };
-}

package/templates/apps/api/src/lib/error-serializer.ts

@@ -1,164 +0,0 @@
-/**
- * Fastify error-serializer — prevents internal error detail from leaking to clients.
- *
- * Fastify's default error handler echoes `err.message` (and in dev,
- * `err.stack`) in the response body. For internal errors (DB failures, SDK
- * exceptions, unhandled throws) that's sensitive: connection strings, host
- * names, schema hints, internal paths. This handler:
- *
- *   - Maps any 5xx-class internal Error to `{ error: "internal_error" }`
- *     with no detail
- *   - Logs the full Error (message, stack, request context) to pino at
- *     error level
- *   - Lets Fastify's built-in 4xx validation errors flow through
- *     (their `validation` payload is safe to surface — it describes the
- *     client's input, not server internals)
- *   - Leaves replies that handlers already committed (explicit status + body)
- *     untouched
- */
-import { idRegex } from "@working-theory/ids";
-import type { FastifyError, FastifyInstance } from "fastify";
-
-const GENERIC_INTERNAL_BODY = { error: "internal_error" } as const;
-
-/**
- * The request target with its QUERY STRING removed (#5970 security review,
- * finding 1).
- *
- * A route may carry its credential in the query — `GET
- * /v1/requests/:id/confirm?token=…` does, because a link in an email has
- * nowhere else to put one — and this handler logs `path` on EVERY error on
- * EVERY route. Logging the raw target would write that credential into the
- * API's own log the moment anything went wrong, which is precisely when logs
- * get read, copied into tickets, and shipped to third parties.
- */
-function pathWithoutQuery(url: string): string {
-  const queryAt = url.indexOf("?");
-  return queryAt === -1 ? url : url.slice(0, queryAt);
-}
-
-/**
- * #6084 D14 — `GET /v1/checkout/sessions/:id` puts its credential in the
- * PATH, so a `cs_…`-shaped segment is truncated to its first 8 characters
- * plus `…` (a path SEGMENT rule, never a substring replace, so it cannot
- * corrupt an unrelated URL). #6216 D11 adds the same arm for `lead_…`
- * segments and #8438 SEC-8438-10 for `person_…` segments, which would
- * otherwise put a full id beside `remoteAddress`.
- */
-const SESSION_ID_LOG_SEGMENT = /^cs_[A-Za-z0-9_]+$/;
-const LEAD_ID_LOG_SEGMENT = idRegex("lead");
-const PERSON_ID_LOG_SEGMENT = idRegex("person");
-
-/**
- * #8932 D10 (contract W9) — a webhook connection token is the per-connection
- * receiver's routing credential (`/v1/webhooks/<provider>/:connectionToken`).
- * Every segment after the provider is replaced by one literal
- * `:connectionToken`, keeping no prefix — unlike the id arms above — and
- * empty segments are dropped first, so a trailing slash, a double slash or a
- * mis-pasted extra segment cannot carry the token past the rule.
- */
-const CONNECTION_TOKEN_PLACEHOLDER = ":connectionToken";
-
-/** A segment as the router matches it: percent-decoded, or raw when it does not decode. */
-function decodedSegment(segment: string): string {
-  try {
-    return decodeURIComponent(segment);
-  } catch {
-    return segment;
-  }
-}
-
-function redactConnectionToken(path: string): string | null {
-  // Compared DECODED: the router decodes before it matches, so
-  // `/v1/%77ebhooks/stripe/<token>` reaches the token route and must be
-  // redacted like its plain spelling.
-  const segments = path
-    .split("/")
-    .filter((segment) => segment.length > 0)
-    .map(decodedSegment);
-  if (segments.length < 4 || segments[0] !== "v1" || segments[1] !== "webhooks") {
-    return null;
-  }
-  return `/${segments.slice(0, 3).join("/")}/${CONNECTION_TOKEN_PLACEHOLDER}`;
-}
-
-/**
- * The ONE path redactor for a log line (#8932 D10): the query string dropped,
- * a webhook connection token replaced whole, and every `cs_…`, `lead_…` and
- * `person_…` segment truncated. The Fastify request serializer (`server.ts`)
- * and this handler's three `path:` fields both call it, so a 429, 413, 415 or
- * 5xx on a token route logs the same redacted path its request line does.
- * A route parameter that is an identifier rather than a secret — `:id` — is
- * kept: it is what makes the line useful.
- */
-export function redactLogPath(url: string): string {
-  const path = pathWithoutQuery(url);
-  const tokenless = redactConnectionToken(path);
-  if (tokenless !== null) return tokenless;
-  return path
-    .split("/")
-    .map((segment) =>
-      SESSION_ID_LOG_SEGMENT.test(segment) ||
-      LEAD_ID_LOG_SEGMENT.test(segment) ||
-      PERSON_ID_LOG_SEGMENT.test(segment)
-        ? `${segment.slice(0, 8)}…`
-        : segment,
-    )
-    .join("/");
-}
-
-export function registerErrorSerializer(server: FastifyInstance): void {
-  server.setErrorHandler(async (err: FastifyError, request, reply) => {
-    // Validation errors (Fastify's schema validator) — keep structured detail.
-    // These describe the client request, not server internals.
-    if (err.validation) {
-      const status = err.statusCode ?? 400;
-      request.log.warn(
-        {
-          method: request.method,
-          path: redactLogPath(request.url),
-          validation: err.validation,
-        },
-        "request validation failed",
-      );
-      return reply.code(status).send({
-        error: "validation-error",
-        details: err.validation,
-      });
-    }
-
-    // Explicit 4xx errors thrown by handlers (e.g. fastify.httpErrors.notFound)
-    // also flow through — they're a deliberate boundary signal, not an
-    // internal leak.
-    const status = err.statusCode ?? 500;
-    if (status >= 400 && status < 500) {
-      request.log.info(
-        {
-          method: request.method,
-          path: redactLogPath(request.url),
-          statusCode: status,
-          errName: err.name,
-        },
-        "request returned 4xx",
-      );
-      // Don't echo err.message — handlers that want a structured body should
-      // call reply.code().send() directly. This branch is the safe fallback.
-      return reply.code(status).send({ error: err.code ?? "client_error" });
-    }
-
-    // 5xx — log everything, return nothing identifying.
-    request.log.error(
-      {
-        method: request.method,
-        path: redactLogPath(request.url),
-        errName: err.name,
-        errMessage: err.message,
-        errStack: err.stack,
-        errCode: err.code,
-      },
-      "internal server error",
-    );
-
-    return reply.code(500).send(GENERIC_INTERNAL_BODY);
-  });
-}

package/templates/apps/api/src/lib/errors.ts

@@ -1,95 +0,0 @@
-/**
- * Canonical error shape for apps/api content-write routes (D14a Stage 0).
- *
- * Every error response from create/update/delete content routes returns this
- * shape as the JSON body, paired with the appropriate HTTP status. The MCP
- * twin (`apps/mcp/src/lib/errors.ts`) returns the same shape sans `status` —
- * MCP carries the error in the tool result body itself.
- *
- * Codes are a closed set; consumers can switch on them to drive UI / retry
- * logic without parsing free-form `message` text. New codes get added here
- * before any route uses them.
- *
- * Usage:
- *   const err = validationError("Invalid type or slug", { field: "type" });
- *   return reply.status(err.status).send(err.body);
- */
-import { mapAdapterError } from "@working-theory/content-adapters";
-
-export type ErrorCode =
-  | "validation_failed"
-  | "not_found"
-  | "conflict"
-  | "payment_required"
-  | "unauthorized";
-
-export interface ErrorBody {
-  error: ErrorCode;
-  message: string;
-  details?: Record<string, unknown>;
-}
-
-export interface ErrorResponse {
-  status: number;
-  body: ErrorBody;
-}
-
-function makeBody(
-  code: ErrorCode,
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorBody {
-  if (details === undefined) {
-    return { error: code, message };
-  }
-  return { error: code, message, details };
-}
-
-export function validationError(
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorResponse {
-  return { status: 400, body: makeBody("validation_failed", message, details) };
-}
-
-export function unauthorizedError(message: string): ErrorResponse {
-  return { status: 401, body: makeBody("unauthorized", message) };
-}
-
-export function paymentRequiredError(message: string): ErrorResponse {
-  return { status: 402, body: makeBody("payment_required", message) };
-}
-
-export function notFoundError(message: string): ErrorResponse {
-  return { status: 404, body: makeBody("not_found", message) };
-}
-
-export function conflictError(
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorResponse {
-  return { status: 409, body: makeBody("conflict", message, details) };
-}
-
-/**
- * Route-layer adapter for `mapAdapterError` from `@working-theory/content-adapters`.
- * The package emits a canonical `{error, message, details?}` body but
- * cannot know the HTTP status (it has no app dependency). This helper
- * pairs the body with the right status. Returns `null` if the error
- * wasn't an `AdapterWriteError` (caller should treat as 500).
- */
-export function adapterErrorResponse(
-  err: unknown,
-  ctx: { type: string; slug: string },
-): ErrorResponse | null {
-  const body = mapAdapterError(err, ctx);
-  if (body === null) return null;
-  switch (body.error) {
-    case "conflict":
-      return { status: 409, body };
-    case "not_found":
-      return { status: 404, body };
-    case "validation_failed":
-      return { status: 400, body };
-  }
-}

package/templates/apps/api/src/lib/file-fallback.ts

@@ -1,87 +0,0 @@
-/**
- * File-fallback writer for the AILK inbox.
- *
- * Writes a Lead to ${AILK_INBOX_FALLBACK_DIR ?? '.ailk/inbox'}/<ISO-ts>-<lead.id>.json
- * when the database is unavailable. Engaged by B6's lead-routing service on DB failure.
- *
- * Path-traversal-safe by construction:
- *  1. lead.id is validated against /^[a-z0-9_-]{8,64}$/i before any fs operation.
- *  2. The resolved write path is checked to be strictly inside targetDir.
- *
- * No quota / count cap. Operators running with this fallback engaged for extended periods
- * should monitor disk usage and replay leads back to DB once it returns.
- *
- * Module is import-side-effect-free. No env reads at module-load time.
- */
-
-import * as fs from "fs/promises";
-import * as path from "path";
-
-import type { Lead } from "@working-theory/validation";
-
-export type FallbackLead = Lead;
-
-export type FallbackResult =
-  | { ok: true; path: string }
-  | {
-      ok: false;
-      error: {
-        kind: "invalid_id" | "path_escape" | "fs_error";
-        message: string;
-      };
-    };
-
-const LEAD_ID_RE = /^[a-z0-9_-]{8,64}$/i;
-
-export async function writeLeadFallback(
-  lead: FallbackLead,
-): Promise<FallbackResult> {
-  if (!LEAD_ID_RE.test(lead.id)) {
-    return {
-      ok: false,
-      error: { kind: "invalid_id", message: `Invalid lead id: ${lead.id}` },
-    };
-  }
-
-  // Resolve target directory — read env inside the function (no module-level side effects)
-  const envDir = process.env.AILK_INBOX_FALLBACK_DIR ?? ".ailk/inbox";
-  const targetDir = path.resolve(process.cwd(), envDir);
-
-  const rawTs = isValidIso(lead.createdAt)
-    ? lead.createdAt
-    : new Date().toISOString();
-  // Replace colons with hyphens for Windows filesystem compatibility
-  const ts = rawTs.replace(/:/g, "-");
-
-  const filename = `${ts}-${lead.id}.json`;
-  const resolved = path.resolve(targetDir, filename);
-
-  // Path-escape check: relative path must not start with '..' or be absolute
-  const rel = path.relative(targetDir, resolved);
-  if (rel.startsWith("..") || path.isAbsolute(rel)) {
-    return {
-      ok: false,
-      error: {
-        kind: "path_escape",
-        message: `Path escape detected: ${resolved}`,
-      },
-    };
-  }
-
-  try {
-    await fs.mkdir(targetDir, { recursive: true });
-    await fs.writeFile(resolved, JSON.stringify(lead, null, 2));
-    return { ok: true, path: resolved };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: { kind: "fs_error", message } };
-  }
-}
-
-// Require YYYY-MM-DD prefix before accepting as ISO — rejects slash-dates, traversal strings, etc.
-const ISO_RE = /^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]*)?$/;
-
-function isValidIso(value: string): boolean {
-  if (!value || !ISO_RE.test(value)) return false;
-  return !isNaN(new Date(value).getTime());
-}

package/templates/apps/api/src/lib/flow-completion-store.ts

@@ -1,136 +0,0 @@
-/**
- * A magnet's completion setting — its data boundary (#8757, spec
- * docs/specs/8757-a-per-magnet-completion-setting-spec.md D3).
- *
- * `flow_definitions.completion` / `checkout_offering` are new columns, and
- * `lib/tenant-db.ts` — the magnet routes' only other data path — stays closed
- * under the parallel contract with #8746 (D7), so the two columns get this
- * named boundary of their own. Every statement is scoped by a server-resolved
- * `workspaceId` (a tenant's, or the public lead route's resolved workspace):
- *
- *   - `completionsFor`       — one `findMany` by workspace AND id list;
- *   - `setCompletion`        — one `updateMany` by id AND workspace, writing
- *                              exactly the two columns;
- *   - `liveCompletionBySlug` — one `findFirst` of a LIVE magnet by workspace
- *                              AND slug (its pair, title and config — the
- *                              config for a declared `completionEmail`);
- *   - `inviteSendCounts`     — two `lead.count`s for the invite email's caps
- *                              (D6), by workspace AND `flow:<slug>` source.
- *
- * No list without an id set, no other model, no read by any other key.
- * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
- * entry, because the never-gate lead route imports it. `architecture.yaml`
- * lists this file under the tenant-scope rule's `paths_scoped` with exactly
- * these four call sites' counts, so a further access fails the lint.
- */
-import {
-  FLOW_COMPLETION_DEFAULT,
-  flowCompletionSettingSchema,
-  type FlowCompletionSetting,
-} from "@working-theory/validation";
-
-import { prisma } from "./prisma.js";
-
-const DEFAULT_SETTING: FlowCompletionSetting = {
-  completion: FLOW_COMPLETION_DEFAULT,
-  checkoutOffering: null,
-};
-
-/**
- * A stored pair as the vocabulary reads it. The database's CHECKs make every
- * stored pair valid; a row that carries neither column (a test fixture, or a
- * read before the migration) reads as the default, as `customersEnabled` does.
- */
-function toSetting(row: { completion?: unknown; checkoutOffering?: unknown }) {
-  const parsed = flowCompletionSettingSchema.safeParse({
-    completion: row.completion,
-    checkoutOffering: row.checkoutOffering ?? null,
-  });
-  return parsed.success ? parsed.data : DEFAULT_SETTING;
-}
-
-/** The setting of each of `ids` in `workspaceId`. An id absent from the map reads as `lead`. */
-export async function completionsFor(
-  workspaceId: string,
-  ids: readonly string[],
-): Promise<Map<string, FlowCompletionSetting>> {
-  const out = new Map<string, FlowCompletionSetting>();
-  if (ids.length === 0) return out;
-  const rows = await prisma.flowDefinition.findMany({
-    where: { workspaceId, id: { in: [...ids] } },
-    select: { id: true, completion: true, checkoutOffering: true },
-  });
-  for (const row of rows) out.set(row.id, toSetting(row));
-  return out;
-}
-
-/** `completionsFor`'s answer for one id. */
-export function completionOf(
-  settings: Map<string, FlowCompletionSetting>,
-  id: string,
-): FlowCompletionSetting {
-  return settings.get(id) ?? DEFAULT_SETTING;
-}
-
-/** Write the pair onto magnet `id` of `workspaceId`; nothing else on the row. */
-export async function setCompletion(
-  workspaceId: string,
-  id: string,
-  setting: FlowCompletionSetting,
-): Promise<"set" | "not_found"> {
-  const result = await prisma.flowDefinition.updateMany({
-    where: { id, workspaceId },
-    data: { completion: setting.completion, checkoutOffering: setting.checkoutOffering },
-  });
-  return result.count > 0 ? "set" : "not_found";
-}
-
-export type LiveCompletion = FlowCompletionSetting & {
-  title: string;
-  /** The stored config, unparsed — the invite email reads its `completionEmail`. */
-  config: unknown;
-};
-
-/** The LIVE magnet at `slug` in `workspaceId`: its setting, title and config, or `null`. */
-export async function liveCompletionBySlug(
-  workspaceId: string,
-  slug: string,
-): Promise<LiveCompletion | null> {
-  const row = await prisma.flowDefinition.findFirst({
-    where: { workspaceId, slug, status: "live" },
-    select: { title: true, config: true, completion: true, checkoutOffering: true },
-  });
-  return row === null ? null : { ...toSetting(row), title: row.title, config: row.config };
-}
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-const HOUR_MS = 60 * 60 * 1000;
-
-/**
- * D6's two caps, counted in the database so they hold across instances and
- * against a spoofed `x-forwarded-for`: this magnet's leads for `email`
- * (case-insensitively) over the last day, and all of its leads over the last
- * hour. Both include the lead the caller just wrote.
- */
-export async function inviteSendCounts(
-  workspaceId: string,
-  slug: string,
-  email: string,
-  now: Date,
-): Promise<{ recipientDay: number; siteHour: number }> {
-  const source = `flow:${slug}`;
-  const [recipientDay, siteHour] = await Promise.all([
-    prisma.lead.count({
-      where: {
-        workspaceId,
-        source,
-        email: { equals: email, mode: "insensitive" },
-        createdAt: { gte: new Date(now.getTime() - DAY_MS) },
-      },
-    }),
-    prisma.lead.count({
-      where: { workspaceId, source, createdAt: { gte: new Date(now.getTime() - HOUR_MS) } },
-    }),
-  ]);
-  return { recipientDay, siteHour };
-}