@oxyhq/core 20.0.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';
@@ -39,6 +39,7 @@ 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 { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
 export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, 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 { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
@@ -46,6 +47,12 @@ export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
 export type { CivicCardResult, IdCardRef, AttestQrPayload, ParsedAttestPayload, SubmitRealLifeAttestationInput, DenyValidationResult, VouchForPersonInput, WithdrawVouchResult, IssueCredentialInput, RevokeCredentialResult, } from './mixins/OxyServices.civic';
 export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
+/**
+ * Chains — the shared per-person record log. `ChainRecord` is generic over the
+ * app's own lexicon payload, so a consumer types its records without Oxy
+ * knowing any app's schema.
+ */
+export type { ChainRecord, ChainRecordPage, AppendedChainRecord } from './mixins/OxyServices.chains';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
@@ -109,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/mixins/OxyServices.chains.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Chains — the shared record log every Oxy app reads and writes.
+ *
+ * A person has ONE chain. An app appends its own records to it and projects its
+ * feeds from what it reads back, instead of keeping a private copy of the same
+ * person's activity. This mixin is the client half of `/chains` in oxy-api, and
+ * it exists so that adopting the chain costs an app no HTTP of its own — the
+ * whole point of the shared substrate is that the second app writes less code
+ * than the first, not the same amount in a different file.
+ *
+ * ## Both calls are SERVICE-authenticated
+ *
+ * They go through `makeServiceRequest`, so they only work on a backend that has
+ * called `configureServiceAuth()`. That is not an accident of implementation: an
+ * append writes to someone else's chain and a read spans many subjects, so
+ * neither belongs in a browser holding a user session. A frontend that needs
+ * this asks its own backend.
+ *
+ * The authority is checked server-side and cannot be talked out of from here:
+ * `chains:write` plus the application's own `chainNamespaces` for an append,
+ * `chains:read` plus the public-collection policy for a read. A call that
+ * violates either gets a 403 or an empty page — this client adds no
+ * pre-validation that could drift from the server's answer.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** A signed record as it comes back from a read. */
+export interface ChainRecord<TRecord = Record<string, unknown>> {
+    recordId: string;
+    /** The subject whose chain it is — the person the record is about. */
+    oxyUserId: string;
+    /** The lexicon NSID, e.g. `app.mention.feed.post`. */
+    collection: string;
+    envelope: {
+        version: number;
+        type: string;
+        subject: string;
+        issuer: string;
+        record: TRecord;
+        issuedAt: number;
+        seq?: number;
+        prev?: string | null;
+        collection?: string;
+        rkey?: string;
+        publicKey: string;
+        alg: string;
+        signature: string;
+    };
+}
+/** One page of a multi-subject read. */
+export interface ChainRecordPage<TRecord = Record<string, unknown>> {
+    records: ChainRecord<TRecord>[];
+    /**
+     * Opaque. Hand it back as `since` to continue; `null` at the end of the
+     * stream as of this snapshot. Never construct one.
+     */
+    nextCursor: string | null;
+}
+/** What an append returns once the record is on the chain. */
+export interface AppendedChainRecord {
+    recordId: string;
+    seq: number;
+    envelope: ChainRecord['envelope'];
+    verified: boolean;
+}
+export declare function OxyServicesChainsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /** Service-token request, implemented by the auth mixin earlier in the pipeline. */
+        makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, userId?: string) => Promise<R>;
+        /**
+         * Append a record to `oxyUserId`'s chain under `collection`/`rkey`.
+         *
+         * Oxy issues and signs it; the calling app never holds a chain signing key.
+         * `rkey` is the app's own id for the thing — reusing it later supersedes the
+         * earlier record for that key, which is how an edit works.
+         *
+         * Requires the `chains:write` scope AND `collection` falling under one of
+         * this application's granted `chainNamespaces`. Both are enforced by the
+         * server; a violation throws with a 403.
+         */
+        appendChainRecord(params: {
+            oxyUserId: string;
+            collection: string;
+            rkey: string;
+            record: Record<string, unknown>;
+        }): Promise<AppendedChainRecord>;
+        /**
+         * Records published by any of `oxyUserIds` under any of `collections`,
+         * oldest first — the read a cross-app feed is projected from.
+         *
+         * Only collections Oxy declares PUBLIC come back, whatever is asked for; a
+         * private one yields nothing rather than an error.
+         *
+         * **Re-poll from slightly BEFORE your last cursor and dedupe by
+         * `recordId`.** The chain's pagination axis is a transaction-start
+         * timestamp, so a record can commit behind a cursor that already passed it.
+         * Re-delivering one costs bytes; skipping one costs a record that never
+         * appears. Projections are expected to be idempotent for exactly this
+         * reason.
+         */
+        readChainRecords<TRecord = Record<string, unknown>>(params: {
+            oxyUserIds: readonly string[];
+            collections: readonly string[];
+            since?: string | null;
+            limit?: number;
+        }): Promise<ChainRecordPage<TRecord>>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;