@oxyhq/core 3.14.0 → 3.16.0

package/src/index.ts

@@ -98,6 +98,7 @@ export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type {
     Application,
     PublicApplication,
+    ConnectedApp,
     ApplicationMember,
     ApplicationCredential,
     ApplicationRole,
@@ -210,6 +211,7 @@ export type {
     IssueCredentialInput,
     RevokeCredentialResult,
 } from './mixins/OxyServices.civic';
+export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
 
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
@@ -532,13 +534,16 @@ export {
     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 {

package/src/mixins/OxyServices.applications.ts

@@ -164,6 +164,32 @@ export interface PublicApplication {
   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;
@@ -309,6 +335,59 @@ export function OxyServicesApplicationsMixin<T extends typeof OxyServicesBase>(B
       }
     }
 
+    /**
+     * 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(): Promise<ConnectedApp[]> {
+      try {
+        return await this.makeRequest<ConnectedApp[]>(
+          '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: string): Promise<void> {
+      try {
+        await this.makeRequest<{ revoked: boolean }>(
+          '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/src/mixins/OxyServices.assets.ts

@@ -2,11 +2,6 @@ import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, A
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '../utils/platform';
 
-interface FileDownloadUrlOptions {
-  /** Omit bearer access tokens from generated URLs, even when authenticated. */
-  omitToken?: boolean;
-}
-
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -25,55 +20,30 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Build a synchronous 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.
+     * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
      *
-     * `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 {
-      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: string, variant?: string, expiresIn?: number): string {
+      // 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/src/mixins/OxyServices.auth.ts

@@ -125,12 +125,35 @@ 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. */
   status: string;
 }
 
+/**
+ * @internal Raw server response of `GET /auth/session/approve-info/:code`.
+ * `originVerified` is typed loosely here because older servers may omit it (or
+ * send a non-boolean); the SDK coerces it to a strict `boolean` when mapping
+ * into {@link CommonsApprovalInfo}.
+ */
+interface CommonsApprovalInfoResponse {
+  application: PublicApplication;
+  scopes: string[];
+  boundOrigin?: string;
+  originVerified?: unknown;
+  expiresAt: number;
+  status: string;
+}
+
 /** Result of approving / denying a "Sign in with Oxy" request. */
 export interface CommonsSignInActionResult {
   success: boolean;
@@ -826,12 +849,23 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getCommonsApprovalInfo(authorizeCode: string): Promise<CommonsApprovalInfo> {
       try {
-        return await this.makeRequest<CommonsApprovalInfo>(
+        const raw = await this.makeRequest<CommonsApprovalInfoResponse>(
           '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/src/mixins/OxyServices.links.ts

@@ -0,0 +1,103 @@
+/**
+ * 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, LinkPreviewBatchResponse } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { buildUrl } from '../utils/apiUtils';
+
+/**
+ * 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<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [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.
+     */
+    async getLinkPreview(url: string, opts?: { wait?: boolean }): Promise<LinkPreview> {
+      try {
+        const path = buildUrl('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
+        return await this.makeRequest<LinkPreview>('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: string[]): Promise<Record<string, LinkPreview>> {
+      const uniqueUrls = Array.from(
+        new Set(urls.filter((u): u is string => typeof u === 'string' && u.trim().length > 0)),
+      );
+      if (uniqueUrls.length === 0) {
+        return {};
+      }
+
+      const chunks: string[][] = [];
+      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<LinkPreviewBatchResponse>(
+              'POST',
+              '/links/previews',
+              { urls: chunk },
+              { cache: false },
+            ),
+          ),
+        );
+
+        return responses.reduce<Record<string, LinkPreview>>(
+          (merged, response) => Object.assign(merged, response?.data ?? {}),
+          {},
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}