@oxy.so/core 1.0.0

package/dist/esm/session/deviceSwitcherRows.js

@@ -0,0 +1,72 @@
+/**
+ * The device switcher's RENDER model: the directory's people and contexts with
+ * their names, handles and avatar URLs already resolved.
+ *
+ * Pure. It takes the projection {@link projectDevicePrincipals} produces from
+ * the directory and answers the five questions a row asks —
+ * what is it called, what is its handle, where is its avatar, what accent is it
+ * drawn in, may it be activated — so the views stay presentational and neither
+ * of them re-derives a display rule.
+ *
+ * One thing the flat account rows this replaced carried is deliberately absent,
+ * because the directory does not carry it and inventing it would mean going back
+ * to fetching another person's profiles: **email**. The directory profile is the
+ * minimum that renders a row, so the secondary line is the `@handle` — never a
+ * synthesized `username@oxy.so`.
+ *
+ * The accent is NOT in that category. It was, briefly, and it was wrong: an
+ * accent is part of drawing the row rather than profile data about its owner,
+ * and without it every non-active row falls back to the ambient theme accent, so
+ * a device holding two people draws them identically (issue #961). The server
+ * carries it on the directory profile, so no client has to guess or fetch.
+ *
+ * It lives here rather than in a UI package because there is more than one
+ * switcher — the SDK's account dialog and the `auth.oxy.so` chooser — and the
+ * whole point of ADR 0002 is that they render ONE list, built once.
+ */
+import { canActivateContext, directoryDisplayName, directoryHandle, } from './deviceDirectory.js';
+function toContextRow(context, activeContextId, resolveAvatarUrl, locale) {
+    return {
+        contextId: context.contextId,
+        accountId: context.subject.accountId,
+        displayName: directoryDisplayName(context.subject.profile, locale),
+        handle: directoryHandle(context.subject.profile),
+        avatarUrl: resolveAvatarUrl(context.subject.profile.avatar),
+        color: context.subject.profile.color ?? null,
+        // Compared on the CONTEXT id, never the account id: on a device holding two
+        // people the same account is active through exactly one of them, and an
+        // account comparison would light up both rows.
+        isActive: context.contextId === activeContextId,
+        isDelegated: context.isDelegated,
+        canActivate: canActivateContext(context.subject),
+    };
+}
+/** The directory's people and their contexts, ready to render. */
+export function buildSwitcherRows(groups, activeContextId, resolveAvatarUrl, locale) {
+    return groups.map((group) => ({
+        principalId: group.principalId,
+        displayName: directoryDisplayName(group.profile, locale),
+        handle: directoryHandle(group.profile),
+        avatarUrl: resolveAvatarUrl(group.profile.avatar),
+        color: group.profile.color ?? null,
+        isActive: group.isActive,
+        contexts: group.contexts.map((context) => toContextRow(context, activeContextId, resolveAvatarUrl, locale)),
+    }));
+}
+/**
+ * Whether the switcher should name the person above each block.
+ *
+ * The question a header answers is "who is operating this account", and that is
+ * only a question worth printing once somebody holds MORE THAN ONE account
+ * here. Two people with one personal account each is the flat list again — every
+ * row already IS a person, and a header would just print each name twice.
+ *
+ * The moment any one of them can act as a second account, every group gets a
+ * header, including the single-context ones: an inconsistent list is harder to
+ * read than a slightly redundant one, and it is exactly then that "The Oxy
+ * Collective, under Nate" and "The Oxy Collective, under Alice" become two
+ * different rows that must be told apart.
+ */
+export function showsPrincipalHeaders(rows) {
+    return rows.some((row) => row.contexts.length > 1);
+}

package/dist/esm/session/identityPin.js

@@ -0,0 +1,249 @@
+/**
+ * Identity pin — the durable binding between THIS device's PRIMARY identity key
+ * and the account that key authenticates as.
+ *
+ * An identity-bound client (Commons, the identity vault) must always act as the
+ * owner of the local signing key — permanently. The `DeviceSession` it shares
+ * with every other Oxy app on the same device tracks a MUTABLE `activeAccountId`
+ * that any sibling app can switch; following it silently changes both the user
+ * such a client renders and the bearer it sends. The pin is the client-side
+ * record that breaks that coupling: `{ publicKey, accountId }`, written when an
+ * identity-mode session is established (the only moment both facts are known
+ * first-hand), read on every boot, and reconciled against the live
+ * `KeyManager.getPublicKey()` before it is trusted (see
+ * `resolveIdentityPin` in `identitySession.ts`).
+ *
+ * It holds NO secret — a public key and an account id, both already known to the
+ * server — so it lives in the same per-origin storage as {@link PersistedAuthState}
+ * (`authStateStore.ts`) rather than the keychain, and mirrors that module's
+ * store shape: `load / save / clear`, an in-memory mirror, a read-back-verified
+ * durable write, and graceful degradation when storage is unavailable.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { logger } from '../logger/index.js';
+/**
+ * Versioned storage key. Deliberately distinct from the `oxy.auth.*` keys so a
+ * session sign-out (which clears the auth blob) and an identity change (which
+ * clears the pin) can never take each other down.
+ */
+export const IDENTITY_PIN_STORAGE_KEY = 'oxy.identity.pin.v1';
+/**
+ * Structural check for a storable identity public key: `KeyManager` only ever
+ * persists secp256k1 hex — compressed (66 chars) or uncompressed (130). A stored
+ * value of any other shape is corrupt, so it is treated as "no pin" (fail
+ * closed) rather than compared. Full curve validation belongs to `KeyManager`;
+ * the pin's real authority is the reconcile against the live local key.
+ */
+function isStorablePublicKey(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    if (value.length !== 66 && value.length !== 130) {
+        return false;
+    }
+    return /^[0-9a-fA-F]+$/.test(value);
+}
+/**
+ * Parse + shape-validate a stored blob. Returns `null` for anything that is not
+ * a well-formed {@link IdentityPin} (absent, malformed JSON, wrong types, junk
+ * public key) so a corrupt entry degrades to "not pinned" rather than throwing —
+ * and, critically, never yields a pin that could bind a client to the wrong
+ * account.
+ */
+function deserialize(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;
+    if (!isStorablePublicKey(candidate.publicKey)) {
+        return null;
+    }
+    if (typeof candidate.accountId !== 'string' || candidate.accountId.length === 0) {
+        return null;
+    }
+    return {
+        publicKey: candidate.publicKey.toLowerCase(),
+        accountId: candidate.accountId,
+    };
+}
+/**
+ * Serialize a pin, or `null` when the caller handed over a value that would not
+ * survive {@link deserialize} — writing it would produce an entry that silently
+ * reads back as "not pinned".
+ */
+function serialize(pin) {
+    if (!isStorablePublicKey(pin.publicKey) || pin.accountId.length === 0) {
+        return null;
+    }
+    return JSON.stringify({ publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId });
+}
+/**
+ * Whether `pin` still describes the identity currently on this device.
+ *
+ * `publicKey` comparison is case-insensitive (hex). A `null` local key is a
+ * definitive "no identity here" and therefore never a match — the caller clears
+ * the pin rather than binding to an account whose key is gone.
+ */
+export function identityPinMatches(pin, localPublicKey) {
+    if (!pin || !localPublicKey) {
+        return false;
+    }
+    return pin.publicKey.toLowerCase() === localPublicKey.toLowerCase();
+}
+/**
+ * A process-lifetime, in-memory {@link IdentityPinStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store.
+ */
+export function createMemoryIdentityPinStore() {
+    let current = null;
+    return {
+        load: async () => current,
+        save: async (pin) => {
+            if (!serialize(pin)) {
+                return false;
+            }
+            // Memory IS this store's durability backing — the write always lands.
+            current = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            return true;
+        },
+        clear: async () => {
+            current = null;
+        },
+    };
+}
+/**
+ * Read the ambient `localStorage`, tolerating the case where merely ACCESSING
+ * `window.localStorage` throws (sandboxed iframe `SecurityError`). Returns
+ * `null` when storage is unavailable.
+ */
+function safeGetLocalStorage() {
+    try {
+        if (typeof globalThis === 'undefined') {
+            return null;
+        }
+        const store = globalThis.localStorage;
+        return store ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A `localStorage`-backed {@link IdentityPinStore}. Degrades to an in-memory
+ * store when `localStorage` is unreachable, and keeps an in-memory mirror so a
+ * failed persist still pins THIS page's lifetime.
+ */
+export function createWebIdentityPinStore() {
+    const storage = safeGetLocalStorage();
+    if (!storage) {
+        return createMemoryIdentityPinStore();
+    }
+    // `undefined` = never written this session → fall back to storage; any set
+    // value (including `null` after clear) is authoritative.
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                return deserialize(storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+            }
+            catch {
+                return null;
+            }
+        },
+        save: async (pin) => {
+            const json = serialize(pin);
+            if (!json) {
+                logger.error('[identityPin] refusing to persist a malformed identity pin', undefined, { component: 'identityPin' });
+                return false;
+            }
+            sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            try {
+                storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+                if (storage.getItem(IDENTITY_PIN_STORAGE_KEY) === json) {
+                    return true;
+                }
+                logger.error('[identityPin] read-back mismatch after save — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session', undefined, { component: 'identityPin' });
+                return false;
+            }
+            catch (error) {
+                logger.error('[identityPin] persist threw — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session', error, { component: 'identityPin' });
+                return false;
+            }
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+            }
+            catch (error) {
+                logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+            }
+        },
+    };
+}
+/**
+ * A native {@link IdentityPinStore} over an injected async key/value store —
+ * the same seam `createNativeAuthStateStore` uses, so `@oxy.so/core` never
+ * imports `expo-secure-store`.
+ */
+export function createNativeIdentityPinStore(storage) {
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                return deserialize(await storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+            }
+            catch {
+                return null;
+            }
+        },
+        save: async (pin) => {
+            const json = serialize(pin);
+            if (!json) {
+                logger.error('[identityPin] refusing to persist a malformed identity pin', undefined, { component: 'identityPin' });
+                return false;
+            }
+            sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            try {
+                await storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+                // A native write can resolve WITHOUT throwing yet not land, so a
+                // read-back is the only reliable proof.
+                if ((await storage.getItem(IDENTITY_PIN_STORAGE_KEY)) === json) {
+                    return true;
+                }
+                logger.error('[identityPin] read-back mismatch after save — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session', undefined, { component: 'identityPin' });
+                return false;
+            }
+            catch (error) {
+                logger.error('[identityPin] persist threw — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session', error, { component: 'identityPin' });
+                return false;
+            }
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                await storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+            }
+            catch (error) {
+                logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+            }
+        },
+    };
+}

package/dist/esm/session/identitySession.js

@@ -0,0 +1,131 @@
+/**
+ * Identity-bound session — pin reconciliation + establishment.
+ *
+ * This is the SDK half of "an identity vault's authenticated user is whoever
+ * owns the local primary key". Two operations, both consumed by the cold boot
+ * (`boot/sessionColdBoot.ts`) and the re-mint lane (`session/refresh.ts`):
+ *
+ *  - {@link resolveIdentityPin} — read the persisted `{publicKey, accountId}`
+ *    pin and reconcile it against the identity currently on this device. A
+ *    definitive mismatch (the key was replaced, or is gone) CLEARS the pin; an
+ *    INDETERMINATE read (keychain locked / storage threw) leaves it untouched.
+ *  - {@link establishIdentitySession} — mint a session from the PRIMARY local
+ *    key (`getPublicKey` → `requestChallenge` → `signChallenge` →
+ *    `verifyChallenge`), persist the resulting device credential, and write the
+ *    pin. This is the identity-mode replacement for the shared-keychain lane,
+ *    which reads the CROSS-APP shared slot and may therefore hold a different
+ *    identity than this device's primary.
+ *
+ * Both take their key/signature functions from an injectable {@link IdentityBinding}
+ * (defaulting to `KeyManager` / `SignatureService`) so the lanes above stay
+ * testable without a keychain.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
+import { identityPinMatches } from './identityPin.js';
+import { logger } from '../logger/index.js';
+function readPublicKeyOf(binding) {
+    return binding.readPublicKey ?? (() => KeyManager.getPublicKey());
+}
+function signChallengeOf(binding) {
+    return binding.signChallenge ?? ((challenge) => SignatureService.signChallenge(challenge));
+}
+/**
+ * Read the persisted pin and reconcile it against the identity on this device.
+ *
+ * Returns the pin ONLY when the local primary public key still matches it — that
+ * is the single condition under which a client may bind its token and its
+ * rendered user to that account.
+ *
+ * Outcomes:
+ *  - no pin stored → `null` (nothing to clear).
+ *  - local key MATCHES → the pin (trusted).
+ *  - local key read succeeded and differs / is absent → the identity was
+ *    replaced or lost: CLEAR the pin and return `null`. Keeping it would pin the
+ *    client to an account it can no longer prove control of.
+ *  - the local key read THREW (keychain locked, storage unavailable) → return
+ *    `null` WITHOUT clearing. A read that produced no verdict is never evidence
+ *    of an identity change (the same rule `KeyManager` applies to its own
+ *    transient errors); the caller falls through to the identity sign-in lane,
+ *    which fails closed on a locked keychain rather than adopting a foreign
+ *    account.
+ */
+export async function resolveIdentityPin(binding) {
+    const pin = await binding.pinStore.load();
+    if (!pin) {
+        return null;
+    }
+    let localPublicKey;
+    try {
+        localPublicKey = await readPublicKeyOf(binding)();
+    }
+    catch (error) {
+        logger.debug('Identity key read did not produce a verdict — keeping the pin untouched', { component: 'identitySession', method: 'resolveIdentityPin' }, error);
+        return null;
+    }
+    if (identityPinMatches(pin, localPublicKey)) {
+        return pin;
+    }
+    logger.warn('Identity pin no longer matches the device identity key — clearing it (the identity was replaced or removed)', { component: 'identitySession', method: 'resolveIdentityPin' });
+    await binding.pinStore.clear();
+    return null;
+}
+/**
+ * Establish a session for the device's PRIMARY identity key and pin it.
+ *
+ * `requestChallenge` → `signChallenge` → `verifyChallenge`; `verifyChallenge`
+ * plants the access token itself. The server resolves the account from the
+ * VERIFIED SIGNER, so the returned session is identity-authoritative — it
+ * ignores the device's `activeAccountId` entirely.
+ *
+ * Side effects on success: the durable device credential is persisted (so the
+ * next boot can take the fast pinned-mint lane) and the pin is written.
+ *
+ * Returns `null` — never throws — for the two "nothing to do" cases: no local
+ * identity (including every web caller, where `KeyManager` has no key), and a
+ * verify that produced no access token. Network/crypto failures propagate so the
+ * caller can classify them.
+ */
+export async function establishIdentitySession(args) {
+    const { oxy, store, binding, requestOptions } = args;
+    const publicKey = await readPublicKeyOf(binding)();
+    if (!publicKey) {
+        return null;
+    }
+    const { challenge } = await oxy.requestChallenge(publicKey, requestOptions);
+    const signed = await signChallengeOf(binding)(challenge);
+    if (signed.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
+        // The signer disagrees with the key we resolved a challenge for — the
+        // identity changed mid-flight, or a custom signer was misconfigured. Refuse:
+        // verifying under a different key would bind this client to another account.
+        throw new Error('Identity sign-in aborted: the signing key does not match the device identity key');
+    }
+    // `signed.challenge` carries the SIGNATURE (mirrors `signChallengeWithSharedKey`).
+    const session = await oxy.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, binding.deviceName, binding.deviceFingerprint, requestOptions);
+    if (!session?.accessToken) {
+        return null;
+    }
+    // Persist the rotating device credential so later boots re-mint through the
+    // fast `POST /session/device/token` lane instead of re-signing a challenge.
+    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,
+        });
+    }
+    const pin = { publicKey: publicKey.toLowerCase(), accountId: session.user.id };
+    // A failed pin persist is NOT fatal: this process is already pinned in memory,
+    // and a later boot without a pin skips the (unpinned) mint lane and re-runs
+    // this exact lane, which rewrites it. Never fail an established session on it.
+    const pinned = await binding.pinStore.save(pin);
+    if (!pinned) {
+        logger.warn('Identity session established but the pin did not durably persist — the next cold start will re-establish it', { component: 'identitySession', method: 'establishIdentitySession' });
+    }
+    return { session, pin };
+}

package/dist/esm/session/projectSessionState.js

@@ -0,0 +1,114 @@
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes `@oxy.so/services` consumers render today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ *
+ * Each projection takes an OPTIONAL `pinnedAccountId`. Omit it (or pass `null`)
+ * and the projection resolves the device's `activeAccountId` exactly as before.
+ * Pass it — an IDENTITY-BOUND client, whose user is fixed by the local identity
+ * key — and the projection resolves THAT account instead, so an account switch
+ * made by another app on the same device changes `state` but never the user this
+ * client renders.
+ */
+/**
+ * The account a projection should resolve: the pin when one is supplied and
+ * non-empty, else the device's active account. An empty-string pin is treated as
+ * "not pinned" rather than as an account that can never match.
+ *
+ * Exported so no other projection over the same state answers it a second,
+ * subtly different way. A null state with
+ * a pin still resolves to the pin: the pinned identity is bound by a local key,
+ * not by device membership.
+ */
+export function boundAccountIdOf(state, pinnedAccountId) {
+    if (typeof pinnedAccountId === 'string' && pinnedAccountId.length > 0) {
+        return pinnedAccountId;
+    }
+    return state?.activeAccountId ?? null;
+}
+/**
+ * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
+ *
+ * `DeviceSessionState` carries no per-account `expiresAt` / `lastActive` —
+ * both are set to `state.updatedAt` (converted to an ISO-8601 string; the
+ * wire value is an epoch-ms number) as a provisional value.
+ *
+ * `usersById` is accepted for signature symmetry with `activeUserOf` even
+ * though `ClientSession` only stores `userId` — a session is still
+ * projected for an account whose id is absent from `usersById` (no
+ * placeholder user is fabricated).
+ *
+ * `isCurrent` marks the PINNED account when one is supplied, so it can never
+ * disagree with {@link activeSessionIdOf} / {@link activeUserOf} for the same
+ * pin.
+ */
+export function deviceStateToClientSessions(state, usersById, pinnedAccountId) {
+    const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+    return state.accounts.map((account) => ({
+        sessionId: account.sessionId,
+        deviceId: state.deviceId,
+        // provisional: expiresAt/lastActive are not carried on DeviceSessionState
+        expiresAt: provisionalTimestamp,
+        lastActive: provisionalTimestamp,
+        userId: account.accountId,
+        isCurrent: account.accountId === boundAccountId,
+        authuser: account.authuser,
+        operatedByUserId: account.operatedByUserId,
+    }));
+}
+/**
+ * The bound account's `sessionId`, or `null` when there is no state, no bound
+ * account, or that account has no session on this device.
+ *
+ * A pinned account that is ABSENT from `state.accounts` yields `null` — the
+ * honest signal that this device no longer carries a session for the pinned
+ * identity, which the caller answers by re-establishing the identity session
+ * (never by adopting the device's active account).
+ */
+export function activeSessionIdOf(state, pinnedAccountId) {
+    if (state === null) {
+        return null;
+    }
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+    if (boundAccountId === null) {
+        return null;
+    }
+    const boundAccount = state.accounts.find((account) => account.accountId === boundAccountId);
+    return boundAccount?.sessionId ?? null;
+}
+/**
+ * The bound account's `User`, resolved from `usersById`. `null` when there is no
+ * state, no bound account, or the bound account id is absent from `usersById`.
+ *
+ * A pinned user is resolved from `usersById` alone — deliberately NOT gated on
+ * device membership — so a transient device-state gap cannot flicker the
+ * identity vault's rendered user. Whether the pinned session still exists on the
+ * device is answered by {@link activeSessionIdOf}.
+ */
+export function activeUserOf(state, usersById, pinnedAccountId) {
+    if (state === null) {
+        return null;
+    }
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+    if (boundAccountId === null) {
+        return null;
+    }
+    return usersById.get(boundAccountId) ?? null;
+}
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export function accountIdsOf(state) {
+    if (state === null) {
+        return [];
+    }
+    return state.accounts.map((account) => account.accountId);
+}