@oxyhq/core 12.10.6 → 12.11.1

package/dist/cjs/mixins/OxyServices.auth.js

@@ -18,6 +18,61 @@ const userIdentity_1 = require("../utils/userIdentity");
  * returned `expiresAt` is authoritative; this is only the client-proposed value.
  */
 const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
+/**
+ * @internal Narrow an untrusted `requesterLabel` from the approve-info response.
+ *
+ * Returns the trimmed label only when the server sent a real, non-empty string;
+ * everything else — absent (an API that predates the field), `null` (a native
+ * requester the server could not describe), or a non-string — degrades to
+ * `null`, so the approval UI drops the line instead of rendering a blank or a
+ * coerced value under the app it is about to authorize.
+ */
+function parseCommonsRequesterLabel(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const label = value.trim();
+    return label.length > 0 ? label : null;
+}
+/**
+ * @internal Narrow an untrusted `subjectAccount` from the approve-info response.
+ *
+ * Returns `null` unless the value is an object carrying a non-empty string `id`
+ * AND `username` — the two fields the approval UI needs to name the delegated
+ * account. A half-populated object is rejected whole rather than rendered with
+ * blanks, and `displayName` is only carried through when it is a string.
+ */
+function parseCommonsSubjectAccount(value) {
+    if (value === null || typeof value !== 'object') {
+        return null;
+    }
+    const raw = value;
+    const { id, username, displayName } = raw;
+    if (typeof id !== 'string' || !id || typeof username !== 'string' || !username) {
+        return null;
+    }
+    return {
+        id,
+        username,
+        ...(typeof displayName === 'string' ? { displayName } : {}),
+    };
+}
+/**
+ * @internal Narrow an untrusted delivery-progress timestamp from the status
+ * response.
+ *
+ * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+ * and `null` for everything else — absent (an older API that has no delivery
+ * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+ * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+ * to the waiting UI is not.
+ */
+function parseCommonsProgressTimestamp(value) {
+    if (typeof value !== 'string' || !value) {
+        return null;
+    }
+    return Number.isFinite(Date.parse(value)) ? value : null;
+}
 /**
  * Sentinel error raised when getServiceToken() is called with a known apiKey
  * but a non-matching secret. Indicates either credential drift in the caller
@@ -466,11 +521,16 @@ function OxyServicesAuthMixin(Base) {
         //   A. Same-device shared-keychain SSO (`signInWithSharedIdentity`): a
         //      sibling native app silently mints its own session from the shared
         //      identity key. No user interaction.
-        //   B. QR / app-to-app handoff: a relying party (`startCommonsSignIn` +
-        //      `pollCommonsSignIn` + the existing `claimSessionByToken`) and the
-        //      approver / Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn`
-        //      / `denyCommonsSignIn`). The approver signs with its PRIMARY local
-        //      key; the RP never sees the private key.
+        //   B. QR / app-to-app / popup / push handoff: a relying party
+        //      (`startCommonsSignIn` + `pollCommonsSignIn`, finalized with either
+        //      `claimSessionByToken` or `finalizeCommonsOAuth`) and the approver /
+        //      Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn` /
+        //      `denyCommonsSignIn`). The approver signs with its PRIMARY local key;
+        //      the RP never sees the private key.
+        //
+        //      ONE request serves every delivery surface. The delivery surface is
+        //      not part of the model: only the request's purpose is, and it is fixed
+        //      at creation by whether an OAuth binding was attached.
         // =======================================================================
         /**
          * MECHANISM A — same-device shared-keychain SSO.
@@ -521,12 +581,23 @@ function OxyServicesAuthMixin(Base) {
          * returns the server-issued public `authorizeCode` + ready-to-render
          * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
          * approver resolves the code and authorizes. Then poll with
-         * {@link pollCommonsSignIn} and, on `authorized`, exchange the
-         * `sessionToken` via the existing `claimSessionByToken`.
+         * {@link pollCommonsSignIn} and finalize.
+         *
+         * ONE request serves every delivery surface, and how it finalizes is decided
+         * here by whether an OAuth binding is attached:
+         *   - no `oauth` (the default): a `device_sign_in` request — on `authorized`,
+         *     exchange the `sessionToken` via the existing `claimSessionByToken`.
+         *   - with `oauth`: an `oauth_authorization` request — on `authorized`, call
+         *     {@link finalizeCommonsOAuth} with the same `sessionToken` to mint the
+         *     single-use authorization code, then exchange it with PKCE.
          *
          * @param params.clientId - The RP's registered OAuth client id
          *   (ApplicationCredential publicKey); required so the server can resolve the
          *   requesting application's identity.
+         * @param params.oauth - Optional OAuth binding ({@link CommonsOAuthContext}).
+         *   Carries only the redirect URI, the PKCE S256 challenge, the requested
+         *   scope, and an optional delegated `subjectAccountId` — never the PKCE
+         *   verifier, the OAuth `state`, or any token.
          */
         async startCommonsSignIn(params) {
             try {
@@ -535,7 +606,15 @@ function OxyServicesAuthMixin(Base) {
                 // QR. Reuses the platform-safe random generator.
                 const sessionToken = await signatureService_1.SignatureService.generateChallenge();
                 const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
-                const res = await this.makeRequest('POST', '/auth/session/create', { sessionToken, expiresAt, clientId: params.clientId }, 
+                const res = await this.makeRequest('POST', '/auth/session/create', {
+                    sessionToken,
+                    expiresAt,
+                    clientId: params.clientId,
+                    // Omitted entirely when absent so the device-sign-in body stays
+                    // exactly what it has always been (the server reads presence, not a
+                    // null, to decide the request's purpose).
+                    ...(params.oauth ? { oauth: params.oauth } : {}),
+                }, 
                 // Public/pre-session (no bearer): skip the preflight so a stale
                 // near-expiry token cannot re-enter refreshAccessToken while the
                 // refresh handler is already in flight (self-await hang).
@@ -556,18 +635,162 @@ function OxyServicesAuthMixin(Base) {
          * MECHANISM B (relying party) — poll a device-flow session for approval.
          *
          * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
-         * caller exchanges the secret `sessionToken` via the existing
-         * `claimSessionByToken` to mint the first access token.
+         * caller finalizes: `claimSessionByToken` for a `device_sign_in` request,
+         * {@link finalizeCommonsOAuth} for an `oauth_authorization` one.
+         *
+         * Every field is narrowed fail-safe. `authorized` counts only as a literal
+         * `true`, the identifiers only as non-empty strings, and the delivery
+         * progress timestamps degrade to `null` when absent or unparseable — so a
+         * partial or older-API payload can advance the waiting UI at most, never
+         * make it believe a request was approved.
          *
          * @param sessionToken - The secret token from {@link startCommonsSignIn}.
          */
         async pollCommonsSignIn(sessionToken) {
             try {
-                return await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, 
+                const res = await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, 
                 // Public/pre-session (no bearer): a preflight here is wrong per se and,
                 // if ever reached while a refresh is pending, would re-enter
                 // refreshAccessToken and await the very promise it runs inside.
                 { cache: false, retry: false, skipAuth: true });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/status returned an unexpected response shape');
+                }
+                const { authorized, sessionId, publicKey, status, purpose, pushSentAt, openedAt } = res;
+                return {
+                    authorized: authorized === true,
+                    ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
+                    ...(typeof publicKey === 'string' && publicKey ? { publicKey } : {}),
+                    ...(typeof status === 'string' && status ? { status } : {}),
+                    purpose: purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+                    pushSentAt: parseCommonsProgressTimestamp(pushSentAt),
+                    openedAt: parseCommonsProgressTimestamp(openedAt),
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (relying party) — ask Oxy to DELIVER a pending sign-in request
+         * to the identity's known Commons installations.
+         *
+         * This is the automatic half of "one intention, one primary action": rather
+         * than offering the user a menu of transports, the caller asks for delivery
+         * and lets the answer pick the route. Pass the returned `targets` to
+         * `selectCommonsDelivery` (`utils/commonsDelivery`) — `targets: 0` means no
+         * capable Commons installation is registered, which is a NORMAL outcome that
+         * resolves to the QR route, not an error to surface.
+         *
+         * **Requires a bearer.** Delivery is only allowed when Oxy already knows the
+         * intended identity from a trusted authenticated context — a request that
+         * merely carries a username or email typed into an unauthenticated browser
+         * must never be able to ring somebody's phone.
+         *
+         * The push it sends carries only `{ type, approvalUrl }` where the URL holds
+         * the public `authorizeCode` — no display data, no secrets. Commons resolves
+         * everything it shows from `getCommonsApprovalInfo`.
+         *
+         * @param authorizeCode - The public code from {@link startCommonsSignIn}.
+         */
+        async deliverCommonsSignIn(authorizeCode) {
+            try {
+                const res = await this.makeRequest('POST', `/auth/session/deliver/${encodeURIComponent(authorizeCode)}`, undefined, 
+                // Bearer REQUIRED (unlike its public siblings): the identity to
+                // deliver to comes from the authenticated caller, never the code.
+                { cache: false });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/deliver returned an unexpected response shape');
+                }
+                const { delivered, targets } = res;
+                // Both fields drive the route choice, so a partial payload is rejected
+                // outright rather than defaulted into a route the server never chose.
+                if (typeof delivered !== 'boolean' ||
+                    typeof targets !== 'number' ||
+                    !Number.isInteger(targets) ||
+                    targets < 0) {
+                    throw new Error('auth/session/deliver returned an incomplete delivery result');
+                }
+                return { delivered, targets };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (approver / Commons) — report that the approval route was
+         * OPENED, so the waiting relying party can show "Opened in Commons".
+         *
+         * Progress only. It is idempotent, applies to a `pending` request alone, and
+         * records a timestamp (`openedAt`) — it never approves, authorizes, or
+         * advances the authorization state machine. Public, like the other approver
+         * handles: the approver has only the public `authorizeCode` at this point
+         * and has not yet signed anything.
+         *
+         * Best-effort by nature — a failure here costs the user only a progress
+         * line, so callers are free to ignore a rejection and continue to the
+         * approval screen.
+         *
+         * @param authorizeCode - The public code scanned from the QR / deep-link / push.
+         */
+        async markCommonsApprovalOpened(authorizeCode) {
+            try {
+                await this.makeRequest('POST', `/auth/session/opened/${encodeURIComponent(authorizeCode)}`, undefined, 
+                // Public (no bearer) — skip the preflight, exactly like approve-info.
+                { cache: false, skipAuth: true });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (relying party) — finalize an APPROVED, OAuth-bound request
+         * into a single-use OAuth authorization code.
+         *
+         * The OAuth counterpart of `claimSessionByToken`: same secret credential,
+         * same single-use semantics, different output. Call it once the request the
+         * RP started with an `oauth` binding reports `authorized`; the server
+         * atomically mints exactly ONE `AuthCode` bound to the redirect URI, PKCE
+         * challenge, scopes, approving identity, and any delegated subject account
+         * the request was created with. A second call cannot mint another code.
+         *
+         * The result is an authorization CODE, never a token — the caller completes
+         * the flow with the ordinary PKCE exchange (`exchangeOAuthCode`) using the
+         * `codeVerifier` it never sent anywhere. Nothing here is exposed to the
+         * popup: the code travels back through the registered callback, and the
+         * main window owns the verifier.
+         *
+         * Like `claimSessionByToken`, this needs no Authorization header — the
+         * high-entropy SECRET `sessionToken` IS the credential. Never pass the
+         * public `authorizeCode` here; it is the approver's handle, not the
+         * initiator's. Every server-side failure (wrong/expired/already-finalized
+         * request, non-OAuth purpose, missing permission for the delegated account)
+         * surfaces as one generic error, so nothing about the request's state can be
+         * probed from outside.
+         *
+         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+         */
+        async finalizeCommonsOAuth(sessionToken) {
+            try {
+                const res = await this.makeRequest('POST', `/auth/session/finalize/${encodeURIComponent(sessionToken)}`, undefined, 
+                // Body-authenticated by the path's secret token (no bearer) — skip the
+                // preflight, exactly like the device-flow claim.
+                { cache: false, skipAuth: true });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/finalize returned an unexpected response shape');
+                }
+                const { code, redirectUri, expiresIn } = res;
+                // All three fields are load-bearing for the exchange that follows, so a
+                // partial payload is rejected outright rather than returned half-parsed.
+                if (typeof code !== 'string' ||
+                    !code ||
+                    typeof redirectUri !== 'string' ||
+                    !redirectUri ||
+                    typeof expiresIn !== 'number' ||
+                    !Number.isFinite(expiresIn)) {
+                    throw new Error('auth/session/finalize returned an incomplete authorization code');
+                }
+                return { code, redirectUri, expiresIn };
             }
             catch (error) {
                 throw this.handleError(error);
@@ -577,9 +800,10 @@ function OxyServicesAuthMixin(Base) {
          * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
          * sign-in request from its public `authorizeCode`.
          *
-         * The returned `application` is resolved server-side and is the only safe
-         * thing to display in the approval UI — NEVER trust the app/name/origin
-         * strings carried in the QR payload. Public (no auth required).
+         * The returned `application` and `subjectAccount` are resolved server-side
+         * and are the only safe things to display in the approval UI — NEVER trust
+         * the app/name/origin strings carried in the QR payload. Public (no auth
+         * required).
          *
          * @param authorizeCode - The public code scanned from the QR / deep-link.
          */
@@ -597,6 +821,17 @@ function OxyServicesAuthMixin(Base) {
                     // missing or non-boolean value (older server, malformed response)
                     // coerces to `false` so a stale server can never imply trust.
                     originVerified: raw.originVerified === true,
+                    // Same discipline: a missing/blank/non-string label degrades to null
+                    // (an older API, or a native requester with no browser to describe),
+                    // and the approver simply omits the "where from" line.
+                    requesterLabel: parseCommonsRequesterLabel(raw.requesterLabel),
+                    // Same discipline: only the literal OAuth purpose opts into OAuth
+                    // finalization. Anything else — including a server that predates this
+                    // field — is the plain device sign-in it has always been.
+                    purpose: raw.purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+                    // A missing/partial delegated account degrades to "no delegation"
+                    // rather than a half-rendered "will act as" line.
+                    subjectAccount: parseCommonsSubjectAccount(raw.subjectAccount),
                     expiresAt: raw.expiresAt,
                     status: raw.status,
                 };
@@ -648,10 +883,15 @@ function OxyServicesAuthMixin(Base) {
          * device-flow session so the RP stops waiting.
          *
          * @param authorizeCode - The public code being denied.
+         * @param reason - Optional closed-set reason ({@link CommonsDenyReason}).
+         *   Pass `'not_me'` ONLY when the user actually reported the request as one
+         *   they did not start — the server records it as a suspicious denial rather
+         *   than an ordinary cancel. Omitting it sends the exact body this endpoint
+         *   has always received.
          */
-        async denyCommonsSignIn(authorizeCode) {
+        async denyCommonsSignIn(authorizeCode, reason) {
             try {
-                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, undefined, 
+                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, reason ? { reason } : undefined, 
                 // Public (no auth required) — skip the bearer preflight.
                 { cache: false, skipAuth: true });
             }
@@ -914,7 +1154,7 @@ function OxyServicesAuthMixin(Base) {
                 const deviceId = (record.deviceId ?? record.device_id);
                 const deviceSecret = (record.deviceSecret ?? record.device_secret);
                 const userRaw = record.user;
-                if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+                if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
                     throw new Error('auth/oauth/token returned an incomplete session payload');
                 }
                 const userObj = userRaw;

package/dist/cjs/mixins/OxyServices.deviceBoot.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountNotOnDeviceError = void 0;
 exports.OxyServicesDeviceBootMixin = OxyServicesDeviceBootMixin;
 /**
  * Device-first token mint mixin.
@@ -17,6 +18,41 @@ exports.OxyServicesDeviceBootMixin = OxyServicesDeviceBootMixin;
  * primitive can be reused from either without double-planting.
  */
 const contracts_1 = require("@oxyhq/contracts");
+/**
+ * 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.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+class AccountNotOnDeviceError extends Error {
+    constructor(accountId, cause) {
+        super(`account_not_on_device: ${accountId} is not a live account of this device session`);
+        this.accountId = accountId;
+        this.cause = cause;
+        this.name = 'AccountNotOnDeviceError';
+        /** HTTP status of the originating response; mirrors the ApiError shape. */
+        this.status = 401;
+    }
+}
+exports.AccountNotOnDeviceError = AccountNotOnDeviceError;
+/**
+ * Structural (never `instanceof`) read of a normalized mint error: the thrown
+ * value may be a plain ApiError-shaped object or come from another realm.
+ */
+function isAccountNotOnDevice(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { status, message } = error;
+    if (status !== 401) {
+        return false;
+    }
+    return typeof message === 'string' && message.includes('account_not_on_device');
+}
 function OxyServicesDeviceBootMixin(Base) {
     return class extends Base {
         /**
@@ -40,11 +76,22 @@ function OxyServicesDeviceBootMixin(Base) {
          * boot's worst-case time-to-route. A transient failure surfaces once and the
          * scheduler/401 path retries it later.
          *
+         * `options.accountId` PINS the mint to one account of the device instead of
+         * whichever account is currently active. It exists for identity-bound
+         * clients (Commons), whose authenticated user is fixed by a local
+         * cryptographic key and must never follow an account switch made by another
+         * app on the same device. The server never mutates `activeAccountId` for a
+         * pinned mint — the returned `state` still reports the device's true active
+         * account — and rejects a non-member/dead account with
+         * `401 account_not_on_device`, surfaced here as {@link AccountNotOnDeviceError}.
+         *
+         * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
-        async mintFromDeviceSecret(deviceId, deviceSecret) {
+        async mintFromDeviceSecret(deviceId, deviceSecret, options) {
+            const accountId = options?.accountId;
             try {
-                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret }, 
+                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret, ...(accountId ? { accountId } : {}) }, 
                 // `bypassQueue`: this mint is the control-plane call the auth lane
                 // depends on — it must run even when every RequestQueue slot is parked
                 // awaiting it, or the whole client deadlocks. See RequestOptions.bypassQueue.
@@ -56,7 +103,11 @@ function OxyServicesDeviceBootMixin(Base) {
                 return parsed;
             }
             catch (error) {
-                throw this.handleError(error);
+                const normalized = this.handleError(error);
+                if (accountId && isAccountNotOnDevice(normalized)) {
+                    throw new AccountNotOnDeviceError(accountId, normalized);
+                }
+                throw normalized;
             }
         }
         /** Mint a one-time hub sync ticket (bearer required). */

package/dist/cjs/mixins/OxyServices.notifications.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesNotificationsMixin = OxyServicesNotificationsMixin;
+/**
+ * Shape of an Expo push token: `ExponentPushToken[…]` (what
+ * `getExpoPushTokenAsync()` returns today) or the equivalent `ExpoPushToken[…]`
+ * spelling. Deliberately plain ASCII — `@oxyhq/core` ships to Hermes, where
+ * Unicode property escapes throw at runtime.
+ */
+const EXPO_PUSH_TOKEN_PATTERN = /^Expo(nent)?PushToken\[[^[\]\s]+\]$/;
+function OxyServicesNotificationsMixin(Base) {
+    return class extends Base {
+        /**
+         * Register this installation's **Expo** push token for the authenticated
+         * identity (`POST /notifications/push-token`, bearer required).
+         *
+         * Idempotent server-side: re-registering the same token for the same
+         * identity refreshes the existing row rather than creating a duplicate, so
+         * callers can safely re-register on every cold boot.
+         *
+         * @throws When `expoPushToken` is not an Expo push token — a raw APNs/FCM
+         *   device token fails here rather than becoming a silently undeliverable
+         *   registration.
+         */
+        async registerPushToken(input) {
+            try {
+                if (!EXPO_PUSH_TOKEN_PATTERN.test(input.expoPushToken)) {
+                    throw new Error('registerPushToken expects an Expo push token ("ExponentPushToken[...]", from getExpoPushTokenAsync). ' +
+                        'A raw APNs/FCM device token from getDevicePushTokenAsync cannot be delivered to.');
+                }
+                await this.makeRequest('POST', '/notifications/push-token', {
+                    token: input.expoPushToken,
+                    platform: input.platform,
+                    // Omitted entirely when absent so the body stays exactly what the
+                    // endpoint has always received (the server reads presence).
+                    ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+                    ...(input.clientId ? { clientId: input.clientId } : {}),
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Retire an **Expo** push token for the authenticated identity
+         * (`DELETE /notifications/push-token`, bearer required).
+         *
+         * Call it when the user turns notifications off, when the vault identity is
+         * replaced, and on sign-out — otherwise the installation keeps receiving
+         * approval requests for an identity it no longer holds.
+         *
+         * @param expoPushToken - The exact token previously registered.
+         */
+        async unregisterPushToken(expoPushToken) {
+            try {
+                await this.makeRequest('DELETE', '/notifications/push-token', { token: expoPushToken }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.privacy.js

@@ -152,6 +152,9 @@ function OxyServicesPrivacyMixin(Base) {
                     cache: false,
                 });
                 this.clearCacheEntry('GET:/privacy/restricted');
+                // The restriction changed the viewer's graph (`restrictedIds`) — bust the
+                // cached consolidated `GET /users/me/graph` so the next read reflects it.
+                this.clearCacheEntry('GET:/users/me/graph');
                 return result;
             }
             catch (error) {
@@ -175,6 +178,9 @@ function OxyServicesPrivacyMixin(Base) {
                     cache: false,
                 });
                 this.clearCacheEntry('GET:/privacy/restricted');
+                // Symmetric to restrictUser: the unrestrict changed the viewer's
+                // `restrictedIds`, so bust the consolidated `GET /users/me/graph` cache.
+                this.clearCacheEntry('GET:/users/me/graph');
                 return result;
             }
             catch (error) {

package/dist/cjs/mixins/OxyServices.user.js

@@ -821,6 +821,7 @@ function OxyServicesUserMixin(Base) {
                     followingIds: graph?.followingIds || [],
                     mutualIds: graph?.mutualIds || [],
                     blockedIds: graph?.blockedIds || [],
+                    restrictedIds: graph?.restrictedIds || [],
                 };
             }
             catch (error) {

package/dist/cjs/mixins/index.js

@@ -28,6 +28,7 @@ const OxyServices_utility_1 = require("./OxyServices.utility");
 const OxyServices_features_1 = require("./OxyServices.features");
 const OxyServices_topics_1 = require("./OxyServices.topics");
 const OxyServices_contacts_1 = require("./OxyServices.contacts");
+const OxyServices_notifications_1 = require("./OxyServices.notifications");
 const OxyServices_appData_1 = require("./OxyServices.appData");
 const OxyServices_civic_1 = require("./OxyServices.civic");
 const OxyServices_nodes_1 = require("./OxyServices.nodes");
@@ -75,6 +76,10 @@ const MIXIN_PIPELINE = [
     OxyServices_features_1.OxyServicesFeaturesMixin,
     OxyServices_topics_1.OxyServicesTopicsMixin,
     OxyServices_contacts_1.OxyServicesContactsMixin,
+    // Push-token registration: the one SDK-owned register/unregister pair every
+    // Oxy app uses, and what lets a "Sign in with Oxy" request be delivered to a
+    // known Commons installation instead of falling back to a QR.
+    OxyServices_notifications_1.OxyServicesNotificationsMixin,
     OxyServices_appData_1.OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServices_civic_1.OxyServicesCivicMixin,

package/dist/cjs/session/SessionClient.js

@@ -33,6 +33,15 @@ class SessionClient {
     getState() {
         return this.state;
     }
+    /**
+     * The account this client's bearer is pinned to, or `null` when it follows the
+     * device's active account (the default). Resolvers are expected to be a plain
+     * synchronous read of already-resolved state (see
+     * {@link SessionClientOptions.getPinnedAccountId}).
+     */
+    pinnedAccountId() {
+        return this.options.getPinnedAccountId?.() ?? null;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => {
@@ -121,15 +130,26 @@ class SessionClient {
         }
         const previousState = this.state;
         this.state = next;
+        const pinnedAccountId = this.pinnedAccountId();
         // Plant the sync-supplied active token (it is for `next.activeAccountId`)
         // now — before the notify below — so the bearer matches the new active
         // account when subscribers observe it. Guarded on difference to avoid a
         // redundant token-change notification on an unchanged token (bootstrap
-        // restate).
-        if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+        // restate). An identity-bound client only accepts it when the active account
+        // IS its pinned account — otherwise the token belongs to somebody else's
+        // switch and must never displace the pinned bearer.
+        if (activeToken &&
+            next.activeAccountId !== null &&
+            (pinnedAccountId === null || next.activeAccountId === pinnedAccountId) &&
+            activeToken !== this.host.getAccessToken()) {
             this.host.setTokens(activeToken);
         }
-        const transport = this.options.transport;
+        // The transport's entire job is converging the bearer on `activeAccountId`,
+        // which is precisely what an identity-bound client must not do: its token is
+        // minted for the pinned account by the cold boot / re-mint lane. Bypass it
+        // while pinned (also removing the mint-before-notify gate, which exists only
+        // to keep the bearer and the ACTIVE account in step).
+        const transport = pinnedAccountId === null ? this.options.transport : null;
         const activeAccountId = next.activeAccountId;
         // Mint before notifying when the bearer does not already belong to the new
         // active account: no bearer at all, an opaque bearer, OR a bearer for a
@@ -201,12 +221,15 @@ class SessionClient {
         // socket push): `applyState` no-ops without planting, but the token still
         // needs planting. Guard on the sync's active account STILL being the current
         // active account so a stale response cannot adopt a token for an account a
-        // newer state already switched away from.
+        // newer state already switched away from — and, when pinned, on that account
+        // being the PINNED one (same rule as the applied path in `applyState`).
+        const pinnedAccountId = this.pinnedAccountId();
         if (!applied &&
             sync.activeToken &&
             this.state &&
             sync.state.activeAccountId !== null &&
             sync.state.activeAccountId === this.state.activeAccountId &&
+            (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
             sync.activeToken.accessToken !== this.host.getAccessToken()) {
             this.host.setTokens(sync.activeToken.accessToken);
         }
@@ -240,12 +263,19 @@ class SessionClient {
      * sign-in. This adds, then switches to the target so the UI lands on the
      * account the user just authenticated.
      *
+     * An identity-bound (pinned) client only ADDS: its own session is minted for
+     * the pinned account explicitly, so switching the device would gratuitously
+     * re-elect the active account under every OTHER app on this device — a
+     * mutation a pinned client must never make.
+     *
      * @param accountId - The signed-in account id (e.g. `session.user.id`). When
      *   omitted, falls back to the host's current-account ref. If neither
      *   resolves, the add still applies and no switch is performed.
      */
     async registerAndActivate(accountId) {
         await this.addCurrentAccount();
+        if (this.pinnedAccountId() !== null)
+            return;
         const target = accountId ?? this.host.getCurrentAccountId();
         if (target && this.state?.activeAccountId !== target) {
             await this.switchAccount(target);
@@ -349,6 +379,12 @@ class SessionClient {
             const applied = this.applyState(payload, 'push');
             if (!applied)
                 return;
+            // An identity-bound client tracks the pushed state but NEVER chases the
+            // device's active account: re-fetching here would only pull an
+            // `activeToken` for somebody else's switch, which the plant guards would
+            // then discard. Skip the round-trip entirely.
+            if (this.pinnedAccountId() !== null)
+                return;
             // A push changed the active account on another device/tab — re-fetch state
             // to plant the access token for the newly-active account. When this tab is
             // still signed out, applyState mints via ensureActiveToken first; bootstrap