@oxyhq/core 9.2.0 → 9.2.2

package/dist/esm/boot/sessionColdBoot.js

@@ -106,6 +106,19 @@ export async function runSessionColdBoot(opts) {
             if (!session?.accessToken) {
                 return { kind: 'skip' };
             }
+            // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+            // boot can use the faster device-secret-mint lane (sockets + tab-focus
+            // re-mint depend on the credential being in the store).
+            if (session.deviceId && session.deviceSecret) {
+                await store.save({
+                    sessionId: session.sessionId,
+                    userId: session.user.id,
+                    deviceId: session.deviceId,
+                    deviceSecret: session.deviceSecret,
+                    accessToken: session.accessToken,
+                    expiresAt: session.expiresAt,
+                });
+            }
             return {
                 kind: 'session',
                 session: {

package/dist/esm/index.js

@@ -34,6 +34,7 @@ export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity.js';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle.js';
 export { normalizeProfileLinks } from './utils/profileLinks.js';
+export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts.js';
 // ---------------------------------------------------------------------------
 // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,
 // verified domains). Wire shapes (DidDocument, SignedRecordEnvelope,

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

@@ -1,5 +1,6 @@
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 import { CACHE_TIMES } from './mixinHelpers.js';
+export { ORGANIZATION_CATEGORIES } from '@oxyhq/contracts';
 export function OxyServicesAccountsMixin(Base) {
     return class extends Base {
         constructor(...args) {

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

@@ -6,8 +6,8 @@
  */
 import { jwtDecode } from 'jwt-decode';
 import { loadNodeCrypto } from '@oxyhq/protocol';
+import { buildUrl } from '../utils/apiUtils.js';
 import { logger } from '../utils/loggerUtils.js';
-import { CACHE_TIMES } from './mixinHelpers.js';
 /**
  * Expected JWT audience for tokens issued by the Oxy auth service.
  */
@@ -108,10 +108,14 @@ export function OxyServicesUtilityMixin(Base) {
          */
         async fetchLinkMetadata(url) {
             try {
-                return await this.makeRequest('GET', '/link-metadata', { url }, {
-                    cache: true,
-                    cacheTTL: CACHE_TIMES.EXTRA_LONG,
-                });
+                const path = buildUrl('/links/preview', { url, wait: 1 });
+                const preview = await this.makeRequest('GET', path, undefined, { cache: false });
+                return {
+                    url: preview.url,
+                    title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
+                    description: preview.description?.trim() || 'Link',
+                    image: preview.image,
+                };
             }
             catch (error) {
                 throw this.handleError(error);

package/dist/esm/session/SessionClient.js

@@ -21,6 +21,10 @@ export class SessionClient {
         this.started = false;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
+        /** App-facing subscriptions to named server-pushed socket events. */
+        this.serverEvents = new Map();
+        /** Event names already bound on the CURRENT socket instance. */
+        this.boundServerEvents = new Set();
     }
     getState() {
         return this.state;
@@ -31,6 +35,41 @@ export class SessionClient {
             this.listeners.delete(listener);
         };
     }
+    /**
+     * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+     * Listeners survive reconnects and socket re-creation; the returned function
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event, listener) {
+        let listeners = this.serverEvents.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.serverEvents.set(event, listeners);
+        }
+        listeners.add(listener);
+        this.bindServerEvent(event);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    bindServerEvent(event) {
+        if (!this.socket || this.boundServerEvents.has(event))
+            return;
+        this.boundServerEvents.add(event);
+        this.socket.on(event, (payload) => {
+            const listeners = this.serverEvents.get(event);
+            if (!listeners)
+                return;
+            for (const listener of [...listeners]) {
+                try {
+                    listener(payload);
+                }
+                catch (error) {
+                    logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+                }
+            }
+        });
+    }
     notify() {
         for (const listener of this.listeners) {
             try {
@@ -210,6 +249,7 @@ export class SessionClient {
         if (this.socket) {
             this.socket.disconnect();
             this.socket = null;
+            this.boundServerEvents.clear();
         }
     }
     async connectSocket() {
@@ -264,6 +304,11 @@ export class SessionClient {
             }
         });
         this.socket = socket;
+        // (Re)bind app-facing server-event subscriptions on the fresh socket.
+        this.boundServerEvents.clear();
+        for (const event of this.serverEvents.keys()) {
+            this.bindServerEvent(event);
+        }
     }
     /**
      * Open the same-origin `BroadcastChannel` (web only). A sibling tab that

package/dist/esm/session/accountDialogController.js

@@ -30,6 +30,12 @@ import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
 import { generateOAuthState, generatePkcePair, normalizeOAuthRedirectUri, persistOAuthHandshake, } from '../utils/oauthPkce.js';
 import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
 const DEFAULT_POLL_INTERVAL_MS = 3000;
+/**
+ * Commons's custom URL scheme. Probed via the injected `canOpenApp` to detect an
+ * installed Commons on the same device; the `oxycommons://approve?...` deep link
+ * itself is the flow's `qrPayload`.
+ */
+const COMMONS_APP_SCHEME = 'oxycommons://';
 const IDLE_SIGN_IN = {
     phase: 'idle',
     authorizeCode: null,
@@ -72,6 +78,7 @@ export class AccountDialogController {
         this.authRedirectUri = options.authRedirectUri ?? null;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.openUrl = options.openUrl;
+        this.canOpenApp = options.canOpenApp;
         this.snapshot = this.computeSnapshot();
     }
     // =========================================================================
@@ -396,11 +403,34 @@ export class AccountDialogController {
                 error: null,
             });
             this.scheduleNextPoll(handle.sessionToken);
+            // Same-device convenience: if Commons is installed (native only — `canOpenApp`
+            // is undefined/false on web), deep-link straight into its approve screen with
+            // the same `oxycommons://approve?...` payload the QR encodes. The QR + polling
+            // stay live as the fallback, so a user who dismisses the app-open still
+            // completes the sign-in by scanning.
+            void this.maybeOpenCommons(handle.qrPayload);
         }
         catch (error) {
             this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: errorMessage(error) });
         }
     }
+    /**
+     * When a `canOpenApp` probe is injected and reports Commons installed, open the
+     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
+     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     */
+    async maybeOpenCommons(qrPayload) {
+        if (!this.canOpenApp || !this.openUrl)
+            return;
+        try {
+            if (await this.canOpenApp(COMMONS_APP_SCHEME)) {
+                this.openUrl(qrPayload);
+            }
+        }
+        catch (error) {
+            logger.debug('[AccountDialogController] Commons deep-link probe failed (QR fallback active)', { component: 'AccountDialogController' }, error);
+        }
+    }
     /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
     cancelSignIn() {
         this.clearPollTimer();
@@ -523,6 +553,7 @@ export class AccountDialogController {
                 expiresAt: claimed.expiresAt ?? '',
                 user: minimalUser,
                 accessToken: claimed.accessToken,
+                ...(claimed.deviceSecret ? { deviceSecret: claimed.deviceSecret } : {}),
             }, minimalUser);
         }
         catch (error) {

package/dist/esm/session/authStateStore.js

@@ -16,12 +16,34 @@
  *
  * ESM-safe (no `require()`).
  */
+import { logger } from '../utils/loggerUtils.js';
 /**
- * Versioned storage key. The `.v1` suffix lets a future shape change ship a
- * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
- * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
+ * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
+ * `accessToken`. Keeping this blob small (<2KB) matters on Android
+ * `expo-secure-store`, whose backing store can silently fail to persist an
+ * oversize value; bundling the token here previously took the mint credential
+ * down with it on every write, losing the session on cold restart.
+ *
+ * The `.v1` suffix lets a future shape change ship a `.v2` key without reading a
+ * stale/incompatible `.v1` blob. Distinct from the `oxy_shared_*` keychain keys
+ * in `KeyManager`, so it never collides.
+ *
+ * BACK-COMPAT: pre-split builds wrote the WHOLE state (including `accessToken` /
+ * `expiresAt`) into this single key. `load()` still reads those token fields
+ * from here when the warm key ({@link AUTH_STATE_TOKEN_STORAGE_KEY}) is absent,
+ * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
+/**
+ * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
+ * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
+ * failure (quota / oversize keychain value) is swallowed because the session is
+ * fully re-mintable from the durable `deviceSecret`. Kept separate from
+ * {@link AUTH_STATE_STORAGE_KEY} so a failed token write can NEVER abort or
+ * corrupt the durable credential write.
+ */
+export const AUTH_STATE_TOKEN_STORAGE_KEY = 'oxy.auth.token.v1';
 /**
  * Parse + shape-validate a stored blob. Returns `null` for anything that is
  * not a well-formed {@link PersistedAuthState} (absent, malformed JSON, wrong
@@ -72,6 +94,95 @@ function deserialize(raw) {
     }
     return state;
 }
+/**
+ * Parse the best-effort warm-token blob. Returns `null` for anything not a
+ * well-formed object so a corrupt warm entry simply forgoes the warm-boot
+ * optimization (the durable credential re-mints a fresh token).
+ */
+function parseWarmToken(raw) {
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const candidate = parsed;
+    const warm = {};
+    if (typeof candidate.accessToken === 'string' && candidate.accessToken.length > 0) {
+        warm.accessToken = candidate.accessToken;
+    }
+    if (typeof candidate.expiresAt === 'string' && candidate.expiresAt.length > 0) {
+        warm.expiresAt = candidate.expiresAt;
+    }
+    return warm;
+}
+/** Serialize ONLY the small, re-mint-critical fields for the durable key. */
+function serializeDurable(state) {
+    const durable = {
+        sessionId: state.sessionId,
+        userId: state.userId,
+    };
+    if (state.deviceId) {
+        durable.deviceId = state.deviceId;
+    }
+    if (state.deviceSecret) {
+        durable.deviceSecret = state.deviceSecret;
+    }
+    return JSON.stringify(durable);
+}
+/**
+ * Serialize the warm-token blob, or `null` when there is no token to persist
+ * (so the caller clears the warm key rather than writing an empty object).
+ */
+function serializeWarmToken(state) {
+    const warm = {};
+    if (state.accessToken) {
+        warm.accessToken = state.accessToken;
+    }
+    if (state.expiresAt) {
+        warm.expiresAt = state.expiresAt;
+    }
+    if (!warm.accessToken && !warm.expiresAt) {
+        return null;
+    }
+    return JSON.stringify(warm);
+}
+/**
+ * Compose the unchanged {@link PersistedAuthState} return shape from the two
+ * on-disk keys. `accessToken` / `expiresAt` come from the warm key when it is
+ * present; when the warm key is ABSENT the token fields fall back to whatever
+ * the durable blob carried — the pre-split combined `oxy.auth.v1` blob (BACK-COMPAT).
+ */
+function composeState(durableRaw, warmRaw) {
+    const state = deserialize(durableRaw);
+    if (!state) {
+        return null;
+    }
+    if (warmRaw !== null) {
+        // New split layout: the warm key is authoritative for the token fields.
+        // Drop anything the durable blob may have carried, then overlay the warm
+        // values (a warm key with no token → the session simply has no warm token).
+        delete state.accessToken;
+        delete state.expiresAt;
+        const warm = parseWarmToken(warmRaw);
+        if (warm?.accessToken) {
+            state.accessToken = warm.accessToken;
+        }
+        if (warm?.expiresAt) {
+            state.expiresAt = warm.expiresAt;
+        }
+    }
+    // else: BACK-COMPAT — the warm key is absent, so `deserialize` already applied
+    // any `accessToken` / `expiresAt` from the old combined blob.
+    return state;
+}
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -109,8 +220,9 @@ function safeGetLocalStorage() {
     }
 }
 /**
- * A `localStorage`-backed {@link AuthStateStore} under the versioned
- * {@link AUTH_STATE_STORAGE_KEY}.
+ * A `localStorage`-backed {@link AuthStateStore} split across the durable
+ * {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the best-effort
+ * {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token).
  *
  * Resilience:
  *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
@@ -137,7 +249,7 @@ export function createWebAuthStateStore() {
                 return sessionMirror;
             }
             try {
-                return deserialize(storage.getItem(AUTH_STATE_STORAGE_KEY));
+                return composeState(storage.getItem(AUTH_STATE_STORAGE_KEY), storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY));
             }
             catch {
                 return null;
@@ -145,12 +257,35 @@ export function createWebAuthStateStore() {
         },
         save: async (state) => {
             sessionMirror = state; // mirror FIRST — authoritative even if persist fails
+            // Durable credential FIRST, then VERIFY it landed. The in-memory mirror
+            // keeps the session live for this page, but a failed DURABLE write means
+            // the mint credential will NOT survive a reload — surface it, never swallow.
+            let durablePersisted = false;
+            try {
+                const durableJson = serializeDurable(state);
+                storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = storage.getItem(AUTH_STATE_STORAGE_KEY) === durableJson;
+                if (!durablePersisted) {
+                    logger.error('[authStateStore] durable credential read-back mismatch after save — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload', undefined, { component: 'authStateStore' });
+                }
+            }
+            catch (error) {
+                logger.error('[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this process via the in-memory mirror but will be lost on reload', error, { component: 'authStateStore' });
+            }
+            // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+            // durable credential re-mints a fresh token) and must never abort or
+            // corrupt the durable write above.
             try {
-                storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+                const warmJson = serializeWarmToken(state);
+                if (warmJson) {
+                    storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
             }
             catch {
-                // Quota / private-mode / disabled storage — non-fatal. The session
-                // stays live via the in-memory mirror; only reload durability is lost.
+                // Quota / private-mode / disabled storage — non-fatal warm-boot loss only.
             }
         },
         clear: async () => {
@@ -161,6 +296,12 @@ export function createWebAuthStateStore() {
             catch {
                 // Non-fatal — see save().
             }
+            try {
+                storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal — see save().
+            }
         },
     };
 }
@@ -168,9 +309,12 @@ export function createWebAuthStateStore() {
  * A native {@link AuthStateStore} over an injected async key/value store.
  *
  * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
- * the SecureStore-backed adapter and passes it here. Every operation is wrapped
- * so a storage exception degrades gracefully (read → `null`, write → swallowed)
- * exactly like the web store.
+ * the SecureStore-backed adapter and passes it here. Persistence is split across
+ * the durable {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the
+ * best-effort {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token) — the
+ * durable write is read-back-verified and its failure surfaced (not swallowed),
+ * while the warm-token write and all reads degrade gracefully exactly like the
+ * web store.
  */
 export function createNativeAuthStateStore(storage) {
     // Same in-memory mirror as the web store — a locked/failed SecureStore write
@@ -182,7 +326,11 @@ export function createNativeAuthStateStore(storage) {
                 return sessionMirror;
             }
             try {
-                return deserialize(await storage.getItem(AUTH_STATE_STORAGE_KEY));
+                const [durableRaw, warmRaw] = await Promise.all([
+                    storage.getItem(AUTH_STATE_STORAGE_KEY),
+                    storage.getItem(AUTH_STATE_TOKEN_STORAGE_KEY),
+                ]);
+                return composeState(durableRaw, warmRaw);
             }
             catch {
                 return null;
@@ -190,11 +338,37 @@ export function createNativeAuthStateStore(storage) {
         },
         save: async (state) => {
             sessionMirror = state;
+            // Durable credential FIRST, then VERIFY. On Android SecureStore an
+            // oversize/failed write can resolve WITHOUT throwing, so a read-back is the
+            // only reliable proof. The mirror keeps the session live for this app run,
+            // but a failed DURABLE write means the mint credential will NOT survive a
+            // cold restart — surface it, never swallow.
+            let durablePersisted = false;
             try {
-                await storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(state));
+                const durableJson = serializeDurable(state);
+                await storage.setItem(AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = (await storage.getItem(AUTH_STATE_STORAGE_KEY)) === durableJson;
+                if (!durablePersisted) {
+                    logger.error('[authStateStore] durable credential read-back mismatch after save — the device credential did not persist (likely oversize SecureStore value); the session survives this app run via the in-memory mirror but will be lost on cold restart', undefined, { component: 'authStateStore' });
+                }
+            }
+            catch (error) {
+                logger.error('[authStateStore] durable credential persist threw — the device credential did not persist; the session survives this app run via the in-memory mirror but will be lost on cold restart', error, { component: 'authStateStore' });
+            }
+            // Warm token AFTER, best-effort. Its failure is genuinely non-fatal (the
+            // durable credential re-mints a fresh token) and must never abort or
+            // corrupt the durable write above.
+            try {
+                const warmJson = serializeWarmToken(state);
+                if (warmJson) {
+                    await storage.setItem(AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
             }
             catch {
-                // Non-fatal — session stays live via the in-memory mirror.
+                // Locked / oversize keychain — non-fatal warm-boot loss only.
             }
         },
         clear: async () => {
@@ -205,6 +379,12 @@ export function createNativeAuthStateStore(storage) {
             catch {
                 // Non-fatal.
             }
+            try {
+                await storage.removeItem(AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal.
+            }
         },
     };
 }