@oxyhq/core 12.10.5 → 12.11.0

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/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