@oxy.so/core 1.0.0

package/dist/cjs/session/accountSwitchTargets.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The two questions an account chooser asks of an account-graph node: is this
+ * kind switchable at all, and may THIS caller become it.
+ *
+ * Pure and I/O-free. They live here rather than beside the surfaces that ask
+ * them because there is more than one such surface — the Console's workspace
+ * tree, the Accounts app's managed-account rows — and a second enumeration of
+ * switch targets is a second place for the rule to go missing, which is
+ * precisely how the Console went on offering `channel` rows after the rule
+ * learned to drop them.
+ *
+ * The DEVICE switcher no longer asks anything here: it renders the server's
+ * device directory (ADR 0002, `deviceDirectory.ts`), whose `available` field is
+ * the server's own authorization verdict. These predicates answer a different
+ * question — one about the caller's account GRAPH, which is a list of accounts
+ * to manage, not a list of identities the device can become.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSwitchTargetAccount = isSwitchTargetAccount;
+exports.canSwitchIntoAccount = canSwitchIntoAccount;
+const contracts_1 = require("@oxy.so/contracts");
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isOperatorSwitchTargetKind(kind)`
+ *    is the exact predicate `POST /accounts/:id/switch` enforces, so a row
+ *    offered on this ground is never a dead button.
+ *
+ * `isOperatorSwitchTargetKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap the kind predicates were introduced to close
+ * on the server.
+ *
+ * And it is the OPERATOR predicate, never `isDelegatedActAsEligibleKind`. The
+ * two differ only on `bot`, so the delegated one produces a list that looks
+ * right and contains one row too many — a seat inside the identity that exists
+ * to act while nobody is present. That is not a hypothetical: it put a live bot
+ * session on a person's own device, beside their personal login.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding an already-projected row can ask it too.
+ */
+function isSwitchTargetAccount(node) {
+    return node.relationship === 'self' || (0, contracts_1.isOperatorSwitchTargetKind)(node.kind);
+}
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+function canSwitchIntoAccount(node) {
+    if (node.relationship === 'self') {
+        return true;
+    }
+    if (!isSwitchTargetAccount(node)) {
+        return false;
+    }
+    const permissions = node.callerMembership?.permissions;
+    if (permissions) {
+        return permissions.includes('account:act_as');
+    }
+    return node.relationship === 'owner';
+}

package/dist/cjs/session/authStateStore.js

@@ -0,0 +1,404 @@
+"use strict";
+/**
+ * Persisted auth state — ONE shape, web + native.
+ *
+ * The zero-cookie device transport persists the device credential per ORIGIN so
+ * a reload restores the session locally without a redirect: `deviceId` +
+ * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
+ * This module is the storage seam: a tiny `load / save / clear` interface plus
+ * platform factories, so the cold boot (`sessionColdBoot`) and the unified re-mint
+ * handler (`refresh.ts`) never touch a platform storage API directly.
+ *
+ * Platform-agnostic — the native factory takes an INJECTED key/value store
+ * (`@oxy.so/services` passes a SecureStore-backed adapter) so `@oxy.so/core`
+ * never imports `expo-secure-store`. The web factory is self-contained
+ * (`localStorage`) and degrades to in-memory when storage is unavailable
+ * (sandboxed iframe `SecurityError`, private-mode quota, SSR).
+ *
+ * ESM-safe (no `require()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_STATE_TOKEN_STORAGE_KEY = exports.AUTH_STATE_STORAGE_KEY = void 0;
+exports.createMemoryAuthStateStore = createMemoryAuthStateStore;
+exports.createWebAuthStateStore = createWebAuthStateStore;
+exports.createNativeAuthStateStore = createNativeAuthStateStore;
+const logger_1 = require("../logger");
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.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
+ * types) so a corrupt entry degrades to "signed out" rather than throwing.
+ */
+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;
+    const hasDeviceCredential = typeof candidate.deviceId === 'string' &&
+        candidate.deviceId.length > 0 &&
+        typeof candidate.deviceSecret === 'string' &&
+        candidate.deviceSecret.length > 0;
+    const hasSessionIdentity = typeof candidate.sessionId === 'string' &&
+        typeof candidate.userId === 'string' &&
+        candidate.sessionId.length > 0 &&
+        candidate.userId.length > 0;
+    // Device-only bootstrap (post join, pre-sign-in): durable credential without session.
+    if (!hasSessionIdentity && !hasDeviceCredential) {
+        return null;
+    }
+    const state = {
+        sessionId: hasSessionIdentity ? candidate.sessionId : '',
+        userId: hasSessionIdentity ? candidate.userId : '',
+    };
+    if (typeof candidate.deviceId === 'string' && candidate.deviceId.length > 0) {
+        state.deviceId = candidate.deviceId;
+    }
+    if (typeof candidate.deviceSecret === 'string' && candidate.deviceSecret.length > 0) {
+        state.deviceSecret = candidate.deviceSecret;
+    }
+    if (typeof candidate.accessToken === 'string' && candidate.accessToken.length > 0) {
+        state.accessToken = candidate.accessToken;
+    }
+    if (typeof candidate.expiresAt === 'string' && candidate.expiresAt.length > 0) {
+        state.expiresAt = candidate.expiresAt;
+    }
+    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`
+ * is unreachable. Not durable across reloads — that is acceptable for the
+ * fallback because the alternative (throwing) would break cold boot entirely.
+ */
+function createMemoryAuthStateStore() {
+    let current = null;
+    return {
+        load: async () => current,
+        save: async (state) => {
+            // Memory IS this store's durability backing — the write always lands.
+            current = state;
+            return true;
+        },
+        clear: async () => {
+            current = null;
+        },
+    };
+}
+/**
+ * Read the ambient `localStorage`, tolerating the case where merely ACCESSING
+ * `window.localStorage` throws. In a sandboxed / cross-origin iframe the getter
+ * itself raises `SecurityError` (not the method calls), so the access must be
+ * inside the try. 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 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),
+ *    the whole store degrades to an in-memory {@link createMemoryAuthStateStore}
+ *    for this page's lifetime — never throws on construction.
+ *  - Individual `getItem`/`setItem`/`removeItem` are each wrapped: a read that
+ *    throws yields `null`; a write that throws (quota, private mode) is
+ *    swallowed. The re-mint lane treats a failed persist as "no durable state"
+ *    rather than crashing.
+ */
+function createWebAuthStateStore() {
+    const storage = safeGetLocalStorage();
+    if (!storage) {
+        return createMemoryAuthStateStore();
+    }
+    // In-memory mirror so a FAILED persist (quota / private mode / locked store)
+    // does not silently lose the session for this page's lifetime. `undefined`
+    // means "never written this session" → fall back to storage; any set value
+    // (including `null` after clear) is authoritative and preferred over storage.
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                return composeState(storage.getItem(exports.AUTH_STATE_STORAGE_KEY), storage.getItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY));
+            }
+            catch {
+                return null;
+            }
+        },
+        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(exports.AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = storage.getItem(exports.AUTH_STATE_STORAGE_KEY) === durableJson;
+                if (!durablePersisted) {
+                    logger_1.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_1.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 {
+                const warmJson = serializeWarmToken(state);
+                if (warmJson) {
+                    storage.setItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    storage.removeItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
+            }
+            catch {
+                // Quota / private-mode / disabled storage — non-fatal warm-boot loss only.
+            }
+            // Report ONLY the durable-credential landing; the warm-token outcome above
+            // is intentionally excluded (it is a best-effort optimization).
+            return durablePersisted;
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                storage.removeItem(exports.AUTH_STATE_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal — see save().
+            }
+            try {
+                storage.removeItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal — see save().
+            }
+        },
+    };
+}
+/**
+ * A native {@link AuthStateStore} over an injected async key/value store.
+ *
+ * `@oxy.so/core` never imports `expo-secure-store`; `@oxy.so/services` constructs
+ * 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.
+ */
+function createNativeAuthStateStore(storage) {
+    // Same in-memory mirror as the web store — a locked/failed SecureStore write
+    // must not silently lose the session for the app's lifetime.
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                const [durableRaw, warmRaw] = await Promise.all([
+                    storage.getItem(exports.AUTH_STATE_STORAGE_KEY),
+                    storage.getItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY),
+                ]);
+                return composeState(durableRaw, warmRaw);
+            }
+            catch {
+                return null;
+            }
+        },
+        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 {
+                const durableJson = serializeDurable(state);
+                await storage.setItem(exports.AUTH_STATE_STORAGE_KEY, durableJson);
+                durablePersisted = (await storage.getItem(exports.AUTH_STATE_STORAGE_KEY)) === durableJson;
+                if (!durablePersisted) {
+                    logger_1.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_1.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(exports.AUTH_STATE_TOKEN_STORAGE_KEY, warmJson);
+                }
+                else {
+                    await storage.removeItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY);
+                }
+            }
+            catch {
+                // Locked / oversize keychain — non-fatal warm-boot loss only.
+            }
+            // Report ONLY the durable-credential landing; the warm-token outcome above
+            // is intentionally excluded (it is a best-effort optimization).
+            return durablePersisted;
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                await storage.removeItem(exports.AUTH_STATE_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal.
+            }
+            try {
+                await storage.removeItem(exports.AUTH_STATE_TOKEN_STORAGE_KEY);
+            }
+            catch {
+                // Non-fatal.
+            }
+        },
+    };
+}

package/dist/cjs/session/createSessionClient.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionClient = createSessionClient;
+const SessionClient_1 = require("./SessionClient");
+const sessionClientHost_1 = require("./sessionClientHost");
+/**
+ * Wires a `SessionClient` over the given `OxyServices` instance: builds the
+ * `SessionClientHost` adapter and passes it through together with a
+ * caller-supplied `TokenTransport`.
+ *
+ * The transport is a required parameter (not constructed here) because it is
+ * the one piece of this integration that is NOT platform-agnostic: `services`
+ * branches native (shared-keychain sign-in) vs. web (silent sign-in), while
+ * `auth-sdk` is web-only. Each consumer builds its own transport and passes
+ * it in; this factory only wires the platform-agnostic parts (host + client)
+ * so neither consumer re-implements them.
+ *
+ * The host is returned alongside the client (not just the client) so the
+ * caller can call `host.setCurrentAccountId(...)` as the active account
+ * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
+ * dist). When omitted, the client falls back to the lazy loader.
+ */
+function createSessionClient(oxyServices, transport, socketFactory) {
+    const host = (0, sessionClientHost_1.createSessionClientHost)(oxyServices);
+    const client = new SessionClient_1.SessionClient(host, { transport, socketFactory });
+    return { client, host };
+}

package/dist/cjs/session/deviceDirectory.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDeviceContext = resolveDeviceContext;
+exports.projectDevicePrincipals = projectDevicePrincipals;
+exports.resolveActiveContext = resolveActiveContext;
+exports.directoryDisplayName = directoryDisplayName;
+exports.directoryHandle = directoryHandle;
+exports.canActivateContext = canActivateContext;
+const accountUtils_1 = require("../utils/accountUtils");
+const userHandle_1 = require("../utils/userHandle");
+/** Resolve one wire context under the principal it hangs off. */
+function toDeviceContext(principal, context) {
+    return {
+        contextId: context.id,
+        actor: {
+            principalId: principal.id,
+            userId: principal.userId,
+            authuser: principal.authuser,
+            profile: principal.user,
+        },
+        subject: {
+            accountId: context.accountId,
+            kind: context.kind,
+            relationship: context.relationship,
+            profile: context.account,
+            onDevice: context.onDevice,
+            available: context.available,
+            lastUsedAt: context.lastUsedAt,
+        },
+        isDelegated: context.accountId !== principal.userId,
+    };
+}
+/**
+ * Resolve one context by its id.
+ *
+ * The search is over `(principal, context)` PAIRS, not over accounts: the same
+ * `accountId` legitimately appears under two principals on a shared device, and
+ * matching on the account would hand back whichever person happened to be
+ * enumerated first.
+ */
+function resolveDeviceContext(directory, contextId) {
+    if (directory === null) {
+        return null;
+    }
+    for (const principal of directory.principals) {
+        for (const context of principal.contexts) {
+            if (context.id === contextId) {
+                return toDeviceContext(principal, context);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The directory as the switcher renders it: people, each with what they may
+ * become.
+ *
+ * A principal with no contexts is kept rather than dropped. It is a real state
+ * — a person whose every context was removed while they remain on the device —
+ * and rendering them with nothing under them is how "sign out of this person"
+ * stays reachable. Silently omitting them would strand the row.
+ */
+function projectDevicePrincipals(directory) {
+    if (directory === null) {
+        return [];
+    }
+    return directory.principals.map((principal) => ({
+        principalId: principal.id,
+        userId: principal.userId,
+        authuser: principal.authuser,
+        profile: principal.user,
+        contexts: principal.contexts.map((context) => toDeviceContext(principal, context)),
+        isActive: directory.activeContextId !== null &&
+            principal.contexts.some((context) => context.id === directory.activeContextId),
+    }));
+}
+/**
+ * The device's active context, or `null`.
+ *
+ * `null` is a real state, not an error: a device with every context removed, or
+ * one whose active context was healed away, has none. It is also the answer when
+ * `activeContextId` names a row no principal holds — a directory that
+ * disagreed with itself, which resolves to "nothing is active" rather than to a
+ * guess.
+ */
+function resolveActiveContext(directory) {
+    if (directory === null || directory.activeContextId === null) {
+        return null;
+    }
+    return resolveDeviceContext(directory, directory.activeContextId);
+}
+/**
+ * The name a directory row renders: the API's `displayName` when it has one,
+ * otherwise the normalized handle, otherwise the localized unnamed sentinel.
+ *
+ * The identity contract's `displayName ?? handle`, and deliberately not
+ * `getAccountDisplayName`'s multi-field chain — that one is for LOCAL account
+ * surfaces, and the directory profile is an API DTO whose `name.displayName`
+ * the server already composed or deliberately omitted. `getAccountDisplayName`
+ * appears here only for its `null` case, which is the sentinel.
+ */
+function directoryDisplayName(profile, locale) {
+    const displayName = profile.name?.displayName?.trim();
+    if (displayName) {
+        return displayName;
+    }
+    return (0, userHandle_1.getNormalizedUserHandle)(profile) ?? (0, accountUtils_1.getAccountDisplayName)(null, locale);
+}
+/**
+ * A directory row's `@handle`, or `null` when the profile carries no usable
+ * username.
+ *
+ * The directory profile has no email — by design, it is the minimum that
+ * renders a row — so the handle is the secondary line, never a synthesized
+ * `username@oxy.so` address.
+ */
+function directoryHandle(profile) {
+    return (0, userHandle_1.getNormalizedUserHandle)(profile);
+}
+/**
+ * Whether a switcher may offer this row — the one question it asks, answered
+ * here so no surface has to re-derive it.
+ *
+ * It is deliberately a single field. `available` is the server's complete
+ * verdict (see {@link DeviceContextSubject.available}), and switchability is an
+ * authorization question the client must READ, never recompute; this exists to
+ * name the field that answers it, not to combine several.
+ *
+ * `onDevice` is NOT part of the question and composing the two is the mistake
+ * this function exists to prevent, in both directions. `onDevice: false` is an
+ * ordinary reachable context whose session is minted on first activation, so
+ * requiring it hides every organization the person has not used here yet.
+ * `onDevice: true` does not imply activatable either: when a principal's own
+ * personal session dies, their delegated contexts keep live sessions of their
+ * own and still cannot be activated, so `available || onDevice` would render a
+ * row the server answers with 403 and then heals away.
+ *
+ * Takes a structural subset so a caller holding a raw `DeviceAccountContext`
+ * from the wire can ask it without resolving the pair first.
+ */
+function canActivateContext(context) {
+    return context.available;
+}