@oxyhq/core 3.10.1 → 3.12.0

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;
             }

package/dist/esm/mixins/index.js

@@ -11,6 +11,7 @@ import { OxyServicesSilentAuthMixin } from './OxyServices.silent.js';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect.js';
 import { OxyServicesSsoMixin } from './OxyServices.sso.js';
 import { OxyServicesUserMixin } from './OxyServices.user.js';
+import { OxyServicesIdentityMixin } from './OxyServices.identity.js';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
 import { OxyServicesLanguageMixin } from './OxyServices.language.js';
 import { OxyServicesPaymentMixin } from './OxyServices.payment.js';
@@ -28,6 +29,7 @@ import { OxyServicesTopicsMixin } from './OxyServices.topics.js';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts.js';
 import { OxyServicesContactsMixin } from './OxyServices.contacts.js';
 import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
+import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -54,6 +56,8 @@ const MIXIN_PIPELINE = [
     OxyServicesSsoMixin,
     // User management (requires auth)
     OxyServicesUserMixin,
+    // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
+    OxyServicesIdentityMixin,
     OxyServicesPrivacyMixin,
     // Feature mixins
     OxyServicesLanguageMixin,
@@ -71,6 +75,8 @@ const MIXIN_PIPELINE = [
     OxyServicesManagedAccountsMixin,
     OxyServicesContactsMixin,
     OxyServicesAppDataMixin,
+    // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
+    OxyServicesCivicMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/dist/esm/server/cors.js

@@ -11,10 +11,9 @@
  *
  * `createOxyCors` returns a self-contained Express middleware (no `cors`
  * package dependency) that:
- *   - allows the Oxy apex origin family (anything under `*.${CENTRAL_IDP_APEX}`,
- *     i.e. `oxy.so` — covering `auth.oxy.so`, `api.oxy.so`, `accounts.oxy.so`,
- *     `console.oxy.so`, `inbox.oxy.so`, the marketing site, …) reusing the
- *     central-origin constants already in core, NOT a fresh hardcoded list,
+ *   - allows the Oxy apex origin family over HTTPS only: the apex plus
+ *     one-label subdomains such as `auth.oxy.so`, `api.oxy.so`,
+ *     `accounts.oxy.so`, `console.oxy.so`, and `inbox.oxy.so`,
  *   - allows the caller's explicit `appOrigins`,
  *   - DENIES everything else (no reflection, never a wildcard with credentials),
  *   - echoes back the EXACT matched origin (so credentialed requests work) and
@@ -24,7 +23,6 @@
  * Node/Express-only: exported solely from `@oxyhq/core/server`.
  */
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
-import { registrableApex } from '../utils/fapiAutoDetect.js';
 /** Default HTTP methods allowed across origins. */
 const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
 /** Default request headers a browser may send on a credentialed cross-origin call. */
@@ -38,29 +36,30 @@ const DEFAULT_ALLOWED_HEADERS = [
 ];
 /** How long (seconds) a browser may cache a successful preflight. */
 const DEFAULT_MAX_AGE_SECONDS = 86400;
+const OXY_ONE_LABEL_SUBDOMAIN_PATTERN = new RegExp(`^[a-z0-9-]+\\.${CENTRAL_IDP_APEX.replace('.', '\\.')}$`);
 /**
- * Whether `candidate` belongs to the Oxy apex origin family — i.e. its
- * registrable apex equals {@link CENTRAL_IDP_APEX} (`oxy.so`). This matches the
- * apex itself (`https://oxy.so`) and any subdomain (`https://auth.oxy.so`,
- * `https://api.oxy.so`, …) over http or https, ports allowed. Returns false on
- * any parse failure (fail closed).
+ * Whether `candidate` belongs to the built-in Oxy apex origin family. This
+ * intentionally mirrors the API allowlist shape: HTTPS only, no custom port,
+ * the apex itself (`https://oxy.so`), or exactly one lowercase subdomain label
+ * (`https://auth.oxy.so`, `https://api.oxy.so`, …).
+ *
+ * Arbitrary/multi-level subdomains and `http://*.oxy.so` are not implicitly
+ * trusted for credentialed CORS. If a service needs a non-standard development
+ * or tenant origin, it must opt in explicitly via `appOrigins`.
  */
 function isOxyFamilyOrigin(candidate) {
-    let hostname;
-    let protocol;
     try {
         const url = new URL(candidate);
-        hostname = url.hostname.toLowerCase();
-        protocol = url.protocol;
+        if (url.protocol !== 'https:' || url.port !== '')
+            return false;
+        const hostname = url.hostname;
+        if (hostname === CENTRAL_IDP_APEX)
+            return true;
+        return OXY_ONE_LABEL_SUBDOMAIN_PATTERN.test(hostname);
     }
     catch {
         return false;
     }
-    if (protocol !== 'https:' && protocol !== 'http:')
-        return false;
-    if (hostname === CENTRAL_IDP_APEX)
-        return true;
-    return registrableApex(hostname) === CENTRAL_IDP_APEX;
 }
 /** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
 function normalizeOrigin(raw) {
@@ -72,8 +71,8 @@ function normalizeOrigin(raw) {
     }
 }
 /**
- * Build the origin-matching predicate: true iff `origin` is in the Oxy apex
- * family OR exactly matches one of the configured app origins.
+ * Build the origin-matching predicate: true iff `origin` is in the built-in
+ * HTTPS Oxy apex family OR exactly matches one of the configured app origins.
  */
 function buildOriginAllowed(appOrigins) {
     const explicit = new Set();

package/dist/esm/server/rateLimit.js

@@ -19,12 +19,36 @@ function isBuiltInExempt(req) {
 function ipKeyGenerator(ip) {
     return ip.replace(/:/g, '_');
 }
-/** Resolve the rate-limit key: per authenticated user, else per (IPv6-safe) IP. */
-function resolveKey(req) {
+/**
+ * Resolve the trusted authenticated rate-limit key.
+ *
+ * `oxy.auth({ optional: true })` preserves legacy non-session user tokens by
+ * decoding their JWT claims locally. Those claims are not cryptographically
+ * verified and therefore MUST NOT influence abuse-control buckets. Only use
+ * identities that came from a server-validated session or a verified service
+ * token/delegation.
+ */
+function resolveTrustedAuthenticatedKey(req) {
     const userId = req.userId ?? req.user?.id ?? req.user?._id;
-    if (userId) {
+    if (userId && req.sessionId) {
         return `user:${userId}`;
     }
+    const delegatedUserId = req.serviceActingAs?.userId;
+    if (delegatedUserId && req.serviceApp?.appId) {
+        return `user:${delegatedUserId}`;
+    }
+    const serviceAppId = req.serviceApp?.appId;
+    if (serviceAppId) {
+        return `service:${serviceAppId}`;
+    }
+    return null;
+}
+/** Resolve the rate-limit key: per trusted authenticated identity, else per (IPv6-safe) IP. */
+function resolveKey(req) {
+    const authenticatedKey = resolveTrustedAuthenticatedKey(req);
+    if (authenticatedKey) {
+        return authenticatedKey;
+    }
     const ip = req.ip || req.socket.remoteAddress || 'unknown';
     return ipKeyGenerator(ip);
 }
@@ -41,9 +65,9 @@ export function createOxyRateLimit(oxy, options = {}) {
         windowMs,
         ...(store ? { store } : {}),
         max: (req) => {
-            const authed = req;
-            const userId = authed.userId ?? authed.user?.id ?? authed.user?._id;
-            return userId ? authenticatedMax : anonymousMax;
+            return resolveTrustedAuthenticatedKey(req)
+                ? authenticatedMax
+                : anonymousMax;
         },
         keyGenerator: (req) => resolveKey(req),
         message,
@@ -61,8 +85,8 @@ export function createOxyRateLimit(oxy, options = {}) {
         resolveSession(req, res, (err) => {
             if (err) {
                 // Optional auth never rejects; a token error just means "anonymous".
-                // Swallow the error and continue to limit as anonymous.
-                next();
+                // Swallow the error and continue through the anonymous limiter.
+                limiter(req, res, next);
                 return;
             }
             limiter(req, res, next);

package/dist/esm/utils/profileLinks.js

@@ -0,0 +1,49 @@
+function cleanUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url }`, using `entry.id` when present and falling back to the
+ *   entry index. Entries without a non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title). Empty/non-string values are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export function normalizeProfileLinks(linksMetadata, links) {
+    if (Array.isArray(linksMetadata) && linksMetadata.length > 0) {
+        const result = [];
+        linksMetadata.forEach((entry, index) => {
+            const url = cleanUrl(entry?.url);
+            if (!url)
+                return;
+            const id = typeof entry?.id === 'string' && entry.id.trim().length > 0
+                ? entry.id
+                : String(index);
+            const title = typeof entry?.title === 'string' ? entry.title : undefined;
+            result.push({ id, url, ...(title !== undefined ? { title } : {}) });
+        });
+        return result;
+    }
+    if (Array.isArray(links) && links.length > 0) {
+        const result = [];
+        links.forEach((value, index) => {
+            const url = cleanUrl(value);
+            if (!url)
+                return;
+            result.push({ id: String(index), url });
+        });
+        return result;
+    }
+    return [];
+}

package/dist/esm/utils/ssoReturn.js

@@ -237,7 +237,7 @@ export async function consumeSsoReturn(oxy, deps = {}) {
     }
     let session;
     try {
-        session = await oxy.exchangeSsoCode(ret.code);
+        session = await oxy.exchangeSsoCode(ret.code, ret.state);
     }
     catch (error) {
         onExchangeError?.(error);