@oxyhq/core 21.0.0 → 21.0.1

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

@@ -149,7 +149,7 @@ export 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
@@ -181,7 +181,7 @@ export 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) => {
@@ -195,7 +195,7 @@ export 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
@@ -360,13 +360,19 @@ export 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;
@@ -405,6 +411,11 @@ export 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 };
@@ -419,6 +430,7 @@ export function OxyServicesUtilityMixin(Base) {
                             appId,
                             appName: decoded.appName || 'unknown',
                             credentialId,
+                            ownerAccountId,
                             scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
                             environment,
                         };
@@ -735,7 +747,7 @@ export 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);
@@ -773,7 +785,7 @@ export 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/esm/mixins/index.js

@@ -32,6 +32,7 @@ import { OxyServicesChainsMixin } from './OxyServices.chains.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph.js';
+import { OxyServicesInferenceMixin } from './OxyServices.inference.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
 /**
@@ -96,6 +97,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.
     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.
+    OxyServicesInferenceMixin,
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,

package/dist/esm/server/auth.js

@@ -27,6 +27,78 @@ export function getOxyUserId(req) {
 export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function getOxyRequestAttribution(req) {
+    const principal = getOxyBillingPrincipal(req);
+    if (!principal) {
+        return null;
+    }
+    return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
 export function getRequiredOxyUserId(req) {
     const userId = getOxyUserId(req);
     if (!userId) {

package/dist/esm/server/index.js

@@ -14,7 +14,7 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
 export { createOxyRateLimit } from './rateLimit.js';
 // SSRF-safe upstream fetch + URL validation (Node-only).
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch.js';