@ogygie/core 0.1.0

package/src/manifest-gateway.test.ts

@@ -0,0 +1,541 @@
+/**
+ * @intent Proves the behaviors of the GENERIC manifest-derived gateway
+ * factory: mounted inventory = manifest routes (mutation test included),
+ * input validated WITHOUT any upstream call, OgygieError relayed intact,
+ * 502/504 on upstream failure, security headers on every response, static
+ * SPA fallback with per-request nonce, boot refusal on incoherent manifest.
+ * The upstream is a real local Fastify recording every hit — no mock of our
+ * own relay code.
+ *
+ * Framework-side file: its fixtures carry no product vocabulary either (the
+ * vocabulary test scans this file too). The product-side proof — the REAL
+ * manifest against the REAL schema registry — stays in the consuming app.
+ */
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import Fastify from "fastify";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { OgygieFailure, ogygieError } from "./error.schema.js";
+import {
+  createManifestGateway,
+  type ManifestGatewayOptions,
+} from "./manifest-gateway.js";
+
+// ------------------------------------------------------------ test fixtures
+const CreateWidgetInputSchema = z.object({ label: z.string().min(3) });
+const ListWidgetsInputSchema = z.object({});
+const WidgetParamsSchema = z.object({ widgetId: z.uuid() });
+const EmptyInputSchema = z.object({});
+const WidgetOutputSchema = z.object({});
+
+const TEST_SCHEMAS = {
+  CreateWidgetInputSchema,
+  ListWidgetsInputSchema,
+  WidgetParamsSchema,
+  EmptyInputSchema,
+  WidgetOutputSchema,
+};
+
+interface TestRoute {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  description: string;
+  schemaInput: string;
+  schemaOutput: string;
+}
+
+const BASE_ROUTES: TestRoute[] = [
+  {
+    method: "POST",
+    path: "/api/widgets",
+    description: "creates a widget (relay test route)",
+    schemaInput: "CreateWidgetInputSchema",
+    schemaOutput: "WidgetOutputSchema",
+  },
+  {
+    method: "GET",
+    path: "/api/widgets",
+    description: "lists widgets (relay test route)",
+    schemaInput: "ListWidgetsInputSchema",
+    schemaOutput: "WidgetOutputSchema",
+  },
+  {
+    method: "GET",
+    path: "/api/widgets/:widgetId",
+    description: "reads one widget (params validation test route)",
+    schemaInput: "WidgetParamsSchema",
+    schemaOutput: "WidgetOutputSchema",
+  },
+  {
+    method: "GET",
+    path: "/api/failing",
+    description: "upstream answers a business OgygieError (relay purity)",
+    schemaInput: "EmptyInputSchema",
+    schemaOutput: "WidgetOutputSchema",
+  },
+  {
+    method: "GET",
+    path: "/api/slow",
+    description: "upstream sleeps longer than the gateway timeout",
+    schemaInput: "EmptyInputSchema",
+    schemaOutput: "WidgetOutputSchema",
+  },
+];
+
+function buildTestManifest(routes: TestRoute[] = BASE_ROUTES) {
+  return {
+    version: 1,
+    product: { name: "generic-product", description: "Produit de test du relais générique." },
+    apps: [
+      { name: "api", path: "apps/api", type: "api", entryPoint: "apps/api/src/server.ts" },
+    ],
+    features: [
+      {
+        name: "widgets",
+        intent: "Feature de test générique du relais dérivé du manifeste.",
+        folder: "src/features/widgets",
+        spec: null,
+        routes,
+        dbTables: [],
+        dependsOn: [],
+        status: "delivered",
+      },
+    ],
+    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+  };
+}
+
+// Business error served by the upstream — built ONCE so its timestamp is
+// stable and the relayed body can be compared byte-for-byte.
+const UPSTREAM_BUSINESS_ERROR = ogygieError({
+  code: "WIDGET_NOT_READY",
+  message: "The widget is not ready to be served.",
+  file: "apps/api/src/features/widgets/service.ts",
+  cause: "widget state is draft",
+  suggestedFix: "Publish the widget before reading it.",
+});
+
+interface UpstreamRecorder {
+  hits: Record<string, number>;
+  lastHeaders: Record<string, string | string[] | undefined>;
+  lastBody: unknown;
+}
+
+async function startUpstream() {
+  const recorder: UpstreamRecorder = { hits: {}, lastHeaders: {}, lastBody: null };
+  const upstream = Fastify({ logger: false });
+  const record = (key: string, headers: UpstreamRecorder["lastHeaders"], body: unknown) => {
+    recorder.hits[key] = (recorder.hits[key] ?? 0) + 1;
+    recorder.lastHeaders = headers;
+    recorder.lastBody = body;
+  };
+  upstream.post("/api/widgets", async (request, reply) => {
+    record("createWidget", request.headers, request.body);
+    return reply.code(201).send({ created: true, echo: request.body });
+  });
+  upstream.get("/api/widgets", async (request, reply) => {
+    record("listWidgets", request.headers, null);
+    return reply.code(200).send({ widgets: [] });
+  });
+  upstream.get("/api/widgets/:widgetId", async (request, reply) => {
+    record("getWidget", request.headers, null);
+    return reply.code(200).send({ params: request.params });
+  });
+  upstream.get("/api/failing", async (request, reply) => {
+    record("failing", request.headers, null);
+    return reply.code(409).send(UPSTREAM_BUSINESS_ERROR);
+  });
+  upstream.get("/api/slow", async (request, reply) => {
+    record("slow", request.headers, null);
+    await sleep(400);
+    return reply.code(200).send({ slow: true });
+  });
+  upstream.post("/api/auth/sign-in/email", async (request, reply) => {
+    record("authSignIn", request.headers, request.body);
+    reply.header("set-cookie", [
+      "session_token=abc123; Path=/; HttpOnly; SameSite=Strict",
+      "csrf_token=def456; Path=/; HttpOnly; SameSite=Strict",
+    ]);
+    return reply.code(200).send({ signedIn: true });
+  });
+  await upstream.listen({ port: 0, host: "127.0.0.1" });
+  const address = upstream.server.address();
+  if (address === null || typeof address === "string") throw new Error("no upstream port");
+  return { upstream, recorder, baseUrl: `http://127.0.0.1:${address.port}` };
+}
+
+type Upstream = Awaited<ReturnType<typeof startUpstream>>;
+let upstream: Upstream;
+
+// Wide-open rate limit: these tests fire hundreds of requests; the rate-limit
+// plugin's PRESENCE is asserted via headers, its ceiling is production config.
+const TEST_RATE_LIMIT = { max: 100_000, timeWindow: "1 minute" };
+
+function gatewayOptions(overrides: Partial<ManifestGatewayOptions> = {}): ManifestGatewayOptions {
+  return {
+    upstreamBaseUrl: upstream.baseUrl,
+    schemas: TEST_SCHEMAS,
+    rateLimit: TEST_RATE_LIMIT,
+    timeoutMs: 2_000,
+    csp: { nonce: true },
+    ...overrides,
+  };
+}
+
+beforeAll(async () => {
+  upstream = await startUpstream();
+});
+afterAll(async () => {
+  await upstream.upstream.close();
+});
+
+describe("manifest-gateway — dérivation du manifeste", () => {
+  it("ÉTANT DONNÉ un manifeste de N routes QUAND la passerelle démarre ALORS elle monte exactement N relais", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    expect(app.gatewayRoutes.map(({ method, path }) => ({ method, path }))).toEqual(
+      BASE_ROUTES.map(({ method, path }) => ({ method, path })),
+    );
+    await app.close();
+  });
+
+  it("MUTATION : une route ajoutée au manifeste apparaît et relaie sans aucune ligne de code", async () => {
+    const addedRoute: TestRoute = {
+      method: "GET",
+      path: "/api/widgets/:widgetId/details",
+      description: "route ajoutée par la mutation du manifeste",
+      schemaInput: "EmptyInputSchema",
+      schemaOutput: "WidgetOutputSchema",
+    };
+    const app = await createManifestGateway(
+      buildTestManifest([...BASE_ROUTES, addedRoute]),
+      gatewayOptions(),
+    );
+    expect(app.gatewayRoutes).toHaveLength(BASE_ROUTES.length + 1);
+    expect(app.gatewayRoutes.at(-1)?.path).toBe(addedRoute.path);
+    // The relay exists even though the upstream 404s it: the 404 comes from
+    // the UPSTREAM (plain Fastify payload), not from GATEWAY_ROUTE_UNKNOWN.
+    const response = await app.inject({ method: "GET", url: "/api/widgets/abc/details" });
+    expect(response.statusCode).toBe(404);
+    expect(response.body).not.toContain("GATEWAY_ROUTE_UNKNOWN");
+    await app.close();
+  });
+
+  it("une route non déclarée répond 404 GATEWAY_ROUTE_UNKNOWN sans atteindre l'upstream", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const hitsBefore = { ...upstream.recorder.hits };
+    const response = await app.inject({ method: "DELETE", url: "/api/widgets" });
+    expect(response.statusCode).toBe(404);
+    expect(response.json().code).toBe("GATEWAY_ROUTE_UNKNOWN");
+    expect(upstream.recorder.hits).toEqual(hitsBefore);
+    await app.close();
+  });
+});
+
+describe("manifest-gateway — validation d'entrée (2e barrière)", () => {
+  it("une entrée invalide → 400 CONTRACT_VALIDATION_FAILED émis PAR la passerelle, sans appel upstream", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const hitsBefore = upstream.recorder.hits["createWidget"] ?? 0;
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/widgets",
+      payload: { label: "ab" },
+    });
+    expect(response.statusCode).toBe(400);
+    const body = response.json();
+    expect(body.code).toBe("CONTRACT_VALIDATION_FAILED");
+    expect(body.cause).toContain("label");
+    expect(upstream.recorder.hits["createWidget"] ?? 0).toBe(hitsBefore);
+    await app.close();
+  });
+
+  it("les params d'URL sont validés contre le schéma déclaré (uuid attendu)", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const invalid = await app.inject({ method: "GET", url: "/api/widgets/not-a-uuid" });
+    expect(invalid.statusCode).toBe(400);
+    expect(invalid.json().code).toBe("CONTRACT_VALIDATION_FAILED");
+    const valid = await app.inject({
+      method: "GET",
+      url: "/api/widgets/3b6f0a52-8f3c-4f5e-9f0a-2b1c6d7e8f90",
+    });
+    expect(valid.statusCode).toBe(200);
+    await app.close();
+  });
+
+  it("un corps qui n'est pas du JSON valide n'atteint jamais le réseau privé", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const hitsBefore = upstream.recorder.hits["createWidget"] ?? 0;
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/widgets",
+      headers: { "content-type": "application/json" },
+      payload: "{broken",
+    });
+    expect(response.statusCode).toBe(400);
+    expect(response.json().code).toBe("CONTRACT_VALIDATION_FAILED");
+    expect(upstream.recorder.hits["createWidget"] ?? 0).toBe(hitsBefore);
+    await app.close();
+  });
+});
+
+describe("manifest-gateway — relais pur", () => {
+  it("une requête valide est transmise avec cookie de session et x-request-id, réponse relayée", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/widgets",
+      headers: { cookie: "session_token=abc123" },
+      payload: { label: "widget zéro" },
+    });
+    expect(response.statusCode).toBe(201);
+    expect(response.json()).toEqual({ created: true, echo: { label: "widget zéro" } });
+    expect(upstream.recorder.lastHeaders["cookie"]).toBe("session_token=abc123");
+    expect(upstream.recorder.lastHeaders["x-request-id"]).toBeTruthy();
+    expect(response.headers["x-request-id"]).toBe(upstream.recorder.lastHeaders["x-request-id"]);
+    await app.close();
+  });
+
+  it("un x-request-id fourni par le client est propagé tel quel", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    await app.inject({
+      method: "GET",
+      url: "/api/widgets",
+      headers: { "x-request-id": "corr-42" },
+    });
+    expect(upstream.recorder.lastHeaders["x-request-id"]).toBe("corr-42");
+    await app.close();
+  });
+
+  it("une OgygieError upstream traverse SANS reformatage — statut et corps inchangés, octet pour octet", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const direct = await fetch(`${upstream.baseUrl}/api/failing`);
+    const directBody = await direct.text();
+    const relayed = await app.inject({ method: "GET", url: "/api/failing" });
+    expect(relayed.statusCode).toBe(direct.status);
+    expect(relayed.body).toBe(directBody);
+    expect(relayed.json().code).toBe("WIDGET_NOT_READY");
+    await app.close();
+  });
+
+  it("le passthrough /api/auth/* relaie sans validation et retransmet Set-Cookie intégralement", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ passthroughPrefixes: ["/api/auth/"] }),
+    );
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/auth/sign-in/email",
+      payload: { email: "user@example.com", password: "secret-password" },
+    });
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ signedIn: true });
+    const cookies = response.headers["set-cookie"];
+    expect(cookies).toHaveLength(2);
+    expect(cookies?.[0]).toContain("session_token=abc123");
+    expect(cookies?.[1]).toContain("csrf_token=def456");
+    await app.close();
+  });
+});
+
+describe("manifest-gateway — upstream en panne", () => {
+  it("upstream injoignable → 502 GATEWAY_UPSTREAM_UNAVAILABLE, sans fuite d'URL privée", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ upstreamBaseUrl: "http://127.0.0.1:1" }),
+    );
+    const response = await app.inject({ method: "GET", url: "/api/widgets" });
+    expect(response.statusCode).toBe(502);
+    expect(response.json().code).toBe("GATEWAY_UPSTREAM_UNAVAILABLE");
+    expect(response.body).not.toContain("127.0.0.1");
+    expect(response.body).not.toContain("stack");
+    await app.close();
+  });
+
+  it("upstream trop lent → 504 GATEWAY_UPSTREAM_TIMEOUT", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ timeoutMs: 80 }),
+    );
+    const response = await app.inject({ method: "GET", url: "/api/slow" });
+    expect(response.statusCode).toBe(504);
+    expect(response.json().code).toBe("GATEWAY_UPSTREAM_TIMEOUT");
+    await app.close();
+  });
+});
+
+describe("manifest-gateway — en-têtes de sécurité et front statique", () => {
+  function buildStaticRoot(): string {
+    const root = mkdtempSync(join(tmpdir(), "gateway-static-"));
+    writeFileSync(
+      join(root, "index.html"),
+      '<!doctype html><html><head><script type="module" src="/assets/app.js"></script></head><body></body></html>',
+    );
+    mkdirSync(join(root, "assets"));
+    writeFileSync(join(root, "assets", "app.js"), 'console.log("static asset");');
+    return root;
+  }
+
+  it("les en-têtes transverses sont posés ICI sur toute réponse (api comme front), CSP sans unsafe-inline", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ staticRoot: buildStaticRoot() }),
+    );
+    for (const url of ["/api/widgets", "/app"]) {
+      const response = await app.inject({ method: "GET", url });
+      expect(response.statusCode).toBe(200);
+      const csp = response.headers["content-security-policy"];
+      expect(csp).toContain("default-src 'self'");
+      expect(csp).toContain("frame-ancestors 'none'");
+      expect(csp).not.toContain("unsafe-inline");
+      expect(response.headers["strict-transport-security"]).toContain("max-age");
+      expect(response.headers["x-content-type-options"]).toBe("nosniff");
+      expect(response.headers["referrer-policy"]).toBeTruthy();
+      expect(response.headers["permissions-policy"]).toContain("camera=()");
+      expect(response.headers["x-ratelimit-limit"]).toBeDefined();
+    }
+    await app.close();
+  });
+
+  it("les en-têtes de sécurité de la passerelle priment sur ceux relayés de l'upstream", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const response = await app.inject({ method: "GET", url: "/api/widgets" });
+    // The upstream (plain Fastify) sets none of these; if it did, the
+    // gateway's own values must win — here we prove the gateway's are there.
+    expect(response.headers["content-security-policy"]).toContain("default-src 'self'");
+    await app.close();
+  });
+
+  it("fichier statique servi, fallback SPA avec nonce par requête, /api inconnu jamais avalé par le fallback", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ staticRoot: buildStaticRoot() }),
+    );
+    const asset = await app.inject({ method: "GET", url: "/assets/app.js" });
+    expect(asset.statusCode).toBe(200);
+    expect(asset.body).toContain("static asset");
+
+    const spa = await app.inject({ method: "GET", url: "/app/nested/route" });
+    expect(spa.statusCode).toBe(200);
+    expect(spa.headers["content-type"]).toContain("text/html");
+    const nonceMatch = /<script nonce="([^"]+)"/.exec(spa.body);
+    expect(nonceMatch).not.toBeNull();
+    expect(spa.headers["content-security-policy"]).toContain(`'nonce-${nonceMatch?.[1]}'`);
+
+    const unknownApi = await app.inject({ method: "GET", url: "/api/nowhere" });
+    expect(unknownApi.statusCode).toBe(404);
+    expect(unknownApi.json().code).toBe("GATEWAY_ROUTE_UNKNOWN");
+
+    const postOutsideApi = await app.inject({ method: "POST", url: "/app" });
+    expect(postOutsideApi.statusCode).toBe(404);
+    expect(postOutsideApi.json().code).toBe("GATEWAY_ROUTE_UNKNOWN");
+    await app.close();
+  });
+
+  it("la RACINE sert le shell du SPA, avec son nonce — l'URL d'entrée du produit n'est pas un cas particulier", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ staticRoot: buildStaticRoot() }),
+    );
+
+    for (const method of ["GET", "HEAD"] as const) {
+      const response = await app.inject({ method, url: "/" });
+      expect(response.statusCode, `${method} /`).toBe(200);
+      expect(response.headers["content-type"]).toContain("text/html");
+    }
+    const root = await app.inject({ method: "GET", url: "/" });
+    const nonceMatch = /<script nonce="([^"]+)"/.exec(root.body);
+    expect(nonceMatch).not.toBeNull();
+    expect(root.headers["content-security-policy"]).toContain(`'nonce-${nonceMatch?.[1]}'`);
+    await app.close();
+  });
+
+  it("MUTATION : sans front à servir, la racine reste un 404 structuré — jamais une page vide", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+
+    const response = await app.inject({ method: "GET", url: "/" });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json().code).toBe("GATEWAY_ROUTE_UNKNOWN");
+    await app.close();
+  });
+});
+
+describe("manifest-gateway — refus de démarrer (GATEWAY_MANIFEST_INVALID)", () => {
+  async function expectBootRefusal(manifest: unknown, options: Partial<ManifestGatewayOptions>) {
+    try {
+      await createManifestGateway(manifest, gatewayOptions(options));
+      expect.unreachable("boot should have been refused");
+    } catch (error) {
+      expect(error).toBeInstanceOf(OgygieFailure);
+      if (error instanceof OgygieFailure) {
+        expect(error.error.code).toBe("GATEWAY_MANIFEST_INVALID");
+      }
+    }
+  }
+
+  it("MUTATION : un manifeste qui ne parse pas est refusé", async () => {
+    await expectBootRefusal({ version: 1, features: "broken" }, {});
+  });
+
+  it("MUTATION : une route dont le schéma d'entrée est introuvable au registre est refusée", async () => {
+    const incompleteRegistry: Record<string, z.ZodType> = { ...TEST_SCHEMAS };
+    delete incompleteRegistry["CreateWidgetInputSchema"];
+    await expectBootRefusal(buildTestManifest(), { schemas: incompleteRegistry });
+  });
+
+  it("MUTATION : un chemin de route malformé est refusé", async () => {
+    const malformed = buildTestManifest([
+      {
+        method: "GET",
+        path: "/api/widg ets",
+        description: "chemin malformé pour le test de refus",
+        schemaInput: "ListWidgetsInputSchema",
+        schemaOutput: "WidgetOutputSchema",
+      },
+    ]);
+    await expectBootRefusal(malformed, {});
+  });
+
+  it("MUTATION : une route déclarée deux fois est refusée", async () => {
+    const listRoute = BASE_ROUTES[1];
+    if (listRoute === undefined) throw new Error("fixture manquante");
+    await expectBootRefusal(buildTestManifest([...BASE_ROUTES, { ...listRoute }]), {});
+  });
+});
+
+describe("manifest-gateway — budget de latence", () => {
+  it("le surcoût du relais est < 5 ms au P95 (keep-alive local, mesuré)", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    await app.listen({ port: 0, host: "127.0.0.1" });
+    const address = app.server.address();
+    if (address === null || typeof address === "string") throw new Error("no gateway port");
+    const gatewayBase = `http://127.0.0.1:${address.port}`;
+
+    async function measure(base: string, samples: number): Promise<number[]> {
+      const durations: number[] = [];
+      for (let index = 0; index < samples; index += 1) {
+        const start = performance.now();
+        const response = await fetch(`${base}/api/widgets`);
+        await response.arrayBuffer();
+        durations.push(performance.now() - start);
+      }
+      return durations.sort((left, right) => left - right);
+    }
+
+    const WARMUP = 30;
+    const SAMPLES = 200;
+    await measure(upstream.baseUrl, WARMUP);
+    await measure(gatewayBase, WARMUP);
+    const direct = await measure(upstream.baseUrl, SAMPLES);
+    const relayed = await measure(gatewayBase, SAMPLES);
+    const p95 = (sorted: number[]) => sorted[Math.floor(sorted.length * 0.95)] ?? 0;
+    const overhead = p95(relayed) - p95(direct);
+    console.log(
+      `latence P95 — direct ${p95(direct).toFixed(2)} ms, via passerelle ${p95(relayed).toFixed(2)} ms, surcoût ${overhead.toFixed(2)} ms`,
+    );
+    expect(overhead).toBeLessThan(5);
+    await app.close();
+  });
+});