@oxyhq/core 20.0.0 → 21.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/projectSessionState.js

@@ -20,12 +20,17 @@
  * 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.
  */
-function boundAccountIdOf(state, pinnedAccountId) {
+export function boundAccountIdOf(state, pinnedAccountId) {
     if (typeof pinnedAccountId === 'string' && pinnedAccountId.length > 0) {
         return pinnedAccountId;
     }
-    return state.activeAccountId;
+    return state?.activeAccountId ?? null;
 }
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
@@ -55,6 +60,7 @@ export function deviceStateToClientSessions(state, usersById, pinnedAccountId) {
         userId: account.accountId,
         isCurrent: account.accountId === boundAccountId,
         authuser: account.authuser,
+        operatedByUserId: account.operatedByUserId,
     }));
 }
 /**

package/dist/esm/session/sharedDeviceCredential.js

@@ -0,0 +1,239 @@
+/**
+ * The shared native DeviceSession credential — one device, one session, many apps.
+ *
+ * ## What this is, and what it deliberately is NOT
+ *
+ * Two different secrets can make a native Oxy app boot signed in, and conflating
+ * them is the bug this module exists to end:
+ *
+ *   Commons private identity key   → identity and signed approval ONLY. It is
+ *                                    self-custody, irreplaceable, and must never
+ *                                    become the general app session transport.
+ *   Shared DeviceSession credential → THIS module. An ordinary `deviceId` +
+ *                                    `deviceSecret` pair that restores ordinary
+ *                                    official apps, follows the device's active
+ *                                    context, and is individually rotatable and
+ *                                    revocable server-side.
+ *
+ * An ordinary app needs the second one. Handing it the first — which is what the
+ * `shared-key-signin` lane does today — gives every sibling app the ability to
+ * sign as the user's cryptographic identity to obtain something as mundane as a
+ * session. That lane stays as a recovery/compatibility path; this one supersedes
+ * it for the ordinary case.
+ *
+ * ## Why sharing one credential is safe against the server
+ *
+ * `POST /session/device/token` does NOT rotate: the response echoes the presented
+ * secret back as `nextDeviceSecret` precisely so several first-party apps sharing
+ * one `DeviceSession` can refresh concurrently without invalidating one another.
+ * So N apps holding one credential is a supported server state, not a race — and
+ * because they then share ONE `DeviceSession`, they automatically share its
+ * `activeContextId` and its token-free `session_state` broadcasts.
+ *
+ * ## The one safety rule everything here is built around
+ *
+ * A read that FAILED and a slot that is EMPTY must never be the same value. The
+ * empty answer authorises writes (seed the slot); the failed answer must
+ * authorise nothing. {@link SharedDeviceCredentialRead} keeps them apart at the
+ * type level, and every decision below fails closed on anything that is not a
+ * positive `absent`/`present`.
+ *
+ * Platform-agnostic: the actual keychain / keystore access is injected as a
+ * {@link SharedDeviceCredentialStore} by `@oxyhq/services`. ESM-safe, no
+ * `require()`, no react/react-native/expo imports.
+ */
+import { logger } from '../logger/index.js';
+/** The usable `{deviceId, deviceSecret}` pair in a persisted state, or null. */
+export function readLocalDeviceCredential(state) {
+    if (!state?.deviceId || !state.deviceSecret) {
+        return null;
+    }
+    return { deviceId: state.deviceId, deviceSecret: state.deviceSecret };
+}
+/**
+ * Narrow an UNTRUSTED bridge payload into a {@link SharedDeviceCredentialRead}.
+ *
+ * Anything unrecognised resolves to `unavailable`, never `absent`. A native
+ * module returning a shape this build does not understand (an older app in the
+ * signing group, a partially-applied upgrade) means we do not KNOW whether the
+ * device has a shared session — and "do not know" must never authorise a write
+ * that would overwrite one.
+ */
+export function normalizeSharedDeviceSessionRead(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { state: 'unavailable', cause: new Error('shared device session bridge returned a non-object') };
+    }
+    const payload = raw;
+    if (payload.status === 'absent') {
+        return { state: 'absent' };
+    }
+    if (payload.status === 'present') {
+        const deviceId = payload.deviceId;
+        const deviceSecret = payload.deviceSecret;
+        if (typeof deviceId === 'string' &&
+            deviceId.length > 0 &&
+            typeof deviceSecret === 'string' &&
+            deviceSecret.length > 0) {
+            return { state: 'present', credential: { deviceId, deviceSecret } };
+        }
+        // A `present` verdict whose payload is incomplete is a broken slot, not an
+        // empty one. Reporting `absent` here would let the next successful sign-in
+        // overwrite whatever is really in there.
+        return {
+            state: 'unavailable',
+            cause: new Error('shared device session bridge reported `present` with an incomplete credential'),
+        };
+    }
+    if (payload.status === 'unavailable') {
+        const reason = typeof payload.reason === 'string' ? payload.reason : 'unknown';
+        return { state: 'unavailable', cause: new Error(`shared device session slot unavailable: ${reason}`) };
+    }
+    return {
+        state: 'unavailable',
+        cause: new Error(`shared device session bridge returned an unrecognised status: ${String(payload.status)}`),
+    };
+}
+/**
+ * Should this app adopt the shared credential? Pure.
+ *
+ * Adoption happens in exactly ONE case: the shared slot holds a credential and
+ * this app has none of its own. That single rule delivers the product
+ * requirement — a newly installed official app joins the device's existing
+ * session without another QR — while making the two failure modes that matter
+ * unreachable:
+ *
+ *  - An app that is already signed in is NEVER moved onto another credential, so
+ *    "no user is signed out merely because one app updates first" holds by
+ *    construction, in both upgrade directions.
+ *  - A failed read never looks like an empty slot, so a locked keychain resolves
+ *    to "keep what I have" rather than "this is a fresh device".
+ *
+ * The cost is stated plainly: two apps that each already own a DIFFERENT device
+ * session stay on their own until one of them loses its credential. Converging
+ * them would mean signing one of them out or a server-side device merge, and
+ * neither is something a boot path may do silently.
+ */
+export function decideSharedDeviceJoin(local, shared) {
+    if (readLocalDeviceCredential(local) !== null) {
+        return { action: 'skip', reason: 'local-credential-present' };
+    }
+    switch (shared.state) {
+        case 'present':
+            return { action: 'adopt', credential: shared.credential };
+        case 'absent':
+            return { action: 'skip', reason: 'shared-empty' };
+        case 'unavailable':
+            return { action: 'skip', reason: 'shared-unreadable' };
+        case 'unsupported':
+            return { action: 'skip', reason: 'shared-unsupported' };
+    }
+}
+/**
+ * Should this app write the credential it just proved into the shared slot? Pure.
+ *
+ * `proven` means the server accepted it moments ago — a successful sign-in or a
+ * successful mint. Only a proven credential is ever published, so the slot can
+ * never be seeded with something no app could use.
+ *
+ * A slot already held by a DIFFERENT `deviceId` is left alone. Overwriting it
+ * would silently migrate every other app on this device onto our session at their
+ * next cold boot — a real, user-visible change of who they are signed in as, and
+ * not something a background persist may decide.
+ */
+export function decideSharedDevicePublish(proven, shared) {
+    switch (shared.state) {
+        case 'unsupported':
+            return { action: 'skip', reason: 'shared-unsupported' };
+        case 'unavailable':
+            return { action: 'skip', reason: 'shared-unreadable' };
+        case 'absent':
+            return { action: 'publish' };
+        case 'present': {
+            if (shared.credential.deviceId !== proven.deviceId) {
+                return { action: 'skip', reason: 'owned-by-another-device' };
+            }
+            if (shared.credential.deviceSecret === proven.deviceSecret) {
+                return { action: 'skip', reason: 'already-current' };
+            }
+            // Same device, newer secret. Sign-in rotates the secret (the mint does
+            // not), so the just-proven one is the credential a fresh install should
+            // join with.
+            return { action: 'publish' };
+        }
+    }
+}
+/**
+ * Read the shared slot, apply {@link decideSharedDevicePublish}, and write when
+ * it says so. Best-effort by contract: the caller's own durable credential is
+ * already persisted, so a failure here only means a future install will have to
+ * sign in interactively.
+ */
+export async function publishProvenDeviceCredential(deps) {
+    const read = await deps.shared.read();
+    const decision = decideSharedDevicePublish(deps.credential, read);
+    if (decision.action === 'skip') {
+        if (decision.reason === 'shared-unreadable') {
+            logger.debug('shared device credential slot unreadable — not publishing (an unreadable slot is never an empty one)', { component: 'sharedDeviceCredential', method: 'publishProvenDeviceCredential' });
+        }
+        return { status: 'skipped', reason: decision.reason };
+    }
+    const published = await deps.shared.publish(deps.credential);
+    return published ? { status: 'published' } : { status: 'publish-failed' };
+}
+/**
+ * Wrap a platform {@link AuthStateStore} so that every durable credential it
+ * persists is ALSO mirrored into the shared slot.
+ *
+ * Writes mirror automatically; reads do NOT adopt. That split is deliberate:
+ *
+ *  - Mirroring on write is the right place because `save()` is where a proven
+ *    credential lands, on every lane there is — interactive sign-in, the cold
+ *    boot mint, the refresh scheduler, the 401 re-mint, shared-key recovery. One
+ *    seam, no lane left out, and no new call site to forget.
+ *  - Adopting on read would hide a change of WHO THIS APP IS SIGNED IN AS inside
+ *    a storage primitive, and would run on every `load()`. Adoption is an
+ *    explicit, once-per-boot cold-boot step instead (`shared-device-adopt`).
+ *
+ * `clear()` deliberately does NOT clear the shared slot. This app signing out is
+ * not authority over the device-wide join point: other apps may still be signed
+ * in on that same credential, and once the server session is really gone the
+ * credential mints `no_active_session` for everyone anyway.
+ */
+export function createSharedMirroringAuthStateStore(deps) {
+    const { local, shared } = deps;
+    // Process-local memo of the credential we last observed the shared slot to
+    // hold. Purely an optimization to keep the refresh scheduler from re-reading
+    // the keychain every mint; a slot wiped out from under us is re-seeded on the
+    // next launch rather than mid-process.
+    let mirrored = null;
+    return {
+        load: () => local.load(),
+        clear: () => local.clear(),
+        save: async (state) => {
+            // The durable local write is the contract this store owes its caller —
+            // run it first and report ITS result, unchanged. The mirror is additive.
+            const durablePersisted = await local.save(state);
+            const credential = readLocalDeviceCredential(state);
+            if (!credential) {
+                return durablePersisted;
+            }
+            if (mirrored !== null &&
+                mirrored.deviceId === credential.deviceId &&
+                mirrored.deviceSecret === credential.deviceSecret) {
+                return durablePersisted;
+            }
+            try {
+                const outcome = await publishProvenDeviceCredential({ shared, credential });
+                if (outcome.status === 'published' || (outcome.status === 'skipped' && outcome.reason === 'already-current')) {
+                    mirrored = credential;
+                }
+            }
+            catch (error) {
+                // A store implementation is contractually non-throwing, but a mirror
+                // failure must never take down the durable write that already succeeded.
+                logger.debug('mirroring the device credential into the shared slot threw — the local credential is unaffected', { component: 'sharedDeviceCredential', method: 'save' }, error);
+            }
+            return durablePersisted;
+        },
+    };
+}