@oxy.so/core 7.11.1 → 7.13.0

package/dist/esm/api/follows.js

@@ -1,4 +1,5 @@
 import { buildPaginationParams, buildQueryParams, buildUrl, } from '../utils/apiUtils.js';
+const enc = encodeURIComponent;
 const GRAPH_TTL = 2 * 60 * 1000;
 const STATUS_TTL = 60 * 1000;
 /**
@@ -13,7 +14,7 @@ export 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;
     }
@@ -27,7 +28,7 @@ export 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;
     }
@@ -41,7 +42,7 @@ export 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,
         });
@@ -71,12 +72,12 @@ export 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 };
     }
     /**
@@ -84,7 +85,7 @@ export 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 };
     }
     /**
@@ -219,16 +220,16 @@ export 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/esm/api/holderEvidence.js

@@ -0,0 +1,9 @@
+/** The one comparison that decides whether two observations name the same viewer context. */
+export 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/esm/api/privacy.js

@@ -1,4 +1,5 @@
 import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
+const enc = encodeURIComponent;
 const LIST_TTL = 60 * 1000;
 const SETTINGS_TTL = 2 * 60 * 1000;
 const refId = (ref) => (typeof ref === 'string' ? ref : ref._id);
@@ -10,7 +11,7 @@ export 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,
         });
@@ -18,10 +19,10 @@ export 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.
         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 ──────────────────────────────────────────────────────────────
@@ -35,14 +36,14 @@ export 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;
     }
@@ -68,14 +69,14 @@ export 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/esm/api/session.js

@@ -8,12 +8,22 @@
 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';
+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,
+});
 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 +128,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() {
@@ -172,7 +291,7 @@ export class SessionApi {
                             : {}),
                     },
                 })
-                : await this.ctx.request('GET', `/session/validate/${sessionId}`, {
+                : await this.ctx.request('GET', `/session/validate/${enc(sessionId)}`, {
                     ...(options.deviceFingerprint
                         ? { deviceFingerprint: options.deviceFingerprint }
                         : {}),
@@ -199,7 +318,7 @@ export 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 OxyApiError('Live session authority is unavailable', {
@@ -209,26 +328,28 @@ export 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/esm/api/topics.js

@@ -1,3 +1,4 @@
+const enc = encodeURIComponent;
 const SHORT = 60 * 1000;
 const LONG = 5 * 60 * 1000;
 const EXTRA_LONG = 30 * 60 * 1000;
@@ -41,7 +42,7 @@ export 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,
         });
@@ -60,10 +61,10 @@ export 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;
     }
 }

package/dist/esm/api/users.js

@@ -6,6 +6,7 @@ import { OXY_ACCOUNT_LIST_CACHE_KEY, OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX, oxyAcc
 import { extractErrorStatus } from '../utils/errorUtils.js';
 import { runBatchLookup } from '../utils/batchLookup.js';
 import { logger } from '../logger/index.js';
+const enc = encodeURIComponent;
 const PROFILE_TTL = 5 * 60 * 1000;
 const SESSION_USER_TTL = 2 * 60 * 1000;
 const ME_TTL = 60 * 1000;
@@ -25,7 +26,7 @@ export class UsersApi {
      * registry-fresh read that neither serves nor overwrites a cached entry.
      */
     async get(userId, options) {
-        const user = await this.ctx.request('GET', `/users/${userId}`, undefined, {
+        const user = await this.ctx.request('GET', `/users/${enc(userId)}`, undefined, {
             cache: options?.cache ?? true,
             cacheTTL: PROFILE_TTL,
         });
@@ -107,7 +108,7 @@ export class UsersApi {
     }
     /** The user a session belongs to. */
     async bySession(sessionId) {
-        const user = await this.ctx.request('GET', `/session/user/${sessionId}`, undefined, {
+        const user = await this.ctx.request('GET', `/session/user/${enc(sessionId)}`, undefined, {
             cache: true,
             cacheTTL: SESSION_USER_TTL,
         });
@@ -183,7 +184,7 @@ export class UsersApi {
         const pagination = typeof limitOrPagination === 'number'
             ? { limit: limitOrPagination }
             : (limitOrPagination ?? {});
-        const users = await this.ctx.request('GET', `/profiles/${userId}/similar`, buildQueryParams(pagination), {
+        const users = await this.ctx.request('GET', `/profiles/${enc(userId)}/similar`, buildQueryParams(pagination), {
             cache: true,
             cacheTTL: PROFILE_TTL,
         });
@@ -195,7 +196,7 @@ export class UsersApi {
      * account. Cached 5 minutes.
      */
     async moderators(communityId) {
-        const moderators = await this.ctx.request('GET', `/users/${communityId}/moderators`, undefined, { cache: true, cacheTTL: PROFILE_TTL });
+        const moderators = await this.ctx.request('GET', `/users/${enc(communityId)}/moderators`, undefined, { cache: true, cacheTTL: PROFILE_TTL });
         return moderators.map((user) => normalizeUserIdentity(user));
     }
     /**