@oxy.so/core 1.0.0

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

@@ -0,0 +1,418 @@
+import { type DeviceDirectory, type DeviceSessionState } from '@oxy.so/contracts';
+import { type DeviceContext } from './deviceDirectory';
+import type { MinimalSocket, SocketIOFactory } from './socketLoader';
+export interface TokenTransport {
+    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
+    ensureActiveToken(state: DeviceSessionState): Promise<void>;
+}
+/**
+ * Where an applied device state came from, so consumers can decide how
+ * AUTHORITATIVE a zero-account ("signed out") verdict is:
+ *  - `request` — the response to a direct REST call this client made
+ *    (`bootstrap` / `switch` / `signOut` / `add`). A stable, server-authoritative
+ *    verdict: an empty state here reflects a real sign-out or revocation, so the
+ *    durable device credential MAY be erased.
+ *  - `push` — an out-of-band Socket.IO `session_state` broadcast. Potentially
+ *    transient (a reconnect race / another device's mutation), so an empty state
+ *    here must NOT erase THIS origin's durable device credential — only clear the
+ *    local UI session. A dead credential re-mints to `no_active_session` and
+ *    resolves signed-out cleanly on the next boot; a wrongly-erased one cannot be
+ *    recovered without a fresh sign-in.
+ */
+export type SessionStateOrigin = 'request' | 'push';
+export interface DeviceCredential {
+    deviceId: string;
+    deviceSecret: string;
+}
+export interface SessionClientHost {
+    makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: {
+        cache?: boolean;
+    }): Promise<T>;
+    getBaseURL(): string;
+    getAccessToken(): string | null;
+    /** Zero-cookie device credential for socket handshake when no bearer is planted yet. */
+    getDeviceCredential(): DeviceCredential | null;
+    onTokensChanged(listener: (token: string | null) => void): () => void;
+    setTokens(accessToken: string): void;
+    getCurrentAccountId(): string | null;
+}
+export interface SessionClientOptions {
+    transport?: TokenTransport;
+    /**
+     * Invoked when an APPLIED state has zero accounts — i.e. a device
+     * signout-all removed the last account from this device set. Providers use
+     * this to clear local session state and, for a `request`-origin verdict, the
+     * persisted {@link AuthStateStore} so a reload does not try to restore a
+     * session that no longer exists on the device.
+     *
+     * The {@link SessionStateOrigin} is passed so the consumer can gate the
+     * DESTRUCTIVE credential wipe: a `push`-origin empty state (a socket broadcast,
+     * possibly a transient reconnect artifact) must NOT erase the durable device
+     * credential — only a `request`-origin verdict (a direct REST sign-out /
+     * revocation) is authoritative enough for that.
+     *
+     * Only fires when a state is actually applied (revision advanced), never on
+     * a stale/rejected push. Exceptions thrown by the callback are isolated.
+     */
+    onUnauthenticated?: (origin: SessionStateOrigin) => void;
+    /**
+     * Statically-injected `socket.io-client` factory (its `io` export).
+     * `@oxy.so/services` lists `socket.io-client` as a real dependency and
+     * passes `io` in directly, so realtime session sync never
+     * depends on a runtime dynamic `import('socket.io-client')` of a bare
+     * specifier — which is bundler-fragile in Metro/Expo-web and Vite when
+     * `@oxy.so/core` is consumed as its published dist (the import resolves to
+     * nothing → `connectSocket` warns and falls back to REST-only). When this is
+     * provided, `connectSocket` uses it and never touches the lazy loader; when
+     * absent it falls back to `getSocketIO()`.
+     */
+    socketFactory?: SocketIOFactory;
+    /**
+     * The PINNED account id for an IDENTITY-BOUND client (the identity vault),
+     * or `null` for every ordinary account-mode client. Read as a function because
+     * the pin is resolved asynchronously at boot and can move when the identity
+     * session is re-established.
+     *
+     * While pinned this client tracks device state TRUTHFULLY — other apps'
+     * accounts and the device's real `activeAccountId` stay visible in `getState()`
+     * — but it NEVER re-binds its bearer to that active account: no `activeToken`
+     * is planted for a non-pinned account (from a sync response or a pushed
+     * `session_state`), the `TokenTransport` (whose entire job is converging on
+     * `activeAccountId`) is bypassed, and a push that switches the device does not
+     * trigger a token re-fetch. The pinned token's lifecycle belongs solely to the
+     * cold boot / re-mint lane, which mints it with an explicit `accountId`.
+     */
+    getPinnedAccountId?: () => string | null;
+}
+type StateListener = (state: DeviceSessionState | null) => void;
+type DirectoryListener = (directory: DeviceDirectory | null) => void;
+export declare class SessionClient {
+    protected readonly host: SessionClientHost;
+    protected readonly options: SessionClientOptions;
+    private state;
+    /**
+     * The device DIRECTORY (ADR 0002) — principals, the contexts each may act as,
+     * and which context is active. Held BESIDE `state` rather than replacing it:
+     * `state` is the flat compatibility projection every app renders until Phase 7
+     * moves it, and the two describe the same device at the same `revision`.
+     *
+     * `null` until something asks for it. A client that never calls
+     * {@link refreshDirectory} has no consumer for a directory and never pays for
+     * the round trip — which is also what keeps the whole account lane's request
+     * count unchanged.
+     */
+    private directory;
+    private readonly listeners;
+    private readonly directoryListeners;
+    protected socket: MinimalSocket | null;
+    private tokenUnsub;
+    private started;
+    /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
+    private channel;
+    /** App-facing subscriptions to named server-pushed socket events. */
+    private readonly serverEvents;
+    /** Event names already bound on the CURRENT socket instance. */
+    private readonly boundServerEvents;
+    constructor(host: SessionClientHost, options?: SessionClientOptions);
+    getState(): DeviceSessionState | null;
+    /**
+     * The device directory, or `null` when this client has never read one.
+     * Populated by {@link refreshDirectory} / {@link activateContext} and kept
+     * fresh from there on.
+     */
+    getDirectory(): DeviceDirectory | null;
+    /**
+     * The active `principal acting as account` pair, with the actor and the
+     * subject kept apart. `null` when no directory has been read, or when the
+     * device genuinely has no active context.
+     *
+     * This is the answer `getState()` cannot give: `activeAccountId` names the
+     * subject and says nothing about whose authentication is behind it.
+     */
+    getActiveContext(): DeviceContext | null;
+    /**
+     * The account this client's bearer is pinned to, or `null` when it follows the
+     * device's active account (the default). Resolvers are expected to be a plain
+     * synchronous read of already-resolved state (see
+     * {@link SessionClientOptions.getPinnedAccountId}).
+     */
+    private pinnedAccountId;
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Subscribe to the directory half. Fires from the SAME {@link notify} as
+     * {@link subscribe}, so the flat state and the directory are never published
+     * at two different points of the ordering sequence — a directory subscriber
+     * and a state subscriber woken by one transition always see the same device
+     * revision under the same bearer.
+     */
+    subscribeDirectory(listener: DirectoryListener): () => void;
+    /**
+     * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+     * Listeners survive reconnects and socket re-creation; the returned function
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event: string, listener: (payload: unknown) => void): () => void;
+    private bindServerEvent;
+    protected notify(): void;
+    /**
+     * Validate + last-writer-wins by revision. Returns true if applied.
+     *
+     * `activeToken` (sync path only) is the server-issued access token for
+     * `raw.activeAccountId`. When present and the state is applied, it is planted
+     * BEFORE any subscriber is notified so the bearer already belongs to the new
+     * active account — the local switch/bootstrap path then needs no redundant
+     * device-secret mint. Push-origin applies carry no token and rely on the
+     * mint-before-notify gate below.
+     *
+     * ORDERING INVARIANT: a subscriber must NEVER observe a newly-active account
+     * while the planted bearer still identifies the PREVIOUS one — otherwise a
+     * `useCurrentUser`-style refetch fires under the wrong account's token (the
+     * account-switch 404 race). So when a transport is available and the planted
+     * bearer does not already belong to `next.activeAccountId`, minting is awaited
+     * BEFORE `notify()`. This covers EVERY notify source (a switch push, a
+     * cross-device push, a cold mint), not just the initial "no bearer yet" case.
+     */
+    protected applyState(raw: unknown, origin?: SessionStateOrigin, activeToken?: string): boolean;
+    /**
+     * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
+     * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push
+     * followed by this same `GET /state` fetch returns the SAME revision (applyState no-ops), but
+     * the token still needs to be planted. The account-match guard rejects a stale response for an
+     * account that is no longer active.
+     */
+    private applySync;
+    /**
+     * The apply + token-plant half of {@link applySync}, on an ALREADY-VALIDATED
+     * sync. Split out so the context-aware removal lane — whose response is a
+     * different wire shape and therefore a different parse — reuses this ordering
+     * verbatim instead of re-deriving it. Two implementations of
+     * "plant before notify" is two chances to get it wrong once.
+     *
+     * Returns whether `applyState` applied, so a caller holding a second half
+     * (the directory) can decide whether anything still needs publishing.
+     */
+    private commitSync;
+    /**
+     * Validate + last-writer-wins, `deviceId`-SCOPED exactly as {@link applyState}
+     * is for the flat half: a directory belonging to a DIFFERENT device resets the
+     * baseline and is accepted at any revision, so a freshly-converged device
+     * cannot lose to a retired device's higher number.
+     *
+     * The comparison itself is deliberately WEAKER than the flat state's. There it
+     * is `revision <= current` — correct, because a `DeviceSessionState` arrives
+     * out of band over a socket, so a straggler can genuinely land after a newer
+     * one. A directory only ever arrives as the response to a request THIS client
+     * just made, so the newest response is the freshest answer and only a strictly
+     * LOWER revision can be a straggler (two GETs racing).
+     *
+     * Equal-revision reads are not redundant, and rejecting them was a bug: the
+     * directory includes rows projected from the account GRAPH, and the server
+     * materializes a context for every account a principal may act as WITHOUT
+     * bumping `revision` — deliberately, since `revision` tracks what the device
+     * holds and must never advance on a read. So a newly-granted `account:act_as`,
+     * and a removed-then-rematerialized context under its NEW id, both appear at
+     * an unchanged revision. Under `<=` neither would ever be seen until some
+     * unrelated device mutation happened to move the number.
+     *
+     * Notifies nothing. Every caller decides where in its own ordering sequence
+     * the publish belongs.
+     */
+    private applyDirectory;
+    /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
+    private fetchDirectory;
+    /**
+     * Re-read the directory when the flat state has moved past it, returning the
+     * in-flight work so the caller can hold its notify until both halves describe
+     * the same revision.
+     *
+     * `null` — meaning "nothing to settle, stay synchronous" — when this client
+     * holds no directory (nobody reads one), when the directory is already at or
+     * ahead of the state, or when there is no bearer to make the call with.
+     * Never rejects: a failed refresh leaves the previous directory in place and
+     * the next transition tries again; it must not swallow the flat state's
+     * notify.
+     */
+    private settleDirectory;
+    /**
+     * The highest device revision this client currently knows for `deviceId`,
+     * across BOTH halves, or `null` when it knows nothing about that device.
+     *
+     * Used to read the server's `changed` flag, which
+     * `POST /session/device/activate` deliberately does not carry: the revision
+     * already says whether the device moved, and a second field saying the same
+     * thing is a second field that can disagree with the first.
+     */
+    private knownRevisionFor;
+    /**
+     * Plant the bearer `POST /session/device/activate` returned for the newly
+     * active context, under the same guards {@link applyState} applies to a
+     * sync-supplied `activeToken`: never for a null active context, never a
+     * foreign account's token while pinned, and never a redundant re-plant of the
+     * token already held.
+     *
+     * `activeToken: null` is not an error — it is an identity-pinned client, or a
+     * caller whose application is not entitled to a bearer for the new context.
+     */
+    private plantActiveContextToken;
+    /**
+     * Bring the FLAT projection back in step after a context activation.
+     *
+     * The activation response answers with the directory and a bearer and
+     * deliberately not with `DeviceSessionState` (ADR 0002) — but every app that
+     * has not moved to the directory still renders from `getState()`, and leaving
+     * it a revision behind would show the PREVIOUS subject under the new
+     * subject's bearer. So it is settled BEFORE the notify, not after.
+     *
+     * This is also what converges the bearer when the activation returned no
+     * token: `GET /session/device/state` mints one for the active account, and
+     * `applyState`'s own mint-before-notify gate holds its notify until it lands.
+     *
+     * Non-fatal on failure — the directory is applied and (usually) the bearer is
+     * planted; the socket push or the next bootstrap catches the flat half up. A
+     * network blip must not turn a completed activation into a thrown error.
+     */
+    private reconcileFlatState;
+    bootstrap(): Promise<void>;
+    /**
+     * Adopt server-authoritative state already returned by another session
+     * endpoint. This avoids immediately re-reading `/session/device/state` after
+     * a successful device-token mint while preserving the same validation,
+     * revision ordering and notification path as `bootstrap()`.
+     */
+    adoptState(state: DeviceSessionState): boolean;
+    /**
+     * Read `GET /session/device/directory` and publish it.
+     *
+     * Calling this is what opts a client into the directory: from here on every
+     * applied device state re-reads it (see {@link settleDirectory}), so the two
+     * halves stay at one revision without the caller polling.
+     */
+    refreshDirectory(): Promise<void>;
+    /**
+     * `POST /session/device/activate` — make one `principal acting as account`
+     * context active (ADR 0002).
+     *
+     * The body is `{ contextId }` and nothing else: an `accountId` cannot name
+     * what to activate on a device where two people can both reach the same
+     * organization, and the server refuses a body carrying one rather than
+     * guessing inside an authorization path.
+     *
+     * The sequence is the ADR's ordering invariant, in order — commit the bearer
+     * for the new context, publish the new snapshot, notify — with the flat
+     * projection reconciled in the middle so no consumer can observe the two
+     * halves disagreeing.
+     *
+     * An IDEMPOTENT activation (the target was already active) moves no revision,
+     * so it reconciles nothing and wakes no sibling tab, mirroring the server's
+     * "bumps nothing and broadcasts nothing". `switchAccount` remains the
+     * compatibility path for callers still keyed on account ids.
+     */
+    activateContext(contextId: string): Promise<void>;
+    switchAccount(accountId: string): Promise<void>;
+    /**
+     * The FLAT removal meanings, unchanged: `{ accountId }` removes that account
+     * however it is reached — plus the operator cascade — and `{ all: true }`
+     * removes the whole device including its credentials.
+     *
+     * `{ accountId }` is deliberately still account-grained. On a device holding
+     * two people it removes BOTH of their routes to that account, which is the
+     * right meaning for "sign this account out of this device" and the wrong one
+     * for "this person is done here" — see {@link signOutContext} and
+     * {@link signOutPrincipal} for the two that can tell those apart.
+     */
+    signOut(target: {
+        accountId: string;
+    } | {
+        all: true;
+    }): Promise<void>;
+    /**
+     * Remove ONE `principal → account` pair, and only that pair.
+     *
+     * Never the account across the device: the same organization reached through
+     * a second person is a different session, a different audit actor and a
+     * different revocation path, and it stays. That distinction is unreachable
+     * through {@link signOut}, whose `accountId` cannot name which route to drop.
+     *
+     * Removal is not permanent while the membership lives — the server offers the
+     * pair again on the next directory read, as `onDevice: false` under a NEW id.
+     */
+    signOutContext(contextId: string): Promise<void>;
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
+     */
+    signOutPrincipal(principalId: string): Promise<void>;
+    /**
+     * The shared apply path for both context-aware removals.
+     *
+     * The response is `{directory, state, activeToken}` — its own contract, never
+     * `deviceSessionSyncSchema`, which would strip the directory silently. Both
+     * halves move in one server transition (a removal elects a replacement active
+     * context), so both are applied before anything is published: the directory
+     * first, so the flat apply's own `settleDirectory` sees a current directory
+     * and does not issue a redundant `GET /session/device/directory` for the
+     * revision already in hand.
+     *
+     * Token-before-notify is `commitSync`'s, reused verbatim rather than
+     * re-derived — including the equal-revision plant when a socket push already
+     * applied this revision.
+     */
+    private removeFromDevice;
+    addCurrentAccount(): Promise<void>;
+    /**
+     * Register the just-signed-in account into the device set AND make it the
+     * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+     *
+     * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+     * (a new account does NOT steal focus from an already-active one), which is
+     * correct for a background/silent add but wrong right after a deliberate
+     * sign-in. This adds, then switches to the target so the UI lands on the
+     * account the user just authenticated.
+     *
+     * An identity-bound (pinned) client only ADDS: its own session is minted for
+     * the pinned account explicitly, so switching the device would gratuitously
+     * re-elect the active account under every OTHER app on this device — a
+     * mutation a pinned client must never make.
+     *
+     * @param accountId - The signed-in account id (e.g. `session.user.id`). When
+     *   omitted, falls back to the host's current-account ref. If neither
+     *   resolves, the add still applies and no switch is performed.
+     */
+    registerAndActivate(accountId?: string): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    private connectSocket;
+    /**
+     * Handle the token-free `session_accounts_changed` signal (room `user:<userId>`).
+     *
+     * Unlike `session_state` (device-scoped, carries the new state to APPLY), this
+     * reaches ALL of a user's connected sockets across their devices/origins and is
+     * a pure SIGNAL: it carries no token, no secret, and no account bodies. The only
+     * trustworthy bit is "something changed for this user", so — matching the
+     * `session_state` contract's guidance — we re-fetch our OWN authoritative device
+     * state (`bootstrap` → `GET /session/device/state`) and let the existing
+     * `applyState` revision guard reconcile it. We never trust any field on the event
+     * beyond routing it to the current user.
+     *
+     * The refetch is a private (bearer) call: the socket only joins `user:<userId>`
+     * when authenticated, so a signed-out client never receives this — but we guard
+     * the bearer anyway so a race at sign-out can't 401.
+     */
+    private onSessionAccountsChanged;
+    /**
+     * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
+     * commits an account switch / sign-out posts a wake ping; on receipt an
+     * authenticated tab re-syncs its device state — instant + network-free for the
+     * common "two tabs of the same origin" case, with no state (and no tokens)
+     * ever crossing the channel. No-op on native (no BroadcastChannel).
+     */
+    private openBroadcastChannel;
+    /**
+     * Wake same-origin sibling tabs after a locally-initiated session mutation.
+     * Opens the channel lazily: a sign-in registers the account (`addCurrentAccount`
+     * / `switchAccount`) BEFORE `start()` runs, so the ping must not depend on
+     * `start()` having opened the channel first.
+     */
+    private postCommitPing;
+}
+export {};

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

@@ -0,0 +1,40 @@
+/**
+ * The two authorization facts a service needs before it acts as a managed
+ * account: whether the caller has standing in the account, and whether that
+ * standing includes `account:act_as` for a delegation-eligible subject.
+ *
+ * This is deliberately separate from `accountSwitchTargets.ts`. A human account
+ * switcher and a backend delegation ask different questions: `bot` is a valid
+ * delegation subject, but it is never a seat a person may switch into. Sharing
+ * one predicate between those paths is what previously put bot sessions on
+ * human devices.
+ *
+ * Pure and I/O-free. Consumers pass the `AccountNode` returned by `getAccount`
+ * (or the structural subset below), so the SDK and every agent runtime read the
+ * API's already-resolved relationship and effective permissions identically.
+ */
+import type { AccountKind, AccountMember, AccountRelationship } from "../mixins/OxyServices.accounts";
+export interface AccountDelegationAccess {
+    /** The caller owns the account or has a live membership in it. */
+    readonly hasStanding: boolean;
+    /** The account may be delegated and the caller holds effective `account:act_as`. */
+    readonly canActAs: boolean;
+}
+export type AccountDelegationNode = {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+};
+/**
+ * Resolve standing and delegated act-as authority from one account-graph node.
+ *
+ * `hasStanding` is intentionally weaker than `canActAs`: an active viewer may
+ * use a private agent shared through its bot account without gaining permission
+ * to edit the agent or mint a session as it. A non-active membership grants
+ * neither fact even if a stale projection still carries permissions.
+ *
+ * Owners normally have no membership blob because ownership is implicit. When
+ * the API does return effective permissions for an owner, those permissions are
+ * authoritative: an explicit `account:act_as` revoke must remain a revoke.
+ */
+export declare function resolveAccountDelegationAccess(node: AccountDelegationNode): AccountDelegationAccess;