@oxy.so/core 4.1.0 → 4.3.0

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

@@ -25,7 +25,7 @@ export type { AccountDelegationAccess, AccountDelegationNode, } from './accountD
 export { AccountDialogController, createAccountDialogController, } from './accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, ContextChoiceOutcome, SignInFailureReason, SignInFlowPhase, SignInFlowState, SignInProgress, } from './accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './authStateStore';
-export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './authStateStore';
+export type { PersistedAuthState, AuthStateStore, AuthStateWriteGuard, NativeKeyValueStorage, } from './authStateStore';
 export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './sharedDeviceCredential';
 export type { SharedDeviceCredential, SharedDeviceCredentialRead, SharedDeviceCredentialStore, SharedDeviceJoinDecision, SharedDeviceJoinSkipReason, SharedDevicePublishDecision, SharedDevicePublishOutcome, SharedDevicePublishSkipReason, } from './sharedDeviceCredential';
 export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './identityPin';

package/dist/types/session/refresh.d.ts

@@ -24,7 +24,8 @@
 import type { DeviceSessionState } from '@oxy.so/contracts';
 import type { OxyServices } from '../OxyServices';
 import type { AuthRefreshHandler } from '../HttpService';
-import type { AuthStateStore } from './authStateStore';
+import { type AuthStateStore } from './authStateStore';
+import type { SharedDeviceCredentialStore } from './sharedDeviceCredential';
 import type { IdentityPin } from './identityPin';
 import { type IdentityBinding } from './identitySession';
 /**
@@ -68,6 +69,10 @@ export interface RefreshDeps {
      * Commons-identity one.
      */
     identity?: IdentityBinding;
+    /** Native ACCOUNT join point. A live local holder always wins. */
+    sharedDeviceCredential?: SharedDeviceCredentialStore;
+    /** A replaced/unmounted provider cannot commit a pending refresh. */
+    isCurrent?: () => boolean;
 }
 /**
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
@@ -127,9 +132,13 @@ export type DeviceSecretMintOutcome = {
  *
  * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
  * the access token; a failed durable persist yields `persist-failed` WITHOUT
- * planting. This function performs NO store mutation on failure — the caller
+ * planting. Apart from the account-mode logout marker below, failure mutations
+ * belong to the caller, which
  * applies the drop/clear policy (which differs web vs native) from the returned
- * status.
+ * status. A native account store with a suppression marker records a current
+ * `no_active_session`, or an invalid secret with prior authenticated session
+ * history, records durable ACCOUNT logout intent; it never deletes that holder.
+ * Error classification uses the existing 401 message markers.
  *
  * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
  * `accountId` (so the server mints that account's token without touching
@@ -142,16 +151,32 @@ export declare function refreshDeviceSecretArm(deps: {
     store: AuthStateStore;
     /** The identity pin, when this client is identity-bound. */
     pin?: IdentityPin | null;
+    isCurrent?: () => boolean;
+}): Promise<DeviceSecretMintOutcome>;
+/**
+ * Prove a shared native ACCOUNT holder before replacing local bytes. Callers
+ * may replace a local credential only after its explicit mint rejection. The
+ * optional guarded storage seam makes custom stores fail closed on adoption.
+ * This lane never clears explicit sign-out intent or uses an identity key.
+ */
+export declare function refreshSharedDeviceArm(deps: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    shared: SharedDeviceCredentialStore;
+    rejectedLocalHolder?: boolean;
+    isCurrent?: () => boolean;
 }): Promise<DeviceSecretMintOutcome>;
 /**
  * Re-mint the persisted session and return the fresh access token, or `null`
  * when no arm could produce one.
  *
  * Arm 1 (`POST /session/device/token`, via {@link refreshDeviceSecretArm}): mint
- * from the persisted `deviceId` + `deviceSecret`. On a 401 the secret is diverged
- * or the device has no live session: drop the secret so the mint lane stops (or
- * clear the store on web, where there is no fallback), then fall to arm 2 on
- * native. A transient error — or a durable-persist failure — leaves the store and
+ * from the persisted `deviceId` + `deviceSecret`. An authenticated native
+ * holder's invalid-secret or `no_active_session` verdict suppresses key recovery
+ * while permitting a separately proved new shared holder. The latter verdict
+ * retains that holder and ends ACCOUNT recovery without a new key challenge.
+ * Classification still uses the existing 401 message markers, not a new parser.
+ * A transient error — or a durable-persist failure — leaves the store and
  * returns `null` WITHOUT falling to arm 2 (those are not bad-secret signals).
  *
  * Arm 2 (native Commons identity): when the secret is absent or was just

package/dist/types/session/sharedDeviceCredential.d.ts

@@ -189,7 +189,9 @@ export declare function publishProvenDeviceCredential(deps: {
  *    seam, no lane left out, and no new call site to forget.
  *  - Adopting on read would hide a change of WHO THIS APP IS SIGNED IN AS inside
  *    a storage primitive, and would run on every `load()`. Adoption is an
- *    explicit, once-per-boot cold-boot step instead (`shared-device-adopt`).
+ *    explicit cold-boot/resume recovery instead; an existing local holder must
+ *    first be rejected by the server, and a new shared holder must mint before
+ *    conditional persistence.
  *
  * `clear()` deliberately does NOT clear the shared slot. This app signing out is
  * not authority over the device-wide join point: other apps may still be signed

package/dist/types/utils/officialOrigins.d.ts

@@ -1,12 +1,8 @@
-/**
- * Official first-party web origin allowlist — shared by OAuth redirect
- * validation and the server-side trusted-origin checks.
- */
+export { isLoopbackOrigin } from '@oxy.so/contracts';
 /**
  * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
  * or `[::1]` on any port, http or https).
  */
-export declare function isLoopbackOrigin(origin: string): boolean;
 /** Whether an origin belongs to the official Oxy web ecosystem. */
 export declare function isOfficialWebOrigin(origin: string): boolean;
 /** @deprecated Use {@link isOfficialWebOrigin}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -179,8 +179,8 @@
     "@oxy.so/telemetry": "^1.2.0",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^4.7.0",
-    "@oxy.so/protocol": "^1.2.1",
+    "@oxy.so/contracts": "^4.9.1",
+    "@oxy.so/protocol": "^1.2.2",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",
@@ -192,9 +192,9 @@
     "zod": "^3.25.64"
   },
   "peerDependencies": {
-    "@react-native-async-storage/async-storage": "*",
-    "expo-crypto": "*",
-    "expo-secure-store": "*",
+    "@react-native-async-storage/async-storage": "<3.0.0",
+    "expo-crypto": "<58.0.0",
+    "expo-secure-store": "<58.0.0",
     "express": "^4.0.0"
   },
   "peerDependenciesMeta": {

package/src/HttpService.ts

@@ -37,20 +37,54 @@ export type AccessTokenProvider = () => string | null;
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
 
+/** Comparison only fences local async work; it never validates token authority. */
+function sameTokenSession(left: string | null, right: string | null): boolean {
+  if (left === right) return true;
+  if (!left || !right) return false;
+  const a = decodeTokenClaims(left);
+  const b = decodeTokenClaims(right);
+  if (!a || !b || !(a.userId || a.id || a.sub) || !(b.userId || b.id || b.sub)) return false;
+  // A refresh may rotate exp/iat/jti while preserving its account and session.
+  // Opaque/malformed context fields cannot establish that equivalence.
+  return ['userId', 'id', 'sub', 'sessionId', 'operatorId', 'clientId', 'appId', 'authMethodId'].every((key) =>
+    (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
+}
+
+/** Cancel this wait only; the shared mint continues for other callers. */
+function awaitRequestSignal<T>(pending: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return pending;
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => { reject(createCancelledError()); };
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+    // Both handlers remain attached even after cancellation, so a late shared
+    // failure is observed without reviving this request or becoming unhandled.
+    pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
+/** A trusted platform transport, for example Expo's streaming fetch. */
+export type ResponseTransport = (input: string, init: RequestInit) => Promise<Response>;
+
 /**
- * A low-level authenticated request whose response body remains unread.
- *
- * This is intended for streaming protocols such as SSE. The body must already
- * be serialised so it can be replayed once after an access-token refresh.
+ * A low-level same-origin request whose response body remains unread.
+ * Only absent/string request bodies can be replayed after a 401. Multipart,
+ * binary and stream bodies are sent once, even if their platform can replay them.
+ * The caller owns response parsing and the AbortSignal for its full lifetime.
  */
-export interface AuthenticatedResponseRequest {
+export interface ResponseRequest {
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   url: string;
-  body?: string;
-  headers?: Record<string, string>;
+  body?: BodyInit;
+  headers?: HeadersInit;
   signal?: AbortSignal;
+  /** Must honour the supplied URL, headers, signal and redirect policy. */
+  fetch?: ResponseTransport;
 }
 
+/** Same response contract, but rejects locally when the SDK has no bearer. */
+export type AuthenticatedResponseRequest = ResponseRequest;
+
 /**
  * Structural type that captures the multipart-write surface every supported
  * FormData implementation exposes (browser, React Native, Node `form-data`
@@ -464,8 +498,7 @@ export class HttpService {
 
     if (providedToken) {
       if (providedToken !== currentToken) {
-        this.tokenStore.setTokens(providedToken);
-        this.notifyTokenChange();
+        this.setTokens(providedToken);
       }
       return providedToken;
     }
@@ -1282,8 +1315,12 @@ export class HttpService {
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (epoch !== this.sessionEpoch) {
-            // The session ended while this re-mint was in flight. Not a failure
-            // (no cooldown), and nothing to plant.
+            // A guarded refresh handler can itself adopt a new active context.
+            // Acknowledge only an already-installed, exact result; never plant
+            // a stale return value over a concurrent switch/logout.
+            if (newToken && !this.sessionEnded && this.tokenStore.getAccessToken() === newToken) {
+              return newToken;
+            }
             this.logger.debug('Discarded a token refresh that outlived its session');
             return null;
           }
@@ -1294,8 +1331,7 @@ export class HttpService {
           // A token is planted again, so there is a session again.
           this.sessionEnded = false;
           if (this.tokenStore.getAccessToken() !== newToken) {
-            this.tokenStore.setTokens(newToken);
-            this.notifyTokenChange();
+            this.setTokens(newToken);
           }
           this.noFresherTokenThan = isInsideRefreshLeadWindow(newToken) ? newToken : null;
           // A success clears the failure timestamp so the next refresh is never
@@ -1463,56 +1499,101 @@ export class HttpService {
    * abort signal defines the lifetime of a healthy stream.
    */
   async requestAuthenticatedResponse(config: AuthenticatedResponseRequest): Promise<Response> {
-    const authHeader = await this.getAuthHeader();
-    if (!authHeader) {
-      throw new OxyAuthenticationError(
-        'An active Oxy session is required for this request',
-        'AUTH_REQUIRED',
-      );
-    }
+    return this.requestRawResponse(config, true);
+  }
 
-    return this.requestAuthenticatedResponseAttempt(config, authHeader, false);
+  /**
+   * Raw response for public or authenticated app endpoints. The SDK supplies
+   * its current bearer when available; caller headers never supply authority.
+   * No caching, envelope transformation or transport-error retry is performed.
+   */
+  async requestResponse(config: ResponseRequest): Promise<Response> {
+    return this.requestRawResponse(config, false);
   }
 
-  private async requestAuthenticatedResponseAttempt(
-    config: AuthenticatedResponseRequest,
-    authHeader: string,
+  private async requestRawResponse(config: ResponseRequest, requireAuth: boolean): Promise<Response> {
+    // Validate before obtaining a bearer: an unrelated origin must not trigger
+    // an auth mint, even when the trusted transport accepts absolute URLs.
+    const target = new URL(this.buildURL(config.url));
+    const base = new URL(this.baseURL);
+    if (target.origin !== base.origin || !['http:', 'https:'].includes(target.protocol)
+      || target.username || target.password) {
+      throw new Error('Raw response requests must target the configured API origin');
+    }
+    if (config.signal?.aborted) throw createCancelledError();
+    // Snapshot caller-owned options once, including headers, before any await.
+    const request = { ...config, headers: new Headers(config.headers) };
+    const contextToken = this.syncAccessTokenFromProvider();
+    const beforeAuthEpoch = this.sessionEpoch;
+    const authHeader = await awaitRequestSignal(this.getAuthHeader(), config.signal);
+    if (beforeAuthEpoch !== this.sessionEpoch || !sameTokenSession(contextToken, this.tokenStore.getAccessToken())) {
+      throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+    }
+    if (config.signal?.aborted) throw createCancelledError();
+    if (requireAuth && !authHeader) {
+      throw new OxyAuthenticationError('An active Oxy session is required for this request', 'AUTH_REQUIRED');
+    }
+    return this.requestResponseAttempt(request, target.href, authHeader, false, this.sessionEpoch, contextToken);
+  }
+
+  private async requestResponseAttempt(
+    config: ResponseRequest,
+    fullUrl: string,
+    authHeader: string | null,
     isAuthRetry: boolean,
+    epoch: number,
+    contextToken: string | null,
   ): Promise<Response> {
+    const assertCurrent = (): void => {
+      this.syncAccessTokenFromProvider();
+      if (epoch !== this.sessionEpoch || !sameTokenSession(contextToken, this.tokenStore.getAccessToken())) {
+        throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+      }
+    };
     const startTime = Date.now();
+    if (config.signal?.aborted) throw createCancelledError();
+    assertCurrent();
     const headers = new Headers(config.headers);
-    if (!headers.has('Accept')) {
-      headers.set('Accept', 'application/json');
-    }
-    // Authentication is owned by this SDK instance. A caller cannot replace
-    // the bearer with a different session or leak one across linked apps.
-    headers.set('Authorization', authHeader);
-    // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
-    // to a second in front of requests.
+    if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+    // Never accept ambient credentials or another authority from a caller.
+    for (const name of ['Authorization', 'Cookie', 'Cookie2', 'Host', 'Proxy-Authorization']) headers.delete(name);
+    if (authHeader) headers.set('Authorization', authHeader);
     const edgeRegionHeader = peekBrowserEdgeRegionHeader();
     for (const [name, value] of Object.entries(edgeRegionHeader)) headers.set(name, value);
     const activityIdHeader = getBrowserActivityIdHeader();
     for (const [name, value] of Object.entries(activityIdHeader)) headers.set(name, value);
 
     try {
-      const fullUrl = this.buildURL(config.url);
-      const response = await fetch(fullUrl, {
+      const body = config.method === 'GET' ? undefined : config.body;
+      const init: RequestInit & { duplex?: 'half' } = {
         method: config.method,
         headers,
-        body: config.method === 'GET' ? undefined : config.body,
+        body,
         signal: config.signal,
-        credentials: this.getCredentialsMode(fullUrl),
-      });
-
-      if (response.status === 401 && !isAuthRetry) {
-        const refreshed = await this.refreshAccessToken('response-401');
+        credentials: 'omit',
+        redirect: 'error',
+      };
+      // Node fetch requires this flag for streaming uploads; ordinary and
+      // multipart bodies keep the platform's existing body serialization.
+      if (body && typeof body === 'object' && 'getReader' in body) init.duplex = 'half';
+      const response = await (config.fetch ?? globalThis.fetch)(fullUrl, init);
+      try { assertCurrent(); } catch (error) { await response.body?.cancel(); throw error; }
+      const replayable = body === undefined || typeof body === 'string';
+      if (response.status === 401 && !isAuthRetry && authHeader && replayable && !config.signal?.aborted) {
+        let refreshed: string | null;
+        try {
+          refreshed = await awaitRequestSignal(this.refreshAccessToken('response-401'), config.signal);
+        } catch (error) {
+          void response.body?.cancel().catch(() => undefined);
+          throw error;
+        }
+        try { assertCurrent(); } catch (error) { await response.body?.cancel(); throw error; }
         if (refreshed) {
           await response.body?.cancel();
-          return this.requestAuthenticatedResponseAttempt(config, `Bearer ${refreshed}`, true);
+          if (config.signal?.aborted) throw createCancelledError();
+          return this.requestResponseAttempt(config, fullUrl, `Bearer ${refreshed}`, true, epoch, contextToken);
         }
-
-        this.tokenStore.clearTokens();
-        this.notifyTokenChange();
+        this.clearTokens();
       }
 
       const duration = Date.now() - startTime;
@@ -1523,8 +1604,11 @@ export class HttpService {
       const duration = Date.now() - startTime;
       this.updateMetrics(false, duration);
       this.config.onRequestEnd?.(config.url, config.method, duration, false);
-      const normalizedError = error instanceof Error ? error : new Error(String(error));
+      const normalizedError = config.signal?.aborted || isCancelledError(error)
+        ? createCancelledError()
+        : error instanceof Error ? error : new Error(String(error));
       this.config.onRequestError?.(config.url, config.method, normalizedError);
+      if (isCancelledError(normalizedError) || normalizedError instanceof OxyAuthenticationError) throw normalizedError;
       throw handleHttpError(normalizedError);
     }
   }
@@ -1552,6 +1636,8 @@ export class HttpService {
 
   // Token management
   setTokens(accessToken: string): void {
+    const current = this.tokenStore.getAccessToken();
+    if (current && !sameTokenSession(current, accessToken)) this.sessionEpoch += 1;
     this.sessionEnded = false;
     this.tokenStore.setTokens(accessToken);
     this.notifyTokenChange();
@@ -1561,18 +1647,19 @@ export class HttpService {
    * End the local session: clear the bearer and abandon every re-mint already
    * in flight, so none of them can plant a token after the sign-out.
    *
-   * {@link clearTokens} alone only drops the bearer, which is right for a
-   * mirror (a linked client following its parent) but not for a sign-out: a
-   * refresh started a moment earlier would finish and plant a new one.
+   * Unlike {@link clearTokens}, this also marks the session as ended and
+   * invalidates pending re-mints even when no bearer is currently present.
    */
   endSession(): void {
-    this.sessionEpoch += 1;
+    if (!this.tokenStore.getAccessToken()) this.sessionEpoch += 1;
     this.sessionEnded = true;
     this.clearTokens();
   }
 
   /**
-   * The current session epoch — see {@link endSession}. A re-mint lane that
+   * The current context epoch: account/session switches and bearer removal
+   * invalidate pending work; rotation within the same context preserves it.
+   * A re-mint lane that
    * plants tokens itself (the device-secret arm) compares it across its awaits.
    */
   getSessionEpoch(): number {
@@ -1604,6 +1691,7 @@ export class HttpService {
   }
 
   clearTokens(): void {
+    if (this.tokenStore.getAccessToken()) this.sessionEpoch += 1;
     this.tokenStore.clearTokens();
     // Drop the response cache on logout. The cache is identity-scoped, so a
     // different user could never read these entries, but a logged-out client

package/src/api/accounts.ts

@@ -17,6 +17,8 @@
  * no per-request "acting-as" header. Identity is carried by the session/token,
  * so a switch propagates through reload and cross-domain exactly like a login.
  */
+import { agentKeyOperationSchema, executeAgentKeyOperationSchema, agentKeyOperationChallengeSchema,
+  agentKeyOperationResultSchema, agentKeyListResponseSchema, type AgentKeyOperation, type AgentKeyOperationProof } from '@oxy.so/contracts';
 import type { User } from '../models/interfaces';
 import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
@@ -413,12 +415,32 @@ export class AccountMembersApi {
   }
 }
 
+/** Current account governors and autonomous rotation use action-bound proofs. */
+export class AccountAgentKeysApi {
+  constructor(private readonly ctx: OxyContext) {}
+  async list(accountId: string) {
+    return agentKeyListResponseSchema.parse(await this.ctx.request<unknown>('GET', `/accounts/${enc(accountId)}/agent-keys`, undefined, { cache: false }));
+  }
+  async requestChallenge(accountId: string, operation: AgentKeyOperation) {
+    const response = await this.ctx.request<unknown>('POST', `/accounts/${enc(accountId)}/agent-keys/challenge`,
+      agentKeyOperationSchema.parse(operation), { cache: false });
+    return agentKeyOperationChallengeSchema.parse(response);
+  }
+  async execute(accountId: string, operation: AgentKeyOperation, proof: AgentKeyOperationProof) {
+    const response = await this.ctx.request<unknown>('POST', `/accounts/${enc(accountId)}/agent-keys/execute`,
+      executeAgentKeyOperationSchema.parse({ operation, proof }), { cache: false });
+    return agentKeyOperationResultSchema.parse(response);
+  }
+}
+
 export class AccountsApi {
   /** Who can act on an account, and with what role. */
   readonly members: AccountMembersApi;
+  readonly agentKeys: AccountAgentKeysApi;
 
   constructor(private readonly ctx: OxyContext) {
     this.members = new AccountMembersApi(ctx);
+    this.agentKeys = new AccountAgentKeysApi(ctx);
   }
 
   /**

package/src/api/agency.ts

@@ -83,7 +83,9 @@ export interface CapabilityExecutionAuthorization {
   ownerAccountId: string;
   coordinatorApplicationId: string;
   coordinatorCredentialId: string;
-  actorType: 'alia' | 'agent';
+  actorType: 'alia' | 'agent' | 'requester';
+  requesterSessionId?: string | null;
+  requesterSessionBindingDigest?: string | null;
   actorAccountId: string | null;
   resourceApp: string;
   effectiveAccountId: string;

package/src/api/apps.ts

@@ -565,13 +565,13 @@ export class AppsApi {
    * consent, authorize, and device-flow approval screens before any session
    * exists.
    */
-  async getPublic(clientId: string): Promise<PublicApplication> {
+  async getPublic(clientId: string, options: { cache?: boolean } = {}): Promise<PublicApplication> {
     const res = await this.ctx.request<{ application: PublicApplication }>(
       'GET',
       `/auth/oauth/client/${enc(clientId)}`,
       undefined,
       // Public client metadata (pre-session consent UI) — skip the bearer preflight.
-      { cache: true, cacheTTL: MEDIUM_TTL, skipAuth: true },
+      { cache: options.cache ?? true, cacheTTL: MEDIUM_TTL, skipAuth: true },
     );
     return res.application;
   }

package/src/api/auth.ts

@@ -18,6 +18,11 @@
 import type { User } from '../models/interfaces';
 import type { CommonsDenyReason, DeviceProof, LoginResult } from '@oxy.so/contracts';
 import {
+  agentProofClaimsSchema,
+  agentChallengeRequestSchema,
+  agentVerifyRequestSchema,
+  type AgentProofClaims,
+  type AgentSignature,
   emailSignInLinkResponseSchema,
   emailSignInPendingSchema,
   emailSignInStartResponseSchema,
@@ -693,12 +698,13 @@ export class AuthOAuthApi {
    * out, so the app can run the OAuth flow again. It never degrades into a
    * session that looks alive and cannot refresh.
    */
+  /** `plantTokens: false` defers bearer installation to a validated provider commit. */
   async exchangeCode(params: {
     code: string;
     clientId: string;
     redirectUri: string;
     codeVerifier: string;
-  }): Promise<OAuthTokenExchangeResult> {
+  }, options: { plantTokens?: boolean } = {}): Promise<OAuthTokenExchangeResult> {
     const form = new URLSearchParams({
       grant_type: 'authorization_code',
       code: params.code,
@@ -735,7 +741,9 @@ export class AuthOAuthApi {
     const expiresInSec =
       typeof record.expires_in === 'number' ? record.expires_in : DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
     const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
-    if (accessToken) {
+    // Provider completion validates the expected subject before committing.
+    // Direct callers retain the historical token-planting default.
+    if (accessToken && options.plantTokens !== false) {
       this.ctx.oxy.session.setAccessToken(accessToken);
     }
     if (!deviceId || !deviceSecret) {
@@ -1158,6 +1166,25 @@ export class AuthCommonsApi {
 
 }
 
+/** Bot entry uses caller-owned keys and the normal account session lane. */
+export class AuthAgentApi {
+  constructor(private readonly ctx: OxyContext) {}
+
+  async requestChallenge(publicKey: string): Promise<AgentProofClaims> {
+    const body = agentChallengeRequestSchema.parse({ publicKey });
+    const response = await this.ctx.request<unknown>('POST', '/auth/agent/challenge', body,
+      { cache: false, skipAuth: true });
+    return agentProofClaimsSchema.parse(response);
+  }
+
+  async verify(publicKey: string, proof: AgentSignature): Promise<LoginResult> {
+    const body = agentVerifyRequestSchema.parse({ publicKey, ...proof });
+    const response = await this.ctx.request<unknown>('POST', '/auth/agent/verify', body,
+      { cache: false, skipAuth: true });
+    return plantSession(this.ctx, response, 'auth/agent/verify');
+  }
+}
+
 export class AuthApi {
   /** Email sign-in and email confirmation codes. */
   readonly email: AuthEmailApi;
@@ -1169,6 +1196,7 @@ export class AuthApi {
   readonly oauth: AuthOAuthApi;
   /** "Sign in with Oxy" handoff to Commons. */
   readonly commons: AuthCommonsApi;
+  readonly agent: AuthAgentApi;
 
   constructor(private readonly ctx: OxyContext) {
     this.email = new AuthEmailApi(ctx);
@@ -1176,6 +1204,7 @@ export class AuthApi {
     this.totp = new AuthTotpApi(ctx);
     this.oauth = new AuthOAuthApi(ctx);
     this.commons = new AuthCommonsApi(ctx);
+    this.agent = new AuthAgentApi(ctx);
   }
 
   /**