@oxy.so/core 7.11.1 → 7.13.0

package/dist/cjs/HttpService.js

@@ -39,6 +39,9 @@ const REQUESTER_PROOF_HEADERS = new Set([
     'x-oxy-presented-requester-context',
     'x-oxy-presented-service-token',
 ]);
+function newCredentialGeneration() {
+    return Object.freeze({});
+}
 /** Comparison only fences local async work; it never validates token authority. */
 function sameTokenSession(left, right) {
     if (left === right)
@@ -249,14 +252,25 @@ const CACHE_SIZE_WARNING_THROTTLE_MS = 60000;
 class TokenStore {
     constructor() {
         this.accessToken = null;
+        this.generation = newCredentialGeneration();
     }
     setTokens(accessToken) {
+        this.generation = newCredentialGeneration();
         this.accessToken = accessToken;
     }
+    /** The identity of the bearer's current installation, never of its bytes. */
+    getGeneration() {
+        return this.generation;
+    }
+    /** Retire the current generation without touching the bearer (provider swaps). */
+    invalidateGeneration() {
+        this.generation = newCredentialGeneration();
+    }
     getAccessToken() {
         return this.accessToken;
     }
     clearTokens() {
+        this.generation = newCredentialGeneration();
         this.accessToken = null;
     }
     hasAccessToken() {
@@ -307,7 +321,7 @@ function linkAbort(parent, child) {
  * Uses native fetch instead of axios for smaller bundle size.
  */
 class HttpService {
-    constructor(config) {
+    constructor(config, credentialSource = null) {
         // Only active calls retain a lease. Invalidation detaches matching leases,
         // so late results cannot warm the cache or attract new deduplicated callers.
         this.readLeases = new Map();
@@ -404,6 +418,7 @@ class HttpService {
             averageResponseTime: 0,
         };
         this.config = config;
+        this.credentialSource = credentialSource;
         this.baseURL = config.baseURL;
         this.tokenStore = new TokenStore();
         this.logger = new requestUtils_1.SimpleLogger(config.enableLogging || false, config.logLevel || 'error', 'HttpService');
@@ -520,6 +535,17 @@ class HttpService {
     async request(config) {
         if (config.signal?.aborted)
             throw (0, errorUtils_1.createCancelledError)('Request cancelled before it was sent');
+        if (config.expectedCredentialGeneration) {
+            // The prototype is deliberately limited to writes; it does not
+            // yet define leases for cached/deduplicated reads or raw response paths.
+            if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(config.method) ||
+                config.skipAuth ||
+                Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization')) {
+                throw new Error('A credential generation requires an implicitly authenticated write');
+            }
+            (this.credentialSource ?? this).assertCredentialGeneration(config.expectedCredentialGeneration);
+            config = { ...config, cache: false, deduplicate: false, retry: false };
+        }
         // The provider can change independently of the last request. Synchronize
         // before deriving the cache and deduplication identity, including hits.
         const explicitAuthorization = Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization');
@@ -609,6 +635,12 @@ class HttpService {
         const authHeader = usesSessionAuth
             ? await (0, requestSignal_1.awaitRequestSignal)(this.getAuthHeader(), signal)
             : null;
+        const assertExpectedCredential = () => {
+            if (config.expectedCredentialGeneration) {
+                (this.credentialSource ?? this).assertCredentialGeneration(config.expectedCredentialGeneration, authHeader);
+            }
+        };
+        assertExpectedCredential();
         const isOriginalSession = () => {
             if (this.sessionEpoch !== contextEpoch)
                 return false;
@@ -658,6 +690,7 @@ class HttpService {
             if (usesSessionAuth && !isOriginalSession()) {
                 throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
             }
+            assertExpectedCredential();
             /**
              * Whether OUR timer fired, so a timeout can be told apart from a
              * cancellation. Both reach us from `fetch` as an indistinguishable
@@ -754,6 +787,9 @@ class HttpService {
                     Object.keys(headers).some((key) => REQUESTER_PROOF_HEADERS.has(key.toLowerCase()))) {
                     throw new Error('Requester proofs require a transport that rejects redirects');
                 }
+                // Header and source generation are checked together in this synchronous
+                // dispatch segment, after the preflight and any queue wait.
+                assertExpectedCredential();
                 const response = useXhrForUpload
                     ? await this.uploadViaXHR(fullUrl, method, headers, bodyValue, controller.signal, timeout, false)
                     : await fetch(fullUrl, {
@@ -768,6 +804,13 @@ class HttpService {
                 // it, including on every throw between here and there.
                 if (timeoutId)
                     clearTimeout(timeoutId);
+                try {
+                    assertExpectedCredential();
+                }
+                catch (error) {
+                    void discardResponseBody(response);
+                    throw error;
+                }
                 if (usesSessionAuth && !isOriginalSession()) {
                     void discardResponseBody(response);
                     throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
@@ -778,6 +821,7 @@ class HttpService {
                     // once before giving up. HttpService deliberately does not know any
                     // session routes; the refresh handler owns session rotation.
                     if (response.status === 401 &&
+                        !config.expectedCredentialGeneration &&
                         !config._isAuthRetry &&
                         usesSessionAuth &&
                         isOriginalSession()) {
@@ -913,12 +957,14 @@ class HttpService {
                 if (usesSessionAuth && !isOriginalSession()) {
                     throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
                 }
+                assertExpectedCredential();
                 const duration = Date.now() - startTime;
                 this.updateMetrics(true, duration);
                 this.config.onRequestEnd?.(url, method, duration, true);
                 return responseData;
             }
             catch (error) {
+                assertExpectedCredential();
                 const duration = Date.now() - startTime;
                 this.updateMetrics(false, duration);
                 // A body reader can reject or finish parsing an error after the viewer
@@ -1030,6 +1076,7 @@ class HttpService {
         if (usesSessionAuth && !isOriginalSession()) {
             throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
         }
+        assertExpectedCredential();
         // Cache the result if caching is enabled
         if (cache && cacheKey && lease.valid && result) {
             this.cache.set(cacheKey, result, cacheTTL);
@@ -1755,6 +1802,27 @@ class HttpService {
     getSessionEpoch() {
         return this.sessionEpoch;
     }
+    /** Capture only the local generation; the caller must separately bind authority. */
+    captureCredentialGeneration() {
+        // A pull-only provider can change A→B→A between reads without notifying us.
+        if (this.accessTokenProvider)
+            return null;
+        return this.tokenStore.getAccessToken() ? this.tokenStore.getGeneration() : null;
+    }
+    isCredentialGenerationCurrent(generation) {
+        return (!this.accessTokenProvider &&
+            this.tokenStore.getAccessToken() !== null &&
+            generation === this.tokenStore.getGeneration());
+    }
+    assertCredentialGeneration(generation, selectedHeader) {
+        const token = this.tokenStore.getAccessToken();
+        if (this.accessTokenProvider ||
+            !token ||
+            generation !== this.tokenStore.getGeneration() ||
+            (selectedHeader !== undefined && selectedHeader !== `Bearer ${token}`)) {
+            throw new OxyServices_errors_1.OxyAuthenticationError('The request credential changed', 'AUTH_SESSION_CHANGED');
+        }
+    }
     /** Whether {@link endSession} ran and no token has been planted since. */
     hasSessionEnded() {
         return this.sessionEnded;
@@ -1763,6 +1831,7 @@ class HttpService {
         this.authRefreshHandler = handler;
     }
     setAccessTokenProvider(provider) {
+        this.tokenStore.invalidateGeneration();
         this.accessTokenProvider = provider;
     }
     /**

package/dist/cjs/OxyServices.js

@@ -117,7 +117,7 @@ class OxyServices {
      * Query). Pass `enableCache: true` to opt in.
      */
     createLinkedClient(config) {
-        const client = new HttpService_1.HttpService({ ...config, enableCache: config.enableCache ?? false });
+        const client = new HttpService_1.HttpService({ ...config, enableCache: config.enableCache ?? false }, this.http);
         const syncToken = (accessToken) => {
             const current = client.getAccessToken();
             if (accessToken) {

package/dist/cjs/api/apps.js

@@ -85,7 +85,7 @@ class ConnectedAppsApi {
      *   `ConnectedApp.applicationId`, NOT a credential/client id).
      */
     async revoke(applicationId) {
-        await this.ctx.request('DELETE', `/auth/grants/${applicationId}`, undefined, { cache: false });
+        await this.ctx.request('DELETE', `/auth/grants/${enc(applicationId)}`, undefined, { cache: false });
         this.ctx.oxy.cache.delete('GET:/auth/grants');
     }
     /** Resource-bound external MCP connections for the active Oxy account. */

package/dist/cjs/api/auth.js

@@ -974,7 +974,7 @@ class AuthApi {
      */
     async checkUsername(username) {
         // Public availability lookup (pre-session) — skip the bearer preflight.
-        return this.ctx.request('GET', `/auth/check-username/${username}`, undefined, {
+        return this.ctx.request('GET', `/auth/check-username/${encodeURIComponent(username)}`, undefined, {
             cache: false,
             skipAuth: true,
         });

package/dist/cjs/api/billing.js

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BillingApi = void 0;
 const client_1 = require("@oxy.so/contracts/client");
+const enc = encodeURIComponent;
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
 const WALLET_TTL = 60 * 1000;
 class BillingApi {
@@ -76,7 +77,7 @@ class BillingApi {
     /** A user's subscription (default: the signed-in user's). */
     async subscription(userId) {
         const id = this.resolveUserId(userId);
-        return this.ctx.request('GET', `/subscription/${id}`, undefined, {
+        return this.ctx.request('GET', `/subscription/${enc(id)}`, undefined, {
             cache: true,
             cacheTTL: SUBSCRIPTION_TTL,
         });
@@ -84,7 +85,7 @@ class BillingApi {
     /** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
     async wallet(userId) {
         const id = this.resolveUserId(userId);
-        return this.ctx.request('GET', `/wallet/${id}`, undefined, {
+        return this.ctx.request('GET', `/wallet/${enc(id)}`, undefined, {
             cache: true,
             cacheTTL: WALLET_TTL,
         });
@@ -97,7 +98,7 @@ class BillingApi {
             params.limit = options.limit;
         if (options.offset)
             params.offset = options.offset;
-        return this.ctx.request('GET', `/wallet/transactions/${id}`, params, {
+        return this.ctx.request('GET', `/wallet/transactions/${enc(id)}`, params, {
             cache: false,
         });
     }

package/dist/cjs/api/devices.js

@@ -4,6 +4,7 @@ exports.DevicesApi = exports.AccountNotOnDeviceError = void 0;
 const client_1 = require("@oxy.so/contracts/client");
 const logger_1 = require("../logger");
 const errorUtils_1 = require("../utils/errorUtils");
+const enc = encodeURIComponent;
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
  * `accountId` is not (or is no longer) a live account of this device session.
@@ -75,7 +76,7 @@ class DevicesApi {
      * @param deviceId - The device ID to remove
      */
     async remove(deviceId) {
-        await this.ctx.request('DELETE', `/devices/${deviceId}`, undefined, { cache: false });
+        await this.ctx.request('DELETE', `/devices/${enc(deviceId)}`, undefined, { cache: false });
     }
     /**
      * Get device sessions for a given session ID
@@ -85,7 +86,7 @@ class DevicesApi {
      */
     async sessions(sessionId) {
         // Cache disabled by default to ensure fresh session data
-        return this.ctx.request('GET', `/session/device/sessions/${sessionId}`, undefined, {
+        return this.ctx.request('GET', `/session/device/sessions/${enc(sessionId)}`, undefined, {
             cache: false, // Don't cache sessions - always get fresh data
             deduplicate: true, // Deduplicate concurrent requests for same sessionId
         });
@@ -103,7 +104,7 @@ class DevicesApi {
             urlParams.deviceId = deviceId;
         if (excludeCurrent)
             urlParams.excludeCurrent = 'true';
-        return this.ctx.request('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+        return this.ctx.request('POST', `/session/device/logout-all/${enc(sessionId)}`, urlParams, { cache: false });
     }
     /**
      * Update device name
@@ -112,7 +113,7 @@ class DevicesApi {
      * @returns Updated device object
      */
     async rename(sessionId, deviceName) {
-        return this.ctx.request('PUT', `/session/device/name/${sessionId}`, { deviceName }, { cache: false });
+        return this.ctx.request('PUT', `/session/device/name/${enc(sessionId)}`, { deviceName }, { cache: false });
     }
     /**
      * Get security information

package/dist/cjs/api/follows.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FollowsApi = void 0;
 const apiUtils_1 = require("../utils/apiUtils");
+const enc = encodeURIComponent;
 const GRAPH_TTL = 2 * 60 * 1000;
 const STATUS_TTL = 60 * 1000;
 /**
@@ -16,7 +17,7 @@ class FollowsApi {
     // ── People ───────────────────────────────────────────────────────────────
     /** Follow a user. */
     async follow(userId) {
-        const result = await this.ctx.request('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.ctx.request('POST', `/users/${enc(userId)}/follow`, undefined, { cache: false });
         this.invalidate([userId]);
         return result;
     }
@@ -30,7 +31,7 @@ class FollowsApi {
     }
     /** Unfollow a user. */
     async unfollow(userId) {
-        const result = await this.ctx.request('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.ctx.request('DELETE', `/users/${enc(userId)}/follow`, undefined, { cache: false });
         this.invalidate([userId]);
         return result;
     }
@@ -44,7 +45,7 @@ class FollowsApi {
     }
     /** Whether the signed-in user follows `userId`. Cached 1 minute, busted by every write. */
     async status(userId) {
-        return this.ctx.request('GET', `/users/${userId}/follow-status`, undefined, {
+        return this.ctx.request('GET', `/users/${enc(userId)}/follow-status`, undefined, {
             cache: true,
             cacheTTL: STATUS_TTL,
         });
@@ -74,12 +75,12 @@ class FollowsApi {
      * `limit`/`offset`/`sort` combination is its own cache entry (2 minutes).
      */
     async followers(userId, params) {
-        const { data, total, hasMore } = await this.userPage(`/users/${userId}/followers`, params);
+        const { data, total, hasMore } = await this.userPage(`/users/${enc(userId)}/followers`, params);
         return { followers: data, total, hasMore };
     }
     /** Who a user follows. `sort` as in `followers`. */
     async following(userId, params) {
-        const { data, total, hasMore } = await this.userPage(`/users/${userId}/following`, params);
+        const { data, total, hasMore } = await this.userPage(`/users/${enc(userId)}/following`, params);
         return { following: data, total, hasMore };
     }
     /**
@@ -87,7 +88,7 @@ class FollowsApi {
      * `userId`.
      */
     async mutuals(userId, params) {
-        const { data, total, hasMore } = await this.userPage(`/users/${userId}/mutuals`, params);
+        const { data, total, hasMore } = await this.userPage(`/users/${enc(userId)}/mutuals`, params);
         return { mutuals: data, total, hasMore };
     }
     /**
@@ -222,16 +223,16 @@ class FollowsApi {
         const keys = ['GET:/users/me/graph'];
         const prefixes = ['GET:/profiles/username/', 'GET:/profiles/resolve'];
         for (const id of targetUserIds) {
-            keys.push(`GET:/users/${id}/follow-status`);
+            keys.push(`GET:/users/${enc(id)}/follow-status`);
             // Profiles embed the viewer-relative `relationship`.
-            keys.push(`GET:/users/${id}`);
+            keys.push(`GET:/users/${enc(id)}`);
             // The target gained or lost a follower, and "followers you know" with it.
-            prefixes.push(`GET:/users/${id}/followers`, `GET:/users/${id}/mutuals`);
+            prefixes.push(`GET:/users/${enc(id)}/followers`, `GET:/users/${enc(id)}/mutuals`);
         }
         // The viewer's own following list changed.
         const viewerId = this.ctx.oxy.session.userId;
         if (viewerId)
-            prefixes.push(`GET:/users/${viewerId}/following`);
+            prefixes.push(`GET:/users/${enc(viewerId)}/following`);
         this.ctx.http.invalidateCache({ keys, prefixes });
     }
 }

package/dist/cjs/api/holderEvidence.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameHolderIdentity = sameHolderIdentity;
+/** The one comparison that decides whether two observations name the same viewer context. */
+function sameHolderIdentity(a, b) {
+    return (a.deviceId === b.deviceId &&
+        a.deviceSessionId === b.deviceSessionId &&
+        a.contextId === b.contextId &&
+        a.actorId === b.actorId &&
+        a.accountId === b.accountId &&
+        a.sessionId === b.sessionId);
+}

package/dist/cjs/api/privacy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrivacyApi = void 0;
 const identityCacheSweep_1 = require("../utils/identityCacheSweep");
+const enc = encodeURIComponent;
 const LIST_TTL = 60 * 1000;
 const SETTINGS_TTL = 2 * 60 * 1000;
 const refId = (ref) => (typeof ref === 'string' ? ref : ref._id);
@@ -13,7 +14,7 @@ class PrivacyApi {
     /** A user's privacy settings (default: the signed-in user's). */
     async settings(userId) {
         const id = await this.resolveUserId(userId);
-        return this.ctx.request('GET', `/privacy/${id}/privacy`, undefined, {
+        return this.ctx.request('GET', `/privacy/${enc(id)}/privacy`, undefined, {
             cache: true,
             cacheTTL: SETTINGS_TTL,
         });
@@ -21,10 +22,10 @@ class PrivacyApi {
     /** Update privacy settings (default: the signed-in user's). */
     async updateSettings(settings, userId) {
         const id = await this.resolveUserId(userId);
-        const res = await this.ctx.request('PATCH', `/privacy/${id}/privacy`, settings, { cache: false });
+        const res = await this.ctx.request('PATCH', `/privacy/${enc(id)}/privacy`, settings, { cache: false });
         // Privacy settings ride the user DTO, so every identity read goes stale too.
         (0, identityCacheSweep_1.evictOxyIdentityCache)(this.ctx.http, id);
-        this.ctx.oxy.cache.delete(`GET:/privacy/${id}/privacy`);
+        this.ctx.oxy.cache.delete(`GET:/privacy/${enc(id)}/privacy`);
         return res;
     }
     // ── Blocked ──────────────────────────────────────────────────────────────
@@ -38,14 +39,14 @@ class PrivacyApi {
     /** Block a user. */
     async block(userId) {
         requireId(userId);
-        const res = await this.ctx.request('POST', `/privacy/blocked/${userId}`, undefined, { cache: false });
+        const res = await this.ctx.request('POST', `/privacy/blocked/${enc(userId)}`, undefined, { cache: false });
         this.invalidate('GET:/privacy/blocked');
         return res;
     }
     /** Unblock a user. */
     async unblock(userId) {
         requireId(userId);
-        const res = await this.ctx.request('DELETE', `/privacy/blocked/${userId}`, undefined, { cache: false });
+        const res = await this.ctx.request('DELETE', `/privacy/blocked/${enc(userId)}`, undefined, { cache: false });
         this.invalidate('GET:/privacy/blocked');
         return res;
     }
@@ -71,14 +72,14 @@ class PrivacyApi {
     /** Restrict a user: limit their interactions without blocking them. */
     async restrict(userId) {
         requireId(userId);
-        const res = await this.ctx.request('POST', `/privacy/restricted/${userId}`, undefined, { cache: false });
+        const res = await this.ctx.request('POST', `/privacy/restricted/${enc(userId)}`, undefined, { cache: false });
         this.invalidate('GET:/privacy/restricted');
         return res;
     }
     /** Lift a restriction. */
     async unrestrict(userId) {
         requireId(userId);
-        const res = await this.ctx.request('DELETE', `/privacy/restricted/${userId}`, undefined, { cache: false });
+        const res = await this.ctx.request('DELETE', `/privacy/restricted/${enc(userId)}`, undefined, { cache: false });
         this.invalidate('GET:/privacy/restricted');
         return res;
     }

package/dist/cjs/api/session.js

@@ -11,12 +11,22 @@ exports.SessionApi = void 0;
 const jwt_decode_1 = require("jwt-decode");
 const userIdentity_1 = require("../utils/userIdentity");
 const OxyServices_errors_1 = require("../OxyServices.errors");
+const client_1 = require("@oxy.so/contracts/client");
+const enc = encodeURIComponent;
+/** How long a refusal (disabled, rate limited, unreachable) is remembered per installation. */
+const EVIDENCE_REFUSAL_MS = 5000;
+const unavailable = (reason) => ({
+    status: 'unavailable',
+    reason,
+});
 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. */
@@ -121,6 +131,115 @@ 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 = (0, jwt_decode_1.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 OxyServices_errors_1.OxyApiError ? error.status : 0;
+            if (status === 403)
+                return unavailable('unsupported');
+            if (status === 409)
+                return unavailable('binding_unavailable');
+            return unavailable('unavailable');
+        }
+        const parsed = (0, client_1.checkContract)(client_1.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() {
@@ -175,7 +294,7 @@ class SessionApi {
                             : {}),
                     },
                 })
-                : await this.ctx.request('GET', `/session/validate/${sessionId}`, {
+                : await this.ctx.request('GET', `/session/validate/${enc(sessionId)}`, {
                     ...(options.deviceFingerprint
                         ? { deviceFingerprint: options.deviceFingerprint }
                         : {}),
@@ -202,7 +321,7 @@ class SessionApi {
                 const invalid = candidate?.status === 401 && candidate.code === 'OXY_LIVE_SESSION_INVALID_V1';
                 const denied = candidate?.status === 403 && candidate.code === 'OXY_LIVE_SESSION_POLICY_V1';
                 if (invalid)
-                    this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+                    this.ctx.oxy.cache.delete(`GET:/session/user/${enc(sessionId)}`);
                 if (invalid || denied)
                     throw error;
                 throw new OxyServices_errors_1.OxyApiError('Live session authority is unavailable', {
@@ -212,26 +331,28 @@ class SessionApi {
                 });
             }
             // The session is gone: drop any user cached for it (#196).
-            this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+            this.ctx.oxy.cache.delete(`GET:/session/user/${enc(sessionId)}`);
             throw error;
         }
     }
     /** The sessions that belong with `sessionId` (same account set). */
     async list(sessionId) {
-        return this.ctx.request('GET', `/session/sessions/${sessionId}`, undefined, {
+        return this.ctx.request('GET', `/session/sessions/${enc(sessionId)}`, undefined, {
             cache: false,
         });
     }
     /** Sign out `sessionId`, or — with `targetSessionId` — one of the sessions beside it. */
     async logout(sessionId, targetSessionId) {
         const url = targetSessionId
-            ? `/session/logout/${sessionId}/${targetSessionId}`
-            : `/session/logout/${sessionId}`;
+            ? `/session/logout/${enc(sessionId)}/${enc(targetSessionId)}`
+            : `/session/logout/${enc(sessionId)}`;
         await this.ctx.request('POST', url, undefined, { cache: false });
     }
     /** Sign out the other sessions for this account; preserve `sessionId`. */
     async logoutAll(sessionId) {
-        await this.ctx.request('POST', `/session/logout-all/${sessionId}`, undefined, { cache: false });
+        await this.ctx.request('POST', `/session/logout-all/${enc(sessionId)}`, undefined, {
+            cache: false,
+        });
     }
     /** Decoded claims of the current token, memoised per token string. */
     claims() {

package/dist/cjs/api/topics.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicsApi = void 0;
+const enc = encodeURIComponent;
 const SHORT = 60 * 1000;
 const LONG = 5 * 60 * 1000;
 const EXTRA_LONG = 30 * 60 * 1000;
@@ -44,7 +45,7 @@ class TopicsApi {
     }
     /** One topic by slug. */
     async get(slug) {
-        return this.ctx.request('GET', `/topics/${slug}`, undefined, {
+        return this.ctx.request('GET', `/topics/${enc(slug)}`, undefined, {
             cache: true,
             cacheTTL: LONG,
         });
@@ -63,10 +64,10 @@ class TopicsApi {
     }
     /** Update a topic's description and translations. Staff or service only. */
     async update(slug, data) {
-        const topic = await this.ctx.request('PATCH', `/topics/${slug}`, data, {
+        const topic = await this.ctx.request('PATCH', `/topics/${enc(slug)}`, data, {
             cache: false,
         });
-        this.ctx.oxy.cache.delete(`GET:/topics/${slug}`);
+        this.ctx.oxy.cache.delete(`GET:/topics/${enc(slug)}`);
         return topic;
     }
 }