@oxy.so/core 1.0.0

package/dist/cjs/server/cors.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * Strict CORS allowlist for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * App backends kept hand-rolling CORS, and the unsafe patterns recurred:
+ *   - `Access-Control-Allow-Origin: *` together with credentials (which is
+ *     spec-invalid AND a credential-leak vector), or
+ *   - a "reflect whatever Origin the request carried" fallback (effectively
+ *     `*` for credentialed requests — the Allo wildcard-fallback class).
+ *
+ * `createOxyCors` returns a self-contained Express middleware (no `cors`
+ * package dependency) that:
+ *   - allows the Oxy apex origin family over HTTPS only: the apex plus
+ *     one-label subdomains such as `auth.oxy.so`, `api.oxy.so`,
+ *     `accounts.oxy.so`, `console.oxy.so`, and `inbox.oxy.so`,
+ *   - allows the caller's explicit `appOrigins`,
+ *   - REFUSES the opaque origin on both sides (see `OPAQUE_ORIGIN`),
+ *   - DENIES everything else (no reflection, never a wildcard with credentials),
+ *   - echoes back the EXACT matched origin (so credentialed requests work) and
+ *     sets `Vary: Origin` for correct caching,
+ *   - answers CORS preflight (`OPTIONS`) with `204`.
+ *
+ * Node/Express-only: exported solely from `@oxy.so/core/server`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAppOrigins = normalizeAppOrigins;
+exports.matchesAllowedOrigin = matchesAllowedOrigin;
+exports.createOxyCors = createOxyCors;
+const logger_1 = require("../logger");
+const authWebUrl_1 = require("../utils/authWebUrl");
+const log = (0, logger_1.createLogger)('OxyCors');
+/** Default HTTP methods allowed across origins. */
+const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
+/** Default request headers a browser may send on a credentialed cross-origin call. */
+const DEFAULT_ALLOWED_HEADERS = [
+    'Content-Type',
+    'Authorization',
+    'X-Requested-With',
+    'X-Oxy-User-Id',
+    'X-Oxy-Internal',
+    'X-CSRF-Token',
+    'X-Oxy-Edge-Region',
+    'X-Oxy-Activity-Id',
+];
+/** How long (seconds) a browser may cache a successful preflight. */
+const DEFAULT_MAX_AGE_SECONDS = 86400;
+const OXY_ONE_LABEL_SUBDOMAIN_PATTERN = new RegExp(`^[a-z0-9-]+\\.${authWebUrl_1.CENTRAL_IDP_APEX.replace('.', '\\.')}$`);
+/**
+ * Whether `candidate` belongs to the built-in Oxy apex origin family. This
+ * intentionally mirrors the API allowlist shape: HTTPS only, no custom port,
+ * the apex itself (`https://oxy.so`), or exactly one lowercase subdomain label
+ * (`https://auth.oxy.so`, `https://api.oxy.so`, …).
+ *
+ * Arbitrary/multi-level subdomains and `http://*.oxy.so` are not implicitly
+ * trusted for credentialed CORS. If a service needs a non-standard development
+ * or tenant origin, it must opt in explicitly via `appOrigins`.
+ */
+function isOxyFamilyOrigin(candidate) {
+    try {
+        const url = new URL(candidate);
+        if (url.protocol !== 'https:' || url.port !== '')
+            return false;
+        const hostname = url.hostname;
+        if (hostname === authWebUrl_1.CENTRAL_IDP_APEX)
+            return true;
+        return OXY_ONE_LABEL_SUBDOMAIN_PATTERN.test(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The URL standard's serialization of an OPAQUE origin: the literal string
+ * `"null"`, which `new URL(x).origin` returns for every scheme that has no
+ * origin to speak of — `exp:`, `capacitor:`, `chrome-extension:`,
+ * `vscode-webview:`, and also `file:`, `data:` and `about:`.
+ *
+ * This value is why an allowlist may never store it. Every such scheme
+ * normalizes to the SAME `"null"`, so a set built by normalization cannot tell
+ * them apart: ONE opaque entry admits ALL of them. With credentials on and the
+ * raw header echoed back, a single `myapp://` in `appOrigins` turned this
+ * helper into "allow any custom-scheme browsing context" — measured live, an
+ * `exp://localhost:8150` entry answered `Origin: vscode-webview://…` with
+ * `access-control-allow-origin: vscode-webview://…` and
+ * `access-control-allow-credentials: true`.
+ *
+ * There is deliberately no escape hatch that matches such an origin by raw
+ * string instead. Admitting a custom-scheme browsing context to a CREDENTIALED
+ * allowlist is a distinct decision with its own threat model, and it must not
+ * arrive as a side effect of someone adding one line to `appOrigins`. Note
+ * also that a native client is not subject to CORS at all — React Native sends
+ * no `Origin` header — so a mobile app never needs an entry here.
+ */
+const OPAQUE_ORIGIN = 'null';
+/** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
+function normalizeOrigin(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalize the configured `appOrigins` into the exact-match set — the
+ * CONFIGURE-SIDE half of the opaque-origin guard.
+ *
+ * An entry that is not a URL, or whose origin is opaque, is dropped and named
+ * in an error log. Dropped rather than thrown on because `appOrigins` is
+ * deployment configuration — at least one Oxy backend reads it from the
+ * environment — and a typo there must cost that one origin its CORS headers,
+ * never the whole service its boot. Both failure modes are equally SAFE (the
+ * entry is absent from the set either way), so the choice is purely about
+ * blast radius, and dropping keeps it to one origin whose requests then fail
+ * visibly in the browser.
+ *
+ * Exported for `__tests__/cors.socket.test.ts` and NOT re-exported from
+ * `server/index.ts`, so it is not part of the package's public surface. The
+ * two halves of the guard are separately exported because they are separately
+ * testable only that way: with this half in place the match-side half is
+ * unreachable through `createOxyCors`, so a test driving the public API alone
+ * would measure this function twice and the other one never.
+ */
+function normalizeAppOrigins(appOrigins) {
+    const explicit = new Set();
+    for (const raw of appOrigins) {
+        const normalized = normalizeOrigin(raw);
+        if (normalized === null) {
+            log.error('CORS allowlist entry ignored: it is not a URL', undefined, { entry: raw });
+            continue;
+        }
+        if (normalized === OPAQUE_ORIGIN) {
+            log.error('CORS allowlist entry ignored: it has no origin to match against', undefined, {
+                entry: raw,
+            });
+            continue;
+        }
+        explicit.add(normalized);
+    }
+    return explicit;
+}
+/**
+ * Whether `origin` may be echoed back: it is in the built-in HTTPS Oxy apex
+ * family, or it exactly matches one of the configured app origins.
+ *
+ * The opaque-origin refusal here is the MATCH-SIDE half of the guard, and it
+ * is what makes the property hold regardless of how `explicit` was built — a
+ * set that somehow contains `"null"` still matches nothing, because no
+ * incoming origin ever normalizes past this line. `normalizeAppOrigins` is
+ * what stops such a set existing today; this is what stops it mattering.
+ *
+ * Exported for the same reason as `normalizeAppOrigins`, and likewise absent
+ * from `server/index.ts`.
+ */
+function matchesAllowedOrigin(explicit, origin) {
+    const normalized = normalizeOrigin(origin);
+    if (normalized === null)
+        return false;
+    if (normalized === OPAQUE_ORIGIN)
+        return false;
+    if (explicit.has(normalized))
+        return true;
+    return isOxyFamilyOrigin(normalized);
+}
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+function createOxyCors(options = {}) {
+    const { appOrigins = [], allowCredentials = true, methods = DEFAULT_ALLOWED_METHODS, allowedHeaders = DEFAULT_ALLOWED_HEADERS, exposedHeaders = [], maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS, } = options;
+    const explicitOrigins = normalizeAppOrigins(appOrigins);
+    const methodsHeader = methods.join(', ');
+    const allowedHeadersHeader = allowedHeaders.join(', ');
+    const exposedHeadersHeader = exposedHeaders.join(', ');
+    return (req, res, next) => {
+        const origin = req.headers.origin;
+        // Same-origin or non-browser requests carry no Origin header — pass through
+        // untouched (no ACAO header is emitted, which is correct for them).
+        if (typeof origin !== 'string' || origin.length === 0) {
+            if (req.method === 'OPTIONS') {
+                res.sendStatus(204);
+                return;
+            }
+            next();
+            return;
+        }
+        // Origin is present. Caching correctness: this response varies by Origin.
+        res.setHeader('Vary', 'Origin');
+        if (!matchesAllowedOrigin(explicitOrigins, origin)) {
+            // DENY: do NOT reflect the origin, do NOT emit a wildcard. The browser
+            // will block the cross-origin read. Preflights for denied origins get a
+            // 204 with no CORS headers (the actual request then fails CORS).
+            if (req.method === 'OPTIONS') {
+                res.sendStatus(204);
+                return;
+            }
+            next();
+            return;
+        }
+        // ALLOW: echo the EXACT matched origin — never `*`, even without credentials.
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        if (allowCredentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        if (exposedHeadersHeader) {
+            res.setHeader('Access-Control-Expose-Headers', exposedHeadersHeader);
+        }
+        if (req.method === 'OPTIONS') {
+            res.setHeader('Access-Control-Allow-Methods', methodsHeader);
+            // Honour the browser's requested headers when present, else the default set.
+            const requested = req.headers['access-control-request-headers'];
+            res.setHeader('Access-Control-Allow-Headers', typeof requested === 'string' && requested.length > 0 ? requested : allowedHeadersHeader);
+            res.setHeader('Access-Control-Max-Age', String(maxAgeSeconds));
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    };
+}

package/dist/cjs/server/index.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * @oxy.so/core/server — Server-only utilities for Oxy backends
+ *
+ * This subpath export provides Express middleware and Node.js-specific
+ * utilities that are not available in React Native or browser environments.
+ *
+ * @example
+ * ```ts
+ * import { createOxyRateLimit } from '@oxy.so/core/server';
+ * import { oxyClient } from '@oxy.so/core';
+ *
+ * const oxy = oxyClient({ apiUrl: 'https://api.oxy.so' });
+ *
+ * app.use(createOxyRateLimit(oxy, { store: redisStore }));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOfficialWebOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.verifySecret = exports.verifyCapabilityTicket = exports.readCapabilityAuthorization = exports.issueCapabilityTicket = exports.inputSatisfiesCapabilityLimits = exports.createCapabilityTicketMiddleware = exports.CapabilityTicketError = exports.OXY_CSP_BASELINE = exports.inlineScriptCspHash = exports.formatOxyCspPolicy = exports.extractInlineScripts = exports.cspSourcesFor = 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.getRequiredOxyBillingPrincipal = exports.getOxyUserId = exports.getOxyRequestAttribution = exports.getOxyDelegatedUserId = exports.getOxyBillingPrincipal = 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; } });
+Object.defineProperty(exports, "getOxyBillingPrincipal", { enumerable: true, get: function () { return auth_1.getOxyBillingPrincipal; } });
+Object.defineProperty(exports, "getOxyDelegatedUserId", { enumerable: true, get: function () { return auth_1.getOxyDelegatedUserId; } });
+Object.defineProperty(exports, "getOxyRequestAttribution", { enumerable: true, get: function () { return auth_1.getOxyRequestAttribution; } });
+Object.defineProperty(exports, "getOxyUserId", { enumerable: true, get: function () { return auth_1.getOxyUserId; } });
+Object.defineProperty(exports, "getRequiredOxyBillingPrincipal", { enumerable: true, get: function () { return auth_1.getRequiredOxyBillingPrincipal; } });
+Object.defineProperty(exports, "getRequiredOxyUserId", { enumerable: true, get: function () { return auth_1.getRequiredOxyUserId; } });
+Object.defineProperty(exports, "isOxyAuthenticated", { enumerable: true, get: function () { return auth_1.isOxyAuthenticated; } });
+Object.defineProperty(exports, "requireOxyAuth", { enumerable: true, get: function () { return auth_1.requireOxyAuth; } });
+Object.defineProperty(exports, "OXY_SERVICE_ENVIRONMENTS", { enumerable: true, get: function () { return auth_1.OXY_SERVICE_ENVIRONMENTS; } });
+var rateLimit_1 = require("./rateLimit");
+Object.defineProperty(exports, "createOxyRateLimit", { enumerable: true, get: function () { return rateLimit_1.createOxyRateLimit; } });
+// SSRF-safe upstream fetch + URL validation (Node-only).
+var safeFetch_1 = require("./safeFetch");
+Object.defineProperty(exports, "assertSafePublicUrl", { enumerable: true, get: function () { return safeFetch_1.assertSafePublicUrl; } });
+Object.defineProperty(exports, "isBlockedIp", { enumerable: true, get: function () { return safeFetch_1.isBlockedIp; } });
+Object.defineProperty(exports, "safeFetch", { enumerable: true, get: function () { return safeFetch_1.safeFetch; } });
+Object.defineProperty(exports, "SsrfRejection", { enumerable: true, get: function () { return safeFetch_1.SsrfRejection; } });
+Object.defineProperty(exports, "UpstreamError", { enumerable: true, get: function () { return safeFetch_1.UpstreamError; } });
+Object.defineProperty(exports, "ALLOWED_PORTS", { enumerable: true, get: function () { return safeFetch_1.ALLOWED_PORTS; } });
+Object.defineProperty(exports, "ALLOWED_PROTOCOLS", { enumerable: true, get: function () { return safeFetch_1.ALLOWED_PROTOCOLS; } });
+Object.defineProperty(exports, "BLOCKED_HOSTNAMES", { enumerable: true, get: function () { return safeFetch_1.BLOCKED_HOSTNAMES; } });
+Object.defineProperty(exports, "DEFAULT_USER_AGENT", { enumerable: true, get: function () { return safeFetch_1.DEFAULT_USER_AGENT; } });
+Object.defineProperty(exports, "MAX_REDIRECTS", { enumerable: true, get: function () { return safeFetch_1.MAX_REDIRECTS; } });
+Object.defineProperty(exports, "MAX_URL_LENGTH", { enumerable: true, get: function () { return safeFetch_1.MAX_URL_LENGTH; } });
+Object.defineProperty(exports, "UPSTREAM_HEADERS_TIMEOUT_MS", { enumerable: true, get: function () { return safeFetch_1.UPSTREAM_HEADERS_TIMEOUT_MS; } });
+// 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.
+//
+// `extractInlineScripts` / `inlineScriptCspHash` / `cspSourcesFor` are exported
+// so a post-deploy gate can ask the SERVED document and the SERVED policy the
+// same questions `buildOxyPagesHeaders` asked the built ones. A gate that
+// re-implemented the scan or the parse would be testing its own copy, and would
+// agree with a broken original.
+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, "cspSourcesFor", { enumerable: true, get: function () { return securityHeaders_1.cspSourcesFor; } });
+Object.defineProperty(exports, "extractInlineScripts", { enumerable: true, get: function () { return securityHeaders_1.extractInlineScripts; } });
+Object.defineProperty(exports, "formatOxyCspPolicy", { enumerable: true, get: function () { return securityHeaders_1.formatOxyCspPolicy; } });
+Object.defineProperty(exports, "inlineScriptCspHash", { enumerable: true, get: function () { return securityHeaders_1.inlineScriptCspHash; } });
+Object.defineProperty(exports, "OXY_CSP_BASELINE", { enumerable: true, get: function () { return securityHeaders_1.OXY_CSP_BASELINE; } });
+var capabilityTicket_1 = require("./capabilityTicket");
+Object.defineProperty(exports, "CapabilityTicketError", { enumerable: true, get: function () { return capabilityTicket_1.CapabilityTicketError; } });
+Object.defineProperty(exports, "createCapabilityTicketMiddleware", { enumerable: true, get: function () { return capabilityTicket_1.createCapabilityTicketMiddleware; } });
+Object.defineProperty(exports, "inputSatisfiesCapabilityLimits", { enumerable: true, get: function () { return capabilityTicket_1.inputSatisfiesCapabilityLimits; } });
+Object.defineProperty(exports, "issueCapabilityTicket", { enumerable: true, get: function () { return capabilityTicket_1.issueCapabilityTicket; } });
+Object.defineProperty(exports, "readCapabilityAuthorization", { enumerable: true, get: function () { return capabilityTicket_1.readCapabilityAuthorization; } });
+Object.defineProperty(exports, "verifyCapabilityTicket", { enumerable: true, get: function () { return capabilityTicket_1.verifyCapabilityTicket; } });
+// Constant-time secret comparison.
+var verifySecret_1 = require("./verifySecret");
+Object.defineProperty(exports, "verifySecret", { enumerable: true, get: function () { return verifySecret_1.verifySecret; } });
+// Cross-service user-invalidation signal: oxy-api publishes when identity
+// changes, every consuming backend sweeps its caches instead of waiting out a TTL.
+var userInvalidation_1 = require("./userInvalidation");
+Object.defineProperty(exports, "createOxyUserInvalidationHandler", { enumerable: true, get: function () { return userInvalidation_1.createOxyUserInvalidationHandler; } });
+Object.defineProperty(exports, "publishOxyUserInvalidation", { enumerable: true, get: function () { return userInvalidation_1.publishOxyUserInvalidation; } });
+// The identity-key enumeration itself is platform-neutral (`src/utils/`) so the
+// client mixins and this Node-only subscriber sweep the SAME list — a second
+// copy is what let `updateAccount` and `updateProfile` drift apart.
+var identityCacheSweep_1 = require("../utils/identityCacheSweep");
+Object.defineProperty(exports, "evictOxyIdentityCache", { enumerable: true, get: function () { return identityCacheSweep_1.evictOxyIdentityCache; } });
+Object.defineProperty(exports, "oxyUserByIdCacheKey", { enumerable: true, get: function () { return identityCacheSweep_1.oxyUserByIdCacheKey; } });
+Object.defineProperty(exports, "OXY_IDENTITY_CACHE_PREFIXES", { enumerable: true, get: function () { return identityCacheSweep_1.OXY_IDENTITY_CACHE_PREFIXES; } });
+// Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
+// SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
+// Pure host handling (no browser deps), so it is safe on the server subpath and
+// lets `@oxy.so/api` derive `auth.<apex>` without duplicating PSL logic.
+var registrableApex_1 = require("../utils/registrableApex");
+Object.defineProperty(exports, "registrableApex", { enumerable: true, get: function () { return registrableApex_1.registrableApex; } });
+var officialOrigins_1 = require("../utils/officialOrigins");
+Object.defineProperty(exports, "isOfficialWebOrigin", { enumerable: true, get: function () { return officialOrigins_1.isOfficialWebOrigin; } });

package/dist/cjs/server/rateLimit.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOxyRateLimit = createOxyRateLimit;
+const node_crypto_1 = require("node:crypto");
+const node_net_1 = require("node:net");
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+const auth_1 = require("./auth");
+/**
+ * Built-in exemptions. A media app's cover-art/avatar fan-out and HLS
+ * sub-requests must not consume the coarse global budget; health probes from
+ * the load balancer must never be limited; CORS preflight is not a real call.
+ */
+function isBuiltInExempt(req) {
+    const path = req.path;
+    return (req.method === 'OPTIONS' ||
+        path.startsWith('/files/upload') ||
+        path.includes('/images/') ||
+        path.includes('/media/') ||
+        path.startsWith('/api/stream/') ||
+        path.includes('/stream/') ||
+        path === '/health' ||
+        path.endsWith('/health'));
+}
+/**
+ * Anonymous rate-limit keys must be PRIVACY-PRESERVING: the raw client IP must
+ * never reach a store at rest (in-memory or Redis). We therefore HMAC-hash the
+ * IP into a short, transient-only bucket key. Two IPv6-specific concerns shape
+ * the pre-hash normalization:
+ *
+ *  - IPv6 hosts are typically handed an entire /64 (often a /56), so a single
+ *    host can rotate through an enormous address space and evade a per-address
+ *    limit. We bucket IPv6 to its /56 prefix BEFORE hashing.
+ *  - express-rate-limit only exposes an `ipKeyGenerator` /56 helper from v8
+ *    onwards; `@oxy.so/core` pins v7 (peer `^7.0.0`), so the masking is
+ *    implemented here rather than pulling a major-version bump of a
+ *    security-critical dependency (and its rate-limit-redis compatibility) into
+ *    an unrelated privacy change. This mirrors `packages/api/src/utils/ipKey.ts`.
+ */
+const IPV6_SUBNET_BITS = 56;
+/** Expand an IPv6 literal (handling `::` and embedded IPv4) to 8 numeric hextets, or null if unparseable. */
+function ipv6Hextets(ip) {
+    let addr = ip;
+    const zone = addr.indexOf('%');
+    if (zone !== -1) {
+        addr = addr.slice(0, zone);
+    }
+    // Embedded IPv4 tail (e.g. `::ffff:203.0.113.7`) → fold the dotted quad into two hextets.
+    const lastColon = addr.lastIndexOf(':');
+    if (lastColon !== -1 && addr.slice(lastColon + 1).includes('.')) {
+        const v4 = addr.slice(lastColon + 1);
+        if (!(0, node_net_1.isIPv4)(v4)) {
+            return null;
+        }
+        const octets = v4.split('.').map((part) => Number.parseInt(part, 10));
+        const high = ((octets[0] << 8) | octets[1]).toString(16);
+        const low = ((octets[2] << 8) | octets[3]).toString(16);
+        addr = `${addr.slice(0, lastColon + 1)}${high}:${low}`;
+    }
+    const halves = addr.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    let groups;
+    if (halves.length === 1) {
+        groups = head;
+    }
+    else {
+        const missing = 8 - (head.length + tail.length);
+        if (missing < 0) {
+            return null;
+        }
+        groups = [...head, ...new Array(missing).fill('0'), ...tail];
+    }
+    if (groups.length !== 8) {
+        return null;
+    }
+    const hextets = groups.map((group) => Number.parseInt(group || '0', 16));
+    if (hextets.some((value) => Number.isNaN(value) || value < 0 || value > 0xffff)) {
+        return null;
+    }
+    return hextets;
+}
+/** Mask an IPv6 address to its /{bits} prefix, returned as a canonical hex string. */
+function maskIPv6(ip, bits) {
+    const hextets = ipv6Hextets(ip);
+    if (!hextets) {
+        return ip;
+    }
+    const masked = hextets.map((hextet, index) => {
+        const groupStart = index * 16;
+        if (groupStart >= bits) {
+            return 0;
+        }
+        const keepBits = Math.min(16, bits - groupStart);
+        const mask = keepBits >= 16 ? 0xffff : (0xffff << (16 - keepBits)) & 0xffff;
+        return hextet & mask;
+    });
+    return `${masked.map((hextet) => hextet.toString(16)).join(':')}/${bits}`;
+}
+/**
+ * Hash a client IP into a privacy-preserving bucket key. IPv6 is bucketed to its
+ * /56 prefix first (so a single v6 host can't rotate through its allocation to
+ * mint fresh keys), then HMAC'd with the server-side salt. The salt is resolved
+ * at CALL time (`IP_HASH_SALT`, else `DEVICE_ID_SALT`, else empty) — an empty
+ * salt still hashes, which beats storing a raw IP; backends SHOULD set one of
+ * those envs. The `rl|` namespace ensures a rate-limit key can never collide
+ * with, or be correlated against, a deviceId derivation that reuses the same
+ * salt. The result is a short hex digest with no colons, so it is Redis-safe.
+ */
+function hashAnonymousIp(ip) {
+    const normalized = (0, node_net_1.isIPv6)(ip) && !ip.startsWith('::ffff:') ? maskIPv6(ip, IPV6_SUBNET_BITS) : ip;
+    const salt = process.env.IP_HASH_SALT || process.env.DEVICE_ID_SALT || '';
+    return (0, node_crypto_1.createHmac)('sha256', salt).update(`rl|${normalized}`).digest('hex').slice(0, 24);
+}
+/**
+ * Resolve the trusted authenticated rate-limit key.
+ *
+ * Only identities that came from a server-validated session or a verified
+ * service token/delegation may pick a bucket. `req.sessionId` is the marker
+ * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * back valid, so requiring it here means an identity written by some OTHER
+ * middleware — which this package cannot vouch for — shares the anonymous
+ * per-IP bucket rather than getting the authenticated quota.
+ */
+function resolveTrustedAuthenticatedKey(req) {
+    const userId = req.userId ?? req.user?.id ?? req.user?._id;
+    if (userId && req.sessionId) {
+        return `user:${userId}`;
+    }
+    const delegatedUserId = req.serviceActingAs?.userId;
+    if (delegatedUserId && req.serviceApp?.appId) {
+        return `user:${delegatedUserId}`;
+    }
+    const serviceAppId = req.serviceApp?.appId;
+    if (serviceAppId) {
+        return `service:${serviceAppId}`;
+    }
+    return null;
+}
+/** Resolve the rate-limit key: per trusted authenticated identity, else per hashed (IPv6-bucketed) IP. */
+function resolveKey(req) {
+    const authenticatedKey = resolveTrustedAuthenticatedKey(req);
+    if (authenticatedKey) {
+        return authenticatedKey;
+    }
+    const ip = req.ip || req.socket.remoteAddress;
+    if (!ip) {
+        return 'unknown';
+    }
+    return hashAnonymousIp(ip);
+}
+/**
+ * Build the composed Oxy rate-limit middleware. See module docs for rationale.
+ */
+function createOxyRateLimit(oxy, options = {}) {
+    const { authenticatedMax = 5000, anonymousMax = 600, windowMs = 15 * 60 * 1000, store, exempt, message = 'Too many requests, please try again later.', auth, } = options;
+    // Idempotent optional-auth resolver. Reuses the SAME session resolution as
+    // every protected route, so the limiter keys by the real user identity.
+    //
+    // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+    // because only the former skips resolution when a preceding middleware has
+    // already resolved a user. The raw middleware writes `req.userId = null` on
+    // every request it cannot authenticate, and because it mutates the shared
+    // `req` that erasure is visible to every handler downstream of the limiter,
+    // not just to the bucket calculation.
+    const resolveSession = (0, auth_1.createOptionalOxyAuth)(oxy, { auth });
+    const skip = (req) => isBuiltInExempt(req) || (exempt ? exempt(req) : false);
+    const limiter = (0, express_rate_limit_1.default)({
+        windowMs,
+        ...(store ? { store } : {}),
+        max: (req) => {
+            return resolveTrustedAuthenticatedKey(req)
+                ? authenticatedMax
+                : anonymousMax;
+        },
+        keyGenerator: (req) => resolveKey(req),
+        message,
+        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
+        // safe for static/streaming/health traffic.
+        if (skip(req)) {
+            next();
+            return;
+        }
+        resolveSession(req, res, (err) => {
+            if (err) {
+                // Optional auth never rejects; a token error just means "anonymous".
+                // Swallow the error and continue through the anonymous limiter.
+                limiter(req, res, next);
+                return;
+            }
+            limiter(req, res, next);
+        });
+    };
+}