@oxyhq/core 3.13.1 → 3.15.0

package/dist/cjs/index.js

@@ -21,7 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setPlatformOS = exports.getPlatformOS = exports.isRTLLocale = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.RecoveryPhraseService = exports.canonicalize = exports.computeRecordId = exports.signedRecordSigningInput = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.createCrossDomainAuth = exports.CrossDomainAuth = exports.createAuthManager = exports.AuthManager = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
 exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = void 0;
 exports.ssoDestKey = exports.ssoGuardKey = exports.ssoStateKey = exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = exports.generateSsoState = exports.consumeSsoReturn = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_IDP_APEX = exports.CENTRAL_AUTH_URL = exports.registrableApex = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = void 0;
-exports.packageInfo = exports.runColdBoot = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = exports.ssoAttemptedKey = exports.ssoNoSessionKey = void 0;
+exports.packageInfo = exports.runColdBoot = exports.allowSsoBounce = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = exports.ssoPriorSessionKey = exports.ssoAttemptedKey = exports.ssoNoSessionKey = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -287,12 +287,14 @@ Object.defineProperty(exports, "ssoGuardKey", { enumerable: true, get: function
 Object.defineProperty(exports, "ssoDestKey", { enumerable: true, get: function () { return ssoBounce_1.ssoDestKey; } });
 Object.defineProperty(exports, "ssoNoSessionKey", { enumerable: true, get: function () { return ssoBounce_1.ssoNoSessionKey; } });
 Object.defineProperty(exports, "ssoAttemptedKey", { enumerable: true, get: function () { return ssoBounce_1.ssoAttemptedKey; } });
+Object.defineProperty(exports, "ssoPriorSessionKey", { enumerable: true, get: function () { return ssoBounce_1.ssoPriorSessionKey; } });
 Object.defineProperty(exports, "ssoCallbackBootstrapKey", { enumerable: true, get: function () { return ssoBounce_1.ssoCallbackBootstrapKey; } });
 Object.defineProperty(exports, "ssoNavigate", { enumerable: true, get: function () { return ssoBounce_1.ssoNavigate; } });
 Object.defineProperty(exports, "getSsoCallbackBootstrapScript", { enumerable: true, get: function () { return ssoBounce_1.getSsoCallbackBootstrapScript; } });
 Object.defineProperty(exports, "buildSsoBounceUrl", { enumerable: true, get: function () { return ssoBounce_1.buildSsoBounceUrl; } });
 Object.defineProperty(exports, "isCentralIdPOrigin", { enumerable: true, get: function () { return ssoBounce_1.isCentralIdPOrigin; } });
 Object.defineProperty(exports, "guardActive", { enumerable: true, get: function () { return ssoBounce_1.guardActive; } });
+Object.defineProperty(exports, "allowSsoBounce", { enumerable: true, get: function () { return ssoBounce_1.allowSsoBounce; } });
 var coldBoot_1 = require("./utils/coldBoot");
 Object.defineProperty(exports, "runColdBoot", { enumerable: true, get: function () { return coldBoot_1.runColdBoot; } });
 // API response contracts (request/response Zod schemas + inferred types) live in

package/dist/cjs/mixins/OxyServices.applications.js

@@ -26,6 +26,49 @@ function OxyServicesApplicationsMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * 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.
+         */
+        async listConnectedApps() {
+            try {
+                return await this.makeRequest('GET', '/auth/grants', undefined, { cache: true, cacheTTL: mixinHelpers_1.CACHE_TIMES.SHORT });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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`.
+         */
+        async revokeAppGrant(applicationId) {
+            try {
+                await this.makeRequest('DELETE', `/auth/grants/${applicationId}`, undefined, { cache: false });
+                // A revoke removes an entry from the user's connected-apps list; bust
+                // the cached `GET /auth/grants` so the next read re-fetches.
+                this.clearCacheEntry('GET:/auth/grants');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * List applications the current user is an active member of.
          *

package/dist/cjs/mixins/OxyServices.nodes.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesNodesMixin = OxyServicesNodesMixin;
+const signatureService_1 = require("../crypto/signatureService");
+const OxyServices_identity_1 = require("./OxyServices.identity");
+const mixinHelpers_1 = require("./mixinHelpers");
+/**
+ * AtProto-style collection (NSID) for a user-node registration record — matches
+ * the server's `NODE_COLLECTION`. A user has exactly one node, so the record is
+ * keyed by the constant {@link NODE_RKEY} (last-writer-wins): re-registering
+ * over-writes the single `self` record rather than appending a second node.
+ */
+const NODE_COLLECTION = 'app.oxy.node';
+/**
+ * The AtProto-style record key for the single node registration — matches the
+ * server's `NODE_RKEY`. Constant (`'self'`) because a user has one node.
+ */
+const NODE_RKEY = 'self';
+/**
+ * Cache-key prefix of every node read (`GET /nodes/me`). Swept after a
+ * register / revoke / managed-provision so a re-read reflects the new node
+ * (or its absence) instead of a stale cached one. The identity tag is a key
+ * SUFFIX, so this prefix invalidates the resource for every cached identity.
+ */
+const NODES_CACHE_PREFIX = 'GET:/nodes/';
+/**
+ * Cache-key prefix of the current user's `GET /users/me`. Swept alongside the
+ * node caches because the user's derived DID document embeds an `#oxy-node`
+ * service entry derived from the node row, so registering / revoking / managing
+ * a node changes user-facing identity state.
+ */
+const USERS_ME_CACHE_PREFIX = 'GET:/users/me';
+function OxyServicesNodesMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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.
+         */
+        async registerNode(input) {
+            try {
+                const userId = this.getCurrentUserId();
+                if (!userId) {
+                    throw new Error('No authenticated user — sign in before registering a node.');
+                }
+                const subject = (0, OxyServices_identity_1.buildUserDid)(userId);
+                const record = {
+                    endpoint: input.endpoint,
+                    nodePublicKey: input.nodePublicKey,
+                    mode: input.mode ?? 'pull',
+                };
+                // Fetch the caller's chain head fresh (uncached) so seq/prev are correct
+                // → no bad_seq / chain_fork — exactly as the identity/civic signers do.
+                const head = await this.makeRequest('GET', `/identity/records/${encodeURIComponent(userId)}/chain/head`, undefined, { cache: false });
+                const envelope = await signatureService_1.SignatureService.signRecordV2('node', subject, record, {
+                    seq: head.seq + 1,
+                    prev: head.headRecordId,
+                    collection: NODE_COLLECTION,
+                    rkey: NODE_RKEY,
+                });
+                await this.makeRequest('POST', '/identity/records', envelope, { cache: false });
+                this._sweepNodeCaches();
+                const node = await this.getMyNode();
+                if (!node) {
+                    throw new Error('Node registration stored but the node could not be materialized.');
+                }
+                return node;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async getMyNode() {
+            try {
+                const res = await this.makeRequest('GET', '/nodes/me', undefined, { cache: true, cacheTTL: mixinHelpers_1.CACHE_TIMES.SHORT });
+                return res.node ?? null;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async removeMyNode() {
+            try {
+                const res = await this.makeRequest('DELETE', '/nodes/me', undefined, { cache: false });
+                this._sweepNodeCaches();
+                return { revoked: res.success === true };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async provisionManagedVault() {
+            try {
+                const res = await this.makeRequest('POST', '/nodes/managed', undefined, { cache: false });
+                this._sweepNodeCaches();
+                return res.node;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async notifyNodeIngest(userId) {
+            try {
+                await this.makeRequest('POST', `/nodes/ingest/notify/${encodeURIComponent(userId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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() {
+            this.clearCacheByPrefix(NODES_CACHE_PREFIX);
+            this.clearCacheByPrefix(USERS_ME_CACHE_PREFIX);
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.user.js

@@ -593,6 +593,27 @@ function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Get user mutuals ("followers you know" — users the authenticated viewer
+         * follows who also follow `userId`). The viewer is derived server-side from auth.
+         */
+        async getUserMutuals(userId, pagination) {
+            try {
+                const params = (0, apiUtils_1.buildPaginationParams)(pagination || {});
+                const response = await this.makeRequest('GET', `/users/${userId}/mutuals`, params, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                return {
+                    mutuals: response.data || [],
+                    total: response.pagination.total,
+                    hasMore: response.pagination.hasMore,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Get notifications
          */

package/dist/cjs/mixins/index.js

@@ -34,6 +34,7 @@ const OxyServices_managedAccounts_1 = require("./OxyServices.managedAccounts");
 const OxyServices_contacts_1 = require("./OxyServices.contacts");
 const OxyServices_appData_1 = require("./OxyServices.appData");
 const OxyServices_civic_1 = require("./OxyServices.civic");
+const OxyServices_nodes_1 = require("./OxyServices.nodes");
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -81,6 +82,9 @@ const MIXIN_PIPELINE = [
     OxyServices_appData_1.OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServices_civic_1.OxyServicesCivicMixin,
+    // User nodes / decentralization (Fase 5): register/read/revoke/manage the
+    // caller's personal data node + ingest hint.
+    OxyServices_nodes_1.OxyServicesNodesMixin,
     // Utility (last, can use all above)
     OxyServices_utility_1.OxyServicesUtilityMixin,
 ];

package/dist/cjs/utils/ssoBounce.js

@@ -49,12 +49,14 @@ exports.ssoGuardKey = ssoGuardKey;
 exports.ssoDestKey = ssoDestKey;
 exports.ssoNoSessionKey = ssoNoSessionKey;
 exports.ssoAttemptedKey = ssoAttemptedKey;
+exports.ssoPriorSessionKey = ssoPriorSessionKey;
 exports.ssoCallbackBootstrapKey = ssoCallbackBootstrapKey;
 exports.getSsoCallbackBootstrapScript = getSsoCallbackBootstrapScript;
 exports.ssoNavigate = ssoNavigate;
 exports.buildSsoBounceUrl = buildSsoBounceUrl;
 exports.isCentralIdPOrigin = isCentralIdPOrigin;
 exports.guardActive = guardActive;
+exports.allowSsoBounce = allowSsoBounce;
 const authWebUrl_1 = require("./authWebUrl");
 /**
  * The RP callback path the central IdP redirects back to after a bounce. The
@@ -78,6 +80,7 @@ const DEST_KEY_PREFIX = 'oxy_sso_dest:';
 const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
 const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
+const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 function ssoStateKey(origin) {
     return `${STATE_KEY_PREFIX}${origin}`;
@@ -110,6 +113,23 @@ function ssoNoSessionKey(origin) {
 function ssoAttemptedKey(origin) {
     return `${ATTEMPTED_KEY_PREFIX}${origin}`;
 }
+/**
+ * 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.
+ */
+function ssoPriorSessionKey(origin) {
+    return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
+}
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -240,3 +260,31 @@ function guardActive(storage, origin, now = Date.now()) {
     }
     return now - ts < exports.SSO_GUARD_TTL_MS;
 }
+/**
+ * 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.
+ */
+function allowSsoBounce(gate) {
+    return gate.hasPriorSession || gate.hasLocalSession;
+}