@ogygie/core 0.13.1 → 0.15.0

package/README.md

@@ -118,6 +118,8 @@ for (const route of app.gatewayRoutes) console.log(route.method, route.path);
 | `schemas` | oui | `Record<string, ZodType>` indexé par nom exporté. Doit contenir **tous** les `schemaInput`/`schemaOutput` du manifeste, sinon le démarrage est refusé. |
 | `timeoutMs` | oui | Délai au-delà duquel l'appel amont est abandonné (→ 504). |
 | `csp.nonce` | oui | Pose un nonce CSP par requête et l'estampille sur les `<script>` de l'`index.html` servi. |
+| `csp.externalOrigins` | non | Liste **FERMÉE** d'origines https externes ajoutées à `connect-src` **et** `img-src`, rien d'autre (ex. un serveur de tuiles public que le front appelle directement). Chaque entrée est validée **au démarrage** : origine https nue, sans chemin ni joker — une entrée invalide refuse de démarrer (`GATEWAY_CSP_ORIGIN_INVALID`), même esprit que `passthroughPrefixes`. Absente ou vide = `connect-src`/`img-src` inchangés, octet pour octet. |
+| `csp.allowWorkerBlob` | non | Ajoute la directive `worker-src 'self' blob:` — nécessaire aux libs qui créent leurs workers depuis un blob (ex. MapLibre GL). Absente ou `false` = aucune directive `worker-src`, comme aujourd'hui. |
 | `staticRoot` | non | Dossier du build front : fichiers statiques + fallback `index.html` pour le routage client. Absent = rien n'est servi. |
 | `rateLimit` | non | `{ max, timeWindow }` ; défaut `300 / 1 minute`. |
 | `passthroughPrefixes` | non | Préfixes relayés **sans validation de contrat** (ex. un catch-all d'auth possédé par l'api, absent du manifeste par nature). Seule brèche à la règle « rien ne passe qui ne soit au manifeste » : liste fermée, chaque entrée justifiée, jamais un motif large. |
@@ -134,11 +136,16 @@ les écraser) : CSP stricte sans `unsafe-inline`, HSTS, `X-Content-Type-Options`
 et les `Set-Cookie` de l'amont, eux, traversent **octet pour octet** — une
 `OgygieError` métier arrive au client sans reformatage.
 
+La CSP ne s'élargit que sur demande EXPLICITE et par liste fermée
+(`csp.externalOrigins`, `csp.allowWorkerBlob` ci-dessus) : sans ces options,
+elle reste strictement celle d'hier.
+
 ### Erreurs
 
 | Code | Statut | Quand |
 |---|---|---|
 | `GATEWAY_MANIFEST_INVALID` | 500, **au démarrage** | Manifeste illisible, chemin de route malformé, route déclarée deux fois, ou schéma déclaré absent de `schemas`. Levée en `OgygieFailure` : le processus ne démarre pas — un démarrage impossible vaut mieux qu'un relais qui ment. |
+| `GATEWAY_CSP_ORIGIN_INVALID` | 500, **au démarrage** | Une entrée de `csp.externalOrigins` n'est pas une origine https nue (joker, chemin, schéma non-https…). Même logique que `GATEWAY_MANIFEST_INVALID` : un démarrage refusé vaut mieux qu'une CSP silencieusement élargie. |
 | `CONTRACT_VALIDATION_FAILED` | 400 | L'entrée ne satisfait pas le schéma déclaré. Émise PAR la passerelle : le trafic invalide n'atteint jamais le réseau privé. Le corps JSON est validé sur POST/PUT/PATCH, `{ ...query, ...params }` sur GET/DELETE. |
 | `GATEWAY_ROUTE_UNKNOWN` | 404 | Aucune route déclarée ne correspond (et aucun fallback SPA applicable). |
 | `GATEWAY_UPSTREAM_UNAVAILABLE` | 502 | L'amont est injoignable. Aucun détail interne ne fuit : ni URL privée, ni stack. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Ogygie framework core: manifest/spec/error schemas, generic tenancy and gate tooling. Ships TypeScript sources — Ogygie products run tsx/vitest by construction (D1).",
   "license": "MIT",
   "type": "module",
@@ -13,28 +13,29 @@
     "access": "public"
   },
   "exports": {
-    "./manifest": "./src/manifest.schema.ts",
-    "./manifest-owners": "./src/manifest-owners.ts",
-    "./vocabulary": "./src/vocabulary.ts",
-    "./vocabulary-audit": "./src/vocabulary-audit.ts",
-    "./web-lint": "./src/web-lint.ts",
     "./bundle-budget": "./src/bundle-budget.ts",
-    "./spec": "./src/spec.schema.ts",
-    "./impact": "./src/impact.ts",
-    "./repo-adapter": "./src/repo-adapter.ts",
+    "./client": "./src/manifest-client.ts",
+    "./client-react": "./src/manifest-client-react.ts",
+    "./clock": "./src/clock.ts",
+    "./contract-purity": "./src/contract-purity.ts",
+    "./db": "./src/db.ts",
     "./decision-refs": "./src/decision-refs.ts",
     "./design-brief": "./src/design-brief.ts",
-    "./module-purity": "./src/module-purity.ts",
-    "./contract-purity": "./src/contract-purity.ts",
     "./errors": "./src/error.schema.ts",
-    "./db": "./src/db.ts",
-    "./clock": "./src/clock.ts",
-    "./tenant": "./src/tenant.ts",
+    "./gateway": "./src/manifest-gateway.ts",
+    "./impact": "./src/impact.ts",
+    "./manifest": "./src/manifest.schema.ts",
+    "./manifest-owners": "./src/manifest-owners.ts",
+    "./module-purity": "./src/module-purity.ts",
+    "./repo-adapter": "./src/repo-adapter.ts",
+    "./scan": "./src/scan.ts",
     "./shared-tables": "./src/shared-tables.ts",
+    "./spec": "./src/spec.schema.ts",
+    "./tenant": "./src/tenant.ts",
     "./test-kit": "./src/test-kit.ts",
-    "./gateway": "./src/manifest-gateway.ts",
-    "./client": "./src/manifest-client.ts",
-    "./client-react": "./src/manifest-client-react.ts"
+    "./vocabulary": "./src/vocabulary.ts",
+    "./vocabulary-audit": "./src/vocabulary-audit.ts",
+    "./web-lint": "./src/web-lint.ts"
   },
   "peerDependencies": {
     "@electric-sql/pglite": "^0.3.0",

package/src/manifest-gateway.test.ts

@@ -3,7 +3,10 @@
  * 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.
+ * SPA fallback with per-request nonce, boot refusal on incoherent manifest,
+ * and the two opt-in CSP widenings (external origins, worker-src blob:) —
+ * default policy unchanged, closed-list validation, boot refusal on an
+ * invalid origin.
  * The upstream is a real local Fastify recording every hit — no mock of our
  * own relay code.
  *
@@ -462,6 +465,95 @@ describe("manifest-gateway — en-têtes de sécurité et front statique", () =>
   });
 });
 
+describe("manifest-gateway — CSP, origines externes et worker-src (opt-in)", () => {
+  it("par défaut (aucune option csp au-delà de nonce) la CSP est STRICTEMENT identique à avant : connect-src/img-src sans ajout, aucun worker-src", async () => {
+    const app = await createManifestGateway(buildTestManifest(), gatewayOptions());
+    const response = await app.inject({ method: "GET", url: "/api/widgets" });
+    const csp = response.headers["content-security-policy"];
+    expect(csp).toContain("connect-src 'self';");
+    expect(csp).toContain("img-src 'self' data:;");
+    expect(csp).not.toContain("worker-src");
+    await app.close();
+  });
+
+  it("csp.externalOrigins ajoute chaque origine à connect-src ET img-src, et rien d'autre", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({
+        csp: { nonce: true, externalOrigins: ["https://data.geopf.fr"] },
+      }),
+    );
+    const response = await app.inject({ method: "GET", url: "/api/widgets" });
+    const csp = response.headers["content-security-policy"];
+    expect(csp).toContain("connect-src 'self' https://data.geopf.fr;");
+    expect(csp).toContain("img-src 'self' data: https://data.geopf.fr;");
+    // Le reste de la politique ne bouge pas.
+    expect(csp).toContain("script-src 'self'");
+    expect(csp).toContain("style-src 'self'");
+    expect(csp).not.toContain("worker-src");
+    await app.close();
+  });
+
+  it("csp.allowWorkerBlob ajoute worker-src 'self' blob: — absent, aucun worker-src", async () => {
+    const withBlob = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ csp: { nonce: true, allowWorkerBlob: true } }),
+    );
+    const responseWithBlob = await withBlob.inject({ method: "GET", url: "/api/widgets" });
+    expect(responseWithBlob.headers["content-security-policy"]).toContain(
+      "worker-src 'self' blob:",
+    );
+    await withBlob.close();
+
+    const withoutBlob = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({ csp: { nonce: true, allowWorkerBlob: false } }),
+    );
+    const responseWithoutBlob = await withoutBlob.inject({ method: "GET", url: "/api/widgets" });
+    expect(responseWithoutBlob.headers["content-security-policy"]).not.toContain("worker-src");
+    await withoutBlob.close();
+  });
+
+  it.each([
+    ["joker de sous-domaine", "https://*.geopf.fr"],
+    ["schéma http, pas https", "http://data.geopf.fr"],
+    ["chemin après l'origine", "https://data.geopf.fr/wmts"],
+    ["barre oblique finale", "https://data.geopf.fr/"],
+    ["chaîne vide", ""],
+    ["pas une URL", "geopf"],
+  ])(
+    "MUTATION : une origine externe invalide (%s) refuse le démarrage — GATEWAY_CSP_ORIGIN_INVALID",
+    async (_label, invalidOrigin) => {
+      try {
+        await createManifestGateway(
+          buildTestManifest(),
+          gatewayOptions({ csp: { nonce: true, externalOrigins: [invalidOrigin] } }),
+        );
+        expect.unreachable("boot should have been refused");
+      } catch (error) {
+        expect(error).toBeInstanceOf(OgygieFailure);
+        if (error instanceof OgygieFailure) {
+          expect(error.error.code).toBe("GATEWAY_CSP_ORIGIN_INVALID");
+        }
+      }
+    },
+  );
+
+  it("une origine externe valide, hôte multi-niveaux avec port, est acceptée", async () => {
+    const app = await createManifestGateway(
+      buildTestManifest(),
+      gatewayOptions({
+        csp: { nonce: true, externalOrigins: ["https://tiles.example.co.uk:8443"] },
+      }),
+    );
+    const response = await app.inject({ method: "GET", url: "/api/widgets" });
+    expect(response.headers["content-security-policy"]).toContain(
+      "connect-src 'self' https://tiles.example.co.uk:8443;",
+    );
+    await app.close();
+  });
+});
+
 describe("manifest-gateway — refus de démarrer (GATEWAY_MANIFEST_INVALID)", () => {
   async function expectBootRefusal(manifest: unknown, options: Partial<ManifestGatewayOptions>) {
     try {

package/src/manifest-gateway.ts

@@ -39,7 +39,25 @@ export interface ManifestGatewayOptions {
   staticRoot?: string;
   rateLimit?: { max: number; timeWindow: string };
   timeoutMs: number;
-  csp: { nonce: boolean };
+  csp: {
+    nonce: boolean;
+    /**
+     * Closed list of external https origins additionally allowed in
+     * connect-src and img-src — nothing else is widened (e.g. a public tile
+     * server the front fetches directly). Each entry is validated at boot: a
+     * bare https origin, no path, no wildcard. An invalid entry refuses to
+     * start (GATEWAY_CSP_ORIGIN_INVALID) — a boot refusal beats a silently
+     * widened policy. Absent or empty = today's connect-src/img-src, byte
+     * for byte unchanged.
+     */
+    externalOrigins?: string[];
+    /**
+     * Adds `worker-src 'self' blob:` — required by libraries that spawn
+     * their workers from a Blob URL (e.g. MapLibre GL). Absent or false =
+     * no worker-src directive at all, identical to today.
+     */
+    allowWorkerBlob?: boolean;
+  };
   /** Path prefixes relayed WITHOUT contract validation (e.g. an auth
    * catch-all owned by the upstream, absent from the manifest by nature). */
   passthroughPrefixes?: string[];
@@ -102,6 +120,11 @@ const SKIPPED_RESPONSE_HEADERS = new Set([
  * (regex, wildcard, spaces…) is a malformed declaration, refused at boot. */
 const WELL_FORMED_ROUTE_PATH = /^\/api(\/(:?[a-zA-Z0-9_-]+))+$/;
 
+/** A bare https origin — scheme, host, optional port, nothing after it. No
+ * path, no query, no wildcard: the character classes below admit neither. */
+const HTTPS_BARE_ORIGIN_PATTERN =
+  /^https:\/\/[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(?::[0-9]{1,5})?$/;
+
 function refuseBoot(cause: string): never {
   throwOgygieError(
     {
@@ -116,6 +139,20 @@ function refuseBoot(cause: string): never {
   );
 }
 
+function refuseCspExternalOrigin(origin: string): never {
+  throwOgygieError(
+    {
+      code: "GATEWAY_CSP_ORIGIN_INVALID",
+      message: "Gateway boot refused: an entry of csp.externalOrigins is not a valid origin.",
+      file: null,
+      cause: `"${origin}" must be a bare https origin — no path, no query, no wildcard (e.g. "https://data.geopf.fr")`,
+      suggestedFix:
+        "Fix the entry in csp.externalOrigins, then restart — a boot refusal beats a silently widened CSP.",
+    },
+    500,
+  );
+}
+
 export async function createManifestGateway(
   manifest: unknown,
   options: ManifestGatewayOptions,
@@ -156,6 +193,15 @@ export async function createManifestGateway(
     }
   }
 
+  // Closed list, validated at boot — same spirit as passthroughPrefixes:
+  // every entry is a deliberate, justified widening, never a broad pattern.
+  const externalOrigins = options.csp.externalOrigins ?? [];
+  for (const origin of externalOrigins) {
+    if (!HTTPS_BARE_ORIGIN_PATTERN.test(origin)) {
+      refuseCspExternalOrigin(origin);
+    }
+  }
+
   const app = Fastify({ logger: false });
   app.decorate("gatewayRoutes", inventory);
 
@@ -171,24 +217,32 @@ export async function createManifestGateway(
     done(null, body),
   );
 
+  // Strict by default: no external origin, no worker-src directive at all —
+  // both widenings below are opt-in, and the default is byte-for-byte what
+  // it was before either option existed.
+  const cspDirectives: Record<string, string[]> = {
+    "default-src": ["'self'"],
+    "script-src": ["'self'"],
+    "style-src": ["'self'"],
+    "img-src": ["'self'", "data:", ...externalOrigins],
+    "font-src": ["'self'"],
+    "connect-src": ["'self'", ...externalOrigins],
+    "object-src": ["'none'"],
+    "base-uri": ["'self'"],
+    "form-action": ["'self'"],
+    "frame-ancestors": ["'none'"],
+  };
+  if (options.csp.allowWorkerBlob === true) {
+    cspDirectives["worker-src"] = ["'self'", "blob:"];
+  }
+
   await app.register(helmet, {
     // Strict CSP, no 'unsafe-inline' anywhere; per-request nonces cover the
     // scripts the front build may inline (spec §Comportements).
     enableCSPNonces: options.csp.nonce,
     contentSecurityPolicy: {
       useDefaults: false,
-      directives: {
-        "default-src": ["'self'"],
-        "script-src": ["'self'"],
-        "style-src": ["'self'"],
-        "img-src": ["'self'", "data:"],
-        "font-src": ["'self'"],
-        "connect-src": ["'self'"],
-        "object-src": ["'none'"],
-        "base-uri": ["'self'"],
-        "form-action": ["'self'"],
-        "frame-ancestors": ["'none'"],
-      },
+      directives: cspDirectives,
     },
   });
   // Helmet does not cover Permissions-Policy; posed here once (spec).

package/src/scan.test.ts

@@ -0,0 +1,31 @@
+/**
+ * @intent Prouve la règle de parcours des gates, avec le cas qui l'a imposée :
+ * un projet Nuxt dont `typecheck` génère `.nuxt/` que `lint` refusait ensuite.
+ */
+import { describe, expect, it } from "vitest";
+import { isScannableDirectory, NEVER_SCANNED_DIRECTORIES } from "./scan.js";
+
+describe("isScannableDirectory", () => {
+  it("parcourt le code du projet", () => {
+    for (const name of ["apps", "packages", "src", "scripts", "features", "specs"]) {
+      expect(isScannableDirectory(name)).toBe(true);
+    }
+  });
+
+  it("ne parcourt AUCUN dossier en point — c'est la règle qui ne vieillit pas", () => {
+    for (const name of [".git", ".nuxt", ".output", ".next", ".svelte-kit", ".turbo", ".venv"]) {
+      expect(isScannableDirectory(name)).toBe(false);
+    }
+  });
+
+  it("ne parcourt pas les artefacts au nom ordinaire", () => {
+    for (const name of NEVER_SCANNED_DIRECTORIES) expect(isScannableDirectory(name)).toBe(false);
+  });
+
+  it("MUTATION : un dossier dont le nom COMMENCE par celui d'un artefact reste parcouru", () => {
+    // `distribution/` n'est pas `dist/`, et `buildings/` n'est pas `build/`.
+    expect(isScannableDirectory("distribution")).toBe(true);
+    expect(isScannableDirectory("buildings")).toBe(true);
+    expect(isScannableDirectory("node_modules_backup")).toBe(true);
+  });
+});

package/src/scan.ts

@@ -0,0 +1,35 @@
+/**
+ * @intent Which directories a gate WALKS — the one rule, for every gate.
+ *
+ * It existed five times, slightly differently, in as many scripts. That is how
+ * it fell behind: the lists were written when a build produced `dist/`, and a
+ * modern framework generates `.nuxt/`, `.output/`, `.next/`, `.svelte-kit/`,
+ * while a Python package carries `.venv/`. A gate that walks into them reports
+ * bans and forbidden words found in code NOBODY WROTE — and worse, it does so
+ * only after a build, so the loop passes in CI and fails on the machine of
+ * whoever just ran it. A consumer project hit exactly that: `typecheck`
+ * generated `.nuxt/`, and `lint` then refused a type-suppression directive the
+ * framework had written into its own generated types.
+ *
+ * The rule is deliberately blunt, because a subtle one would fall behind again:
+ * a DOT-directory is never source. Everything a project actually writes lives
+ * in a plainly-named folder; tooling, caches, virtual environments and build
+ * output all hide behind a dot, by a convention older than any of these tools.
+ */
+
+/** Plainly-named directories that are still artefacts, not source. */
+export const NEVER_SCANNED_DIRECTORIES = [
+  "node_modules",
+  "dist",
+  "dist-ui",
+  "build",
+  "coverage",
+] as const;
+
+/** Does a gate walk into this directory? Its NAME is the whole question. */
+export function isScannableDirectory(name: string): boolean {
+  // `.git`, `.nuxt`, `.output`, `.next`, `.svelte-kit`, `.turbo`, `.venv`,
+  // `.pytest_cache`… — one rule instead of a list that ages.
+  if (name.startsWith(".")) return false;
+  return !(NEVER_SCANNED_DIRECTORIES as readonly string[]).includes(name);
+}