@oxy.so/core 7.16.0 → 7.18.0

package/dist/cjs/server/callerAuthority.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * What every "may the person behind this request …?" read on `OxyServer`
+ * shares: which requests carry a person at all, the one failure type and its
+ * status mapping, the response envelope, and the positive-only answer cache.
+ *
+ * The readers built on it answer different questions — keep them apart:
+ *
+ * | Question | Reader |
+ * |---|---|
+ * | Does this person hold one of MY application's declared operator keys (`payments.operate`)? | `appPermissionsFor` (`./appPermissions`) |
+ * | What may this person do in Oxy account X (an organization, store, channel)? | `accountAccessFor` (`./callerAccess`) |
+ * | What may this person do to application A, through the account that owns it (`app:read`, `app:update`)? | `applicationAccessFor` (`./callerAccess`) |
+ *
+ * ## The outcome mapping, and why an outage is never a "no"
+ *
+ * Every reader asks Oxy with the request's OWN verified bearer and maps the
+ * answer the same way: a 401 means the session is gone (sign in again); a 403
+ * or 404 is Oxy's definitive refusal; anything else — a 5xx, a timeout, a
+ * malformed body — is UNAVAILABLE, answered 503. Only a positive answer is
+ * cached, so a blip can never be remembered as a refusal, and a refusal is
+ * never remembered at all (the next request asks again).
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallerAuthorityCache = exports.OxyAccessError = void 0;
+exports.readCallerSession = readCallerSession;
+exports.isBearerToken = isBearerToken;
+exports.accessErrorStatus = accessErrorStatus;
+exports.authorityErrorBody = authorityErrorBody;
+exports.errorStatus = errorStatus;
+exports.accessFailure = accessFailure;
+exports.permissionSet = permissionSet;
+/** Entries kept per reader; the oldest goes first. */
+const CALLER_AUTHORITY_CACHE_MAX = 1000;
+/**
+ * The person behind `req`, or why there is none: `service` for a request
+ * authenticated by a service token (delegated or not — its bearer is the
+ * service's, never the person's), `missing` when `middleware.auth()` resolved
+ * no user session.
+ */
+function readCallerSession(req) {
+    if (req.serviceApp)
+        return { ok: false, reason: 'service' };
+    const { userId, sessionId, accessToken } = req;
+    if (typeof userId !== 'string' ||
+        userId.length === 0 ||
+        typeof sessionId !== 'string' ||
+        sessionId.length === 0 ||
+        typeof accessToken !== 'string' ||
+        !isBearerToken(accessToken)) {
+        return { ok: false, reason: 'missing' };
+    }
+    return { ok: true, session: { userId, sessionId, accessToken } };
+}
+/** A bearer that can be put in an `Authorization` header unchanged. */
+function isBearerToken(token) {
+    return token.length > 0 && !/\s/.test(token);
+}
+/** The typed failure of `asUser`, `accountAccessFor`, `applicationAccessFor` and their middleware. */
+class OxyAccessError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'OxyAccessError';
+        this.code = code;
+        this.permission = options.permission;
+        this.cause = options.cause;
+    }
+}
+exports.OxyAccessError = OxyAccessError;
+/**
+ * The status for an {@link OxyAccessError}: `deny` (default `403`) for a
+ * refusal; `401` for no session (`404` when `deny` is `404`, so a hidden
+ * surface stays hidden from the signed-out too); `503` when Oxy could not say.
+ */
+function accessErrorStatus(error, deny = 403) {
+    switch (error.code) {
+        case 'ACCESS_DENIED':
+            return deny;
+        case 'ACCESS_SESSION_REQUIRED':
+            return deny === 404 ? 404 : 401;
+        case 'ACCESS_UNAVAILABLE':
+            return 503;
+    }
+}
+/** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
+function authorityErrorBody(status) {
+    switch (status) {
+        case 401:
+            return { error: { code: 'unauthorized', message: 'Authentication required' } };
+        case 403:
+            return { error: { code: 'forbidden', message: 'Not permitted' } };
+        case 404:
+            return { error: { code: 'not_found', message: 'Not found' } };
+        case 503:
+            return { error: { code: 'service_unavailable', message: 'Temporarily unavailable' } };
+        default:
+            return { error: { code: 'internal_error', message: 'Internal error' } };
+    }
+}
+/** The HTTP status an `OxyApiError` (or anything shaped like one) carries. */
+function errorStatus(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : undefined;
+}
+/**
+ * Map a failed caller-bearer read of Oxy to its outcome: 401 → session
+ * required, 403/404 → denied, everything else → unavailable.
+ */
+function accessFailure(error, what) {
+    const status = errorStatus(error);
+    if (status === 401) {
+        return new OxyAccessError('ACCESS_SESSION_REQUIRED', `Oxy refused the session reading ${what}`, {
+            cause: error,
+        });
+    }
+    if (status === 403 || status === 404) {
+        return new OxyAccessError('ACCESS_DENIED', `Oxy refused ${what} to this session`, {
+            cause: error,
+        });
+    }
+    return new OxyAccessError('ACCESS_UNAVAILABLE', `Could not read ${what} from Oxy`, {
+        cause: error,
+    });
+}
+/**
+ * The positive-only answer cache one caller-authority reader keeps, keyed by
+ * (resource, session, person). Concurrent identical reads share one lookup; a
+ * `fresh` read skips the cache and refreshes it; a slower, OLDER answer never
+ * overwrites a newer one (the newer may be the fresh read that saw a
+ * revocation); a failure is never stored.
+ */
+class CallerAuthorityCache {
+    /**
+     * @param ttlMs How long an answer is reused; `0` disables the cache.
+     * @param isAbout Whether a cached answer concerns `userId` beyond the
+     *   session's own user (an application-permissions answer names the
+     *   resolved operator), for {@link invalidate}.
+     */
+    constructor(ttlMs, isAbout = () => false) {
+        this.ttlMs = ttlMs;
+        this.isAbout = isAbout;
+        this.entries = new Map();
+        this.pending = new Map();
+    }
+    async read(resourceKey, session, fresh, lookup) {
+        const key = JSON.stringify([...resourceKey, session.sessionId, session.userId]);
+        const ttl = this.ttlMs;
+        if (!fresh && ttl > 0) {
+            const cached = this.entries.get(key);
+            if (cached && cached.expiresAt > Date.now())
+                return cached.value;
+            const inFlight = this.pending.get(key);
+            if (inFlight)
+                return inFlight;
+        }
+        const startedAt = Date.now();
+        const answer = lookup().then((value) => {
+            if (ttl > 0)
+                this.remember(key, session.userId, value, startedAt, ttl);
+            return value;
+        });
+        if (fresh || ttl <= 0)
+            return answer;
+        this.pending.set(key, answer);
+        try {
+            return await answer;
+        }
+        finally {
+            if (this.pending.get(key) === answer)
+                this.pending.delete(key);
+        }
+    }
+    /** Forget every answer, or those about one person. */
+    invalidate(filter = {}) {
+        const { userId } = filter;
+        if (!userId) {
+            this.entries.clear();
+            return;
+        }
+        for (const [key, entry] of this.entries) {
+            if (entry.userId === userId || this.isAbout(entry.value, userId))
+                this.entries.delete(key);
+        }
+    }
+    remember(key, userId, value, startedAt, ttl) {
+        const existing = this.entries.get(key);
+        if (existing && existing.startedAt > startedAt)
+            return;
+        this.entries.delete(key);
+        this.entries.set(key, { value, userId, startedAt, expiresAt: startedAt + ttl });
+        if (this.entries.size > CALLER_AUTHORITY_CACHE_MAX) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+    }
+}
+exports.CallerAuthorityCache = CallerAuthorityCache;
+/** A frozen, sorted permission set with `has`. */
+function permissionSet(permissions) {
+    const sorted = Object.freeze([...new Set(permissions)].sort());
+    const held = new Set(sorted);
+    return { permissions: sorted, has: (permission) => held.has(permission) };
+}

package/dist/cjs/server/capabilityTicket.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.inputSatisfiesCapabilityLimits = exports.CapabilityTicketError = void 0;
 exports.issueCapabilityTicket = issueCapabilityTicket;
 exports.verifyCapabilityTicket = verifyCapabilityTicket;
+exports.resolveCapabilityTicketKey = resolveCapabilityTicketKey;
 exports.readCapabilityAuthorization = readCapabilityAuthorization;
 exports.createCapabilityTicketMiddleware = createCapabilityTicketMiddleware;
 const node_crypto_1 = require("node:crypto");
@@ -49,7 +50,7 @@ function issueCapabilityTicket(claims, options) {
     const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(payload))}`;
     return `${signingInput}.${base64UrlEncode((0, node_crypto_1.sign)(null, Buffer.from(signingInput), options.privateKey))}`;
 }
-function verifyCapabilityTicket(token, options) {
+function parseCapabilityTicket(token) {
     const segments = token.split('.');
     if (segments.length !== 3) {
         throw new CapabilityTicketError('malformed', 'Capability ticket must have three segments');
@@ -70,21 +71,29 @@ function verifyCapabilityTicket(token, options) {
         headerRecord.kid.length === 0) {
         throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
     }
-    const publicKey = options.resolvePublicKey(headerRecord.kid);
+    return {
+        keyId: headerRecord.kid,
+        signingInput: `${encodedHeader}.${encodedPayload}`,
+        encodedPayload,
+        encodedSignature,
+    };
+}
+/** Signature and claims of a parsed ticket against the key its `kid` resolved to. */
+function checkCapabilityTicket(ticket, publicKey, options) {
     if (!publicKey || publicKey.asymmetricKeyType !== 'ed25519') {
         throw new CapabilityTicketError('unknown_key', 'Capability ticket signing key is not trusted');
     }
     let providedSignature;
     try {
-        providedSignature = Buffer.from(encodedSignature, 'base64url');
+        providedSignature = Buffer.from(ticket.encodedSignature, 'base64url');
     }
     catch {
         throw new CapabilityTicketError('malformed', 'Capability ticket signature is malformed');
     }
-    if (!(0, node_crypto_1.verify)(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), publicKey, providedSignature)) {
+    if (!(0, node_crypto_1.verify)(null, Buffer.from(ticket.signingInput), publicKey, providedSignature)) {
         throw new CapabilityTicketError('invalid_signature', 'Capability ticket signature is invalid');
     }
-    const parsed = contracts_1.capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(encodedPayload));
+    const parsed = contracts_1.capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(ticket.encodedPayload));
     if (!parsed.success) {
         throw new CapabilityTicketError('invalid_claims', 'Capability ticket claims are invalid');
     }
@@ -107,6 +116,30 @@ function verifyCapabilityTicket(token, options) {
     }
     return claims;
 }
+function verifyCapabilityTicket(token, options) {
+    const ticket = parseCapabilityTicket(token);
+    return checkCapabilityTicket(ticket, options.resolvePublicKey(ticket.keyId), options);
+}
+/**
+ * A verifier for one ticket whose key lookup may be asynchronous: the key is
+ * resolved once, and the returned `check` re-verifies signature and claims
+ * against it (the live verifier checks again after introspection, so a slow
+ * authority answer cannot outlive the ticket).
+ *
+ * @internal Shared by the middleware and `createLiveCapabilityTicketVerifier`.
+ */
+async function resolveCapabilityTicketKey(token, options) {
+    const ticket = parseCapabilityTicket(token);
+    let publicKey;
+    try {
+        publicKey = await options.resolvePublicKey(ticket.keyId);
+    }
+    catch {
+        // A key set that cannot be read trusts no key; never a different error class.
+        publicKey = undefined;
+    }
+    return { check: () => checkCapabilityTicket(ticket, publicKey, options) };
+}
 function readCapabilityAuthorization(authorization) {
     if (!authorization)
         return null;
@@ -129,7 +162,7 @@ function createCapabilityTicketMiddleware(options) {
         }
         let claims;
         try {
-            claims = verifyCapabilityTicket(token, options);
+            claims = (await resolveCapabilityTicketKey(token, options)).check();
         }
         catch (error) {
             const code = error instanceof CapabilityTicketError ? error.code : 'invalid_claims';

package/dist/cjs/server/cors.js

@@ -27,6 +27,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeAppOrigins = normalizeAppOrigins;
 exports.matchesAllowedOrigin = matchesAllowedOrigin;
+exports.createOxyOriginCheck = createOxyOriginCheck;
+exports.createOxySocketCors = createOxySocketCors;
 exports.createOxyCors = createOxyCors;
 const logger_1 = require("../logger");
 const authWebUrl_1 = require("../utils/authWebUrl");
@@ -163,6 +165,43 @@ function matchesAllowedOrigin(explicit, origin) {
         return true;
     return isOxyFamilyOrigin(normalized);
 }
+/**
+ * The origin predicate `createOxyCors` applies, for any other transport that
+ * must admit the same browsers: the built-in HTTPS Oxy apex family plus the
+ * exact `appOrigins`, never an opaque origin (`exp://`, `file:`, …).
+ *
+ * ```ts
+ * const allowed = createOxyOriginCheck(['https://app.example.com']);
+ * allowed('https://mention.oxy.so'); // true
+ * ```
+ */
+function createOxyOriginCheck(appOrigins = []) {
+    const explicit = normalizeAppOrigins(appOrigins);
+    return (origin) => matchesAllowedOrigin(explicit, origin);
+}
+/**
+ * The Socket.IO server options that admit exactly the origins `createOxyCors`
+ * admits — spread them into `new Server(httpServer, { ...createOxySocketCors(…) })`.
+ *
+ * Two halves, because Socket.IO has two transports: `cors` answers the
+ * long-polling requests (which browsers check), and `allowRequest` refuses a
+ * handshake from any other browser origin, which is the only check a WebSocket
+ * upgrade gets — browsers apply no CORS to it. A request with no `Origin`
+ * header (a native app, a server) is not a browser cross-origin request and is
+ * admitted; authenticate it with `oxy.middleware.socket()` as every socket.
+ */
+function createOxySocketCors(options = {}) {
+    const allowed = createOxyOriginCheck(options.appOrigins);
+    const admits = (origin) => origin === undefined || (typeof origin === 'string' && (origin === '' || allowed(origin)));
+    return {
+        cors: {
+            origin: (origin, callback) => callback(null, admits(origin)),
+            credentials: options.allowCredentials ?? true,
+            methods: ['GET', 'POST'],
+        },
+        allowRequest: (req, callback) => callback(null, admits(req.headers.origin)),
+    };
+}
 /**
  * Create a strict Oxy CORS middleware. See module docs.
  *
@@ -173,7 +212,7 @@ function matchesAllowedOrigin(explicit, origin) {
  */
 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 allowed = createOxyOriginCheck(appOrigins);
     const methodsHeader = methods.join(', ');
     const allowedHeadersHeader = allowedHeaders.join(', ');
     const exposedHeadersHeader = exposedHeaders.join(', ');
@@ -191,7 +230,7 @@ function createOxyCors(options = {}) {
         }
         // Origin is present. Caching correctness: this response varies by Origin.
         res.setHeader('Vary', 'Origin');
-        if (!matchesAllowedOrigin(explicitOrigins, origin)) {
+        if (!allowed(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).

package/dist/cjs/server/index.js

@@ -5,20 +5,39 @@
  * This subpath export provides Express middleware and Node.js-specific
  * utilities that are not available in React Native or browser environments.
  *
+ * One `OxyServer` per process, authenticated as the backend's own workload
+ * (ADR 0026/0049 — no api key, no client secret):
+ *
  * @example
  * ```ts
- * import { OxyServer, createOxyAuthMiddleware, createOxyRateLimit } from '@oxy.so/core/server';
+ * import {
+ *   OxyServer,
+ *   createOxyAuthMiddleware,
+ *   createOxyCors,
+ *   createOxyRateLimit,
+ *   createOxySecurityHeaders,
+ *   oxyTrustProxy,
+ * } from '@oxy.so/core/server';
  *
- * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', serviceAuth: { apiKey, apiSecret } });
+ * export const oxy = new OxyServer({
+ *   baseURL: process.env.OXY_API_URL ?? 'https://api.oxy.so',
+ *   applicationId: process.env.OXY_APPLICATION_ID,
+ *   serviceIdentity: 'when-anonymous',
+ * });
  *
+ * app.set('trust proxy', oxyTrustProxy);
+ * app.use(createOxySecurityHeaders(), createOxyCors({ appOrigins }));
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * app.use('/api', createOxyAuthMiddleware(oxy));
+ *
+ * // As the person behind the request, never on the shared client:
+ * const node = await oxy.withUser(req, (user) => user.accounts.get(accountId));
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.resolveClientIp = exports.oxyTrustProxy = exports.isPrivateProxyAddress = exports.isCloudflareAddress = exports.CLOUDFLARE_IPV6_RANGES = exports.CLOUDFLARE_IPV4_RANGES = 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.getOxyActor = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = exports.appPermissionErrorStatus = exports.OxyAppPermissionError = exports.APP_PERMISSIONS_CACHE_TTL_MS = exports.OXY_ACCOUNT_DELETED_EVENT_URI = exports.OxyAccountEventError = exports.OXY_ALIA_MACHINE_SCOPES = exports.OXY_ALIA_RESOURCE_APPLICATION_ID = exports.isOxyAliaMachinePrincipal = exports.getOxyAliaMachineCredentialBearer = exports.createOxyAliaMachineCredentialAuth = exports.ServerSessionApi = exports.ServerSafetyApi = exports.ServerReputationApi = exports.ServerNotificationsApi = exports.ServerLinkedAccountsApi = exports.ServerAssetsApi = exports.ServerAgencyApi = exports.ServerAppsApi = exports.ServerAccountsApi = exports.DEFAULT_SERVICE_TOKEN_AUDIENCE = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = exports.ServiceCredentialMismatchError = exports.OxyServer = void 0;
-exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.createLiveCapabilityTicketVerifier = exports.verifySecret = exports.verifyOxyAppAssertion = exports.verifyAppAssertion = exports.signOxyAppAssertion = exports.readOxyAppAssertionKeyId = exports.readAppAssertionHeader = exports.oxyAppAssertionClaimsSchema = exports.OxyAppAssertionError = exports.OXY_APP_ASSERTION_DEFAULT_ISSUER = exports.createOxyJwksKeyResolver = exports.verifyCapabilityTicket = exports.readCapabilityAuthorization = exports.issueCapabilityTicket = exports.inputSatisfiesCapabilityLimits = exports.createCapabilityTicketMiddleware = exports.CapabilityTicketError = exports.OXY_FILES_UPLOAD_ORIGIN = exports.OXY_CSP_BASELINE = exports.inlineScriptCspHash = exports.formatOxyCspPolicy = exports.extractInlineScripts = exports.cspSourcesFor = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.LargeUploadFailedError = exports.verifyStreamKeyAuthorization = exports.StreamKeyAuthorizationVerificationError = exports.STREAM_KEY_AUTHORIZATION_EVENT_TYPE = exports.verifyFileEventSignature = exports.FileEventVerificationError = exports.FILE_EVENT_TYPES = exports.FILE_EVENT_SIGNATURE_HEADER = exports.FILE_EVENT_DEFAULT_TOLERANCE_SECONDS = exports.withDeadline = exports.readResponseJson = exports.readResponseBody = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DNS_LOOKUP_TIMEOUT_MS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = void 0;
-exports.OxyRequesterClient = exports.signInAgentAccount = exports.hasBoundedServiceTokenLifetime = exports.OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.attestWorkloadIdentity = exports.withoutNodeHttpObservation = exports.observeNodeHttp = exports.createEcosystemTraffic = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.registrableApex = void 0;
+exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.resolveClientIp = exports.oxyTrustProxy = exports.isPrivateProxyAddress = exports.isCloudflareAddress = exports.CLOUDFLARE_IPV6_RANGES = exports.CLOUDFLARE_IPV4_RANGES = 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.getOxyActor = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = exports.appPermissionErrorStatus = exports.OxyAppPermissionError = exports.APP_PERMISSIONS_CACHE_TTL_MS = exports.OXY_ACCOUNT_DELETED_EVENT_URI = exports.OxyAccountEventError = exports.OXY_ALIA_MACHINE_SCOPES = exports.OXY_ALIA_RESOURCE_APPLICATION_ID = exports.isOxyAliaMachinePrincipal = exports.getOxyAliaMachineCredentialBearer = exports.createOxyAliaMachineCredentialAuth = exports.ServerSessionApi = exports.ServerSafetyApi = exports.ServerReputationApi = exports.ServerNotificationsApi = exports.ServerLinkedAccountsApi = exports.ServerAssetsApi = exports.ServerAgencyApi = exports.ServerAppsApi = exports.ServerAccountsApi = exports.accessErrorStatus = exports.OxyAccessError = exports.OxyUserClient = exports.DEFAULT_SERVICE_TOKEN_AUDIENCE = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = exports.ServiceCredentialMismatchError = exports.OxyServer = void 0;
+exports.createLiveCapabilityTicketVerifier = exports.verifySecret = exports.verifyOxyAppAssertion = exports.verifyAppAssertion = exports.signOxyAppAssertion = exports.readOxyAppAssertionKeyId = exports.readAppAssertionHeader = exports.oxyAppAssertionClaimsSchema = exports.OxyAppAssertionError = exports.OXY_APP_ASSERTION_DEFAULT_ISSUER = exports.createOxyJwksKeyResolver = exports.verifyCapabilityTicket = exports.readCapabilityAuthorization = exports.issueCapabilityTicket = exports.inputSatisfiesCapabilityLimits = exports.createCapabilityTicketMiddleware = exports.CapabilityTicketError = exports.OXY_FILES_UPLOAD_ORIGIN = exports.OXY_CSP_BASELINE = exports.inlineScriptCspHash = exports.formatOxyCspPolicy = exports.extractInlineScripts = exports.cspSourcesFor = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxySocketCors = exports.createOxyOriginCheck = exports.createOxyCors = exports.LargeUploadFailedError = exports.verifyStreamKeyAuthorization = exports.StreamKeyAuthorizationVerificationError = exports.STREAM_KEY_AUTHORIZATION_EVENT_TYPE = exports.verifyFileEventSignature = exports.FileEventVerificationError = exports.FILE_EVENT_TYPES = exports.FILE_EVENT_SIGNATURE_HEADER = exports.FILE_EVENT_DEFAULT_TOLERANCE_SECONDS = exports.withDeadline = exports.readResponseJson = exports.readResponseBody = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DNS_LOOKUP_TIMEOUT_MS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = void 0;
+exports.OxyRequesterClient = exports.signInAgentAccount = exports.hasBoundedServiceTokenLifetime = exports.OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.attestWorkloadIdentity = 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 = 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");
@@ -26,6 +45,13 @@ Object.defineProperty(exports, "OxyServer", { enumerable: true, get: function ()
 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; } });
 Object.defineProperty(exports, "DEFAULT_SERVICE_TOKEN_AUDIENCE", { enumerable: true, get: function () { return OxyServer_1.DEFAULT_SERVICE_TOKEN_AUDIENCE; } });
+// The requesting person: an isolated client bound to their bearer, and what
+// they may do in an account or over an application (with typed outcomes).
+var userClient_1 = require("./userClient");
+Object.defineProperty(exports, "OxyUserClient", { enumerable: true, get: function () { return userClient_1.OxyUserClient; } });
+var callerAuthority_1 = require("./callerAuthority");
+Object.defineProperty(exports, "OxyAccessError", { enumerable: true, get: function () { return callerAuthority_1.OxyAccessError; } });
+Object.defineProperty(exports, "accessErrorStatus", { enumerable: true, get: function () { return callerAuthority_1.accessErrorStatus; } });
 var namespaces_1 = require("./namespaces");
 Object.defineProperty(exports, "ServerAccountsApi", { enumerable: true, get: function () { return namespaces_1.ServerAccountsApi; } });
 Object.defineProperty(exports, "ServerAppsApi", { enumerable: true, get: function () { return namespaces_1.ServerAppsApi; } });
@@ -116,6 +142,8 @@ Object.defineProperty(exports, "LargeUploadFailedError", { enumerable: true, get
 // 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; } });
+Object.defineProperty(exports, "createOxyOriginCheck", { enumerable: true, get: function () { return cors_1.createOxyOriginCheck; } });
+Object.defineProperty(exports, "createOxySocketCors", { enumerable: true, get: function () { return cors_1.createOxySocketCors; } });
 // Shared Helmet + Content-Security-Policy baseline (Cloudflare Insights beacon,
 // Oxy API/CDN origins) with additive, per-app extensions.
 //

package/dist/cjs/server/liveCapabilityTicket.js

@@ -13,7 +13,9 @@ function createLiveCapabilityTicketVerifier(options) {
     }
     return async (ticket, input = {}) => {
         input.signal?.throwIfAborted();
-        const signed = (0, capabilityTicket_1.verifyCapabilityTicket)(ticket, options);
+        const verifier = await (0, capabilityTicket_1.resolveCapabilityTicketKey)(ticket, options);
+        input.signal?.throwIfAborted();
+        const signed = verifier.check();
         if (!signed.catalog)
             throw new Error('Internal MCP requires a signed catalogue binding');
         const controller = new AbortController();
@@ -39,7 +41,7 @@ function createLiveCapabilityTicketVerifier(options) {
             if ((0, contracts_1.canonicalCapabilityJson)(live) !== (0, contracts_1.canonicalCapabilityJson)(signed))
                 throw new Error('Capability introspection claims mismatch');
             // An authority response delayed past expiry cannot extend the signed grant.
-            return (0, capabilityTicket_1.verifyCapabilityTicket)(ticket, options);
+            return verifier.check();
         }
         finally {
             clearTimeout(timer);

package/dist/cjs/server/middleware.js

@@ -6,6 +6,7 @@ exports.parseJsonSegment = parseJsonSegment;
 exports.resolveServiceTokenPublicKey = resolveServiceTokenPublicKey;
 const serviceTokenLifetime_1 = require("./serviceTokenLifetime");
 const appPermissions_1 = require("./appPermissions");
+const callerAuthority_1 = require("./callerAuthority");
 const contracts_1 = require("@oxy.so/contracts");
 const jwt_decode_1 = require("jwt-decode");
 const protocol_1 = require("@oxy.so/protocol");
@@ -137,7 +138,7 @@ function createOxyMiddleware(host) {
      * @returns Express middleware function
      */
     function auth(options = {}) {
-        const { debug = false, onError, onRefusal, loadUser = false, optional = false, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', host.baseURL).toString(), expectedIssuer = exports.OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
+        const { debug = false, onError, onRefusal, loadUser = false, optional = false, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', host.baseURL).toString(), expectedIssuer = exports.OXY_JWT_ISSUER, expectedAudience = host.defaultAudience ?? OXY_JWT_AUDIENCE, } = options;
         const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer || options.liveSession);
         /**
          * Make a refusal observable to the HOST, without telling the client
@@ -1173,7 +1174,108 @@ function createOxyMiddleware(host) {
             res.status(status).json((0, appPermissions_1.appPermissionErrorBody)(status));
         };
     }
-    return { auth, socket, service, requireScope, requireAppPermission };
+    /**
+     * One gate for both caller-access readers: read the id from the route
+     * parameter, ask, admit on `permission`, answer a refusal by its outcome.
+     */
+    function requireCallerAccess(method, permission, options, read, admit) {
+        const { param, deny = 403, respond = true, ...lookup } = options;
+        if (typeof permission !== 'string' || permission.trim() === '') {
+            throw new Error(`${method}: permission must be a non-empty string`);
+        }
+        if (typeof param !== 'string' || param.trim() === '') {
+            throw new Error(`${method}: param must name the route parameter that holds the id`);
+        }
+        if (deny !== 403 && deny !== 404) {
+            throw new Error(`${method}: deny must be 403 or 404`);
+        }
+        return async (req, res, next) => {
+            let refusal;
+            const id = req.params?.[param];
+            try {
+                if (typeof id !== 'string' || id === '') {
+                    throw new callerAuthority_1.OxyAccessError('ACCESS_DENIED', `No ${param} on this route`);
+                }
+                const access = await read(req, id, lookup);
+                if (access.has(permission)) {
+                    admit(req, access);
+                    next();
+                    return;
+                }
+                refusal = new callerAuthority_1.OxyAccessError('ACCESS_DENIED', `Missing permission ${permission}`, {
+                    permission,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof callerAuthority_1.OxyAccessError)) {
+                    next(error);
+                    return;
+                }
+                refusal = new callerAuthority_1.OxyAccessError(error.code, error.message, {
+                    permission,
+                    cause: error.cause ?? error,
+                });
+            }
+            if (refusal.code === 'ACCESS_UNAVAILABLE') {
+                logger_1.logger.warn(`[oxy.auth] ${method} could not ask Oxy`, {
+                    component: 'auth',
+                    method,
+                    permission,
+                    path: req.path,
+                });
+            }
+            if (!respond) {
+                next(refusal);
+                return;
+            }
+            const status = (0, callerAuthority_1.accessErrorStatus)(refusal, deny);
+            res.status(status).json((0, callerAuthority_1.authorityErrorBody)(status));
+        };
+    }
+    /**
+     * Express middleware: the person behind the request must hold `permission`
+     * in the Oxy ACCOUNT named by the route parameter `param` (an organization,
+     * store, channel). Mount after `auth()`. On success the answer is on
+     * `req.oxyAccountAccess`. See `OxyServer.accountAccessFor`.
+     *
+     * @example
+     * ```typescript
+     * router.patch('/stores/:storeId', oxy.middleware.requireAccountAccess('account:update', { param: 'storeId', fresh: true }), handler);
+     * ```
+     */
+    function requireAccountAccess(permission, options) {
+        return requireCallerAccess('requireAccountAccess', permission, options, (req, id, lookup) => host.accountAccessFor(req, id, lookup), (req, access) => {
+            req.oxyAccountAccess = access;
+        });
+    }
+    /**
+     * Express middleware: the person behind the request must hold the
+     * application permission `permission` (`app:read`, `app:update`,
+     * `webhooks:update`, …) over the APPLICATION named by the route parameter
+     * `param`, through the account that owns it. Mount after `auth()`. On
+     * success the answer is on `req.oxyApplicationAccess`. See
+     * `OxyServer.applicationAccessFor`; for THIS backend's own operator keys use
+     * `requireAppPermission` instead.
+     *
+     * @example
+     * ```typescript
+     * router.get('/apps/:appId/payments', oxy.middleware.requireApplicationAccess('app:read', { param: 'appId' }), handler);
+     * ```
+     */
+    function requireApplicationAccess(permission, options) {
+        return requireCallerAccess('requireApplicationAccess', permission, options, (req, id, lookup) => host.applicationAccessFor(req, id, lookup), (req, access) => {
+            req.oxyApplicationAccess = access;
+        });
+    }
+    return {
+        auth,
+        socket,
+        service,
+        requireScope,
+        requireAppPermission,
+        requireAccountAccess,
+        requireApplicationAccess,
+    };
 }
 function isExactNonEmptyServiceClaim(value) {
     return typeof value === 'string' && value.length > 0 && value.trim() === value;

package/dist/cjs/server/namespaces.js

@@ -61,6 +61,14 @@ const SERVICE_RECONCILE_RATE_LIMIT_MAX_WAIT_MS = 60000;
 const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 /** A header value fetch accepts on every runtime: printable ASCII only. */
 const HEADER_SAFE_PATTERN = /^[\x20-\x7e]*$/;
+/** The `RequestOptions` half of {@link ServiceCallOptions}, only the fields that were set. */
+function serviceCallRequestOptions(options) {
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+        ...(options.retry !== undefined ? { retry: options.retry } : {}),
+    };
+}
 /** The headers both streamed service uploads share. */
 function uploadHeaders(mime, description) {
     return {
@@ -151,10 +159,13 @@ class ServerAssetsApi extends assets_1.AssetsApi {
          *   changes the file's visibility.
          * - `remove`: only references this application holds. Never trashes or
          *   deletes the file.
+         *
+         * Both take {@link ServiceCallOptions} for each request they send — e.g.
+         * `{ retry: false, timeout: 5000 }` from an outbox that retries by itself.
          */
         this.references = {
-            add: (references) => this.sendReferences('POST', references),
-            remove: (references) => this.sendReferences('DELETE', references),
+            add: (references, options = {}) => this.sendReferences('POST', references, options),
+            remove: (references, options = {}) => this.sendReferences('DELETE', references, options),
             /**
              * Reconcile this application's references of ONE entity type with its
              * real inventory (ADR 0043 D6) — the safety net for a reference a crash or
@@ -313,13 +324,13 @@ class ServerAssetsApi extends assets_1.AssetsApi {
             await release();
         return result;
     }
-    async sendReferences(method, references) {
+    async sendReferences(method, references, options) {
         const results = [];
         for (let start = 0; start < references.length; start += SERVICE_REFERENCES_CHUNK_SIZE) {
             const chunk = references
                 .slice(start, start + SERVICE_REFERENCES_CHUNK_SIZE)
                 .map(({ fileId, entityType, entityId }) => ({ fileId, entityType, entityId }));
-            const res = await lane(this.ctx).request(method, '/assets/service/references', { references: chunk }, { cache: false });
+            const res = await lane(this.ctx).request(method, '/assets/service/references', { references: chunk }, { ...serviceCallRequestOptions(options), cache: false });
             results.push(...res.results);
         }
         return results;