@oxyhq/core 20.1.0 → 21.0.1

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

@@ -267,61 +267,6 @@ export interface UpdateAccountMemberInput {
 export interface TransferAccountOwnershipInput {
     userId: string;
 }
-/** Credential kind. Account (bot) credentials are always `service` tokens. */
-export type AccountCredentialType = 'service';
-/** Deployment environment a bot credential is scoped to. */
-export type AccountCredentialEnvironment = 'development' | 'staging' | 'production';
-/** Bot credential lifecycle status. */
-export type AccountCredentialStatus = 'active' | 'deprecated' | 'revoked';
-/** Input accepted by `createAccountCredential`. Credential `type` is always `service`. */
-export interface CreateAccountCredentialInput {
-    name: string;
-    environment: AccountCredentialEnvironment;
-    scopes?: string[];
-}
-/**
- * Client-facing AccountCredential shape (a bot account's service token). The raw
- * secret is NEVER part of this shape — it is returned exactly once, separately,
- * at creation/rotation.
- */
-export interface AccountCredential {
-    _id: string;
-    /** The bot account this credential authenticates as (account `_id`). */
-    accountId: string;
-    name: string;
-    publicKey: string;
-    type: AccountCredentialType;
-    environment: AccountCredentialEnvironment;
-    scopes: string[];
-    status: AccountCredentialStatus;
-    lastUsedAt?: string;
-    expiresAt?: string;
-    /**
-     * Audit link to the credential this one was rotated FROM. Populated on
-     * credentials created via rotation; absent on original credentials.
-     */
-    rotatedFromCredentialId?: string;
-    createdByUserId: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/** Result of creating a bot credential — `secret` is returned ONCE. */
-export interface AccountCredentialWithSecret {
-    credential: AccountCredential;
-    secret: string;
-}
-/**
- * Result of rotating a bot credential. Extends the create result with audit
- * fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom` (the
- * previous credential's `credentialId`) and `graceExpiresAt` (ISO string marking
- * when the old credential stops being honoured during the rotation grace window).
- */
-export interface RotateAccountCredentialResult extends AccountCredentialWithSecret {
-    /** The previous credential's `credentialId` that this rotation supersedes. */
-    rotatedFrom: string;
-    /** ISO timestamp at which the rotated-from credential's grace window ends. */
-    graceExpiresAt: string;
-}
 /**
  * Application classification. Set only by Oxy platform staff — never editable
  * through the normal member-facing update path.
@@ -329,8 +274,18 @@ export interface RotateAccountCredentialResult extends AccountCredentialWithSecr
 export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'system';
 /** Lifecycle status of an application. */
 export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
-/** OAuth credential kind. `service` credentials mint service tokens. */
-export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+/**
+ * Credential kind.
+ *
+ * The first three are OAuth clients: the `oxy_dk_…` `publicKey` is the
+ * `client_id`, and any secret is presented BESIDE it. `service` credentials
+ * additionally mint service tokens.
+ *
+ * `machine` is the OpenAI-SDK-compatible API key (issue #972 §2.3): its
+ * credential material is ONE `oxy_sk_…` bearer string returned in `token`
+ * exactly once on create/rotate, never in `secret`.
+ */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service' | 'machine';
 /** Deployment environment an application credential is scoped to. */
 export type ApplicationEnvironment = 'development' | 'staging' | 'production';
 /** Application credential lifecycle status. */
@@ -386,6 +341,12 @@ export interface ApplicationCredential {
     applicationId: string;
     name: string;
     publicKey: string;
+    /**
+     * `oxy_sk_<id>` — the PUBLIC lookup half of a `machine` credential's bearer
+     * token, present only on that type. Safe to render: the secret half is 256
+     * bits that were shown exactly once and are never returned again.
+     */
+    tokenPrefix?: string;
     type: ApplicationCredentialType;
     environment: ApplicationEnvironment;
     scopes: string[];
@@ -441,23 +402,67 @@ export interface CreateApplicationCredentialInput {
     type: ApplicationCredentialType;
     environment: ApplicationEnvironment;
     scopes?: string[];
+    /**
+     * Lifetime of a `machine` credential, in seconds — 60 to 730 days. Omit for a
+     * key that does not expire on its own.
+     *
+     * **`machine` only.** On every other credential type `expires_at` means the
+     * rotation grace deadline, so a caller setting it at creation would make a
+     * brand-new credential indistinguishable from a rotated one. The server
+     * REJECTS it for those types rather than ignoring it, so sending it with the
+     * wrong `type` is a 400, not a silently dropped field.
+     */
+    expiresInSeconds?: number;
+}
+/** Input accepted by `rotateAppCredential`. */
+export interface RotateApplicationCredentialInput {
+    /**
+     * How long the superseded `machine` token keeps working, in seconds — 1 to 30
+     * days. Omitting it revokes the previous token the instant the replacement is
+     * minted, which is the safe default for a leaked key.
+     *
+     * **`machine` only, and opt-in.** `confidential`/`service` credentials always
+     * retire on the platform's fixed seven-day grace and the server REJECTS this
+     * field for them, so their contract is unchanged.
+     */
+    graceSeconds?: number;
 }
-/** Result of creating an application credential — `secret` is returned ONCE. */
+/**
+ * Result of creating an application credential — credential material is returned
+ * ONCE and can never be read back.
+ *
+ * Exactly one of the two fields carries it, decided by
+ * {@link ApplicationCredentialType}: `secret` for a `confidential`/`service`
+ * client, `token` for a `machine` API key, and NEITHER for a `public` client
+ * (`secret` is `null`). They are separate fields rather than one, so a surface
+ * that renders "the secret" cannot silently render an API key's bearer token
+ * under the wrong label, or a `null` where a token should be.
+ */
 export interface ApplicationCredentialWithSecret {
     credential: ApplicationCredential;
-    secret: string;
+    /** The OAuth client secret. `null` for `public` and `machine` credentials. */
+    secret: string | null;
+    /** The full `oxy_sk_…` bearer token. Present ONLY for a `machine` credential. */
+    token?: string;
 }
 /**
  * Result of rotating an application credential. Extends the create result with
- * audit fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom`
- * (the previous credential's `credentialId`) and `graceExpiresAt` (ISO string
- * marking when the old credential stops being honoured during the grace window).
+ * audit fields: the new credential material is returned ONCE, plus `rotatedFrom`
+ * (the previous credential's `credentialId`) and `graceExpiresAt`.
  */
 export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
     /** The previous credential's `credentialId` that this rotation supersedes. */
     rotatedFrom: string;
-    /** ISO timestamp at which the rotated-from credential's grace window ends. */
-    graceExpiresAt: string;
+    /**
+     * ISO timestamp at which the rotated-from credential stops being honoured, or
+     * `null` when no grace window was configured and it was revoked outright.
+     *
+     * Nullable because a `machine` credential's grace is OPT-IN (issue #972 §2.3):
+     * rotating an API key without asking for a window kills the old token
+     * immediately, and there is then no deadline to report. The OAuth/service
+     * types always carry their fixed seven-day deadline.
+     */
+    graceExpiresAt: string | null;
 }
 /** Time window for application usage statistics. */
 export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
@@ -675,36 +680,6 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * @param data - Target user id.
          */
         transferAccountOwnership(accountId: string, data: TransferAccountOwnershipInput): Promise<AccountSuccessResult>;
-        /**
-         * List a bot account's service credentials. The response NEVER includes
-         * secrets.
-         * @param accountId - The account's Mongo `_id`.
-         */
-        listAccountCredentials(accountId: string): Promise<AccountCredential[]>;
-        /**
-         * Create a service credential for a bot account. The plaintext `secret` is
-         * returned exactly ONCE; the server stores only a hash and will never return
-         * it again.
-         * @param accountId - The account's Mongo `_id`.
-         * @param data - Credential configuration (`type` is always `service`).
-         */
-        createAccountCredential(accountId: string, data: CreateAccountCredentialInput): Promise<AccountCredentialWithSecret>;
-        /**
-         * Rotate a bot credential's secret. The new plaintext `secret` is returned
-         * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
-         * credentialId) and `graceExpiresAt` (ISO string for the grace window during
-         * which the old credential is still honoured).
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        rotateAccountCredential(accountId: string, credentialId: string): Promise<RotateAccountCredentialResult>;
-        /**
-         * Revoke a bot credential (`status='revoked'`). Revoked credentials can no
-         * longer authenticate.
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        revokeAccountCredential(accountId: string, credentialId: string): Promise<AccountSuccessResult>;
         /**
          * List the applications owned by an account. Backed by
          * `GET /applications?ownerAccountId=<id>`.
@@ -753,8 +728,11 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * which the old credential is still honoured).
          * @param applicationId - The application's Mongo `_id`.
          * @param credentialId - The credential's Mongo `_id`.
+         * @param options - `graceSeconds` keeps a superseded `machine` token working
+         *   for that long. Omitted, the previous token dies the moment the
+         *   replacement is minted.
          */
-        rotateAppCredential(applicationId: string, credentialId: string): Promise<RotateApplicationCredentialResult>;
+        rotateAppCredential(applicationId: string, credentialId: string, options?: RotateApplicationCredentialInput): Promise<RotateApplicationCredentialResult>;
         /**
          * Revoke an application credential (`status='revoked'`). Revoked credentials
          * can no longer authenticate.

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

@@ -4,7 +4,7 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { LoginResult, LoginSessionResult, CommonsDenyReason } from '@oxyhq/contracts';
+import type { LoginResult, CommonsDenyReason } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -39,6 +39,41 @@ export interface OAuthUserInfoResponse {
     name?: string;
     picture?: string;
 }
+/**
+ * The session an OAuth authorization-code exchange yields.
+ *
+ * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
+ * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
+ * requires `deviceId` because those lanes always join the origin's DeviceSession.
+ * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
+ * parties, whose grant is deliberately ISOLATED: an untrusted application must be
+ * able to receive a session carrying NO DeviceSession credential at all.
+ *
+ * Both device fields are therefore optional here, and a response omitting them is
+ * a well-formed device-less grant rather than a malformed payload. What that
+ * costs the session is spelled out on `exchangeOAuthCode` below.
+ */
+export interface OAuthTokenExchangeResult {
+    sessionId: string;
+    /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
+    expiresAt: string;
+    accessToken?: string;
+    /**
+     * The DeviceSession this grant joined, when the server issued one. ABSENT for
+     * an isolated third-party grant — never assume a string.
+     */
+    deviceId?: string;
+    /**
+     * The zero-cookie mint credential for {@link deviceId}. Present only alongside
+     * it; absent for an isolated third-party grant.
+     */
+    deviceSecret?: string;
+    user: {
+        id: string;
+        username?: string;
+        avatar?: string;
+    };
+}
 /**
  * How a "Sign in with Oxy" request finalizes once the approver authorizes it.
  *
@@ -793,13 +828,30 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * response this method used before were an Oxy invention no OAuth library
          * could interoperate with; the endpoint no longer accepts them. The method's
          * OWN signature is unchanged, so callers are unaffected.
+         *
+         * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+         * outcome, not an error. A third-party grant is meant to be isolated from the
+         * browser's shared DeviceSession, so the token endpoint must be free to return
+         * no device credential at all — the guard that used to require the pair made
+         * that omission unshippable, since it turned every third-party sign-in through
+         * the SDK into a silent `exchange-failed`.
+         *
+         * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+         * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+         * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+         * access token itself — nothing persists a restore credential, the cold boot's
+         * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+         * scheduler has nothing to re-mint from. When the token expires the session
+         * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+         * out, so the app can run the OAuth flow again. It never degrades into a
+         * session that looks alive and cannot refresh.
          */
         exchangeOAuthCode(params: {
             code: string;
             clientId: string;
             redirectUri: string;
             codeVerifier: string;
-        }): Promise<LoginSessionResult>;
+        }): Promise<OAuthTokenExchangeResult>;
         /**
          * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
          * The response is a flat JSON document — no `{ data }` wrapper.
@@ -850,7 +902,27 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         handleError(error: unknown): Error;
         healthCheck(): Promise<{
             status: string;
-            users?: number;
+            users
+            /**
+             * @internal Narrow an untrusted delivery-progress timestamp from the status
+             * response.
+             *
+             * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+             * and `null` for everything else — absent (an older API that has no delivery
+             * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+             * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+             * to the waiting UI is not.
+             */
+            ? /**
+             * @internal Narrow an untrusted delivery-progress timestamp from the status
+             * response.
+             *
+             * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+             * and `null` for everything else — absent (an older API that has no delivery
+             * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+             * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+             * to the waiting UI is not.
+             */: number;
             timestamp?: string;
             [key: string]: any;
         }>;

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/models/session.d.ts

@@ -13,6 +13,17 @@ export interface ClientSession {
      * account-chooser ordering, not for any token-refresh mechanism.
      */
     authuser?: number;
+    /**
+     * The HUMAN operating this account, when it is a delegated session — the
+     * audit actor behind "The Oxy Collective". Absent when the session belongs to
+     * the account itself.
+     *
+     * The flat wire shape has carried it since the multi-account model shipped and
+     * nothing read it, so an operated org rendered exactly like a directly
+     * signed-in one. `SessionClient.getActiveContext()` is the richer answer
+     * (ADR 0002); this is the same fact on the compatibility lane.
+     */
+    operatedByUserId?: string;
 }
 export interface StorageKeys {
     sessions: string;