@oxyhq/core 21.0.0 → 21.0.2

package/dist/types/mixins/OxyServices.inference.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+import { OxyInferenceClient } from '../inference/OxyInferenceClient';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesInferenceMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /** @internal Memoized so repeated calls return one object identity. */
+        _inferenceClient: OxyInferenceClient | 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(): OxyInferenceClient;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -19,9 +19,21 @@ export interface ServiceActingAsVerification {
 }
 /**
  * Service app metadata attached to requests authenticated with service tokens.
- * `scopes` reflects the scopes granted to the app at signup time (from the
- * `Application.scopes` field); route-level checks can require additional
- * scope-narrowing via `requireScope()`.
+ *
+ * Every field comes from the token's SIGNED payload and is populated only after
+ * the signature, `iss`/`aud`/`type` binding and expiry all pass — so a verifier
+ * holding this object can name the responsible principals without a lookup of
+ * its own. Together with `credentialId` and `ownerAccountId` it is the canonical
+ * attribution tuple of ADR 0007 minus the delegated user.
+ *
+ * `scopes` are the EFFECTIVE scopes: the credential's own scopes intersected
+ * with the owning application's grant at mint time (the API's `intersectScopes`
+ * is the single authority for that intersection — nothing re-intersects here).
+ * Route-level checks narrow further via `requireScope()`.
+ *
+ * A delegated end user is NOT a field of this type, and must never become one.
+ * It lives in `req.serviceActingAs` / `req.userId`, is authorised per request,
+ * and is attribution only.
  */
 export interface ServiceApp {
     appId: string;
@@ -29,6 +41,12 @@ export interface ServiceApp {
     scopes: string[];
     /** The credentialId of the specific service credential that minted this token. */
     credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * The BILLING principal — never a user id, and never the delegated
+     * `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
     /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
     environment: OxyServiceEnvironment;
 }
@@ -49,11 +67,24 @@ interface AuthMiddlewareOptions {
      * When provided, service tokens will be cryptographically verified.
      * When omitted, service tokens will be rejected (secure default).
      *
-     * **Migration note (>=1.11.14):** the Oxy API now signs service tokens
-     * with a dedicated `SERVICE_TOKEN_SECRET` distinct from `ACCESS_TOKEN_SECRET`.
-     * Pass that value here. If you keep passing the access-token secret you will
-     * still verify ALL signed-by-Oxy tokens (which is the whole class of bug
-     * H4 was supposed to prevent — DO NOT do that in production).
+     * **The only value that works is `ACCESS_TOKEN_SECRET`, and you should not
+     * want to hold it — see issue #987 and ADR 0012.** The Oxy API signs service
+     * tokens with `ACCESS_TOKEN_SECRET` (`packages/api/src/routes/auth.ts`),
+     * which is also the key that signs every user access token. There is no
+     * separate service-token secret: earlier revisions of this comment named a
+     * `SERVICE_TOKEN_SECRET` that has never existed in the API, in any workflow or
+     * in any task definition, and passing one would fail every verification.
+     *
+     * The consequence to hold onto: the scheme is symmetric, so a host that can
+     * VERIFY a service token can also MINT one — including a user access token.
+     * **Local verification is therefore appropriate only inside the Oxy API's own
+     * trust boundary, and no service outside it holds this key today.** Do not be
+     * the first: if you need to verify Oxy service tokens from another service,
+     * follow #987 rather than copying the secret.
+     *
+     * `docs/adr/0012-service-token-signing-key-model.md` records the decision to
+     * retire this option in favour of asymmetric signing against a published
+     * JWKS, at which point it is removed rather than deprecated.
      */
     jwtSecret?: string;
     /**
@@ -125,7 +156,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          *   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
@@ -157,7 +188,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * 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) => {
@@ -171,7 +202,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * 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
@@ -213,7 +244,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * @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);
@@ -242,7 +273,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * ```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/types/mixins/index.d.ts

@@ -32,6 +32,7 @@ import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
+import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
@@ -43,7 +44,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/server/auth.d.ts

@@ -16,6 +16,12 @@ export interface OxyServiceAppContext {
     appName: string;
     scopes: string[];
     credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * Read off the VERIFIED service-token claim set — never a user id, and never
+     * the delegated `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
     environment: OxyServiceEnvironment;
 }
 export interface OxyServiceActingAsContext {
@@ -44,6 +50,80 @@ export interface OxyAuthMiddlewareOptions {
 }
 export declare function getOxyUserId(req: Request): string | null;
 export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+    /** `applications.owner_account_id` — the financially responsible account. */
+    readonly accountId: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    readonly environment: OxyServiceEnvironment;
+    readonly scopes: readonly string[];
+}
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+    readonly delegatedUserId: string | 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 declare function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null;
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export declare function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal;
+/**
+ * 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 declare function getOxyDelegatedUserId(req: Request): string | null;
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export declare function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null;
 export declare function getRequiredOxyUserId(req: Request): string;
 export declare function requireOxyAuth(req: Request, res: Response, next: NextFunction): void;
 export declare function createOptionalOxyAuth(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;

package/dist/types/server/cors.d.ts

@@ -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,
@@ -29,6 +30,11 @@ export interface OxyCorsOptions {
      * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
      * ADDITION TO the built-in HTTPS Oxy apex origin family. Each is normalized
      * via `new URL().origin`.
+     *
+     * An entry that is not a URL, or whose origin is the opaque origin
+     * (`exp://…`, `capacitor://…`, `chrome-extension://…`, `file:`, `data:`), is
+     * DROPPED with an error log rather than admitted — see `OPAQUE_ORIGIN` for
+     * why one such entry would otherwise admit every other one.
      */
     appOrigins?: string[];
     /**
@@ -46,6 +52,41 @@ export interface OxyCorsOptions {
     /** Preflight cache lifetime in seconds. Default 86400 (24h). */
     maxAgeSeconds?: number;
 }
+/**
+ * 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.
+ */
+export declare function normalizeAppOrigins(appOrigins: string[]): Set<string>;
+/**
+ * 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 declare function matchesAllowedOrigin(explicit: ReadonlySet<string>, origin: string): boolean;
 /**
  * Create a strict Oxy CORS middleware. See module docs.
  *

package/dist/types/server/index.d.ts

@@ -14,8 +14,8 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
-export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "21.0.0",
+  "version": "21.0.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -116,7 +116,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.26.0",
+    "@oxyhq/contracts": "^0.30.0",
     "@oxyhq/protocol": "^0.2.0",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",

package/src/HttpService.ts

@@ -913,6 +913,19 @@ export class HttpService {
    */
   private static readonly CACHE_IDENTITY_DELIM = ' id=';
 
+  /**
+   * The keys whose presence beside `data` makes a body a PAGE rather than a
+   * payload — see {@link unwrapResponse} for why this list is narrow.
+   *
+   *  - `pagination` — the offset-paginated house envelope (`sendPaginated`).
+   *  - `nextCursor` — the keyset-paginated one (the account audit trails).
+   *
+   * Membership is decided by key PRESENCE, never by value: the last page sends
+   * `nextCursor: null`, and an envelope that collapsed into a bare payload
+   * exactly when the stream ended would be a worse bug than the one this fixes.
+   */
+  private static readonly PAGE_ENVELOPE_KEYS: readonly string[] = ['pagination', 'nextCursor'];
+
   /**
    * Derive a stable, non-sensitive identity discriminator for cache scoping.
    *
@@ -1212,21 +1225,48 @@ export class HttpService {
   }
 
   /**
-   * Unwrap standardized API response format
+   * Unwrap the standardized API response envelope — EXCEPT when the envelope is
+   * a page, in which case it travels whole.
+   *
+   * `{ data: <payload> }` is the house success envelope (`sendSuccess`), and
+   * reducing it to `<payload>` is what every call site in the SDK expects. But
+   * the reduction DISCARDS every sibling key, silently, and a page's siblings
+   * are the only thing that says where the next page starts. That is how
+   * `GET /accounts/:id/audit` lost its `nextCursor`: the caller received a bare
+   * array, `getNextPageParam` read `undefined`, and pagination was dead past the
+   * first page with nothing to show that it was.
+   *
+   * ## Why the rule is narrow, and not "any sibling key survives"
+   *
+   * "An object carrying `data` plus anything else is not an envelope" is the
+   * tempting general rule, and it is wrong here: this API already answers
+   * `{ data, count }` on ~15 routes, plus `{ data, source }`, `{ data, reason }`
+   * and `{ data, secretDestroyed }`, and a dozen measured Console call sites
+   * type those as the bare payload (`Array<ProviderConnection>`,
+   * `AccountBillingState | null`, …). Preserving those envelopes would hand every
+   * one of them an object where it expects its payload — at runtime only, since
+   * the response type is a call-site assertion. So the rule names PAGINATION
+   * specifically: `data` beside {@link PAGE_ENVELOPE_KEYS} is a page.
+   *
+   * A route whose sibling key genuinely matters to its caller belongs in that
+   * list, or should not be a sibling of `data` at all — the cursor-paginated
+   * surfaces already in the SDK (`{ follows, nextCursor }`,
+   * `{ records, nextCursor }`) sidestep this by never using `data`.
    */
   private unwrapResponse(responseData: unknown): unknown {
-    // Handle paginated responses: { data: [...], pagination: {...} }
-    if (responseData && typeof responseData === 'object' && 'data' in responseData && 'pagination' in responseData) {
+    if (!responseData || typeof responseData !== 'object' || !('data' in responseData)) {
+      // Not the success envelope (or not an object at all) — as-is.
       return responseData;
     }
-    
-    // Handle regular success responses: { data: ... }
-    if (responseData && typeof responseData === 'object' && 'data' in responseData && !Array.isArray(responseData)) {
-      return responseData.data;
+
+    // A page travels whole: its cursor/pagination sibling is unrecoverable
+    // information, not decoration.
+    if (HttpService.PAGE_ENVELOPE_KEYS.some((key) => key in responseData)) {
+      return responseData;
     }
-    
-    // Return as-is for responses that don't use sendSuccess wrapper
-    return responseData;
+
+    // Regular success envelope: `{ data: ... }` -> the payload.
+    return Array.isArray(responseData) ? responseData : responseData.data;
   }
 
   /**

package/src/__tests__/httpServiceUnwrapEnvelope.test.ts

@@ -0,0 +1,115 @@
+/**
+ * `HttpService.unwrapResponse` envelope tests — driven through the REAL class
+ * against a stubbed `fetch`, never by calling the private method.
+ *
+ * The convenience unwrap reduces the house `{ data: <payload> }` envelope to its
+ * payload, and in doing so it discards every sibling key. That silently killed
+ * pagination on the account audit trails (`GET /accounts/:id/audit` and
+ * `GET /accounts/:id/billing/audit`, which answer `{ data, count, nextCursor }`):
+ * the caller got a bare array, `getNextPageParam` read `undefined`, and there was
+ * nothing at the call site to show that page 2 could never be requested.
+ *
+ * The three cases below are the whole contract, and each is load-bearing:
+ *
+ *  - a cursor page travels WHOLE (the regression),
+ *  - a `{ data, pagination }` page still travels whole (the behaviour that
+ *    already existed — the positive control for "pages are preserved"),
+ *  - a bare `{ data }` body still unwraps (the control proving the convenience
+ *    every other call site depends on is intact).
+ *
+ * Reverting the fix must redden the first and leave the other two green.
+ */
+
+import { HttpService } from '../HttpService';
+
+/** One entry of an audit page — only the shape matters here. */
+const ENTRY = { source: 'application_credential', eventType: 'created' } as const;
+
+function jsonBody(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('HttpService response-envelope unwrapping', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  /** Drive a real `HttpService.get` against a stubbed wire body. */
+  async function fetchWireBody<T>(body: unknown): Promise<T> {
+    globalThis.fetch = jest.fn(async () => jsonBody(body)) as unknown as typeof fetch;
+    const http = new HttpService({ baseURL: 'http://api.test.invalid' });
+    return http.get<T>('/accounts/acct-1/audit', { cache: false });
+  }
+
+  it('preserves a cursor page whole — `count` and `nextCursor` reach the caller', async () => {
+    const wire = { data: [ENTRY], count: 1, nextCursor: 'CURSOR-XYZ' };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    // The cursor is the only thing that says where page 2 starts. Asserted on
+    // its own because `toEqual` above would also pass a body that merely
+    // happened to be an array of one entry.
+    expect(page.nextCursor).toBe('CURSOR-XYZ');
+    expect(page.count).toBe(1);
+    expect(page.data).toEqual([ENTRY]);
+  });
+
+  it('preserves the LAST cursor page, where `nextCursor` is null', async () => {
+    // The recognition is by key presence, not truthiness: if the envelope
+    // collapsed into a bare array exactly when the stream ended, every caller
+    // would crash on the final page instead of finishing.
+    const wire = { data: [ENTRY], count: 1, nextCursor: null };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    expect(page.nextCursor).toBeNull();
+  });
+
+  it('preserves the offset-paginated `{ data, pagination }` envelope (control)', async () => {
+    const wire = {
+      data: [ENTRY],
+      pagination: { total: 1, limit: 50, offset: 0, hasMore: false },
+    };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+  });
+
+  it('still unwraps a bare `{ data }` success envelope to its payload (control)', async () => {
+    const payload = { id: 'acct-1', name: 'Acme' };
+
+    const unwrapped = await fetchWireBody<typeof payload>({ data: payload });
+
+    expect(unwrapped).toEqual(payload);
+  });
+
+  it('still unwraps `{ data, count }`, which a dozen callers type as the bare payload', async () => {
+    // `{ data, count }` is answered by ~15 routes whose Console call sites type
+    // the result `Array<T>`. `count` is `data.length` — recoverable — so this
+    // envelope deliberately does NOT survive, and widening the rule to "any
+    // sibling key" would break every one of those callers at runtime.
+    const entries = [ENTRY, ENTRY];
+
+    const unwrapped = await fetchWireBody<typeof entries>({ data: entries, count: 2 });
+
+    expect(unwrapped).toEqual(entries);
+  });
+
+  it('passes through a body that has no `data` key at all', async () => {
+    // The cursor surfaces already in the SDK (`{ follows, nextCursor }`,
+    // `{ records, nextCursor }`) rely on this lane.
+    const wire = { follows: [{ relationshipId: 'rel-1' }], nextCursor: 'CURSOR-ABC' };
+
+    const passed = await fetchWireBody<typeof wire>(wire);
+
+    expect(passed).toEqual(wire);
+  });
+});

package/src/i18n/locales/en-US.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Upload and modify your files",
       "filesDelete": "Delete your files",
       "webhooksReceive": "Receive webhooks",
-      "chatCompletions": "Use AI chat on your behalf",
-      "modelsRead": "List available AI models",
+      "inferenceInvoke": "Run AI requests on your behalf",
+      "inferenceModelsRead": "List available AI models",
+      "inferenceUsageRead": "Read its AI usage and costs",
+      "inferenceRoutingRead": "Read how AI requests are routed",
+      "inferenceRoutingWrite": "Change how AI requests are routed",
+      "inferenceProvidersRead": "Read its connected AI providers",
+      "inferenceProvidersWrite": "Manage its connected AI providers",
       "federationWrite": "Act across federated services"
     },
     "account": {

package/src/i18n/locales/es-ES.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Subir y modificar tus archivos",
       "filesDelete": "Eliminar tus archivos",
       "webhooksReceive": "Recibir webhooks",
-      "chatCompletions": "Usar el chat con IA en tu nombre",
-      "modelsRead": "Ver los modelos de IA disponibles",
+      "inferenceInvoke": "Ejecutar peticiones de IA en tu nombre",
+      "inferenceModelsRead": "Ver los modelos de IA disponibles",
+      "inferenceUsageRead": "Ver su consumo y costes de IA",
+      "inferenceRoutingRead": "Ver cómo se enrutan las peticiones de IA",
+      "inferenceRoutingWrite": "Cambiar cómo se enrutan las peticiones de IA",
+      "inferenceProvidersRead": "Ver sus proveedores de IA conectados",
+      "inferenceProvidersWrite": "Gestionar sus proveedores de IA conectados",
       "federationWrite": "Actuar en servicios federados"
     },
     "account": {