@oxy.so/core 1.18.0 → 3.0.0

package/dist/cjs/server/OxyServer.js

@@ -0,0 +1,521 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServer = exports.ServiceCredentialMismatchError = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = void 0;
+/**
+ * `OxyServer` — the Oxy client for a backend.
+ *
+ * ```ts
+ * import { OxyServer } from '@oxy.so/core/server';
+ *
+ * const oxy = new OxyServer({
+ *   baseURL: 'https://api.oxy.so',
+ *   serviceAuth: { apiKey: process.env.OXY_SERVICE_API_KEY!, apiSecret: process.env.OXY_SERVICE_API_SECRET! },
+ * });
+ *
+ * app.use('/api', oxy.middleware.auth());
+ * io.use(oxy.middleware.socket());
+ * app.use('/internal', oxy.middleware.service(), oxy.middleware.requireScope('files:read'));
+ *
+ * const people = await oxy.users.getMany(ids);           // service lane when available
+ * const meta = await oxy.assets.metadataByIds(fileIds);  // service-only
+ * ```
+ *
+ * Everything `OxyServices` has, plus the service-token lane (a key pair from
+ * `serviceAuth` / `configureServiceAuth`, or — with neither — the process's
+ * attested workload identity, ADR 0026), the Express / Socket.IO middleware,
+ * account events, and the service-only methods of `assets`, `notifications`,
+ * `linkedAccounts`, `agency` and `reputation`.
+ *
+ * Node only.
+ */
+const jwt_decode_1 = require("jwt-decode");
+const protocol_1 = require("@oxy.so/protocol");
+const OxyServices_1 = require("../OxyServices");
+const logger_1 = require("../logger");
+const workloadIdentity_1 = require("./workloadIdentity");
+const middleware_1 = require("./middleware");
+const namespaces_1 = require("./namespaces");
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
+/**
+ * Sentinel error raised when a service token is asked for with a known apiKey
+ * but a non-matching secret: credential drift in the caller, or a cross-tenant
+ * cache lookup attempt. Surface as a 401-equivalent.
+ */
+class ServiceCredentialMismatchError extends Error {
+    constructor() {
+        super('Service credential mismatch: provided secret does not match the secret stored for this apiKey');
+        this.name = 'ServiceCredentialMismatchError';
+    }
+}
+exports.ServiceCredentialMismatchError = ServiceCredentialMismatchError;
+const WORKLOAD_CACHE_KEY = 'workload-identity';
+/** A token is reused until 60s before expiry (clock drift). */
+const TOKEN_REUSE_MARGIN_MS = 60000;
+/** Bound on remembered `appId:userId` delegation answers. */
+const ACTING_AS_CACHE_MAX = 1000;
+/** A positive grant is reused for 5 minutes — the revocation latency window. */
+const ACTING_AS_GRANT_TTL_MS = 5 * 60 * 1000;
+/** A negative answer (or a failed lookup) is reused for 1 minute. */
+const ACTING_AS_DENIAL_TTL_MS = 60 * 1000;
+class OxyServer extends OxyServices_1.OxyServices {
+    constructor(config) {
+        super(config);
+        this.serviceTokens = new Map();
+        this.serviceApiKey = null;
+        this.serviceApiSecret = null;
+        this.actingAs = new Map();
+        this.actingAsPending = new Map();
+        /** Public keys only; never private material. */
+        this.jwksCache = { keys: new Map(), expiresAt: 0, lastAttemptAt: 0 };
+        /**
+         * Before this instant a request without a user session does not try to mint
+         * a service token and goes out anonymous. Set after a failed mint.
+         */
+        this.anonymousServiceTokenRetryAt = 0;
+        /**
+         * Account events addressed to this application (Oxy account deletions every
+         * relying application must honour, OxyHQ/Mention#1169).
+         */
+        this.accountEvents = {
+            /**
+             * Verify an account event token — a webhook body, or a feed entry's `token`
+             * — and return the event. Throws {@link OxyAccountEventError} unless it is
+             * an EdDSA `secevent+jwt` from Oxy's key set, issued by `oxy-auth`,
+             * addressed to this application, carrying exactly one known event. Be
+             * idempotent on `eventId`: Oxy delivers at least once.
+             */
+            verify: (token, options = {}) => this.verifyAccountEvent(token, options),
+            /**
+             * One page of account events for this application, oldest first — the pull
+             * feed behind the webhook. Verify each entry's `token` before acting on it.
+             */
+            list: async (options = {}) => {
+                const query = {};
+                if (options.after)
+                    query.after = options.after;
+                if (options.limit !== undefined)
+                    query.limit = String(options.limit);
+                return this.serviceRequest('GET', '/account-events', query);
+            },
+        };
+        if (config.serviceAuth) {
+            this.configureServiceAuth(config.serviceAuth.apiKey, config.serviceAuth.apiSecret);
+        }
+        const server = this;
+        const serviceLane = {
+            get available() {
+                return server.canMintServiceToken();
+            },
+            request: (...args) => this.serviceRequest(...args),
+        };
+        this.context.service = serviceLane;
+        if (config.serviceIdentity === 'when-anonymous') {
+            this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest());
+        }
+        this.middleware = (0, middleware_1.createOxyMiddleware)({
+            get baseURL() {
+                return server.baseURL;
+            },
+            jwksCache: this.jwksCache,
+            validateSession: (sessionId, options) => this.session.validate(sessionId, options),
+            verifyActingAs: (appId, userId) => this.verifyActingAs(appId, userId),
+        });
+    }
+    /** Files, plus the service-only metadata and linked-URL lookups. */
+    get assets() {
+        if (!this._serverAssets)
+            this._serverAssets = new namespaces_1.ServerAssetsApi(this.context);
+        return this._serverAssets;
+    }
+    /** The inbox and push tokens, plus `create`. */
+    get notifications() {
+        if (!this._serverNotifications)
+            this._serverNotifications = new namespaces_1.ServerNotificationsApi(this.context);
+        return this._serverNotifications;
+    }
+    /** Linked external accounts, plus `forUser`. */
+    get linkedAccounts() {
+        if (!this._serverLinkedAccounts)
+            this._serverLinkedAccounts = new namespaces_1.ServerLinkedAccountsApi(this.context);
+        return this._serverLinkedAccounts;
+    }
+    /** Delegated capabilities, plus `introspectRequesterAssertion`. */
+    get agency() {
+        if (!this._serverAgency)
+            this._serverAgency = new namespaces_1.ServerAgencyApi(this.context);
+        return this._serverAgency;
+    }
+    /** Reputation reads, plus `award`. */
+    get reputation() {
+        if (!this._serverReputation)
+            this._serverReputation = new namespaces_1.ServerReputationApi(this.context);
+        return this._serverReputation;
+    }
+    // ── Service token ────────────────────────────────────────────────────────
+    /**
+     * Set this service's application credential. Each `(apiKey, apiSecret)` pair
+     * is cached independently, so a multi-tenant host switching credentials
+     * cannot leak one tenant's token to another.
+     */
+    configureServiceAuth(apiKey, apiSecret) {
+        this.serviceApiKey = apiKey;
+        this.serviceApiSecret = apiSecret;
+    }
+    /**
+     * A service token (short-lived, cached and refreshed per credential pair;
+     * concurrent callers share one mint).
+     *
+     * With no credential configured or passed, the token comes from the process's
+     * attested workload identity (ADR 0026); with neither, this throws.
+     *
+     * If the cache already holds a token for `apiKey` but `apiSecret` does not
+     * constant-time match the secret that produced it, this throws
+     * {@link ServiceCredentialMismatchError} rather than return the cached token.
+     */
+    async serviceToken(apiKey, apiSecret) {
+        const key = apiKey || this.serviceApiKey;
+        const secret = apiSecret || this.serviceApiSecret;
+        if (!key || !secret) {
+            // No credential — prove what this process IS instead. The fallback, not the
+            // preference: a deployment that still has a credential keeps using it.
+            if ((0, workloadIdentity_1.canAttestWorkloadIdentity)()) {
+                return this.workloadServiceToken();
+            }
+            throw new Error('Service credentials not provided. Pass serviceAuth, call configureServiceAuth(), or pass apiKey and apiSecret.');
+        }
+        // The apiKey is the credential's PUBLIC id (`oxy_dk_…`, the OAuth
+        // client_id), so it keys the in-memory cache as is; the secret never does.
+        const cacheKey = key;
+        const now = Date.now();
+        const providedSecretBuf = Buffer.from(secret, 'utf8');
+        let entry = this.serviceTokens.get(cacheKey);
+        if (entry) {
+            // Verify the secret on every hit, fresh token or not. Constant-time, and
+            // run on equal-length inputs even when the lengths differ.
+            const nodeCrypto = await (0, protocol_1.loadNodeCrypto)();
+            const stored = entry.secretBuf;
+            const lengthMatch = stored.length === providedSecretBuf.length;
+            const compareBuf = lengthMatch ? providedSecretBuf : Buffer.alloc(stored.length);
+            const equal = nodeCrypto.timingSafeEqual(stored, compareBuf);
+            if (!lengthMatch || !equal) {
+                logger_1.logger.warn('[oxy.auth] Service token cache hit with mismatched secret', {
+                    component: 'auth',
+                    method: 'serviceToken',
+                });
+                throw new ServiceCredentialMismatchError();
+            }
+            if (entry.token && entry.expiresAt > now + TOKEN_REUSE_MARGIN_MS) {
+                return entry.token;
+            }
+            if (entry.pending) {
+                return entry.pending;
+            }
+        }
+        else {
+            // Seed an empty entry so concurrent callers serialize on one promise.
+            entry = { token: '', expiresAt: 0, secretBuf: providedSecretBuf, pending: null, apiKey: key };
+            this.serviceTokens.set(cacheKey, entry);
+        }
+        const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf);
+        entry.pending = pending;
+        try {
+            return await pending;
+        }
+        catch (error) {
+            // Never keep an entry that never held a token: a wrong first secret must
+            // not make the right one fail locally as a mismatch later.
+            const failed = this.serviceTokens.get(cacheKey);
+            if (failed?.pending === pending && !failed.token) {
+                this.serviceTokens.delete(cacheKey);
+            }
+            throw error;
+        }
+        finally {
+            const settled = this.serviceTokens.get(cacheKey);
+            if (settled?.pending === pending)
+                settled.pending = null;
+        }
+    }
+    /**
+     * Forget cached service token(s) so the next `serviceToken()` mints anew —
+     * the way back from a 401 after a credential was revoked or rotated.
+     *
+     * `apiKey` clears that credential's entry; with none, the configured
+     * credential's; with neither, every entry. Synchronous.
+     */
+    invalidateServiceToken(apiKey) {
+        const targetKey = apiKey ?? this.serviceApiKey;
+        if (!targetKey) {
+            this.serviceTokens.clear();
+            return;
+        }
+        this.serviceTokens.delete(targetKey);
+    }
+    /**
+     * One request with this service's token. `actAs` sends `X-Oxy-User-Id`: the
+     * request is on behalf of that user (the API checks the delegation grant).
+     * Never cached unless `cache` says so. Rejects with `OxyApiError`.
+     */
+    async serviceRequest(method, url, data, options = {}) {
+        const { actAs, headers, ...rest } = options;
+        const token = await this.serviceToken();
+        const merged = { ...headers, Authorization: `Bearer ${token}` };
+        if (actAs)
+            merged['X-Oxy-User-Id'] = actAs;
+        return this.request(method, url, data, { cache: false, ...rest, headers: merged });
+    }
+    // ── Delegation and account events ────────────────────────────────────────
+    /**
+     * Whether service app `appId` holds an active delegation grant to act for
+     * `userId`; the grant's scopes, or `null`. Used by `middleware.auth()` for
+     * `X-Oxy-User-Id`.
+     *
+     * Answers are cached per `appId:userId` (a grant for 5 minutes — the
+     * revocation window; a denial or failed lookup for 1 minute), bounded to the
+     * 1000 most recent pairs, and concurrent lookups of one pair share a single
+     * request.
+     */
+    async verifyActingAs(appId, userId) {
+        const cacheKey = `${appId}:${userId}`;
+        const cached = this.actingAs.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            // Refresh recency for the LRU bound.
+            this.actingAs.delete(cacheKey);
+            this.actingAs.set(cacheKey, cached);
+            return cached.result;
+        }
+        const inflight = this.actingAsPending.get(cacheKey);
+        if (inflight)
+            return inflight;
+        const lookup = this.lookupActingAs(appId, userId).finally(() => {
+            this.actingAsPending.delete(cacheKey);
+        });
+        this.actingAsPending.set(cacheKey, lookup);
+        return lookup;
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    /**
+     * The bearer for a request with no user session, under `serviceIdentity:
+     * 'when-anonymous'`: this process's service token, or `null` to send the
+     * request anonymous.
+     *
+     * `null`, never a throw, whenever there is no token to offer:
+     * - no key pair and no attestable workload (a local checkout);
+     * - the mint failed. The request still goes out, anonymous, and so does every
+     *   request for the next {@link ANONYMOUS_SERVICE_TOKEN_RETRY_MS}, so an Oxy
+     *   refusing attestation is asked once per window rather than once per read.
+     *
+     * The token comes from {@link serviceToken}: cached and single-flight, so
+     * concurrent reads share one mint.
+     */
+    async serviceTokenForAnonymousRequest() {
+        if (Date.now() < this.anonymousServiceTokenRetryAt)
+            return null;
+        if (!this.canMintServiceToken())
+            return null;
+        try {
+            return await this.serviceToken();
+        }
+        catch (error) {
+            this.anonymousServiceTokenRetryAt = Date.now() + exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS;
+            logger_1.logger.warn('[oxy.auth] No service token for a request without a session; sending it anonymous', {
+                component: 'auth',
+                method: 'serviceTokenForAnonymousRequest',
+                retryInMs: exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    canMintServiceToken() {
+        return Boolean(this.serviceApiKey && this.serviceApiSecret) || (0, workloadIdentity_1.canAttestWorkloadIdentity)();
+    }
+    async mintServiceToken(key, secret, cacheKey, secretBuf) {
+        const response = await this.request('POST', '/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false, skipAuth: true });
+        const expiresAt = Date.now() + response.expiresIn * 1000;
+        const entry = this.serviceTokens.get(cacheKey);
+        if (entry) {
+            entry.token = response.token;
+            entry.expiresAt = expiresAt;
+            entry.secretBuf = secretBuf;
+        }
+        else {
+            this.serviceTokens.set(cacheKey, { token: response.token, expiresAt, secretBuf, pending: null, apiKey: key });
+        }
+        return response.token;
+    }
+    /** A token obtained by attestation, cached like a credential's (one identity per process). */
+    async workloadServiceToken() {
+        const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+        if (entry?.token && entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS)
+            return entry.token;
+        if (entry?.pending)
+            return entry.pending;
+        const seeded = entry ?? { token: '', expiresAt: 0, secretBuf: Buffer.alloc(0), pending: null, apiKey: WORKLOAD_CACHE_KEY };
+        this.serviceTokens.set(WORKLOAD_CACHE_KEY, seeded);
+        const pending = (async () => {
+            const granted = await (0, workloadIdentity_1.requestWorkloadServiceToken)({ baseUrl: this.baseURL });
+            const current = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            if (current) {
+                current.token = granted.token;
+                current.expiresAt = Date.now() + granted.expiresIn * 1000;
+            }
+            return granted.token;
+        })();
+        seeded.pending = pending;
+        try {
+            return await pending;
+        }
+        catch (error) {
+            const failed = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            if (failed?.pending === pending && !failed.token)
+                this.serviceTokens.delete(WORKLOAD_CACHE_KEY);
+            throw error;
+        }
+        finally {
+            const settled = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            if (settled?.pending === pending)
+                settled.pending = null;
+        }
+    }
+    async lookupActingAs(appId, userId) {
+        try {
+            // The verify endpoint admits only a platform-trusted caller, so this
+            // carries the VERIFIER's own service token. No retry and a short timeout:
+            // it runs inside request-handling middleware, and a retry loop would
+            // multiply the latency of every delegated request. A verifier with no
+            // credential throws here and is refused below — a host that cannot prove
+            // who it is has no business learning who delegated to whom.
+            const serviceToken = await this.serviceToken();
+            const result = await this.request('GET', '/internal/service-acting-as/verify', { appId, userId }, { cache: false, retry: false, timeout: 5000, headers: { Authorization: `Bearer ${serviceToken}` } });
+            const verified = result?.authorized
+                ? { authorized: true, scopes: Array.isArray(result.scopes) ? result.scopes : [] }
+                : null;
+            this.rememberActingAs(`${appId}:${userId}`, verified, ACTING_AS_GRANT_TTL_MS);
+            return verified;
+        }
+        catch (error) {
+            logger_1.logger.warn('[oxy.auth] verifyActingAs lookup failed — caching negative result', {
+                component: 'auth',
+                method: 'verifyActingAs',
+                appId,
+                userId,
+            }, error);
+            this.rememberActingAs(`${appId}:${userId}`, null, ACTING_AS_DENIAL_TTL_MS);
+            return null;
+        }
+    }
+    rememberActingAs(cacheKey, result, ttlMs) {
+        this.actingAs.delete(cacheKey);
+        this.actingAs.set(cacheKey, { result, expiresAt: Date.now() + ttlMs });
+        if (this.actingAs.size > ACTING_AS_CACHE_MAX) {
+            const oldest = this.actingAs.keys().next().value;
+            if (oldest !== undefined)
+                this.actingAs.delete(oldest);
+        }
+    }
+    async verifyAccountEvent(token, options) {
+        if (typeof token !== 'string' || token.length === 0 || token.length > 16 * 1024) {
+            throw new middleware_1.OxyAccountEventError('Account event token is missing or oversized');
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+            throw new middleware_1.OxyAccountEventError('Account event token is not a compact JWS');
+        }
+        const [headerB64, payloadB64, signatureB64] = parts;
+        let header;
+        let payload;
+        try {
+            header = (0, middleware_1.parseJsonSegment)(headerB64);
+            payload = (0, middleware_1.parseJsonSegment)(payloadB64);
+        }
+        catch {
+            throw new middleware_1.OxyAccountEventError('Account event token is malformed');
+        }
+        if (Object.keys(header).length !== 3
+            || header.alg !== 'EdDSA'
+            || header.typ !== 'secevent+jwt'
+            || typeof header.kid !== 'string'
+            || !/^[A-Za-z0-9._-]{1,128}$/.test(header.kid)) {
+            throw new middleware_1.OxyAccountEventError('Account event token header is not supported');
+        }
+        const nodeCrypto = await (0, protocol_1.loadNodeCrypto)();
+        let jwk;
+        try {
+            jwk = await (0, middleware_1.resolveServiceTokenPublicKey)(header.kid, options.jwksUrl ?? new URL('/.well-known/jwks.json', this.baseURL).toString(), this.jwksCache);
+        }
+        catch (error) {
+            throw new middleware_1.OxyAccountEventError(error instanceof Error ? error.message.replace('Service token', 'Account event') : 'Signing key is unavailable');
+        }
+        const signature = Buffer.from(signatureB64, 'base64url');
+        if (signature.toString('base64url') !== signatureB64 || signature.length !== 64) {
+            throw new middleware_1.OxyAccountEventError('Account event token signature is malformed');
+        }
+        let verified = false;
+        try {
+            const publicKey = nodeCrypto.createPublicKey({ key: jwk, format: 'jwk' });
+            verified = nodeCrypto.verify(null, Buffer.from(`${headerB64}.${payloadB64}`), publicKey, signature);
+        }
+        catch {
+            verified = false;
+        }
+        if (!verified)
+            throw new middleware_1.OxyAccountEventError('Account event token signature is invalid');
+        if (payload.iss !== middleware_1.OXY_JWT_ISSUER) {
+            throw new middleware_1.OxyAccountEventError('Account event token issuer is not Oxy');
+        }
+        const audience = options.audience ?? await this.configuredServiceAppId();
+        if (typeof payload.aud !== 'string' || payload.aud !== audience) {
+            throw new middleware_1.OxyAccountEventError('Account event token is addressed to another application');
+        }
+        if (typeof payload.jti !== 'string' || payload.jti.length === 0 || payload.jti.length > 128) {
+            throw new middleware_1.OxyAccountEventError('Account event token has no event id');
+        }
+        if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat)) {
+            throw new middleware_1.OxyAccountEventError('Account event token has no issue time');
+        }
+        const events = payload.events;
+        if (typeof events !== 'object' || events === null || Array.isArray(events)) {
+            throw new middleware_1.OxyAccountEventError('Account event token carries no events');
+        }
+        const entries = Object.entries(events);
+        const deleted = events[middleware_1.OXY_ACCOUNT_DELETED_EVENT_URI];
+        if (entries.length !== 1 || typeof deleted !== 'object' || deleted === null || Array.isArray(deleted)) {
+            throw new middleware_1.OxyAccountEventError('Account event token carries an unknown event');
+        }
+        const body = deleted;
+        if (typeof body.userId !== 'string' || body.userId.length === 0 || body.userId.length > 128) {
+            throw new middleware_1.OxyAccountEventError('Account event names no account');
+        }
+        if (typeof body.occurredAt !== 'string' || Number.isNaN(Date.parse(body.occurredAt))) {
+            throw new middleware_1.OxyAccountEventError('Account event has no occurrence time');
+        }
+        if (body.username !== undefined && body.username !== null && typeof body.username !== 'string') {
+            throw new middleware_1.OxyAccountEventError('Account event username is malformed');
+        }
+        return {
+            eventId: payload.jti,
+            type: 'account.deleted',
+            userId: body.userId,
+            username: typeof body.username === 'string' ? body.username : null,
+            occurredAt: body.occurredAt,
+            retained: body.retained === true,
+            applicationId: payload.aud,
+            issuedAt: payload.iat,
+        };
+    }
+    /** The `appId` claim of this service's own token. */
+    async configuredServiceAppId() {
+        const serviceToken = await this.serviceToken();
+        const appId = (0, jwt_decode_1.jwtDecode)(serviceToken).appId;
+        if (typeof appId !== 'string' || appId.length === 0) {
+            throw new middleware_1.OxyAccountEventError('No audience given and the service credential names no application');
+        }
+        return appId;
+    }
+}
+exports.OxyServer = OxyServer;

package/dist/cjs/server/auth.js

@@ -125,7 +125,7 @@ function getRequiredOxyUserId(req) {
  * Why the credential on this request was refused, or `null` when none was
  * presented (or it was accepted).
  *
- * Set by `oxy.auth()` — including the `optional: true` mount the composed
+ * Set by `server.middleware.auth()` — including the `optional: true` mount the composed
  * helpers use, where a refusal otherwise leaves no trace: the request simply
  * arrives unauthenticated and the host answers its own generic 401. Hosts log
  * this beside their own 401; it is diagnostic and **must not be put into a
@@ -163,7 +163,7 @@ function requireOxyAuth(req, res, next) {
     next();
 }
 function createOptionalOxyAuth(oxy, options = {}) {
-    const resolveSession = oxy.auth({ ...options.auth, optional: true });
+    const resolveSession = oxy.middleware.auth({ ...options.auth, optional: true });
     return (req, res, next) => {
         if (getOxyUserId(req)) {
             next();

package/dist/cjs/server/index.js

@@ -7,17 +7,32 @@
  *
  * @example
  * ```ts
- * import { createOxyRateLimit } from '@oxy.so/core/server';
- * import { oxyClient } from '@oxy.so/core';
+ * import { OxyServer, createOxyAuthMiddleware, createOxyRateLimit } from '@oxy.so/core/server';
  *
- * const oxy = oxyClient({ apiUrl: 'https://api.oxy.so' });
+ * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', serviceAuth: { apiKey, apiSecret } });
  *
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
+ * app.use('/api', createOxyAuthMiddleware(oxy));
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.signOxyRequesterAssertion = exports.readOxyRequesterAssertionKeyId = exports.oxyRequesterAssertionClaimsSchema = exports.OxyRequesterAssertionError = exports.OXY_REQUESTER_ASSERTION_TYPE = exports.OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS = exports.OXY_REQUESTER_ASSERTION_HEADER = exports.OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER = exports.createOxyRequesterAssertionAuth = exports.createOxyJwksKeyResolver = 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.getOxyAuthRefusal = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
-exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.withoutNodeHttpObservation = exports.observeNodeHttp = exports.createEcosystemTraffic = exports.isOfficialWebOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.verifySecret = exports.verifyOxyRequesterAssertion = void 0;
+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.getOxyAuthRefusal = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = exports.OXY_ACCOUNT_DELETED_EVENT_URI = exports.OxyAccountEventError = exports.ServerReputationApi = exports.ServerNotificationsApi = exports.ServerLinkedAccountsApi = exports.ServerAssetsApi = exports.ServerAgencyApi = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = exports.ServiceCredentialMismatchError = exports.OxyServer = void 0;
+exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.withoutNodeHttpObservation = exports.observeNodeHttp = exports.createEcosystemTraffic = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.verifySecret = exports.verifyOxyRequesterAssertion = exports.signOxyRequesterAssertion = exports.readOxyRequesterAssertionKeyId = exports.oxyRequesterAssertionClaimsSchema = exports.OxyRequesterAssertionError = exports.OXY_REQUESTER_ASSERTION_TYPE = exports.OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS = exports.OXY_REQUESTER_ASSERTION_HEADER = exports.OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER = exports.createOxyRequesterAssertionAuth = exports.createOxyJwksKeyResolver = void 0;
+// The backend client: OxyServices plus the service-token lane, middleware,
+// account events and the service-only namespace methods.
+var OxyServer_1 = require("./OxyServer");
+Object.defineProperty(exports, "OxyServer", { enumerable: true, get: function () { return OxyServer_1.OxyServer; } });
+Object.defineProperty(exports, "ServiceCredentialMismatchError", { enumerable: true, get: function () { return OxyServer_1.ServiceCredentialMismatchError; } });
+Object.defineProperty(exports, "ANONYMOUS_SERVICE_TOKEN_RETRY_MS", { enumerable: true, get: function () { return OxyServer_1.ANONYMOUS_SERVICE_TOKEN_RETRY_MS; } });
+var namespaces_1 = require("./namespaces");
+Object.defineProperty(exports, "ServerAgencyApi", { enumerable: true, get: function () { return namespaces_1.ServerAgencyApi; } });
+Object.defineProperty(exports, "ServerAssetsApi", { enumerable: true, get: function () { return namespaces_1.ServerAssetsApi; } });
+Object.defineProperty(exports, "ServerLinkedAccountsApi", { enumerable: true, get: function () { return namespaces_1.ServerLinkedAccountsApi; } });
+Object.defineProperty(exports, "ServerNotificationsApi", { enumerable: true, get: function () { return namespaces_1.ServerNotificationsApi; } });
+Object.defineProperty(exports, "ServerReputationApi", { enumerable: true, get: function () { return namespaces_1.ServerReputationApi; } });
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "OxyAccountEventError", { enumerable: true, get: function () { return middleware_1.OxyAccountEventError; } });
+Object.defineProperty(exports, "OXY_ACCOUNT_DELETED_EVENT_URI", { enumerable: true, get: function () { return middleware_1.OXY_ACCOUNT_DELETED_EVENT_URI; } });
 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; } });
@@ -97,7 +112,7 @@ 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
+// client namespaces 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; } });
@@ -110,7 +125,9 @@ Object.defineProperty(exports, "OXY_IDENTITY_CACHE_PREFIXES", { enumerable: true
 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, "isLoopbackOrigin", { enumerable: true, get: function () { return officialOrigins_1.isLoopbackOrigin; } });
 Object.defineProperty(exports, "isOfficialWebOrigin", { enumerable: true, get: function () { return officialOrigins_1.isOfficialWebOrigin; } });
+Object.defineProperty(exports, "isAllowedDeviceJoinOrigin", { enumerable: true, get: function () { return officialOrigins_1.isAllowedDeviceJoinOrigin; } });
 var traffic_1 = require("./traffic");
 Object.defineProperty(exports, "createEcosystemTraffic", { enumerable: true, get: function () { return traffic_1.createEcosystemTraffic; } });
 var trafficNodeHttp_1 = require("./trafficNodeHttp");