signet-protocol 0.1.0

package/dist/credentials.js

@@ -0,0 +1,686 @@
+// Verification Credential (kind 31000, type: credential)
+// Create, sign, verify, and parse Signet credentials for all 4 tiers
+import { createAttestation } from 'nostr-attestations';
+import { ATTESTATION_KIND, ATTESTATION_TYPES, DEFAULT_CREDENTIAL_EXPIRY_SECONDS, DEFAULT_CRYPTO_ALGORITHM } from './constants.js';
+import { signEvent, verifyEvent, getPublicKey, hash } from './crypto.js';
+import { validateCredential, getTagValue, getTagValues } from './validation.js';
+import { ringSign, ringVerify } from './ring-signature.js';
+import { createAgeRangeProof, verifyAgeRangeProof } from './range-proof.js';
+import { SignetValidationError } from './errors.js';
+import { MerkleTree } from './merkle.js';
+/** Build an unsigned credential event */
+export function buildCredentialEvent(verifierPubkey, params) {
+    const signetTags = [
+        ['tier', String(params.tier)],
+        ['verification-type', params.type],
+        ['scope', params.scope],
+        ['method', params.method],
+        ['algo', DEFAULT_CRYPTO_ALGORITHM],
+    ];
+    if (params.profession)
+        signetTags.push(['profession', params.profession]);
+    if (params.jurisdiction)
+        signetTags.push(['jurisdiction', params.jurisdiction]);
+    if (params.ageRange)
+        signetTags.push(['age-range', params.ageRange]);
+    if (params.entityType)
+        signetTags.push(['entity-type', params.entityType]);
+    if (params.nullifier)
+        signetTags.push(['nullifier', params.nullifier]);
+    if (params.merkleRoot)
+        signetTags.push(['merkle-root', params.merkleRoot]);
+    if (params.guardianPubkeys) {
+        for (const gp of params.guardianPubkeys) {
+            signetTags.push(['guardian', gp]);
+        }
+    }
+    if (params.supersedes)
+        signetTags.push(['supersedes', params.supersedes]);
+    // Tier 2-4: assertion-first hybrid (references subject's Tier 1 self-declaration)
+    // Tier 1: direct claim (self-attestation, no assertion reference)
+    const useAssertionFirst = params.tier > 1 && params.assertionEventId;
+    const template = createAttestation({
+        type: ATTESTATION_TYPES.CREDENTIAL,
+        identifier: useAssertionFirst ? undefined : params.subjectPubkey,
+        subject: params.subjectPubkey,
+        assertion: useAssertionFirst ? {
+            id: params.assertionEventId,
+            relay: params.assertionRelay,
+        } : undefined,
+        expiration: params.expiresAt,
+        occurredAt: params.occurredAt,
+        summary: `${params.type} verification (tier ${params.tier}) for ${params.subjectPubkey.slice(0, 8)}...`,
+        content: params.content || '',
+        tags: signetTags,
+    });
+    return {
+        ...template,
+        pubkey: verifierPubkey,
+        created_at: Math.floor(Date.now() / 1000),
+    };
+}
+/** Create and sign a Tier 1 (self-declared) credential */
+export async function createSelfDeclaredCredential(privateKey, scope = 'adult', expiresAt) {
+    const pubkey = getPublicKey(privateKey);
+    const event = buildCredentialEvent(pubkey, {
+        subjectPubkey: pubkey,
+        tier: 1,
+        type: 'self',
+        scope,
+        method: 'self-declaration',
+        expiresAt: expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS,
+    });
+    return signEvent(event, privateKey);
+}
+/** Create and sign a Tier 2 (web-of-trust vouched) credential.
+ * Typically issued by an aggregator service when vouch threshold is met.
+ * Uses assertion-first hybrid pattern: references the subject's Tier 1 self-declaration. */
+export async function createPeerVouchedCredential(issuerPrivateKey, subjectPubkey, opts) {
+    const pubkey = getPublicKey(issuerPrivateKey);
+    const event = buildCredentialEvent(pubkey, {
+        subjectPubkey,
+        tier: 2,
+        type: 'peer',
+        scope: 'adult',
+        method: 'in-person',
+        assertionEventId: opts.assertionEventId,
+        assertionRelay: opts.assertionRelay,
+        expiresAt: opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS,
+    });
+    return signEvent(event, issuerPrivateKey);
+}
+/** Create and sign a Tier 3 (professional verified adult) credential.
+ * Uses assertion-first hybrid pattern: references the subject's Tier 1 self-declaration. */
+export async function createProfessionalCredential(verifierPrivateKey, subjectPubkey, opts) {
+    const pubkey = getPublicKey(verifierPrivateKey);
+    const event = buildCredentialEvent(pubkey, {
+        subjectPubkey,
+        tier: 3,
+        type: 'professional',
+        scope: 'adult',
+        method: 'in-person-id',
+        profession: opts.profession,
+        jurisdiction: opts.jurisdiction,
+        assertionEventId: opts.assertionEventId,
+        assertionRelay: opts.assertionRelay,
+        expiresAt: opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS,
+        occurredAt: opts.occurredAt,
+        content: opts.proofBlob,
+    });
+    return signEvent(event, verifierPrivateKey);
+}
+/** Create and sign a Tier 4 (professional verified adult+child) credential.
+ * Uses assertion-first hybrid pattern: references the subject's Tier 1 self-declaration. */
+export async function createChildSafetyCredential(verifierPrivateKey, subjectPubkey, opts) {
+    const pubkey = getPublicKey(verifierPrivateKey);
+    const event = buildCredentialEvent(pubkey, {
+        subjectPubkey,
+        tier: 4,
+        type: 'professional',
+        scope: 'adult+child',
+        method: 'in-person-id',
+        profession: opts.profession,
+        jurisdiction: opts.jurisdiction,
+        ageRange: opts.ageRange,
+        assertionEventId: opts.assertionEventId,
+        assertionRelay: opts.assertionRelay,
+        expiresAt: opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS,
+        occurredAt: opts.occurredAt,
+        content: opts.proofBlob,
+    });
+    return signEvent(event, verifierPrivateKey);
+}
+/** Verify a credential event's signature and structure */
+export async function verifyCredential(event) {
+    const signatureValid = await verifyEvent(event);
+    const validation = validateCredential(event);
+    const expiresStr = getTagValue(event, 'expiration');
+    const expired = expiresStr ? (() => { const exp = parseInt(expiresStr, 10); return isNaN(exp) || exp < Math.floor(Date.now() / 1000); })() : false;
+    return {
+        signatureValid,
+        structureValid: validation.valid,
+        expired,
+        errors: validation.errors,
+    };
+}
+/** Check if a credential is expired */
+export function isCredentialExpired(event) {
+    const expiresStr = getTagValue(event, 'expiration');
+    if (!expiresStr)
+        return false;
+    const exp = parseInt(expiresStr, 10);
+    // NaN expiration is treated as expired (not perpetually valid)
+    return isNaN(exp) || exp < Math.floor(Date.now() / 1000);
+}
+/** Parse a credential event into a structured object */
+export function parseCredential(event) {
+    if (event.kind !== ATTESTATION_KIND)
+        return null;
+    if (getTagValue(event, 'type') !== ATTESTATION_TYPES.CREDENTIAL)
+        return null;
+    const tier = getTagValue(event, 'tier');
+    if (!tier)
+        return null;
+    const guardianValues = getTagValues(event, 'guardian');
+    const algorithm = (getTagValue(event, 'algo') || DEFAULT_CRYPTO_ALGORITHM);
+    // For assertion-first events (Tier 2-4), the subject pubkey is in the 'p' tag.
+    // For direct claims (Tier 1), strip 'credential:' prefix from d-tag.
+    const dTag = getTagValue(event, 'd') || '';
+    const pTag = getTagValue(event, 'p');
+    let subjectPubkey;
+    if (dTag.startsWith('assertion:') && pTag) {
+        subjectPubkey = pTag;
+    }
+    else {
+        subjectPubkey = dTag.startsWith('credential:') ? dTag.slice('credential:'.length) : dTag;
+    }
+    return {
+        subjectPubkey,
+        tier: (() => { const t = parseInt(tier, 10); return (!isNaN(t) && t >= 1 && t <= 4 ? t : 1); })(),
+        type: (getTagValue(event, 'verification-type') || 'self'),
+        scope: (getTagValue(event, 'scope') || 'adult'),
+        method: (getTagValue(event, 'method') || 'self-declaration'),
+        profession: getTagValue(event, 'profession'),
+        jurisdiction: getTagValue(event, 'jurisdiction'),
+        ageRange: getTagValue(event, 'age-range'),
+        expiresAt: (() => { const expiresStr = getTagValue(event, 'expiration'); const expiresNum = expiresStr ? parseInt(expiresStr, 10) : undefined; return (expiresNum !== undefined && !isNaN(expiresNum)) ? expiresNum : undefined; })(),
+        entityType: getTagValue(event, 'entity-type'),
+        nullifier: getTagValue(event, 'nullifier'),
+        merkleRoot: getTagValue(event, 'merkle-root'),
+        guardianPubkeys: guardianValues.length > 0 ? guardianValues : undefined,
+        supersedes: getTagValue(event, 'supersedes'),
+        supersededBy: getTagValue(event, 'superseded-by'),
+        occurredAt: (() => { const s = getTagValue(event, 'occurred_at'); const n = s ? parseInt(s, 10) : undefined; return (n !== undefined && !isNaN(n)) ? n : undefined; })(),
+        algorithm,
+    };
+}
+/**
+ * Create a Tier 3 credential with ring signature issuer privacy.
+ * The credential is signed by the verifier's Nostr key (for relay acceptance),
+ * but the content includes a ring signature proving "one of N verifiers" issued it.
+ */
+export async function createRingProtectedCredential(verifierPrivateKey, subjectPubkey, ring, signerIndex, opts) {
+    const pubkey = getPublicKey(verifierPrivateKey);
+    const expiresAt = opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS;
+    // Use a single timestamp for both the ring signature binding and the event
+    const timestamp = Math.floor(Date.now() / 1000);
+    // Ring signature binds to subject + timestamp (not event ID, which changes with content)
+    const ringSig = ringSign(`signet:credential:${subjectPubkey}:${timestamp}`, ring, signerIndex, verifierPrivateKey);
+    const content = { ringSignature: ringSig };
+    const event = {
+        kind: ATTESTATION_KIND,
+        pubkey,
+        created_at: timestamp,
+        tags: buildCredentialEvent(pubkey, {
+            subjectPubkey,
+            tier: 3,
+            type: 'professional',
+            scope: 'adult',
+            method: 'in-person-id',
+            profession: opts.profession,
+            jurisdiction: opts.jurisdiction,
+            expiresAt,
+            content: JSON.stringify(content),
+        }).tags,
+        content: JSON.stringify(content),
+    };
+    return signEvent(event, verifierPrivateKey);
+}
+/**
+ * Create a Tier 4 credential with ring signature AND age range proof.
+ */
+export async function createRingProtectedChildCredential(verifierPrivateKey, subjectPubkey, ring, signerIndex, opts) {
+    const pubkey = getPublicKey(verifierPrivateKey);
+    const expiresAt = opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS;
+    // Use a single timestamp for both the ring signature binding and the event
+    const timestamp = Math.floor(Date.now() / 1000);
+    // Create the age range proof, bound to the subject pubkey to prevent transplanting
+    const rangeProof = createAgeRangeProof(opts.actualAge, opts.ageRange, subjectPubkey);
+    // Ring signature binds to subject + timestamp (not event ID, which changes with content)
+    const ringSig = ringSign(`signet:credential:${subjectPubkey}:${timestamp}`, ring, signerIndex, verifierPrivateKey);
+    const content = {
+        ringSignature: ringSig,
+        rangeProof,
+    };
+    const event = {
+        kind: ATTESTATION_KIND,
+        pubkey,
+        created_at: timestamp,
+        tags: buildCredentialEvent(pubkey, {
+            subjectPubkey,
+            tier: 4,
+            type: 'professional',
+            scope: 'adult+child',
+            method: 'in-person-id',
+            profession: opts.profession,
+            jurisdiction: opts.jurisdiction,
+            ageRange: opts.ageRange,
+            expiresAt,
+            content: JSON.stringify(content),
+        }).tags,
+        content: JSON.stringify(content),
+    };
+    return signEvent(event, verifierPrivateKey);
+}
+/**
+ * Verify the ring signature and optional range proof inside a credential's content.
+ */
+export function verifyRingProtectedContent(event) {
+    const result = {
+        hasRingSignature: false,
+        ringValid: false,
+        hasRangeProof: false,
+        rangeProofValid: false,
+    };
+    if (!event.content)
+        return result;
+    try {
+        const raw = JSON.parse(event.content);
+        if (!raw || typeof raw !== 'object')
+            return result;
+        const content = raw;
+        const dTag = getTagValue(event, 'd') || '';
+        const subjectPubkey = dTag.startsWith('credential:') ? dTag.slice('credential:'.length) : dTag;
+        if (content.ringSignature &&
+            typeof content.ringSignature === 'object' &&
+            typeof content.ringSignature.message === 'string' &&
+            Array.isArray(content.ringSignature.ring) &&
+            content.ringSignature.ring.every((r) => typeof r === 'string') &&
+            typeof content.ringSignature.c0 === 'string' &&
+            Array.isArray(content.ringSignature.responses) &&
+            content.ringSignature.responses.every((r) => typeof r === 'string')) {
+            result.hasRingSignature = true;
+            // Verify the ring signature is cryptographically valid
+            const cryptoValid = ringVerify(content.ringSignature);
+            // Verify the binding message references this credential's subject
+            const expectedPrefix = `signet:credential:${subjectPubkey}:`;
+            const messageBindsToSubject = content.ringSignature.message.startsWith(expectedPrefix);
+            // Extract timestamp from after the validated prefix
+            const timestampStr = content.ringSignature.message.slice(expectedPrefix.length);
+            const msgTimestamp = parseInt(timestampStr, 10);
+            const timestampMatches = !isNaN(msgTimestamp) && msgTimestamp === event.created_at;
+            result.ringValid = cryptoValid && messageBindsToSubject && timestampMatches;
+        }
+        if (content.rangeProof &&
+            typeof content.rangeProof === 'object' &&
+            !Array.isArray(content.rangeProof)) {
+            result.hasRangeProof = true;
+            const expectedAgeRange = getTagValue(event, 'age-range');
+            if (!expectedAgeRange) {
+                result.rangeProofValid = false;
+            }
+            else {
+                result.rangeProofValid = verifyAgeRangeProof(content.rangeProof, expectedAgeRange, subjectPubkey);
+            }
+        }
+    }
+    catch {
+        // Content is not JSON or not a RingProtectedContent — that's OK for Tier 1/2
+    }
+    return result;
+}
+// --- Credential Renewal ---
+/**
+ * Renew an expiring credential. Creates a new credential with the same parameters
+ * but a fresh expiry. Must be issued by the same verifier (or a new one for re-verification).
+ */
+export async function renewCredential(verifierPrivateKey, existingCredential, newExpiresAt) {
+    const parsed = parseCredential(existingCredential);
+    if (!parsed)
+        throw new SignetValidationError('Invalid credential to renew');
+    const pubkey = getPublicKey(verifierPrivateKey);
+    const expiresAt = newExpiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS;
+    const event = buildCredentialEvent(pubkey, {
+        subjectPubkey: parsed.subjectPubkey,
+        tier: parsed.tier,
+        type: parsed.type,
+        scope: parsed.scope,
+        method: parsed.method,
+        profession: parsed.profession,
+        jurisdiction: parsed.jurisdiction,
+        ageRange: parsed.ageRange,
+        expiresAt,
+    });
+    return signEvent(event, verifierPrivateKey);
+}
+/**
+ * Check if a credential needs renewal (within N days of expiry).
+ */
+export function needsRenewal(event, withinDays = 30) {
+    if (withinDays < 0)
+        throw new SignetValidationError('withinDays must be non-negative');
+    const expiresStr = getTagValue(event, 'expiration');
+    if (!expiresStr)
+        return false;
+    const expiresAt = parseInt(expiresStr, 10);
+    if (isNaN(expiresAt))
+        return false;
+    const now = Math.floor(Date.now() / 1000);
+    const threshold = now + withinDays * 24 * 60 * 60;
+    return expiresAt <= threshold;
+}
+// --- Two-Credential Ceremony ---
+/**
+ * Create a two-credential ceremony issuing Natural Person + Persona credentials.
+ * The verifier sees all documents but only publishes privacy-preserving tags.
+ */
+export async function createTwoCredentialCeremony(verifierPrivateKey, naturalPersonPubkey, personaPubkey, opts) {
+    const verifierPubkey = getPublicKey(verifierPrivateKey);
+    const expiresAt = opts.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS;
+    // 1. Compute nullifier from document details (NOT published, only hash)
+    const nullifier = computeNullifier(opts.documentType, opts.documentCountry, opts.documentNumber);
+    // 2. Build Merkle tree from verified attributes
+    const merkleLeaves = {
+        name: opts.name,
+        nationality: opts.nationality,
+        documentType: opts.documentType,
+        dateOfBirth: opts.dateOfBirth,
+        nullifier: nullifier,
+    };
+    const tree = new MerkleTree(merkleLeaves);
+    const merkleRoot = tree.getRoot();
+    // 3. Compute age range from DOB if not provided
+    const VALID_AGE_RANGES = ['0-3', '4-7', '8-12', '13-17', '18+'];
+    const ageRange = opts.ageRange || computeAgeRange(opts.dateOfBirth);
+    if (!VALID_AGE_RANGES.includes(ageRange)) {
+        throw new SignetValidationError(`Invalid age range: must be one of ${VALID_AGE_RANGES.join(', ')}`);
+    }
+    // 4. Determine tier and scope
+    const isChild = ageRange !== '18+';
+    const tier = isChild ? 4 : 3;
+    const scope = isChild ? 'adult+child' : 'adult';
+    // 5. Issue Natural Person credential (keypair A)
+    const npEvent = buildCredentialEvent(verifierPubkey, {
+        subjectPubkey: naturalPersonPubkey,
+        tier,
+        type: 'professional',
+        scope,
+        method: 'in-person-id',
+        profession: opts.profession,
+        jurisdiction: opts.jurisdiction,
+        ageRange,
+        entityType: 'natural_person',
+        nullifier,
+        merkleRoot,
+        guardianPubkeys: opts.guardianPubkeys,
+        expiresAt,
+        occurredAt: opts.occurredAt,
+    });
+    const naturalPerson = await signEvent(npEvent, verifierPrivateKey);
+    // 6. Issue Persona credential (keypair B) — NO nullifier, NO merkle-root
+    const personaEvent = buildCredentialEvent(verifierPubkey, {
+        subjectPubkey: personaPubkey,
+        tier,
+        type: 'professional',
+        scope,
+        method: 'in-person-id',
+        profession: opts.profession,
+        jurisdiction: opts.jurisdiction,
+        ageRange,
+        entityType: 'persona',
+        guardianPubkeys: opts.guardianPubkeys,
+        expiresAt,
+        occurredAt: opts.occurredAt,
+    });
+    const persona = await signEvent(personaEvent, verifierPrivateKey);
+    // 7. Generate Merkle proofs for all leaves
+    const merkleProofs = Object.keys(merkleLeaves)
+        .sort()
+        .map((key) => tree.prove(key));
+    return {
+        naturalPerson,
+        persona,
+        merkleLeaves,
+        merkleProofs,
+    };
+}
+/** Compute age range string from ISO date of birth */
+function computeAgeRange(dateOfBirth) {
+    const dob = new Date(dateOfBirth);
+    if (isNaN(dob.getTime()))
+        throw new SignetValidationError('Invalid date of birth: value is not a parseable ISO date');
+    const now = new Date();
+    let age = now.getFullYear() - dob.getFullYear();
+    const monthDiff = now.getMonth() - dob.getMonth();
+    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
+        age--;
+    }
+    if (age < 0 || age > 150) {
+        throw new SignetValidationError(`Implausible age ${age} computed from date of birth`);
+    }
+    if (age >= 18)
+        return '18+';
+    if (age >= 13)
+        return '13-17';
+    if (age >= 8)
+        return '8-12';
+    if (age >= 4)
+        return '4-7';
+    return '0-3';
+}
+// --- Credential Chains ---
+/**
+ * Issue a new credential that supersedes an existing one.
+ * The old credential gets a superseded-by tag added (returned as updated event).
+ */
+export async function supersedeCredential(verifierPrivateKey, oldCredential, newParams) {
+    const parsed = parseCredential(oldCredential);
+    if (!parsed)
+        throw new SignetValidationError('Invalid credential to supersede');
+    const verifierPubkey = getPublicKey(verifierPrivateKey);
+    const expiresAt = newParams.expiresAt || Math.floor(Date.now() / 1000) + DEFAULT_CREDENTIAL_EXPIRY_SECONDS;
+    // Build new credential with supersedes link
+    const newEvent = buildCredentialEvent(verifierPubkey, {
+        subjectPubkey: newParams.subjectPubkey,
+        tier: newParams.tier || parsed.tier,
+        type: newParams.type || parsed.type,
+        scope: newParams.scope || parsed.scope,
+        method: newParams.method || parsed.method,
+        profession: newParams.profession ?? parsed.profession,
+        jurisdiction: newParams.jurisdiction ?? parsed.jurisdiction,
+        ageRange: newParams.ageRange ?? parsed.ageRange,
+        entityType: newParams.entityType ?? parsed.entityType,
+        nullifier: newParams.nullifier ?? parsed.nullifier,
+        merkleRoot: newParams.merkleRoot ?? parsed.merkleRoot,
+        guardianPubkeys: newParams.guardianPubkeys ?? parsed.guardianPubkeys,
+        supersedes: oldCredential.id,
+        expiresAt,
+    });
+    const newCredential = await signEvent(newEvent, verifierPrivateKey);
+    // Note: We do NOT modify the old credential. Adding a tag would invalidate its
+    // id and signature (which are computed from the serialized event including tags).
+    // The supersession relationship is established by the 'supersedes' tag on the
+    // new credential pointing to the old credential's id.
+    return { newCredential, oldCredential };
+}
+const MAX_CHAIN_DEPTH = 100;
+/**
+ * Follow supersedes/superseded-by chain to find current active credential.
+ */
+export function resolveCredentialChain(events) {
+    if (events.length === 0)
+        return null;
+    // Build lookup maps
+    const byId = new Map();
+    for (const e of events)
+        byId.set(e.id, e);
+    // Build a set of all IDs that are superseded by another event in the set
+    const supersededIds = new Set();
+    for (const e of events) {
+        const supersedesId = getTagValue(e, 'supersedes');
+        if (supersedesId && byId.has(supersedesId)) {
+            supersededIds.add(supersedesId);
+        }
+    }
+    // The "current" credential is the one whose ID is NOT in the superseded set
+    let current;
+    for (const e of events) {
+        if (!supersededIds.has(e.id)) {
+            current = e;
+        }
+    }
+    if (!current)
+        current = events[events.length - 1];
+    // Walk backwards through supersedes links to build history
+    const history = [];
+    let cursor = current;
+    const visited = new Set();
+    while (cursor) {
+        if (visited.has(cursor.id))
+            break;
+        if (history.length >= MAX_CHAIN_DEPTH)
+            break;
+        visited.add(cursor.id);
+        const supersedesId = getTagValue(cursor, 'supersedes');
+        if (supersedesId && byId.has(supersedesId)) {
+            history.unshift(byId.get(supersedesId));
+            cursor = byId.get(supersedesId);
+        }
+        else {
+            break;
+        }
+    }
+    return { current, history };
+}
+/**
+ * Check if a credential has been superseded.
+ */
+export function isSuperseded(event) {
+    return !!getTagValue(event, 'superseded-by');
+}
+// --- Nullifier Utilities ---
+/**
+ * Compute a deterministic nullifier from document details.
+ * Uses length-prefixed encoding to prevent field-boundary collisions:
+ *   SHA-256( len(docType) + docType + len(country) + country + len(docNum) + docNum + domainTag )
+ *
+ * Each field is prefixed with its UTF-8 byte length as a 2-byte big-endian uint16,
+ * followed by a fixed domain separation tag.
+ */
+export function computeNullifier(documentType, countryCode, documentNumber) {
+    const domainTag = 'signet-nullifier-v2';
+    const fields = [documentType, countryCode, documentNumber, domainTag];
+    // Calculate total buffer size: 2 bytes length prefix + field bytes for each field
+    const encoder = new TextEncoder();
+    const encoded = fields.map(f => encoder.encode(f));
+    const totalLen = encoded.reduce((sum, buf) => sum + 2 + buf.length, 0);
+    const buffer = new Uint8Array(totalLen);
+    let offset = 0;
+    for (const fieldBytes of encoded) {
+        // 2-byte big-endian length prefix
+        buffer[offset] = (fieldBytes.length >> 8) & 0xff;
+        buffer[offset + 1] = fieldBytes.length & 0xff;
+        offset += 2;
+        buffer.set(fieldBytes, offset);
+        offset += fieldBytes.length;
+    }
+    return hash(buffer);
+}
+/**
+ * Check if a nullifier already exists in a set of credentials.
+ * Returns the conflicting credential if found.
+ */
+export function checkNullifierDuplicate(nullifier, existingCredentials) {
+    for (const cred of existingCredentials) {
+        const credNullifier = getTagValue(cred, 'nullifier');
+        if (credNullifier === nullifier) {
+            return { isDuplicate: true, conflicting: cred };
+        }
+    }
+    return { isDuplicate: false };
+}
+/**
+ * Build a nullifier-chain tag linking old and new nullifiers (for document renewal).
+ */
+export function buildNullifierChainTag(oldNullifier) {
+    return [['nullifier-chain', oldNullifier]];
+}
+/**
+ * Compute nullifiers for ALL documents presented during a verification ceremony.
+ * Returns a nullifier family containing all nullifiers. Collision with ANY nullifier
+ * in ANY family triggers duplicate detection.
+ */
+export function computeNullifierFamily(documents) {
+    if (documents.length === 0) {
+        throw new SignetValidationError('At least one document is required for nullifier computation');
+    }
+    const nullifiers = documents.map(doc => ({
+        documentType: doc.documentType,
+        nullifier: computeNullifier(doc.documentType, doc.countryCode, doc.documentNumber),
+    }));
+    return {
+        primary: nullifiers[0].nullifier,
+        nullifiers,
+    };
+}
+/**
+ * Build nullifier-family tags for a credential event.
+ * The primary nullifier is stored in the 'nullifier' tag (backwards compatible).
+ * Additional nullifiers are stored in 'nullifier-family' tags.
+ */
+export function buildNullifierFamilyTags(family) {
+    const tags = [
+        ['nullifier', family.primary],
+    ];
+    for (const entry of family.nullifiers) {
+        tags.push(['nullifier-family', entry.nullifier, entry.documentType]);
+    }
+    return tags;
+}
+/**
+ * Check if ANY nullifier in a family collides with ANY nullifier in existing credentials.
+ * This catches attempts to use different documents for the same person.
+ */
+export function checkNullifierFamilyDuplicate(family, existingCredentials) {
+    for (const cred of existingCredentials) {
+        // Check against primary nullifier tag
+        const credNullifier = getTagValue(cred, 'nullifier');
+        // Also check against all nullifier-family tags
+        const credFamilyNullifiers = getTagValues(cred, 'nullifier-family');
+        const allCredNullifiers = new Set();
+        if (credNullifier)
+            allCredNullifiers.add(credNullifier);
+        for (const fn of credFamilyNullifiers) {
+            allCredNullifiers.add(fn);
+        }
+        // Check each nullifier in the new family against all existing nullifiers
+        for (const entry of family.nullifiers) {
+            if (allCredNullifiers.has(entry.nullifier)) {
+                return { isDuplicate: true, conflicting: cred, matchedNullifier: entry.nullifier };
+            }
+        }
+    }
+    return { isDuplicate: false };
+}
+// --- Guardian Delegation ---
+/**
+ * Create a guardian delegation event (kind 31000, type: delegation).
+ * Allows a guardian to delegate specific permissions to another adult for a child.
+ */
+export async function createGuardianDelegation(guardianPrivateKey, params) {
+    const guardianPubkey = getPublicKey(guardianPrivateKey);
+    const signetTags = [
+        ['p', params.delegatePubkey],
+        ['delegation-type', 'guardian-delegate'],
+        ['child', params.childPubkey],
+        ['scope', params.scope],
+        ['algo', DEFAULT_CRYPTO_ALGORITHM],
+    ];
+    const template = createAttestation({
+        type: ATTESTATION_TYPES.DELEGATION,
+        identifier: `${params.childPubkey}:${params.delegatePubkey}`,
+        subject: params.delegatePubkey,
+        expiration: params.expiresAt,
+        occurredAt: params.occurredAt,
+        summary: `Guardian delegation for ${params.childPubkey.slice(0, 8)}... to ${params.delegatePubkey.slice(0, 8)}...`,
+        content: '',
+        tags: signetTags,
+    });
+    const event = {
+        ...template,
+        pubkey: guardianPubkey,
+        created_at: Math.floor(Date.now() / 1000),
+    };
+    return signEvent(event, guardianPrivateKey);
+}
+//# sourceMappingURL=credentials.js.map