@oxyhq/core 9.1.0 → 9.2.1

package/dist/types/boot/{coldBootV2.d.ts → sessionColdBoot.d.ts}

@@ -1,5 +1,5 @@
 /**
- * coldBootV2 — one device-first cold boot for every consumer.
+ * Device-first session cold boot for every consumer.
  *
  * On a fresh page load / app launch this resolves the device's session in a
  * deterministic order, built on the pure `runColdBoot` primitive. It NEVER

package/dist/types/index.d.ts

@@ -34,7 +34,8 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
-export type { AccountKind, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, } from './mixins/OxyServices.identity';
@@ -83,10 +84,13 @@ export { registrableApex } from './utils/registrableApex';
 export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, } from './utils/oauthPkce';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
+export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
+export type { SyncHubAfterSignInOptions } from './session/hubSync';
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
 export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
@@ -99,8 +103,8 @@ export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthSt
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
-export { runSessionColdBoot } from './boot/coldBootV2';
-export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/coldBootV2';
+export { runSessionColdBoot } from './boot/sessionColdBoot';
+export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

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

@@ -33,6 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
+import type { OrganizationCategory } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
@@ -42,6 +43,9 @@ import type { OxyServicesBase } from '../OxyServices.base';
  * and have no direct login.
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot';
+/** Real-estate / team taxonomy for `kind: 'organization'` accounts. */
+export type { OrganizationCategory } from '@oxyhq/contracts';
+export { ORGANIZATION_CATEGORIES } from '@oxyhq/contracts';
 /**
  * The calling user's relationship to an account node, as resolved by the API:
  * - `self` — the caller's own personal (root) account.
@@ -143,6 +147,8 @@ export interface CreateAccountInput {
     };
     bio?: string;
     avatar?: string;
+    /** Meaningful only when `kind` is `organization`. */
+    organizationCategory?: OrganizationCategory;
 }
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
@@ -153,6 +159,8 @@ export interface UpdateAccountInput {
     };
     bio?: string | null;
     avatar?: string | null;
+    /** Clears the category when `null`; only valid on `kind: 'organization'`. */
+    organizationCategory?: OrganizationCategory | null;
 }
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */
 export interface InviteAccountMemberInput {

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

@@ -319,6 +319,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             deviceId: string;
             expiresAt: string;
             user: User;
+            deviceSecret?: string;
         }>;
         /**
          * MECHANISM A — same-device shared-keychain SSO.
@@ -477,6 +478,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         passwordSignIn(identifier: string, password: string, options?: {
             deviceName?: string;
             deviceFingerprint?: string;
+            deviceId?: string;
         }): Promise<LoginResult>;
         /**
          * Complete a 2FA-gated sign-in started by {@link passwordSignIn}. Presents
@@ -490,6 +492,19 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             token?: string;
             backupCode?: string;
             deviceName?: string;
+            deviceId?: string;
+        }): Promise<LoginSessionResult>;
+        /**
+         * Exchange an OAuth authorization code (returned to the RP redirect URI
+         * after password sign-in at auth.oxy.so) for a device-first session.
+         * Public first-party clients use PKCE (`codeVerifier`); the access token is
+         * planted immediately on success.
+         */
+        exchangeOAuthCode(params: {
+            code: string;
+            clientId: string;
+            redirectUri: string;
+            codeVerifier: string;
         }): Promise<LoginSessionResult>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;

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

@@ -2,7 +2,7 @@
  * Device-first token mint mixin.
  *
  * The client half of the zero-cookie device transport: the single network call
- * the cold boot (`coldBootV2`) and the unified re-mint handler (`refresh.ts`)
+ * the cold boot (`sessionColdBoot`) and the unified re-mint handler (`refresh.ts`)
  * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
  * token. The response is validated against the `@oxyhq/contracts`
  * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
+import { type DeviceTokenMintResponse, type DeviceHubTicketIssueResponse, type DeviceHubTicketRedeemResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -33,6 +33,10 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
         mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;
+        /** Mint a one-time hub sync ticket (bearer required). */
+        issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse>;
+        /** Redeem a hub sync ticket for a fresh device secret (public). */
+        redeemHubTicket(ticket: string, returnOrigin: string): Promise<DeviceHubTicketRedeemResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -1,4 +1,4 @@
-import type { UserNameResponse } from '@oxyhq/contracts';
+import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -129,6 +129,8 @@ export interface User {
     };
     isManagedAccount?: boolean;
     managedBy?: string;
+    /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
+    organizationCategory?: OrganizationCategory;
     notificationPreferences?: NotificationPreferences;
     userPreferences?: UserPreferences;
     [key: string]: unknown;

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

@@ -31,4 +31,10 @@ export interface SessionLoginResponse {
     user: MinimalUserData;
     /** JWT access token for API authentication */
     accessToken?: string;
+    /**
+     * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+     * first-party alongside `deviceId` so cold boot can re-mint via
+     * `POST /session/device/token`.
+     */
+    deviceSecret?: string;
 }

package/dist/types/server/index.d.ts

@@ -24,3 +24,4 @@ export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
 export { registrableApex } from '../utils/registrableApex';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins';

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

@@ -4,12 +4,18 @@ 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>;
 }
+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;

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

@@ -97,6 +97,12 @@ export interface AccountDialogControllerOptions {
     onSignedIn?: (user: MinimalUserData) => void;
     /** Central IdP apex for `openPasswordAtOxyAuth` (defaults to `CENTRAL_IDP_APEX`). */
     idpApex?: string;
+    /**
+     * Registered OAuth redirect URI for this RP (exact match against
+     * `Application.redirectUris`). When set, wins over `returnUrl` /
+     * `location.origin` normalization in {@link openPasswordAtOxyAuth}.
+     */
+    authRedirectUri?: string | null;
     /** QR device-flow poll interval in ms (default 3000). */
     pollIntervalMs?: number;
     /**
@@ -115,6 +121,7 @@ export declare class AccountDialogController {
     private readonly commitSession?;
     private readonly onSignedIn?;
     private readonly idpApex;
+    private readonly authRedirectUri;
     private readonly pollIntervalMs;
     private readonly openUrl?;
     private readonly listeners;
@@ -244,7 +251,8 @@ export declare class AccountDialogController {
     openPasswordAtOxyAuth(params?: {
         returnUrl?: string;
         state?: string;
-    }): string;
+        redirectUri?: string;
+    }): Promise<string>;
     private scheduleNextPoll;
     private pollOnce;
     private claimAndComplete;

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

@@ -5,7 +5,7 @@
  * a reload restores the session locally without a redirect: `deviceId` +
  * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
  * This module is the storage seam: a tiny `load / save / clear` interface plus
- * platform factories, so the cold boot (`coldBootV2`) and the unified re-mint
+ * platform factories, so the cold boot (`sessionColdBoot`) and the unified re-mint
  * handler (`refresh.ts`) never touch a platform storage API directly.
  *
  * Platform-agnostic — the native factory takes an INJECTED key/value store

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

@@ -0,0 +1,20 @@
+/**
+ * Post-sign-in hub sync — plant device credentials on auth.oxy.so via a
+ * one-time server ticket (no secrets in URL fragments).
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+export interface SyncHubAfterSignInOptions {
+    /** Skip sync when false (OxyProvider hubSync prop). @default true */
+    enabled?: boolean;
+}
+/**
+ * After a successful sign-in on an official web app, mint a hub ticket and
+ * redirect to auth.oxy.so/sync so the IdP hub can redeem it and persist the
+ * shared device credential for silent OAuth restore on other origins.
+ *
+ * No-op on native, non-official origins, and when already on the IdP hub.
+ */
+export declare function syncHubAfterSignIn(oxy: Pick<OxyServices, 'issueHubTicket'>, opts?: SyncHubAfterSignInOptions): Promise<boolean>;
+/** Redeem a hub ticket on auth.oxy.so and persist credentials locally. */
+export declare function redeemHubTicketOnHub(oxy: Pick<OxyServices, 'redeemHubTicket'>, store: AuthStateStore, ticket: string): Promise<boolean>;

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

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import type { SessionClientHost } from './SessionClient';
+import type { DeviceCredential, SessionClientHost } from './SessionClient';
 /**
  * Thin `SessionClientHost` adapter over an `OxyServices` instance.
  *
@@ -14,4 +14,5 @@ import type { SessionClientHost } from './SessionClient';
  */
 export declare function createSessionClientHost(oxyServices: OxyServices): SessionClientHost & {
     setCurrentAccountId(id: string | null): void;
+    setDeviceCredential(credential: DeviceCredential | null): void;
 };

package/dist/types/utils/coldBoot.d.ts

@@ -16,7 +16,7 @@
  *     web bundle — the reason any run-once guard for a step must live in the
  *     calling consumer, never in a core module-level singleton).
  *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
- *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
  *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
@@ -94,7 +94,7 @@ export interface RunColdBootOptions<S> {
      * fails to settle before the deadline, the runner abandons the await for that
      * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
      * each now racing against an already-expired deadline. This is deliberate:
-     * the runner keeps iterating so the TERMINAL step (e.g. `coldBootV2`'s
+     * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
      * `bootstrap-hop`, whose `run()` performs its navigation side effect
      * synchronously before its first `await`) still gets to fire. A step that
      * has nothing to contribute after the deadline simply doesn't settle and is

package/dist/types/utils/oauthPkce.d.ts

@@ -42,6 +42,11 @@ export interface BuildOAuthAuthorizeUrlParams {
     state: string;
     /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
     codeChallenge: string;
+    /**
+     * OAuth `prompt` parameter. Use `none` for silent cross-origin session restore
+     * (no UI when the IdP hub already has a session + grant).
+     */
+    prompt?: 'none' | 'login' | 'consent';
 }
 /**
  * Compute the PKCE S256 `code_challenge` for a given verifier:
@@ -72,3 +77,25 @@ export declare function generateOAuthState(): Promise<string>;
  * All values are percent-encoded by `URL.searchParams`.
  */
 export declare function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): string;
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
+/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
+export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
+/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
+export declare const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = "oxy.cross_origin_restore_attempted";
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ */
+export declare function normalizeOAuthRedirectUri(input: string): string;
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export declare function persistOAuthHandshake(state: string, codeVerifier: string): boolean;
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export declare function readOAuthHandshake(): {
+    state: string;
+    codeVerifier: string;
+} | null;
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export declare function clearOAuthHandshake(): void;

package/dist/types/utils/officialOrigins.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Official first-party web origin allowlist — shared by hub-ticket issuance,
+ * OAuth redirect validation, and cross-origin session restore.
+ */
+export declare function buildIdpHubOrigin(): string;
+/** Whether the current web origin is the central IdP hub (`auth.oxy.so`). */
+export declare function isIdpHubOrigin(): boolean;
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+export declare function isOfficialWebOrigin(origin: string): boolean;
+/** Normalize and validate a return URL against official origins. Returns origin only. */
+export declare function normalizeOfficialReturnOrigin(raw: string): string | null;
+/** Validate a hub-sync return URL; returns the full normalized URL string. */
+export declare function parseHubSyncReturnUrl(raw: string | null): string | null;
+/** Build auth.oxy.so/sync redirect URL with a one-time hub ticket. */
+export declare function buildHubSyncUrl(ticket: string, returnUrl?: string): string;
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export declare const isAllowedDeviceJoinOrigin: typeof isOfficialWebOrigin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.13.0",
+    "@oxyhq/contracts": "^0.13.1",
     "@oxyhq/protocol": "^0.1.3",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/boot/__tests__/{coldBootV2.test.ts → sessionColdBoot.test.ts}

@@ -9,7 +9,7 @@
 import type { OxyServices } from '../../OxyServices';
 import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
-import { runSessionColdBoot } from '../coldBootV2';
+import { runSessionColdBoot } from '../sessionColdBoot';
 import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
 
 interface OxyOverrides {
@@ -258,6 +258,26 @@ describe('runSessionColdBoot — shared-key-signin (native)', () => {
     );
   });
 
+  it('persists deviceSecret from shared-key verifyChallenge for the next mint lane', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => ({
+      ...sharedSession,
+      deviceSecret: 'shared-mint-secret',
+    }));
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    const persisted = await store.load();
+    expect(persisted).toMatchObject({
+      sessionId: 'sess-shared',
+      userId: 'user-shared',
+      deviceId: 'dev-1',
+      deviceSecret: 'shared-mint-secret',
+      accessToken: 'access-shared',
+    });
+  });
+
   it('does NOT run the shared-key lane on web', async () => {
     const store = createMemoryAuthStateStore();
     const signInWithSharedIdentity = jest.fn(async () => sharedSession);

package/src/boot/{coldBootV2.ts → sessionColdBoot.ts}

@@ -1,5 +1,5 @@
 /**
- * coldBootV2 — one device-first cold boot for every consumer.
+ * Device-first session cold boot for every consumer.
  *
  * On a fresh page load / app launch this resolves the device's session in a
  * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
@@ -139,7 +139,7 @@ export async function runSessionColdBoot(
         // Transient (network / 5xx): keep the secret; a later attempt can succeed.
         logger.debug(
           'device-secret mint failed (transient) — keeping secret',
-          { component: 'coldBootV2', method: 'device-secret-mint' },
+          { component: 'sessionColdBoot', method: 'device-secret-mint' },
           error,
         );
         return { kind: 'skip' };
@@ -156,6 +156,19 @@ export async function runSessionColdBoot(
       if (!session?.accessToken) {
         return { kind: 'skip' };
       }
+      // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+      // boot can use the faster device-secret-mint lane (sockets + tab-focus
+      // re-mint depend on the credential being in the store).
+      if (session.deviceId && session.deviceSecret) {
+        await store.save({
+          sessionId: session.sessionId,
+          userId: session.user.id,
+          deviceId: session.deviceId,
+          deviceSecret: session.deviceSecret,
+          accessToken: session.accessToken,
+          expiresAt: session.expiresAt,
+        });
+      }
       return {
         kind: 'session',
         session: {

package/src/index.ts

@@ -86,6 +86,7 @@ export type {
 // ---------------------------------------------------------------------------
 export type {
     AccountKind,
+    OrganizationCategory,
     AccountRelationship,
     AccountRole,
     AccountMemberStatus,
@@ -127,6 +128,8 @@ export type {
     ApplicationUsageStats,
 } from './mixins/OxyServices.accounts';
 
+export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
+
 // ---------------------------------------------------------------------------
 // Reputation (Oxy Trust: ledger, balances, disputes, rules, influence)
 // ---------------------------------------------------------------------------
@@ -523,14 +526,38 @@ export {
     generatePkcePair,
     DEFAULT_OAUTH_SCOPE,
     OXY_AUTHORIZE_URL,
+    OXY_OAUTH_STATE_STORAGE_KEY,
+    OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
+    OXY_SILENT_OAUTH_ATTEMPTED_KEY,
+    OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
+    normalizeOAuthRedirectUri,
+    persistOAuthHandshake,
+    readOAuthHandshake,
+    clearOAuthHandshake,
 } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 
+export {
+    buildIdpHubOrigin,
+    buildHubSyncUrl,
+    isIdpHubOrigin,
+    isOfficialWebOrigin,
+    isAllowedDeviceJoinOrigin,
+    normalizeOfficialReturnOrigin,
+    parseHubSyncReturnUrl,
+} from './utils/officialOrigins';
+
+export {
+    syncHubAfterSignIn,
+    redeemHubTicketOnHub,
+} from './session/hubSync';
+export type { SyncHubAfterSignInOptions } from './session/hubSync';
+
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
 // The injectable socket factory type: consumers that bundle socket.io-client
 // (services/auth-sdk) pass its `io` export as `socketFactory` so realtime sync
 // never relies on core's lazy dynamic import of a bare specifier.
@@ -609,12 +636,12 @@ export {
 } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
 
-export { runSessionColdBoot } from './boot/coldBootV2';
+export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type {
     RunSessionColdBootOptions,
     SignedOutReason,
     DeviceBootSession,
-} from './boot/coldBootV2';
+} from './boot/sessionColdBoot';
 
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

package/src/mixins/OxyServices.accounts.ts

@@ -33,6 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
+import type { OrganizationCategory } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
@@ -50,6 +51,10 @@ import { CACHE_TIMES } from './mixinHelpers';
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot';
 
+/** Real-estate / team taxonomy for `kind: 'organization'` accounts. */
+export type { OrganizationCategory } from '@oxyhq/contracts';
+export { ORGANIZATION_CATEGORIES } from '@oxyhq/contracts';
+
 /**
  * The calling user's relationship to an account node, as resolved by the API:
  * - `self` — the caller's own personal (root) account.
@@ -155,6 +160,8 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string };
   bio?: string;
   avatar?: string;
+  /** Meaningful only when `kind` is `organization`. */
+  organizationCategory?: OrganizationCategory;
 }
 
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
@@ -163,6 +170,8 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string };
   bio?: string | null;
   avatar?: string | null;
+  /** Clears the category when `null`; only valid on `kind: 'organization'`. */
+  organizationCategory?: OrganizationCategory | null;
 }
 
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */