@oxyhq/core 21.0.0 → 21.0.1

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/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; } });