@oxyhq/core 3.10.0 → 3.11.0

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

@@ -1,7 +1,15 @@
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
 import { loadNodeCrypto } from '../utils/platformCrypto.js';
 import { logger } from '../utils/loggerUtils.js';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
+/**
+ * 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;
 /**
  * Sentinel error raised when getServiceToken() is called with a known apiKey
  * but a non-matching secret. Indicates either credential drift in the caller
@@ -143,11 +151,25 @@ export function OxyServicesAuthMixin(Base) {
             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;
                 }
             }
@@ -413,6 +435,173 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        // =======================================================================
+        // "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 = {}) {
+            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) {
+            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('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) {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                return await this.makeRequest('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) {
+            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('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) {
+            try {
+                return await this.makeRequest('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).

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

@@ -0,0 +1,287 @@
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
+import { CACHE_TIMES } from './mixinHelpers.js';
+/**
+ * Registrable apex the Oxy DID method is anchored on. A user's DID is
+ * `did:web:<OXY_IDENTITY_APEX>:u:<userId>`, anchored on the stable account id
+ * (NOT the keypair).
+ */
+const OXY_IDENTITY_APEX = 'oxy.so';
+/**
+ * Derive a user's Oxy DID from their stable account id.
+ * `did:web:oxy.so:u:<userId>`.
+ */
+export function buildUserDid(userId) {
+    return `did:web:${OXY_IDENTITY_APEX}:u:${userId}`;
+}
+export function OxyServicesIdentityMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Resolve the W3C DID document for any user. The API derives it on demand
+         * from the account's `authMethods` + `publicKey` — there is no stored
+         * document. Public (no auth required); short-TTL cached.
+         *
+         * @param userId - The account's Mongo `_id`. URL-encoded into the path.
+         */
+        async resolveDid(userId) {
+            try {
+                return await this.makeRequest('GET', `/u/${encodeURIComponent(userId)}/did.json`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * The current user's DID (`did:web:oxy.so:u:<userId>`), derived locally from
+         * the access token's user id. Throws if no user is authenticated.
+         */
+        getMyDid() {
+            const userId = this.getCurrentUserId();
+            if (!userId) {
+                throw new Error('No authenticated user — cannot derive DID.');
+            }
+            return buildUserDid(userId);
+        }
+        /** Resolve the current user's DID document. Requires an authenticated session. */
+        async getMyDidDocument() {
+            const userId = this.getCurrentUserId();
+            if (!userId) {
+                throw new Error('No authenticated user — cannot resolve DID document.');
+            }
+            return this.resolveDid(userId);
+        }
+        /**
+         * List the current user's linked authentication methods plus their DID.
+         * Each `identity` method carries a `verificationMethodId` linking it to its
+         * DID verification-method fragment.
+         */
+        async listAuthMethods() {
+            try {
+                return await this.makeRequest('GET', '/auth/methods', undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Link the on-device cryptographic identity to the current account,
+         * upgrading it from custodial to self-sovereign. Signs a proof of private
+         * key ownership and posts it to `POST /auth/link`.
+         *
+         * NATIVE-ONLY: requires a stored identity (throws if `KeyManager` has no key
+         * or no user is authenticated). The signed payload is
+         * `JSON.stringify({ action: 'link_identity', userId, timestamp })` — the
+         * exact bytes the server reconstructs and verifies.
+         */
+        async linkIdentityKey() {
+            try {
+                const userId = this.getCurrentUserId();
+                if (!userId) {
+                    throw new Error('No authenticated user — sign in before linking an identity key.');
+                }
+                const publicKey = await KeyManager.getPublicKey();
+                if (!publicKey) {
+                    throw new Error('No identity found on this device. Create or import an identity first.');
+                }
+                const timestamp = Date.now();
+                // The signed message MUST match the server's reconstruction byte-for-byte:
+                // JSON.stringify with this exact key order (action, userId, timestamp).
+                const message = JSON.stringify({ action: 'link_identity', userId, timestamp });
+                const signature = await SignatureService.sign(message);
+                const result = await this.makeRequest('POST', '/auth/link', { type: 'identity', publicKey, signature, timestamp }, { cache: false });
+                this._invalidateIdentityCaches(userId);
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Link password authentication to the current account. Adds a `password`
+         * auth method (does not remove existing methods).
+         *
+         * @param email - The email to associate with password auth.
+         * @param password - The new password (server enforces strength rules).
+         */
+        async linkPassword(email, password) {
+            try {
+                const result = await this.makeRequest('POST', '/auth/link', { type: 'password', email, password }, { cache: false });
+                this._invalidateIdentityCaches(this.getCurrentUserId());
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Unlink an authentication method from the current account. The server
+         * refuses to remove the last remaining method (the account would become
+         * inaccessible). Unlinking `identity` downgrades the account to custodial.
+         *
+         * @param type - The auth-method type to remove.
+         */
+        async unlinkAuthMethod(type) {
+            try {
+                const result = await this.makeRequest('DELETE', `/auth/link/${encodeURIComponent(type)}`, undefined, { cache: false });
+                this._invalidateIdentityCaches(this.getCurrentUserId());
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Sign a record with the on-device identity key, WITHOUT publishing it.
+         * The subject is the current user's DID. NATIVE-ONLY (requires a stored
+         * key). Use {@link publishRecord} to sign and store in one step.
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        async signRecord(type, record) {
+            const subject = this.getMyDid();
+            return SignatureService.signRecord(type, subject, record);
+        }
+        /**
+         * Sign a record and publish it to the append-only record store
+         * (`POST /identity/records`). NATIVE-ONLY (requires a stored key).
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        async publishRecord(type, record) {
+            try {
+                const envelope = await this.signRecord(type, record);
+                return await this.makeRequest('POST', '/identity/records', envelope, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Fetch a user's most recent signed record of a given type. Public (no auth
+         * required); short-TTL cached.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to fetch.
+         */
+        async getRecord(userId, type) {
+            try {
+                const res = await this.makeRequest('GET', `/identity/records/${encodeURIComponent(userId)}/${encodeURIComponent(type)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return res.record;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Ask the server to verify a user's stored record: it recomputes the
+         * canonical signing input, checks the signature, and asserts the signing key
+         * is a current verification method on the subject's DID.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to verify.
+         */
+        async verifyRecord(userId, type) {
+            try {
+                return await this.makeRequest('GET', `/identity/records/${encodeURIComponent(userId)}/${encodeURIComponent(type)}/verify`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Download the current user's signed, open-format data-export bundle
+         * (`GET /users/me/export`) — the "credible exit" snapshot. Always carries an
+         * Oxy provenance `attestation`; carries an optional client `proof` when the
+         * account holds its own key.
+         */
+        async exportMyData() {
+            try {
+                return await this.makeRequest('GET', '/users/me/export', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Start verifying ownership of a domain. Returns the instructions: publish
+         * EITHER the DNS-TXT record OR the `/.well-known/oxy-domain` file, then call
+         * {@link verifyDomain}.
+         *
+         * @param domain - The domain to claim (e.g. `nate.com`).
+         */
+        async requestDomainVerification(domain) {
+            try {
+                return await this.makeRequest('POST', '/identity/domains', { domain }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Complete domain verification: the server checks the DNS-TXT record or
+         * well-known file and, on success, attaches the domain to the account
+         * (surfaced in the DID's `alsoKnownAs` and the user's `verifiedDomains`).
+         *
+         * @param domain - The domain previously requested via
+         *   {@link requestDomainVerification}.
+         */
+        async verifyDomain(domain) {
+            try {
+                const result = await this.makeRequest('POST', `/identity/domains/${encodeURIComponent(domain)}/verify`, undefined, { cache: false });
+                this._invalidateIdentityCaches(this.getCurrentUserId());
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** List the current user's verified domains. */
+        async listDomains() {
+            try {
+                const res = await this.makeRequest('GET', '/identity/domains', undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return res.domains ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Remove a verified domain from the current account.
+         * @param domain - The verified domain to remove.
+         */
+        async removeDomain(domain) {
+            try {
+                const result = await this.makeRequest('DELETE', `/identity/domains/${encodeURIComponent(domain)}`, undefined, { cache: false });
+                this._invalidateIdentityCaches(this.getCurrentUserId());
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Bust the cached reads that an identity mutation invalidates: the current
+         * user (`/users/me*`), the linked auth-methods list, the verified-domains
+         * list, and the user's derived DID document (which embeds auth methods +
+         * verified domains, so it goes stale on link/unlink/domain changes).
+         *
+         * Internal helper (leading underscore); not part of the supported public
+         * surface. 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).
+         */
+        _invalidateIdentityCaches(userId) {
+            this.clearCacheByPrefix('GET:/users/me');
+            this.clearCacheEntry('GET:/auth/methods');
+            this.clearCacheEntry('GET:/identity/domains');
+            if (userId) {
+                this.clearCacheEntry(`GET:/u/${encodeURIComponent(userId)}/did.json`);
+            }
+        }
+    };
+}

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

@@ -23,6 +23,7 @@
  * `verifyChallenge` — so callers do NOT need to plant tokens manually.
  */
 import { createDebugLogger } from '../shared/utils/debugUtils.js';
+import { ssoStateKey } from '../utils/ssoBounce.js';
 const debug = createDebugLogger('SSO');
 /**
  * Generate a cryptographically secure state value for the SSO bounce.
@@ -42,6 +43,25 @@ export function generateSsoState() {
     }
     throw new Error('No secure random source available for SSO state generation');
 }
+/**
+ * Read the SSO bounce state stored for the current browser origin, if any.
+ *
+ * Returns `null` outside a browser (no `window`/`sessionStorage`) or when no
+ * state is stored — in which case the caller cannot (and must not) enforce a
+ * state match, e.g. native flows or pre-hydration callbacks that already
+ * validated the state before this exchange.
+ */
+function getStoredSsoStateForCurrentOrigin() {
+    if (typeof window === 'undefined' || !window.location || !window.sessionStorage) {
+        return null;
+    }
+    try {
+        return window.sessionStorage.getItem(ssoStateKey(window.location.origin));
+    }
+    catch {
+        return null;
+    }
+}
 export function OxyServicesSsoMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -68,12 +88,19 @@ export function OxyServicesSsoMixin(Base) {
          * @param code - The opaque single-use code delivered in the SSO return
          *   fragment (see {@link parseSsoReturnFragment}). The central store burns
          *   it atomically on exchange.
+         * @param state - The state value returned alongside the code. In browsers,
+         *   when an SSO bounce state is still stored for the current origin, this
+         *   must match before any token-committing exchange is attempted.
          * @returns The resolved {@link SessionLoginResponse}.
          */
-        async exchangeSsoCode(code) {
+        async exchangeSsoCode(code, state) {
             if (typeof code !== 'string' || code.length === 0) {
                 throw this.handleError(new Error('exchangeSsoCode requires a non-empty code'));
             }
+            const expectedState = getStoredSsoStateForCurrentOrigin();
+            if (expectedState !== null && (typeof state !== 'string' || state.length === 0 || state !== expectedState)) {
+                throw this.handleError(new Error('SSO exchange state mismatch'));
+            }
             const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/sso/exchange`;
             debug.log('Exchanging SSO code for session...');
             let response;

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

@@ -415,6 +415,7 @@ export function OxyServicesUserMixin(Base) {
                     url: `/users/me/data`,
                     params: { format },
                     cache: false,
+                    responseType: 'blob',
                 });
                 return result;
             }