@oxy.so/core 7.11.0 → 7.12.0

package/dist/esm/api/session.js

@@ -8,12 +8,21 @@
 import { jwtDecode } from 'jwt-decode';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 import { OxyApiError } from '../OxyServices.errors.js';
+import { checkContract, holderContextEvidenceV1ResponseCheck } from '@oxy.so/contracts/client';
+/** How long a refusal (disabled, rate limited, unreachable) is remembered per installation. */
+const EVIDENCE_REFUSAL_MS = 5000;
+const unavailable = (reason) => ({
+    status: 'unavailable',
+    reason,
+});
 export class SessionApi {
     constructor(ctx) {
         this.ctx = ctx;
         this.deviceCredentialProvider = null;
         this.decodedFor = null;
         this.decoded = null;
+        /** One server round trip per installed bearer; the key is the opaque generation. */
+        this.evidence = new WeakMap();
     }
     // ── Local state ──────────────────────────────────────────────────────────
     /** The current access token, or `null` when signed out. */
@@ -118,6 +127,115 @@ export class SessionApi {
             return null;
         }
     }
+    // ── Holder-context evidence (ADR 0053) ───────────────────────────────────
+    /**
+     * Ask the server which shared-device context the INSTALLED bearer belongs to,
+     * and bind the answer to that exact installation.
+     *
+     * The result is honored only if the credential generation captured before
+     * the request is still current when the answer is committed, so a refresh,
+     * setter, account or actor switch, cross-tab change, restore or A to B to A
+     * during the request yields `changed`. The answer must also agree with the
+     * claims of the bearer that was captured; a disagreement is
+     * `binding_unavailable`. Nothing here refreshes, clears or mints a credential,
+     * and no outcome is a revocation verdict: callers keep their existing checks.
+     * Concurrent callers share one request per installation.
+     */
+    observeHolderEvidence() {
+        const generation = this.ctx.http.captureCredentialGeneration();
+        const token = this.ctx.http.getAccessToken();
+        if (!generation || !token)
+            return Promise.resolve(unavailable('no_credential'));
+        const known = this.evidence.get(generation);
+        if (known) {
+            const refused = known.settledAt !== undefined;
+            if (!refused || Date.now() - known.settledAt < EVIDENCE_REFUSAL_MS) {
+                return known.result.then((result) => result.status === 'ok' && result.evidence.expiresAtMs <= Date.now()
+                    ? this.refreshEvidence(generation, token)
+                    : result);
+            }
+        }
+        return this.refreshEvidence(generation, token);
+    }
+    /** Whether evidence still names the installed bearer and has not expired. */
+    isHolderEvidenceCurrent(evidence) {
+        return (Date.now() < evidence.expiresAtMs &&
+            this.ctx.http.isCredentialGenerationCurrent(evidence.generation));
+    }
+    refreshEvidence(generation, token) {
+        const entry = {
+            result: this.acquireEvidence(generation, token).then((result) => {
+                if (result.status !== 'ok')
+                    entry.settledAt = Date.now();
+                return result;
+            }),
+        };
+        this.evidence.set(generation, entry);
+        return entry.result;
+    }
+    async acquireEvidence(generation, token) {
+        let claims;
+        try {
+            claims = jwtDecode(token);
+        }
+        catch {
+            return unavailable('unsupported');
+        }
+        const proof = await this.readDeviceProof();
+        if (!proof)
+            return unavailable('no_holder');
+        let response;
+        try {
+            response = await this.ctx.request('POST', '/session/device/context-evidence-v1', proof, {
+                cache: false,
+                retry: false,
+                expectedCredentialGeneration: generation,
+            });
+        }
+        catch (error) {
+            if (error?.code === 'AUTH_SESSION_CHANGED') {
+                return unavailable('changed');
+            }
+            const status = error instanceof OxyApiError ? error.status : 0;
+            if (status === 403)
+                return unavailable('unsupported');
+            if (status === 409)
+                return unavailable('binding_unavailable');
+            return unavailable('unavailable');
+        }
+        const parsed = checkContract(holderContextEvidenceV1ResponseCheck, response);
+        if (!parsed)
+            return unavailable('unavailable');
+        // Commit synchronously: nothing may replace the bearer between this check
+        // and the evidence becoming visible to its caller.
+        if (!this.ctx.http.isCredentialGenerationCurrent(generation))
+            return unavailable('changed');
+        const expiresAtMs = Date.parse(parsed.expiresAt);
+        if (parsed.deviceId !== proof.deviceId ||
+            parsed.accountId !== claims.userId ||
+            parsed.sessionId !== claims.sessionId ||
+            (claims.act?.sub !== undefined && parsed.actorId !== claims.act.sub) ||
+            (claims.device_context_id !== undefined && parsed.contextId !== claims.device_context_id)) {
+            return unavailable('binding_unavailable');
+        }
+        if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+            return unavailable('unavailable');
+        }
+        const evidence = Object.freeze({
+            generation,
+            identity: Object.freeze({
+                deviceId: parsed.deviceId,
+                deviceSessionId: parsed.deviceSessionId,
+                contextId: parsed.contextId,
+                actorId: parsed.actorId,
+                accountId: parsed.accountId,
+                sessionId: parsed.sessionId,
+            }),
+            deviceRevision: parsed.revision,
+            expiresAtMs,
+        });
+        return { status: 'ok', evidence };
+    }
     // ── The server session ───────────────────────────────────────────────────
     /** Ask the server whether the current access token is valid. */
     async validateToken() {

package/dist/esm/aws/index.js

@@ -6,8 +6,21 @@ import { defaultProvider } from '@aws-sdk/credential-provider-node';
  * Long-lived IAM user access keys are deliberately not a local service identity.
  */
 export function createAwsWorkloadCredentialProvider(options = {}) {
-    const provider = defaultProvider(options);
+    // An explicitly selected profile is an authority boundary. defaultProvider
+    // falls through a missing profile to ambient ECS/IMDS credentials, which may
+    // name another application. fromIni resolves only the selected profile and
+    // its declared source chain, or rejects; there is no ambient fallback.
+    if (options.profile !== undefined && !options.profile.trim())
+        throw new Error('An explicit AWS workload profile must not be empty');
+    const ambient = options.profile === undefined ? defaultProvider(options) : undefined;
+    const resolveProfile = async () => (await import('@aws-sdk/credential-provider-ini')).fromIni(options);
+    let selectedProfile;
     return async () => {
+        let provider = ambient;
+        if (!provider) {
+            selectedProfile ?? (selectedProfile = resolveProfile());
+            provider = await selectedProfile;
+        }
         const credentials = await provider();
         if (!credentials.sessionToken ||
             !credentials.expiration ||

package/dist/esm/index.js

@@ -30,6 +30,7 @@ import './crypto/polyfill.js';
 // ---------------------------------------------------------------------------
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices.js';
 export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors.js';
+export { sameHolderIdentity } from './api/holderEvidence.js';
 export { ASSET_MULTIPART_UPLOAD_MAX_BYTES, assetUrlCacheTTL, MAX_UPLOAD_BYTES } from './api/assets.js';
 export { DirectUploadInterruptedError } from './api/directUpload.js';
 export { buildUserDid } from './api/identity.js';

package/dist/types/HttpService.d.ts

@@ -22,6 +22,18 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+declare const credentialGenerationBrand: unique symbol;
+/**
+ * An opaque, immutable token for ONE installation of a bearer in a client.
+ *
+ * `TokenStore` swaps it on every write path (setter, refresh, account or actor
+ * switch, cross-tab or restored token, clear), so two installations of the same
+ * bytes (A, B, A) are different generations. It names a local sequence only: it
+ * is not evidence of an account, a scope or authorization.
+ */
+export type CredentialGeneration = {
+    readonly [credentialGenerationBrand]: true;
+};
 /** A trusted platform transport, for example Expo's streaming fetch. */
 export type ResponseTransport = (input: string, init: RequestInit) => Promise<Response>;
 /**
@@ -44,6 +56,13 @@ export interface ResponseRequest {
 /** Same response contract, but rejects locally when the SDK has no bearer. */
 export type AuthenticatedResponseRequest = ResponseRequest;
 export interface RequestOptions {
+    /**
+     * Bind a write to ONE installation of the source's bearer. The transport
+     * rejects (`AUTH_SESSION_CHANGED`) when the generation was replaced before
+     * dispatch, after queueing, or before the result is returned. Implies no cache,
+     * deduplication or retry, and a 401 neither refreshes nor clears the session.
+     */
+    expectedCredentialGeneration?: CredentialGeneration;
     cache?: boolean;
     cacheTTL?: number;
     deduplicate?: boolean;
@@ -228,6 +247,7 @@ export declare class HttpService {
      * bearer — and through the token listeners, the account — back.
      */
     private sessionEpoch;
+    private readonly credentialSource;
     /** Preserve a known device across legacy rotations which omit the claim. */
     private sessionDeviceId;
     /** Preserve known actor and context hints across rotations without those claims. */
@@ -258,7 +278,7 @@ export declare class HttpService {
      */
     private _tokenChangeListeners;
     private requestMetrics;
-    constructor(config: OxyConfig);
+    constructor(config: OxyConfig, credentialSource?: HttpService | null);
     private syncAccessTokenFromProvider;
     /**
      * Robust FormData detection that works in browser, React Native, and
@@ -521,6 +541,10 @@ export declare class HttpService {
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
     getSessionEpoch(): number;
+    /** Capture only the local generation; the caller must separately bind authority. */
+    captureCredentialGeneration(): CredentialGeneration | null;
+    isCredentialGenerationCurrent(generation: CredentialGeneration): boolean;
+    private assertCredentialGeneration;
     /** Whether {@link endSession} ran and no token has been planted since. */
     hasSessionEnded(): boolean;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;

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

@@ -0,0 +1,45 @@
+/**
+ * Holder-context evidence: the server's point-in-time observation of which
+ * shared-device context a bearer is installed in, bound to ONE installation of
+ * that bearer in this client (ADR 0053).
+ *
+ * Evidence is never authorization. It lets a caller that already captured a
+ * viewer intent prove, before a write is dispatched, that the bearer the write
+ * will carry belongs to that viewer's account and actor, and then pin the write
+ * to the exact installation with `expectedCredentialGeneration`. Anything that
+ * cannot be proven is `unavailable`, and the caller keeps its existing checks.
+ */
+import type { HolderContextEvidenceV1Response } from '@oxy.so/contracts';
+import type { CredentialGeneration } from '../HttpService';
+/** The identifiers the server observed; none of them is a credential. */
+export type HolderEvidenceIdentity = Readonly<Pick<HolderContextEvidenceV1Response, 'deviceId' | 'deviceSessionId' | 'contextId' | 'actorId' | 'accountId' | 'sessionId'>>;
+export interface HolderEvidence {
+    /** The installation of the bearer this evidence was observed for. */
+    readonly generation: CredentialGeneration;
+    readonly identity: HolderEvidenceIdentity;
+    /** The device-session revision the server observed. */
+    readonly deviceRevision: number;
+    /** Epoch milliseconds: the earlier of the bearer and session expiry. */
+    readonly expiresAtMs: number;
+}
+/**
+ * Why no evidence exists. Every reason means "keep the existing checks": none of
+ * them says the session is revoked, and none may clear or refresh credentials.
+ *
+ * - `no_credential`: no bearer is installed, or it comes from a pull-only provider.
+ * - `no_holder`: this client holds no device credential to prove the holder with.
+ * - `changed`: the bearer was replaced while the evidence was being acquired.
+ * - `unsupported`: a delegated, OAuth or legacy bearer, or the endpoint is not offered.
+ * - `binding_unavailable`: the server could not match holder, context and bearer.
+ * - `unavailable`: the endpoint is off, rate limited, unreachable or answered wrongly.
+ */
+export type HolderEvidenceUnavailableReason = 'no_credential' | 'no_holder' | 'changed' | 'unsupported' | 'binding_unavailable' | 'unavailable';
+export type HolderEvidenceResult = {
+    readonly status: 'ok';
+    readonly evidence: HolderEvidence;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: HolderEvidenceUnavailableReason;
+};
+/** The one comparison that decides whether two observations name the same viewer context. */
+export declare function sameHolderIdentity(a: HolderEvidenceIdentity, b: HolderEvidenceIdentity): boolean;

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

@@ -2,6 +2,7 @@ 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';
+import type { HolderEvidence, HolderEvidenceResult } from './holderEvidence';
 /**
  * Reads the device credential this client holds, if any — `{ deviceId,
  * deviceSecret }` from the provider's auth store. See
@@ -29,6 +30,8 @@ export declare class SessionApi {
     private deviceCredentialProvider;
     private decodedFor;
     private decoded;
+    /** One server round trip per installed bearer; the key is the opaque generation. */
+    private readonly evidence;
     constructor(ctx: OxyContext);
     /** The current access token, or `null` when signed out. */
     get accessToken(): string | null;
@@ -75,6 +78,24 @@ export declare class SessionApi {
      * that cannot be read only means the sign-in gets its own device.
      */
     readDeviceProof(): Promise<DeviceProof | null>;
+    /**
+     * Ask the server which shared-device context the INSTALLED bearer belongs to,
+     * and bind the answer to that exact installation.
+     *
+     * The result is honored only if the credential generation captured before
+     * the request is still current when the answer is committed, so a refresh,
+     * setter, account or actor switch, cross-tab change, restore or A to B to A
+     * during the request yields `changed`. The answer must also agree with the
+     * claims of the bearer that was captured; a disagreement is
+     * `binding_unavailable`. Nothing here refreshes, clears or mints a credential,
+     * and no outcome is a revocation verdict: callers keep their existing checks.
+     * Concurrent callers share one request per installation.
+     */
+    observeHolderEvidence(): Promise<HolderEvidenceResult>;
+    /** Whether evidence still names the installed bearer and has not expired. */
+    isHolderEvidenceCurrent(evidence: HolderEvidence): boolean;
+    private refreshEvidence;
+    private acquireEvidence;
     /** Ask the server whether the current access token is valid. */
     validateToken(): Promise<boolean>;
     /**

package/dist/types/index.d.ts

@@ -24,7 +24,9 @@ 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, ResponsePayload, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler, } from './HttpService';
+export type { RequestOptions, ResponsePayload, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler, CredentialGeneration, } from './HttpService';
+export { sameHolderIdentity } from './api/holderEvidence';
+export type { HolderEvidence, HolderEvidenceIdentity, HolderEvidenceResult, HolderEvidenceUnavailableReason, } from './api/holderEvidence';
 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/server/safety.d.ts

@@ -17,7 +17,7 @@ export declare class ServerSafetyApi extends SafetyApi {
     /** The original personal bearer, a verified MCP connection proof, or explicit anonymous access. */
     profileAccess(input: ProfileAccessInput, options?: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner";
         policyVersion: "1";
     }>;
     profileAccessBatch(input: ProfileAccessBatchInput, options: SafetyRequester): Promise<{
@@ -25,14 +25,14 @@ export declare class ServerSafetyApi extends SafetyApi {
             subjectAccountId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
     }>;
     messageAccess(input: MessageAccessInput, options: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     messageAccessBatch(input: MessageAccessBatchInput, options: SafetyRequester): Promise<{
@@ -40,7 +40,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -60,7 +60,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -70,7 +70,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             targetAccountId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -96,7 +96,7 @@ export declare class ServerSafetyApi extends SafetyApi {
     }>;
     contentAccess(input: ContentAccessInput, options: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     contentAccessBatch(input: ContentAccessBatchInput, options: SafetyRequester): Promise<{
@@ -104,14 +104,14 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
     }>;
     deliveryAccess(input: DeliveryAccessInput): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     requestPurchaseApproval(input: PurchaseEffects, options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.11.0",
+  "version": "7.12.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "6.3.0",
+    "@oxy.so/contracts": "6.4.0",
     "@oxy.so/protocol": "^1.5.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^1.6.0",
@@ -199,7 +199,8 @@
     "expo-crypto": "<59.0.0",
     "expo-secure-store": "<59.0.0",
     "express": "^4.0.0",
-    "@aws-sdk/credential-provider-node": ">=3.972.83 <4"
+    "@aws-sdk/credential-provider-node": ">=3.972.83 <4",
+    "@aws-sdk/credential-provider-ini": ">=3.973.16 <4"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {
@@ -216,6 +217,9 @@
     },
     "@aws-sdk/credential-provider-node": {
       "optional": true
+    },
+    "@aws-sdk/credential-provider-ini": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -232,6 +236,7 @@
     "typescript": "^5.9.2",
     "helmet": "^8.3.0",
     "socket.io": "^4.8.1",
-    "@aws-sdk/credential-provider-node": "3.972.83"
+    "@aws-sdk/credential-provider-node": "3.972.83",
+    "@aws-sdk/credential-provider-ini": "3.973.16"
   }
 }