@oxy.so/core 4.0.0 → 4.2.0

package/dist/types/api/accounts.d.ts

@@ -17,6 +17,7 @@
  * 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 { 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';
@@ -340,10 +341,47 @@ export declare class AccountMembersApi {
      */
     remove(accountId: string, memberId: string): Promise<AccountSuccessResult>;
 }
+/** Current account governors and autonomous rotation use action-bound proofs. */
+export declare class AccountAgentKeysApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    list(accountId: string): Promise<{
+        keys: {
+            id: string;
+            revokedAt: string | null;
+            publicKey: string;
+            label: string;
+            enrolledByUserId: string | null;
+            enrollmentMethod: "governor" | "rotation" | "recovery";
+            linkedAt: string;
+            lastUsedAt: string | null;
+        }[];
+    }>;
+    requestChallenge(accountId: string, operation: AgentKeyOperation): Promise<{
+        claims: {
+            expiresAt: number;
+            accountId: string;
+            version: 1;
+            audience: "oxy-api/agent";
+            action: "agent_signin" | "agent_enroll" | "agent_rotate" | "agent_recover" | "agent_governance";
+            challenge: string;
+            actorId: string;
+            authMethodId: string | null;
+            publicKey: string;
+            payloadDigest: string;
+        };
+        governorPublicKey: string | null;
+    }>;
+    execute(accountId: string, operation: AgentKeyOperation, proof: AgentKeyOperationProof): Promise<{
+        methodId: string | null;
+        revokedMethodIds: string[];
+    }>;
+}
 export declare class AccountsApi {
     private readonly ctx;
     /** Who can act on an account, and with what role. */
     readonly members: AccountMembersApi;
+    readonly agentKeys: AccountAgentKeysApi;
     constructor(ctx: OxyContext);
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/types/api/agency.d.ts

@@ -52,7 +52,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/dist/types/api/apps.d.ts

@@ -422,7 +422,9 @@ export declare class AppsApi {
      * consent, authorize, and device-flow approval screens before any session
      * exists.
      */
-    getPublic(clientId: string): Promise<PublicApplication>;
+    getPublic(clientId: string, options?: {
+        cache?: boolean;
+    }): Promise<PublicApplication>;
     /**
      * Bust every cached application list — the unscoped entry and every
      * owner-scoped `GET:/applications?ownerAccountId=<id>` variant — plus any

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

@@ -17,7 +17,7 @@
  */
 import type { User } from '../models/interfaces';
 import type { CommonsDenyReason, DeviceProof, LoginResult } from '@oxy.so/contracts';
-import { type EmailSignInPending, type EmailSignInStartResponse, type EmailVerificationConfirmResponse, type EmailVerificationStartRequest, type EmailVerificationStartResponse, type ReauthAction, type ReauthProof, type SignInMethods, type SignInStepResult, type TotpEnrollResponse } from '@oxy.so/contracts';
+import { type AgentProofClaims, type AgentSignature, type EmailSignInPending, type EmailSignInStartResponse, type EmailVerificationConfirmResponse, type EmailVerificationStartRequest, type EmailVerificationStartResponse, type ReauthAction, type ReauthProof, type SignInMethods, type SignInStepResult, type TotpEnrollResponse } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 import type { SessionLoginResponse } from '../models/session';
 import type { PublicApplication } from './apps';
@@ -425,11 +425,14 @@ export declare 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. */
     exchangeCode(params: {
         code: string;
         clientId: string;
         redirectUri: string;
         codeVerifier: string;
+    }, options?: {
+        plantTokens?: boolean;
     }): Promise<OAuthTokenExchangeResult>;
     /**
      * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
@@ -608,6 +611,13 @@ export declare class AuthCommonsApi {
      */
     deny(authorizeCode: string, reason?: CommonsDenyReason): Promise<CommonsSignInActionResult>;
 }
+/** Bot entry uses caller-owned keys and the normal account session lane. */
+export declare class AuthAgentApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    requestChallenge(publicKey: string): Promise<AgentProofClaims>;
+    verify(publicKey: string, proof: AgentSignature): Promise<LoginResult>;
+}
 export declare class AuthApi {
     private readonly ctx;
     /** Email sign-in and email confirmation codes. */
@@ -620,6 +630,7 @@ export declare class AuthApi {
     readonly oauth: AuthOAuthApi;
     /** "Sign in with Oxy" handoff to Commons. */
     readonly commons: AuthCommonsApi;
+    readonly agent: AuthAgentApi;
     constructor(ctx: OxyContext);
     /**
      * Register a new identity with public key authentication

package/dist/types/api/billing.d.ts

@@ -9,6 +9,8 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { type SubjectProductAccess, type SubjectProductAccessQuery } from '@oxy.so/contracts';
+import { type ProductSubscriptionSummary, type SubscriptionCreditGrant, type ProductSubscriptionCancellationResult } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 /** Subscription tier. */
 export type SubscriptionPlan = 'basic' | 'pro' | 'business';
@@ -97,6 +99,16 @@ export interface WalletTransactionsPage {
 export declare class BillingApi {
     protected readonly ctx: OxyContext;
     constructor(ctx: OxyContext);
+    /** Product rights only; requires a production application-bound user session. Never cached. */
+    productAccess(query: SubjectProductAccessQuery): Promise<SubjectProductAccess>;
+    /** Named commercial sources for the current subject; no inferred plan collapse. */
+    productSubscriptions(): Promise<ProductSubscriptionSummary[]>;
+    /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
+    creditGrants(): Promise<SubscriptionCreditGrant[]>;
+    /** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
+    cancelProductSubscription(sourceId: string, expectedSubjectAccountId?: string): Promise<void>;
+    /** Provider acceptance versus completed local cancellation, for user-facing flows. */
+    cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string): Promise<ProductSubscriptionCancellationResult>;
     /** The signed-in user's payment history. Never cached. */
     payments(): Promise<Payment[]>;
     /** A user's subscription (default: the signed-in user's). */

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

@@ -1,4 +1,4 @@
-import type { DeviceProof } from '@oxy.so/contracts';
+import type { AccountActorChain, DeviceProof } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
@@ -15,6 +15,8 @@ export interface SessionValidation {
     user: User;
     sessionId?: string;
     source?: string;
+    /** Who acted, and as whom, read off the session row (issue #1520). */
+    actor?: AccountActorChain;
 }
 export declare class SessionApi {
     private readonly ctx;

package/dist/types/boot/sessionColdBoot.d.ts

@@ -42,7 +42,7 @@
  */
 import { type ColdBootOutcome } from '../utils/coldBoot';
 import { type IdentityBinding } from '../session/identitySession';
-import { type SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
+import type { SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
 import type { DeviceSessionState } from '@oxy.so/contracts';

package/dist/types/index.d.ts

@@ -24,7 +24,7 @@ export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices';
 export type { OxyConfig, LinkedHttpClient } from './OxyServices';
 export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
-export type { RequestOptions, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
+export type { RequestOptions, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 export type { SessionApi, DeviceCredentialProvider, SessionValidation } from './api/session';
 export type { AuthApi, ChallengeResponse, RegistrationRequest, ChallengeVerifyRequest, PublicKeyCheckResponse, OAuthUserInfoResponse, OAuthTokenExchangeResult, CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, SignInDeviceOptions, ClaimedSession, } from './api/auth';
 export type { UsersApi, ResolveExternalUserInput, DeleteAccountProof } from './api/users';

package/dist/types/inference/OxyInferenceClient.d.ts

@@ -1,3 +1,4 @@
+import type { MeteredGeneration } from '@oxy.so/contracts';
 /**
  * The Oxy inference client — one surface, two credential lanes (issue #972,
  * workstream 15).
@@ -49,6 +50,7 @@
  * schema, so a rename on either side fails a build rather than a customer's
  * request.
  */
+import { type DecisionRequest, type DecisionSuccess } from '@oxy.so/contracts';
 import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceReasoning, InferenceRequestOutcome, InferenceAudioMediaType, InferenceStreamEvent, InferenceSpeechParameters, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxy.so/contracts';
 /** The base URL of the Oxy API, when a caller names none. */
 export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
@@ -222,6 +224,8 @@ export interface OxyGenerationReceipt {
     readonly platformFeeOnly: boolean;
     readonly settledAt: string;
 }
+/** The endpoint returns either a customer receipt or internal technical usage. */
+export type OxyGenerationRecord = OxyGenerationReceipt | MeteredGeneration;
 /**
  * Anything the inference API refused.
  *
@@ -336,6 +340,8 @@ export declare class OxyInferenceClient {
      *   `code`, `retryable` and `requestId`.
      */
     respond(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): Promise<OxyInferenceResponse>;
+    /** Typed nonstreaming decisions. Idempotency conflicts are never replayed or retried. */
+    decide(request: DecisionRequest, options?: OxyInferenceRequestOptions): Promise<DecisionSuccess>;
     /** Generate audio bytes through Oxy's authenticated inference edge. */
     speech(request: OxySpeechRequest, options?: OxyInferenceRequestOptions): Promise<OxySpeechResponse>;
     /**
@@ -369,5 +375,11 @@ export declare class OxyInferenceClient {
      */
     getGeneration(id: string, options?: {
         signal?: AbortSignal;
+        delegatedUserId?: string;
     }): Promise<OxyGenerationReceipt>;
+    /** Read a financial receipt (v1) or an internal technical record (v2). */
+    getGenerationRecord(id: string, options?: {
+        signal?: AbortSignal;
+        delegatedUserId?: string;
+    }): Promise<OxyGenerationRecord>;
 }

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

@@ -14,7 +14,7 @@
 import type { OxyServices } from '../OxyServices';
 import { OxyInferenceClient, type OxyInferenceClientOptions } from './OxyInferenceClient';
 export { OXY_INFERENCE_BASE_URL, OxyInferenceClient, OxyInferenceError, OxyInferenceProtocolError, } from './OxyInferenceClient';
-export type { OxyGenerationReceipt, OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyResponsesRequest, OxySpeechRequest, OxySpeechResponse, } from './OxyInferenceClient';
+export type { OxyGenerationReceipt, OxyGenerationRecord, OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyResponsesRequest, OxySpeechRequest, OxySpeechResponse, } from './OxyInferenceClient';
 /**
  * An inference client bound to `oxy`'s session: it calls the same API origin
  * with the session's current bearer on every request.

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

@@ -36,6 +36,14 @@ export interface OxyServerConfig extends OxyConfig {
  */
 export declare const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
 /** `POST /auth/service-token`. */
+export interface ActingAsVerificationOptions {
+    /** Only explicit read-only callers may reuse authority; effects always pass false. */
+    cache?: boolean;
+    /** Taken from verified service claims by middleware, never from a user header. */
+    credentialId?: string;
+    ownerAccountId?: string;
+    environment?: string;
+}
 export interface ServiceTokenResponse {
     token: string;
     expiresIn: number;
@@ -55,6 +63,7 @@ export declare class OxyServer extends OxyServices {
     private serviceApiSecret;
     private readonly actingAs;
     private readonly actingAsPending;
+    private readonly actingAsGenerations;
     /** Public keys only; never private material. */
     private readonly jwksCache;
     /**
@@ -124,16 +133,13 @@ export declare class OxyServer extends OxyServices {
         actAs?: string;
     }): Promise<T>;
     /**
-     * Whether service app `appId` holds an active delegation grant to act for
-     * `userId`; the grant's scopes, or `null`. Used by `middleware.auth()` for
-     * `X-Oxy-User-Id`.
-     *
-     * Answers are cached per `appId:userId` (a grant for 5 minutes — the
-     * revocation window; a denial or failed lookup for 1 minute), bounded to the
-     * 1000 most recent pairs, and concurrent lookups of one pair share a single
-     * request.
+     * Resolve authority live by default. Explicit read-only reuse lasts at most
+     * 60s positive / 10s negative, anchored to request start; errors never cache.
+     * Effects do not share an older in-flight read. Durable epoch plus local
+     * completion ordering prevents ABA and late positive replies overwriting a
+     * newer refusal even when app/credential revocation leaves epoch unchanged.
      */
-    verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+    verifyActingAs(appId: string, userId: string, options?: ActingAsVerificationOptions): Promise<ServiceActingAsVerification | null>;
     /**
      * Account events addressed to this application (Oxy account deletions every
      * relying application must honour, OxyHQ/Mention#1169).
@@ -176,6 +182,7 @@ export declare class OxyServer extends OxyServices {
     /** A token obtained by attestation, cached like a credential's (one identity per process). */
     private workloadServiceToken;
     private lookupActingAs;
+    private clearActingAsPair;
     private rememberActingAs;
     private verifyAccountEvent;
     /** The `appId` claim of this service's own token. */

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

@@ -0,0 +1,14 @@
+/** Autonomous entry helper. The signer owns its private key (for example in a KMS). */
+import { type LoginResult } from '@oxy.so/contracts';
+import type { OxyServices } from '../OxyServices';
+export interface AgentAccountSigner {
+    /** Compressed or uncompressed SEC1 secp256k1 public key; no private-key field exists. */
+    publicKey: string;
+    signMessage(message: string): Promise<string>;
+}
+/** Explicit sign-in; no timer, automatic escalation or service credential lane. */
+export declare function signInAgentAccount(options: {
+    client: Pick<OxyServices, 'auth'>;
+    accountId: string;
+    signer: AgentAccountSigner;
+}): Promise<LoginResult>;

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

@@ -1,5 +1,6 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { AuthMiddlewareOptions, OxyAuthRefusal, OxyMiddleware } from './middleware';
+import type { AccountActorChain } from '@oxy.so/contracts';
 import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 export { OXY_SERVICE_ENVIRONMENTS };
 export type { OxyServiceEnvironment, OxyAuthRefusal };
@@ -37,6 +38,12 @@ export interface OxyAuthRequest extends Request {
     sessionId?: string | null;
     serviceApp?: OxyServiceAppContext;
     serviceActingAs?: OxyServiceActingAsContext;
+    /**
+     * Who acted, and as whom, on a USER session — read off the session row by the
+     * Oxy API, never off a header. `null`/absent when the request is not a user
+     * session or the API did not report it. Read it with {@link getOxyActor}.
+     */
+    oxyActor?: AccountActorChain | null;
     /**
      * Why the presented credential was refused, when one was and the request
      * still reached the handler (the optional path). Read it with
@@ -57,6 +64,17 @@ export interface OxyAuthMiddlewareOptions {
     auth?: AuthMiddlewareOptions;
 }
 export declare function getOxyUserId(req: Request): string | null;
+/**
+ * Who acted, and as whom, on this user session (issue #1520), or `null` when
+ * the session authority did not report it.
+ *
+ * An audit records `actorAccountId` as the actor and `effectiveAccountId`
+ * (equal to {@link getOxyUserId}) as the account spoken as. A bot acting with
+ * nobody operating it is its own actor; a person acting as an organization or
+ * a bot is the actor of a `delegated` chain. Never substitute the effective
+ * account's owner for either: when this is `null`, record the actor as unknown.
+ */
+export declare function getOxyActor(req: Request): AccountActorChain | null;
 export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
 /**
  * The principal a request is CHARGED to, and the identifiers a receipt needs.

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

@@ -1,5 +1,5 @@
 import { type KeyObject } from 'node:crypto';
-import { type CapabilityTicketClaims, type GrantLimit, type PolicyDecision } from '@oxy.so/contracts';
+import { type CapabilityTicketClaims, type PolicyDecision } from '@oxy.so/contracts';
 import type { Request, RequestHandler } from 'express';
 type UnsignedCapabilityTicketClaims = Omit<CapabilityTicketClaims, 'iss' | 'iat' | 'exp' | 'jti'>;
 export interface CapabilityTicketSigningOptions {
@@ -27,8 +27,6 @@ export declare class CapabilityTicketError extends Error {
     readonly code: 'malformed' | 'invalid_signature' | 'unknown_key' | 'invalid_claims' | 'expired' | 'not_yet_valid' | 'wrong_audience' | 'wrong_issuer' | 'ttl_exceeded';
     constructor(code: 'malformed' | 'invalid_signature' | 'unknown_key' | 'invalid_claims' | 'expired' | 'not_yet_valid' | 'wrong_audience' | 'wrong_issuer' | 'ttl_exceeded', message: string);
 }
-/** Enforces the signed per-action bounds before a domain handler runs. */
-export declare function inputSatisfiesCapabilityLimits(tool: string, input: Record<string, unknown>, limits: readonly GrantLimit[]): boolean;
 export declare function issueCapabilityTicket(claims: UnsignedCapabilityTicketClaims, options: CapabilityTicketSigningOptions): string;
 export declare function verifyCapabilityTicket(token: string, options: CapabilityTicketVerificationOptions): CapabilityTicketClaims;
 export declare function readCapabilityAuthorization(authorization: string | undefined): string | null;
@@ -38,4 +36,4 @@ export declare function readCapabilityAuthorization(authorization: string | unde
  * planning and execution.
  */
 export declare function createCapabilityTicketMiddleware(options: CapabilityTicketMiddlewareOptions): RequestHandler;
-export {};
+export { inputSatisfiesCapabilityLimits } from '@oxy.so/contracts';

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

@@ -17,9 +17,10 @@
 export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS } from './OxyServer';
 export type { OxyServerConfig, ServiceTokenResponse } from './OxyServer';
 export { ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces';
+export type { CapabilityTicketGrant, CapabilityTicketIntrospection, CreateExecutionAuthorizationInput, ServiceCapabilityCatalog, } from './namespaces';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
 export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyActor, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
 export type { OxyAuthHost } from './auth';
 export type { OxyAuthenticatedRequest, OxyAuthRefusal, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
@@ -35,6 +36,8 @@ export type { CapabilityTicketMiddlewareOptions, CapabilityTicketRequest, Capabi
 export { createOxyJwksKeyResolver, createOxyRequesterAssertionAuth, OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER, OXY_REQUESTER_ASSERTION_HEADER, OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS, OXY_REQUESTER_ASSERTION_TYPE, OxyRequesterAssertionError, oxyRequesterAssertionClaimsSchema, readOxyRequesterAssertionKeyId, signOxyRequesterAssertion, verifyOxyRequesterAssertion, } from './requesterAssertion';
 export type { OxyJwksKeyResolverOptions, OxyRequesterAssertionAuthOptions, OxyRequesterAssertionClaims, OxyRequesterAssertionErrorCode, OxyRequesterAssertionIntrospection, OxyRequesterAssertionIntrospector, OxyRequesterAssertionRequest, OxyRequesterAssertionVerificationOptions, OxyRequesterContext, } from './requesterAssertion';
 export { verifySecret } from './verifySecret';
+export { createLiveCapabilityTicketVerifier } from './liveCapabilityTicket';
+export type { LiveCapabilityTicketVerifierOptions } from './liveCapabilityTicket';
 export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation';
 export type { OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } from './userInvalidation';
 export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep';
@@ -52,3 +55,6 @@ export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
  */
 export { canAttestWorkloadIdentity, requestWorkloadServiceToken } from './workloadIdentity';
 export type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';
+export { OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS, hasBoundedServiceTokenLifetime } from './serviceTokenLifetime';
+export { signInAgentAccount } from './agentAccount';
+export type { AgentAccountSigner } from './agentAccount';

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

@@ -0,0 +1,15 @@
+import { type CapabilityTicketClaims } from '@oxy.so/contracts';
+import { type CapabilityTicketVerificationOptions } from './capabilityTicket';
+import type { CapabilityTicketIntrospection } from './namespaces';
+export interface LiveCapabilityTicketVerifierOptions extends CapabilityTicketVerificationOptions {
+    issuer: string;
+    introspect: (ticket: string, options: {
+        signal: AbortSignal;
+    }) => Promise<CapabilityTicketIntrospection>;
+    /** Network bound only; does not establish an authority freshness policy. */
+    timeoutMs?: number;
+}
+/** Local signature + live receiving-service introspection; no cache or retry. */
+export declare function createLiveCapabilityTicketVerifier(options: LiveCapabilityTicketVerifierOptions): (ticket: string, input?: {
+    signal?: AbortSignal;
+}) => Promise<CapabilityTicketClaims>;

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

@@ -6,6 +6,7 @@
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
 import type { OxyRequestUser } from './auth';
+import { type AccountActorChain } from '@oxy.so/contracts';
 import type { ApiError, User } from '../models/interfaces';
 import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 /**
@@ -29,6 +30,8 @@ import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
  * authoritative store stays server-side.
  */
 export interface ServiceActingAsVerification {
+    /** Decimal durable generation, never lossy JS number. */
+    epoch?: string;
     authorized: boolean;
     scopes: string[];
 }
@@ -113,11 +116,10 @@ export interface ServiceApp {
     appName: string;
     scopes: string[];
     /**
-     * `internal` when the caller is one of Oxy's own applications: app to app it
-     * is trusted outright — {@link requireScope} passes and it may act for a user
-     * without a delegation grant. `external` keeps every scope and grant rule.
-     * What the USER may do (their accounts, plan, limits) is still for the
-     * receiving service to decide. A token without the claim reads as `external`.
+     * Classification only. Both tiers obey scope ceilings and live offline
+     * delegation; neither a brand nor a header proves a user's authority.
+     * Resource authorization remains with the receiving service. A missing
+     * claim reads as external.
      */
     tier: 'internal' | 'external';
     /** The credentialId of the specific service credential that minted this token. */
@@ -225,8 +227,14 @@ export interface OxyMiddlewareHost {
     }): Promise<{
         valid: boolean;
         user?: User;
+        actor?: unknown;
     } | null>;
-    verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+    verifyActingAs(appId: string, userId: string, options?: {
+        cache?: boolean;
+        credentialId?: string;
+        ownerAccountId?: string;
+        environment?: string;
+    }): Promise<ServiceActingAsVerification | null>;
 }
 /** Build the middleware set for one server. See `OxyServer.middleware`. */
 export declare function createOxyMiddleware(host: OxyMiddlewareHost): {
@@ -276,6 +284,7 @@ interface AuthReq {
         userId: string;
         scopes: string[];
     };
+    oxyActor?: AccountActorChain | null;
     oxyAuthRefusal?: OxyAuthRefusal;
 }
 interface AuthRes {

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

@@ -4,12 +4,12 @@
  * `server.assets.metadataByIds(...)` sits beside every client method of
  * `oxy.assets`.
  */
-import type { CreateOxyNotificationRequest, AwardReputationInput, ReputationTransaction, ServiceLinkedAccountListResponse } from '@oxy.so/contracts';
+import { type ForegroundExecutionAuthorizationInput, type ActorRef, type AppCapabilityCatalog, type AutonomyLevel, type CapabilityTicketClaims, type CapabilityTicketRequest, type GrantLimit, type PolicyDecision, type ResourceRef, type CreateOxyNotificationRequest, type AwardReputationInput, type ReputationTransaction, type ServiceLinkedAccountListResponse } from '@oxy.so/contracts';
 import type { Notification, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceLinkedDownloadUrl } from '../models/interfaces';
 import { AssetsApi } from '../api/assets';
 import { NotificationsApi } from '../api/notifications';
 import { LinkedAccountsApi } from '../api/linkedAccounts';
-import { AgencyApi, type RequesterAssertionGrant, type RequesterAssertionIntrospection } from '../api/agency';
+import { AgencyApi, type CapabilityExecutionAuthorization, type RequesterAssertionGrant, type RequesterAssertionIntrospection } from '../api/agency';
 import { ReputationApi } from '../api/reputation';
 export declare class ServerAssetsApi extends AssetsApi {
     /**
@@ -71,7 +71,82 @@ export declare class ServerLinkedAccountsApi extends LinkedAccountsApi {
      */
     forUser(userId: string): Promise<ServiceLinkedAccountListResponse>;
 }
+/** Projection of the existing service-authenticated registry response. */
+export interface ServiceCapabilityCatalog {
+    id: string;
+    appSlug: string;
+    version: string;
+    digest: string;
+    audience: string;
+    catalog: AppCapabilityCatalog;
+}
+export interface CapabilityTicketGrant {
+    decision: PolicyDecision;
+    ticket?: string;
+    claims?: CapabilityTicketClaims;
+}
+export interface CapabilityTicketIntrospection {
+    active: boolean;
+    claims?: CapabilityTicketClaims;
+    decision?: PolicyDecision;
+    error?: string;
+}
+interface ExecutionAuthorizationTerms {
+    ownerAccountId: string;
+    coordinatorApplicationId: string;
+    coordinatorCredentialId: string;
+    actor: ActorRef;
+    resource: ResourceRef;
+    tool: string;
+    limits?: GrantLimit[];
+    expiresAt: string;
+}
+export type CreateExecutionAuthorizationInput = ExecutionAuthorizationTerms & ({
+    kind: 'direct_request';
+    runId: string;
+    stepId?: string;
+    automationId?: never;
+    maximumAutonomy: Exclude<AutonomyLevel, 'autonomous'>;
+} | {
+    kind: 'automation';
+    automationId: string;
+    runId?: never;
+    stepId?: never;
+    maximumAutonomy: AutonomyLevel;
+});
 export declare class ServerAgencyApi extends AgencyApi {
+    /** Live registry discovery with this service's existing capability scopes. */
+    serviceCatalogs(input?: {
+        appId?: string;
+        signal?: AbortSignal;
+    }): Promise<ServiceCapabilityCatalog[]>;
+    /** Existing Oxy execution authority is required; this call creates none. */
+    issueCapabilityTicket(input: CapabilityTicketRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<CapabilityTicketGrant>;
+    /** Receiving app authenticates live introspection using its own service credential. */
+    introspectCapabilityTicket(ticket: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<CapabilityTicketIntrospection>;
+    /**
+     * Authenticates the existing user-authority route with the requester's bearer.
+     * The service bearer and attribution headers cannot substitute for that user.
+     * The token goes only to this client's configured Oxy authority; never retry.
+     */
+    createExecutionAuthorization(input: CreateExecutionAuthorizationInput, options: {
+        requesterToken: string;
+        signal?: AbortSignal;
+    }): Promise<CapabilityExecutionAuthorization>;
+    /** Revoke a direct approval on its canonical requester-authenticated lane. */
+    revokeExecutionAuthorization(authorizationId: string, options: {
+        requesterToken: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Independent service proof plus present requester bearer, sent only to Oxy. */
+    createForegroundExecutionAuthorization(input: ForegroundExecutionAuthorizationInput, options: {
+        requesterToken: string;
+        signal?: AbortSignal;
+    }): Promise<CapabilityExecutionAuthorization>;
     /**
      * Product backend → Oxy: trade the signed-in requester's access token for a
      * one-use assertion naming `agentId` (ADR 0025), authenticated with this
@@ -104,3 +179,4 @@ export declare class ServerReputationApi extends ReputationApi {
      */
     award(input: AwardReputationInput): Promise<ReputationTransaction>;
 }
+export {};

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

@@ -0,0 +1,7 @@
+/** Approved I03 ceiling shared by issuance and both JWT verifiers. */
+export declare const OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = 300;
+/** Call only after signature verification; cache checks alone confer no authority. */
+export declare function hasBoundedServiceTokenLifetime(claims: {
+    iat?: unknown;
+    exp?: unknown;
+}, nowSeconds?: number): boolean;

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

@@ -37,6 +37,8 @@ export interface SessionClientHost {
     getCurrentAccountId(): string | null;
 }
 export interface SessionClientOptions {
+    /** Await durable local logout intent after an explicit removal or an applied nonempty→empty device transition. */
+    onFullExplicitSignOut?: () => Promise<void>;
     transport?: TokenTransport;
     /**
      * Invoked when an APPLIED state has zero accounts — i.e. a device
@@ -107,6 +109,8 @@ export declare class SessionClient {
     protected socket: MinimalSocket | null;
     private tokenUnsub;
     private started;
+    private lifecycleGeneration;
+    private fullSignOutPersistence;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
     /** App-facing subscriptions to named server-pushed socket events. */
@@ -114,6 +118,10 @@ export declare class SessionClient {
     /** Event names already bound on the CURRENT socket instance. */
     private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
+    private persistFullSignOut;
+    private requestDevice;
+    /** Stop and discard only this client's local device projection; no server revocation. */
+    resetLocalState(): void;
     getState(): DeviceSessionState | null;
     /**
      * The device directory, or `null` when this client has never read one.