@oxy.so/core 7.25.0 → 7.27.0

package/dist/cjs/api/identity.js

@@ -118,9 +118,26 @@ class IdentityApi {
      * 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.
+     *
+     * `{ fresh: true }` reads the document as it is NOW: it skips (and drops)
+     * this client's cached copy, is not joined to an in-flight read, and sends
+     * `Cache-Control: no-cache` so no HTTP cache on the way answers for the
+     * origin. Use it whenever the answer decides where money goes: `#key-1` is
+     * the account's Peable receive key and changes on a rotation or an
+     * organization key replacement, and a cached copy would derive an address
+     * from the previous key for up to the cache TTL.
      */
-    async resolveDid(userId) {
-        return this.ctx.request('GET', `/u/${encodeURIComponent(userId)}/did.json`, undefined, {
+    async resolveDid(userId, options = {}) {
+        const path = `/u/${encodeURIComponent(userId)}/did.json`;
+        if (options.fresh) {
+            this.ctx.http.invalidateCache({ keys: [`GET:${path}`] });
+            return this.ctx.request('GET', path, undefined, {
+                cache: false,
+                deduplicate: false,
+                headers: { 'Cache-Control': 'no-cache' },
+            });
+        }
+        return this.ctx.request('GET', path, undefined, {
             cache: true,
             cacheTTL: SHORT_TTL,
         });

package/dist/cjs/crypto/identityDerivations.js

@@ -65,6 +65,12 @@ function deriveScopedSeedFromKey(privateKeyHex, info) {
  * `HMAC-SHA256(SOCIAL_RECEIVE_CHAIN_CODE_KEY, compressed identity public key)`.
  * Identical to `@fairco.in/core`'s `deriveSocialReceiveSpendingKey`.
  *
+ * INTERNAL to `@oxy.so/core` (not exported from `@oxy.so/core/crypto`): the
+ * derivation is non-hardened and the chain code is a public function of the
+ * identity public key, so `identity = child - I_L mod n` — whoever holds one
+ * child private key and the public key holds the identity key. Callers get
+ * signatures ({@link signSocialReceiveDigest}), never the child key.
+ *
  * @returns the child private key and its compressed public key, lowercase hex.
  */
 function deriveSocialReceiveKey(privateKeyHex, index) {

package/dist/cjs/crypto/index.js

@@ -12,7 +12,7 @@
  * common chunk, which is the cost the lazy loading exists to avoid.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = exports.deriveSocialReceiveKey = exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
+exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
 // MUST stay the first import: the shim has to exist before any module below
 // evaluates or draws randomness (see `./polyfill`).
 require("./polyfill");
@@ -53,13 +53,16 @@ Object.defineProperty(exports, "AEAD_NONCE_LENGTH", { enumerable: true, get: fun
 var ecdh_1 = require("./ecdh");
 Object.defineProperty(exports, "deriveSharedSecret", { enumerable: true, get: function () { return ecdh_1.deriveSharedSecret; } });
 // What the identity key computes without leaving its holder: the same functions
-// Commons' identity host implements natively on Android.
+// Commons' identity host implements natively on Android. The social-receive
+// CHILD private key (`deriveSocialReceiveKey`) is deliberately not here: the
+// derivation is non-hardened under a chain code anyone can compute from the
+// public key, so one leaked child private key reveals the identity key. Only
+// signatures (`signSocialReceiveDigest`) leave this module.
 var identityDerivations_1 = require("./identityDerivations");
 Object.defineProperty(exports, "SCOPED_SEED_KDF_SALT", { enumerable: true, get: function () { return identityDerivations_1.SCOPED_SEED_KDF_SALT; } });
 Object.defineProperty(exports, "SOCIAL_RECEIVE_CHAIN_CODE_KEY", { enumerable: true, get: function () { return identityDerivations_1.SOCIAL_RECEIVE_CHAIN_CODE_KEY; } });
 Object.defineProperty(exports, "MAX_SOCIAL_RECEIVE_INDEX", { enumerable: true, get: function () { return identityDerivations_1.MAX_SOCIAL_RECEIVE_INDEX; } });
 Object.defineProperty(exports, "deriveScopedSeedFromKey", { enumerable: true, get: function () { return identityDerivations_1.deriveScopedSeedFromKey; } });
-Object.defineProperty(exports, "deriveSocialReceiveKey", { enumerable: true, get: function () { return identityDerivations_1.deriveSocialReceiveKey; } });
 Object.defineProperty(exports, "signSocialReceiveDigest", { enumerable: true, get: function () { return identityDerivations_1.signSocialReceiveDigest; } });
 Object.defineProperty(exports, "authChallengeDigest", { enumerable: true, get: function () { return identityDerivations_1.authChallengeDigest; } });
 // Identity proofs — the one signed format for operations on a personal root

package/dist/cjs/index.js

@@ -21,10 +21,10 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.StoreInstallerError = exports.setStoreInstaller = exports.getStoreInstaller = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.sameHolderIdentity = exports.retryAfterSecondsOf = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
-exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = void 0;
-exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = exports.isLocaleLoaded = exports.loadLocale = void 0;
-exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = void 0;
+exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.supportProviderOf = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.StoreInstallerError = exports.setStoreInstaller = exports.getStoreInstaller = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.sameHolderIdentity = exports.retryAfterSecondsOf = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
+exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = void 0;
+exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = exports.isLocaleLoaded = exports.loadLocale = exports.translate = void 0;
+exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = void 0;
 // The crypto shim MUST stay the first import. The root itself ships no crypto
 // library (`__tests__/rootEntryGraph.test.ts`), but `@oxy.so/protocol`'s root
 // entry (reached by the OAuth/PKCE and device helpers) does, and Metro does not
@@ -97,6 +97,7 @@ Object.defineProperty(exports, "getCanonicalUserHandle", { enumerable: true, get
 Object.defineProperty(exports, "getNormalizedUserHandle", { enumerable: true, get: function () { return userHandle_1.getNormalizedUserHandle; } });
 var profileLinks_1 = require("./utils/profileLinks");
 Object.defineProperty(exports, "normalizeProfileLinks", { enumerable: true, get: function () { return profileLinks_1.normalizeProfileLinks; } });
+Object.defineProperty(exports, "supportProviderOf", { enumerable: true, get: function () { return profileLinks_1.supportProviderOf; } });
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------

package/dist/cjs/utils/profileLinks.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeProfileLinks = normalizeProfileLinks;
+exports.supportProviderOf = supportProviderOf;
 function cleanUrl(value) {
     if (typeof value !== 'string')
         return null;
@@ -37,12 +38,14 @@ function normalizeProfileLinks(linksMetadata, links) {
             const title = typeof entry?.title === 'string' ? entry.title : undefined;
             const description = typeof entry?.description === 'string' ? entry.description : undefined;
             const image = typeof entry?.image === 'string' ? entry.image : undefined;
+            const faviconUrl = typeof entry?.faviconUrl === 'string' ? entry.faviconUrl : undefined;
             result.push({
                 id,
                 url,
                 ...(title !== undefined ? { title } : {}),
                 ...(description !== undefined ? { description } : {}),
                 ...(image !== undefined ? { image } : {}),
+                ...(faviconUrl !== undefined ? { faviconUrl } : {}),
             });
         });
         return result;
@@ -59,3 +62,34 @@ function normalizeProfileLinks(linksMetadata, links) {
     }
     return [];
 }
+const SUPPORT_PROVIDERS = [
+    { provider: { id: 'patreon', name: 'Patreon' }, hosts: ['patreon.com'] },
+    { provider: { id: 'kofi', name: 'Ko-fi' }, hosts: ['ko-fi.com'] },
+    { provider: { id: 'buymeacoffee', name: 'Buy Me a Coffee' }, hosts: ['buymeacoffee.com'] },
+    { provider: { id: 'github-sponsors', name: 'GitHub Sponsors' }, hosts: ['github.com'] },
+    { provider: { id: 'liberapay', name: 'Liberapay' }, hosts: ['liberapay.com'] },
+];
+/**
+ * The support platform a link points at, or `null`. GitHub Sponsors is the one
+ * host shared with ordinary GitHub pages, so only its `/sponsors/` path counts.
+ */
+function supportProviderOf(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+    for (const { provider, hosts } of SUPPORT_PROVIDERS) {
+        if (!hosts.some((known) => host === known || host.endsWith(`.${known}`)))
+            continue;
+        if (provider.id === 'github-sponsors' &&
+            !parsed.pathname.toLowerCase().startsWith('/sponsors/')) {
+            continue;
+        }
+        return provider;
+    }
+    return null;
+}

package/dist/esm/api/identity.js

@@ -80,9 +80,26 @@ export class IdentityApi {
      * 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.
+     *
+     * `{ fresh: true }` reads the document as it is NOW: it skips (and drops)
+     * this client's cached copy, is not joined to an in-flight read, and sends
+     * `Cache-Control: no-cache` so no HTTP cache on the way answers for the
+     * origin. Use it whenever the answer decides where money goes: `#key-1` is
+     * the account's Peable receive key and changes on a rotation or an
+     * organization key replacement, and a cached copy would derive an address
+     * from the previous key for up to the cache TTL.
      */
-    async resolveDid(userId) {
-        return this.ctx.request('GET', `/u/${encodeURIComponent(userId)}/did.json`, undefined, {
+    async resolveDid(userId, options = {}) {
+        const path = `/u/${encodeURIComponent(userId)}/did.json`;
+        if (options.fresh) {
+            this.ctx.http.invalidateCache({ keys: [`GET:${path}`] });
+            return this.ctx.request('GET', path, undefined, {
+                cache: false,
+                deduplicate: false,
+                headers: { 'Cache-Control': 'no-cache' },
+            });
+        }
+        return this.ctx.request('GET', path, undefined, {
             cache: true,
             cacheTTL: SHORT_TTL,
         });

package/dist/esm/crypto/identityDerivations.js

@@ -58,6 +58,12 @@ export function deriveScopedSeedFromKey(privateKeyHex, info) {
  * `HMAC-SHA256(SOCIAL_RECEIVE_CHAIN_CODE_KEY, compressed identity public key)`.
  * Identical to `@fairco.in/core`'s `deriveSocialReceiveSpendingKey`.
  *
+ * INTERNAL to `@oxy.so/core` (not exported from `@oxy.so/core/crypto`): the
+ * derivation is non-hardened and the chain code is a public function of the
+ * identity public key, so `identity = child - I_L mod n` — whoever holds one
+ * child private key and the public key holds the identity key. Callers get
+ * signatures ({@link signSocialReceiveDigest}), never the child key.
+ *
  * @returns the child private key and its compressed public key, lowercase hex.
  */
 export function deriveSocialReceiveKey(privateKeyHex, index) {

package/dist/esm/crypto/index.js

@@ -24,8 +24,12 @@ export { hkdfSha256 } from './kdf.js';
 export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead.js';
 export { deriveSharedSecret } from './ecdh.js';
 // What the identity key computes without leaving its holder: the same functions
-// Commons' identity host implements natively on Android.
-export { SCOPED_SEED_KDF_SALT, SOCIAL_RECEIVE_CHAIN_CODE_KEY, MAX_SOCIAL_RECEIVE_INDEX, deriveScopedSeedFromKey, deriveSocialReceiveKey, signSocialReceiveDigest, authChallengeDigest, } from './identityDerivations.js';
+// Commons' identity host implements natively on Android. The social-receive
+// CHILD private key (`deriveSocialReceiveKey`) is deliberately not here: the
+// derivation is non-hardened under a chain code anyone can compute from the
+// public key, so one leaked child private key reveals the identity key. Only
+// signatures (`signSocialReceiveDigest`) leave this module.
+export { SCOPED_SEED_KDF_SALT, SOCIAL_RECEIVE_CHAIN_CODE_KEY, MAX_SOCIAL_RECEIVE_INDEX, deriveScopedSeedFromKey, signSocialReceiveDigest, authChallengeDigest, } from './identityDerivations.js';
 // Identity proofs — the one signed format for operations on a personal root
 // (docs/adr/0024-one-oxy-account-root-holders.md D7)
 export { digestIdentityPayload, signIdentityProof } from './identityProof.js';

package/dist/esm/index.js

@@ -53,7 +53,7 @@ export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform
 // ---------------------------------------------------------------------------
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity.js';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle.js';
-export { normalizeProfileLinks } from './utils/profileLinks.js';
+export { normalizeProfileLinks, supportProviderOf } from './utils/profileLinks.js';
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------

package/dist/esm/utils/profileLinks.js

@@ -34,12 +34,14 @@ export function normalizeProfileLinks(linksMetadata, links) {
             const title = typeof entry?.title === 'string' ? entry.title : undefined;
             const description = typeof entry?.description === 'string' ? entry.description : undefined;
             const image = typeof entry?.image === 'string' ? entry.image : undefined;
+            const faviconUrl = typeof entry?.faviconUrl === 'string' ? entry.faviconUrl : undefined;
             result.push({
                 id,
                 url,
                 ...(title !== undefined ? { title } : {}),
                 ...(description !== undefined ? { description } : {}),
                 ...(image !== undefined ? { image } : {}),
+                ...(faviconUrl !== undefined ? { faviconUrl } : {}),
             });
         });
         return result;
@@ -56,3 +58,34 @@ export function normalizeProfileLinks(linksMetadata, links) {
     }
     return [];
 }
+const SUPPORT_PROVIDERS = [
+    { provider: { id: 'patreon', name: 'Patreon' }, hosts: ['patreon.com'] },
+    { provider: { id: 'kofi', name: 'Ko-fi' }, hosts: ['ko-fi.com'] },
+    { provider: { id: 'buymeacoffee', name: 'Buy Me a Coffee' }, hosts: ['buymeacoffee.com'] },
+    { provider: { id: 'github-sponsors', name: 'GitHub Sponsors' }, hosts: ['github.com'] },
+    { provider: { id: 'liberapay', name: 'Liberapay' }, hosts: ['liberapay.com'] },
+];
+/**
+ * The support platform a link points at, or `null`. GitHub Sponsors is the one
+ * host shared with ordinary GitHub pages, so only its `/sponsors/` path counts.
+ */
+export function supportProviderOf(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+    for (const { provider, hosts } of SUPPORT_PROVIDERS) {
+        if (!hosts.some((known) => host === known || host.endsWith(`.${known}`)))
+            continue;
+        if (provider.id === 'github-sponsors' &&
+            !parsed.pathname.toLowerCase().startsWith('/sponsors/')) {
+            continue;
+        }
+        return provider;
+    }
+    return null;
+}

package/dist/types/api/identity.d.ts

@@ -10,6 +10,15 @@ export interface VerifyDomainResult {
 export interface RemoveDomainResult {
     success: boolean;
 }
+/** Options for {@link IdentityApi.resolveDid}. */
+export interface ResolveDidOptions {
+    /**
+     * Read the document from the origin now, never from a cache. Required when
+     * `#key-1` decides where money goes (deriving a Peable receive address): the
+     * key changes on a rotation or an organization key replacement.
+     */
+    fresh?: boolean;
+}
 /** How the caller proves control of the CURRENT key during a key rotation. */
 export type RotateKeyProof = 'device' | 'phrase';
 /** Options for {@link IdentityApi.rotateKey}. */
@@ -93,8 +102,16 @@ export declare class IdentityApi {
      * 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.
+     *
+     * `{ fresh: true }` reads the document as it is NOW: it skips (and drops)
+     * this client's cached copy, is not joined to an in-flight read, and sends
+     * `Cache-Control: no-cache` so no HTTP cache on the way answers for the
+     * origin. Use it whenever the answer decides where money goes: `#key-1` is
+     * the account's Peable receive key and changes on a rotation or an
+     * organization key replacement, and a cached copy would derive an address
+     * from the previous key for up to the cache TTL.
      */
-    resolveDid(userId: string): Promise<DidDocument>;
+    resolveDid(userId: string, options?: ResolveDidOptions): Promise<DidDocument>;
     /**
      * The signed-in user's linked authentication methods plus their DID. Each
      * `identity` method carries a `verificationMethodId` linking it to its DID

package/dist/types/crypto/identityDerivations.d.ts

@@ -37,6 +37,12 @@ export declare function deriveScopedSeedFromKey(privateKeyHex: string, info: str
  * `HMAC-SHA256(SOCIAL_RECEIVE_CHAIN_CODE_KEY, compressed identity public key)`.
  * Identical to `@fairco.in/core`'s `deriveSocialReceiveSpendingKey`.
  *
+ * INTERNAL to `@oxy.so/core` (not exported from `@oxy.so/core/crypto`): the
+ * derivation is non-hardened and the chain code is a public function of the
+ * identity public key, so `identity = child - I_L mod n` — whoever holds one
+ * child private key and the public key holds the identity key. Callers get
+ * signatures ({@link signSocialReceiveDigest}), never the child key.
+ *
  * @returns the child private key and its compressed public key, lowercase hex.
  */
 export declare function deriveSocialReceiveKey(privateKeyHex: string, index: number): {

package/dist/types/crypto/index.d.ts

@@ -27,7 +27,7 @@ export { hkdfSha256 } from './kdf';
 export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead';
 export type { AeadResult } from './aead';
 export { deriveSharedSecret } from './ecdh';
-export { SCOPED_SEED_KDF_SALT, SOCIAL_RECEIVE_CHAIN_CODE_KEY, MAX_SOCIAL_RECEIVE_INDEX, deriveScopedSeedFromKey, deriveSocialReceiveKey, signSocialReceiveDigest, authChallengeDigest, } from './identityDerivations';
+export { SCOPED_SEED_KDF_SALT, SOCIAL_RECEIVE_CHAIN_CODE_KEY, MAX_SOCIAL_RECEIVE_INDEX, deriveScopedSeedFromKey, signSocialReceiveDigest, authChallengeDigest, } from './identityDerivations';
 export { digestIdentityPayload, signIdentityProof } from './identityProof';
 export { deriveIdentityLinkCode } from './identityLink';
 export { solveRegistrationPow } from './registrationPow';

package/dist/types/index.d.ts

@@ -41,7 +41,7 @@ export { DirectUploadInterruptedError } from './api/directUpload';
 export type { DirectUploadProgress } from './api/directUpload';
 export type { AssetsApi, AssetRecord, UploadedAsset, AssetLinkState, AssetUploadOptions, AssetUploadStageProgress, AssetLinkTarget, AssetDeleteResult, CompletedAssetUpload, LargeUploadOptions, LargeUploadProgress, LargeUploadResult, } from './api/assets';
 export { buildUserDid } from './api/identity';
-export type { IdentityApi, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './api/identity';
+export type { IdentityApi, VerifyDomainResult, RemoveDomainResult, ResolveDidOptions, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './api/identity';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './api/accounts';
 export type { AccountsApi, AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, } from './api/accounts';
 export type { AppsApi, AppAssertionsApi, Application, ApplicationCallerMembership, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, PublicApplication, ConnectedApp, ConnectedMcpClient, ApplicationDeleteResult, ApplicationFilesWebhook, } from './api/apps';
@@ -70,8 +70,8 @@ export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRout
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
-export { normalizeProfileLinks } from './utils/profileLinks';
-export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
+export { normalizeProfileLinks, supportProviderOf } from './utils/profileLinks';
+export type { ProfileLink, ProfileLinkMetadata, SupportProvider } from './utils/profileLinks';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';

package/dist/types/utils/profileLinks.d.ts

@@ -13,6 +13,8 @@ export interface ProfileLink {
     url: string;
     description?: string;
     image?: string;
+    /** Clarity's favicon for the link's host, when Clarity has one. */
+    faviconUrl?: string;
 }
 /** Source shape of a single `User.linksMetadata` entry. */
 export interface ProfileLinkMetadata {
@@ -21,6 +23,7 @@ export interface ProfileLinkMetadata {
     description?: string;
     image?: string;
     id?: string;
+    faviconUrl?: string;
 }
 /**
  * Normalizes a user's profile links into a clean display shape.
@@ -42,3 +45,13 @@ export interface ProfileLinkMetadata {
  * as `https://`; prefixing is a display concern left to the caller.
  */
 export declare function normalizeProfileLinks(linksMetadata?: ProfileLinkMetadata[], links?: string[]): ProfileLink[];
+/** A platform a profile can point supporters to, recognised by the link's host. */
+export interface SupportProvider {
+    id: 'patreon' | 'kofi' | 'buymeacoffee' | 'github-sponsors' | 'liberapay';
+    name: string;
+}
+/**
+ * The support platform a link points at, or `null`. GitHub Sponsors is the one
+ * host shared with ordinary GitHub pages, so only its `/sponsors/` path counts.
+ */
+export declare function supportProviderOf(url: string): SupportProvider | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.25.0",
+  "version": "7.27.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/api/identity.ts

@@ -68,6 +68,16 @@ export interface RemoveDomainResult {
   success: boolean;
 }
 
+/** Options for {@link IdentityApi.resolveDid}. */
+export interface ResolveDidOptions {
+  /**
+   * Read the document from the origin now, never from a cache. Required when
+   * `#key-1` decides where money goes (deriving a Peable receive address): the
+   * key changes on a rotation or an organization key replacement.
+   */
+  fresh?: boolean;
+}
+
 /** How the caller proves control of the CURRENT key during a key rotation. */
 export type RotateKeyProof = 'device' | 'phrase';
 
@@ -191,17 +201,29 @@ export class IdentityApi {
    * 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.
+   *
+   * `{ fresh: true }` reads the document as it is NOW: it skips (and drops)
+   * this client's cached copy, is not joined to an in-flight read, and sends
+   * `Cache-Control: no-cache` so no HTTP cache on the way answers for the
+   * origin. Use it whenever the answer decides where money goes: `#key-1` is
+   * the account's Peable receive key and changes on a rotation or an
+   * organization key replacement, and a cached copy would derive an address
+   * from the previous key for up to the cache TTL.
    */
-  async resolveDid(userId: string): Promise<DidDocument> {
-    return this.ctx.request<DidDocument>(
-      'GET',
-      `/u/${encodeURIComponent(userId)}/did.json`,
-      undefined,
-      {
-        cache: true,
-        cacheTTL: SHORT_TTL,
-      },
-    );
+  async resolveDid(userId: string, options: ResolveDidOptions = {}): Promise<DidDocument> {
+    const path = `/u/${encodeURIComponent(userId)}/did.json`;
+    if (options.fresh) {
+      this.ctx.http.invalidateCache({ keys: [`GET:${path}`] });
+      return this.ctx.request<DidDocument>('GET', path, undefined, {
+        cache: false,
+        deduplicate: false,
+        headers: { 'Cache-Control': 'no-cache' },
+      });
+    }
+    return this.ctx.request<DidDocument>('GET', path, undefined, {
+      cache: true,
+      cacheTTL: SHORT_TTL,
+    });
   }
 
   /**

package/src/crypto/identityDerivations.ts

@@ -73,6 +73,12 @@ export function deriveScopedSeedFromKey(privateKeyHex: string, info: string): Ui
  * `HMAC-SHA256(SOCIAL_RECEIVE_CHAIN_CODE_KEY, compressed identity public key)`.
  * Identical to `@fairco.in/core`'s `deriveSocialReceiveSpendingKey`.
  *
+ * INTERNAL to `@oxy.so/core` (not exported from `@oxy.so/core/crypto`): the
+ * derivation is non-hardened and the chain code is a public function of the
+ * identity public key, so `identity = child - I_L mod n` — whoever holds one
+ * child private key and the public key holds the identity key. Callers get
+ * signatures ({@link signSocialReceiveDigest}), never the child key.
+ *
  * @returns the child private key and its compressed public key, lowercase hex.
  */
 export function deriveSocialReceiveKey(

package/src/crypto/index.ts

@@ -57,13 +57,16 @@ export type { AeadResult } from './aead';
 export { deriveSharedSecret } from './ecdh';
 
 // What the identity key computes without leaving its holder: the same functions
-// Commons' identity host implements natively on Android.
+// Commons' identity host implements natively on Android. The social-receive
+// CHILD private key (`deriveSocialReceiveKey`) is deliberately not here: the
+// derivation is non-hardened under a chain code anyone can compute from the
+// public key, so one leaked child private key reveals the identity key. Only
+// signatures (`signSocialReceiveDigest`) leave this module.
 export {
   SCOPED_SEED_KDF_SALT,
   SOCIAL_RECEIVE_CHAIN_CODE_KEY,
   MAX_SOCIAL_RECEIVE_INDEX,
   deriveScopedSeedFromKey,
-  deriveSocialReceiveKey,
   signSocialReceiveDigest,
   authChallengeDigest,
 } from './identityDerivations';

package/src/index.ts

@@ -133,6 +133,7 @@ export type {
   IdentityApi,
   VerifyDomainResult,
   RemoveDomainResult,
+  ResolveDidOptions,
   RotateKeyProof,
   RotateKeyOptions,
   RotateKeyResult,
@@ -319,8 +320,8 @@ export {
   getNormalizedUserHandle,
 } from './utils/userHandle';
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
-export { normalizeProfileLinks } from './utils/profileLinks';
-export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
+export { normalizeProfileLinks, supportProviderOf } from './utils/profileLinks';
+export type { ProfileLink, ProfileLinkMetadata, SupportProvider } from './utils/profileLinks';
 
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)

package/src/utils/profileLinks.ts

@@ -13,6 +13,8 @@ export interface ProfileLink {
   url: string;
   description?: string;
   image?: string;
+  /** Clarity's favicon for the link's host, when Clarity has one. */
+  faviconUrl?: string;
 }
 
 /** Source shape of a single `User.linksMetadata` entry. */
@@ -22,6 +24,7 @@ export interface ProfileLinkMetadata {
   description?: string;
   image?: string;
   id?: string;
+  faviconUrl?: string;
 }
 
 function cleanUrl(value: unknown): string | null {
@@ -63,12 +66,14 @@ export function normalizeProfileLinks(
       const title = typeof entry?.title === 'string' ? entry.title : undefined;
       const description = typeof entry?.description === 'string' ? entry.description : undefined;
       const image = typeof entry?.image === 'string' ? entry.image : undefined;
+      const faviconUrl = typeof entry?.faviconUrl === 'string' ? entry.faviconUrl : undefined;
       result.push({
         id,
         url,
         ...(title !== undefined ? { title } : {}),
         ...(description !== undefined ? { description } : {}),
         ...(image !== undefined ? { image } : {}),
+        ...(faviconUrl !== undefined ? { faviconUrl } : {}),
       });
     });
     return result;
@@ -86,3 +91,42 @@ export function normalizeProfileLinks(
 
   return [];
 }
+
+/** A platform a profile can point supporters to, recognised by the link's host. */
+export interface SupportProvider {
+  id: 'patreon' | 'kofi' | 'buymeacoffee' | 'github-sponsors' | 'liberapay';
+  name: string;
+}
+
+const SUPPORT_PROVIDERS: readonly { provider: SupportProvider; hosts: readonly string[] }[] = [
+  { provider: { id: 'patreon', name: 'Patreon' }, hosts: ['patreon.com'] },
+  { provider: { id: 'kofi', name: 'Ko-fi' }, hosts: ['ko-fi.com'] },
+  { provider: { id: 'buymeacoffee', name: 'Buy Me a Coffee' }, hosts: ['buymeacoffee.com'] },
+  { provider: { id: 'github-sponsors', name: 'GitHub Sponsors' }, hosts: ['github.com'] },
+  { provider: { id: 'liberapay', name: 'Liberapay' }, hosts: ['liberapay.com'] },
+];
+
+/**
+ * The support platform a link points at, or `null`. GitHub Sponsors is the one
+ * host shared with ordinary GitHub pages, so only its `/sponsors/` path counts.
+ */
+export function supportProviderOf(url: string): SupportProvider | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+  for (const { provider, hosts } of SUPPORT_PROVIDERS) {
+    if (!hosts.some((known) => host === known || host.endsWith(`.${known}`))) continue;
+    if (
+      provider.id === 'github-sponsors' &&
+      !parsed.pathname.toLowerCase().startsWith('/sponsors/')
+    ) {
+      continue;
+    }
+    return provider;
+  }
+  return null;
+}