@oxy.so/core 1.0.0

package/dist/types/server/securityHeaders.d.ts

@@ -0,0 +1,221 @@
+/**
+ * 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`).
+ *
+ *  3. A STATIC EXPO EXPORT SHIPS AN INLINE SCRIPT THE BASELINE FORBIDS.
+ *     `web.output: 'static'` makes Expo Router emit
+ *     `<script type="module">globalThis.__EXPO_ROUTER_HYDRATE__=true;</script>`,
+ *     which is what tells the client entry to call `hydrateRoot` instead of
+ *     `createRoot().render()`. Nothing in app code puts it there, so — like the
+ *     Cloudflare beacon above — an app cannot allowlist it from the app side.
+ *     Measured on `accounts.oxy.so` 2026-08-21: blocked, so every visit threw
+ *     away the server-rendered markup and re-rendered from scratch, with only a
+ *     console error to show for it. The hashes are therefore DERIVED from the
+ *     built output rather than hand-written (see {@link extractInlineScripts}):
+ *     a hash pasted into config is correct exactly until the build changes one
+ *     byte, and then it fails the same silent way.
+ *
+ * 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 `@oxy.so/core/server`.
+ */
+import type { RequestHandler } from 'express';
+import { type HelmetOptions } from 'helmet';
+/** 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 declare const OXY_CSP_BASELINE: Readonly<Partial<Record<OxyCspDirective, readonly string[]>>>;
+/**
+ * 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 declare function buildOxyCspDirectives(extensions?: OxyCspExtensions): Record<string, string[]>;
+/**
+ * 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 declare function formatOxyCspPolicy(directives: Record<string, string[]>): string;
+/**
+ * The source list one directive carries in a serialized policy, or `[]` when
+ * the policy does not name that directive. The inverse of
+ * {@link formatOxyCspPolicy}, and the reason it lives here rather than beside
+ * either caller: the post-deploy gate parses the policy the ORIGIN serves while
+ * the unit test parses the one the middleware renders, so a copy in each would
+ * let the header shape change with the test still green and the gate reading
+ * `[]` — reporting every script blocked, which reads as a broken app rather
+ * than as a broken parser.
+ *
+ * A directive present with no sources (`upgrade-insecure-requests`) and a
+ * directive absent entirely both answer `[]`. Callers that need to tell those
+ * apart are asking a different question than "what is allowed here".
+ */
+export declare function cspSourcesFor(policy: string, directive: string): string[];
+/**
+ * Every inline `<script>` body in an HTML document, in document order. A
+ * `<script src=…>` is a URL the source list already governs and is skipped.
+ *
+ * Scanned rather than matched with one regex because the two failure modes are
+ * not symmetric: an EXTRA body costs a redundant hash nobody notices, while a
+ * MISSED body silently reinstates the exact breakage this exists to prevent.
+ * So the scan errs toward finding them — it walks the open tag quote-aware
+ * instead of letting a `>` inside an attribute value truncate it.
+ *
+ * The type attribute is deliberately not consulted. Whether a given `type`
+ * executes is a browser decision (and it changes: `importmap` and
+ * `speculationrules` were both once inert), and pinning the exact bytes of a
+ * data block we ship ourselves weakens nothing.
+ */
+export declare function extractInlineScripts(html: string): string[];
+/**
+ * The `'sha256-…'` source that allows one inline script, hashed over its exact
+ * bytes as CSP specifies — no trimming, no normalization. One byte of
+ * whitespace either way is a different hash and the script stays blocked.
+ */
+export declare function inlineScriptCspHash(source: string): string;
+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;
+    /**
+     * The BUILT HTML documents this `_headers` will be served alongside. Every
+     * inline script found in them is allowed by hash, added to `script-src`.
+     *
+     * Passing the built output — rather than hand-writing a hash into
+     * `oxy.pages-headers.json` — is the whole point: a pasted hash is correct
+     * until the generator changes one byte of that script, and then the script is
+     * blocked again with nothing but a console error to show for it.
+     */
+    html?: readonly string[];
+}
+/**
+ * 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.
+ *
+ * Adding a hash to `script-src` does not narrow it: per CSP Level 3 a hash is
+ * an additional source, so `'self'` and the beacon host keep matching external
+ * scripts. (It WOULD neutralize `'unsafe-inline'` in the same directive — which
+ * is why this hashes scripts only. `style-src` keeps `'unsafe-inline'` for
+ * react-native-web's runtime stylesheet, and a style hash would silently switch
+ * that off and render every Oxy web app unstyled.)
+ */
+export declare function buildOxyPagesHeaders(options?: OxyPagesHeadersOptions): string;
+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 declare function createOxySecurityHeaders(options?: OxySecurityHeadersOptions): RequestHandler;

package/dist/types/server/userInvalidation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Oxy user-invalidation publish/consume helpers for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend caches Oxy identity, and none of them find out when it
+ * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
+ * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
+ * writes the profile (the `evictOxyIdentityCache` calls in the user and accounts
+ * mixins) and never when somebody else does — which is the normal case, since
+ * profiles are edited in Oxy's own apps. So an avatar or display-name change is
+ * invisible to every consuming backend for up to five minutes, per process.
+ *
+ * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
+ * when a user's identity changes. This module is the consumer half: it parses
+ * and validates the event, sweeps the SDK's own cache, and hands the event to
+ * app-specific eviction. Wiring it is two lines and every backend that does so
+ * stops serving stale identity.
+ *
+ * WHY THE TRANSPORT IS THE CALLER'S JOB
+ * -------------------------------------
+ * This module deliberately does NOT take a Redis client. ioredis and node-redis
+ * disagree about how to subscribe — node-redis passes the listener to
+ * `subscribe(channel, listener)`, ioredis takes `subscribe(channel)` and then
+ * emits `'message'` on the client — and a helper that accepted "a client" would
+ * have to sniff which library it was handed. That kind of detection is exactly
+ * what breaks silently when a consumer upgrades a client library.
+ *
+ * So the split is: this module owns parsing, validation, dispatch and the
+ * never-throw guarantee (the parts that are easy to get wrong and identical
+ * everywhere), and the caller owns its own client's two-line subscribe idiom
+ * (trivial, but library-specific).
+ *
+ *     // node-redis
+ *     await subscriber.subscribe(
+ *       OXY_USER_INVALIDATION_CHANNEL,
+ *       createOxyUserInvalidationHandler({ oxy: oxyClient }),
+ *     );
+ *
+ *     // ioredis
+ *     const handle = createOxyUserInvalidationHandler({ oxy: oxyClient });
+ *     await subscriber.subscribe(OXY_USER_INVALIDATION_CHANNEL);
+ *     subscriber.on('message', (_channel, raw) => handle(raw));
+ *
+ * Subscribe on EVERY task, not just an elected leader. The SDK cache this sweeps
+ * is per-process in-memory, so a leader-only subscriber would leave every other
+ * task stale — and leader-gating would add a failure mode (leader down means no
+ * invalidation anywhere) to a signal whose whole point is that losing it is
+ * merely slow, never wrong.
+ *
+ * Node-only; exported solely from `@oxy.so/core/server`.
+ */
+import { type OxyUserChangeReason, type OxyUserInvalidationEvent } from '@oxy.so/contracts';
+import { type OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
+/**
+ * The publish surface of a Redis client. Both `ioredis` and `node-redis`
+ * satisfy this structurally, so neither library is a dependency here.
+ */
+export interface OxyInvalidationPublisher {
+    publish(channel: string, message: string): unknown;
+}
+/**
+ * Broadcast that an Oxy user's record changed.
+ *
+ * Returns `true` when a message was put on the wire and `false` when the reason
+ * is not a broadcast one ({@link isPublishedOxyUserChangeReason}) — the latter is
+ * a deliberate no-op, not a failure. Suppressing at the publisher rather than
+ * letting every subscriber discard matters at bulk-follow scale, where a single
+ * call moves up to 200 edges.
+ *
+ * NEVER THROWS AND NEVER RETURNS A REJECTED PROMISE. This is called from inside
+ * cache invalidation, which itself runs after a successful database write on the
+ * request path: a publish failure must not turn a completed profile update into
+ * a 500. A dropped message costs a consumer its TTL and nothing more.
+ *
+ * @param publisher - A connected Redis client. Must NOT be a client currently in
+ *                    subscriber mode — Redis forbids `PUBLISH` on a subscribed
+ *                    connection, so pass the publisher half of a pub/sub pair.
+ * @param userId    - The Oxy user whose record changed.
+ * @param reason    - How the record changed. See {@link OxyUserChangeReason}.
+ * @param onError   - Optional diagnostic sink for a failed publish.
+ */
+export declare function publishOxyUserInvalidation(publisher: OxyInvalidationPublisher, userId: string, reason: OxyUserChangeReason, onError?: (error: unknown) => void): boolean;
+/** Options for {@link createOxyUserInvalidationHandler}. */
+export interface OxyUserInvalidationHandlerOptions {
+    /**
+     * The backend's `OxyServices` instance. When supplied, its GET response cache
+     * is swept for the invalidated user — this is the whole reason a backend that
+     * has no cache of its own still benefits from subscribing.
+     */
+    oxy?: OxyIdentityCacheEvictor;
+    /**
+     * App-specific eviction (e.g. a Redis identity cache the app maintains itself).
+     * May be async; a rejection is routed to `onError` and never escapes.
+     */
+    onInvalidate?: (event: OxyUserInvalidationEvent) => void | Promise<void>;
+    /** Diagnostic sink for an unparseable message or a failing `onInvalidate`. */
+    onError?: (error: unknown, raw: string) => void;
+}
+/**
+ * Build the message handler for {@link OXY_USER_INVALIDATION_CHANNEL}.
+ *
+ * The returned function NEVER THROWS and never returns a rejected promise. It
+ * runs inside the Redis client's message dispatch, where an exception either
+ * takes down the subscriber connection or surfaces as an unhandled rejection —
+ * and losing the subscription is strictly worse than losing one message, because
+ * it is silent and permanent.
+ *
+ * A message that fails schema validation is dropped, not retried: the payload is
+ * produced by a contract both sides compile against, so a malformed one means a
+ * version skew or an unrelated publisher on the channel, neither of which a retry
+ * fixes.
+ */
+export declare function createOxyUserInvalidationHandler(options?: OxyUserInvalidationHandlerOptions): (raw: string) => void;

package/dist/types/server/verifySecret.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Constant-time secret comparison for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Backends kept comparing secrets with `provided !== EXPECTED`. A plain `===`/
+ * `!==` short-circuits on the first differing byte, leaking timing information
+ * an attacker can use to recover a secret byte-by-byte. This helper performs a
+ * constant-time comparison via `crypto.timingSafeEqual`, guarded by a length
+ * check, and never throws — replacing the `token !== SECRET` pattern (Alia
+ * docker-host / integrations webhook secrets, internal webhook bearers, etc.).
+ *
+ * Node-only (`node:crypto`); exported solely from `@oxy.so/core/server`.
+ */
+/**
+ * Compare two secrets in constant time.
+ *
+ * Returns `true` iff both are non-empty strings of equal byte length with
+ * identical contents. Returns `false` — without throwing — when either value is
+ * not a string, when lengths differ, or when contents differ.
+ *
+ * The length-equality guard is required because `crypto.timingSafeEqual` throws
+ * on unequal-length buffers; comparing lengths first leaks only the LENGTH of
+ * the expected secret (already low-value / often public), never its bytes.
+ *
+ * @param provided - The untrusted, caller-supplied value (e.g. a request token).
+ * @param expected - The trusted secret to compare against.
+ */
+export declare function verifySecret(provided: string, expected: string): boolean;