@baukit/csp 0.0.0-stage → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Koss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# `@baukit/csp`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Content Security Policy that generated web and mobile web exports serve (ADR 0006 section 7).
+Products keep only their origins; the directives live here, so every product gets the same policy.
+
+```ts
+import { contentSecurityPolicy, originOf, SECURITY_HEADERS } from '@baukit/csp';
+
+const policy = contentSecurityPolicy({
+  styles: 'files',
+  origins: { api: originOf(process.env.VITE_API_URL) },
+  scriptHashes: [],
+});
+```
+
+`contentSecurityPolicy` throws on any script source that is not a `'sha256-...'` hash, and leaves
+out `upgrade-insecure-requests` only when an origin is plain `http:`.
+`developmentContentSecurityPolicy` adds inline styles and the HMR socket for the dev server.
+`unhashedInlineScripts` lists inline scripts a built page carries that the policy does not hash.
+
+`SECURITY_HEADERS` holds the headers sent next to the policy: COOP and CORP `same-origin` and
+`nosniff`. COEP stays unset because `require-corp` blocks third-party images and analytics that do
+not opt in.

package/dist/headers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Response headers every page of a built web app carries next to its policy.
+ * COEP stays unset: `require-corp` blocks third-party images and analytics
+ * that do not send CORP themselves.
+ */
+export declare const SECURITY_HEADERS: Readonly<Record<string, string>>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI7D,CAAC"}

package/dist/headers.js

@@ -0,0 +1,11 @@
+/**
+ * Response headers every page of a built web app carries next to its policy.
+ * COEP stays unset: `require-corp` blocks third-party images and analytics
+ * that do not send CORP themselves.
+ */
+export const SECURITY_HEADERS = {
+    'Cross-Origin-Opener-Policy': 'same-origin',
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    'X-Content-Type-Options': 'nosniff',
+};
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,4BAA4B,EAAE,aAAa;IAC3C,8BAA8B,EAAE,aAAa;IAC7C,wBAAwB,EAAE,SAAS;CACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SECURITY_HEADERS } from './headers.js';
+export { clerkFrontendApiOrigin, contentSecurityPolicy, developmentContentSecurityPolicy, hashSource, inlineScripts, originOf, unhashedInlineScripts, type PolicyOptions, type PolicyOrigins, type StyleSources, } from './policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,gCAAgC,EAChC,UAAU,EACV,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SECURITY_HEADERS } from './headers.js';
+export { clerkFrontendApiOrigin, contentSecurityPolicy, developmentContentSecurityPolicy, hashSource, inlineScripts, originOf, unhashedInlineScripts, } from './policy.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,gCAAgC,EAChC,UAAU,EACV,aAAa,EACb,QAAQ,EACR,qBAAqB,GAItB,MAAM,aAAa,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Content Security Policy for a built web app (ADR 0006 section 7). Pure, so
+ * build plugins, build checks and tests share one definition.
+ */
+/** `files`: CSS ships as files. `runtime-injected`: the UI library writes `<style>` at runtime. */
+export type StyleSources = 'files' | 'runtime-injected';
+export interface PolicyOrigins {
+    readonly api?: string | undefined;
+    readonly issuer?: string | undefined;
+    readonly analytics?: string | undefined;
+    readonly media?: string | undefined;
+    readonly suiteHub?: string | undefined;
+    readonly vendorConnect?: readonly string[];
+    readonly vendorImages?: readonly string[];
+}
+export interface PolicyOptions {
+    readonly styles: StyleSources;
+    readonly origins: PolicyOrigins;
+    /** `'sha256-...'` sources for every inline `<script>` the build emits. */
+    readonly scriptHashes: readonly string[];
+}
+/** Returns the origin of a configured URL, or `undefined` when it is unset. */
+export declare function originOf(value: string | undefined): string | undefined;
+/** The text of every inline script, in document order. */
+export declare function inlineScripts(html: string): string[];
+/** Formats a base64 SHA-256 digest as a CSP source. */
+export declare function hashSource(base64Digest: string): string;
+/**
+ * The production policy. `upgrade-insecure-requests` is left out only when an
+ * origin is plain `http:`, which happens for local builds against localhost.
+ */
+export declare function contentSecurityPolicy(options: PolicyOptions): string;
+/**
+ * The dev server variant: inline styles and the HMR websocket. Never served
+ * for a production build.
+ */
+export declare function developmentContentSecurityPolicy(options: PolicyOptions, hmrOrigins: readonly string[]): string;
+/** Inline scripts whose hash the policy's `script-src` lacks, as CSP hash sources. */
+export declare function unhashedInlineScripts(html: string, policy: string, hash: (script: string) => string): string[];
+/** Decodes Clerk's frontend API host from a publishable key (`pk_<env>_<base64 host$>`). */
+export declare function clerkFrontendApiOrigin(publishableKey: string | undefined): string | undefined;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAQD,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMtE;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpD;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMvD;AAyDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAOpE;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,MAAM,CAMR;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAC/B,MAAM,EAAE,CASV;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAO7F"}

package/dist/policy.js

@@ -0,0 +1,113 @@
+/**
+ * Content Security Policy for a built web app (ADR 0006 section 7). Pure, so
+ * build plugins, build checks and tests share one definition.
+ */
+const SELF = "'self'";
+const NONE = "'none'";
+const INLINE = "'unsafe-inline'";
+const INLINE_SCRIPT = /<script\b(?![^>]*\bsrc\s*=)[^>]*>([\s\S]*?)<\/script\s*>/giu;
+const HASH_SOURCE = /^'sha256-[A-Za-z0-9+/]+={0,2}'$/u;
+/** Returns the origin of a configured URL, or `undefined` when it is unset. */
+export function originOf(value) {
+    if (value === undefined || value.trim() === '') {
+        return undefined;
+    }
+    const url = new URL(value.includes('://') ? value : `https://${value}`);
+    return url.origin;
+}
+/** The text of every inline script, in document order. */
+export function inlineScripts(html) {
+    return [...html.matchAll(INLINE_SCRIPT)].map((match) => match[1] ?? '');
+}
+/** Formats a base64 SHA-256 digest as a CSP source. */
+export function hashSource(base64Digest) {
+    const source = `'sha256-${base64Digest}'`;
+    if (!HASH_SOURCE.test(source)) {
+        throw new Error(`not a base64 SHA-256 digest: ${base64Digest}`);
+    }
+    return source;
+}
+function sources(...values) {
+    return [...new Set(values.filter((value) => value !== undefined))];
+}
+function originList(origins) {
+    return [
+        origins.api,
+        origins.issuer,
+        origins.analytics,
+        origins.media,
+        origins.suiteHub,
+        ...(origins.vendorConnect ?? []),
+        ...(origins.vendorImages ?? []),
+    ];
+}
+function usesPlainHttp(origins) {
+    return originList(origins).some((origin) => origin?.startsWith('http:') === true);
+}
+function directives(options) {
+    const { origins } = options;
+    const issuer = origins.issuer;
+    return [
+        ['default-src', [SELF]],
+        ['script-src', sources(SELF, ...options.scriptHashes)],
+        ['style-src', options.styles === 'files' ? [SELF] : [SELF, INLINE]],
+        ['img-src', sources(SELF, 'data:', 'blob:', origins.media, ...(origins.vendorImages ?? []))],
+        ['media-src', sources(SELF, 'blob:', origins.media)],
+        [
+            'connect-src',
+            sources(SELF, origins.api, issuer, origins.analytics, origins.suiteHub, ...(origins.vendorConnect ?? [])),
+        ],
+        ['frame-src', issuer === undefined ? [NONE] : [issuer]],
+        ['worker-src', [SELF]],
+        ['manifest-src', [SELF]],
+        ['object-src', [NONE]],
+        ['base-uri', [NONE]],
+        ['form-action', sources(SELF, issuer)],
+        ['frame-ancestors', [NONE]],
+    ];
+}
+function serialize(entries, upgrade) {
+    const parts = entries.map(([name, values]) => `${name} ${values.join(' ')}`);
+    return (upgrade ? [...parts, 'upgrade-insecure-requests'] : parts).join('; ');
+}
+/**
+ * The production policy. `upgrade-insecure-requests` is left out only when an
+ * origin is plain `http:`, which happens for local builds against localhost.
+ */
+export function contentSecurityPolicy(options) {
+    for (const hash of options.scriptHashes) {
+        if (!HASH_SOURCE.test(hash)) {
+            throw new Error(`not a CSP hash source: ${hash}`);
+        }
+    }
+    return serialize(directives(options), !usesPlainHttp(options.origins));
+}
+/**
+ * The dev server variant: inline styles and the HMR websocket. Never served
+ * for a production build.
+ */
+export function developmentContentSecurityPolicy(options, hmrOrigins) {
+    const entries = directives({ ...options, styles: 'runtime-injected' }).map(([name, values]) => name === 'connect-src' ? [name, sources(...values, ...hmrOrigins)] : [name, values]);
+    return serialize(entries, false);
+}
+/** Inline scripts whose hash the policy's `script-src` lacks, as CSP hash sources. */
+export function unhashedInlineScripts(html, policy, hash) {
+    const scriptSrc = policy
+        .split(';')
+        .map((directive) => directive.trim().split(/\s+/u))
+        .find(([name]) => name === 'script-src');
+    const allowed = new Set(scriptSrc?.slice(1) ?? []);
+    return inlineScripts(html)
+        .map((script) => hashSource(hash(script)))
+        .filter((source) => !allowed.has(source));
+}
+/** Decodes Clerk's frontend API host from a publishable key (`pk_<env>_<base64 host$>`). */
+export function clerkFrontendApiOrigin(publishableKey) {
+    const encoded = publishableKey?.split('_')[2];
+    if (encoded === undefined || encoded === '') {
+        return undefined;
+    }
+    const host = atob(encoded).replace(/\$$/u, '');
+    return originOf(`https://${host}`);
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@baukit/csp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.19.0",
+  "description": "Content Security Policy builder and security headers for Baukit web builds.",
+  "license": "MIT",
+  "author": "Patrick Koss",
+  "homepage": "https://github.com/PatrickKoss/baukit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PatrickKoss/baukit.git",
+    "directory": "typescript/packages/csp"
+  },
+  "bugs": {
+    "url": "https://github.com/PatrickKoss/baukit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "pnpm run build",
+    "test": "tsc -p tsconfig.test.json && vitest run --config ../../vitest.config.ts && node ../../scripts/test-packed-exports.mjs",
+    "lint": "eslint . --max-warnings=0",
+    "format:check": "prettier --check src package.json tsconfig.json tsconfig.test.json README.md"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5"
+  }
+}

package/src/headers.ts

@@ -0,0 +1,10 @@
+/**
+ * Response headers every page of a built web app carries next to its policy.
+ * COEP stays unset: `require-corp` blocks third-party images and analytics
+ * that do not send CORP themselves.
+ */
+export const SECURITY_HEADERS: Readonly<Record<string, string>> = {
+  'Cross-Origin-Opener-Policy': 'same-origin',
+  'Cross-Origin-Resource-Policy': 'same-origin',
+  'X-Content-Type-Options': 'nosniff',
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+export { SECURITY_HEADERS } from './headers.js';
+export {
+  clerkFrontendApiOrigin,
+  contentSecurityPolicy,
+  developmentContentSecurityPolicy,
+  hashSource,
+  inlineScripts,
+  originOf,
+  unhashedInlineScripts,
+  type PolicyOptions,
+  type PolicyOrigins,
+  type StyleSources,
+} from './policy.js';

package/src/policy.test.ts

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  clerkFrontendApiOrigin,
+  contentSecurityPolicy,
+  developmentContentSecurityPolicy,
+  hashSource,
+  inlineScripts,
+  originOf,
+  SECURITY_HEADERS,
+  unhashedInlineScripts,
+} from './index.js';
+
+const origins = {
+  api: 'https://api.example.test',
+  issuer: 'https://login.example.test',
+  analytics: 'https://eu.posthog.example.test',
+};
+
+function sha256Base64(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('base64');
+}
+
+function directive(policy: string, name: string): string[] | undefined {
+  return policy
+    .split(';')
+    .map((part) => part.trim().split(' '))
+    .find(([directiveName]) => directiveName === name)
+    ?.slice(1);
+}
+
+describe('content security policy', () => {
+  it('locks scripts and styles to the app origin for file-based CSS', () => {
+    const policy = contentSecurityPolicy({ styles: 'files', origins, scriptHashes: [] });
+
+    expect(directive(policy, 'script-src')).toEqual(["'self'"]);
+    expect(directive(policy, 'style-src')).toEqual(["'self'"]);
+    expect(directive(policy, 'connect-src')).toEqual([
+      "'self'",
+      'https://api.example.test',
+      'https://login.example.test',
+      'https://eu.posthog.example.test',
+    ]);
+    expect(directive(policy, 'frame-src')).toEqual(['https://login.example.test']);
+    expect(directive(policy, 'form-action')).toEqual(["'self'", 'https://login.example.test']);
+    expect(directive(policy, 'object-src')).toEqual(["'none'"]);
+    expect(directive(policy, 'base-uri')).toEqual(["'none'"]);
+    expect(directive(policy, 'frame-ancestors')).toEqual(["'none'"]);
+    expect(policy).toContain('upgrade-insecure-requests');
+    expect(policy).not.toContain('unsafe-inline');
+    expect(policy).not.toContain('unsafe-eval');
+  });
+
+  it('allows inline styles but never inline scripts for runtime-injected CSS', () => {
+    const policy = contentSecurityPolicy({
+      styles: 'runtime-injected',
+      origins: { api: 'https://api.example.test', media: 'https://media.example.test' },
+      scriptHashes: [hashSource('Ym9vdA==')],
+    });
+
+    expect(directive(policy, 'style-src')).toEqual(["'self'", "'unsafe-inline'"]);
+    expect(directive(policy, 'script-src')).toEqual(["'self'", "'sha256-Ym9vdA=='"]);
+    expect(directive(policy, 'img-src')).toContain('https://media.example.test');
+    expect(directive(policy, 'frame-src')).toEqual(["'none'"]);
+  });
+
+  it('rejects anything but hash sources for scripts', () => {
+    expect(() => hashSource('not base64!')).toThrow(/SHA-256/u);
+    expect(() =>
+      contentSecurityPolicy({ styles: 'files', origins, scriptHashes: ["'unsafe-inline'"] }),
+    ).toThrow(/not a CSP hash source/u);
+  });
+
+  it('deduplicates origins configured twice', () => {
+    const policy = contentSecurityPolicy({
+      styles: 'files',
+      origins: { api: 'https://same.example.test', issuer: 'https://same.example.test' },
+      scriptHashes: [],
+    });
+
+    expect(directive(policy, 'connect-src')).toEqual(["'self'", 'https://same.example.test']);
+  });
+
+  it('omits upgrade-insecure-requests only for plain http origins', () => {
+    const local = contentSecurityPolicy({
+      styles: 'files',
+      origins: { vendorImages: ['http://localhost:9000'] },
+      scriptHashes: [],
+    });
+
+    expect(local).not.toContain('upgrade-insecure-requests');
+    expect(directive(local, 'frame-src')).toEqual(["'none'"]);
+  });
+
+  it('relaxes only the dev variant for styles and the HMR socket', () => {
+    const policy = developmentContentSecurityPolicy(
+      { styles: 'files', origins, scriptHashes: [] },
+      ['ws://localhost:5173'],
+    );
+
+    expect(directive(policy, 'style-src')).toEqual(["'self'", "'unsafe-inline'"]);
+    expect(directive(policy, 'connect-src')).toContain('ws://localhost:5173');
+    expect(directive(policy, 'script-src')).toEqual(["'self'"]);
+    expect(policy).not.toContain('upgrade-insecure-requests');
+  });
+});
+
+describe('inline script hashes', () => {
+  const html =
+    '<script type="module" src="/assets/index.js"></script><script>boot()</script><script type="importmap">{}</script>';
+
+  it('finds inline scripts and skips external ones', () => {
+    expect(inlineScripts(html)).toEqual(['boot()', '{}']);
+  });
+
+  it('reports every inline script the policy does not hash', () => {
+    const policy = contentSecurityPolicy({
+      styles: 'files',
+      origins,
+      scriptHashes: [hashSource(sha256Base64('boot()'))],
+    });
+
+    expect(unhashedInlineScripts(html, policy, sha256Base64)).toEqual([
+      `'sha256-${sha256Base64('{}')}'`,
+    ]);
+  });
+});
+
+describe('origins', () => {
+  it('reduces URLs and bare hosts to origins', () => {
+    expect(originOf('https://api.example.test/v1/')).toBe('https://api.example.test');
+    expect(originOf('eu.posthog.example.test')).toBe('https://eu.posthog.example.test');
+    expect(originOf('  ')).toBeUndefined();
+    expect(originOf(undefined)).toBeUndefined();
+  });
+
+  it('decodes the Clerk frontend API host from a publishable key', () => {
+    const key = `pk_test_${btoa('clerk.example.test$')}`;
+
+    expect(clerkFrontendApiOrigin(key)).toBe('https://clerk.example.test');
+    expect(clerkFrontendApiOrigin('')).toBeUndefined();
+    expect(clerkFrontendApiOrigin(undefined)).toBeUndefined();
+  });
+});
+
+describe('security headers', () => {
+  it('isolates the opener and resources without requiring CORP from subresources', () => {
+    expect(SECURITY_HEADERS).toEqual({
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Resource-Policy': 'same-origin',
+      'X-Content-Type-Options': 'nosniff',
+    });
+    expect(Object.keys(SECURITY_HEADERS)).not.toContain('Cross-Origin-Embedder-Policy');
+  });
+});

package/src/policy.ts

@@ -0,0 +1,162 @@
+/**
+ * Content Security Policy for a built web app (ADR 0006 section 7). Pure, so
+ * build plugins, build checks and tests share one definition.
+ */
+
+/** `files`: CSS ships as files. `runtime-injected`: the UI library writes `<style>` at runtime. */
+export type StyleSources = 'files' | 'runtime-injected';
+
+export interface PolicyOrigins {
+  readonly api?: string | undefined;
+  readonly issuer?: string | undefined;
+  readonly analytics?: string | undefined;
+  readonly media?: string | undefined;
+  readonly suiteHub?: string | undefined;
+  readonly vendorConnect?: readonly string[];
+  readonly vendorImages?: readonly string[];
+}
+
+export interface PolicyOptions {
+  readonly styles: StyleSources;
+  readonly origins: PolicyOrigins;
+  /** `'sha256-...'` sources for every inline `<script>` the build emits. */
+  readonly scriptHashes: readonly string[];
+}
+
+const SELF = "'self'";
+const NONE = "'none'";
+const INLINE = "'unsafe-inline'";
+const INLINE_SCRIPT = /<script\b(?![^>]*\bsrc\s*=)[^>]*>([\s\S]*?)<\/script\s*>/giu;
+const HASH_SOURCE = /^'sha256-[A-Za-z0-9+/]+={0,2}'$/u;
+
+/** Returns the origin of a configured URL, or `undefined` when it is unset. */
+export function originOf(value: string | undefined): string | undefined {
+  if (value === undefined || value.trim() === '') {
+    return undefined;
+  }
+  const url = new URL(value.includes('://') ? value : `https://${value}`);
+  return url.origin;
+}
+
+/** The text of every inline script, in document order. */
+export function inlineScripts(html: string): string[] {
+  return [...html.matchAll(INLINE_SCRIPT)].map((match) => match[1] ?? '');
+}
+
+/** Formats a base64 SHA-256 digest as a CSP source. */
+export function hashSource(base64Digest: string): string {
+  const source = `'sha256-${base64Digest}'`;
+  if (!HASH_SOURCE.test(source)) {
+    throw new Error(`not a base64 SHA-256 digest: ${base64Digest}`);
+  }
+  return source;
+}
+
+function sources(...values: readonly (string | undefined)[]): string[] {
+  return [...new Set(values.filter((value): value is string => value !== undefined))];
+}
+
+function originList(origins: PolicyOrigins): (string | undefined)[] {
+  return [
+    origins.api,
+    origins.issuer,
+    origins.analytics,
+    origins.media,
+    origins.suiteHub,
+    ...(origins.vendorConnect ?? []),
+    ...(origins.vendorImages ?? []),
+  ];
+}
+
+function usesPlainHttp(origins: PolicyOrigins): boolean {
+  return originList(origins).some((origin) => origin?.startsWith('http:') === true);
+}
+
+function directives(options: PolicyOptions): [string, string[]][] {
+  const { origins } = options;
+  const issuer = origins.issuer;
+  return [
+    ['default-src', [SELF]],
+    ['script-src', sources(SELF, ...options.scriptHashes)],
+    ['style-src', options.styles === 'files' ? [SELF] : [SELF, INLINE]],
+    ['img-src', sources(SELF, 'data:', 'blob:', origins.media, ...(origins.vendorImages ?? []))],
+    ['media-src', sources(SELF, 'blob:', origins.media)],
+    [
+      'connect-src',
+      sources(
+        SELF,
+        origins.api,
+        issuer,
+        origins.analytics,
+        origins.suiteHub,
+        ...(origins.vendorConnect ?? []),
+      ),
+    ],
+    ['frame-src', issuer === undefined ? [NONE] : [issuer]],
+    ['worker-src', [SELF]],
+    ['manifest-src', [SELF]],
+    ['object-src', [NONE]],
+    ['base-uri', [NONE]],
+    ['form-action', sources(SELF, issuer)],
+    ['frame-ancestors', [NONE]],
+  ];
+}
+
+function serialize(entries: readonly [string, readonly string[]][], upgrade: boolean): string {
+  const parts = entries.map(([name, values]) => `${name} ${values.join(' ')}`);
+  return (upgrade ? [...parts, 'upgrade-insecure-requests'] : parts).join('; ');
+}
+
+/**
+ * The production policy. `upgrade-insecure-requests` is left out only when an
+ * origin is plain `http:`, which happens for local builds against localhost.
+ */
+export function contentSecurityPolicy(options: PolicyOptions): string {
+  for (const hash of options.scriptHashes) {
+    if (!HASH_SOURCE.test(hash)) {
+      throw new Error(`not a CSP hash source: ${hash}`);
+    }
+  }
+  return serialize(directives(options), !usesPlainHttp(options.origins));
+}
+
+/**
+ * The dev server variant: inline styles and the HMR websocket. Never served
+ * for a production build.
+ */
+export function developmentContentSecurityPolicy(
+  options: PolicyOptions,
+  hmrOrigins: readonly string[],
+): string {
+  const entries = directives({ ...options, styles: 'runtime-injected' }).map(
+    ([name, values]): [string, string[]] =>
+      name === 'connect-src' ? [name, sources(...values, ...hmrOrigins)] : [name, values],
+  );
+  return serialize(entries, false);
+}
+
+/** Inline scripts whose hash the policy's `script-src` lacks, as CSP hash sources. */
+export function unhashedInlineScripts(
+  html: string,
+  policy: string,
+  hash: (script: string) => string,
+): string[] {
+  const scriptSrc = policy
+    .split(';')
+    .map((directive) => directive.trim().split(/\s+/u))
+    .find(([name]) => name === 'script-src');
+  const allowed = new Set(scriptSrc?.slice(1) ?? []);
+  return inlineScripts(html)
+    .map((script) => hashSource(hash(script)))
+    .filter((source) => !allowed.has(source));
+}
+
+/** Decodes Clerk's frontend API host from a publishable key (`pk_<env>_<base64 host$>`). */
+export function clerkFrontendApiOrigin(publishableKey: string | undefined): string | undefined {
+  const encoded = publishableKey?.split('_')[2];
+  if (encoded === undefined || encoded === '') {
+    return undefined;
+  }
+  const host = atob(encoded).replace(/\$$/u, '');
+  return originOf(`https://${host}`);
+}

package/src/vectors.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { contentSecurityPolicy, developmentContentSecurityPolicy } from './index.js';
+
+const everyOrigin = {
+  api: 'https://api.example.test',
+  issuer: 'https://login.example.test',
+  analytics: 'https://eu.posthog.example.test',
+  media: 'https://media.example.test',
+  suiteHub: 'https://hub.example.test',
+  vendorConnect: ['https://clerk.example.test'],
+  vendorImages: ['https://img.clerk.com'],
+};
+const bootHash = ["'sha256-Ym9vdA=='"];
+
+// Output of the template copies of policy.ts before they moved into this package.
+describe('policy vectors', () => {
+  it('keeps the production policy with every origin byte-equal', () => {
+    expect(
+      contentSecurityPolicy({ styles: 'files', origins: everyOrigin, scriptHashes: bootHash }),
+    ).toBe(
+      "default-src 'self'; script-src 'self' 'sha256-Ym9vdA=='; style-src 'self'; img-src 'self' data: blob: https://media.example.test https://img.clerk.com; media-src 'self' blob: https://media.example.test; connect-src 'self' https://api.example.test https://login.example.test https://eu.posthog.example.test https://hub.example.test https://clerk.example.test; frame-src https://login.example.test; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self' https://login.example.test; frame-ancestors 'none'; upgrade-insecure-requests",
+    );
+  });
+
+  it('keeps the local http policy with runtime-injected styles byte-equal', () => {
+    expect(
+      contentSecurityPolicy({
+        styles: 'runtime-injected',
+        origins: { api: 'http://localhost:8080', issuer: 'http://localhost:8081' },
+        scriptHashes: [],
+      }),
+    ).toBe(
+      "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src 'self' blob:; connect-src 'self' http://localhost:8080 http://localhost:8081; frame-src http://localhost:8081; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self' http://localhost:8081; frame-ancestors 'none'",
+    );
+  });
+
+  it('keeps the policy without origins byte-equal', () => {
+    expect(contentSecurityPolicy({ styles: 'files', origins: {}, scriptHashes: [] })).toBe(
+      "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; media-src 'self' blob:; connect-src 'self'; frame-src 'none'; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests",
+    );
+  });
+
+  it('keeps the development policy byte-equal', () => {
+    expect(
+      developmentContentSecurityPolicy(
+        { styles: 'files', origins: everyOrigin, scriptHashes: bootHash },
+        ['ws://localhost:5173', 'ws://127.0.0.1:5173'],
+      ),
+    ).toBe(
+      "default-src 'self'; script-src 'self' 'sha256-Ym9vdA=='; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://media.example.test https://img.clerk.com; media-src 'self' blob: https://media.example.test; connect-src 'self' https://api.example.test https://login.example.test https://eu.posthog.example.test https://hub.example.test https://clerk.example.test ws://localhost:5173 ws://127.0.0.1:5173; frame-src https://login.example.test; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self' https://login.example.test; frame-ancestors 'none'",
+    );
+  });
+});