@oxyhq/core 5.4.3 → 6.0.0

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

@@ -1,3 +1,4 @@
+import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { KeyManager } from '../crypto/keyManager.js';
 import { SignatureService } from '../crypto/signatureService.js';
@@ -613,207 +614,6 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
-        /**
-         * Refresh every device-local refresh-cookie slot in a single round trip
-         * (Google-style multi-account rebuild).
-         *
-         * Calls `POST {sessionBaseUrl}/auth/refresh-all` with `credentials: 'include'`
-         * and NO bearer. The browser attaches every indexed `oxy_rt_${authuser}`
-         * cookie it has; the server rotates each in parallel and returns one entry
-         * per VALID account.
-         *
-         * Failure handling:
-         * - 401 → no signed-in accounts on this device → returns `{ accounts: [] }`
-         *   (NOT an error; this is the cold-boot "not signed in" path).
-         * - 404 → endpoint not deployed → returns `{ accounts: [] }`.
-         * - Any other non-2xx → throws via `handleError`.
-         *
-         * The refresh cookie itself never enters JS — only the rotated access
-         * tokens do. Each access token still needs to be planted via
-         * `setTokens(...)` (or per-account in-memory storage) at the consumer.
-         */
-        async refreshAllSessions(options = {}) {
-            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/refresh-all`;
-            // Optional bounded abort (see `RefreshAllOptions.timeout`). A positive
-            // timeout arms an `AbortController` that aborts the in-flight request; an
-            // abort is treated as "no signed-in accounts on this device" — the same
-            // outcome as a 401 — so a cross-domain stall falls through cleanly instead
-            // of hanging the cold boot.
-            const timeout = typeof options.timeout === 'number' && options.timeout > 0 ? options.timeout : undefined;
-            const controller = timeout !== undefined ? new AbortController() : undefined;
-            const timeoutId = timeout !== undefined && controller
-                ? setTimeout(() => controller.abort(), timeout)
-                : undefined;
-            let response;
-            try {
-                response = await fetch(url, {
-                    method: 'POST',
-                    credentials: 'include',
-                    headers: { Accept: 'application/json' },
-                    signal: controller?.signal,
-                });
-            }
-            catch (error) {
-                // A bounded-timeout abort is the "not signed in / cross-domain stall"
-                // path, NOT an error. The browser raises a DOMException named
-                // 'AbortError' (some runtimes use a generic Error); match on the name so
-                // we never throw the timeout into the cold-boot error handler.
-                if (error instanceof Error && error.name === 'AbortError') {
-                    return { accounts: [] };
-                }
-                throw this.handleError(error);
-            }
-            finally {
-                if (timeoutId !== undefined) {
-                    clearTimeout(timeoutId);
-                }
-            }
-            if (response.status === 401) {
-                return { accounts: [] };
-            }
-            if (response.status === 404) {
-                return { accounts: [] };
-            }
-            if (!response.ok) {
-                throw this.handleError(new Error(`Refresh-all failed with HTTP ${response.status}`));
-            }
-            const payload = (await response.json());
-            const raw = Array.isArray(payload.accounts) ? payload.accounts : [];
-            const accounts = [];
-            for (const entry of raw) {
-                if (entry === null || typeof entry !== 'object') {
-                    continue;
-                }
-                const e = entry;
-                if (!e.accessToken || !e.expiresAt || !e.sessionId || !e.user) {
-                    continue;
-                }
-                const userId = e.user.id ?? e.user._id;
-                // `name.displayName` is optional on the contract — do NOT drop no-name
-                // accounts. Only an absent userId or username makes the entry unusable.
-                if (!userId || !e.user.username) {
-                    continue;
-                }
-                if (typeof e.authuser !== 'number') {
-                    continue;
-                }
-                accounts.push({
-                    authuser: e.authuser,
-                    accessToken: e.accessToken,
-                    expiresAt: e.expiresAt,
-                    sessionId: e.sessionId,
-                    user: {
-                        id: userId,
-                        username: e.user.username,
-                        // `name.displayName` is optional; carry whatever structured name the
-                        // server sent (possibly an empty object) and let consumers fall back.
-                        name: e.user.name ?? {},
-                        avatar: e.user.avatar ?? null,
-                        email: e.user.email,
-                        color: e.user.color ?? null,
-                    },
-                });
-            }
-            return { accounts };
-        }
-        /**
-         * Rotate a single refresh-cookie slot and return the fresh access token.
-         *
-         * When `authuser` is provided, the server rotates ONLY that slot
-         * (`oxy_rt_${authuser}`) — sibling accounts on the same device stay
-         * untouched. When omitted, the server picks the lowest indexed slot present.
-         * The refresh cookie itself never enters JS.
-         *
-         * Returns `null` on 401 (no cookie / expired / reused) so the caller can
-         * fall through cleanly to the unauthenticated path.
-         */
-        async refreshTokenViaCookie(opts = {}) {
-            const result = await this._refreshCookieRaw(opts.authuser);
-            return result;
-        }
-        /**
-         * Sign out a single device-local account by its authuser slot index.
-         *
-         * Revokes that slot's refresh-token family and deactivates its session;
-         * sibling indexed slots stay signed in. The browser-side `oxy_rt_${n}`
-         * cookie is cleared by the server's `Set-Cookie` response header.
-         */
-        async logoutSessionByAuthuser(authuser) {
-            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout?authuser=${encodeURIComponent(String(authuser))}`;
-            try {
-                const response = await fetch(url, {
-                    method: 'POST',
-                    credentials: 'include',
-                    headers: { Accept: 'application/json' },
-                });
-                if (!response.ok && response.status !== 401) {
-                    throw new Error(`Logout (authuser=${authuser}) failed with HTTP ${response.status}`);
-                }
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Sign out EVERY device-local account on this device by clearing every
-         * presented refresh-cookie slot at once. Revokes every family + clears
-         * every slot. Always succeeds (idempotent on unknown/garbage tokens).
-         */
-        async logoutAllSessionsViaCookie() {
-            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout`;
-            try {
-                const response = await fetch(url, {
-                    method: 'POST',
-                    credentials: 'include',
-                    headers: { Accept: 'application/json' },
-                });
-                if (!response.ok && response.status !== 401) {
-                    throw new Error(`Logout-all failed with HTTP ${response.status}`);
-                }
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Internal: raw `POST /auth/refresh[?authuser=N]` call returning the
-         * minted access token. Returns `null` on 401 / non-2xx.
-         *
-         * @internal
-         */
-        async _refreshCookieRaw(authuser) {
-            const base = this.getSessionBaseUrl().replace(/\/$/, '');
-            const url = typeof authuser === 'number'
-                ? `${base}/auth/refresh?authuser=${encodeURIComponent(String(authuser))}`
-                : `${base}/auth/refresh`;
-            let response;
-            try {
-                response = await fetch(url, {
-                    method: 'POST',
-                    credentials: 'include',
-                    headers: { Accept: 'application/json' },
-                });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-            if (!response.ok) {
-                return null;
-            }
-            const payload = (await response.json());
-            if (typeof payload.accessToken !== 'string' || !payload.accessToken) {
-                return null;
-            }
-            const expiresAt = typeof payload.expiresAt === 'string' ? payload.expiresAt : '';
-            if (typeof payload.authuser !== 'number') {
-                return null;
-            }
-            return {
-                accessToken: payload.accessToken,
-                expiresAt,
-                authuser: payload.authuser,
-            };
-        }
         /**
          * Internal: decode (without verifying) the `sessionId` claim from a
          * server-signed access token. The server already verified the signature;
@@ -983,5 +783,70 @@ export function OxyServicesAuthMixin(Base) {
         async signInWithEmail(email, password, deviceName, deviceFingerprint) {
             return this.signIn(email, password, deviceName, deviceFingerprint);
         }
+        /**
+         * Device-first password sign-in. Unlike the legacy {@link signIn} (which
+         * assumes a one-step session and is kept intact for existing callers until
+         * the F4 cutover), this returns the FULL `POST /auth/login` contract — the
+         * discriminated {@link LoginResult}: either a 2FA challenge
+         * (`{ twoFactorRequired, loginToken }`) to complete via
+         * {@link completeTwoFactorSignIn}, or a session arm.
+         *
+         * `options.deviceToken` attributes the new session to the caller's existing
+         * device set (so an in-app login from a cross-apex, cookie-less web app
+         * still joins the same DeviceSession). On the session arm, a returned access
+         * token is planted immediately (mirroring {@link verifyChallenge}), so the
+         * caller has an authenticated client without a second round-trip.
+         */
+        async passwordSignIn(identifier, password, options = {}) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/login', {
+                    identifier,
+                    password,
+                    deviceName: options.deviceName,
+                    deviceFingerprint: options.deviceFingerprint,
+                    deviceToken: options.deviceToken,
+                }, { cache: false });
+                const parsed = safeParseContract(loginResultSchema, res);
+                if (!parsed) {
+                    throw new Error('auth/login returned an unexpected response shape');
+                }
+                if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+                    this.setTokens(parsed.accessToken);
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Complete a 2FA-gated sign-in started by {@link passwordSignIn}. Presents
+         * the short-lived `loginToken` with either a TOTP `token` or a `backupCode`
+         * to `POST /security/2fa/verify-login`, which must resolve to the session
+         * arm of {@link LoginResult} (a second 2FA challenge here is a protocol
+         * error). A returned access token is planted immediately.
+         */
+        async completeTwoFactorSignIn(params) {
+            try {
+                const res = await this.makeRequest('POST', '/security/2fa/verify-login', {
+                    loginToken: params.loginToken,
+                    token: params.token,
+                    backupCode: params.backupCode,
+                    deviceToken: params.deviceToken,
+                    deviceName: params.deviceName,
+                }, { cache: false });
+                const parsed = safeParseContract(loginResultSchema, res);
+                if (!parsed || 'twoFactorRequired' in parsed) {
+                    throw new Error('security/2fa/verify-login returned an unexpected response shape');
+                }
+                if (parsed.accessToken) {
+                    this.setTokens(parsed.accessToken);
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
     };
 }

package/dist/esm/mixins/OxyServices.authorizedApps.js

@@ -0,0 +1,35 @@
+export function OxyServicesAuthorizedAppsMixin(Base) {
+    return class extends Base {
+        /**
+         * List the authenticated user's authorized RP apps — the intersection of the
+         * user's FedCM grants and the currently-approved RP catalog. Powers the
+         * "Connected apps" management UI. Requires a real user session.
+         */
+        async listAuthorizedApps() {
+            try {
+                const response = await this.makeRequest('GET', '/fedcm/me/authorized-apps', undefined, {
+                    cache: true,
+                    cacheTTL: 30 * 1000, // 30 second cache — short, this drives a manageable UI
+                });
+                return response?.apps ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Revoke the authenticated user's authorization for a specific RP origin.
+         * The corresponding cache entry is invalidated so a subsequent
+         * `listAuthorizedApps()` sees fresh data.
+         */
+        async revokeAuthorizedApp(origin) {
+            try {
+                await this.makeRequest('DELETE', `/fedcm/me/authorized-apps/${encodeURIComponent(origin)}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/fedcm/me/authorized-apps');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Device-first bootstrap mixin (auth centralization, wave 1).
+ *
+ * The client half of the new device-first session bootstrap: the four network
+ * calls the cold boot (`coldBootV2`) and the unified refresh handler
+ * (`refresh.ts`) make, plus the URL builder for the cross-apex bootstrap hop.
+ * Every response is validated against the `@oxyhq/contracts` `deviceBoot`
+ * schemas via `safeParseContract`, so producer (oxy-api) and consumer cannot
+ * drift — an unexpected shape throws here rather than silently corrupting the
+ * persisted store.
+ *
+ * These methods are ADDITIVE and carry NO persistence or token-planting side
+ * effects of their own (except the bearer-authenticated calls that naturally
+ * flow through `HttpService`). The cold boot / refresh handler own persistence
+ * and `setTokens`, so the same network primitive can be reused from either
+ * without double-planting.
+ */
+import { authTokenBundleSchema, tokenRefreshResponseSchema, deviceTokenIssueResponseSchema, webSessionResultSchema, safeParseContract, } from '@oxyhq/contracts';
+export function OxyServicesDeviceBootMixin(Base) {
+    return class extends Base {
+        /**
+         * Exchange a single-use boot `code` (from the `#oxy_boot` return fragment)
+         * for a token bundle. Origin-bound + GETDEL-burned server-side.
+         *
+         * @throws if the response does not match {@link authTokenBundleSchema}.
+         */
+        async exchangeBootCode(code) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/device/exchange', { code }, { cache: false });
+                const parsed = safeParseContract(authTokenBundleSchema, res);
+                if (!parsed) {
+                    throw new Error('device/exchange returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Same-site fast path (`*.oxy.so` apps). Reads the first-party `oxy_device`
+         * cookie via a credentialed same-origin fetch and either resolves a full
+         * session bundle or reports the device is known-but-signed-out. Never
+         * redirects.
+         *
+         * @throws if the response matches neither arm of {@link webSessionResultSchema}.
+         */
+        async requestWebSession() {
+            try {
+                const res = await this.makeRequest('POST', '/auth/device/web-session', undefined, { cache: false });
+                const parsed = safeParseContract(webSessionResultSchema, res);
+                if (!parsed) {
+                    throw new Error('device/web-session returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Rotate the persisted refresh-token family (web + native, one call). The
+         * caller (refresh handler / cold boot) plants + persists the rotated pair.
+         *
+         * @throws if the response does not match {@link tokenRefreshResponseSchema}.
+         */
+        async refreshWithToken(refreshToken) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/refresh-token', { refreshToken }, 
+                // `skipAuth`: refresh-token is body-authenticated and is called from
+                // inside the refresh handler — sending the near-expired bearer through
+                // the preflight would deadlock. See RequestOptions.skipAuth.
+                { cache: false, skipAuth: true });
+                const parsed = safeParseContract(tokenRefreshResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('auth/refresh-token returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Issue (or rotate) the native channel's opaque device token. Bearer-gated —
+         * the server derives the deviceId from the JWT. Native apps mirror the
+         * returned token into the shared keychain via
+         * `KeyManager.setSharedDeviceToken`.
+         *
+         * @throws if the response does not match {@link deviceTokenIssueResponseSchema}.
+         */
+        async issueNativeDeviceToken() {
+            try {
+                const res = await this.makeRequest('POST', '/auth/device/token', undefined, { cache: false });
+                const parsed = safeParseContract(deviceTokenIssueResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('auth/device/token returned an unexpected response shape');
+                }
+                return parsed.deviceToken;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Build the top-level `GET /auth/device/bootstrap` URL for the cross-apex
+         * hop. The server validates `return_to` against the trusted-origin lane and
+         * echoes `state` back in the return fragment for CSRF verification.
+         */
+        buildBootstrapUrl(returnTo, state) {
+            const base = this.getBaseURL().replace(/\/+$/, '');
+            const params = new URLSearchParams({ return_to: returnTo, state });
+            return `${base}/auth/device/bootstrap?${params.toString()}`;
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -6,10 +6,7 @@
  */
 import { OxyServicesBase } from '../OxyServices.base.js';
 import { OxyServicesAuthMixin } from './OxyServices.auth.js';
-import { OxyServicesFedCMMixin } from './OxyServices.fedcm.js';
-import { OxyServicesSilentAuthMixin } from './OxyServices.silent.js';
-import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect.js';
-import { OxyServicesSsoMixin } from './OxyServices.sso.js';
+import { OxyServicesAuthorizedAppsMixin } from './OxyServices.authorizedApps.js';
 import { OxyServicesUserMixin } from './OxyServices.user.js';
 import { OxyServicesIdentityMixin } from './OxyServices.identity.js';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
@@ -31,30 +28,25 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
+import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
  * Order matters for dependencies:
  * 1. Base auth mixin first (required by all others)
- * 2. Cross-domain auth mixins (FedCM, silent iframe, Redirect)
- * 3. User mixin (requires auth)
- * 4. Feature mixins (can depend on user)
- * 5. Utility mixin last (augments all)
+ * 2. User mixin (requires auth)
+ * 3. Feature mixins (can depend on user)
+ * 4. Utility mixin last (augments all)
  *
  * To add a new mixin: insert it at the appropriate position in this array.
  */
 const MIXIN_PIPELINE = [
     // Base authentication
     OxyServicesAuthMixin,
-    // Cross-domain authentication (web-only)
-    // - FedCM: Modern browser-native identity federation (Google-style)
-    // - Silent: iframe-based restore for first-party IdP hosts
-    // - Redirect: Traditional redirect-based authentication
-    OxyServicesFedCMMixin,
-    OxyServicesSilentAuthMixin,
-    OxyServicesRedirectAuthMixin,
-    // Central cross-domain SSO (opaque-code exchange).
-    OxyServicesSsoMixin,
+    // Legacy FedCM "Connected apps" management (list/revoke authorized RP grants).
+    // The FedCM sign-in surface was removed in the device-first cutover; only
+    // this management pair survives until the AppGrant migration.
+    OxyServicesAuthorizedAppsMixin,
     // User management (requires auth)
     OxyServicesUserMixin,
     // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
@@ -88,6 +80,10 @@ const MIXIN_PIPELINE = [
     // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
     // so apps stop scraping link metadata locally.
     OxyServicesLinksMixin,
+    // Device-first session bootstrap: the client half of the new
+    // /auth/device/* + /auth/refresh-token surface (exchange, web-session,
+    // refresh, native device-token, bootstrap-url builder).
+    OxyServicesDeviceBootMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/dist/esm/session/SessionClient.js

@@ -37,7 +37,15 @@ export class SessionClient {
             logger.warn('[SessionClient] discarded invalid session state');
             return false;
         }
-        if (this.state && next.revision <= this.state.revision) {
+        // The revision is monotone ONLY within a single deviceId. When the incoming
+        // state belongs to a DIFFERENT device than the currently-applied one, reset
+        // the baseline and accept it regardless of revision: a freshly-converged
+        // device (low revision) must not lose last-writer-wins to a stale, higher-
+        // revision state from a retired device. Only when the deviceIds MATCH is the
+        // `revision <= current` guard a valid staleness check.
+        if (this.state &&
+            next.deviceId === this.state.deviceId &&
+            next.revision <= this.state.revision) {
             return false;
         }
         this.state = next;
@@ -47,6 +55,16 @@ export class SessionClient {
                 logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
             });
         }
+        // A device signout-all leaves zero accounts — tell the provider to clear
+        // the persisted store so a reload does not try to restore a dead session.
+        if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+            try {
+                this.options.onUnauthenticated();
+            }
+            catch (error) {
+                logger.error('[SessionClient] onUnauthenticated threw', error);
+            }
+        }
         return true;
     }
     /**
@@ -93,6 +111,27 @@ export class SessionClient {
         const res = await this.host.makeRequest('POST', '/session/device/add', undefined, { cache: false });
         this.applySync(res);
     }
+    /**
+     * Register the just-signed-in account into the device set AND make it the
+     * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+     *
+     * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+     * (a new account does NOT steal focus from an already-active one), which is
+     * correct for a background/silent add but wrong right after a deliberate
+     * sign-in. This adds, then switches to the target so the UI lands on the
+     * account the user just authenticated.
+     *
+     * @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();
+        const target = accountId ?? this.host.getCurrentAccountId();
+        if (target && this.state?.activeAccountId !== target) {
+            await this.switchAccount(target);
+        }
+    }
     async start() {
         if (this.started)
             return;
@@ -117,7 +156,10 @@ export class SessionClient {
         }
     }
     async connectSocket() {
-        const io = await getSocketIO();
+        // Prefer a statically-injected factory (services/auth-sdk bundle
+        // socket.io-client as a real dep); fall back to the lazy loader — and warn
+        // if THAT yields nothing — only when no factory was injected.
+        const io = this.options.socketFactory ?? (await getSocketIO());
         if (!io) {
             logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
             return;