Initial Commit

packages/api-stack/api/api-graphql-ui-graphiql/src/headers/csp.md

@@ -0,0 +1,64 @@
+# `headers/csp`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the `Content-Security-Policy` header values emitted on the GraphiQL
+HTML response. The policy is hard-coded to a posture that's safe for
+production deployments: `default-src 'self'`, `script-src 'self'`,
+`style-src 'self' 'unsafe-inline'`, `img-src 'self' data:`, and
+`connect-src 'self'`.
+
+`'unsafe-inline'` is granted to `style-src` because GraphiQL's bundled
+CSS ships inline `<style>` declarations. It is NOT granted to
+`script-src` — the bundled bootstrap is loaded from `/graphql/ui/assets/`
+with a hashed filename, never inlined.
+
+## Features
+
+- `CSP_HEADER_VALUE` — single canonical value used on every HTML response.
+- `buildCspHeader()` — returns the `{ name, value }` pair so future
+  per-environment relaxations have a single touch-point.
+- `cspAllowsInlineScripts(value)` — predicate used by the conformance
+  test to guard against accidental `'unsafe-inline'` creep into
+  `script-src`.
+
+## Usage: Basic
+
+```ts
+import { buildCspHeader } from "@suaveplan/api-graphql-ui-graphiql";
+
+const { name, value } = buildCspHeader();
+// name === "Content-Security-Policy"
+// value === "default-src 'self'; style-src 'self' 'unsafe-inline'; ..."
+```
+
+## Usage: Advanced
+
+```ts
+import { cspAllowsInlineScripts } from "@suaveplan/api-graphql-ui-graphiql";
+
+if (cspAllowsInlineScripts(myCspValue)) {
+    throw new Error("script-src must NOT include 'unsafe-inline'");
+}
+```
+
+## API Reference
+
+- `CSP_HEADER_NAME: "Content-Security-Policy"`.
+- `CSP_HEADER_VALUE: string` — the canonical value emitted on the
+  HTML response.
+- `buildCspHeader(): { name: string; value: string }` — returns the
+  name/value pair.
+- `cspAllowsInlineScripts(value): boolean` — predicate matching
+  `'unsafe-inline'` inside a `script-src` directive.
+
+## Implementation Notes
+
+Inline-style allowance is documented in the module header so future
+maintainers don't tighten the policy without understanding why. The
+predicate operates on the raw header string rather than parsing the CSP
+grammar — sufficient for the conformance check.