@oxy.so/core 1.0.0

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

@@ -0,0 +1,105 @@
+/**
+ * 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 type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import type { SessionLoginResponse } from '../models/session';
+import { type AuthChallenge } from '../crypto/signatureService';
+import { type IdentityPin, type IdentityPinStore } from './identityPin';
+/** Per-call transport overrides forwarded to the challenge/verify round-trips. */
+export interface IdentityRequestOptions {
+    retry?: boolean;
+    timeout?: number;
+}
+/**
+ * Everything an identity-bound client needs to resolve and re-establish its
+ * session. `@oxy.so/services` builds one of these (platform-appropriate pin
+ * store) and passes it to the cold boot and the refresh handler.
+ */
+export interface IdentityBinding {
+    /** Where the `{publicKey, accountId}` pin is persisted. */
+    pinStore: IdentityPinStore;
+    /**
+     * Reads this device's PRIMARY identity public key. Defaults to
+     * `KeyManager.getPublicKey()`. NEVER the shared-slot key.
+     */
+    readPublicKey?: () => Promise<string | null>;
+    /**
+     * Signs a server challenge with the PRIMARY local private key. Defaults to
+     * `SignatureService.signChallenge`.
+     */
+    signChallenge?: (challenge: string) => Promise<AuthChallenge>;
+    /** Optional device labels forwarded to `verifyChallenge`. */
+    deviceName?: string;
+    deviceFingerprint?: string;
+}
+/** The result of a successful {@link establishIdentitySession}. */
+export interface EstablishedIdentitySession {
+    session: SessionLoginResponse;
+    /** The pin as written: the local key plus the account the server resolved for it. */
+    pin: IdentityPin;
+}
+/**
+ * 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 declare function resolveIdentityPin(binding: IdentityBinding): Promise<IdentityPin | 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 declare function establishIdentitySession(args: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    binding: IdentityBinding;
+    requestOptions?: IdentityRequestOptions;
+}): Promise<EstablishedIdentitySession | null>;

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

@@ -0,0 +1,74 @@
+import type { DeviceSessionState } from '@oxy.so/contracts';
+import type { ClientSession } from '../models/session';
+import type { User } from '../models/interfaces';
+/**
+ * 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 declare function boundAccountIdOf(state: DeviceSessionState | null, pinnedAccountId?: string | null): string | 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 declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>, pinnedAccountId?: string | null): ClientSession[];
+/**
+ * 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 declare function activeSessionIdOf(state: DeviceSessionState | null, pinnedAccountId?: string | null): string | 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 declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>, pinnedAccountId?: string | null): User | null;
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export declare function accountIdsOf(state: DeviceSessionState | null): string[];

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

@@ -0,0 +1,179 @@
+/**
+ * Unified token refresh — THE single access-token re-mint for web + native.
+ *
+ * The access token is short-lived; there is no refresh token. To keep a session
+ * alive past the access token's TTL the client re-mints via the zero-cookie
+ * device transport:
+ *
+ *  - `refreshPersistedSession` — arm 1 mints a fresh access token from the
+ *    persisted `deviceId` + `deviceSecret` (`POST /session/device/token`),
+ *    planting + persisting the rotated secret; arm 2 (native only) re-mints via
+ *    the shared-keychain identity when there is no usable secret. It is used BOTH
+ *    reactively (wrapped as the `AuthRefreshHandler` installed on `HttpService`)
+ *    AND proactively (the scheduler below calls it).
+ *  - `createAuthRefreshHandler` / `installAuthRefreshHandler` wire arm 1+2 into
+ *    `HttpService.setAuthRefreshHandler`, keeping that layer's single-flight
+ *    dedup + cooldown (this module does NOT reimplement them).
+ *  - `startTokenRefreshScheduler` — a proactive scheduler decoupled from any
+ *    React type: re-mints ~60s before `exp`, re-arms on token change + web
+ *    tab-focus, `.unref?.()`s its timer in Node.
+ *
+ * Framework-free; no module-level mutable state.
+ */
+import type { DeviceSessionState } from '@oxy.so/contracts';
+import type { OxyServices } from '../OxyServices';
+import type { AuthRefreshHandler } from '../HttpService';
+import type { AuthStateStore } from './authStateStore';
+import type { IdentityPin } from './identityPin';
+import { type IdentityBinding } from './identitySession';
+/**
+ * Lead time (ms) before access-token expiry at which the proactive scheduler
+ * re-mints. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
+ * (60s) so the scheduled re-mint and the request-time preflight use the same
+ * window — the scheduler just fires it during idle/background.
+ */
+export declare const TOKEN_REFRESH_LEAD_MS = 60000;
+export interface RefreshDeps {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    /**
+     * Whether to fall back to the native shared-keychain re-mint (arm 2) when the
+     * persisted secret is absent / rejected. Defaults to `isNative()` — web has no
+     * shared keychain. Exposed for tests. IGNORED when {@link identity} is set: an
+     * identity-bound client must never adopt the CROSS-APP shared slot, which may
+     * hold a different identity than this device's primary key.
+     */
+    allowSharedKeyFallback?: boolean;
+    /**
+     * Identity-bound (pinned) mode. When present, every re-mint targets the
+     * PINNED account — resolved fresh from the pin store on each call, since a
+     * re-established session can move it — instead of the device's active
+     * account, and arm 2 becomes the PRIMARY-key identity sign-in rather than the
+     * shared-keychain one.
+     */
+    identity?: IdentityBinding;
+}
+/**
+ * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
+ * the re-mint handler and the cold boot can react per the transport contract
+ * without re-classifying the raw error:
+ *  - `ok` — minted, persisted `nextDeviceSecret`, planted the token.
+ *  - `no-secret` — the store holds no `deviceId` + `deviceSecret` to mint from.
+ *  - `invalid-secret` — 401 `invalid_device_secret`: the presented secret
+ *    no longer matches the server's stored hash.
+ *  - `no-session` — 401 `no_active_session`: the device is known but has no live
+ *    session (authoritative signed-out).
+ *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
+ *    pinned account is not (or no longer) a live account of this device session.
+ *    The device secret is FINE — it is the identity binding that went stale, so
+ *    the caller must re-establish from the local key, never drop the credential.
+ *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
+ *  - `persist-failed` — the mint succeeded but `nextDeviceSecret` could NOT be
+ *    durably persisted. The token is deliberately NOT planted: advertising a
+ *    healthy session on a secret that will not survive a reload is exactly the
+ *    divergence that logs users out.
+ */
+export type DeviceSecretMintOutcome = {
+    status: 'ok';
+    token: string;
+    sessionId: string;
+    userId: string;
+    state: DeviceSessionState;
+} | {
+    status: 'no-secret';
+} | {
+    status: 'invalid-secret';
+} | {
+    status: 'no-session';
+} | {
+    status: 'account-not-on-device';
+} | {
+    status: 'transient';
+} | {
+    status: 'persist-failed';
+};
+/**
+ * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
+ * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ *
+ * Concurrent lanes (cold boot, the proactive scheduler, a request-time preflight,
+ * a 401 retry, the socket token transport, or a tab-focus reconcile) must not
+ * each persist a different view of the mint response. Routing EVERY lane through
+ * this one single-flight makes concurrent callers await the SAME in-flight mint
+ * and all receive its result, so the durable store converges on one credential.
+ *
+ * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
+ * the access token; a failed durable persist yields `persist-failed` WITHOUT
+ * planting. This function performs NO store mutation on failure — the caller
+ * applies the drop/clear policy (which differs web vs native) from the returned
+ * status.
+ *
+ * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
+ * `accountId` (so the server mints that account's token without touching
+ * `activeAccountId`), and the persisted `sessionId`/`userId` are resolved from
+ * the PINNED account entry — never from `state.activeAccountId`, whose drift is
+ * exactly what the pin exists to stop.
+ */
+export declare function refreshDeviceSecretArm(deps: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    /** The identity pin, when this client is identity-bound. */
+    pin?: IdentityPin | null;
+}): Promise<DeviceSecretMintOutcome>;
+/**
+ * Re-mint the persisted session and return the fresh access token, or `null`
+ * when no arm could produce one.
+ *
+ * Arm 1 (`POST /session/device/token`, via {@link refreshDeviceSecretArm}): mint
+ * from the persisted `deviceId` + `deviceSecret`. On a 401 the secret is diverged
+ * or the device has no live session: drop the secret so the mint lane stops (or
+ * clear the store on web, where there is no fallback), then fall to arm 2 on
+ * native. A transient error — or a durable-persist failure — leaves the store and
+ * returns `null` WITHOUT falling to shared-key (those are not bad-secret signals).
+ *
+ * Arm 2 (native shared-keychain): when the secret is absent or was just rejected,
+ * re-mint via `signInWithSharedIdentity` (which plants tokens). On success the
+ * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
+ * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
+ * in-session shared-key recovery must not leave the fast-lane credential empty.
+ *
+ * IDENTITY-BOUND clients (`deps.identity`) run a different arm 2: the
+ * shared-keychain lane is DISABLED (its cross-app slot may hold a different
+ * identity) and replaced by {@link establishIdentitySession}, which re-signs a
+ * challenge with the PRIMARY local key and rewrites the pin. Arm 1 is pinned.
+ */
+export declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
+/**
+ * Build the reactive `AuthRefreshHandler` (arm 1 + arm 2). Install it via
+ * {@link installAuthRefreshHandler} or directly on
+ * `oxy.httpService.setAuthRefreshHandler`. `HttpService` owns single-flight
+ * dedup + cooldown, so the timer, the request-time preflight, and a 401 all
+ * collapse to one network attempt.
+ */
+export declare function createAuthRefreshHandler(deps: RefreshDeps): AuthRefreshHandler;
+/**
+ * Install the unified refresh handler on the owner client's `HttpService`.
+ * Returns a disposer that removes it.
+ */
+export declare function installAuthRefreshHandler(deps: RefreshDeps): () => void;
+/** Handle returned by {@link startTokenRefreshScheduler}; `dispose()` tears it down. */
+export interface TokenRefreshSchedulerHandle {
+    dispose(): void;
+}
+/**
+ * Start the proactive re-mint scheduler against `oxy`.
+ *
+ * Schedules a single timer to fire {@link TOKEN_REFRESH_LEAD_MS} before the
+ * current access token's `exp`, calling
+ * `oxy.httpService.refreshAccessToken('preflight')` (which runs the installed
+ * handler; deduped + cooldown-guarded). After every attempt it reschedules
+ * from the possibly-rotated token. It also reschedules whenever the token
+ * changes (a sign-out that clears the token cancels the timer) and, on web
+ * tab-focus, re-mints immediately if already inside the lead window (a
+ * long-hidden tab throttles timers, so the token can be expired on return).
+ *
+ * No-ops cleanly when there is no token or an opaque/no-`exp` token — the
+ * reactive 401 path stays the only re-mint trigger in that case. The timer is
+ * `.unref?.()`-ed so it never keeps a Node/Jest event loop alive.
+ */
+export declare function startTokenRefreshScheduler(oxy: OxyServices): TokenRefreshSchedulerHandle;

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

@@ -0,0 +1,18 @@
+import type { OxyServices } from '../OxyServices';
+import type { DeviceCredential, SessionClientHost } from './SessionClient';
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` is host-agnostic: it only needs a REST + token surface.
+ * `OxyServices` already exposes all of that except `getCurrentAccountId`,
+ * which has no direct equivalent — the adapter holds a mutable ref set by
+ * the caller (`OxyContext` in `@oxy.so/services`) via `setCurrentAccountId`.
+ *
+ * Shared here (rather than duplicated per consumer) because it is entirely
+ * platform-agnostic: every method it calls exists identically on
+ * `OxyServices` regardless of host (web, Expo/RN, Node).
+ */
+export declare function createSessionClientHost(oxyServices: OxyServices): SessionClientHost & {
+    setCurrentAccountId(id: string | null): void;
+    setDeviceCredential(credential: DeviceCredential | null): void;
+};

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

@@ -0,0 +1,202 @@
+/**
+ * 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 `@oxy.so/services`. ESM-safe, no
+ * `require()`, no react/react-native/expo imports.
+ */
+import type { AuthStateStore, PersistedAuthState } from './authStateStore';
+/**
+ * The zero-cookie device credential, as shared between apps. Exactly the pair
+ * `POST /session/device/token` takes — nothing else travels through the shared
+ * slot: no access token, no account id, no user id, no identity key.
+ */
+export interface SharedDeviceCredential {
+    deviceId: string;
+    deviceSecret: string;
+}
+/**
+ * The outcome of reading the shared slot. FOUR states, and the distinction
+ * between the last two is load-bearing:
+ *
+ * - `present`     — a well-formed credential was read.
+ * - `absent`      — the read SUCCEEDED and the slot is empty. The only state that
+ *                   may authorise seeding the slot.
+ * - `unavailable` — the read failed (keychain locked, keystore unreadable, the
+ *                   bridge returned something unrecognisable). Authorises
+ *                   nothing: not adoption, and above all not a write.
+ * - `unsupported` — this build has no shared slot at all (web, or a native app
+ *                   without the module linked). Not an error; simply means the
+ *                   app keeps its own per-app credential.
+ */
+export type SharedDeviceCredentialRead = {
+    state: 'present';
+    credential: SharedDeviceCredential;
+} | {
+    state: 'absent';
+} | {
+    state: 'unavailable';
+    cause: unknown;
+} | {
+    state: 'unsupported';
+};
+/**
+ * The platform seam. `@oxy.so/services` implements this over the iOS Keychain
+ * Access Group (a dedicated `keychainService`) or the Android signature-protected
+ * `OxyDeviceSession` broker.
+ */
+export interface SharedDeviceCredentialStore {
+    /** Never throws — a failure is reported as `unavailable`, never as `absent`. */
+    read(): Promise<SharedDeviceCredentialRead>;
+    /**
+     * Publish the credential. Resolves `true` only when a read-back confirmed the
+     * exact bytes landed; `false` on any failure. Never throws.
+     */
+    publish(credential: SharedDeviceCredential): Promise<boolean>;
+    /** Drop this app's copy of the shared credential. Never throws. */
+    clear(): Promise<void>;
+}
+/** Why {@link decideSharedDeviceJoin} declined to adopt the shared credential. */
+export type SharedDeviceJoinSkipReason = 'shared-unsupported' | 'shared-unreadable' | 'shared-empty' | 'local-credential-present';
+/** What a booting app should do with the shared slot it just read. */
+export type SharedDeviceJoinDecision = {
+    action: 'adopt';
+    credential: SharedDeviceCredential;
+} | {
+    action: 'skip';
+    reason: SharedDeviceJoinSkipReason;
+};
+/** Why {@link decideSharedDevicePublish} declined to write the shared slot. */
+export type SharedDevicePublishSkipReason = 'shared-unsupported' | 'shared-unreadable' | 'already-current' | 'owned-by-another-device';
+/** What an app that just PROVED a credential should do with the shared slot. */
+export type SharedDevicePublishDecision = {
+    action: 'publish';
+} | {
+    action: 'skip';
+    reason: SharedDevicePublishSkipReason;
+};
+/** The usable `{deviceId, deviceSecret}` pair in a persisted state, or null. */
+export declare function readLocalDeviceCredential(state: PersistedAuthState | null): SharedDeviceCredential | null;
+/**
+ * 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 declare function normalizeSharedDeviceSessionRead(raw: unknown): SharedDeviceCredentialRead;
+/**
+ * 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 declare function decideSharedDeviceJoin(local: PersistedAuthState | null, shared: SharedDeviceCredentialRead): SharedDeviceJoinDecision;
+/**
+ * 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 declare function decideSharedDevicePublish(proven: SharedDeviceCredential, shared: SharedDeviceCredentialRead): SharedDevicePublishDecision;
+/** The result of {@link publishProvenDeviceCredential}, for logs and tests. */
+export type SharedDevicePublishOutcome = {
+    status: 'published';
+} | {
+    status: 'publish-failed';
+} | {
+    status: 'skipped';
+    reason: SharedDevicePublishSkipReason;
+};
+/**
+ * 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 declare function publishProvenDeviceCredential(deps: {
+    shared: SharedDeviceCredentialStore;
+    credential: SharedDeviceCredential;
+}): Promise<SharedDevicePublishOutcome>;
+/**
+ * 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 declare function createSharedMirroringAuthStateStore(deps: {
+    local: AuthStateStore;
+    shared: SharedDeviceCredentialStore;
+}): AuthStateStore;

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

@@ -0,0 +1,11 @@
+export interface MinimalSocket {
+    connected: boolean;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    /** Client→server emit (e.g. joining the `/auth-session` room for a QR flow). */
+    emit(event: string, ...args: unknown[]): void;
+    connect(): void;
+    disconnect(): void;
+}
+export type SocketIOFactory = (uri: string, opts?: Record<string, unknown>) => MinimalSocket;
+export declare function getSocketIO(): Promise<SocketIOFactory | null>;