@oxyhq/core 12.11.1 → 13.2.0

package/dist/esm/index.js

@@ -106,7 +106,7 @@ export { translate } from './i18n/index.js';
 // ---------------------------------------------------------------------------
 // API request / URL helpers
 // ---------------------------------------------------------------------------
-export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils.js';
+export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils.js';
 export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils.js';
 export { retryAsync } from './utils/asyncUtils.js';
 // ---------------------------------------------------------------------------
@@ -148,9 +148,8 @@ export { runColdBoot } from './utils/coldBoot.js';
 // OAuth 2.0 Authorization Code + PKCE helpers ("Sign in with Oxy" third party).
 // Standard OAuth against auth.oxy.so/authorize — no FedCM/cookies/SSO bounce.
 // ---------------------------------------------------------------------------
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce.js';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins.js';
-export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync.js';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce.js';
+export { isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, } from './utils/officialOrigins.js';
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------

package/dist/esm/mixins/OxyServices.deviceBoot.js

@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { deviceTokenMintResponseSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemResponseSchema, safeParseContract, } from '@oxyhq/contracts';
+import { deviceTokenMintResponseSchema, safeParseContract, } from '@oxyhq/contracts';
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
  * `accountId` is not (or is no longer) a live account of this device session.
@@ -105,36 +105,5 @@ export function OxyServicesDeviceBootMixin(Base) {
                 throw normalized;
             }
         }
-        /** Mint a one-time hub sync ticket (bearer required). */
-        async issueHubTicket(returnOrigin) {
-            try {
-                const res = await this.makeRequest('POST', '/session/device/hub-ticket', { returnOrigin }, { cache: false });
-                const parsed = safeParseContract(deviceHubTicketIssueResponseSchema, res);
-                if (!parsed) {
-                    throw new Error('session/device/hub-ticket returned an unexpected response shape');
-                }
-                return parsed;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /** Redeem a hub sync ticket for a fresh device secret (public). */
-        async redeemHubTicket(ticket, returnOrigin) {
-            try {
-                const res = await this.makeRequest('POST', '/session/device/redeem-ticket', { ticket, returnOrigin }, 
-                // Public device-hub sync mint (bearer-less). Same control-plane class as
-                // the device-secret mint — bypassQueue so it never waits for a slot.
-                { cache: false, skipAuth: true, bypassQueue: true });
-                const parsed = safeParseContract(deviceHubTicketRedeemResponseSchema, res);
-                if (!parsed) {
-                    throw new Error('session/device/redeem-ticket returned an unexpected response shape');
-                }
-                return parsed;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
     };
 }

package/dist/esm/mixins/OxyServices.user.js

@@ -1,5 +1,5 @@
 import { recommendationRequestSchema } from '@oxyhq/contracts';
-import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils.js';
+import { buildQueryParams, buildPaginationParams, } from '../utils/apiUtils.js';
 import { KeyManager } from '../crypto/keyManager.js';
 import { SignatureService } from '../crypto/signatureService.js';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
@@ -65,10 +65,7 @@ export function OxyServicesUserMixin(Base) {
          */
         async searchProfiles(query, pagination) {
             try {
-                const params = { query, ...pagination };
-                const searchParams = buildSearchParams(params);
-                const paramsObj = Object.fromEntries(searchParams.entries());
-                const response = await this.makeRequest('GET', '/profiles/search', paramsObj, {
+                const response = await this.makeRequest('GET', '/profiles/search', buildQueryParams({ query, ...pagination }), {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
                 });
@@ -526,6 +523,41 @@ export function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Invalidate every cached read a follow/unfollow write invalidates.
+         *
+         * Shared by the four mutation entry points (`followUser`, `unfollowUser`,
+         * `followUsers`, `unfollowUsers`) so they can never drift on which caches a
+         * write busts.
+         *
+         * The follower/following/mutuals LISTS are cleared by PREFIX rather than by
+         * exact key. Those reads are paginated and ordered, so one logical list is
+         * spread across many content-addressed keys
+         * (`GET:/users/<id>/followers:{"limit":"20","offset":"40","sort":"oldest"}`);
+         * an exact-key clear would only bust whichever page/sort variant happened to
+         * be read last and would leave every other page stale. `clearCacheByPrefix`
+         * deletes all of them, and all identity-scoped variants of each.
+         */
+        invalidateFollowGraphCaches(targetUserIds) {
+            for (const id of targetUserIds) {
+                this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+                // Profile fetches embed viewer-relative `relationship` — bust so a
+                // remount doesn't serve a stale isFollowing for up to 5 minutes.
+                this.clearCacheEntry(`GET:/users/${id}`);
+                // The target gained/lost a follower, and the viewer's presence in the
+                // target's "followers you know" set changed with it.
+                this.clearCacheByPrefix(`GET:/users/${id}/followers`);
+                this.clearCacheByPrefix(`GET:/users/${id}/mutuals`);
+            }
+            this.clearCacheByPrefix('GET:/profiles/username/');
+            this.clearCacheByPrefix('GET:/profiles/resolve');
+            // The write changed the viewer's OWN following list and graph.
+            const viewerId = this.getCurrentUserId();
+            if (viewerId) {
+                this.clearCacheByPrefix(`GET:/users/${viewerId}/following`);
+            }
+            this.clearCacheEntry('GET:/users/me/graph');
+        }
         /**
          * Follow a user.
          *
@@ -539,16 +571,7 @@ export function OxyServicesUserMixin(Base) {
         async followUser(userId) {
             try {
                 const result = await this.makeRequest('POST', `/users/${userId}/follow`, undefined, { cache: false });
-                this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
-                // Profile fetches embed viewer-relative `relationship` — bust so a
-                // remount doesn't serve a stale isFollowing for up to 5 minutes.
-                this.clearCacheEntry(`GET:/users/${userId}`);
-                this.clearCacheByPrefix('GET:/profiles/username/');
-                this.clearCacheByPrefix('GET:/profiles/resolve');
-                // The follow changed the viewer's graph — bust the cached consolidated
-                // `GET /users/me/graph` so the next read reflects the new following/
-                // mutual set instead of the stale pre-write snapshot.
-                this.clearCacheEntry('GET:/users/me/graph');
+                this.invalidateFollowGraphCaches([userId]);
                 return result;
             }
             catch (error) {
@@ -569,15 +592,7 @@ export function OxyServicesUserMixin(Base) {
             }
             try {
                 const result = await this.makeRequest('POST', '/users/follow/bulk', { userIds }, { cache: false });
-                // Bust each affected user's cached follow-status (see `followUser`).
-                for (const id of userIds) {
-                    this.clearCacheEntry(`GET:/users/${id}/follow-status`);
-                    this.clearCacheEntry(`GET:/users/${id}`);
-                }
-                this.clearCacheByPrefix('GET:/profiles/username/');
-                this.clearCacheByPrefix('GET:/profiles/resolve');
-                // The batch changed the viewer's graph — bust the consolidated cache.
-                this.clearCacheEntry('GET:/users/me/graph');
+                this.invalidateFollowGraphCaches(userIds);
                 return result;
             }
             catch (error) {
@@ -598,15 +613,7 @@ export function OxyServicesUserMixin(Base) {
             }
             try {
                 const result = await this.makeRequest('POST', '/users/unfollow/bulk', { userIds }, { cache: false });
-                // Bust each affected user's cached follow-status (see `followUser`).
-                for (const id of userIds) {
-                    this.clearCacheEntry(`GET:/users/${id}/follow-status`);
-                    this.clearCacheEntry(`GET:/users/${id}`);
-                }
-                this.clearCacheByPrefix('GET:/profiles/username/');
-                this.clearCacheByPrefix('GET:/profiles/resolve');
-                // The batch changed the viewer's graph — bust the consolidated cache.
-                this.clearCacheEntry('GET:/users/me/graph');
+                this.invalidateFollowGraphCaches(userIds);
                 return result;
             }
             catch (error) {
@@ -619,13 +626,7 @@ export function OxyServicesUserMixin(Base) {
         async unfollowUser(userId) {
             try {
                 const result = await this.makeRequest('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
-                // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
-                this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
-                this.clearCacheEntry(`GET:/users/${userId}`);
-                this.clearCacheByPrefix('GET:/profiles/username/');
-                this.clearCacheByPrefix('GET:/profiles/resolve');
-                // The unfollow changed the viewer's graph — bust the consolidated cache.
-                this.clearCacheEntry('GET:/users/me/graph');
+                this.invalidateFollowGraphCaches([userId]);
                 return result;
             }
             catch (error) {
@@ -684,11 +685,16 @@ export function OxyServicesUserMixin(Base) {
             }
         }
         /**
-         * Get user followers
+         * Get user followers.
+         *
+         * `sort` orders the underlying follow edges — `recent` (newest first, the
+         * server default) or `oldest`. Because the response is cached and the cache
+         * key is content-addressed on the query params, each `limit`/`offset`/`sort`
+         * combination is its own entry.
          */
         async getUserFollowers(userId, pagination) {
             try {
-                const params = buildPaginationParams(pagination || {});
+                const params = buildQueryParams(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/followers`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -704,11 +710,11 @@ export function OxyServicesUserMixin(Base) {
             }
         }
         /**
-         * Get user following
+         * Get user following. `sort` behaves as in {@link getUserFollowers}.
          */
         async getUserFollowing(userId, pagination) {
             try {
-                const params = buildPaginationParams(pagination || {});
+                const params = buildQueryParams(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/following`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -729,7 +735,7 @@ export function OxyServicesUserMixin(Base) {
          */
         async getUserMutuals(userId, pagination) {
             try {
-                const params = buildPaginationParams(pagination || {});
+                const params = buildQueryParams(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/mutuals`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache

package/dist/esm/server/index.js

@@ -20,6 +20,9 @@ export { createOxyRateLimit } from './rateLimit.js';
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch.js';
 // Strict CORS allowlist (Oxy apex family + explicit app origins).
 export { createOxyCors } from './cors.js';
+// 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.js';
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret.js';
 // Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
@@ -27,4 +30,4 @@ export { verifySecret } from './verifySecret.js';
 // 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.js';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins.js';
+export { isOfficialWebOrigin } from '../utils/officialOrigins.js';

package/dist/esm/server/rateLimit.js

@@ -168,6 +168,9 @@ export function createOxyRateLimit(oxy, options = {}) {
         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) => {
         // Skipped paths bypass BOTH session resolution and limiting — cheap and

package/dist/esm/server/securityHeaders.js

@@ -0,0 +1,224 @@
+/**
+ * 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 helmet 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 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 = 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) {
+    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, source) {
+    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) {
+    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 = {}) {
+    const directiveNames = new Set([
+        ...Object.keys(OXY_CSP_BASELINE),
+        ...Object.keys(extensions),
+    ]);
+    const resolved = {};
+    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) {
+    return Object.entries(directives)
+        .map(([name, sources]) => (sources.length === 0 ? name : `${name} ${sources.join(' ')}`))
+        .join('; ');
+}
+/**
+ * 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 = {}) {
+    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');
+}
+/**
+ * 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 = {}) {
+    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/dist/esm/session/accountDialogController.js

@@ -477,9 +477,9 @@ export class AccountDialogController {
                     user: result.user,
                     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 });
             }
             // Re-project + refetch immediately; the subscription also fires.
@@ -982,11 +982,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`.
      */
     async commitAuthorizedSession(session, user, opts) {
         const commit = opts?.fromSwitch

package/dist/esm/utils/apiUtils.js

@@ -2,18 +2,43 @@
  * Utility functions for common API patterns
  */
 /**
- * Build URL search parameters from an object
- * @param params Object with parameter key-value pairs
- * @returns URLSearchParams instance
+ * Build a plain query-parameter record from an object, stringifying values and
+ * dropping `undefined`/`null` entries.
+ *
+ * This is the shape `OxyServices.makeRequest` expects for a GET's `params`:
+ * `HttpService` inspects it with `Object.keys(...)` (both to decide whether to
+ * append a query string and to build the request's cache key), and
+ * `Object.keys(new URLSearchParams({ limit: '20' }))` is `[]` — a
+ * `URLSearchParams` exposes its entries through iterator methods, never as own
+ * enumerable properties. Passing one to `makeRequest` therefore silently drops
+ * the whole query string. Always hand `makeRequest` a plain record.
+ *
+ * Generic over the input object rather than taking `Record<string, unknown>`,
+ * because a TypeScript `interface` (`PaginationParams`, `FollowGraphParams`, …)
+ * has no implicit index signature and so is not assignable to that type.
  */
-export function buildSearchParams(params) {
-    const searchParams = new URLSearchParams();
+export function buildQueryParams(params) {
+    const query = {};
+    // Widening the value to `unknown` is always sound; the default overload of
+    // `Object.entries` would otherwise infer `any` here.
     for (const [key, value] of Object.entries(params)) {
         if (value !== undefined && value !== null) {
-            searchParams.append(key, value.toString());
+            query[key] = String(value);
         }
     }
-    return searchParams;
+    return query;
+}
+/**
+ * Build URL search parameters from an object.
+ *
+ * For building a URL string only — see {@link buildQueryParams} for the shape
+ * `makeRequest` needs.
+ *
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+export function buildSearchParams(params) {
+    return new URLSearchParams(buildQueryParams(params));
 }
 /**
  * Build URL with search parameters
@@ -29,12 +54,16 @@ export function buildUrl(baseUrl, params) {
     return queryString ? `${baseUrl}?${queryString}` : baseUrl;
 }
 /**
- * Build pagination search parameters
+ * Build pagination query parameters.
+ *
+ * Returns a plain record — NOT a `URLSearchParams` — because that is the only
+ * shape `makeRequest`/`HttpService` can read. See {@link buildQueryParams}.
+ *
  * @param params Pagination parameters
- * @returns URLSearchParams with pagination
+ * @returns Query record with pagination
  */
 export function buildPaginationParams(params) {
-    return buildSearchParams(params);
+    return buildQueryParams(params);
 }
 /**
  * Safe JSON parsing with error handling

package/dist/esm/utils/oauthPkce.js

@@ -145,10 +145,6 @@ export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
 export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
 /** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
 export const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = 'oxy.oauth_redirect_uri';
-/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
-export const OXY_SILENT_OAUTH_ATTEMPTED_KEY = 'oxy.silent_oauth_attempted';
-/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
-export const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = 'oxy.cross_origin_restore_attempted';
 /**
  * `sessionStorage` key for the in-app path to return to after an authorize
  * round trip. See {@link persistOAuthReturnPath}.