@oxyhq/core 13.0.0 → 13.2.0

package/dist/cjs/index.js

@@ -20,9 +20,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.RecoveryPhraseService = exports.SignatureService = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.ORGANIZATION_CATEGORIES = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
 exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = void 0;
-exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = void 0;
-exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = void 0;
-exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = void 0;
+exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.translate = void 0;
+exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = void 0;
+exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -215,6 +215,7 @@ Object.defineProperty(exports, "translate", { enumerable: true, get: function ()
 // API request / URL helpers
 // ---------------------------------------------------------------------------
 var apiUtils_1 = require("./utils/apiUtils");
+Object.defineProperty(exports, "buildQueryParams", { enumerable: true, get: function () { return apiUtils_1.buildQueryParams; } });
 Object.defineProperty(exports, "buildSearchParams", { enumerable: true, get: function () { return apiUtils_1.buildSearchParams; } });
 Object.defineProperty(exports, "buildUrl", { enumerable: true, get: function () { return apiUtils_1.buildUrl; } });
 Object.defineProperty(exports, "buildPaginationParams", { enumerable: true, get: function () { return apiUtils_1.buildPaginationParams; } });

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

@@ -68,10 +68,7 @@ function OxyServicesUserMixin(Base) {
          */
         async searchProfiles(query, pagination) {
             try {
-                const params = { query, ...pagination };
-                const searchParams = (0, apiUtils_1.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', (0, apiUtils_1.buildQueryParams)({ query, ...pagination }), {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
                 });
@@ -529,6 +526,41 @@ 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.
          *
@@ -542,16 +574,7 @@ 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) {
@@ -572,15 +595,7 @@ 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) {
@@ -601,15 +616,7 @@ 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) {
@@ -622,13 +629,7 @@ 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) {
@@ -687,11 +688,16 @@ 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 = (0, apiUtils_1.buildPaginationParams)(pagination || {});
+                const params = (0, apiUtils_1.buildQueryParams)(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/followers`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -707,11 +713,11 @@ function OxyServicesUserMixin(Base) {
             }
         }
         /**
-         * Get user following
+         * Get user following. `sort` behaves as in {@link getUserFollowers}.
          */
         async getUserFollowing(userId, pagination) {
             try {
-                const params = (0, apiUtils_1.buildPaginationParams)(pagination || {});
+                const params = (0, apiUtils_1.buildQueryParams)(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/following`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -732,7 +738,7 @@ function OxyServicesUserMixin(Base) {
          */
         async getUserMutuals(userId, pagination) {
             try {
-                const params = (0, apiUtils_1.buildPaginationParams)(pagination || {});
+                const params = (0, apiUtils_1.buildQueryParams)(pagination || {});
                 const response = await this.makeRequest('GET', `/users/${userId}/mutuals`, params, {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache

package/dist/cjs/server/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isOfficialWebOrigin = exports.registrableApex = exports.verifySecret = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
+exports.isOfficialWebOrigin = exports.registrableApex = exports.verifySecret = exports.OXY_CSP_BASELINE = exports.formatOxyCspPolicy = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "createOptionalOxyAuth", { enumerable: true, get: function () { return auth_1.createOptionalOxyAuth; } });
 Object.defineProperty(exports, "createOxyAuthMiddleware", { enumerable: true, get: function () { return auth_1.createOxyAuthMiddleware; } });
@@ -44,6 +44,14 @@ Object.defineProperty(exports, "UPSTREAM_HEADERS_TIMEOUT_MS", { enumerable: true
 // Strict CORS allowlist (Oxy apex family + explicit app origins).
 var cors_1 = require("./cors");
 Object.defineProperty(exports, "createOxyCors", { enumerable: true, get: function () { return cors_1.createOxyCors; } });
+// Shared Helmet + Content-Security-Policy baseline (Cloudflare Insights beacon,
+// Oxy API/CDN origins) with additive, per-app extensions.
+var securityHeaders_1 = require("./securityHeaders");
+Object.defineProperty(exports, "buildOxyCspDirectives", { enumerable: true, get: function () { return securityHeaders_1.buildOxyCspDirectives; } });
+Object.defineProperty(exports, "buildOxyPagesHeaders", { enumerable: true, get: function () { return securityHeaders_1.buildOxyPagesHeaders; } });
+Object.defineProperty(exports, "createOxySecurityHeaders", { enumerable: true, get: function () { return securityHeaders_1.createOxySecurityHeaders; } });
+Object.defineProperty(exports, "formatOxyCspPolicy", { enumerable: true, get: function () { return securityHeaders_1.formatOxyCspPolicy; } });
+Object.defineProperty(exports, "OXY_CSP_BASELINE", { enumerable: true, get: function () { return securityHeaders_1.OXY_CSP_BASELINE; } });
 // Constant-time secret comparison.
 var verifySecret_1 = require("./verifySecret");
 Object.defineProperty(exports, "verifySecret", { enumerable: true, get: function () { return verifySecret_1.verifySecret; } });

package/dist/cjs/server/securityHeaders.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * 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`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_CSP_BASELINE = void 0;
+exports.buildOxyCspDirectives = buildOxyCspDirectives;
+exports.formatOxyCspPolicy = formatOxyCspPolicy;
+exports.buildOxyPagesHeaders = buildOxyPagesHeaders;
+exports.createOxySecurityHeaders = createOxySecurityHeaders;
+const helmet_1 = __importDefault(require("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.
+ */
+exports.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'], ... }
+ * ```
+ */
+function buildOxyCspDirectives(extensions = {}) {
+    const directiveNames = new Set([
+        ...Object.keys(exports.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 = exports.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.
+ */
+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.
+ */
+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' } },
+ * }));
+ * ```
+ */
+function createOxySecurityHeaders(options = {}) {
+    const { csp, helmet: helmetOptions } = options;
+    const directives = buildOxyCspDirectives(csp);
+    return (0, helmet_1.default)({
+        ...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/cjs/utils/apiUtils.js

@@ -3,23 +3,49 @@
  * Utility functions for common API patterns
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildQueryParams = buildQueryParams;
 exports.buildSearchParams = buildSearchParams;
 exports.buildUrl = buildUrl;
 exports.buildPaginationParams = buildPaginationParams;
 exports.safeJsonParse = safeJsonParse;
 /**
- * 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.
  */
-function buildSearchParams(params) {
-    const searchParams = new URLSearchParams();
+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
+ */
+function buildSearchParams(params) {
+    return new URLSearchParams(buildQueryParams(params));
 }
 /**
  * Build URL with search parameters
@@ -35,12 +61,16 @@ 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
  */
 function buildPaginationParams(params) {
-    return buildSearchParams(params);
+    return buildQueryParams(params);
 }
 /**
  * Safe JSON parsing with error handling