# `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.