@oxy.so/core 7.26.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/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/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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.26.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,