@oxyhq/core 3.14.0 → 3.16.0

package/dist/esm/index.js

@@ -128,7 +128,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn.js';
 export { generateSsoState } from './mixins/OxyServices.sso.js';
 // SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce.js';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, allowSsoBounce, } from './utils/ssoBounce.js';
 export { runColdBoot } from './utils/coldBoot.js';
 // 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/dist/esm/mixins/OxyServices.applications.js

@@ -23,6 +23,49 @@ export 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: 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/esm/mixins/OxyServices.assets.js

@@ -16,51 +16,30 @@ export function OxyServicesAssetsMixin(Base) {
             }
         }
         /**
-         * 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, variant, expiresIn, options = {}) {
-            const token = options.omitToken ? undefined : this.getClient().getAccessToken();
-            // Public case: no auth token and no expiry requested → clean CDN URL.
-            // CloudFront serves the public media origin under `${cloudURL}/<id>`.
-            if (!token && !expiresIn) {
+        getFileDownloadUrl(fileId, variant, expiresIn) {
+            // Never embed the in-memory bearer token: this URL is rendered into DOM
+            // attributes, browser network panels, caches, and logs. Public assets get
+            // the clean CDN origin; private/authorized access goes through
+            // `getFileDownloadUrlAsync`.
+            if (!expiresIn) {
                 const variantQs = variant ? `?variant=${encodeURIComponent(variant)}` : '';
                 return `${this.getCloudURL()}/${encodeURIComponent(fileId)}${variantQs}`;
             }
-            // Signed / private case: route through the authenticated API origin's
-            // stream endpoint so the request can be authorized (private assets are not
-            // exposed on the public CDN).
             const base = this.getBaseURL();
             const params = new URLSearchParams();
             if (variant)
                 params.set('variant', variant);
-            if (expiresIn)
-                params.set('expiresIn', String(expiresIn));
+            params.set('expiresIn', String(expiresIn));
             params.set('fallback', 'placeholderVisible');
-            if (token)
-                params.set('token', token);
             const qs = params.toString();
             return `${base}/assets/${encodeURIComponent(fileId)}/stream${qs ? `?${qs}` : ''}`;
         }

package/dist/esm/mixins/OxyServices.auth.js

@@ -546,7 +546,18 @@ export function OxyServicesAuthMixin(Base) {
          */
         async getCommonsApprovalInfo(authorizeCode) {
             try {
-                return await this.makeRequest('GET', `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`, undefined, { cache: false });
+                const raw = await this.makeRequest('GET', `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`, undefined, { cache: false });
+                return {
+                    application: raw.application,
+                    scopes: raw.scopes,
+                    boundOrigin: raw.boundOrigin,
+                    // Fail-safe: only a literal boolean `true` counts as verified. A
+                    // missing or non-boolean value (older server, malformed response)
+                    // coerces to `false` so a stale server can never imply trust.
+                    originVerified: raw.originVerified === true,
+                    expiresAt: raw.expiresAt,
+                    status: raw.status,
+                };
             }
             catch (error) {
                 throw this.handleError(error);

package/dist/esm/mixins/OxyServices.links.js

@@ -0,0 +1,65 @@
+import { buildUrl } from '../utils/apiUtils.js';
+/**
+ * Maximum number of URLs sent per `POST /links/previews` request. Matches the
+ * server-side batch cap (`linkPreviewBatchRequestSchema`'s `.max(50)`); larger
+ * inputs are split into multiple chunked calls and the result maps merged,
+ * mirroring how `getUsersByIds` chunks at 100.
+ */
+const LINK_PREVIEWS_CHUNK_SIZE = 50;
+export function OxyServicesLinksMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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.
+         */
+        async getLinkPreview(url, opts) {
+            try {
+                const path = buildUrl('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
+                return await this.makeRequest('GET', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async getLinkPreviews(urls) {
+            const uniqueUrls = Array.from(new Set(urls.filter((u) => typeof u === 'string' && u.trim().length > 0)));
+            if (uniqueUrls.length === 0) {
+                return {};
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueUrls.length; i += LINK_PREVIEWS_CHUNK_SIZE) {
+                chunks.push(uniqueUrls.slice(i, i + LINK_PREVIEWS_CHUNK_SIZE));
+            }
+            try {
+                const responses = await Promise.all(chunks.map((chunk) => this.makeRequest('POST', '/links/previews', { urls: chunk }, { cache: false })));
+                return responses.reduce((merged, response) => Object.assign(merged, response?.data ?? {}), {});
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,172 @@
+import { SignatureService } from '../crypto/signatureService.js';
+import { buildUserDid } from './OxyServices.identity.js';
+import { CACHE_TIMES } from './mixinHelpers.js';
+/**
+ * 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';
+export 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 = 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.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: 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/esm/mixins/index.js

@@ -30,6 +30,8 @@ import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts.j
 import { OxyServicesContactsMixin } from './OxyServices.contacts.js';
 import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 import { OxyServicesCivicMixin } from './OxyServices.civic.js';
+import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
+import { OxyServicesLinksMixin } from './OxyServices.links.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -77,6 +79,12 @@ const MIXIN_PIPELINE = [
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,
+    // User nodes / decentralization (Fase 5): register/read/revoke/manage the
+    // caller's personal data node + ingest hint.
+    OxyServicesNodesMixin,
+    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
+    // so apps stop scraping link metadata locally.
+    OxyServicesLinksMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/dist/esm/utils/ssoBounce.js

@@ -64,6 +64,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). */
 export function ssoStateKey(origin) {
     return `${STATE_KEY_PREFIX}${origin}`;
@@ -96,6 +97,23 @@ export function ssoNoSessionKey(origin) {
 export 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.
+ */
+export function ssoPriorSessionKey(origin) {
+    return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
+}
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -226,3 +244,31 @@ export function guardActive(storage, origin, now = Date.now()) {
     }
     return now - ts < 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.
+ */
+export function allowSsoBounce(gate) {
+    return gate.hasPriorSession || gate.hasLocalSession;
+}