@oxyhq/core 12.11.1 → 13.2.0

package/src/server/__tests__/securityHeaders.test.ts

@@ -0,0 +1,244 @@
+import type { NextFunction, Request, Response } from 'express';
+import {
+  buildOxyCspDirectives,
+  buildOxyPagesHeaders,
+  createOxySecurityHeaders,
+  formatOxyCspPolicy,
+  OXY_CSP_BASELINE,
+  type OxyCspExtensions,
+} from '../securityHeaders';
+
+const CLOUDFLARE_SCRIPT_HOST = 'https://static.cloudflareinsights.com';
+const CLOUDFLARE_REPORT_HOST = 'https://cloudflareinsights.com';
+
+/** Run the middleware and return the CSP header exactly as a browser would see it. */
+function renderPolicy(options: Parameters<typeof createOxySecurityHeaders>[0]): string {
+  const headers: Record<string, string> = {};
+  const res = {
+    setHeader: (name: string, value: string | number | readonly string[]): void => {
+      headers[name] = String(value);
+    },
+    removeHeader: (): void => undefined,
+  } as unknown as Response;
+  const req = { method: 'GET', headers: {} } as unknown as Request;
+  const next = jest.fn() as unknown as NextFunction;
+
+  createOxySecurityHeaders(options)(req, res, next);
+  return headers['Content-Security-Policy'] ?? '';
+}
+
+/** The sources of one directive, parsed back out of the rendered header. */
+function policySources(policy: string, directive: string): string[] {
+  const found = policy
+    .split(';')
+    .map((segment) => segment.trim())
+    .find((segment) => segment === directive || segment.startsWith(`${directive} `));
+  if (found === undefined) return [];
+  return found.split(/\s+/).slice(1);
+}
+
+describe('@oxyhq/core/server buildOxyCspDirectives', () => {
+  it('carries the Cloudflare Insights beacon on BOTH halves of the baseline', () => {
+    // The bug this helper exists for: the script host alone leaves the beacon
+    // loading but unable to report, which looks fixed and is not.
+    const directives = buildOxyCspDirectives();
+    expect(directives['script-src']).toContain(CLOUDFLARE_SCRIPT_HOST);
+    expect(directives['connect-src']).toContain(CLOUDFLARE_REPORT_HOST);
+  });
+
+  it('carries the Oxy platform origins every app reaches through the SDK', () => {
+    const directives = buildOxyCspDirectives();
+    expect(directives['connect-src']).toEqual(
+      expect.arrayContaining(['https://api.oxy.so', 'wss://api.oxy.so', 'https://cloud.oxy.so']),
+    );
+    expect(directives['img-src']).toContain('https://cloud.oxy.so');
+    expect(directives['media-src']).toContain('https://cloud.oxy.so');
+  });
+
+  it('emits the hardening floor: closed object-src/script-src-attr and upgrade-insecure-requests', () => {
+    const directives = buildOxyCspDirectives();
+    expect(directives['object-src']).toEqual(["'none'"]);
+    expect(directives['script-src-attr']).toEqual(["'none'"]);
+    expect(directives['frame-ancestors']).toEqual(["'none'"]);
+    expect(directives['upgrade-insecure-requests']).toEqual([]);
+  });
+
+  it('MERGES an extension into the baseline instead of replacing it', () => {
+    const directives = buildOxyCspDirectives({
+      scriptSrc: ['https://app.example.com'],
+      connectSrc: ['wss://api.example.com'],
+    });
+
+    // The extension is present…
+    expect(directives['script-src']).toContain('https://app.example.com');
+    expect(directives['connect-src']).toContain('wss://api.example.com');
+    // …and every baseline source SURVIVED it.
+    for (const source of OXY_CSP_BASELINE.scriptSrc ?? []) {
+      expect(directives['script-src']).toContain(source);
+    }
+    for (const source of OXY_CSP_BASELINE.connectSrc ?? []) {
+      expect(directives['connect-src']).toContain(source);
+    }
+  });
+
+  it("retains 'self' in every extended directive, including directives absent from the baseline", () => {
+    // The footgun: an explicit `script-src` replaces helmet's default and drops
+    // `'self'`, so the app's own bundle stops loading.
+    const extensions: OxyCspExtensions = {
+      scriptSrc: ['https://app.example.com'],
+      connectSrc: ['https://api.example.com'],
+      imgSrc: ['blob:'],
+      mediaSrc: ['blob:'],
+      styleSrc: ['https://fonts.example.com'],
+      fontSrc: ['https://fonts.example.com'],
+      // Not in the baseline at all — must still be seeded with 'self'.
+      frameSrc: ['https://player.vimeo.com'],
+      workerSrc: ['blob:'],
+      manifestSrc: ['https://cdn.example.com'],
+      scriptSrcElem: ['https://app.example.com'],
+      styleSrcElem: ['https://cdn.example.com'],
+    };
+    const directives = buildOxyCspDirectives(extensions);
+
+    for (const directive of Object.keys(extensions)) {
+      const headerName = directive.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+      expect(directives[headerName]).toContain("'self'");
+    }
+  });
+
+  it('dedupes sources a caller repeats or that already exist in the baseline', () => {
+    const directives = buildOxyCspDirectives({
+      scriptSrc: ["'self'", CLOUDFLARE_SCRIPT_HOST, 'https://app.example.com'],
+      frameSrc: ["'self'", 'https://player.vimeo.com', 'https://player.vimeo.com'],
+    });
+
+    expect(directives['script-src']).toEqual([
+      "'self'",
+      CLOUDFLARE_SCRIPT_HOST,
+      'https://app.example.com',
+    ]);
+    expect(directives['frame-src']).toEqual(["'self'", 'https://player.vimeo.com']);
+  });
+
+  it("drops the 'none' sentinel when a closed directive is opened, and keeps it otherwise", () => {
+    // 'none' alongside any other source is meaningless per the CSP spec, so an
+    // app that must be framable opts back in explicitly.
+    expect(buildOxyCspDirectives({ frameAncestors: ["'self'"] })['frame-ancestors']).toEqual([
+      "'self'",
+    ]);
+    expect(buildOxyCspDirectives({ objectSrc: [] })['object-src']).toEqual(["'none'"]);
+  });
+
+  it('rejects sources that would terminate the directive or the policy', () => {
+    expect(() => buildOxyCspDirectives({ scriptSrc: ["https://a.example.com; script-src 'unsafe-inline'"] })).toThrow(
+      /script-src/,
+    );
+    expect(() => buildOxyCspDirectives({ connectSrc: ['https://a.example.com,https://b.example.com'] })).toThrow(
+      /connect-src/,
+    );
+    expect(() => buildOxyCspDirectives({ imgSrc: [''] })).toThrow(/img-src/);
+  });
+
+  it('never mutates the exported baseline across calls', () => {
+    const before = [...(OXY_CSP_BASELINE.scriptSrc ?? [])];
+    buildOxyCspDirectives({ scriptSrc: ['https://app.example.com'] });
+    buildOxyCspDirectives({ scriptSrc: ['https://other.example.com'] });
+    expect([...(OXY_CSP_BASELINE.scriptSrc ?? [])]).toEqual(before);
+    expect(buildOxyCspDirectives()['script-src']).toEqual(before);
+  });
+});
+
+describe('@oxyhq/core/server formatOxyCspPolicy', () => {
+  it('serializes directives into a single CSP header value', () => {
+    const policy = formatOxyCspPolicy(buildOxyCspDirectives());
+    expect(policy).toContain("script-src 'self' https://static.cloudflareinsights.com");
+    expect(policy).toContain('upgrade-insecure-requests');
+    expect(policy.endsWith('upgrade-insecure-requests')).toBe(true);
+  });
+});
+
+describe('@oxyhq/core/server buildOxyPagesHeaders', () => {
+  it('emits a Cloudflare Pages _headers block with CSP and hardening headers', () => {
+    const block = buildOxyPagesHeaders();
+    expect(block.startsWith('/*\n')).toBe(true);
+    expect(block).toContain('Content-Security-Policy:');
+    expect(block).toContain(CLOUDFLARE_SCRIPT_HOST);
+    expect(block).toContain(CLOUDFLARE_REPORT_HOST);
+    expect(block).toContain('X-Frame-Options: DENY');
+    expect(block).toContain('Strict-Transport-Security:');
+  });
+
+  it('merges per-app CSP extensions into the deployed header', () => {
+    const block = buildOxyPagesHeaders({
+      csp: { workerSrc: ["'self'"], imgSrc: ['blob:', 'https:'] },
+    });
+    expect(block).toContain("worker-src 'self'");
+    expect(block).toContain('blob:');
+    expect(block).toContain('https:');
+    expect(block).toContain(CLOUDFLARE_SCRIPT_HOST);
+  });
+});
+
+describe('@oxyhq/core/server createOxySecurityHeaders', () => {
+  it('sends the resolved baseline as a real Content-Security-Policy header', () => {
+    const policy = renderPolicy({});
+
+    expect(policySources(policy, 'script-src')).toEqual(["'self'", CLOUDFLARE_SCRIPT_HOST]);
+    expect(policySources(policy, 'connect-src')).toEqual([
+      "'self'",
+      CLOUDFLARE_REPORT_HOST,
+      'https://api.oxy.so',
+      'wss://api.oxy.so',
+      'https://cloud.oxy.so',
+    ]);
+    expect(policy).toContain('upgrade-insecure-requests');
+  });
+
+  it('sends merged app extensions without losing the baseline', () => {
+    const policy = renderPolicy({
+      csp: {
+        connectSrc: ['https://api.mention.earth', 'wss://api.mention.earth'],
+        frameSrc: ['https://www.youtube-nocookie.com'],
+      },
+    });
+
+    expect(policySources(policy, 'connect-src')).toEqual([
+      "'self'",
+      CLOUDFLARE_REPORT_HOST,
+      'https://api.oxy.so',
+      'wss://api.oxy.so',
+      'https://cloud.oxy.so',
+      'https://api.mention.earth',
+      'wss://api.mention.earth',
+    ]);
+    expect(policySources(policy, 'frame-src')).toEqual([
+      "'self'",
+      'https://www.youtube-nocookie.com',
+    ]);
+  });
+
+  it('passes non-CSP helmet options through and calls next()', () => {
+    const headers: Record<string, string> = {};
+    const res = {
+      setHeader: (name: string, value: string | number | readonly string[]): void => {
+        headers[name] = String(value);
+      },
+      removeHeader: (): void => undefined,
+    } as unknown as Response;
+    const next = jest.fn() as unknown as NextFunction & jest.Mock;
+
+    createOxySecurityHeaders({
+      helmet: {
+        crossOriginResourcePolicy: { policy: 'cross-origin' },
+        frameguard: { action: 'deny' },
+        referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+      },
+    })({ method: 'GET', headers: {} } as unknown as Request, res, next);
+
+    expect(headers['Cross-Origin-Resource-Policy']).toBe('cross-origin');
+    expect(headers['X-Frame-Options']).toBe('DENY');
+    expect(headers['Referrer-Policy']).toBe('strict-origin-when-cross-origin');
+    expect(headers['Content-Security-Policy']).toContain("script-src 'self'");
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/server/index.ts

@@ -63,6 +63,22 @@ export type {
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 
+// Shared Helmet + Content-Security-Policy baseline (Cloudflare Insights beacon,
+// Oxy API/CDN origins) with additive, per-app extensions.
+export {
+  buildOxyCspDirectives,
+  buildOxyPagesHeaders,
+  createOxySecurityHeaders,
+  formatOxyCspPolicy,
+  OXY_CSP_BASELINE,
+} from './securityHeaders';
+export type {
+  OxyCspDirective,
+  OxyCspExtensions,
+  OxyPagesHeadersOptions,
+  OxySecurityHeadersOptions,
+} from './securityHeaders';
+
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret';
 
@@ -71,11 +87,4 @@ export { verifySecret } from './verifySecret';
 // Pure host handling (no browser deps), so it is safe on the server subpath and
 // lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex';
-export {
-  buildIdpHubOrigin,
-  buildHubSyncUrl,
-  isIdpHubOrigin,
-  isOfficialWebOrigin,
-  normalizeOfficialReturnOrigin,
-  parseHubSyncReturnUrl,
-} from '../utils/officialOrigins';
+export { isOfficialWebOrigin } from '../utils/officialOrigins';

package/src/server/rateLimit.ts

@@ -278,6 +278,9 @@ export function createOxyRateLimit(
     standardHeaders: true,
     legacyHeaders: false,
     skip,
+    // hashAnonymousIp already buckets IPv6 to /56 before HMAC; disable the v8
+    // static source scan that false-positives on req.ip (ERR_ERL_KEY_GEN_IPV6).
+    validate: { keyGeneratorIpFallback: false },
   });
 
   return (req, res, next) => {

package/src/server/securityHeaders.ts

@@ -0,0 +1,304 @@
+/**
+ * Shared security headers (Helmet + Content-Security-Policy) for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A CSP only governs an origin that serves DOCUMENTS; on a JSON API it governs
+ * no browsing context. The Oxy origins that serve HTML through Cloudflare have
+ * so far either hand-written their own policy or shipped none at all, and two
+ * bugs follow from that:
+ *
+ *  1. THE CLOUDFLARE INSIGHTS BEACON IS BLOCKED BY A HAND-WRITTEN POLICY.
+ *     Cloudflare injects `<script src="https://static.cloudflareinsights.com/
+ *     beacon.min.js/...">` into HTML it proxies. No application code loads it,
+ *     so it cannot be allowlisted from the app side any other way, and an
+ *     origin whose policy says `script-src 'self'` logs
+ *     `Loading the script 'https://static.cloudflareinsights.com/beacon.min.js'
+ *     violates the following Content Security Policy directive: "script-src
+ *     'self'"` and collects nothing. The beacon needs BOTH hosts, and they are
+ *     different halves of the same feature: `static.cloudflareinsights.com`
+ *     serves the script (`script-src`), `cloudflareinsights.com` receives the
+ *     measurements (`connect-src`). Allowing only the script leaves the beacon
+ *     loading but unable to report, which looks fixed and is not. Verified in
+ *     production 2026-07-29: `mention.earth` serves HTML behind Cloudflare with
+ *     the beacon injected and `script-src 'self'` — blocked; `oxy.so` had
+ *     already allowlisted the same two hosts in its own static `_headers`,
+ *     independently, which is the divergence this baseline exists to end.
+ *
+ *  2. AN EXPLICIT DIRECTIVE SILENTLY REPLACES HELMET'S DEFAULT.
+ *     Writing `scriptSrc: ['https://example.com']` drops `'self'` — the page's
+ *     own bundle stops loading (or, worse, only some lazily-loaded chunk does,
+ *     so it ships). This helper makes that structurally impossible: callers can
+ *     only ADD sources to the Oxy baseline, never replace a directive, and they
+ *     cannot pass their own `contentSecurityPolicy` through to Helmet at all
+ *     (the option is typed `never`).
+ *
+ * WHAT IT PROVIDES
+ * ----------------
+ * `createOxySecurityHeaders(options)` returns the Helmet middleware with the
+ * Oxy-wide CSP baseline applied, plus per-app extensions merged (and deduped)
+ * into it. Everything Helmet does that is NOT the CSP (HSTS, frameguard,
+ * referrer policy, CORP/COOP, …) is passed straight through, so an app keeps
+ * full control of those.
+ *
+ * `buildOxyCspDirectives(extensions)` is the same resolution as a pure
+ * function, for the Oxy document origins that are NOT Express — a Next.js
+ * `headers()`, a Cloudflare Pages `_headers` generator — so one policy can
+ * cover them without a second implementation.
+ *
+ * SCOPE: mount this on backends that serve HTML. A JSON-only API gains nothing
+ * from a source-list CSP; harden those with the non-CSP headers instead
+ * (`hsts`, `noSniff`, `frameguard`, CORP) rather than adding directives that
+ * apply to no document.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+
+import type { RequestHandler } from 'express';
+import helmet, { type HelmetOptions } from 'helmet';
+
+/** CSP keyword for "this origin". Always present in every open baseline directive. */
+const SELF = "'self'";
+
+/** CSP keyword for a fully closed directive. Meaningless alongside any other source. */
+const NONE = "'none'";
+
+/**
+ * Cloudflare Web Analytics. Injected at the edge into proxied HTML — no Oxy app
+ * loads it, and no Oxy app should have to know these hostnames. Both are
+ * required: the script host, and the host the beacon reports to.
+ */
+const CLOUDFLARE_INSIGHTS_SCRIPT_ORIGIN = 'https://static.cloudflareinsights.com';
+const CLOUDFLARE_INSIGHTS_REPORT_ORIGIN = 'https://cloudflareinsights.com';
+
+/**
+ * Oxy platform origins. Every Oxy web origin runs the SDK, which calls the Oxy
+ * API over HTTPS and Socket.IO, and resolves all canonical media through the
+ * Oxy CDN (`getFileDownloadUrl` → `cloud.oxy.so`).
+ */
+const OXY_API_ORIGIN = 'https://api.oxy.so';
+const OXY_API_WEBSOCKET_ORIGIN = 'wss://api.oxy.so';
+const OXY_CDN_ORIGIN = 'https://cloud.oxy.so';
+
+/** The CSP directives an Oxy app may extend, in Helmet's camelCase spelling. */
+export type OxyCspDirective =
+  | 'baseUri'
+  | 'connectSrc'
+  | 'defaultSrc'
+  | 'fontSrc'
+  | 'formAction'
+  | 'frameAncestors'
+  | 'frameSrc'
+  | 'imgSrc'
+  | 'manifestSrc'
+  | 'mediaSrc'
+  | 'objectSrc'
+  | 'scriptSrc'
+  | 'scriptSrcAttr'
+  | 'scriptSrcElem'
+  | 'styleSrc'
+  | 'styleSrcElem'
+  | 'workerSrc';
+
+/**
+ * Per-app ADDITIONS to the Oxy baseline, keyed by directive. Values are merged
+ * into the baseline and deduped — they never replace it, so `'self'` (and the
+ * Cloudflare beacon hosts) cannot be lost. Extending a directive the baseline
+ * does not define seeds it with `'self'` first, for the same reason.
+ */
+export type OxyCspExtensions = Partial<Record<OxyCspDirective, readonly string[]>>;
+
+/**
+ * The Oxy-wide CSP baseline. Deliberately the floor every Oxy origin needs, not
+ * a superset of what any one app allows — permissive sources an individual app
+ * wants (`https:` images, `blob:` media, embed hosts, LiveKit) are that app's
+ * extension, so each widening stays visible at its call site.
+ *
+ * `style-src` carries `'unsafe-inline'` because react-native-web injects its
+ * stylesheet as inline `<style>` at runtime; without it every Oxy web app
+ * renders unstyled.
+ */
+export const OXY_CSP_BASELINE: Readonly<Partial<Record<OxyCspDirective, readonly string[]>>> =
+  Object.freeze({
+    defaultSrc: Object.freeze([SELF]),
+    baseUri: Object.freeze([SELF]),
+    formAction: Object.freeze([SELF]),
+    frameAncestors: Object.freeze([NONE]),
+    objectSrc: Object.freeze([NONE]),
+    scriptSrc: Object.freeze([SELF, CLOUDFLARE_INSIGHTS_SCRIPT_ORIGIN]),
+    scriptSrcAttr: Object.freeze([NONE]),
+    styleSrc: Object.freeze([SELF, "'unsafe-inline'"]),
+    imgSrc: Object.freeze([SELF, 'data:', OXY_CDN_ORIGIN]),
+    mediaSrc: Object.freeze([SELF, OXY_CDN_ORIGIN]),
+    fontSrc: Object.freeze([SELF, 'data:']),
+    connectSrc: Object.freeze([
+      SELF,
+      CLOUDFLARE_INSIGHTS_REPORT_ORIGIN,
+      OXY_API_ORIGIN,
+      OXY_API_WEBSOCKET_ORIGIN,
+      OXY_CDN_ORIGIN,
+    ]),
+  });
+
+/** `connectSrc` → `connect-src`. Total over `OxyCspDirective` (all are camelCase ASCII). */
+function toHeaderDirectiveName(directive: OxyCspDirective): string {
+  return directive.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+/**
+ * A source containing `;` or `,` would silently terminate the directive (or the
+ * whole policy) and hand the rest of the string to the browser as new
+ * directives. Helmet rejects these too; we reject them here so the pure builder
+ * is equally safe, and so the failure names the offending directive.
+ */
+function assertValidSource(directive: OxyCspDirective, source: string): void {
+  if (typeof source !== 'string' || source.length === 0) {
+    throw new TypeError(`Oxy CSP: ${toHeaderDirectiveName(directive)} received an empty source.`);
+  }
+  if (source.includes(';') || source.includes(',')) {
+    throw new TypeError(
+      `Oxy CSP: ${toHeaderDirectiveName(directive)} source ${JSON.stringify(source)} may not contain ";" or ",".`,
+    );
+  }
+}
+
+/** Order-preserving, first-seen-wins dedupe. */
+function dedupe(sources: readonly string[]): string[] {
+  return [...new Set(sources)];
+}
+
+/**
+ * Resolve the effective CSP directives: the Oxy baseline, with each app
+ * extension merged in and deduped.
+ *
+ * Merge rules:
+ *  - A baseline directive is EXTENDED, never replaced — `'self'` and the
+ *    Cloudflare beacon hosts always survive.
+ *  - A directive absent from the baseline is seeded with `'self'`, so adding
+ *    (say) an embed host to `frame-src` cannot lock the origin out of itself.
+ *  - A directive whose baseline is exactly `'none'` is CLOSED: extending it
+ *    drops the sentinel, because `'none'` alongside any other source is
+ *    meaningless per the CSP spec. This is how an app that must be framable
+ *    opts back in with `frameAncestors: ["'self'"]`.
+ *
+ * @example
+ * ```ts
+ * buildOxyCspDirectives({ frameSrc: ['https://player.vimeo.com'] });
+ * // → { ..., 'frame-src': ["'self'", 'https://player.vimeo.com'], ... }
+ * ```
+ */
+export function buildOxyCspDirectives(extensions: OxyCspExtensions = {}): Record<string, string[]> {
+  const directiveNames = new Set<OxyCspDirective>([
+    ...(Object.keys(OXY_CSP_BASELINE) as OxyCspDirective[]),
+    ...(Object.keys(extensions) as OxyCspDirective[]),
+  ]);
+
+  const resolved: Record<string, string[]> = {};
+
+  for (const directive of directiveNames) {
+    const extras = extensions[directive] ?? [];
+    for (const source of extras) {
+      assertValidSource(directive, source);
+    }
+
+    const baseline = OXY_CSP_BASELINE[directive] ?? [SELF];
+    const isClosed = baseline.length === 1 && baseline[0] === NONE;
+    const merged = isClosed && extras.length > 0 ? extras : [...baseline, ...extras];
+
+    resolved[toHeaderDirectiveName(directive)] = dedupe(merged);
+  }
+
+  // Valueless directive: rewrite stray `http://` subresources to HTTPS rather
+  // than failing them, which matters for federated/user-supplied URLs.
+  resolved['upgrade-insecure-requests'] = [];
+
+  return resolved;
+}
+
+/**
+ * Serialize resolved CSP directives into the single-line header value browsers
+ * and Cloudflare `_headers` expect. Valueless directives (e.g.
+ * `upgrade-insecure-requests`) emit the name alone.
+ */
+export function formatOxyCspPolicy(directives: Record<string, string[]>): string {
+  return Object.entries(directives)
+    .map(([name, sources]) => (sources.length === 0 ? name : `${name} ${sources.join(' ')}`))
+    .join('; ');
+}
+
+export interface OxyPagesHeadersOptions {
+  /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
+  csp?: OxyCspExtensions;
+  /**
+   * Emit `Strict-Transport-Security` (default `true`). Cloudflare Pages serves
+   * HTTPS only, so static deploys should keep this on.
+   */
+  hsts?: boolean;
+}
+
+/**
+ * Build a Cloudflare Pages `_headers` block for an Oxy HTML origin. Uses the
+ * same CSP resolution as {@link createOxySecurityHeaders} plus the non-CSP
+ * hardening headers Helmet would add on an Express HTML backend.
+ */
+export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): string {
+  const csp = formatOxyCspPolicy(buildOxyCspDirectives(options.csp));
+  const lines = [
+    '/*',
+    `  Content-Security-Policy: ${csp}`,
+    '  X-Frame-Options: DENY',
+    '  X-Content-Type-Options: nosniff',
+    '  Referrer-Policy: strict-origin-when-cross-origin',
+  ];
+  if (options.hsts !== false) {
+    lines.push('  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export interface OxySecurityHeadersOptions {
+  /**
+   * Per-app additions to the Oxy CSP baseline. Merged, deduped, never
+   * replacing — see {@link buildOxyCspDirectives}.
+   */
+  csp?: OxyCspExtensions;
+  /**
+   * Everything Helmet does that is not the CSP: `hsts`, `frameguard`,
+   * `referrerPolicy`, `crossOriginResourcePolicy`, … Passed straight through.
+   *
+   * `contentSecurityPolicy` is typed `never` on purpose: the CSP is owned by
+   * this helper so the baseline cannot be replaced (nor the `'self'` guarantee
+   * bypassed) by an app that hands Helmet its own directive block. Extend it
+   * through `csp` instead.
+   */
+  helmet?: HelmetOptions & { contentSecurityPolicy?: never };
+}
+
+/**
+ * Build the shared Oxy security-headers middleware: Helmet with the Oxy CSP
+ * baseline plus this app's extensions.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxySecurityHeaders({
+ *   csp: {
+ *     connectSrc: ['https://api.example.com', 'wss://api.example.com'],
+ *     frameSrc: ['https://player.vimeo.com'],
+ *   },
+ *   helmet: { crossOriginResourcePolicy: { policy: 'cross-origin' } },
+ * }));
+ * ```
+ */
+export function createOxySecurityHeaders(options: OxySecurityHeadersOptions = {}): RequestHandler {
+  const { csp, helmet: helmetOptions } = options;
+  const directives = buildOxyCspDirectives(csp);
+
+  return helmet({
+    ...helmetOptions,
+    // `useDefaults: false`: the baseline above is the whole policy, so what the
+    // browser receives is exactly what `buildOxyCspDirectives` returns — no
+    // silent union with Helmet's defaults that tests would never see.
+    contentSecurityPolicy: { useDefaults: false, directives },
+  });
+}

package/src/session/__tests__/accountDialogController.test.ts

@@ -433,11 +433,9 @@ describe('AccountDialogController — switchTo (uniform switch)', () => {
     expect(commitSession.mock.calls[0][0]).toMatchObject({ sessionId: 'sess-org', accessToken: 'access-org' });
   });
 
-  it('commits a graph switch via the IN-PLACE commitSwitchedSession — never the hub-syncing commitSession', async () => {
-    // PROBLEM 2: an account switch must not run the cross-origin hub-sync
-    // full-page redirect. When both funnels are wired, the mint-switch must use
-    // commitSwitchedSession (in-place) and NEVER commitSession (which may
-    // redirect on an official web origin).
+  it('commits a graph switch via the IN-PLACE commitSwitchedSession — never commitSession', async () => {
+    // An account switch must use commitSwitchedSession (in-place) and NEVER
+    // commitSession when both funnels are wired.
     const oxy = makeOxy();
     const sc = new TestSessionClient(host());
     sc.set(state([{ accountId: 'a1', sessionId: 's1' }], 'a1'));

package/src/session/accountDialogController.ts

@@ -302,21 +302,17 @@ export interface AccountDialogControllerOptions {
    * `SessionClient.registerAndActivate` (registration + activation only — no
    * provider-side durable persist/hydration).
    *
-   * This is the SIGN-IN commit: on an official web origin it may run the
-   * cross-origin hub-sync (a full-page redirect to `auth.oxy.so/sync`) that
-   * bootstraps silent OAuth restore on OTHER origins. A first sign-in on a web
-   * origin legitimately needs that. An account SWITCH does NOT — see
-   * {@link commitSwitchedSession}.
+   * This is the SIGN-IN commit: registers the session into the host's device
+   * set with durable persist + profile hydration. An account SWITCH uses
+   * {@link commitSwitchedSession} instead — see below.
    */
   commitSession?: (session: SessionLoginResponse) => Promise<void>;
   /**
    * Commit a minted graph SWITCH session into the host's session set — same
    * device-first registration + durable persist + profile hydration as
-   * {@link commitSession}, but IN-PLACE: it must NOT trigger the cross-origin
-   * hub-sync redirect. Switching into an account you already operate reuses the
-   * device credential that was already hub-synced at the original sign-in, so
-   * re-syncing is redundant and a full-page redirect on switch is the exact
-   * regression this separation prevents. Cross-tab/app propagation of the switch
+   * {@link commitSession}, but IN-PLACE: it must NOT re-run sign-in side effects
+   * that belong only to a fresh authorization (for example, a redundant full
+   * device-set reconcile on switch). Cross-tab/app propagation of the switch
    * still happens instantly via the server's device-scoped `session_state` /
    * `session_accounts_changed` socket broadcast — no navigation required.
    *
@@ -811,9 +807,9 @@ export class AccountDialogController {
             accessToken: result.accessToken,
           },
           result.user,
-          // A switch is IN-PLACE: commit without the hub-sync redirect (the
-          // device is already known/synced). Cross-tab/app propagation rides the
-          // server's `session_state` socket broadcast, not a navigation.
+          // A switch is IN-PLACE: use the switch commit funnel (not sign-in).
+          // Cross-tab/app propagation rides the server's `session_state` socket
+          // broadcast, not a navigation.
           { fromSwitch: true },
         );
       }
@@ -1349,11 +1345,9 @@ export class AccountDialogController {
    * consumer's commit funnel (durable persist + hydration); falls back to
    * `SessionClient.registerAndActivate` (registration + activation only).
    *
-   * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel
-   * so it never runs the cross-origin hub-sync redirect; a SIGN-IN uses
-   * `commitSession` (which may hub-sync on an official web origin). When the
-   * switch funnel is not wired it falls back to the sign-in funnel, then to
-   * `registerAndActivate`.
+   * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel;
+   * a SIGN-IN uses `commitSession`. When the switch funnel is not wired it falls
+   * back to the sign-in funnel, then to `registerAndActivate`.
    */
   private async commitAuthorizedSession(
     session: SessionLoginResponse,