@oxy.so/core 7.11.1 → 7.13.0

package/src/api/follows.ts

@@ -28,6 +28,8 @@ import {
   type FollowGraphParams,
 } from '../utils/apiUtils';
 
+const enc = encodeURIComponent;
+
 const GRAPH_TTL = 2 * 60 * 1000;
 const STATUS_TTL = 60 * 1000;
 
@@ -130,7 +132,7 @@ export class FollowsApi {
   async follow(userId: string): Promise<FollowMutationResult> {
     const result = await this.ctx.request<FollowMutationResult>(
       'POST',
-      `/users/${userId}/follow`,
+      `/users/${enc(userId)}/follow`,
       undefined,
       { cache: false },
     );
@@ -155,7 +157,7 @@ export class FollowsApi {
   async unfollow(userId: string): Promise<FollowMutationResult> {
     const result = await this.ctx.request<FollowMutationResult>(
       'DELETE',
-      `/users/${userId}/follow`,
+      `/users/${enc(userId)}/follow`,
       undefined,
       { cache: false },
     );
@@ -178,7 +180,7 @@ export class FollowsApi {
 
   /** Whether the signed-in user follows `userId`. Cached 1 minute, busted by every write. */
   async status(userId: string): Promise<{ isFollowing: boolean }> {
-    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,
     });
@@ -221,13 +223,13 @@ export class FollowsApi {
    * `limit`/`offset`/`sort` combination is its own cache entry (2 minutes).
    */
   async followers(userId: string, params?: FollowGraphParams): Promise<UserPage<'followers'>> {
-    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: string, params?: FollowGraphParams): Promise<UserPage<'following'>> {
-    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 };
   }
 
@@ -236,7 +238,7 @@ export class FollowsApi {
    * `userId`.
    */
   async mutuals(userId: string, params?: FollowGraphParams): Promise<UserPage<'mutuals'>> {
-    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 };
   }
 
@@ -443,15 +445,15 @@ export class FollowsApi {
     const keys: string[] = ['GET:/users/me/graph'];
     const prefixes: string[] = ['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`);
+    if (viewerId) prefixes.push(`GET:/users/${enc(viewerId)}/following`);
     this.ctx.http.invalidateCache({ keys, prefixes });
   }
 }

package/src/api/holderEvidence.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 function sameHolderIdentity(a: HolderEvidenceIdentity, b: HolderEvidenceIdentity): boolean {
+  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/src/api/privacy.ts

@@ -5,6 +5,8 @@ import type { BlockedUser, PrivacySettings, RestrictedUser } from '../models/int
 import type { OxyContext } from '../client/context';
 import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
 
+const enc = encodeURIComponent;
+
 const LIST_TTL = 60 * 1000;
 const SETTINGS_TTL = 2 * 60 * 1000;
 
@@ -20,7 +22,7 @@ export class PrivacyApi {
   /** A user's privacy settings (default: the signed-in user's). */
   async settings(userId?: string): Promise<PrivacySettings> {
     const id = await this.resolveUserId(userId);
-    return this.ctx.request<PrivacySettings>('GET', `/privacy/${id}/privacy`, undefined, {
+    return this.ctx.request<PrivacySettings>('GET', `/privacy/${enc(id)}/privacy`, undefined, {
       cache: true,
       cacheTTL: SETTINGS_TTL,
     });
@@ -34,13 +36,13 @@ export class PrivacyApi {
     const id = await this.resolveUserId(userId);
     const res = await this.ctx.request<PrivacySettings>(
       'PATCH',
-      `/privacy/${id}/privacy`,
+      `/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;
   }
 
@@ -59,7 +61,7 @@ export class PrivacyApi {
     requireId(userId);
     const res = await this.ctx.request<{ message: string }>(
       'POST',
-      `/privacy/blocked/${userId}`,
+      `/privacy/blocked/${enc(userId)}`,
       undefined,
       { cache: false },
     );
@@ -72,7 +74,7 @@ export class PrivacyApi {
     requireId(userId);
     const res = await this.ctx.request<{ message: string }>(
       'DELETE',
-      `/privacy/blocked/${userId}`,
+      `/privacy/blocked/${enc(userId)}`,
       undefined,
       { cache: false },
     );
@@ -105,7 +107,7 @@ export class PrivacyApi {
     requireId(userId);
     const res = await this.ctx.request<{ message: string }>(
       'POST',
-      `/privacy/restricted/${userId}`,
+      `/privacy/restricted/${enc(userId)}`,
       undefined,
       { cache: false },
     );
@@ -118,7 +120,7 @@ export class PrivacyApi {
     requireId(userId);
     const res = await this.ctx.request<{ message: string }>(
       'DELETE',
-      `/privacy/restricted/${userId}`,
+      `/privacy/restricted/${enc(userId)}`,
       undefined,
       { cache: false },
     );

package/src/api/session.ts

@@ -12,6 +12,22 @@ import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
 import { normalizeUserIdentity } from '../utils/userIdentity';
 import { OxyApiError } from '../OxyServices.errors';
+import { checkContract, holderContextEvidenceV1ResponseCheck } from '@oxy.so/contracts/client';
+import type { CredentialGeneration } from '../HttpService';
+import type {
+  HolderEvidence,
+  HolderEvidenceResult,
+  HolderEvidenceUnavailableReason,
+} from './holderEvidence';
+
+const enc = encodeURIComponent;
+
+/** How long a refusal (disabled, rate limited, unreachable) is remembered per installation. */
+const EVIDENCE_REFUSAL_MS = 5_000;
+const unavailable = (reason: HolderEvidenceUnavailableReason): HolderEvidenceResult => ({
+  status: 'unavailable',
+  reason,
+});
 
 /**
  * Reads the device credential this client holds, if any — `{ deviceId,
@@ -42,12 +58,21 @@ interface AccessTokenClaims {
   exp?: number;
   userId?: string;
   id?: string;
+  sessionId?: string;
+  deviceId?: string;
+  device_context_id?: string;
+  act?: { sub?: string };
 }
 
 export class SessionApi {
   private deviceCredentialProvider: DeviceCredentialProvider | null = null;
   private decodedFor: string | null = null;
   private decoded: AccessTokenClaims | null = null;
+  /** One server round trip per installed bearer; the key is the opaque generation. */
+  private readonly evidence = new WeakMap<
+    CredentialGeneration,
+    { result: Promise<HolderEvidenceResult>; settledAt?: number }
+  >();
 
   constructor(protected readonly ctx: OxyContext) {}
 
@@ -163,6 +188,128 @@ export class SessionApi {
     }
   }
 
+  // ── 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(): Promise<HolderEvidenceResult> {
+    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 as number) < 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: HolderEvidence): boolean {
+    return (
+      Date.now() < evidence.expiresAtMs &&
+      this.ctx.http.isCredentialGenerationCurrent(evidence.generation)
+    );
+  }
+
+  private refreshEvidence(
+    generation: CredentialGeneration,
+    token: string,
+  ): Promise<HolderEvidenceResult> {
+    const entry: { result: Promise<HolderEvidenceResult>; settledAt?: number } = {
+      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;
+  }
+
+  private async acquireEvidence(
+    generation: CredentialGeneration,
+    token: string,
+  ): Promise<HolderEvidenceResult> {
+    let claims: AccessTokenClaims;
+    try {
+      claims = jwtDecode<AccessTokenClaims>(token);
+    } catch {
+      return unavailable('unsupported');
+    }
+    const proof = await this.readDeviceProof();
+    if (!proof) return unavailable('no_holder');
+    let response: unknown;
+    try {
+      response = await this.ctx.request<unknown>(
+        'POST',
+        '/session/device/context-evidence-v1',
+        proof,
+        {
+          cache: false,
+          retry: false,
+          expectedCredentialGeneration: generation,
+        },
+      );
+    } catch (error) {
+      if ((error as { code?: unknown } | null)?.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: HolderEvidence = 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. */
@@ -231,7 +378,7 @@ export class SessionApi {
           )
         : await this.ctx.request<SessionValidation>(
             'GET',
-            `/session/validate/${sessionId}`,
+            `/session/validate/${enc(sessionId)}`,
             {
               ...(options.deviceFingerprint
                 ? { deviceFingerprint: options.deviceFingerprint }
@@ -262,7 +409,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}`);
+        if (invalid) this.ctx.oxy.cache.delete(`GET:/session/user/${enc(sessionId)}`);
         if (invalid || denied) throw error;
         throw new OxyApiError('Live session authority is unavailable', {
           status: 503,
@@ -271,29 +418,36 @@ 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: string): Promise<ClientSession[]> {
-    return this.ctx.request<ClientSession[]>('GET', `/session/sessions/${sessionId}`, undefined, {
-      cache: false,
-    });
+    return this.ctx.request<ClientSession[]>(
+      'GET',
+      `/session/sessions/${enc(sessionId)}`,
+      undefined,
+      {
+        cache: false,
+      },
+    );
   }
 
   /** Sign out `sessionId`, or — with `targetSessionId` — one of the sessions beside it. */
   async logout(sessionId: string, targetSessionId?: string): Promise<void> {
     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: string): Promise<void> {
-    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. */

package/src/api/topics.ts

@@ -4,6 +4,8 @@
 import type { OxyContext } from '../client/context';
 import type { TopicData, TopicListResult, TopicTranslation } from '../models/Topic';
 
+const enc = encodeURIComponent;
+
 const SHORT = 60 * 1000;
 const LONG = 5 * 60 * 1000;
 const EXTRA_LONG = 30 * 60 * 1000;
@@ -51,7 +53,7 @@ export class TopicsApi {
 
   /** One topic by slug. */
   async get(slug: string): Promise<TopicData> {
-    return this.ctx.request<TopicData>('GET', `/topics/${slug}`, undefined, {
+    return this.ctx.request<TopicData>('GET', `/topics/${enc(slug)}`, undefined, {
       cache: true,
       cacheTTL: LONG,
     });
@@ -86,10 +88,10 @@ export class TopicsApi {
     slug: string,
     data: { description?: string; translations?: Record<string, TopicTranslation> },
   ): Promise<TopicData> {
-    const topic = await this.ctx.request<TopicData>('PATCH', `/topics/${slug}`, data, {
+    const topic = await this.ctx.request<TopicData>('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/src/api/users.ts

@@ -22,6 +22,8 @@ import { extractErrorStatus } from '../utils/errorUtils';
 import { type BatchLookup, runBatchLookup } from '../utils/batchLookup';
 import { logger } from '../logger';
 
+const enc = encodeURIComponent;
+
 const PROFILE_TTL = 5 * 60 * 1000;
 const SESSION_USER_TTL = 2 * 60 * 1000;
 const ME_TTL = 60 * 1000;
@@ -65,7 +67,7 @@ export class UsersApi {
    * registry-fresh read that neither serves nor overwrites a cached entry.
    */
   async get(userId: string, options?: { cache?: boolean }): Promise<User> {
-    const user = await this.ctx.request<User>('GET', `/users/${userId}`, undefined, {
+    const user = await this.ctx.request<User>('GET', `/users/${enc(userId)}`, undefined, {
       cache: options?.cache ?? true,
       cacheTTL: PROFILE_TTL,
     });
@@ -166,7 +168,7 @@ export class UsersApi {
 
   /** The user a session belongs to. */
   async bySession(sessionId: string): Promise<User> {
-    const user = await this.ctx.request<User>('GET', `/session/user/${sessionId}`, undefined, {
+    const user = await this.ctx.request<User>('GET', `/session/user/${enc(sessionId)}`, undefined, {
       cache: true,
       cacheTTL: SESSION_USER_TTL,
     });
@@ -271,7 +273,7 @@ export class UsersApi {
         : (limitOrPagination ?? {});
     const users = await this.ctx.request<User[]>(
       'GET',
-      `/profiles/${userId}/similar`,
+      `/profiles/${enc(userId)}/similar`,
       buildQueryParams(pagination),
       {
         cache: true,
@@ -289,7 +291,7 @@ export class UsersApi {
   async moderators(communityId: string): Promise<User[]> {
     const moderators = await this.ctx.request<User[]>(
       'GET',
-      `/users/${communityId}/moderators`,
+      `/users/${enc(communityId)}/moderators`,
       undefined,
       { cache: true, cacheTTL: PROFILE_TTL },
     );