@oxyhq/core 21.0.0 → 21.0.2

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/cors.js

@@ -15,6 +15,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,
@@ -22,7 +23,9 @@
  *
  * Node/Express-only: exported solely from `@oxyhq/core/server`.
  */
+import { createLogger } from '../logger/index.js';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
+const log = 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. */
@@ -61,6 +64,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 {
@@ -71,24 +97,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) {
+export 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`.
+ */
+export 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.
@@ -100,7 +167,7 @@ function buildOriginAllowed(appOrigins) {
  */
 export 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(', ');
@@ -118,7 +185,7 @@ export 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/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';