@oxy.so/core 1.0.0

package/dist/types/session/accountSwitchTargets.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import type { AccountRelationship, AccountKind, AccountMember } from '../mixins/OxyServices.accounts';
+/**
+ * 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.
+ */
+export declare function isSwitchTargetAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+}): boolean;
+/**
+ * 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.
+ */
+export declare function canSwitchIntoAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+}): boolean;

package/dist/types/session/authStateStore.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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()`).
+ */
+/**
+ * The persisted session credential set for a single origin.
+ *
+ * `sessionId` + `userId` identify the owning device session and active account.
+ * `deviceId` + `deviceSecret` are the zero-cookie mint credential: the client
+ * presents BOTH at `POST /session/device/token` — the secret is the proof, the
+ * deviceId selects the device doc. The secret is rotated in-use: the mint returns
+ * `nextDeviceSecret`, which the cold boot / re-mint handler persist BEFORE
+ * planting the minted access token (multi-tab anti-loss).
+ *
+ * `accessToken` + `expiresAt` are OPTIONAL warm-boot fields. Persisting them lets
+ * the cold boot plant a still-valid access token on the very first paint WITHOUT
+ * a blocking mint round-trip — the proactive scheduler then rotates it in the
+ * background. They are a strict optimization: the store is fully functional (via
+ * `deviceSecret`) when they are absent or stale, and the access token is
+ * short-lived, so persisting it adds no exposure the already-persisted
+ * `deviceSecret` does not.
+ */
+export interface PersistedAuthState {
+    sessionId: string;
+    userId: string;
+    /**
+     * The stable device identifier this session is bound to (zero-cookie
+     * transport). Persisted alongside {@link deviceSecret} because the
+     * `POST /session/device/token` mint presents BOTH. Sourced from every login
+     * lane (password / 2FA / QR claim / challenge verify) via the response's
+     * `deviceId`.
+     */
+    deviceId?: string;
+    /**
+     * The rotating device secret (zero-cookie transport). Possession of it mints a
+     * short access token for the device's active account via
+     * `POST /session/device/token`. Rotated in-use.
+     */
+    deviceSecret?: string;
+    /** Optional warm-boot access token (short-lived; see interface docs). */
+    accessToken?: string;
+    /** Optional warm-boot access-token expiry, ISO-8601. */
+    expiresAt?: string;
+}
+/**
+ * The storage seam consumed by the cold boot and the re-mint handler. Async
+ * throughout so one interface fits both synchronous web `localStorage` and
+ * asynchronous native SecureStore/AsyncStorage. `clear()` (sign-out) wipes the
+ * per-sign-in credential blob.
+ */
+export interface AuthStateStore {
+    load(): Promise<PersistedAuthState | null>;
+    /**
+     * Persist the credential blob and report whether it durably landed.
+     *
+     * Resolves `true` when the state is retained consistent with this store's
+     * durability guarantee — a durable backing whose read-back matched, or a
+     * degraded/in-memory store that held it in memory. Resolves `false` when a
+     * DURABLE backing was expected but the write did NOT land (read-back mismatch
+     * or a thrown write); the in-memory mirror still keeps the session live for
+     * this process, but it will be lost on reload.
+     *
+     * A lane persisting a ROTATED device secret (the mint's `nextDeviceSecret`)
+     * MUST treat `false` as fatal for that mint: it must NOT plant/advertise a
+     * session built on a secret that will not survive a reload.
+     */
+    save(state: PersistedAuthState): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/**
+ * The minimal async key/value surface a native store must provide. Matches
+ * both `expo-secure-store` (wrapped) and `@react-native-async-storage`.
+ */
+export interface NativeKeyValueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * 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 declare 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 declare const AUTH_STATE_TOKEN_STORAGE_KEY = "oxy.auth.token.v1";
+/**
+ * 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.
+ */
+export declare function createMemoryAuthStateStore(): AuthStateStore;
+/**
+ * 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.
+ */
+export declare function createWebAuthStateStore(): AuthStateStore;
+/**
+ * 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.
+ */
+export declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

package/dist/types/session/createSessionClient.d.ts

@@ -0,0 +1,30 @@
+import type { OxyServices } from '../OxyServices';
+import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
+import { createSessionClientHost } from './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.
+ */
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory): {
+    client: SessionClient;
+    host: ReturnType<typeof createSessionClientHost>;
+};

package/dist/types/session/deviceDirectory.d.ts

@@ -0,0 +1,182 @@
+import type { AccountKind, DeviceContextRelationship, DeviceDirectory, DeviceDirectoryProfile } from '@oxy.so/contracts';
+/**
+ * Pure projections over the device directory (`GET /session/device/directory`,
+ * ADR 0002). No I/O — the caller holds the directory `SessionClient` fetched.
+ *
+ * These exist to say the one thing the flat `DeviceSessionState` projection
+ * structurally cannot: WHO an account is being reached through.
+ * `DeviceSessionState.accounts[]` has carried `operatedByUserId` on the wire all
+ * along and nothing in this SDK ever read it, so "signed in as The Oxy
+ * Collective" and "Nate operating The Oxy Collective" render identically today —
+ * two different audit actors, two different revocation paths, one row. The
+ * directory keeps the two facts apart, and so does everything below.
+ */
+/**
+ * The human whose authentication backs a context — the audit actor.
+ *
+ * Always a person (ADR 0001: a principal is never an organization, project,
+ * channel or bot) and the owner of the `authuser` slot. An organization in the
+ * switcher consumes no slot of its own; it is a SUBJECT under some principal.
+ */
+export interface DeviceContextActor {
+    /** Identifies the principal row — the id `POST /session/device/signout { principalId }` takes. */
+    principalId: string;
+    /** The person's own account id. */
+    userId: string;
+    /** Google-style signed-in-human slot, allocated per person. */
+    authuser: number;
+    profile: DeviceDirectoryProfile;
+}
+/** The account a context acts AS — what a profile header renders. */
+export interface DeviceContextSubject {
+    accountId: string;
+    kind: AccountKind;
+    relationship: DeviceContextRelationship;
+    profile: DeviceDirectoryProfile;
+    /**
+     * `false` for a context the principal may act as but has never activated here.
+     *
+     * NOT a synonym for activatable, in either direction — see
+     * {@link canActivateContext}.
+     */
+    onDevice: boolean;
+    /**
+     * Whether this context can be activated right now — the server's whole verdict,
+     * returned as a row rather than omitted so the UI can explain a row going away.
+     *
+     * It is STRICTER than the old `/switch` gate, and stricter than the name
+     * suggests: it is the live `account:act_as` check AND the PRINCIPAL's own
+     * personal session being live. Activation has no proof of who is acting once
+     * the human's own session is gone, so a dead principal makes every one of
+     * their contexts unavailable — the delegated ones whose own sessions are
+     * perfectly alive included.
+     */
+    available: boolean;
+    lastUsedAt: number | null;
+}
+/**
+ * One resolved `principal acting as account` pair — the globally switchable
+ * unit, with its two halves named.
+ */
+export interface DeviceContext {
+    /**
+     * The identifier `POST /session/device/activate` takes. Names the PAIR, never
+     * the account.
+     *
+     * NOT STABLE ACROSS A REMOVAL, and therefore never something to persist or to
+     * hold across a read. Removing a delegated context is not permanent while the
+     * membership lives: the server rematerializes the pair on the next directory
+     * read, as `onDevice: false` under a NEW id — and it does so WITHOUT bumping
+     * `revision`, so "the device has not changed" is not evidence the id has not.
+     * Re-resolve from the directory in hand every time, and read an id that no
+     * longer resolves as gone rather than as an error.
+     */
+    contextId: string;
+    actor: DeviceContextActor;
+    subject: DeviceContextSubject;
+    /**
+     * Whether the actor and the subject are different accounts — "Nate operating
+     * The Oxy Collective" rather than "Nate". Compared by id rather than read off
+     * `relationship`, so it stays true if the vocabulary ever grows a fourth term.
+     */
+    isDelegated: boolean;
+}
+/**
+ * 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.
+ */
+export declare function resolveDeviceContext(directory: DeviceDirectory | null, contextId: string): DeviceContext | null;
+/**
+ * One person on the device, with every account they can act as beneath them.
+ *
+ * This is the switcher's shape, and it is grouped rather than flat because the
+ * flat one cannot state the fact the whole model exists for: the same
+ * organization reachable through two people is TWO rows, under two different
+ * humans, and a list keyed by account can only ever show one of them.
+ */
+export interface DevicePrincipalGroup {
+    /** The id `POST /session/device/signout { principalId }` takes. */
+    principalId: string;
+    /** The person's own account id. */
+    userId: string;
+    /** Google-style signed-in-human slot. An organization consumes none. */
+    authuser: number;
+    profile: DeviceDirectoryProfile;
+    /**
+     * Every context this person can reach, in the server's order (their personal
+     * account first, then the accounts they act as, by account id). Not re-sorted
+     * here: the server's order is already total and revision-stable, and a second
+     * ordering rule on the client would be a second thing to keep in agreement.
+     */
+    contexts: DeviceContext[];
+    /** Whether the device's ACTIVE context belongs to this person. */
+    isActive: boolean;
+}
+/**
+ * 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.
+ */
+export declare function projectDevicePrincipals(directory: DeviceDirectory | null): DevicePrincipalGroup[];
+/**
+ * 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.
+ */
+export declare function resolveActiveContext(directory: DeviceDirectory | null): DeviceContext | null;
+/**
+ * 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.
+ */
+export declare function directoryDisplayName(profile: DeviceDirectoryProfile, locale?: string): string;
+/**
+ * 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.
+ */
+export declare function directoryHandle(profile: DeviceDirectoryProfile): string | null;
+/**
+ * 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.
+ */
+export declare function canActivateContext(context: {
+    available: boolean;
+}): boolean;

package/dist/types/session/deviceSwitcherRows.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { type DevicePrincipalGroup } from './deviceDirectory';
+/** One `principal acting as account` row. */
+export interface SwitcherContextRow {
+    /**
+     * The id `activateContext` / `signOutContext` take. Names the PAIR.
+     *
+     * Not stable across a removal, so it is read out of the directory in hand on
+     * every render and never held across one.
+     */
+    contextId: string;
+    accountId: string;
+    displayName: string;
+    /** The `@handle` secondary line, or `null` when the profile has no username. */
+    handle: string | null;
+    avatarUrl: string | undefined;
+    /**
+     * The SUBJECT account's own accent — a named Bloom preset, or `null` when it
+     * has none and the renderer should use the ambient theme accent.
+     *
+     * Forwarded verbatim, never resolved to a colour here: mapping a preset name
+     * to a hex is Bloom's job, and `@oxy.so/core` cannot import a UI package.
+     */
+    color: string | null;
+    /** Whether this pair is the device's active context. */
+    isActive: boolean;
+    /** Whether the actor and the subject are different accounts. */
+    isDelegated: boolean;
+    /**
+     * Whether the row may be pressed — the server's `available`, read and never
+     * recomputed. Composing it with `onDevice` is wrong in both directions (see
+     * `canActivateContext`), so this is one field forwarded, not a derivation.
+     */
+    canActivate: boolean;
+}
+/** One person on this device, with the accounts they can act as beneath them. */
+export interface SwitcherPrincipalRow {
+    /** The id `signOutPrincipal` takes. */
+    principalId: string;
+    displayName: string;
+    handle: string | null;
+    avatarUrl: string | undefined;
+    /** The PERSON's own accent, on the same terms as a context row's. */
+    color: string | null;
+    /** Whether the device's ACTIVE context belongs to this person. */
+    isActive: boolean;
+    contexts: SwitcherContextRow[];
+}
+/** Resolves an avatar file id to a thumbnail URL. Bind to `getFileDownloadUrl`. */
+export type ResolveAvatarUrl = (avatar: string | null | undefined) => string | undefined;
+/** The directory's people and their contexts, ready to render. */
+export declare function buildSwitcherRows(groups: DevicePrincipalGroup[], activeContextId: string | null, resolveAvatarUrl: ResolveAvatarUrl, locale?: string): SwitcherPrincipalRow[];
+/**
+ * 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 declare function showsPrincipalHeaders(rows: SwitcherPrincipalRow[]): boolean;

package/dist/types/session/identityPin.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 type { NativeKeyValueStorage } from './authStateStore';
+/**
+ * The persisted identity binding.
+ *
+ * `publicKey` is the device's PRIMARY identity public key (lower-case hex, as
+ * `KeyManager` stores it) — never the cross-app shared-slot key, which may hold
+ * a different identity. `accountId` is the account the server resolved for that
+ * key when the session was established.
+ */
+export interface IdentityPin {
+    publicKey: string;
+    accountId: string;
+}
+/**
+ * The storage seam for {@link IdentityPin}. Async throughout so one interface
+ * fits both synchronous web `localStorage` and asynchronous native
+ * SecureStore/AsyncStorage.
+ */
+export interface IdentityPinStore {
+    load(): Promise<IdentityPin | null>;
+    /**
+     * Persist the pin and report whether it durably landed.
+     *
+     * `true` means the value is retained consistent with this store's durability
+     * guarantee (a durable backing whose read-back matched, or a degraded/in-memory
+     * store that held it in memory). `false` means a DURABLE backing was expected
+     * but the write did not land — the in-memory mirror keeps this process pinned,
+     * but the next cold boot will have to re-establish the identity session (which
+     * rewrites the pin) instead of taking the fast pinned-mint lane.
+     */
+    save(pin: IdentityPin): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/**
+ * 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 declare const IDENTITY_PIN_STORAGE_KEY = "oxy.identity.pin.v1";
+/**
+ * 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 declare function identityPinMatches(pin: IdentityPin | null, localPublicKey: string | null): boolean;
+/**
+ * A process-lifetime, in-memory {@link IdentityPinStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store.
+ */
+export declare function createMemoryIdentityPinStore(): IdentityPinStore;
+/**
+ * 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 declare function createWebIdentityPinStore(): IdentityPinStore;
+/**
+ * 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 declare function createNativeIdentityPinStore(storage: NativeKeyValueStorage): IdentityPinStore;