@oxyhq/core 3.10.0 → 3.11.0

package/src/index.ts

@@ -51,6 +51,13 @@ export type { SilentAuthOptions } from './mixins/OxyServices.silent';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+// "Sign in with Oxy" — handoff (Workstream C)
+export type {
+    CommonsSignInHandle,
+    CommonsSignInStatus,
+    CommonsApprovalInfo,
+    CommonsSignInActionResult,
+} from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type {
     CreateManagedAccountInput,
@@ -159,6 +166,23 @@ export type {
     ReverseReputationTransactionInput,
 } from './mixins/OxyServices.reputation';
 
+// ---------------------------------------------------------------------------
+// Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,
+// verified domains). Wire shapes (DidDocument, SignedRecordEnvelope,
+// AuthMethodsResponse, VerifiedDomain, DomainVerificationInstructions,
+// ExportBundle) live in `@oxyhq/contracts` — import them directly from there.
+// ---------------------------------------------------------------------------
+export { buildUserDid } from './mixins/OxyServices.identity';
+export type {
+    IdentityRecordType,
+    UnlinkableAuthMethodType,
+    LinkAuthMethodResult,
+    PublishRecordResult,
+    VerifyRecordResult,
+    VerifyDomainResult,
+    RemoveDomainResult,
+} from './mixins/OxyServices.identity';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------
@@ -206,8 +230,9 @@ export {
     IdentityPersistError,
 } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService } from './crypto/signatureService';
-export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput } from './crypto/signatureService';
+export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
+export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 
@@ -462,7 +487,7 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // ---------------------------------------------------------------------------
 // Cross-domain SSO infrastructure
 // ---------------------------------------------------------------------------
-export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
+export { autoDetectAuthWebUrl, registrableApex } from './utils/fapiAutoDetect';
 
 // Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
 export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';

package/src/mixins/OxyServices.assets.ts

@@ -1,5 +1,11 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor } from '../models/interfaces';
 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 {
@@ -44,8 +50,13 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
      *
      * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
      */
-    getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string {
-      const token = this.getClient().getAccessToken();
+    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>`.
@@ -212,10 +223,33 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         } else if (typeof Blob !== 'undefined' && file instanceof Blob) {
           formData.append('file', file, fileName);
         } else if ('uri' in file && typeof (file as RNFileDescriptor).uri === 'string') {
-          // React Native file descriptor — RN's FormData handles {uri, type, name} natively.
-          // It reads the file from disk during the multipart request — no in-JS Blob
-          // conversion (which would fail on Hermes for ArrayBuffer-backed Blobs).
-          formData.append('file', file as unknown as Blob, fileName);
+          const descriptor = file as RNFileDescriptor;
+
+          if (isReactNative()) {
+            // React Native file descriptor — RN's FormData handles {uri, type, name} natively.
+            // It reads the file from disk during the multipart request — no in-JS Blob
+            // conversion (which would fail on Hermes for ArrayBuffer-backed Blobs).
+            formData.append('file', descriptor as unknown as Blob, fileName);
+          } else {
+            // Web (browser/Node): the browser's FormData cannot read bytes from a plain
+            // { uri } object — it would serialize "[object Object]" and the server would
+            // store a 0-byte asset. Materialize the uri into a real Blob first. `fetch`
+            // resolves blob:, data:, and http(s): uris on web, so all picker outputs work.
+            const res = await fetch(descriptor.uri);
+            if (!res.ok) {
+              throw new Error(`Failed to read file from uri (status ${res.status})`);
+            }
+            const fetched = await res.blob();
+            // Preserve the descriptor's declared MIME type when the fetched blob has none.
+            const blob =
+              fetched.type === '' && descriptor.type
+                ? new Blob([fetched], { type: descriptor.type })
+                : fetched;
+            if (blob.size === 0) {
+              throw new Error('Cannot upload an empty file');
+            }
+            formData.append('file', blob, fileName);
+          }
         } else {
           throw new Error('Unsupported file input: expected File, Blob, or { uri, type?, name?, size? } descriptor');
         }
@@ -452,7 +486,9 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     public async fetchAssetContent(url: string, type: 'text'): Promise<string>;
     public async fetchAssetContent(url: string, type: 'blob'): Promise<Blob>;
     public async fetchAssetContent(url: string, type: 'text' | 'blob') {
-      const response = await fetch(url, { credentials: 'include' });
+      const response = await fetch(url, {
+        credentials: shouldSendAssetCredentials(url, this.getBaseURL()) ? 'include' : 'omit',
+      });
       if (!response?.ok) {
         throw new Error(`Failed to fetch asset content (status ${response?.status})`);
       }
@@ -460,3 +496,16 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
   };
 }
+
+/**
+ * Only send ambient credentials (cookies) when the asset URL is same-origin with
+ * the configured API base. Caller-supplied cross-origin asset URLs must not leak
+ * the user's cookies to arbitrary hosts.
+ */
+function shouldSendAssetCredentials(url: string, baseURL: string): boolean {
+  try {
+    return new URL(url).origin === new URL(baseURL).origin;
+  } catch {
+    return false;
+  }
+}

package/src/mixins/OxyServices.auth.ts

@@ -12,11 +12,21 @@ import type {
 import type { UserNameResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
+import type { PublicApplication } from './OxyServices.applications';
 import { OxyAuthenticationError } from '../OxyServices.errors';
+import { KeyManager } from '../crypto/keyManager';
+import { SignatureService } from '../crypto/signatureService';
 import { loadNodeCrypto } from '../utils/platformCrypto';
 import { logger } from '../utils/loggerUtils';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
+/**
+ * Default lifetime of a "Sign in with Oxy" device-flow session / authorize code.
+ * Matches the authorize-code TTL the server enforces (5 minutes). The server's
+ * returned `expiresAt` is authoritative; this is only the client-proposed value.
+ */
+const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
+
 export interface ChallengeResponse {
   challenge: string;
   expiresAt: string;
@@ -64,6 +74,79 @@ export interface PublicKeyCheckResponse {
   message: string;
 }
 
+// ===========================================================================
+// "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
+// ===========================================================================
+
+/**
+ * Handle returned by {@link OxyServicesAuthMixin.startCommonsSignIn} for a
+ * relying-party app initiating a "Sign in with Oxy" flow.
+ *
+ * `sessionToken` is the SECRET, high-entropy device-flow credential — it stays
+ * on the initiating client, is exchanged once via `claimSessionByToken`, and is
+ * NEVER placed in the QR/deep-link. `authorizeCode` is the PUBLIC handle carried
+ * in `qrPayload`; the approver (Commons) resolves it via
+ * {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
+ */
+export interface CommonsSignInHandle {
+  /** Secret device-flow token (held by the initiator; exchanged via `claimSessionByToken`). */
+  sessionToken: string;
+  /** Public, single-use authorize code carried in the QR / deep-link. */
+  authorizeCode: string;
+  /** Ready-to-render deep-link / universal-link string (`oxycommons://approve?...`). */
+  qrPayload: string;
+  /** Server-authoritative expiry (epoch milliseconds). */
+  expiresAt: number;
+  /** Session lifecycle status as reported by the server (e.g. `'pending'`). */
+  status: string;
+}
+
+/** Poll result for a "Sign in with Oxy" device-flow session (`GET /auth/session/status`). */
+export interface CommonsSignInStatus {
+  /** True once an approver has authorized the session. */
+  authorized: boolean;
+  /** The authorized session id (present once `authorized`). */
+  sessionId?: string;
+  /** The approving identity's public key (present once `authorized`). */
+  publicKey?: string;
+  /** Lifecycle status (`'pending'` | `'authorized'` | `'cancelled'` | `'expired'`). */
+  status?: string;
+}
+
+/**
+ * Server-resolved approval context shown by the approver (Commons) before
+ * authorizing — the TRUSTED identity of the requesting app, resolved from the
+ * `authorizeCode` server-side (never from the QR string).
+ */
+export interface CommonsApprovalInfo {
+  /** Sanitized, display-safe identity of the requesting application. */
+  application: PublicApplication;
+  /** OAuth scopes the application is requesting. */
+  scopes: string[];
+  /** The origin the session is bound to (the RP web origin), when applicable. */
+  boundOrigin?: string;
+  /** Server-authoritative expiry (epoch milliseconds). */
+  expiresAt: number;
+  /** Session lifecycle status. */
+  status: string;
+}
+
+/** Result of approving / denying a "Sign in with Oxy" request. */
+export interface CommonsSignInActionResult {
+  success: boolean;
+}
+
+/** @internal Response shape of the extended `POST /auth/session/create`. */
+interface CommonsSessionCreateResponse {
+  authorizeCode: string;
+  qrPayload: string;
+  status: string;
+  /** Optional server-authoritative expiry; falls back to the client-proposed value. */
+  expiresAt?: number;
+  /** Optional server echo of the session token (the client-supplied value is authoritative). */
+  sessionToken?: string;
+}
+
 export interface ServiceTokenResponse {
   token: string;
   expiresIn: number;
@@ -247,11 +330,24 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       entry.pending = pending;
       try {
         return await pending;
+      } catch (error) {
+        // Do not retain unauthenticated cache entries. If the initial
+        // /auth/service-token request fails (for example, wrong apiSecret),
+        // leaving the pre-seeded empty entry would cause later calls with the
+        // real secret for the same apiKey to fail locally as a credential
+        // mismatch without ever contacting the server. Keep previously-issued
+        // stale tokens on refresh failures, but remove never-authenticated
+        // entries.
+        const failed = this._serviceTokenCache.get(cacheKey);
+        if (failed?.pending === pending && !failed.token) {
+          this._serviceTokenCache.delete(cacheKey);
+        }
+        throw error;
       } finally {
         // Clear the in-flight slot; the entry itself (with fresh token / expiry)
         // is updated inside _doFetchServiceToken before we land here.
         const settled = this._serviceTokenCache.get(cacheKey);
-        if (settled) {
+        if (settled?.pending === pending) {
           settled.pending = null;
         }
       }
@@ -595,6 +691,218 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    // =======================================================================
+    // "Sign in with Oxy" — handoff (Workstream C)
+    //
+    // Two mechanisms share the same challenge/verify + device-flow primitives:
+    //   A. Same-device shared-keychain SSO (`signInWithSharedIdentity`): a
+    //      sibling native app silently mints its own session from the shared
+    //      identity key. No user interaction.
+    //   B. QR / app-to-app handoff: a relying party (`startCommonsSignIn` +
+    //      `pollCommonsSignIn` + the existing `claimSessionByToken`) and the
+    //      approver / Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn`
+    //      / `denyCommonsSignIn`). The approver signs with its PRIMARY local
+    //      key; the RP never sees the private key.
+    // =======================================================================
+
+    /**
+     * MECHANISM A — same-device shared-keychain SSO.
+     *
+     * Native-only. If this device holds a shared identity (the cross-app
+     * `group.so.oxy.shared` keychain key), prove control of it and mint a
+     * session: `requestChallenge(sharedPublicKey)` → `signChallengeWithSharedKey`
+     * → `verifyChallenge` (which plants the tokens). Returns `null` on web or
+     * when no shared identity is present — never throws for the absent-identity
+     * case, so a cold-boot caller can fall through to the next step.
+     *
+     * The cold-boot wiring that CALLS this lives in `OxyContext`
+     * (`@oxyhq/services`); this method just performs the exchange.
+     */
+    async signInWithSharedIdentity(
+      opts: { deviceName?: string; deviceFingerprint?: string } = {}
+    ): Promise<SessionLoginResponse | null> {
+      try {
+        // `hasSharedIdentity()` already returns false on web (the shared
+        // keychain is native-only), so this short-circuits the web case without
+        // a wasted challenge round-trip.
+        if (!(await KeyManager.hasSharedIdentity())) {
+          return null;
+        }
+        const sharedPublicKey = await KeyManager.getSharedPublicKey();
+        if (!sharedPublicKey) {
+          return null;
+        }
+
+        const { challenge } = await this.requestChallenge(sharedPublicKey);
+        const signed = await SignatureService.signChallengeWithSharedKey(challenge);
+
+        // `signed.challenge` carries the SIGNATURE (mirrors `signChallenge`).
+        return await this.verifyChallenge(
+          signed.publicKey,
+          challenge,
+          signed.challenge,
+          signed.timestamp,
+          opts.deviceName,
+          opts.deviceFingerprint,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.
+     *
+     * Generates a secret device-flow `sessionToken` client-side (it never
+     * appears in the QR), registers it with `POST /auth/session/create`, and
+     * returns the server-issued public `authorizeCode` + ready-to-render
+     * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
+     * approver resolves the code and authorizes. Then poll with
+     * {@link pollCommonsSignIn} and, on `authorized`, exchange the
+     * `sessionToken` via the existing `claimSessionByToken`.
+     *
+     * @param params.clientId - The RP's registered OAuth client id
+     *   (ApplicationCredential publicKey); required so the server can resolve the
+     *   requesting application's identity.
+     */
+    async startCommonsSignIn(params: { clientId: string }): Promise<CommonsSignInHandle> {
+      try {
+        // High-entropy opaque secret token (256-bit hex). Generated client-side
+        // and held only here; the server stores it but never returns it in the
+        // QR. Reuses the platform-safe random generator.
+        const sessionToken = await SignatureService.generateChallenge();
+        const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
+
+        const res = await this.makeRequest<CommonsSessionCreateResponse>(
+          'POST',
+          '/auth/session/create',
+          { sessionToken, expiresAt, clientId: params.clientId },
+          { cache: false }
+        );
+
+        return {
+          sessionToken,
+          authorizeCode: res.authorizeCode,
+          qrPayload: res.qrPayload,
+          expiresAt: res.expiresAt ?? expiresAt,
+          status: res.status,
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (relying party) — poll a device-flow session for approval.
+     *
+     * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
+     * caller exchanges the secret `sessionToken` via the existing
+     * `claimSessionByToken` to mint the first access token.
+     *
+     * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+     */
+    async pollCommonsSignIn(sessionToken: string): Promise<CommonsSignInStatus> {
+      try {
+        return await this.makeRequest<CommonsSignInStatus>(
+          'GET',
+          `/auth/session/status/${encodeURIComponent(sessionToken)}`,
+          undefined,
+          { cache: false, retry: false }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
+     * sign-in request from its public `authorizeCode`.
+     *
+     * The returned `application` is resolved server-side and is the only safe
+     * thing to display in the approval UI — NEVER trust the app/name/origin
+     * strings carried in the QR payload. Public (no auth required).
+     *
+     * @param authorizeCode - The public code scanned from the QR / deep-link.
+     */
+    async getCommonsApprovalInfo(authorizeCode: string): Promise<CommonsApprovalInfo> {
+      try {
+        return await this.makeRequest<CommonsApprovalInfo>(
+          'GET',
+          `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`,
+          undefined,
+          { cache: false }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (approver / Commons) — approve a sign-in request by signing a
+     * fresh challenge with the PRIMARY local identity key.
+     *
+     * Commons holds the user's identity as its primary key (not the shared
+     * key), so this uses `signChallenge`. The signed-but-cookieless authorize
+     * endpoint resolves the user from the verified signer — the RP that started
+     * the flow then claims its session. Native-only (requires a local identity).
+     *
+     * @param params.authorizeCode - The public code being approved.
+     * @param params.deviceName - Optional human-readable device label.
+     * @param params.deviceFingerprint - Optional device fingerprint.
+     */
+    async approveCommonsSignIn(params: {
+      authorizeCode: string;
+      deviceName?: string;
+      deviceFingerprint?: string;
+    }): Promise<CommonsSignInActionResult> {
+      try {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+          throw new Error('No identity found on this device. Create or import an identity first.');
+        }
+
+        const { challenge } = await this.requestChallenge(publicKey);
+        const signed = await SignatureService.signChallenge(challenge);
+
+        return await this.makeRequest<CommonsSignInActionResult>(
+          'POST',
+          `/auth/session/authorize-signed/${encodeURIComponent(params.authorizeCode)}`,
+          {
+            // `signed.challenge` carries the SIGNATURE; `challenge` is the
+            // original server-issued challenge string.
+            publicKey: signed.publicKey,
+            challenge,
+            signature: signed.challenge,
+            timestamp: signed.timestamp,
+            ...(params.deviceName ? { deviceName: params.deviceName } : {}),
+            ...(params.deviceFingerprint ? { deviceFingerprint: params.deviceFingerprint } : {}),
+          },
+          { cache: false }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * MECHANISM B (approver / Commons) — deny a sign-in request, cancelling the
+     * device-flow session so the RP stops waiting.
+     *
+     * @param authorizeCode - The public code being denied.
+     */
+    async denyCommonsSignIn(authorizeCode: string): Promise<CommonsSignInActionResult> {
+      try {
+        return await this.makeRequest<CommonsSignInActionResult>(
+          'POST',
+          `/auth/session/deny/${encodeURIComponent(authorizeCode)}`,
+          undefined,
+          { cache: false }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Refresh every device-local refresh-cookie slot in a single round trip
      * (Google-style multi-account rebuild).