@oxyhq/core 20.0.0 → 21.0.0

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

@@ -0,0 +1,182 @@
+import type { AccountKind, DeviceContextRelationship, DeviceDirectory, DeviceDirectoryProfile } from '@oxyhq/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 `@oxyhq/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/projectSessionState.d.ts

@@ -1,6 +1,35 @@
 import type { DeviceSessionState } from '@oxyhq/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 `@oxyhq/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`.
  *

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 `@oxyhq/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. `@oxyhq/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "20.0.0",
+  "version": "21.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -116,7 +116,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.25.0",
+    "@oxyhq/contracts": "^0.26.0",
     "@oxyhq/protocol": "^0.2.0",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",
@@ -127,7 +127,7 @@
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
     "socket.io-client": "^4.8.1",
-    "tldts": "^7.4.8",
+    "tldts": "^7.4.10",
     "zod": "^3.25.64"
   },
   "peerDependencies": {