@invisi-labs/primitives 1.2.0 → 1.2.1

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ReceivingAddress } from './address.cjs';
 export { DecodedAddress, ReceivingKeyLookup, decodeAddress } from './address.cjs';
-import { N as NoteBytes, a as NoteDecryptionContext, C as CreditStateDecryptionContext } from './encryption-0HQXc3tT.cjs';
-export { b as CreditStateEncryptionContext, c as NoteEncryptionContext, d as decryptCreditState, e as decryptPrivateTransferNote, f as encryptCreditState, g as encryptPrivateTransferNote } from './encryption-0HQXc3tT.cjs';
+import { N as NoteBytes, a as NoteDecryptionContext, C as CreditStateDecryptionContext } from './encryption-P2HJ89FQ.cjs';
+export { b as CreditStateEncryptionContext, c as NoteEncryptionContext, d as decryptCreditState, e as decryptPrivateTransferNote, f as encryptCreditState, g as encryptPrivateTransferNote } from './encryption-P2HJ89FQ.cjs';
 import { a as CreditState, b as CreditPolicy, c as CreditUsage, N as Note, P as ProtocolContext, C as CreditDeliveryState, d as CreditDataV1, F as FundsDataV1 } from './types-CEAuh35C.cjs';
 export { e as CreditStateRecovery, M as MAX_MEMO_BYTES, f as Memo, R as ReceivingKeys, g as decodeMemoText, h as encodeMemo } from './types-CEAuh35C.cjs';
 export { computeNoteCommitment, computeNoteIdentity, computeNoteNullifier } from './note.cjs';
@@ -465,10 +465,23 @@ declare function acceptWalletResponses(prepared: readonly PreparedWalletRequest[
 
 declare function provenanceIntentHash(originalRequestHash: string): string;
 
+type DeliveryDecryptionResult = Uint8Array | null | {
+    status: "authentication-failed";
+};
+interface DeliveryDetectionCandidate extends NoteDecryptionContext {
+    role: "funds" | "owner" | "spender";
+    clue: `0x${string}`;
+    ciphertext: `0x${string}`;
+}
+interface DeliveryDetectionBatch {
+    ownerAddress: `0x${string}`;
+    results: readonly ("candidate" | "not-recipient" | "unresolved")[];
+}
 /** App-owned decryption. Only null means nonrecipient; operational failures must reject. */
 interface DeliveryDecryptor {
-    decryptNote(envelope: NoteBytes, context: NoteDecryptionContext): Promise<Uint8Array | null>;
-    decryptCredit(envelope: NoteBytes, context: CreditStateDecryptionContext): Promise<Uint8Array | null>;
+    detect?(candidates: readonly DeliveryDetectionCandidate[]): Promise<DeliveryDetectionBatch>;
+    decryptNote(envelope: NoteBytes, context: NoteDecryptionContext): Promise<DeliveryDecryptionResult>;
+    decryptCredit(envelope: NoteBytes, context: CreditStateDecryptionContext): Promise<DeliveryDecryptionResult>;
 }
 /** Keeps App failures and invalid plaintext distinct from unrelated local scan candidates. */
 declare class DeliveryDecryptionError extends Error {
@@ -477,6 +490,7 @@ declare class DeliveryDecryptionError extends Error {
 /** Bind untrusted App plaintext to the requested wallet, deployment, token and commitment. */
 declare function authenticatedDecryptor(wallet: Wallet, decryptor: DeliveryDecryptor): {
     ownerAddress: `0x${string}`;
+    detectCandidates(candidates: readonly DeliveryDetectionCandidate[]): Promise<any[]>;
     decryptNote(envelope: NoteBytes, context: Omit<NoteDecryptionContext, "ownerAddress">): Promise<{
         chainId: bigint;
         protocolAddress: bigint;
@@ -489,4 +503,9 @@ declare function authenticatedDecryptor(wallet: Wallet, decryptor: DeliveryDecry
     decryptCredit(envelope: NoteBytes, context: Omit<CreditStateDecryptionContext, "ownerAddress">): Promise<CreditDeliveryState | null>;
 };
 
-export { type Address, AuthorizedStatement, CreditDataV1, CreditDeliveryState, type CreditOpening, CreditPolicy, CreditState, CreditStateDecryptionContext, CreditUsage, D_CNULL, D_CREDIT, D_CREDIT_KEY_HASH, D_CREDIT_RECOVERY, D_CREDIT_STATE_NONCE, D_IDENT, D_NOTE, D_NULL, DeliveryDecryptionError, type DeliveryDecryptor, type DeliveryKind, Detector, Disclosure, type DisclosureExport, type DisclosureOutput, type DisclosureResult, FIELD_MODULUS, FundsDataV1, type Hex, MAX_CIPHERTEXT_BYTES, MAX_WALLET_BATCH_BYTES, MissingCapabilityError, NativeWalletError, Note, NoteBytes, NoteDecryptionContext, NullifierCapability, type PreparedWalletRequest, ProtocolContext, ReceivingAddress, type SigningRequest, TREE_DEPTH, ViewingCapability, WALLET_AUTHORIZATION_TYPES, Wallet, type WalletAcceptedResults, type WalletAuthorizationRequest, type WalletAuthorizationWitness, type WalletBytes, type WalletDecryptContext, type WalletHex, type WalletMethod, type WalletOperation, type WalletParams, type WalletRequest, type WalletResponse, type WalletResults, type WalletWireContext, acceptWalletResponse, acceptWalletResponses, authenticatedDecryptor, computeOwnerAddress, computeWalletAuthorizationDigest, createClue, createClueFromSeed, createSigningRequest, creditV1, decodeDeliveryHeader, deliveryCodec, deliveryHeader, deriveClueKey, fundsV1, generateCreditSharedKey, generateNonce, poseidonHash, prepareWalletRequest, provenanceIntentHash, validateClueKey, validateDeliveryCiphertext, validateWalletBatch, validateWalletResponses, verifyWalletAuthorization, viewingPublicKey, walletAuthorizationTypedData };
+/** AEAD failure is ambiguous: wrong recipient key, wrong context or damaged ciphertext. */
+declare class DeliveryAuthenticationError extends Error {
+    constructor(cause?: unknown);
+}
+
+export { type Address, AuthorizedStatement, CreditDataV1, CreditDeliveryState, type CreditOpening, CreditPolicy, CreditState, CreditStateDecryptionContext, CreditUsage, D_CNULL, D_CREDIT, D_CREDIT_KEY_HASH, D_CREDIT_RECOVERY, D_CREDIT_STATE_NONCE, D_IDENT, D_NOTE, D_NULL, DeliveryAuthenticationError, DeliveryDecryptionError, type DeliveryDecryptionResult, type DeliveryDecryptor, type DeliveryDetectionBatch, type DeliveryDetectionCandidate, type DeliveryKind, Detector, Disclosure, type DisclosureExport, type DisclosureOutput, type DisclosureResult, FIELD_MODULUS, FundsDataV1, type Hex, MAX_CIPHERTEXT_BYTES, MAX_WALLET_BATCH_BYTES, MissingCapabilityError, NativeWalletError, Note, NoteBytes, NoteDecryptionContext, NullifierCapability, type PreparedWalletRequest, ProtocolContext, ReceivingAddress, type SigningRequest, TREE_DEPTH, ViewingCapability, WALLET_AUTHORIZATION_TYPES, Wallet, type WalletAcceptedResults, type WalletAuthorizationRequest, type WalletAuthorizationWitness, type WalletBytes, type WalletDecryptContext, type WalletHex, type WalletMethod, type WalletOperation, type WalletParams, type WalletRequest, type WalletResponse, type WalletResults, type WalletWireContext, acceptWalletResponse, acceptWalletResponses, authenticatedDecryptor, computeOwnerAddress, computeWalletAuthorizationDigest, createClue, createClueFromSeed, createSigningRequest, creditV1, decodeDeliveryHeader, deliveryCodec, deliveryHeader, deriveClueKey, fundsV1, generateCreditSharedKey, generateNonce, poseidonHash, prepareWalletRequest, provenanceIntentHash, validateClueKey, validateDeliveryCiphertext, validateWalletBatch, validateWalletResponses, verifyWalletAuthorization, viewingPublicKey, walletAuthorizationTypedData };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ReceivingAddress } from './address.js';
 export { DecodedAddress, ReceivingKeyLookup, decodeAddress } from './address.js';
-import { N as NoteBytes, a as NoteDecryptionContext, C as CreditStateDecryptionContext } from './encryption-D06YBTW0.js';
-export { b as CreditStateEncryptionContext, c as NoteEncryptionContext, d as decryptCreditState, e as decryptPrivateTransferNote, f as encryptCreditState, g as encryptPrivateTransferNote } from './encryption-D06YBTW0.js';
+import { N as NoteBytes, a as NoteDecryptionContext, C as CreditStateDecryptionContext } from './encryption-Bzsl9VQk.js';
+export { b as CreditStateEncryptionContext, c as NoteEncryptionContext, d as decryptCreditState, e as decryptPrivateTransferNote, f as encryptCreditState, g as encryptPrivateTransferNote } from './encryption-Bzsl9VQk.js';
 import { a as CreditState, b as CreditPolicy, c as CreditUsage, N as Note, P as ProtocolContext, C as CreditDeliveryState, d as CreditDataV1, F as FundsDataV1 } from './types-CEAuh35C.js';
 export { e as CreditStateRecovery, M as MAX_MEMO_BYTES, f as Memo, R as ReceivingKeys, g as decodeMemoText, h as encodeMemo } from './types-CEAuh35C.js';
 export { computeNoteCommitment, computeNoteIdentity, computeNoteNullifier } from './note.js';
@@ -465,10 +465,23 @@ declare function acceptWalletResponses(prepared: readonly PreparedWalletRequest[
 
 declare function provenanceIntentHash(originalRequestHash: string): string;
 
+type DeliveryDecryptionResult = Uint8Array | null | {
+    status: "authentication-failed";
+};
+interface DeliveryDetectionCandidate extends NoteDecryptionContext {
+    role: "funds" | "owner" | "spender";
+    clue: `0x${string}`;
+    ciphertext: `0x${string}`;
+}
+interface DeliveryDetectionBatch {
+    ownerAddress: `0x${string}`;
+    results: readonly ("candidate" | "not-recipient" | "unresolved")[];
+}
 /** App-owned decryption. Only null means nonrecipient; operational failures must reject. */
 interface DeliveryDecryptor {
-    decryptNote(envelope: NoteBytes, context: NoteDecryptionContext): Promise<Uint8Array | null>;
-    decryptCredit(envelope: NoteBytes, context: CreditStateDecryptionContext): Promise<Uint8Array | null>;
+    detect?(candidates: readonly DeliveryDetectionCandidate[]): Promise<DeliveryDetectionBatch>;
+    decryptNote(envelope: NoteBytes, context: NoteDecryptionContext): Promise<DeliveryDecryptionResult>;
+    decryptCredit(envelope: NoteBytes, context: CreditStateDecryptionContext): Promise<DeliveryDecryptionResult>;
 }
 /** Keeps App failures and invalid plaintext distinct from unrelated local scan candidates. */
 declare class DeliveryDecryptionError extends Error {
@@ -477,6 +490,7 @@ declare class DeliveryDecryptionError extends Error {
 /** Bind untrusted App plaintext to the requested wallet, deployment, token and commitment. */
 declare function authenticatedDecryptor(wallet: Wallet, decryptor: DeliveryDecryptor): {
     ownerAddress: `0x${string}`;
+    detectCandidates(candidates: readonly DeliveryDetectionCandidate[]): Promise<any[]>;
     decryptNote(envelope: NoteBytes, context: Omit<NoteDecryptionContext, "ownerAddress">): Promise<{
         chainId: bigint;
         protocolAddress: bigint;
@@ -489,4 +503,9 @@ declare function authenticatedDecryptor(wallet: Wallet, decryptor: DeliveryDecry
     decryptCredit(envelope: NoteBytes, context: Omit<CreditStateDecryptionContext, "ownerAddress">): Promise<CreditDeliveryState | null>;
 };
 
-export { type Address, AuthorizedStatement, CreditDataV1, CreditDeliveryState, type CreditOpening, CreditPolicy, CreditState, CreditStateDecryptionContext, CreditUsage, D_CNULL, D_CREDIT, D_CREDIT_KEY_HASH, D_CREDIT_RECOVERY, D_CREDIT_STATE_NONCE, D_IDENT, D_NOTE, D_NULL, DeliveryDecryptionError, type DeliveryDecryptor, type DeliveryKind, Detector, Disclosure, type DisclosureExport, type DisclosureOutput, type DisclosureResult, FIELD_MODULUS, FundsDataV1, type Hex, MAX_CIPHERTEXT_BYTES, MAX_WALLET_BATCH_BYTES, MissingCapabilityError, NativeWalletError, Note, NoteBytes, NoteDecryptionContext, NullifierCapability, type PreparedWalletRequest, ProtocolContext, ReceivingAddress, type SigningRequest, TREE_DEPTH, ViewingCapability, WALLET_AUTHORIZATION_TYPES, Wallet, type WalletAcceptedResults, type WalletAuthorizationRequest, type WalletAuthorizationWitness, type WalletBytes, type WalletDecryptContext, type WalletHex, type WalletMethod, type WalletOperation, type WalletParams, type WalletRequest, type WalletResponse, type WalletResults, type WalletWireContext, acceptWalletResponse, acceptWalletResponses, authenticatedDecryptor, computeOwnerAddress, computeWalletAuthorizationDigest, createClue, createClueFromSeed, createSigningRequest, creditV1, decodeDeliveryHeader, deliveryCodec, deliveryHeader, deriveClueKey, fundsV1, generateCreditSharedKey, generateNonce, poseidonHash, prepareWalletRequest, provenanceIntentHash, validateClueKey, validateDeliveryCiphertext, validateWalletBatch, validateWalletResponses, verifyWalletAuthorization, viewingPublicKey, walletAuthorizationTypedData };
+/** AEAD failure is ambiguous: wrong recipient key, wrong context or damaged ciphertext. */
+declare class DeliveryAuthenticationError extends Error {
+    constructor(cause?: unknown);
+}
+
+export { type Address, AuthorizedStatement, CreditDataV1, CreditDeliveryState, type CreditOpening, CreditPolicy, CreditState, CreditStateDecryptionContext, CreditUsage, D_CNULL, D_CREDIT, D_CREDIT_KEY_HASH, D_CREDIT_RECOVERY, D_CREDIT_STATE_NONCE, D_IDENT, D_NOTE, D_NULL, DeliveryAuthenticationError, DeliveryDecryptionError, type DeliveryDecryptionResult, type DeliveryDecryptor, type DeliveryDetectionBatch, type DeliveryDetectionCandidate, type DeliveryKind, Detector, Disclosure, type DisclosureExport, type DisclosureOutput, type DisclosureResult, FIELD_MODULUS, FundsDataV1, type Hex, MAX_CIPHERTEXT_BYTES, MAX_WALLET_BATCH_BYTES, MissingCapabilityError, NativeWalletError, Note, NoteBytes, NoteDecryptionContext, NullifierCapability, type PreparedWalletRequest, ProtocolContext, ReceivingAddress, type SigningRequest, TREE_DEPTH, ViewingCapability, WALLET_AUTHORIZATION_TYPES, Wallet, type WalletAcceptedResults, type WalletAuthorizationRequest, type WalletAuthorizationWitness, type WalletBytes, type WalletDecryptContext, type WalletHex, type WalletMethod, type WalletOperation, type WalletParams, type WalletRequest, type WalletResponse, type WalletResults, type WalletWireContext, acceptWalletResponse, acceptWalletResponses, authenticatedDecryptor, computeOwnerAddress, computeWalletAuthorizationDigest, createClue, createClueFromSeed, createSigningRequest, creditV1, decodeDeliveryHeader, deliveryCodec, deliveryHeader, deriveClueKey, fundsV1, generateCreditSharedKey, generateNonce, poseidonHash, prepareWalletRequest, provenanceIntentHash, validateClueKey, validateDeliveryCiphertext, validateWalletBatch, validateWalletResponses, verifyWalletAuthorization, viewingPublicKey, walletAuthorizationTypedData };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   computeNoteNullifier
-} from "./chunk-TJYV6KTQ.js";
+} from "./chunk-XM4B6K37.js";
 import {
   CREDIT_POLICY_FIELDS,
   CREDIT_USAGE_FIELDS,
@@ -12,6 +12,7 @@ import {
   D_IDENT,
   D_NOTE,
   D_NULL,
+  DeliveryAuthenticationError,
   FIELD_MODULUS,
   MAX_CIPHERTEXT_BYTES,
   TREE_DEPTH,
@@ -49,7 +50,7 @@ import {
   validateContext,
   validateDeliveryCiphertext,
   viewingPublicKey
-} from "./chunk-PRUUPDVD.js";
+} from "./chunk-QAC5T4S5.js";
 import {
   MissingCapabilityError,
   ReceivingAddress,
@@ -915,6 +916,17 @@ function authenticatedDecryptor(wallet, decryptor) {
   const ownerAddress = wallet.ownerAddress;
   return {
     ownerAddress,
+    async detectCandidates(candidates) {
+      if (!decryptor.detect) return candidates.map(() => "candidate");
+      const result = await decryptor.detect(structuredClone(candidates));
+      if (!result || BigInt(result.ownerAddress) !== BigInt(ownerAddress) || !Array.isArray(result.results) || result.results.length !== candidates.length || result.results.some(
+        (value) => !["candidate", "not-recipient", "unresolved"].includes(value)
+      ))
+        throw new DeliveryDecryptionError(
+          new Error("invalid detection batch or wrong account")
+        );
+      return [...result.results];
+    },
     async decryptNote(envelope, context2) {
       context2 = { ...context2 };
       try {
@@ -922,6 +934,11 @@ function authenticatedDecryptor(wallet, decryptor) {
         const full = { ...context2, ownerAddress };
         const plaintext = await decryptor.decryptNote(bytes2.slice(), { ...full });
         if (plaintext === null) return null;
+        if (!(plaintext instanceof Uint8Array)) {
+          if (plaintext?.status === "authentication-failed")
+            throw new DeliveryAuthenticationError();
+          throw new Error("invalid decryption result");
+        }
         const codec = deliveryCodec(bytes2[0]);
         if (codec.kind !== "funds") throw new Error("unexpected envelope kind");
         const note = codec.decode(checkedPlaintext(plaintext, codec), full);
@@ -930,6 +947,7 @@ function authenticatedDecryptor(wallet, decryptor) {
         await noteCommitment(full, note);
         return note;
       } catch (cause) {
+        if (cause instanceof DeliveryAuthenticationError) throw cause;
         throw new DeliveryDecryptionError(cause);
       }
     },
@@ -940,6 +958,11 @@ function authenticatedDecryptor(wallet, decryptor) {
         const full = { ...context2, ownerAddress };
         const plaintext = await decryptor.decryptCredit(bytes2.slice(), { ...full });
         if (plaintext === null) return null;
+        if (!(plaintext instanceof Uint8Array)) {
+          if (plaintext?.status === "authentication-failed")
+            throw new DeliveryAuthenticationError();
+          throw new Error("invalid decryption result");
+        }
         const codec = deliveryCodec(bytes2[0]);
         if (codec.kind !== "credit") throw new Error("unexpected envelope kind");
         const state = codec.decode(checkedPlaintext(plaintext, codec), full);
@@ -954,6 +977,7 @@ function authenticatedDecryptor(wallet, decryptor) {
         await creditCommitment(full, state.note);
         return state;
       } catch (cause) {
+        if (cause instanceof DeliveryAuthenticationError) throw cause;
         throw new DeliveryDecryptionError(cause);
       }
     }
@@ -1242,6 +1266,7 @@ export {
   D_IDENT,
   D_NOTE,
   D_NULL,
+  DeliveryAuthenticationError,
   DeliveryDecryptionError,
   Detector,
   Disclosure,