@unicitylabs/sphere-sdk 0.7.1 → 0.7.2

package/dist/core/index.d.cts

@@ -2363,6 +2363,20 @@ declare function signMessage(privateKeyHex: string, message: string): string;
  * @returns `true` if the signature is valid and matches the expected public key
  */
 declare function verifySignedMessage(message: string, signature: string, expectedPubkey: string): boolean;
+/**
+ * Recover the compressed secp256k1 public key from a signed message.
+ *
+ * Use this when the server needs to identify the signer (not just verify
+ * a signature against a known pubkey). Combined with `sphere.resolve(pubkey)`
+ * it gives a fully cryptographically-attributable identity for backend auth,
+ * without trusting any client-supplied identifier claim.
+ *
+ * @param message    - The plaintext that was signed
+ * @param signature  - 130-char hex (v + r + s) as produced by `signMessage`
+ * @returns          - Compressed 66-char hex pubkey
+ * @throws           - On malformed signature length or out-of-range recovery byte
+ */
+declare function recoverPubkeyFromSignature(message: string, signature: string): string;
 
 /**
  * Result of an instant split send operation
@@ -6491,23 +6505,6 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
-/**
- * Compute the Unicity L3 DIRECT:// address that corresponds to a given
- * compressed secp256k1 public key.
- *
- * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
- * only uses the public key, so the private key is never needed. This lets
- * a backend trust only one thing from the client (the chain pubkey, whose
- * ownership the client proves via signature) and derive everything else
- * locally. Closes the entire class of "client claims an identifier the
- * server can't verify" bugs at the API level.
- *
- * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
- *                    (66 chars, leading 02 or 03).
- * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
- */
-declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
-
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6749,7 +6746,6 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
-
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7996,4 +7992,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.d.ts

@@ -2363,6 +2363,20 @@ declare function signMessage(privateKeyHex: string, message: string): string;
  * @returns `true` if the signature is valid and matches the expected public key
  */
 declare function verifySignedMessage(message: string, signature: string, expectedPubkey: string): boolean;
+/**
+ * Recover the compressed secp256k1 public key from a signed message.
+ *
+ * Use this when the server needs to identify the signer (not just verify
+ * a signature against a known pubkey). Combined with `sphere.resolve(pubkey)`
+ * it gives a fully cryptographically-attributable identity for backend auth,
+ * without trusting any client-supplied identifier claim.
+ *
+ * @param message    - The plaintext that was signed
+ * @param signature  - 130-char hex (v + r + s) as produced by `signMessage`
+ * @returns          - Compressed 66-char hex pubkey
+ * @throws           - On malformed signature length or out-of-range recovery byte
+ */
+declare function recoverPubkeyFromSignature(message: string, signature: string): string;
 
 /**
  * Result of an instant split send operation
@@ -6491,23 +6505,6 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
-/**
- * Compute the Unicity L3 DIRECT:// address that corresponds to a given
- * compressed secp256k1 public key.
- *
- * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
- * only uses the public key, so the private key is never needed. This lets
- * a backend trust only one thing from the client (the chain pubkey, whose
- * ownership the client proves via signature) and derive everything else
- * locally. Closes the entire class of "client claims an identifier the
- * server can't verify" bugs at the API level.
- *
- * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
- *                    (66 chars, leading 02 or 03).
- * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
- */
-declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
-
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6749,7 +6746,6 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
-
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7996,4 +7992,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.js

@@ -4837,6 +4837,27 @@ function verifySignedMessage(message, signature, expectedPubkey) {
     return false;
   }
 }
+function recoverPubkeyFromSignature(message, signature) {
+  if (signature.length !== 130) {
+    throw new SphereError(
+      `Invalid signature length: expected 130 hex chars, got ${signature.length}`,
+      "SIGNING_ERROR"
+    );
+  }
+  const v = parseInt(signature.slice(0, 2), 16) - 31;
+  const r = signature.slice(2, 66);
+  const s = signature.slice(66, 130);
+  if (v < 0 || v > 3) {
+    throw new SphereError(
+      `Invalid recovery byte: v=${v} out of range [0..3]`,
+      "SIGNING_ERROR"
+    );
+  }
+  const hashHex = hashSignMessage(message);
+  const hashBytes = Buffer.from(hashHex, "hex");
+  const recovered = ec.recoverPubKey(hashBytes, { r, s }, v);
+  return recovered.encode("hex", true);
+}
 
 // l1/crypto.ts
 import CryptoJS3 from "crypto-js";
@@ -27373,42 +27394,27 @@ async function parseAndDecryptWalletDat(data, password, onProgress) {
 
 // core/Sphere.ts
 import { SigningService as SigningService2 } from "@unicitylabs/state-transition-sdk/lib/sign/SigningService";
-import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
-
-// core/address-derivation.ts
 import { TokenType as TokenType5 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
 import { HashAlgorithm as HashAlgorithm7 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
 import { UnmaskedPredicateReference as UnmaskedPredicateReference3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference";
-var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
-var COMPRESSED_PUBKEY_RE = /^(02|03)[0-9a-fA-F]{64}$/;
-async function computeDirectAddressFromChainPubkey(chainPubkey) {
-  if (typeof chainPubkey !== "string" || !COMPRESSED_PUBKEY_RE.test(chainPubkey)) {
-    throw new Error(
-      `computeDirectAddressFromChainPubkey: chainPubkey must be 66-char hex with 02/03 prefix, got "${String(chainPubkey).slice(0, 12)}..."`
-    );
-  }
-  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
-  const tokenType = new TokenType5(tokenTypeBytes);
-  const publicKeyBytes = Buffer.from(chainPubkey, "hex");
-  const predicateRef = await UnmaskedPredicateReference3.create(
-    tokenType,
-    "secp256k1",
-    publicKeyBytes,
-    HashAlgorithm7.SHA256
-  );
-  return (await predicateRef.toAddress()).toString();
-}
-
-// core/Sphere.ts
+import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
 function isValidNametag2(nametag) {
   if (isPhoneNumber(nametag)) return true;
   return /^[a-z0-9_-]{3,20}$/.test(nametag);
 }
+var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
   const signingService = await SigningService2.createFromSecret(secret);
-  const pubkeyHex = Buffer.from(signingService.publicKey).toString("hex");
-  return computeDirectAddressFromChainPubkey(pubkeyHex);
+  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
+  const tokenType = new TokenType5(tokenTypeBytes);
+  const predicateRef = UnmaskedPredicateReference3.create(
+    tokenType,
+    signingService.algorithm,
+    signingService.publicKey,
+    HashAlgorithm7.SHA256
+  );
+  return (await (await predicateRef).toAddress()).toString();
 }
 var Sphere = class _Sphere {
   // Singleton
@@ -30792,7 +30798,6 @@ export {
   base58Encode,
   bytesToHex3 as bytesToHex,
   checkNetworkHealth,
-  computeDirectAddressFromChainPubkey,
   computeHash160,
   convertBits,
   createAddress,
@@ -30850,6 +30855,7 @@ export {
   randomBytes2 as randomBytes,
   randomHex,
   randomUUID,
+  recoverPubkeyFromSignature,
   ripemd160,
   scanAddressesImpl,
   serializeEncrypted,