@oxyhq/core 3.14.0 → 3.16.0

package/dist/types/index.d.ts

@@ -41,13 +41,14 @@ export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHa
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
-export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
+export type { Application, PublicApplication, ConnectedApp, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 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';
 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';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
@@ -93,7 +94,8 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, allowSsoBounce, } from './utils/ssoBounce';
+export type { SsoBounceGate } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { packageInfo } from './constants/version';

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

@@ -151,6 +151,31 @@ export interface PublicApplication {
     /** Optional display name of the developer/owner organisation. */
     developerName?: string;
 }
+/**
+ * A connected (OAuth-authorized) application from the current user's point of
+ * view: an application the user has granted access to via the consent flow.
+ *
+ * Returned by `GET /auth/grants` and rendered in the user-facing "Connected
+ * apps" management surface. Keyed by `applicationId` (the application's Mongo
+ * `_id`) rather than a credential/client id, so the grant — and a subsequent
+ * {@link OxyServicesApplicationsMixin.revokeAppGrant} — survive credential
+ * rotation. This is a display shape: it carries the application's name/logo and
+ * the granted scopes, never any membership or credential material.
+ */
+export interface ConnectedApp {
+    /** The connected application's Mongo `_id`. Use this to revoke the grant. */
+    applicationId: string;
+    /** Human-readable application name shown to the user. */
+    name: string;
+    /** Optional logo URL for the application. */
+    logoUrl?: string;
+    /** OAuth scopes the user has granted to the application. */
+    scopes: string[];
+    /** ISO timestamp of when the user first authorized the application. */
+    firstGrantedAt: string;
+    /** ISO timestamp of when the grant was last exercised. */
+    lastUsedAt: string;
+}
 /** Input accepted by `createApplication`. Staff-only fields are not settable here. */
 export interface CreateApplicationInput {
     name: string;
@@ -265,6 +290,32 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
          *   key). URL-encoded before being placed in the path.
          */
         getPublicApplication(clientId: string): Promise<PublicApplication>;
+        /**
+         * List the OAuth-authorized applications the current user has connected —
+         * the third-party apps the user granted access to via the consent flow.
+         * Each entry is a {@link ConnectedApp} carrying the application's display
+         * identity, the granted scopes, and when the grant was first made and last
+         * exercised. Requires an authenticated session.
+         *
+         * Backed by `GET /auth/grants`. The response is briefly cached
+         * (identity-scoped); {@link revokeAppGrant} busts that cache so a revoke is
+         * reflected on the next read.
+         */
+        listConnectedApps(): Promise<ConnectedApp[]>;
+        /**
+         * Revoke the current user's grant for a connected application, identified by
+         * its application `_id` (a {@link ConnectedApp.applicationId}, NOT a
+         * credential/client id — keyed by application so the revocation survives
+         * credential rotation). After this the application can no longer act on the
+         * user's behalf until it is re-authorized.
+         *
+         * Backed by `DELETE /auth/grants/:applicationId`. On success the cached
+         * connected-apps list (`GET:/auth/grants`) is invalidated so the next
+         * {@link listConnectedApps} read reflects the removal.
+         *
+         * @param applicationId - The connected application's Mongo `_id`.
+         */
+        revokeAppGrant(applicationId: string): Promise<void>;
         /**
          * List applications the current user is an active member of.
          *

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

@@ -1,9 +1,5 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
-interface FileDownloadUrlOptions {
-    /** Omit bearer access tokens from generated URLs, even when authenticated. */
-    omitToken?: boolean;
-}
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -11,32 +7,16 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          */
         deleteFile(fileId: string): Promise<any>;
         /**
-         * Build a synchronous file URL from an Oxy asset id.
+         * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
          *
-         * This is the single chokepoint every Oxy app uses to turn a stored file id
-         * (avatars, post media, etc.) into a `<img src>`-ready URL, so it resolves to
-         * one of two forms depending on whether the caller needs a signed/private URL:
-         *
-         * - **Public asset (default)** — no access token planted on the client AND no
-         *   `expiresIn` requested → returns the clean CDN form
-         *   `${cloudURL}/<id>[?variant=...]` (e.g. `https://cloud.oxy.so/<id>?variant=thumb`).
-         *   CloudFront resolves the id against the public media origin. No token,
-         *   `fallback`, or origin query params are emitted — these URLs are cacheable
-         *   and shareable.
-         * - **Signed / private asset** — an access token is present on the client OR
-         *   `expiresIn` was passed (the caller explicitly wants an expiring/authorized
-         *   URL) → keeps the authenticated origin form
-         *   `${baseURL}/assets/<id>/stream?...&token=...`. Private assets are NOT on
-         *   the public CDN, so they must go through the API origin that can authorize
-         *   the request.
-         *
-         * `cloudURL` (default `https://cloud.oxy.so`) is configured once on the
-         * `OxyServices` constructor and read via `getCloudURL()`; the API origin is
-         * `getBaseURL()` (e.g. `https://api.oxy.so`).
-         *
-         * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
+         * This method must never embed the caller's general access token in the
+         * returned URL. The URL is commonly rendered into DOM attributes, browser
+         * network panels, caches, and logs. Public asset URLs use the clean CDN
+         * origin; callers that need authorized/private access should use
+         * {@link getFileDownloadUrlAsync}, which asks the API for a scoped download
+         * URL instead of exposing the in-memory bearer token in a query string.
          */
-        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number, options?: FileDownloadUrlOptions): string;
+        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
         /**
          * Get file download URL asynchronously (returns signed URL directly from CDN)
          */
@@ -172,4 +152,3 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         }>;
     };
 } & T;
-export {};

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

@@ -94,6 +94,14 @@ export interface CommonsApprovalInfo {
     scopes: string[];
     /** The origin the session is bound to (the RP web origin), when applicable. */
     boundOrigin?: string;
+    /**
+     * Server-authoritative anti-phishing flag: `true` only when this device-flow
+     * sign-in was started from a verified, registered origin of a trusted app.
+     * The approver (Commons) shows a warning when this is `false`. Always present
+     * — a missing/non-boolean server value is coerced to `false` (fail-safe to
+     * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
+     */
+    originVerified: boolean;
     /** Server-authoritative expiry (epoch milliseconds). */
     expiresAt: number;
     /** Session lifecycle status. */

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

@@ -0,0 +1,102 @@
+/**
+ * Link Preview (unfurl) Mixin
+ *
+ * Resolves link previews ("unfurls") through the Oxy API so every Oxy app
+ * stops scraping link metadata locally. The API owns resolution and re-hosts
+ * the preview `image`/`favicon` on Oxy media (`cloud.oxy.so/<fileId>`), so
+ * consumers render the returned URLs directly with no per-app proxy.
+ *
+ * Wire shapes (`LinkPreview`, `LinkPreviewBatchResponse`) are the single source
+ * of truth in `@oxyhq/contracts`; this mixin imports them rather than
+ * redefining them so producer (oxy-api) and consumers cannot drift.
+ *
+ * Caching note: these GET/POST reads are NOT cached at the SDK layer (`cache:
+ * false`). A preview can be returned `'pending'` first and `'resolved'` on a
+ * later read, so an SDK GET cache would pin the stale `'pending'` snapshot.
+ * App-side caching (React Query / stores) owns this responsibility.
+ */
+import type { LinkPreview } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve a single link preview via `GET /links/preview?url=<encoded>&wait=0|1`.
+         *
+         * @param url - The URL to unfurl. Sent percent-encoded in the query string.
+         * @param opts.wait - When `true`, asks the server to resolve synchronously
+         *   (`wait=1`) instead of returning a `'pending'` placeholder for a
+         *   first-seen URL. Defaults to `false` (`wait=0`).
+         *
+         * Not cached at the SDK layer: a `'pending'` result can become `'resolved'`
+         * on a later read, so caching here would serve the stale placeholder.
+         */
+        getLinkPreview(url: string, opts?: {
+            wait?: boolean;
+        }): Promise<LinkPreview>;
+        /**
+         * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
+         *
+         * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
+         * (the server-side cap). Chunks run concurrently and their `data` maps are
+         * merged into a single result keyed by the REQUESTED url (the exact string
+         * passed in `urls`) — matching the batch contract — so a caller can always
+         * look its own input back up.
+         *
+         * An empty / whitespace-only input resolves immediately with `{}` and
+         * performs no network call. A failure in any chunk surfaces (via
+         * `handleError`) rather than being swallowed.
+         */
+        getLinkPreviews(urls: string[]): Promise<Record<string, LinkPreview>>;
+        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;
+        getSessionBaseUrl(): 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;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | 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;

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

@@ -0,0 +1,242 @@
+/**
+ * User-Node Methods Mixin (self-sovereign identity layer — Fase 5 user nodes)
+ *
+ * The client surface for a user's personal data NODE — the decentralised store
+ * that holds an authentic copy of their signed-record chain. Commons drives all
+ * of this:
+ *
+ *  - {@link OxyServicesNodesMixin.registerNode} registers (or re-registers) a
+ *    SELF-HOSTED node. Registration is NOT a bespoke endpoint — it is a signed
+ *    `type:'node'` v2 record (`collection: 'app.oxy.node'`, `rkey: 'self'`,
+ *    last-writer-wins) published through the EXISTING `POST /identity/records`
+ *    path; the server verifies it and materializes the operational
+ *    {@link UserNodeStatus} cache as a side effect, so the registration's
+ *    authority is the user's own signature, never an Oxy grant.
+ *  - {@link OxyServicesNodesMixin.getMyNode} reads the caller's cached node
+ *    status (`GET /nodes/me`) — the fast, stale-but-instant projection plus the
+ *    live liveness badge Oxy maintains with background probes.
+ *  - {@link OxyServicesNodesMixin.removeMyNode} revokes the registration
+ *    (`DELETE /nodes/me`) so the node leaves the DID document and the liveness
+ *    sweeps.
+ *  - {@link OxyServicesNodesMixin.provisionManagedVault} asks Oxy to operate a
+ *    MANAGED vault on the caller's behalf (`POST /nodes/managed`) — the
+ *    "Create your vault" convenience for non-technical users (Oxy custodial-signs
+ *    the node record; `managed:true, controller:'oxy'`).
+ *  - {@link OxyServicesNodesMixin.notifyNodeIngest} sends an unauthenticated
+ *    HINT (`POST /nodes/ingest/notify/:userId`) that a user's node has new
+ *    records; the server fully re-verifies before ingesting, so the hint can
+ *    never inject data.
+ *
+ * `registerNode` signs on the caller's per-subject hash chain with the on-device
+ * identity key (reusing {@link SignatureService.signRecordV2} — the same
+ * `ES256K-DER-SHA256` scheme + {@link signedRecordSigningInput} the identity and
+ * civic mixins use), so it is NATIVE-ONLY: it throws on web (where `KeyManager`
+ * has no key) and when no user is authenticated. Reading the node status,
+ * revoking, provisioning a managed vault, and sending an ingest hint are plain
+ * authenticated/public requests with no signing.
+ *
+ * The wire shapes here are API-INTERNAL (the F5 user-node surface is not yet a
+ * published `@oxyhq/contracts` schema), so {@link UserNodeStatus} mirrors the
+ * server's `serializeNode` projection exactly. Dates cross the wire as ISO
+ * strings.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** How Oxy and the node move records: the node pulls (default), or Oxy pushes. */
+export type UserNodeMode = 'pull' | 'push';
+/**
+ * Who operates the node:
+ *  - `self` — the user self-hosts the node (registered by their own signed
+ *    `type:'node'` record).
+ *  - `oxy`  — Oxy operates a MANAGED vault on the user's behalf (custodial-signed
+ *    `type:'node'` record; the `controller:[OXY_DID]` model).
+ */
+export type UserNodeController = 'self' | 'oxy';
+/**
+ * Liveness badge of a node, maintained ONLY by Oxy's background probes:
+ *  - `active`      — the last probe reached the node's liveness manifest.
+ *  - `unreachable` — the last probe failed (DNS/connect/timeout/non-2xx); the
+ *    cached row is still served, only the badge changes.
+ *  - `revoked`     — the user removed the registration; excluded from the DID
+ *    document and from liveness sweeps.
+ */
+export type UserNodeLivenessStatus = 'active' | 'unreachable' | 'revoked';
+/**
+ * The caller's registered node, as projected by the server's `serializeNode`
+ * (`GET /nodes/me`, `POST /nodes/managed`). A denormalised, fast-to-read copy of
+ * the authoritative signed `type:'node'` record plus the live liveness state Oxy
+ * maintains in the background.
+ *
+ * `mode` / `managed` / `controller` / `status` are always present (server fields
+ * with defaults); the probe/sync fields and `nodeDid` are present only once set.
+ * The `Date` fields cross the wire as ISO-8601 strings.
+ */
+export interface UserNodeStatus {
+    /** Optional DID the node advertises for itself (informational). */
+    nodeDid?: string;
+    /** The node's public HTTPS base URL (where its liveness manifest lives). */
+    endpoint: string;
+    /** The node's secp256k1 public key (hex) — records it signs verify against this. */
+    nodePublicKey: string;
+    /** Transport direction. `pull` (the node paces its own sync) by default. */
+    mode: UserNodeMode;
+    /** Whether Oxy operates this node on the user's behalf (managed vault). */
+    managed: boolean;
+    /** Operator of the node — `self` (user self-hosts) or `oxy` (managed vault). */
+    controller: UserNodeController;
+    /** Liveness badge — maintained only by background probes, never a read handler. */
+    status: UserNodeLivenessStatus;
+    /** Last time a probe reached the node successfully (ISO-8601). */
+    lastSeenAt?: string;
+    /** Last time a probe ran, success or failure (ISO-8601). */
+    lastProbeAt?: string;
+    /** Human-readable reason the last probe OR ingest failed (cleared on success). */
+    lastError?: string;
+    /** Last synced chain `seq` for two-way sync (advanced only by the ingest worker). */
+    cursor?: number;
+    /** Last time the ingest worker ran a pull for this node (ISO-8601). */
+    lastSyncedAt?: string;
+    /** When the node was first registered (ISO-8601). */
+    createdAt: string;
+    /** When the node row was last updated (ISO-8601). */
+    updatedAt: string;
+}
+/**
+ * Input for {@link OxyServicesNodesMixin.registerNode} — the operational facts of
+ * the user's self-hosted node that go into the signed `type:'node'` record.
+ */
+export interface RegisterNodeInput {
+    /** The node's public HTTPS base URL (where its liveness manifest is served). */
+    endpoint: string;
+    /** The node's secp256k1 public key (hex) — records the node signs verify against this. */
+    nodePublicKey: string;
+    /** Transport direction; defaults to `'pull'` when omitted. */
+    mode?: UserNodeMode;
+}
+/** Result of {@link OxyServicesNodesMixin.removeMyNode} (`DELETE /nodes/me`). */
+export interface RemoveNodeResult {
+    /** `true` when an active registration was flipped to `revoked`. */
+    revoked: boolean;
+}
+export declare function OxyServicesNodesMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Register (or re-register) the caller's SELF-HOSTED personal data node.
+         *
+         * Builds the `{ endpoint, nodePublicKey, mode }` node record, signs a v2
+         * envelope on the caller's own per-subject hash chain (fetching the current
+         * chain head first so `seq`/`prev` are never stale), and publishes it through
+         * the EXISTING `POST /identity/records` path — which verifies the signature
+         * and materializes the operational node cache as a side effect. The signed
+         * record (not this call) is the authority; re-registering over-writes the
+         * single `self` record (last-writer-wins).
+         *
+         * NATIVE-ONLY: signs with the on-device identity key (throws on web / when no
+         * identity or no authenticated user — the guard fires before any network).
+         * `mode` defaults to `'pull'`. After a successful publish the node + `/users/me`
+         * GET caches are swept, then the freshly-materialized status is returned.
+         *
+         * Throws if the chain record stored but the server skipped materialization
+         * (e.g. a malformed endpoint the server rejected) — an unexpected state rather
+         * than a silent `null`.
+         *
+         * @param input - The node's endpoint, public key, and optional transport mode.
+         */
+        registerNode(input: RegisterNodeInput): Promise<UserNodeStatus>;
+        /**
+         * Read the caller's registered node status (`GET /nodes/me`), or `null` when
+         * the caller has no node. Auth required; short-TTL cached (the liveness badge
+         * is background-maintained) and swept after the caller's own
+         * register / revoke / managed-provision.
+         */
+        getMyNode(): Promise<UserNodeStatus | null>;
+        /**
+         * Revoke the caller's node registration (`DELETE /nodes/me`). The node flips
+         * to `revoked` server-side (leaving the DID document and liveness sweeps).
+         * Auth required; the node + `/users/me` GET caches are swept on success.
+         *
+         * Maps the server's `{ success }` to the SDK's `{ revoked }` semantic.
+         */
+        removeMyNode(): Promise<RemoveNodeResult>;
+        /**
+         * Provision (or refresh) an Oxy-operated MANAGED vault for the caller
+         * (`POST /nodes/managed`) — the "Create your vault" convenience for
+         * non-technical users. Oxy custodial-signs the node registration onto the
+         * caller's chain and returns the materialized node (`managed:true,
+         * controller:'oxy'`). Idempotent server-side. Auth required; the owner id is
+         * resolved from the session, never the body. The node + `/users/me` GET caches
+         * are swept on success.
+         */
+        provisionManagedVault(): Promise<UserNodeStatus>;
+        /**
+         * Send an ingest HINT that a user's node has new records
+         * (`POST /nodes/ingest/notify/:userId`). Unauthenticated by design and
+         * fire-and-forget on the server (it only schedules a background re-pull of the
+         * named user's OWN node, then fully re-verifies — a notify can never inject
+         * data), so this resolves once the 202 hint is accepted and returns nothing.
+         *
+         * @param userId - The user whose node may have new records. URL-encoded.
+         */
+        notifyNodeIngest(userId: string): Promise<void>;
+        /**
+         * Sweep the GET caches a node mutation invalidates: every node read
+         * (`GET:/nodes/`) so a re-read reflects the new node / its absence, and
+         * `/users/me` because the user's derived DID document embeds an `#oxy-node`
+         * service entry that changes on register / revoke / manage. Public rather
+         * than `private` because mixins compose into an exported anonymous class
+         * where TypeScript cannot represent a private member in the emitted
+         * declaration file (TS4094) — mirrors the civic / identity cache sweepers.
+         */
+        _sweepNodeCaches(): void;
+        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;
+        getSessionBaseUrl(): 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;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | 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;

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

@@ -30,6 +30,8 @@ import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesNodesMixin } from './OxyServices.nodes';
+import { OxyServicesLinksMixin } from './OxyServices.links';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -39,7 +41,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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

@@ -79,6 +79,21 @@ export declare function ssoNoSessionKey(origin: string): string;
  * centrally) can probe again.
  */
 export declare function ssoAttemptedKey(origin: string): string;
+/**
+ * Per-origin DURABLE "this device/origin has had a signed-in Oxy session
+ * before" hint.
+ *
+ * Unlike every other key in this module — which lives in per-tab
+ * `sessionStorage` — this hint is written to DURABLE storage (web
+ * `localStorage`; the services provider uses its own `storageKeyPrefix`-scoped
+ * key in `@oxyhq/services`). It is set whenever a session is established or
+ * restored and survives a session expiring; it is cleared ONLY on an explicit
+ * full sign-out. It exists purely to drive {@link allowSsoBounce}: a returning
+ * visitor (hint present) whose local session has lapsed still gets ONE terminal
+ * `/sso` establish bounce to recover a session that lives only at the central
+ * IdP, while a truly first-time anonymous visitor is never force-bounced.
+ */
+export declare function ssoPriorSessionKey(origin: string): string;
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -159,3 +174,49 @@ export declare function isCentralIdPOrigin(origin: string): boolean;
  *   `Date.now()`.
  */
 export declare function guardActive(storage: Pick<Storage, 'getItem'>, origin: string, now?: number): boolean;
+/**
+ * Inputs to the smart {@link allowSsoBounce} gate.
+ */
+export interface SsoBounceGate {
+    /**
+     * Whether this device/origin has had a signed-in Oxy session before (the
+     * durable {@link ssoPriorSessionKey} hint). Set whenever a session is
+     * established or restored; survives session expiry; cleared only on explicit
+     * full sign-out. `true` ⇒ a returning visitor.
+     */
+    readonly hasPriorSession: boolean;
+    /**
+     * Whether a local/stored session was recovered earlier this cold boot. At the
+     * terminal bounce gate this is effectively always `false` (an earlier step
+     * would have won and short-circuited), but it is part of the contract — "no
+     * prior hint AND no local session" — so it is passed explicitly for fidelity
+     * and robustness.
+     */
+    readonly hasLocalSession: boolean;
+}
+/**
+ * Decide whether the terminal `/sso` establish-bounce is ALLOWED for this
+ * visitor (the smart `enabled` gate for the `sso-bounce` cold-boot step).
+ *
+ * The terminal bounce is the ONLY cold-boot step that can recover a session
+ * that lives SOLELY at the central IdP — the cross-apex Relying-Party case
+ * (e.g. `mention.earth`, a different apex from `oxy.so`) whose device-local
+ * session has expired and whose `Domain=oxy.so` refresh cookie never reaches
+ * `api.<apex>`. It is also what plants the first-party per-apex `fedcm_session`
+ * cookie that the EARLIER `silent-iframe` step later relies on. So it must fire
+ * for a RETURNING user, yet it must NOT force a truly first-time anonymous
+ * visitor off to the IdP.
+ *
+ *   - ALLOW when there is a prior-signed-in hint OR a local session was
+ *     recovered this boot (a returning user) — so a central-only cross-domain
+ *     session recovers via ONE bounce, after which the per-apex cookie is
+ *     planted and subsequent loads restore silently with no bounce.
+ *   - else (no hint, no local session) SUPPRESS — a first-time anonymous
+ *     visitor browses without a forced redirect.
+ *
+ * This is the smart DEFAULT and the ONLY behaviour: apps never configure it.
+ * It is also the GATE DECISION ONLY — callers still apply the per-tab loop
+ * guards (`ssoAttemptedKey`, `ssoNoSessionKey`, {@link guardActive}) so an
+ * allowed bounce still fires at most once per cold boot.
+ */
+export declare function allowSsoBounce(gate: SsoBounceGate): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",