@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.15.0-bopen.1

package/out/src/utility/identityUtils.js

@@ -1,8 +1,264 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseResults = exports.queryOverlay = exports.transformVerifiableCertificatesWithTrust = void 0;
+exports.parseResults = exports.IdentityEvidenceVerifier = exports.queryOverlayEvidence = exports.queryOverlay = exports.transformVerifiableCertificatesWithTrust = void 0;
+exports.filterCertificatesByIdentityKey = filterCertificatesByIdentityKey;
+exports.filterCertificatesByAttributes = filterCertificatesByAttributes;
 exports.parseResults$ = parseResults$;
 const sdk_1 = require("@bsv/sdk");
+const utils_1 = require("@bsv/sdk/primitives/utils");
+const WalletSettingsManager_1 = require("../WalletSettingsManager");
+const MAX_IDENTITY_RESULTS = 256;
+const MAX_IDENTITY_CERTIFICATE_BYTES = 256 * 1024;
+const MAX_IDENTITY_FIELDS = 100;
+const IDENTITY_PROTOCOL = [1, 'identity'];
+const IDENTITY_KEY_ID = '1';
+// BRC-100 bounds a discovered certificate's certifierInfo.description to 5-50
+// UTF-8 bytes. Trust settings accept up to 500 so stored settings stay
+// readable, so the bound is applied where the result is built.
+const MIN_CERTIFIER_DESCRIPTION_BYTES = 5;
+const MAX_CERTIFIER_DESCRIPTION_BYTES = 50;
+const FALLBACK_CERTIFIER_DESCRIPTION = 'Trusted certifier';
+/** Cut a long description at a code point boundary; replace one too short to keep. */
+function certifierDescription(description) {
+    let kept = '';
+    let bytes = 0;
+    for (const char of description) {
+        const size = (0, utils_1.toArray)(char, 'utf8').length;
+        if (bytes + size > MAX_CERTIFIER_DESCRIPTION_BYTES)
+            break;
+        kept += char;
+        bytes += size;
+    }
+    kept = kept.trimEnd();
+    return (0, utils_1.toArray)(kept, 'utf8').length >= MIN_CERTIFIER_DESCRIPTION_BYTES ? kept : FALLBACK_CERTIFIER_DESCRIPTION;
+}
+function isPlainRecord(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function ownData(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor == null || !('value' in descriptor)) {
+        throw new Error(`Identity certificate ${key} must be an own data property`);
+    }
+    return descriptor.value;
+}
+function boundedBytes(value, field, minimum, maximum) {
+    const normalized = value instanceof Uint8Array ? Array.from(value) : value;
+    if (!Array.isArray(normalized) || normalized.length < minimum || normalized.length > maximum) {
+        throw new Error(`${field} must contain ${minimum}-${maximum} bytes`);
+    }
+    for (let index = 0; index < normalized.length; index++) {
+        if (!Object.prototype.hasOwnProperty.call(normalized, index) ||
+            !Number.isInteger(normalized[index]) ||
+            normalized[index] < 0 ||
+            normalized[index] > 255) {
+            throw new Error(`${field} must be a dense byte array`);
+        }
+    }
+    return Array.from(normalized);
+}
+function pushOpcode(value) {
+    if (value.length <= 75)
+        return value.length;
+    if (value.length <= 0xff)
+        return 0x4c;
+    if (value.length <= 0xffff)
+        return 0x4d;
+    return 0x4e;
+}
+function certificateRecord(encoded) {
+    const parsed = JSON.parse((0, utils_1.toUTF8Strict)(encoded));
+    if (!isPlainRecord(parsed))
+        throw new Error('Identity certificate must be a plain object');
+    const allowed = new Set([
+        'type',
+        'serialNumber',
+        'subject',
+        'certifier',
+        'revocationOutpoint',
+        'fields',
+        'keyring',
+        'signature'
+    ]);
+    for (const key of Reflect.ownKeys(parsed)) {
+        if (typeof key !== 'string' || !allowed.has(key)) {
+            throw new Error('Identity certificate contains an unexpected field');
+        }
+        ownData(parsed, key);
+    }
+    for (const key of allowed)
+        ownData(parsed, key);
+    const fields = ownData(parsed, 'fields');
+    const keyring = ownData(parsed, 'keyring');
+    if (!isPlainRecord(fields) || !isPlainRecord(keyring)) {
+        throw new Error('Identity certificate fields and keyring must be plain objects');
+    }
+    const fieldNames = Object.keys(fields);
+    const keyringNames = Object.keys(keyring);
+    if (fieldNames.length < 1 ||
+        fieldNames.length > MAX_IDENTITY_FIELDS ||
+        keyringNames.length < 1 ||
+        keyringNames.length > MAX_IDENTITY_FIELDS) {
+        throw new Error('Identity certificate fields or keyring have invalid cardinality');
+    }
+    for (const fieldName of keyringNames) {
+        if (!Object.prototype.hasOwnProperty.call(fields, fieldName)) {
+            throw new Error('Identity keyring refers to an absent certificate field');
+        }
+        const key = ownData(keyring, fieldName);
+        if (typeof key !== 'string' || key.length > 2048) {
+            throw new Error('Identity keyring value is missing or oversized');
+        }
+    }
+    return parsed;
+}
+function normalizeIdentitySearch(input) {
+    return input.trim().replaceAll(/\s+/g, ' ');
+}
+/** Match literal tokens in order, without a combinatorial wildcard expression. */
+function identityFuzzyMatches(actual, expected) {
+    const tokens = normalizeIdentitySearch(expected).split(' ');
+    const lines = actual.split(/\r\n?|\n|\u2028|\u2029/);
+    for (const line of lines) {
+        let cursor = 0;
+        let tokenIndex = 0;
+        while (tokenIndex < tokens.length) {
+            const literal = new RegExp(tokens[tokenIndex].replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`), 'gi');
+            literal.lastIndex = cursor;
+            const found = literal.exec(line);
+            if (found == null)
+                break;
+            cursor = found.index + found[0].length;
+            tokenIndex++;
+        }
+        if (tokenIndex === tokens.length)
+            return true;
+    }
+    return false;
+}
+// The default English text index omits these words before matching. Apostrophes
+// inside English words are retained; punctuation otherwise separates terms.
+const IDENTITY_STOP_WORDS = " a about above after again against all am an and any are aren't as at be because been before being below between both but by can't cannot could couldn't did didn't do does doesn't doing don't down during each few for from further had hadn't has hasn't have haven't having he he'd he'll he's her here here's hers herself him himself his how how's i i'd i'll i'm i've if in into is isn't it it's its itself let's me more most mustn't my myself no nor not of off on once only or other ought our ours ourselves out over own same shan't she she'd she'll she's should shouldn't so some such than that that's the their theirs them themselves then there there's these they they'd they'll they're they've this those through to too under until up very was wasn't we we'd we'll we're we've were weren't what what's when when's where where's which while who who's whom why why's with won't would wouldn't you you'd you'll you're you've your yours yourself yourselves ";
+function identityTextTokens(text) {
+    // ASCII apostrophes are part of English names such as O'Neil.
+    const tokens = text.match(/(?:[^\p{Dash}\p{Pattern_Syntax}\p{Quotation_Mark}\p{Terminal_Punctuation}\p{White_Space}]|')+/gu) ?? [];
+    return tokens.filter(token => !IDENTITY_STOP_WORDS.includes(` ${token} `));
+}
+/** -1 rejects the result; 1 records a positive indexed term; 0 is neutral. */
+function identityQueryPartMatch(tokens, text, raw, phrase) {
+    const negative = raw.startsWith('-') && raw.length > 1;
+    if (phrase !== undefined) {
+        const present = containsText(text, phrase);
+        if (negative ? present : !present)
+            return -1;
+        if (negative)
+            return 0;
+    }
+    const terms = identityTextTokens(phrase ?? (negative ? raw.slice(1) : raw));
+    const matched = terms.some(term => tokens.includes(term));
+    if (!matched)
+        return 0;
+    return negative ? -1 : 1;
+}
+/**
+ * Bind the overlay's English text search using complete tokens, stopwords and
+ * exact phrases. Language-specific stemming remains unsupported; a stem-only
+ * overlay result may be conservatively dropped rather than treated as a substring.
+ */
+function identityTextMatches(searchable, search) {
+    const text = foldIdentityText(searchable);
+    const query = foldIdentityText(search);
+    const tokens = identityTextTokens(text);
+    const parts = /-?"([^"]*)"|[^\s"]+/g;
+    let positiveMatch = false;
+    let match = parts.exec(query);
+    while (match != null) {
+        const result = identityQueryPartMatch(tokens, text, match[0], match[1]);
+        if (result === -1)
+            return false;
+        if (result === 1)
+            positiveMatch = true;
+        match = parts.exec(query);
+    }
+    return positiveMatch;
+}
+/** The overlay matches userName exactly and other named fields fuzzily. */
+function identityAttributeMatches(fieldName, actual, expected) {
+    if (typeof actual !== 'string')
+        return false;
+    if (fieldName === 'userName')
+        return actual === normalizeIdentitySearch(expected);
+    return identityFuzzyMatches(actual, expected);
+}
+function foldIdentityText(input) {
+    return input
+        .normalize('NFD')
+        .replaceAll(/\p{Mn}/gu, '')
+        .toLowerCase();
+}
+function containsText(haystack, needle) {
+    return haystack.includes(needle);
+}
+const UNSEARCHABLE_IDENTITY_FIELDS = new Set(['profilePhoto', 'icon']);
+/**
+ * `any` is the overlay's all-fields search, not a field name. Accept a certificate
+ * when its searchable fields satisfy the same search the overlay ran.
+ */
+function identityAnyMatches(fields, expected) {
+    const normalized = normalizeIdentitySearch(expected);
+    if (normalized.length < 2)
+        return false;
+    const searchable = Object.entries(fields)
+        .filter(([key, value]) => !UNSEARCHABLE_IDENTITY_FIELDS.has(key) && typeof value === 'string')
+        .map(([, value]) => value)
+        .join(' ');
+    if (normalized.length === 2)
+        return identityFuzzyMatches(searchable, normalized);
+    return identityTextMatches(searchable, normalized);
+}
+/** Re-bind authenticated certificates to the identity lookup they answered. */
+function filterCertificatesByIdentityKey(certificates, identityKey) {
+    const expected = identityKey.toLowerCase();
+    return certificates.filter(certificate => typeof certificate.subject === 'string' && certificate.subject.toLowerCase() === expected);
+}
+function usableIdentityAttributes(attributes) {
+    const expected = [];
+    for (const key of Object.keys(attributes)) {
+        const descriptor = Object.getOwnPropertyDescriptor(attributes, key);
+        if (descriptor == null || !('value' in descriptor) || typeof descriptor.value !== 'string')
+            return undefined;
+        if (normalizeIdentitySearch(descriptor.value).length > 0)
+            expected.push([key, descriptor.value]);
+    }
+    return expected;
+}
+function certificateMatchesAttributes(certificate, anySearch, expected) {
+    const fields = certificate.decryptedFields;
+    if (fields == null || typeof fields !== 'object' || Array.isArray(fields))
+        return false;
+    const record = fields;
+    if (anySearch !== undefined)
+        return identityAnyMatches(record, anySearch);
+    return expected.every(([fieldName, value]) => {
+        const descriptor = Object.getOwnPropertyDescriptor(record, fieldName);
+        return descriptor != null && 'value' in descriptor && identityAttributeMatches(fieldName, descriptor.value, value);
+    });
+}
+/** Re-bind authenticated certificates to the attribute lookup they answered. */
+function filterCertificatesByAttributes(certificates, attributes) {
+    if (attributes == null || typeof attributes !== 'object' || Array.isArray(attributes))
+        return [];
+    const any = Object.getOwnPropertyDescriptor(attributes, 'any');
+    if (any != null && (!('value' in any) || typeof any.value !== 'string'))
+        return [];
+    const expected = any == null ? usableIdentityAttributes(attributes) : [];
+    if (expected == null || (any == null && expected.length === 0))
+        return [];
+    return certificates.filter(certificate => certificateMatchesAttributes(certificate, any?.value, expected));
+}
 /**
  * Transforms an array of VerifiableCertificate instances according to the trust settings.
  * Only certificates whose grouped total trust meets the threshold are returned,
@@ -13,46 +269,58 @@ const sdk_1 = require("@bsv/sdk");
  * @returns a DiscoverCertificatesResult with totalCertificates and ordered certificates.
  */
 const transformVerifiableCertificatesWithTrust = (trustSettings, certificates) => {
+    const validatedTrust = (0, WalletSettingsManager_1.validateTrustSettings)(trustSettings);
     // Group certificates by subject while accumulating trust.
-    const identityGroups = {};
+    const identityGroups = new Map();
     // Cache certifier lookups.
-    const certifierCache = {};
-    certificates.forEach(cert => {
+    const certifierCache = new Map(validatedTrust.trustedCertifiers.map(certifier => [certifier.identityKey, certifier]));
+    certificates.slice(0, MAX_IDENTITY_RESULTS).forEach(cert => {
         const { subject, certifier } = cert;
         if (subject === '' || certifier === '')
             return;
-        // Lookup and cache certifier details from trustSettings.
-        if (certifierCache[certifier] == null) {
-            const found = trustSettings.trustedCertifiers.find(x => x.identityKey === certifier);
-            if (found == null)
-                return; // Skip this certificate if its certifier is not trusted.
-            certifierCache[certifier] = found;
-        }
+        const trustedCertifier = certifierCache.get(certifier);
+        if (trustedCertifier == null)
+            return;
         // Create the IdentityCertifier object that we want to attach.
         const certifierInfo = {
-            name: certifierCache[certifier].name,
-            iconUrl: certifierCache[certifier].iconUrl ?? '',
-            description: certifierCache[certifier].description,
-            trust: certifierCache[certifier].trust
+            name: trustedCertifier.name,
+            iconUrl: trustedCertifier.iconUrl ?? 'https://bsvblockchain.org/favicon.ico',
+            description: certifierDescription(trustedCertifier.description),
+            trust: trustedCertifier.trust
         };
         // Create an extended certificate that includes certifierInfo.
-        // Note: We use object spread to copy over all properties from the original certificate.
         const extendedCert = {
-            ...cert,
+            type: cert.type,
+            serialNumber: cert.serialNumber,
+            subject: cert.subject,
+            certifier: cert.certifier,
+            revocationOutpoint: cert.revocationOutpoint,
             signature: cert.signature, // We know it exists at this point
-            decryptedFields: cert.decryptedFields,
-            publiclyRevealedKeyring: cert.keyring,
+            fields: { ...cert.fields },
+            decryptedFields: { ...cert.decryptedFields },
+            publiclyRevealedKeyring: { ...cert.keyring },
             certifierInfo
         };
         // Group certificates by subject.
-        identityGroups[subject] ??= { totalTrust: 0, members: [] };
-        identityGroups[subject].totalTrust += certifierInfo.trust;
-        identityGroups[subject].members.push(extendedCert);
+        let group = identityGroups.get(subject);
+        if (group == null) {
+            group = { totalTrust: 0, members: [], certifiers: new Set(), certificates: new Set() };
+            identityGroups.set(subject, group);
+        }
+        const certificateID = `${cert.type}\0${cert.serialNumber}\0${certifier}`;
+        if (group.certificates.has(certificateID))
+            return;
+        group.certificates.add(certificateID);
+        if (!group.certifiers.has(certifier)) {
+            group.certifiers.add(certifier);
+            group.totalTrust += certifierInfo.trust;
+        }
+        group.members.push(extendedCert);
     });
     // Filter out groups that do not meet the trust threshold and flatten the results.
     const finalResults = [];
-    Object.values(identityGroups).forEach(group => {
-        if (group.totalTrust >= trustSettings.trustLevel) {
+    identityGroups.forEach(group => {
+        if (group.totalTrust >= validatedTrust.trustLevel) {
             finalResults.push(...group.members);
         }
     });
@@ -66,19 +334,80 @@ const transformVerifiableCertificatesWithTrust = (trustSettings, certificates) =
 exports.transformVerifiableCertificatesWithTrust = transformVerifiableCertificatesWithTrust;
 /**
  * Performs an identity overlay service lookup query and returns the parsed results.
+ * Requires an independently maintained ChainTracker; missing context returns no identities.
  *
  * Identity paths benefit from a larger grace window (more hosts contribute outputs before the
  * query resolves) — 300 ms is well under the "instant" perception threshold and catches the long
  * tail of healthy-but-slightly-slow hosts.
  */
-const queryOverlay = async (query, resolver) => {
-    const results = await resolver.query({
-        service: 'ls_identity',
-        query
-    }, undefined, { graceMs: 300 });
-    return await (0, exports.parseResults)(results);
+const queryOverlay = async (query, resolver, chainTracker) => {
+    if (chainTracker == null)
+        return [];
+    return await (0, exports.parseResults)(await (0, exports.queryOverlayEvidence)(query, resolver), chainTracker);
 };
 exports.queryOverlay = queryOverlay;
+/**
+ * Fetch an owned snapshot of UNTRUSTED evidence, suitable only for revalidation.
+ * A limit rejects the lookup because this legacy result cannot represent partial completion.
+ */
+const queryOverlayEvidence = async (query, resolver, limits = {}) => {
+    const candidateBytes = limits.candidateBytes ?? sdk_1.defaultTransactionEvidenceLimits.candidateBytes;
+    const retainedBytes = limits.retainedBytes ?? sdk_1.defaultTransactionEvidenceLimits.retainedBytes;
+    const maxOutputs = limits.outputs ?? 512;
+    if (![candidateBytes, retainedBytes, maxOutputs].every(value => Number.isSafeInteger(value) && value > 0))
+        throw new sdk_1.TransactionEvidenceError('limit');
+    const outputs = [];
+    let bytes = 0;
+    let received = false;
+    let closed = false;
+    let limited = false;
+    const accept = (output) => {
+        const size = output.beef.length + (output.context?.length ?? 0);
+        if (outputs.length >= maxOutputs || output.beef.length > candidateBytes || bytes + size > retainedBytes) {
+            limited = true;
+            return;
+        }
+        bytes += size;
+        outputs.push({
+            ...output,
+            beef: output.beef.slice(),
+            ...(output.context === undefined ? {} : { context: output.context.slice() })
+        });
+    };
+    try {
+        const results = await resolver.query({
+            service: 'ls_identity',
+            query
+        }, undefined, {
+            graceMs: 300,
+            evidenceLimits: { maxOutputs, maxBytes: retainedBytes },
+            onEvidence: event => {
+                if (closed)
+                    return;
+                received = true;
+                if (event.type === 'output')
+                    accept(event.output);
+                else
+                    limited = true;
+            }
+        });
+        if (limited)
+            throw new sdk_1.TransactionEvidenceError('limit');
+        if (results.type !== 'output-list')
+            return results;
+        // Custom/older resolvers may not implement the additive intake callback.
+        if (!received)
+            for (const output of results.outputs)
+                accept(output);
+        if (limited)
+            throw new sdk_1.TransactionEvidenceError('limit');
+        return { type: 'output-list', outputs };
+    }
+    finally {
+        closed = true;
+    }
+};
+exports.queryOverlayEvidence = queryOverlayEvidence;
 /**
  * Cooperative yield helper. On environments where the main thread also drives UI work
  * (React Native, browsers), parsing many certificates synchronously freezes input handling.
@@ -98,63 +427,196 @@ const isUiRuntime = () => {
     return false;
 };
 const yieldToUi = async () => {
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await new Promise(resolve => setTimeout(resolve, 0));
 };
 /**
  * Parse a single overlay output into a verified, decrypted certificate. Returns `null` on any
  * parse / decrypt / verify failure so a malformed entry can never block the others.
  */
-const parseOne = async (output) => {
+const decodeIdentityOutput = async (verifiedOutput) => {
     try {
-        const tx = sdk_1.Transaction.fromBEEF(output.beef);
-        const decodedOutput = sdk_1.PushDrop.decode(tx.outputs[output.outputIndex].lockingScript);
-        const certificate = JSON.parse(sdk_1.Utils.toUTF8(decodedOutput.fields[0]));
-        const verifiableCert = new sdk_1.VerifiableCertificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, certificate.keyring, certificate.signature);
-        const decryptedFields = await verifiableCert.decryptFields(new sdk_1.ProtoWallet('anyone'));
-        await verifiableCert.verify();
+        const decodedOutput = sdk_1.PushDrop.decode(verifiedOutput.lockingScript);
+        if (decodedOutput.fields.length !== 2)
+            return null;
+        const certificateBytes = boundedBytes(decodedOutput.fields[0], 'Identity certificate', 1, MAX_IDENTITY_CERTIFICATE_BYTES);
+        const fieldSignature = boundedBytes(decodedOutput.fields[1], 'Identity field signature', 8, 80);
+        const chunks = verifiedOutput.lockingScript.chunks;
+        if (chunks.length !== 5 ||
+            chunks[0].op !== 33 ||
+            chunks[0].data?.length !== 33 ||
+            chunks[1].op !== 0xac ||
+            chunks[2].op !== pushOpcode(certificateBytes) ||
+            chunks[3].op !== pushOpcode(fieldSignature) ||
+            chunks[4].op !== 0x6d) {
+            return null;
+        }
+        const certificate = certificateRecord(certificateBytes);
+        const subject = ownData(certificate, 'subject');
+        if (typeof subject !== 'string')
+            return null;
+        const anyoneWallet = new sdk_1.ProtoWallet('anyone');
+        const { publicKey: expectedLockingKey } = await anyoneWallet.getPublicKey({
+            protocolID: IDENTITY_PROTOCOL,
+            keyID: IDENTITY_KEY_ID,
+            counterparty: subject
+        });
+        if (decodedOutput.lockingPublicKey.toString() !== expectedLockingKey)
+            return null;
+        const { valid } = await anyoneWallet.verifySignature({
+            data: certificateBytes,
+            signature: fieldSignature,
+            counterparty: subject,
+            protocolID: IDENTITY_PROTOCOL,
+            keyID: IDENTITY_KEY_ID
+        });
+        if (valid !== true)
+            return null;
+        const verifiableCert = new sdk_1.VerifiableCertificate(ownData(certificate, 'type'), ownData(certificate, 'serialNumber'), subject, ownData(certificate, 'certifier'), ownData(certificate, 'revocationOutpoint'), ownData(certificate, 'fields'), ownData(certificate, 'keyring'), ownData(certificate, 'signature'));
+        if ((await verifiableCert.verify()) !== true)
+            return null;
+        const decryptedFields = await verifiableCert.decryptFields(anyoneWallet);
+        if (Object.keys(decryptedFields).length === 0)
+            return null;
         verifiableCert.decryptedFields = decryptedFields;
         return verifiableCert;
     }
-    catch (error) {
-        console.error(error);
+    catch {
+        // Untrusted parsing/decryption errors can contain identity data. Do not log it.
         return null;
     }
 };
+/**
+ * Wallet/session-owned identity validation. Chain evidence is checked on every
+ * use; bounded certificate crypto results are independent of mutable trust ratings.
+ */
+class IdentityEvidenceVerifier {
+    chainTracker;
+    chainNamespace;
+    disposed = false;
+    coordinator;
+    certificates = new Map();
+    expiryTimer;
+    constructor(chainTracker, chainNamespace = 'caller-chain-tracker', limits) {
+        this.chainTracker = chainTracker;
+        this.chainNamespace = chainNamespace;
+        this.coordinator = new sdk_1.TransactionEvidenceCoordinator({
+            chainTracker,
+            chainNamespace,
+            limits,
+            policyId: 'sdk-spv-overlay-graph-v1'
+        });
+    }
+    clone(json) {
+        const cert = JSON.parse(json);
+        const copy = new sdk_1.VerifiableCertificate(cert.type, cert.serialNumber, cert.subject, cert.certifier, cert.revocationOutpoint, cert.fields, cert.keyring, cert.signature);
+        copy.decryptedFields = cert.decryptedFields;
+        return copy;
+    }
+    async parse(output) {
+        try {
+            const evidence = { ...output, beef: output.beef.slice() };
+            const verified = await this.coordinator.verify(evidence);
+            if (this.disposed)
+                return null;
+            const cached = this.certificates.get(verified.outpoint);
+            if (cached !== undefined && cached.expiresAt > Date.now()) {
+                return { outpoint: verified.outpoint, certificate: this.clone(cached.json) };
+            }
+            const certificate = await decodeIdentityOutput(verified);
+            if (certificate === null)
+                return null;
+            // Certificate crypto can await; fence its completion against current chain/session state.
+            await this.coordinator.verify(evidence);
+            if (this.disposed)
+                return null;
+            // Store owned bytes and return a separate object; callers cannot mutate future results.
+            const json = JSON.stringify(certificate);
+            this.prune();
+            let bytes = [...this.certificates.values()].reduce((total, value) => total + value.json.length * 2, 0);
+            while (this.certificates.size > 0 &&
+                (this.certificates.size >= 128 || bytes + json.length * 2 > 2 * 1024 * 1024)) {
+                const oldest = this.certificates.keys().next().value;
+                bytes -= this.certificates.get(oldest).json.length * 2;
+                this.certificates.delete(oldest);
+            }
+            if (json.length * 2 <= 2 * 1024 * 1024) {
+                this.certificates.set(verified.outpoint, { json, expiresAt: Date.now() + 60_000 });
+                this.scheduleExpiry();
+            }
+            return { outpoint: verified.outpoint, certificate: this.clone(json) };
+        }
+        catch (error) {
+            if (error instanceof sdk_1.TransactionEvidenceError && (error.code === 'limit' || error.code === 'timeout'))
+                throw error;
+            return null;
+        }
+    }
+    prune() {
+        for (const [key, cached] of this.certificates)
+            if (cached.expiresAt <= Date.now())
+                this.certificates.delete(key);
+    }
+    scheduleExpiry() {
+        clearTimeout(this.expiryTimer);
+        const expiresAt = Math.min(...[...this.certificates.values()].map(value => value.expiresAt));
+        if (!Number.isFinite(expiresAt))
+            return;
+        this.expiryTimer = setTimeout(() => {
+            this.prune();
+            this.scheduleExpiry();
+        }, Math.max(1, expiresAt - Date.now()));
+        this.expiryTimer.unref?.();
+    }
+    dispose() {
+        this.disposed = true;
+        this.coordinator.dispose();
+        this.certificates.clear();
+        clearTimeout(this.expiryTimer);
+    }
+}
+exports.IdentityEvidenceVerifier = IdentityEvidenceVerifier;
 /**
  * Parse the returned UTXOs, decrypting and verifying each certificate.
+ * An omitted ChainTracker fails closed. Each call revalidates transaction evidence;
+ * returned certificates carry no reusable chain-verdict or unspentness guarantee.
  *
  * On UI runtimes (browser / React Native), yields between iterations so the JS thread does not
  * own the frame for the full duration. On Node, runs straight through.
  */
-const parseResults = async (lookupResult) => {
-    if (lookupResult.type !== 'output-list')
-        return [];
-    const parsedResults = [];
-    const shouldYield = isUiRuntime();
-    for (const output of lookupResult.outputs) {
-        if (shouldYield)
-            await yieldToUi();
-        const cert = await parseOne(output);
-        if (cert != null)
-            parsedResults.push(cert);
-    }
-    return parsedResults;
+const parseResults = async (lookupResult, chainTracker, verifier) => {
+    const certificates = [];
+    for await (const certificate of parseResults$(lookupResult, chainTracker, verifier))
+        certificates.push(certificate);
+    return certificates;
 };
 exports.parseResults = parseResults;
 /**
  * Iterable variant of {@link parseResults}: emits each successfully parsed certificate as soon as
  * it's ready, so callers can render progressively instead of waiting for the full set.
  */
-async function* parseResults$(lookupResult) {
-    if (lookupResult.type !== 'output-list')
+async function* parseResults$(lookupResult, chainTracker, verifier) {
+    if (lookupResult.type !== 'output-list' || chainTracker == null)
+        return;
+    if (verifier !== undefined && verifier.chainTracker !== chainTracker)
         return;
+    const owned = verifier === undefined;
+    verifier ??= new IdentityEvidenceVerifier(chainTracker);
     const shouldYield = isUiRuntime();
-    for (const output of lookupResult.outputs) {
-        if (shouldYield)
-            await yieldToUi();
-        const cert = await parseOne(output);
-        if (cert != null)
-            yield cert;
+    const seen = new Set();
+    try {
+        for (const output of lookupResult.outputs) {
+            if (shouldYield)
+                await yieldToUi();
+            const result = await verifier.parse(output);
+            if (result !== null && !seen.has(result.outpoint)) {
+                seen.add(result.outpoint);
+                yield result.certificate;
+            }
+        }
+    }
+    finally {
+        if (owned)
+            verifier.dispose();
     }
 }
 //# sourceMappingURL=identityUtils.js.map