@oxyhq/core 12.10.6 → 12.11.0

package/src/mixins/OxyServices.deviceBoot.ts

@@ -24,6 +24,42 @@ import {
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 
+/**
+ * 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.
+ */
+export class AccountNotOnDeviceError extends Error {
+  override readonly name = 'AccountNotOnDeviceError';
+  /** HTTP status of the originating response; mirrors the ApiError shape. */
+  readonly status = 401;
+  constructor(readonly accountId: string, readonly cause?: unknown) {
+    super(
+      `account_not_on_device: ${accountId} is not a live account of this device session`,
+    );
+  }
+}
+
+/**
+ * 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: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const { status, message } = error as { status?: unknown; message?: unknown };
+  if (status !== 401) {
+    return false;
+  }
+  return typeof message === 'string' && message.includes('account_not_on_device');
+}
+
 export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     /**
@@ -47,17 +83,29 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * 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: string,
       deviceSecret: string,
+      options?: { accountId?: string },
     ): Promise<DeviceTokenMintResponse> {
+      const accountId = options?.accountId;
       try {
         const res = await this.makeRequest<unknown>(
           'POST',
           '/session/device/token',
-          { deviceId, deviceSecret },
+          { 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.
@@ -69,7 +117,11 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         }
         return parsed;
       } catch (error) {
-        throw this.handleError(error);
+        const normalized = this.handleError(error);
+        if (accountId && isAccountNotOnDevice(normalized)) {
+          throw new AccountNotOnDeviceError(accountId, normalized);
+        }
+        throw normalized;
       }
     }
 

package/src/mixins/OxyServices.notifications.ts

@@ -0,0 +1,142 @@
+/**
+ * Push Notification Registration Mixin
+ *
+ * Registers this installation's push token with Oxy so the platform can reach
+ * the signed-in identity — most importantly to deliver a "Sign in with Oxy"
+ * approval request to a known Commons installation (issue #691, Phase 4)
+ * instead of forcing the user onto a QR.
+ *
+ * This lives in `@oxyhq/core` because push registration is cross-cutting: every
+ * Oxy app that wants to receive platform notifications performs the exact same
+ * bearer-authenticated register/unregister pair. App-local copies drift (see the
+ * token-kind hazard below), so there is ONE implementation here.
+ *
+ * ## The token is an EXPO PUSH TOKEN
+ *
+ * `registerPushToken` takes the token returned by
+ * `Notifications.getExpoPushTokenAsync()` — the `ExponentPushToken[…]` handle —
+ * because the server delivers through Expo's push service, which only accepts
+ * that form.
+ *
+ * It does NOT take `getDevicePushTokenAsync()`'s raw APNs/FCM device token.
+ * Registering one of those looks completely successful (the row is stored, the
+ * endpoint returns 200) and then every push silently fails at delivery time,
+ * which is exactly the failure mode this surface is written to make impossible:
+ * the token is validated here, at the call site, so a raw device token is
+ * rejected immediately with an explicit error rather than becoming a dead
+ * registration nobody notices.
+ *
+ * Acquiring the token (permission prompt, `expo-notifications`) is the app's
+ * job — `@oxyhq/core` never imports an `expo-*` module.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/**
+ * Platform the push token was minted on. Mirrors the enum the server accepts;
+ * a value outside it is rejected server-side.
+ */
+export type PushTokenPlatform = 'ios' | 'android' | 'web';
+
+/**
+ * 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]+\]$/;
+
+/** Registration input for {@link OxyServicesNotificationsMixin.registerPushToken}. */
+export interface RegisterPushTokenInput {
+  /**
+   * The **Expo push token** for this installation — `ExponentPushToken[…]`,
+   * from `Notifications.getExpoPushTokenAsync()`.
+   *
+   * NOT the raw APNs/FCM token from `getDevicePushTokenAsync()`; that form is
+   * rejected before any request is sent.
+   */
+  expoPushToken: string;
+  /** Platform this token was minted on. */
+  platform: PushTokenPlatform;
+  /**
+   * Optional device-first `deviceId` this installation is registered under, so
+   * the server can retire the token when that device session goes away instead
+   * of pushing to an installation that has signed out.
+   */
+  deviceId?: string;
+  /**
+   * Optional registered OAuth client id (the caller's credential `publicKey`,
+   * `oxy_dk_…`) identifying WHICH application this installation is. The server
+   * resolves it to the registering `Application` and rejects an unusable one.
+   *
+   * This is what makes "deliver the approval request to a known Commons
+   * installation" possible: delivery targets the Commons application's
+   * registrations, never every push token the identity owns.
+   */
+  clientId?: string;
+}
+
+export function OxyServicesNotificationsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  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: RegisterPushTokenInput): Promise<void> {
+      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<unknown>(
+          '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: string): Promise<void> {
+      try {
+        await this.makeRequest<unknown>(
+          'DELETE',
+          '/notifications/push-token',
+          { token: expoPushToken },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}