@oxyhq/core 21.0.0 → 21.0.2

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

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * The inference API, reached with whatever bearer this session already holds
+ * (issue #972, workstream 15).
+ *
+ * ```typescript
+ * const models = await oxyServices.inference().listModels();
+ * ```
+ *
+ * One method, and it is a FACTORY rather than a set of inference methods on
+ * `OxyServices`. The calls themselves live once, in
+ * {@link OxyInferenceClient} — which an external developer holding only an
+ * `oxy_sk_…` machine key constructs directly, with no Oxy session anywhere in
+ * the picture. Declaring the same calls a second time here would give the
+ * ecosystem two spellings of one request, and only one of them would stay
+ * correct.
+ *
+ * This is the reasoning `createLinkedClient` is already built on: the plumbing
+ * that binds an Oxy bearer to a client belongs in core, once, rather than in
+ * each app.
+ *
+ * The credential is a FUNCTION, not the current token: a session bearer rotates
+ * on refresh and on account switch, and a client that captured one at
+ * construction would start answering 401 an hour into the process's life.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesInferenceMixin = OxyServicesInferenceMixin;
+const OxyInferenceClient_1 = require("../inference/OxyInferenceClient");
+function OxyServicesInferenceMixin(Base) {
+    return class extends Base {
+        constructor() {
+            super(...arguments);
+            /** @internal Memoized so repeated calls return one object identity. */
+            this._inferenceClient = null;
+        }
+        /**
+         * The inference client for this session.
+         *
+         * Bound to this instance's base URL and to `getAccessToken()`, so it
+         * follows every refresh, sign-in and account switch without being
+         * rebuilt.
+         *
+         * A service-authenticated process wants a different credential and
+         * builds {@link OxyInferenceClient} directly:
+         * `new OxyInferenceClient({ credential: () => oxy.getServiceToken() })`.
+         * The mint is asynchronous and cached, which is exactly what a
+         * credential function is for.
+         */
+        inference() {
+            if (this._inferenceClient === null) {
+                this._inferenceClient = new OxyInferenceClient_1.OxyInferenceClient({
+                    baseURL: this.getBaseURL(),
+                    credential: () => this.getAccessToken(),
+                });
+            }
+            return this._inferenceClient;
+        }
+    };
+}

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

@@ -152,7 +152,7 @@ function OxyServicesUtilityMixin(Base) {
          *   additionally checked for `aud`, `iss`, and `type` claims to prevent
          *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-         *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
+         *   direct access to `ACCESS_TOKEN_SECRET`.
          *
          * **Why session-less user tokens are refused rather than trusted:**
          * every user access token the Oxy API issues carries a `sessionId` (see
@@ -184,7 +184,7 @@ function OxyServicesUtilityMixin(Base) {
          * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
          * // Protect all routes under /protected
-         * app.use('/protected', oxy.auth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+         * app.use('/protected', oxy.auth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
          *
          * // Access user in route handler
          * app.get('/protected/me', (req, res) => {
@@ -198,7 +198,7 @@ function OxyServicesUtilityMixin(Base) {
          * app.use('/public', oxy.auth({ optional: true }));
          *
          * // Require a specific scope on a service-token-protected route
-         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }), oxy.requireScope('files:write'));
+         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }), oxy.requireScope('files:write'));
          * ```
          *
          * @param options Optional configuration
@@ -363,13 +363,19 @@ function OxyServicesUtilityMixin(Base) {
                                 return onError(error);
                             return res.status(401).json(error);
                         }
-                        // Validate required service token fields
+                        // Validate required service token fields. All of them are
+                        // required, `ownerAccountId` included: an optional billing
+                        // principal is one fallback away from being resolved from the
+                        // delegated user, which is the exact confusion ADR 0007 forbids.
                         const appId = decoded.appId;
                         const credentialId = decoded.credentialId;
+                        const ownerAccountId = decoded.ownerAccountId;
                         const environment = decoded.environment;
                         if (!appId ||
                             typeof credentialId !== 'string' ||
                             credentialId.length === 0 ||
+                            typeof ownerAccountId !== 'string' ||
+                            ownerAccountId.length === 0 ||
                             !isOxyServiceEnvironment(environment)) {
                             if (optional) {
                                 req.userId = null;
@@ -408,6 +414,11 @@ function OxyServicesUtilityMixin(Base) {
                                     return onError(error);
                                 return res.status(403).json(error);
                             }
+                            // ATTRIBUTION ONLY. `req.userId` answers "on whose behalf", never
+                            // "who pays": the billing principal stays `req.serviceApp
+                            // .ownerAccountId`, which this branch does not touch. Read it
+                            // through `getOxyBillingPrincipal` (`@oxyhq/core/server`), whose
+                            // return type a user id cannot satisfy (ADR 0007).
                             req.userId = oxyUserId;
                             req.user = { id: oxyUserId };
                             req.serviceActingAs = { userId: oxyUserId, scopes: grant.scopes };
@@ -422,6 +433,7 @@ function OxyServicesUtilityMixin(Base) {
                             appId,
                             appName: decoded.appName || 'unknown',
                             credentialId,
+                            ownerAccountId,
                             scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
                             environment,
                         };
@@ -738,7 +750,7 @@ function OxyServicesUtilityMixin(Base) {
          * @example
          * ```typescript
          * // Protect internal endpoints
-         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
          *
          * app.post('/internal/trigger', (req, res) => {
          *   console.log('Service app:', req.serviceApp);
@@ -776,7 +788,7 @@ function OxyServicesUtilityMixin(Base) {
          * ```typescript
          * app.use(
          *   '/internal/files',
-         *   oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }),
+         *   oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }),
          *   oxy.requireScope('files:write'),
          * );
          * ```

package/dist/cjs/mixins/index.js

@@ -36,6 +36,7 @@ const OxyServices_chains_1 = require("./OxyServices.chains");
 const OxyServices_nodes_1 = require("./OxyServices.nodes");
 const OxyServices_links_1 = require("./OxyServices.links");
 const OxyServices_followGraph_1 = require("./OxyServices.followGraph");
+const OxyServices_inference_1 = require("./OxyServices.inference");
 const OxyServices_deviceBoot_1 = require("./OxyServices.deviceBoot");
 const OxyServices_deviceTransfer_1 = require("./OxyServices.deviceTransfer");
 /**
@@ -100,6 +101,11 @@ const MIXIN_PIPELINE = [
     // The user-owned follow graph (#809). One relationship per user and target,
     // shared across applications, with per-application context on top.
     OxyServices_followGraph_1.OxyServicesFollowGraphMixin,
+    // The inference model catalogue (#972). Reads only, and deliberately no
+    // request/stream/receipt methods — the public inference edge those would
+    // call is workstream 4 and does not exist yet. See
+    // `docs/inference/README.md` for what is and is not built.
+    OxyServices_inference_1.OxyServicesInferenceMixin,
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServices_deviceBoot_1.OxyServicesDeviceBootMixin,

package/dist/cjs/server/auth.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OXY_SERVICE_ENVIRONMENTS = void 0;
 exports.getOxyUserId = getOxyUserId;
 exports.isOxyAuthenticated = isOxyAuthenticated;
+exports.getOxyBillingPrincipal = getOxyBillingPrincipal;
+exports.getRequiredOxyBillingPrincipal = getRequiredOxyBillingPrincipal;
+exports.getOxyDelegatedUserId = getOxyDelegatedUserId;
+exports.getOxyRequestAttribution = getOxyRequestAttribution;
 exports.getRequiredOxyUserId = getRequiredOxyUserId;
 exports.requireOxyAuth = requireOxyAuth;
 exports.createOptionalOxyAuth = createOptionalOxyAuth;
@@ -36,6 +40,78 @@ function getOxyUserId(req) {
 function isOxyAuthenticated(req) {
     return getOxyUserId(req) !== null;
 }
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+function getOxyBillingPrincipal(req) {
+    const serviceApp = req.serviceApp;
+    if (!serviceApp) {
+        return null;
+    }
+    const accountId = normalizeId(serviceApp.ownerAccountId);
+    const applicationId = normalizeId(serviceApp.appId);
+    const credentialId = normalizeId(serviceApp.credentialId);
+    if (!accountId || !applicationId || !credentialId) {
+        return null;
+    }
+    return {
+        accountId,
+        applicationId,
+        credentialId,
+        environment: serviceApp.environment,
+        scopes: serviceApp.scopes,
+    };
+}
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+function getRequiredOxyBillingPrincipal(req) {
+    const principal = getOxyBillingPrincipal(req);
+    if (!principal) {
+        throw new Error('Request has no verified Oxy service principal');
+    }
+    return principal;
+}
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+function getOxyDelegatedUserId(req) {
+    return normalizeId(req.serviceActingAs?.userId);
+}
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+function getOxyRequestAttribution(req) {
+    const principal = getOxyBillingPrincipal(req);
+    if (!principal) {
+        return null;
+    }
+    return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
 function getRequiredOxyUserId(req) {
     const userId = getOxyUserId(req);
     if (!userId) {

package/dist/cjs/server/cors.js

@@ -16,6 +16,7 @@
  *     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,
@@ -24,8 +25,12 @@
  * Node/Express-only: exported solely from `@oxyhq/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. */
@@ -64,6 +69,29 @@ function isOxyFamilyOrigin(candidate) {
         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 {
@@ -74,24 +102,65 @@ function normalizeOrigin(raw) {
     }
 }
 /**
- * Build the origin-matching predicate: true iff `origin` is in the built-in
- * HTTPS Oxy apex family OR exactly matches one of the configured app origins.
+ * 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 buildOriginAllowed(appOrigins) {
+function normalizeAppOrigins(appOrigins) {
     const explicit = new Set();
     for (const raw of appOrigins) {
         const normalized = normalizeOrigin(raw);
-        if (normalized)
-            explicit.add(normalized);
+        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 (origin) => {
-        const normalized = normalizeOrigin(origin);
-        if (normalized === null)
-            return false;
-        if (explicit.has(normalized))
-            return true;
-        return isOxyFamilyOrigin(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.
@@ -103,7 +172,7 @@ function buildOriginAllowed(appOrigins) {
  */
 function createOxyCors(options = {}) {
     const { appOrigins = [], allowCredentials = true, methods = DEFAULT_ALLOWED_METHODS, allowedHeaders = DEFAULT_ALLOWED_HEADERS, exposedHeaders = [], maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS, } = options;
-    const isOriginAllowed = buildOriginAllowed(appOrigins);
+    const explicitOrigins = normalizeAppOrigins(appOrigins);
     const methodsHeader = methods.join(', ');
     const allowedHeadersHeader = allowedHeaders.join(', ');
     const exposedHeadersHeader = exposedHeaders.join(', ');
@@ -121,7 +190,7 @@ function createOxyCors(options = {}) {
         }
         // Origin is present. Caching correctness: this response varies by Origin.
         res.setHeader('Vary', 'Origin');
-        if (!isOriginAllowed(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).

package/dist/cjs/server/index.js

@@ -16,11 +16,15 @@
  * ```
  */
 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.OXY_CSP_BASELINE = exports.formatOxyCspPolicy = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
+exports.isOfficialWebOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.verifySecret = exports.OXY_CSP_BASELINE = exports.formatOxyCspPolicy = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.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; } });