@oxyhq/core 20.1.0 → 21.0.0

package/dist/types/boot/sessionColdBoot.d.ts

@@ -15,10 +15,17 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
- *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
- *      re-mint from THIS device's primary identity key.
- *   4. Signed out.
+ *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
+ *      of its own but a sibling official app already put one in the shared native
+ *      slot: adopt it and mint. This is how a newly installed official app joins
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
  *
  * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
  *   - `account` (default) — the device's ACTIVE account owns the session. Every
@@ -33,6 +40,7 @@
  */
 import { type ColdBootOutcome } from '../utils/coldBoot';
 import { type IdentityBinding } from '../session/identitySession';
+import { type SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
 /**
@@ -108,6 +116,18 @@ export interface RunSessionColdBootOptions {
      * `sessionMode: 'identity'`. Ignored in `'account'` mode.
      */
     identity?: IdentityBinding;
+    /**
+     * The cross-app native slot holding this device's shared DeviceSession
+     * credential, enabling the `shared-device-adopt` lane. Supplied by
+     * `@oxyhq/services` on native; absent on web, where each origin is its own
+     * device by design.
+     *
+     * IGNORED in `sessionMode: 'identity'`. The shared slot belongs to whichever
+     * principal signed in on this device; an identity-bound client must resolve
+     * its session from the local key alone, and adopting a device credential is
+     * exactly the drift that mode exists to prevent.
+     */
+    sharedDeviceCredential?: SharedDeviceCredentialStore;
 }
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as

package/dist/types/index.d.ts

@@ -25,7 +25,7 @@ export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval';
 export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery';
 export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRoute, } from './utils/commonsDelivery';
-export type { ServiceTokenResponse, OAuthUserInfoResponse } from './mixins/OxyServices.auth';
+export type { ServiceTokenResponse, OAuthUserInfoResponse, OAuthTokenExchangeResult, } from './mixins/OxyServices.auth';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
@@ -116,12 +116,17 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
-export { isSwitchTargetAccount, canSwitchIntoAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
-export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
+export { canActivateContext, directoryDisplayName, directoryHandle, projectDevicePrincipals, resolveActiveContext, resolveDeviceContext, } from './session/deviceDirectory';
+export type { DeviceContext, DeviceContextActor, DeviceContextSubject, DevicePrincipalGroup, } from './session/deviceDirectory';
+export { buildSwitcherRows, showsPrincipalHeaders } from './session/deviceSwitcherRows';
+export type { ResolveAvatarUrl, SwitcherContextRow, SwitcherPrincipalRow, } from './session/deviceSwitcherRows';
+export { isSwitchTargetAccount, canSwitchIntoAccount, } from './session/accountSwitchTargets';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
+export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './session/sharedDeviceCredential';
+export type { SharedDeviceCredential, SharedDeviceCredentialRead, SharedDeviceCredentialStore, SharedDeviceJoinDecision, SharedDeviceJoinSkipReason, SharedDevicePublishDecision, SharedDevicePublishOutcome, SharedDevicePublishSkipReason, } from './session/sharedDeviceCredential';
 export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './session/identityPin';
 export type { IdentityPin, IdentityPinStore } from './session/identityPin';
 export { resolveIdentityPin, establishIdentitySession, } from './session/identitySession';

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -4,7 +4,7 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { LoginResult, LoginSessionResult, CommonsDenyReason } from '@oxyhq/contracts';
+import type { LoginResult, CommonsDenyReason } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -39,6 +39,41 @@ export interface OAuthUserInfoResponse {
     name?: string;
     picture?: string;
 }
+/**
+ * The session an OAuth authorization-code exchange yields.
+ *
+ * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
+ * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
+ * requires `deviceId` because those lanes always join the origin's DeviceSession.
+ * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
+ * parties, whose grant is deliberately ISOLATED: an untrusted application must be
+ * able to receive a session carrying NO DeviceSession credential at all.
+ *
+ * Both device fields are therefore optional here, and a response omitting them is
+ * a well-formed device-less grant rather than a malformed payload. What that
+ * costs the session is spelled out on `exchangeOAuthCode` below.
+ */
+export interface OAuthTokenExchangeResult {
+    sessionId: string;
+    /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
+    expiresAt: string;
+    accessToken?: string;
+    /**
+     * The DeviceSession this grant joined, when the server issued one. ABSENT for
+     * an isolated third-party grant — never assume a string.
+     */
+    deviceId?: string;
+    /**
+     * The zero-cookie mint credential for {@link deviceId}. Present only alongside
+     * it; absent for an isolated third-party grant.
+     */
+    deviceSecret?: string;
+    user: {
+        id: string;
+        username?: string;
+        avatar?: string;
+    };
+}
 /**
  * How a "Sign in with Oxy" request finalizes once the approver authorizes it.
  *
@@ -793,13 +828,30 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * response this method used before were an Oxy invention no OAuth library
          * could interoperate with; the endpoint no longer accepts them. The method's
          * OWN signature is unchanged, so callers are unaffected.
+         *
+         * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+         * outcome, not an error. A third-party grant is meant to be isolated from the
+         * browser's shared DeviceSession, so the token endpoint must be free to return
+         * no device credential at all — the guard that used to require the pair made
+         * that omission unshippable, since it turned every third-party sign-in through
+         * the SDK into a silent `exchange-failed`.
+         *
+         * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+         * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+         * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+         * access token itself — nothing persists a restore credential, the cold boot's
+         * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+         * scheduler has nothing to re-mint from. When the token expires the session
+         * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+         * out, so the app can run the OAuth flow again. It never degrades into a
+         * session that looks alive and cannot refresh.
          */
         exchangeOAuthCode(params: {
             code: string;
             clientId: string;
             redirectUri: string;
             codeVerifier: string;
-        }): Promise<LoginSessionResult>;
+        }): Promise<OAuthTokenExchangeResult>;
         /**
          * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
          * The response is a flat JSON document — no `{ data }` wrapper.
@@ -850,7 +902,27 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         handleError(error: unknown): Error;
         healthCheck(): Promise<{
             status: string;
-            users?: number;
+            users
+            /**
+             * @internal Narrow an untrusted delivery-progress timestamp from the status
+             * response.
+             *
+             * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+             * and `null` for everything else — absent (an older API that has no delivery
+             * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+             * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+             * to the waiting UI is not.
+             */
+            ? /**
+             * @internal Narrow an untrusted delivery-progress timestamp from the status
+             * response.
+             *
+             * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+             * and `null` for everything else — absent (an older API that has no delivery
+             * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+             * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+             * to the waiting UI is not.
+             */: number;
             timestamp?: string;
             [key: string]: any;
         }>;

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

@@ -13,6 +13,17 @@ export interface ClientSession {
      * account-chooser ordering, not for any token-refresh mechanism.
      */
     authuser?: number;
+    /**
+     * The HUMAN operating this account, when it is a delegated session — the
+     * audit actor behind "The Oxy Collective". Absent when the session belongs to
+     * the account itself.
+     *
+     * The flat wire shape has carried it since the multi-account model shipped and
+     * nothing read it, so an operated org rendered exactly like a directly
+     * signed-in one. `SessionClient.getActiveContext()` is the richer answer
+     * (ADR 0002); this is the same fact on the compatibility lane.
+     */
+    operatedByUserId?: string;
 }
 export interface StorageKeys {
     sessions: string;

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

@@ -1,4 +1,5 @@
-import { type DeviceSessionState } from '@oxyhq/contracts';
+import { type DeviceDirectory, type DeviceSessionState } from '@oxyhq/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. */
@@ -84,11 +85,25 @@ export interface SessionClientOptions {
     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;
@@ -100,6 +115,21 @@ export declare class SessionClient {
     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
@@ -108,6 +138,14 @@ export declare class SessionClient {
      */
     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
@@ -143,13 +181,176 @@ export declare class SessionClient {
      * 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>;
+    /**
+     * 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