@kya-brasil/core 0.9.0 → 0.11.0

package/README.md

@@ -43,6 +43,21 @@ const verdict = checkAction(credential.mandate, {
 // verdict.allowed, verdict.checks (every rule evaluated, with its reason), verdict.not_evaluated (extensions)
 ```
 
+## Delegation chains (sub-agents)
+
+A mandate with `delegation: { max_depth, max_ttl_seconds }` lets the agent hand a narrower mandate to another key
+(SPEC section 17). Verify a chain received in `KYA-Delegation`, offline, then evaluate the action on every level:
+
+```ts
+import { checkDelegatedAction, decodeDelegationHeader, verifyDelegationChain } from "@kya-brasil/core";
+const r = await verifyDelegationChain({ credential, chain: decodeDelegationHeader(header) });
+if (!r.ok) reject(r.error);                         // r.delegate is the key that must sign the request
+const verdict = checkDelegatedAction(r.mandates, { action: "quote", amount: 80, currency: "BRL" });
+```
+
+To delegate, `prepareDelegation({ credential, chain, delegate, mandate, ttlSeconds })` returns the delegation and
+the text the delegator signs with its agent key; `mandateSubsetProblems(parent, child)` says why a mandate is broader.
+
 ## Payment instruments (card networks, acquirers, issuers)
 
 A mandate can list the instruments the agent may pay with. Each one is a network and the SHA-256 of a reference

package/dist/credential.d.ts

@@ -20,6 +20,19 @@ export declare function buildCredential(p: {
     status?: CredentialStatus;
     status_reason?: string | null;
 }): Credential;
+/** D-29: credential of a natural person. Nothing personal: no name, no CPF, no certificate subject. */
+export declare function buildPersonCredential(p: {
+    credential_id: string;
+    agent: AgentKey;
+    certificate: {
+        sha256: string;
+        issuer: string;
+        signed_at: string;
+    };
+    mandate: Mandate;
+    issuer: string;
+    now?: Date;
+}): Credential;
 export declare function signCredential(c: Credential, privateKey: CryptoKey, keyId: string, now?: Date): Promise<Credential>;
 export declare function verifyCredentialSignature(c: Credential, publicJwk: JsonWebKey): Promise<{
     valid: boolean;

package/dist/credential.js

@@ -29,6 +29,29 @@ export function buildCredential(p) {
         revocation_url: `${p.issuer}/v1/agents/${p.credential_id}/status`
     };
 }
+/** D-29: credential of a natural person. Nothing personal: no name, no CPF, no certificate subject. */
+export function buildPersonCredential(p) {
+    const now = p.now ?? new Date();
+    const ttl = new Date(now.getTime() + CREDENTIAL_TTL_DAYS * 86400000);
+    const mandateEnd = p.mandate.valid_until ? new Date(p.mandate.valid_until) : null;
+    const expires = mandateEnd && mandateEnd < ttl ? mandateEnd : ttl;
+    return {
+        credential_id: p.credential_id,
+        version: 1,
+        agent: p.agent,
+        principal: { kind: "person", verified_by: "icp-brasil-e-cpf" },
+        authorized_by: { method: "icp-brasil-e-cpf", certificate_sha256: p.certificate.sha256, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at },
+        mandate: p.mandate,
+        kyb_snapshot: null,
+        status: "active",
+        status_reason: null,
+        issued_at: now.toISOString(),
+        expires_at: expires.toISOString(),
+        issuer: p.issuer,
+        verify_url: `${p.issuer}/v1/agents/${p.credential_id}`,
+        revocation_url: `${p.issuer}/v1/agents/${p.credential_id}/status`
+    };
+}
 export async function signCredential(c, privateKey, keyId, now = new Date()) {
     const { attestation: _a, ...payload } = c;
     const attestation = await signAttestation(payload, privateKey, keyId, `${c.issuer}/v1/verify`, now);

package/dist/delegation.d.ts

@@ -0,0 +1,92 @@
+import { type ActionQuery, type ActionVerdict } from "./mandate.js";
+import { type AgentKey, type Mandate } from "./types.js";
+/** A delegated mandate travels in a header on every request: keep it small. */
+export declare const DELEGATED_MANDATE_MAX_BYTES = 2048;
+export interface Delegation {
+    version: 1;
+    credential_id: string;
+    /** `signature_sha256` of the delegation this one extends; null at depth 1 (signed by the credential's agent). */
+    parent: string | null;
+    /** The key that receives the mandate (evm or web-bot-auth). */
+    delegate: AgentKey;
+    depth: number;
+    issued_at: string;
+    expires_at: string;
+    mandate: Mandate;
+    /** Signature by the delegator: the credential's agent at depth 1, the previous delegate after that. */
+    signature: string;
+}
+/** The credential fields a chain is checked against (a Credential, or the `credential` of a verification). */
+export interface DelegationAnchor {
+    credential_id: string;
+    agent: AgentKey;
+    mandate: Mandate;
+    expires_at: string;
+}
+/**
+ * Why `child` is not contained in `parent` (empty array = contained). Every reserved field the parent restricts
+ * must be at least as restricted in the child; a child may restrict what the parent leaves open. Extensions
+ * (non-reserved fields) are not compared: they are never evaluated.
+ */
+export declare function mandateSubsetProblems(parent: Mandate, child: Mandate): string[];
+export declare function isMandateSubset(parent: Mandate, child: Mandate): boolean;
+/** Validates a mandate to delegate: the usual schema plus the size limit of delegated mandates. */
+export declare function validateDelegatedMandate(input: unknown): Mandate;
+/** The exact text the delegator signs. */
+export declare function delegationText(d: Omit<Delegation, "signature" | "version">): Promise<string>;
+/** Identifier of a signed delegation, used as `parent` by the next one. */
+export declare function delegationRef(d: Pick<Delegation, "signature">): Promise<string>;
+/**
+ * Builds the unsigned delegation that extends `chain` (empty = delegate from the credential itself) and the text
+ * to sign. The delegator signs `text` with its key and sets `signature`. Throws INVALID_INPUT when the policy
+ * does not allow it (depth, lifetime, mandate not contained in the delegator's).
+ */
+export declare function prepareDelegation(p: {
+    credential: DelegationAnchor;
+    chain?: Delegation[];
+    delegate: {
+        kind?: unknown;
+        id?: unknown;
+    };
+    mandate: unknown;
+    ttlSeconds: number;
+    now?: Date;
+}): Promise<{
+    delegation: Omit<Delegation, "signature">;
+    text: string;
+}>;
+export type DelegationChainResult = {
+    ok: true;
+    delegate: AgentKey;
+    depth: number;
+    expires_at: string;
+    mandates: Mandate[];
+    ref: string;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+/**
+ * Verifies a delegation chain against its credential, offline: every link signed by the key above it, depth and
+ * lifetime within each policy, each mandate contained in the one above, nothing expired. On success `delegate` is
+ * the key that must sign the request and `mandates` is every mandate an action must satisfy (credential first).
+ * The credential's own status (active, not revoked) is the caller's to check, as for any request.
+ */
+export declare function verifyDelegationChain(p: {
+    credential: DelegationAnchor;
+    chain: unknown;
+    now?: Date;
+}): Promise<DelegationChainResult>;
+/**
+ * Evaluates an action against every mandate of a verified chain (credential first). Allowed only when all allow
+ * it; `levels[0]` is the credential's mandate, `levels[n]` the mandate of delegation n.
+ */
+export declare function checkDelegatedAction(mandates: Mandate[], q: ActionQuery): {
+    allowed: boolean;
+    levels: ActionVerdict[];
+};
+/** Encodes a chain for the `KYA-Delegation` header (base64url of its JSON). */
+export declare function encodeDelegationHeader(chain: Delegation[]): string;
+/** Decodes a `KYA-Delegation` header; throws INVALID_INPUT when it is not base64url JSON. */
+export declare function decodeDelegationHeader(value: string): unknown;

package/dist/delegation.js

@@ -0,0 +1,268 @@
+/**
+ * Delegation to sub-agents (D-30, docs/SPEC.md section 17).
+ *
+ * The principal allows it once, in the mandate it signs with its certificate (`delegation: { max_depth,
+ * max_ttl_seconds }`). The credential's agent then signs, with its own key, a short-lived delegation that hands a
+ * NARROWER mandate to another key; that key may delegate again while the depth allows. Nothing is stored by the
+ * issuer: the chain travels with the request (`KYA-Delegation`) and any verifier checks it offline against the
+ * credential. An action is allowed only when every mandate in the chain allows it.
+ *
+ * Delegation text (what the delegator signs; EIP-191 for evm/erc8004, raw Ed25519 for web-bot-auth):
+ *   KYA Brasil: delegation
+ *   credential: <credential_id>
+ *   parent: <signature_sha256 of the previous delegation | ->
+ *   delegate: <kind>:<id>
+ *   depth: <1..3>
+ *   issued: <ISO 8601>
+ *   expires: <ISO 8601>
+ *   mandate-sha256: <hex SHA-256 of the canonical JSON of the delegated mandate>
+ */
+import { canonicalize } from "./attestation.js";
+import { normalizeAgentKey, verifyAgentSignature } from "./challenge.js";
+import { DELEGATION_MAX_DEPTH, DELEGATION_MIN_TTL_SECONDS, checkAction, counterpartyMatches, normalizeCounterparty, validateMandate } from "./mandate.js";
+import { KyaError } from "./types.js";
+/** A delegated mandate travels in a header on every request: keep it small. */
+export const DELEGATED_MANDATE_MAX_BYTES = 2048;
+/** Clock difference tolerated on `issued_at`. */
+const SKEW_MS = 300_000;
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+const sha256Hex = async (text) => hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+/**
+ * Why `child` is not contained in `parent` (empty array = contained). Every reserved field the parent restricts
+ * must be at least as restricted in the child; a child may restrict what the parent leaves open. Extensions
+ * (non-reserved fields) are not compared: they are never evaluated.
+ */
+export function mandateSubsetProblems(parent, child) {
+    const p = [];
+    if (parent.actions) {
+        if (!child.actions)
+            p.push("actions: parent restricts actions, delegated mandate must list them");
+        else
+            for (const a of child.actions)
+                if (!parent.actions.includes(a))
+                    p.push(`actions: "${a}" is not in the parent mandate`);
+    }
+    for (const k of ["max_per_operation", "max_per_day"]) {
+        const pm = parent[k];
+        const cm = child[k];
+        if (!pm)
+            continue;
+        if (!cm)
+            p.push(`${k}: parent sets a ceiling, delegated mandate must too`);
+        else if (cm.currency !== pm.currency)
+            p.push(`${k}: currency ${cm.currency} differs from the parent's ${pm.currency}`);
+        else if (cm.amount > pm.amount)
+            p.push(`${k}: ${cm.amount} is above the parent's ${pm.amount}`);
+    }
+    if (parent.currencies) {
+        if (!child.currencies)
+            p.push("currencies: parent restricts currencies, delegated mandate must list them");
+        else
+            for (const c of child.currencies)
+                if (!parent.currencies.includes(c))
+                    p.push(`currencies: ${c} is not in the parent mandate`);
+    }
+    if (parent.counterparties && parent.counterparties.length) {
+        if (!child.counterparties || !child.counterparties.length)
+            p.push("counterparties: parent restricts counterparties, delegated mandate must list them");
+        else
+            for (const c of child.counterparties)
+                if (!parent.counterparties.some((pc) => counterpartyMatches(pc, normalizeCounterparty(c))))
+                    p.push(`counterparties: ${c} is not covered by the parent mandate`);
+    }
+    if (parent.payment_instruments && parent.payment_instruments.length) {
+        if (!child.payment_instruments || !child.payment_instruments.length)
+            p.push("payment_instruments: parent restricts instruments, delegated mandate must list them");
+        else
+            for (const i of child.payment_instruments)
+                if (!parent.payment_instruments.some((pi) => pi.network === i.network && pi.ref_sha256 === i.ref_sha256))
+                    p.push(`payment_instruments: ${i.network} ${i.ref_sha256.slice(0, 12)}… is not in the parent mandate`);
+    }
+    if (parent.valid_from && (!child.valid_from || Date.parse(child.valid_from) < Date.parse(parent.valid_from)))
+        p.push("valid_from: delegated mandate starts before the parent's");
+    if (parent.valid_until && (!child.valid_until || Date.parse(child.valid_until) > Date.parse(parent.valid_until)))
+        p.push("valid_until: delegated mandate ends after the parent's");
+    if (child.delegation) {
+        if (!parent.delegation)
+            p.push("delegation: parent does not allow further delegation");
+        else {
+            if (child.delegation.max_depth > parent.delegation.max_depth - 1)
+                p.push(`delegation.max_depth: at most ${parent.delegation.max_depth - 1} below this level`);
+            if (child.delegation.max_ttl_seconds > parent.delegation.max_ttl_seconds)
+                p.push(`delegation.max_ttl_seconds: above the parent's ${parent.delegation.max_ttl_seconds}`);
+        }
+    }
+    return p;
+}
+export function isMandateSubset(parent, child) {
+    return mandateSubsetProblems(parent, child).length === 0;
+}
+/** Validates a mandate to delegate: the usual schema plus the size limit of delegated mandates. */
+export function validateDelegatedMandate(input) {
+    const m = validateMandate(input);
+    if (JSON.stringify(m).length > DELEGATED_MANDATE_MAX_BYTES)
+        throw new KyaError("INVALID_INPUT", `delegated mandate larger than ${DELEGATED_MANDATE_MAX_BYTES} bytes`);
+    return m;
+}
+/** The exact text the delegator signs. */
+export async function delegationText(d) {
+    return [
+        "KYA Brasil: delegation",
+        `credential: ${d.credential_id}`,
+        `parent: ${d.parent ?? "-"}`,
+        `delegate: ${d.delegate.kind}:${d.delegate.id}`,
+        `depth: ${d.depth}`,
+        `issued: ${d.issued_at}`,
+        `expires: ${d.expires_at}`,
+        `mandate-sha256: ${await sha256Hex(canonicalize(d.mandate))}`
+    ].join("\n");
+}
+/** Identifier of a signed delegation, used as `parent` by the next one. */
+export function delegationRef(d) {
+    return sha256Hex(d.signature);
+}
+/**
+ * Builds the unsigned delegation that extends `chain` (empty = delegate from the credential itself) and the text
+ * to sign. The delegator signs `text` with its key and sets `signature`. Throws INVALID_INPUT when the policy
+ * does not allow it (depth, lifetime, mandate not contained in the delegator's).
+ */
+export async function prepareDelegation(p) {
+    const chain = p.chain ?? [];
+    const now = p.now ?? new Date();
+    const delegate = normalizeAgentKey(p.delegate);
+    if (delegate.kind === "erc8004")
+        throw new KyaError("INVALID_INPUT", "delegate must be an evm or web-bot-auth key");
+    const mandate = validateDelegatedMandate(p.mandate);
+    const last = chain[chain.length - 1];
+    const parentMandate = last ? last.mandate : p.credential.mandate;
+    const policy = parentMandate.delegation;
+    const depth = chain.length + 1;
+    if (!policy)
+        throw new KyaError("INVALID_INPUT", depth === 1 ? "the credential's mandate does not allow delegation" : "the delegator's mandate does not allow further delegation");
+    if (depth > DELEGATION_MAX_DEPTH)
+        throw new KyaError("INVALID_INPUT", `delegation deeper than ${DELEGATION_MAX_DEPTH}`);
+    if (!Number.isInteger(p.ttlSeconds) || p.ttlSeconds < DELEGATION_MIN_TTL_SECONDS || p.ttlSeconds > policy.max_ttl_seconds)
+        throw new KyaError("INVALID_INPUT", `ttlSeconds must be from ${DELEGATION_MIN_TTL_SECONDS} to ${policy.max_ttl_seconds}`);
+    const problems = mandateSubsetProblems(parentMandate, mandate);
+    if (problems.length)
+        throw new KyaError("INVALID_INPUT", `delegated mandate is broader than the delegator's: ${problems.join("; ")}`);
+    let expires = now.getTime() + p.ttlSeconds * 1000;
+    for (const bound of [p.credential.expires_at, last?.expires_at])
+        if (bound)
+            expires = Math.min(expires, Date.parse(bound));
+    const delegation = {
+        version: 1,
+        credential_id: p.credential.credential_id,
+        parent: last ? await delegationRef(last) : null,
+        delegate,
+        depth,
+        issued_at: now.toISOString(),
+        expires_at: new Date(expires).toISOString(),
+        mandate
+    };
+    return { delegation, text: await delegationText(delegation) };
+}
+/**
+ * Verifies a delegation chain against its credential, offline: every link signed by the key above it, depth and
+ * lifetime within each policy, each mandate contained in the one above, nothing expired. On success `delegate` is
+ * the key that must sign the request and `mandates` is every mandate an action must satisfy (credential first).
+ * The credential's own status (active, not revoked) is the caller's to check, as for any request.
+ */
+export async function verifyDelegationChain(p) {
+    const fail = (error, message) => ({ ok: false, error, message });
+    const now = (p.now ?? new Date()).getTime();
+    if (!Array.isArray(p.chain) || p.chain.length === 0)
+        return fail("KYA_DELEGATION_MALFORMED", "delegation chain must be a non-empty array");
+    if (p.chain.length > DELEGATION_MAX_DEPTH)
+        return fail("KYA_DELEGATION_TOO_DEEP", `delegation deeper than ${DELEGATION_MAX_DEPTH}`);
+    let signer = p.credential.agent;
+    let parentMandate = p.credential.mandate;
+    let parentRef = null;
+    let notAfter = Date.parse(p.credential.expires_at);
+    if (!Number.isFinite(notAfter))
+        return fail("KYA_DELEGATION_MALFORMED", "the credential has no valid expires_at");
+    const mandates = [p.credential.mandate];
+    for (let i = 0; i < p.chain.length; i++) {
+        const at = `delegation ${i + 1}`;
+        const raw = p.chain[i];
+        if (!raw || typeof raw !== "object" || raw.version !== 1 || typeof raw.signature !== "string" || typeof raw.issued_at !== "string" || typeof raw.expires_at !== "string")
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: not a v1 delegation`);
+        if (raw.credential_id !== p.credential.credential_id)
+            return fail("KYA_DELEGATION_MISMATCH", `${at}: issued under another credential`);
+        if (raw.depth !== i + 1)
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: depth must be ${i + 1}`);
+        if ((raw.parent ?? null) !== parentRef)
+            return fail("KYA_DELEGATION_MISMATCH", `${at}: does not extend the previous link`);
+        let delegate;
+        let mandate;
+        try {
+            delegate = normalizeAgentKey(raw.delegate ?? {});
+            if (delegate.kind === "erc8004")
+                throw new KyaError("INVALID_INPUT", "erc8004 delegate");
+            mandate = validateDelegatedMandate(raw.mandate);
+        }
+        catch (e) {
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: ${e.message}`);
+        }
+        if (delegate.id !== raw.delegate?.id || canonicalize(mandate) !== canonicalize(raw.mandate))
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: delegate or mandate not in normalized form`);
+        const policy = parentMandate.delegation;
+        if (!policy)
+            return fail("KYA_DELEGATION_NOT_ALLOWED", i === 0 ? "the credential's mandate does not allow delegation" : `${at}: the delegator's mandate does not allow further delegation`);
+        const issued = Date.parse(raw.issued_at);
+        const expires = Date.parse(raw.expires_at);
+        if (!Number.isFinite(issued) || !Number.isFinite(expires) || expires <= issued)
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: bad issued_at / expires_at`);
+        if (expires - issued > policy.max_ttl_seconds * 1000)
+            return fail("KYA_DELEGATION_TTL", `${at}: lives longer than ${policy.max_ttl_seconds}s`);
+        if (expires > notAfter)
+            return fail("KYA_DELEGATION_TTL", `${at}: outlives the link above it`);
+        if (issued > now + SKEW_MS)
+            return fail("KYA_DELEGATION_NOT_YET_VALID", `${at}: issued in the future`);
+        if (expires < now)
+            return fail("KYA_DELEGATION_EXPIRED", `${at}: expired at ${raw.expires_at}`);
+        const problems = mandateSubsetProblems(parentMandate, mandate);
+        if (problems.length)
+            return fail("KYA_DELEGATION_BROADER", `${at}: ${problems.join("; ")}`);
+        const text = await delegationText({ credential_id: raw.credential_id, parent: parentRef, delegate, depth: i + 1, issued_at: raw.issued_at, expires_at: raw.expires_at, mandate });
+        if (!(await verifyAgentSignature(signer, text, raw.signature)))
+            return fail("KYA_DELEGATION_BAD_SIGNATURE", `${at}: not signed by the key above it`);
+        signer = delegate;
+        parentMandate = mandate;
+        parentRef = await delegationRef({ signature: raw.signature });
+        notAfter = expires;
+        mandates.push(mandate);
+    }
+    return { ok: true, delegate: signer, depth: p.chain.length, expires_at: new Date(notAfter).toISOString(), mandates, ref: parentRef };
+}
+/**
+ * Evaluates an action against every mandate of a verified chain (credential first). Allowed only when all allow
+ * it; `levels[0]` is the credential's mandate, `levels[n]` the mandate of delegation n.
+ */
+export function checkDelegatedAction(mandates, q) {
+    const levels = mandates.map((m) => checkAction(m, q));
+    return { allowed: levels.length > 0 && levels.every((l) => l.allowed), levels };
+}
+/** Encodes a chain for the `KYA-Delegation` header (base64url of its JSON). */
+export function encodeDelegationHeader(chain) {
+    const bytes = new TextEncoder().encode(JSON.stringify(chain));
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCodePoint(b);
+    const b64 = btoa(s).replaceAll("+", "-").replaceAll("/", "_");
+    let end = b64.length;
+    while (end > 0 && b64[end - 1] === "=")
+        end--;
+    return b64.slice(0, end);
+}
+/** Decodes a `KYA-Delegation` header; throws INVALID_INPUT when it is not base64url JSON. */
+export function decodeDelegationHeader(value) {
+    try {
+        const b64 = value.trim().replaceAll("-", "+").replaceAll("_", "/");
+        const bin = atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "="));
+        return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.codePointAt(0) ?? 0)));
+    }
+    catch {
+        throw new KyaError("INVALID_INPUT", "KYA-Delegation is not base64url JSON");
+    }
+}

package/dist/icp-brasil.d.ts

@@ -29,10 +29,16 @@ export interface IcpProof {
     /** Base64 DER of the AC certificate that issued it (verifies the CRL), or null when not found. */
     issuer_certificate: string | null;
 }
-/** CNPJ carried by the certificate's ICP-Brasil otherName, or null when it is not a PJ certificate. */
 export declare function cnpjFromCertificate(cert: X509Certificate): string | null;
+/** OID 2.16.76.1.3.1: data of the e-CPF holder, "ddmmaaaa" birth date followed by the 11-digit CPF (DOC-ICP-04). */
+export declare const OID_ICP_PERSON = "2.16.76.1.3.1";
 /**
- * Verifies a CMS SignedData (base64 DER) over `challenge` and returns the proof. Throws KyaError
+ * CPF of an e-CPF (natural person) certificate: from the 2.16.76.1.3.1 otherName (positions 9 to 19), or the
+ * common name suffix ":<11 digits>" as a fallback. Null for an e-CNPJ or any other certificate.
+ */
+export declare function cpfFromCertificate(cert: X509Certificate): string | null;
+/**
+ * Verifies a CMS SignedData (base64 DER) over `challenge` by an e-CNPJ and returns the proof. Throws KyaError
  * CERTIFICATE_INVALID / CHALLENGE_FAILED / CNPJ_MISMATCH. `anchors` are PEM or DER (base64) roots.
  */
 export declare function verifyIcpSignature(p: {
@@ -43,3 +49,23 @@ export declare function verifyIcpSignature(p: {
     now?: Date;
     requireChain?: boolean;
 }): Promise<IcpProof>;
+/** e-CPF proof (D-29). `cpf` is for the caller to key-hash at once and forget: never store or return it. No subject (name). */
+export interface IcpPersonProof {
+    cpf: string;
+    certificate_sha256: string;
+    issuer: string;
+    not_before: string;
+    not_after: string;
+    signed_at: string;
+    serial_number: string;
+    crl_urls: string[];
+    issuer_certificate: string | null;
+}
+/** Verifies a CMS over `challenge` by a natural person's e-CPF (D-29). Refuses an e-CNPJ. */
+export declare function verifyIcpPersonSignature(p: {
+    cmsBase64: string;
+    challenge: string;
+    anchors: string[];
+    now?: Date;
+    requireChain?: boolean;
+}): Promise<IcpPersonProof>;

package/dist/icp-brasil.js

@@ -31,7 +31,8 @@ const unb64 = (s) => Uint8Array.from(atob(s.replace(/\s+/g, "")), (c) => c.charC
 const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)));
 const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 /** CNPJ carried by the certificate's ICP-Brasil otherName, or null when it is not a PJ certificate. */
-export function cnpjFromCertificate(cert) {
+/** Digits of an ICP-Brasil otherName in the Subject Alternative Name (OID 2.16.76.1.3.<n>), or null. */
+function otherNameDigits(cert, oidSuffix) {
     const san = cert.extensions.find((e) => e.type === OID_SAN);
     if (!san)
         return null;
@@ -47,27 +48,44 @@ export function cnpjFromCertificate(cert) {
         const inner = block.valueBlock.value;
         const oid = inner[0];
         const oidStr = oid?.valueBlock?.toString?.() ?? "";
-        if (!/2\.16\.76\.1\.3\.3$/.test(oidStr))
+        if (oidStr !== `2.16.76.1.3.${oidSuffix}`)
             continue;
         const explicit = inner[1];
         const valueBlock = explicit?.valueBlock?.value?.[0];
         if (!valueBlock)
             continue;
         const raw = "valueBlock" in valueBlock && "valueHexView" in valueBlock.valueBlock ? new TextDecoder().decode(valueBlock.valueBlock.valueHexView) : String(valueBlock.valueBlock.value);
-        const digits = raw.replace(/\D/g, "");
-        if (digits.length === 14)
-            return digits;
+        return raw.replace(/\D/g, "");
     }
     return null;
 }
+export function cnpjFromCertificate(cert) {
+    const digits = otherNameDigits(cert, "3");
+    return digits && digits.length === 14 ? digits : null;
+}
+/** OID 2.16.76.1.3.1: data of the e-CPF holder, "ddmmaaaa" birth date followed by the 11-digit CPF (DOC-ICP-04). */
+export const OID_ICP_PERSON = "2.16.76.1.3.1";
+/**
+ * CPF of an e-CPF (natural person) certificate: from the 2.16.76.1.3.1 otherName (positions 9 to 19), or the
+ * common name suffix ":<11 digits>" as a fallback. Null for an e-CNPJ or any other certificate.
+ */
+export function cpfFromCertificate(cert) {
+    if (cnpjFromCertificate(cert))
+        return null;
+    const data = otherNameDigits(cert, "1");
+    if (data && data.length >= 19)
+        return data.slice(8, 19);
+    const cn = /CN=([^,]+)/.exec(cert.subject)?.[1] ?? "";
+    return /:(\d{11})\s*$/.exec(cn)?.[1] ?? null;
+}
 async function sha256Hex(bytes) {
     return hex(await crypto.subtle.digest("SHA-256", bytes.slice().buffer));
 }
 /**
- * Verifies a CMS SignedData (base64 DER) over `challenge` and returns the proof. Throws KyaError
- * CERTIFICATE_INVALID / CHALLENGE_FAILED / CNPJ_MISMATCH. `anchors` are PEM or DER (base64) roots.
+ * Shared steps: parse the CMS, require attached content to equal the text, verify the signature, pick the signer
+ * certificate, check its dates, run `identify` (which throws for the wrong kind of certificate), then the chain.
  */
-export async function verifyIcpSignature(p) {
+async function checkCms(p, identify) {
     ensureEngine();
     const now = p.now ?? new Date();
     let cms;
@@ -88,7 +106,7 @@ export async function verifyIcpSignature(p) {
     const trusted = p.anchors.map((a) => pkijs.Certificate.fromBER(unb64(a.replace(/-----[^-]+-----/g, ""))));
     const data = new TextEncoder().encode(p.challenge);
     // An attached CMS (the .p7s carries the signed text) is verified over its own content by pkijs, whatever
-    // `data` says: it MUST carry exactly the challenge, or any document the company ever signed would pass.
+    // `data` says: it MUST carry exactly the challenge, or any document ever signed would pass.
     const embedded = signed.encapContentInfo.eContent;
     if (embedded) {
         const content = new Uint8Array(embedded.getValue());
@@ -104,7 +122,7 @@ export async function verifyIcpSignature(p) {
         throw new KyaError("CHALLENGE_FAILED", `signature verification failed: ${e.message}`);
     }
     if (!ok)
-        throw new KyaError("CHALLENGE_FAILED", "e-CNPJ signature does not match the challenge");
+        throw new KyaError("CHALLENGE_FAILED", "the ICP-Brasil signature does not match the challenge");
     // The signer: match SignerInfo's issuerAndSerialNumber against the carried certificates.
     const si = signed.signerInfos[0];
     const sid = si.sid;
@@ -113,11 +131,7 @@ export async function verifyIcpSignature(p) {
     const x = new X509Certificate(der);
     if (x.notBefore > now || x.notAfter < now)
         throw new KyaError("CERTIFICATE_INVALID", `certificate valid from ${x.notBefore.toISOString()} to ${x.notAfter.toISOString()}`);
-    const cnpj = cnpjFromCertificate(x);
-    if (!cnpj)
-        throw new KyaError("CERTIFICATE_INVALID", "certificate has no ICP-Brasil CNPJ (not an e-CNPJ)");
-    if (cnpj !== normalizeCnpj(p.expectedCnpj))
-        throw new KyaError("CNPJ_MISMATCH", `certificate belongs to CNPJ ${cnpj}, not ${normalizeCnpj(p.expectedCnpj)}`);
+    identify(x);
     if (p.requireChain !== false) {
         if (!trusted.length)
             throw new KyaError("CERTIFICATE_INVALID", "no ICP-Brasil trust anchors configured");
@@ -126,18 +140,60 @@ export async function verifyIcpSignature(p) {
         if (!chain.result)
             throw new KyaError("CERTIFICATE_INVALID", `certificate chain not trusted: ${chain.resultMessage}`);
     }
-    // The issuing AC: carried in the CMS or among the anchors (the bundle includes the intermediate ACs).
-    const issuerCert = [...certs, ...trusted].map((c) => new X509Certificate(c.toSchema().toBER(false))).find((c) => c.subject === x.issuer) ?? null;
+    return { x, der, certs, trusted, now };
+}
+/** The issuing AC: carried in the CMS or among the anchors (the bundle includes the intermediate ACs). */
+function issuerCertificateOf(c) {
+    const issuerCert = [...c.certs, ...c.trusted].map((k) => new X509Certificate(k.toSchema().toBER(false))).find((k) => k.subject === c.x.issuer) ?? null;
+    return issuerCert ? b64(issuerCert.rawData) : null;
+}
+/**
+ * Verifies a CMS SignedData (base64 DER) over `challenge` by an e-CNPJ and returns the proof. Throws KyaError
+ * CERTIFICATE_INVALID / CHALLENGE_FAILED / CNPJ_MISMATCH. `anchors` are PEM or DER (base64) roots.
+ */
+export async function verifyIcpSignature(p) {
+    let cnpj = "";
+    const c = await checkCms(p, (x) => {
+        const found = cnpjFromCertificate(x);
+        if (!found)
+            throw new KyaError("CERTIFICATE_INVALID", cpfFromCertificate(x) ? "this is a natural person's certificate (e-CPF); sign with the company's e-CNPJ" : "certificate has no ICP-Brasil CNPJ (not an e-CNPJ)");
+        if (found !== normalizeCnpj(p.expectedCnpj))
+            throw new KyaError("CNPJ_MISMATCH", `certificate belongs to CNPJ ${found}, not ${normalizeCnpj(p.expectedCnpj)}`);
+        cnpj = found;
+    });
     return {
         cnpj,
-        certificate_sha256: await sha256Hex(new Uint8Array(der)),
-        certificate_subject: x.subject,
-        issuer: x.issuer,
-        not_before: x.notBefore.toISOString(),
-        not_after: x.notAfter.toISOString(),
-        signed_at: now.toISOString(),
-        serial_number: normalizeSerial(x.serialNumber),
-        crl_urls: crlUrlsOf(x),
-        issuer_certificate: issuerCert ? b64(issuerCert.rawData) : null
+        certificate_sha256: await sha256Hex(new Uint8Array(c.der)),
+        certificate_subject: c.x.subject,
+        issuer: c.x.issuer,
+        not_before: c.x.notBefore.toISOString(),
+        not_after: c.x.notAfter.toISOString(),
+        signed_at: c.now.toISOString(),
+        serial_number: normalizeSerial(c.x.serialNumber),
+        crl_urls: crlUrlsOf(c.x),
+        issuer_certificate: issuerCertificateOf(c)
+    };
+}
+/** Verifies a CMS over `challenge` by a natural person's e-CPF (D-29). Refuses an e-CNPJ. */
+export async function verifyIcpPersonSignature(p) {
+    let cpf = "";
+    const c = await checkCms(p, (x) => {
+        if (cnpjFromCertificate(x))
+            throw new KyaError("CERTIFICATE_INVALID", "this is a company certificate (e-CNPJ); a person signs with their e-CPF");
+        const found = cpfFromCertificate(x);
+        if (!found)
+            throw new KyaError("CERTIFICATE_INVALID", "certificate has no ICP-Brasil CPF (not an e-CPF)");
+        cpf = found;
+    });
+    return {
+        cpf,
+        certificate_sha256: await sha256Hex(new Uint8Array(c.der)),
+        issuer: c.x.issuer,
+        not_before: c.x.notBefore.toISOString(),
+        not_after: c.x.notAfter.toISOString(),
+        signed_at: c.now.toISOString(),
+        serial_number: normalizeSerial(c.x.serialNumber),
+        crl_urls: crlUrlsOf(c.x),
+        issuer_certificate: issuerCertificateOf(c)
     };
 }

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export * from "./revocation.js";
 export * from "./erc8004.js";
 export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
+export * from "./person.js";
+export * from "./delegation.js";

package/dist/index.js

@@ -9,3 +9,5 @@ export * from "./revocation.js";
 export * from "./erc8004.js";
 export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
+export * from "./person.js";
+export * from "./delegation.js";

package/dist/mandate.d.ts

@@ -4,7 +4,11 @@
  * `checkAction`; extensions are carried in the credential untouched and never evaluated.
  * Validation is hand-written (no Ajv: `new Function` is blocked on Workers).
  */
-import { type Mandate, type MandateCore } from "./types.js";
+import { type DelegationPolicy, type Mandate, type MandateCore } from "./types.js";
+/** Delegation bounds (D-30): how deep a chain may go and how long one link may live. */
+export declare const DELEGATION_MAX_DEPTH = 3;
+export declare const DELEGATION_MIN_TTL_SECONDS = 60;
+export declare const DELEGATION_MAX_TTL_SECONDS = 86400;
 export declare const MANDATE_SCHEMA: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://kya.example/.well-known/kya-mandate.schema.json";
@@ -72,6 +76,26 @@ export declare const MANDATE_SCHEMA: {
                 readonly additionalProperties: false;
             };
         };
+        readonly delegation: {
+            readonly type: "object";
+            readonly description: "Allows the agent to hand a narrower mandate to other keys (sub-agents), without a new certificate signature. Absent = no delegation.";
+            readonly properties: {
+                readonly max_depth: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 3;
+                    readonly description: "How many levels of sub-agents below this agent.";
+                };
+                readonly max_ttl_seconds: {
+                    readonly type: "integer";
+                    readonly minimum: 60;
+                    readonly maximum: 86400;
+                    readonly description: "Longest lifetime of one delegation.";
+                };
+            };
+            readonly required: readonly ["max_depth", "max_ttl_seconds"];
+            readonly additionalProperties: false;
+        };
         readonly valid_from: {
             readonly type: "string";
             readonly format: "date-time";
@@ -102,12 +126,19 @@ export declare const MANDATE_SCHEMA: {
 };
 /** Throws KyaError INVALID_INPUT with the first problem found; returns the mandate with reserved fields normalized. */
 export declare function validateMandate(input: unknown): Mandate;
+/** Validates a `delegation` field of a mandate (used by validateMandate). */
+export declare function validateDelegationPolicy(v: unknown): DelegationPolicy;
 /**
  * SHA-256 (lowercase hex) of a payment reference as a mandate stores it (D-25): UTF-8, whitespace removed,
  * case kept. Use it on the network's token reference or PAR, never on a card number.
  */
 export declare function hashPaymentRef(ref: string): Promise<string>;
 export declare function normalizeCounterparty(c: string): string;
+/**
+ * Whether a mandate entry matches a normalized counterparty: exactly, or for a `*.domain` entry the domain itself
+ * and any subdomain (SPEC section 5).
+ */
+export declare function counterpartyMatches(entry: string, counterparty: string): boolean;
 export interface ActionQuery {
     action?: string;
     amount?: number;

package/dist/mandate.js

@@ -5,6 +5,10 @@
  * Validation is hand-written (no Ajv: `new Function` is blocked on Workers).
  */
 import { KyaError } from "./types.js";
+/** Delegation bounds (D-30): how deep a chain may go and how long one link may live. */
+export const DELEGATION_MAX_DEPTH = 3;
+export const DELEGATION_MIN_TTL_SECONDS = 60;
+export const DELEGATION_MAX_TTL_SECONDS = 86_400;
 export const MANDATE_SCHEMA = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://kya.example/.well-known/kya-mandate.schema.json",
@@ -32,6 +36,16 @@ export const MANDATE_SCHEMA = {
                 additionalProperties: false
             }
         },
+        delegation: {
+            type: "object",
+            description: "Allows the agent to hand a narrower mandate to other keys (sub-agents), without a new certificate signature. Absent = no delegation.",
+            properties: {
+                max_depth: { type: "integer", minimum: 1, maximum: 3, description: "How many levels of sub-agents below this agent." },
+                max_ttl_seconds: { type: "integer", minimum: 60, maximum: 86400, description: "Longest lifetime of one delegation." }
+            },
+            required: ["max_depth", "max_ttl_seconds"],
+            additionalProperties: false
+        },
         valid_from: { type: "string", format: "date-time" },
         valid_until: { type: "string", format: "date-time" }
     },
@@ -68,6 +82,8 @@ export function validateMandate(input) {
     }
     if (m.payment_instruments !== undefined)
         m.payment_instruments = validatePaymentInstruments(m.payment_instruments, bad);
+    if (m.delegation !== undefined)
+        m.delegation = validateDelegationPolicy(m.delegation);
     for (const k of ["valid_from", "valid_until"])
         if (m[k] !== undefined && !isoDate(m[k]))
             throw bad(k, "ISO 8601 date-time");
@@ -75,6 +91,20 @@ export function validateMandate(input) {
         throw bad("valid_until", "must be after valid_from");
     return m;
 }
+/** Validates a `delegation` field of a mandate (used by validateMandate). */
+export function validateDelegationPolicy(v) {
+    const bad = (why) => new KyaError("INVALID_INPUT", `mandate.delegation: ${why}`);
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw bad(`object { max_depth: 1..${DELEGATION_MAX_DEPTH}, max_ttl_seconds: ${DELEGATION_MIN_TTL_SECONDS}..${DELEGATION_MAX_TTL_SECONDS} }`);
+    const { max_depth, max_ttl_seconds, ...rest } = v;
+    if (Object.keys(rest).length)
+        throw bad(`unknown field(s): ${Object.keys(rest).join(", ")}`);
+    if (!Number.isInteger(max_depth) || max_depth < 1 || max_depth > DELEGATION_MAX_DEPTH)
+        throw bad(`max_depth must be an integer from 1 to ${DELEGATION_MAX_DEPTH}`);
+    if (!Number.isInteger(max_ttl_seconds) || max_ttl_seconds < DELEGATION_MIN_TTL_SECONDS || max_ttl_seconds > DELEGATION_MAX_TTL_SECONDS)
+        throw bad(`max_ttl_seconds must be an integer from ${DELEGATION_MIN_TTL_SECONDS} to ${DELEGATION_MAX_TTL_SECONDS}`);
+    return { max_depth: max_depth, max_ttl_seconds: max_ttl_seconds };
+}
 const NETWORK = /^[a-z][a-z0-9_-]{1,31}$/;
 function validatePaymentInstruments(v, bad) {
     if (!Array.isArray(v) || v.length > 20)
@@ -123,7 +153,22 @@ export function normalizeCounterparty(c) {
         return digits.toUpperCase();
     return s.toLowerCase();
 }
-const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until"];
+/**
+ * Whether a mandate entry matches a normalized counterparty: exactly, or for a `*.domain` entry the domain itself
+ * and any subdomain (SPEC section 5).
+ */
+export function counterpartyMatches(entry, counterparty) {
+    const e = normalizeCounterparty(entry);
+    if (e === counterparty)
+        return true;
+    if (!e.startsWith("*."))
+        return false;
+    const base = e.slice(2);
+    return counterparty === base || counterparty.endsWith(`.${base}`);
+}
+// `delegation` is reserved (validated, never listed as not evaluated) but is not a rule on actions: it is
+// enforced when a delegation chain is verified (delegation.ts).
+const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until", "delegation"];
 /** Deterministic evaluation of the reserved mandate fields against an intended action. */
 export function checkAction(mandate, q) {
     const now = q.now ?? new Date();
@@ -150,7 +195,8 @@ export function checkAction(mandate, q) {
     }
     if (mandate.counterparties && mandate.counterparties.length && q.counterparty) {
         const c = normalizeCounterparty(q.counterparty);
-        push("counterparties", mandate.counterparties.includes(c), `${c} ${mandate.counterparties.includes(c) ? "is" : "is not"} an allowed counterparty`);
+        const ok = mandate.counterparties.some((m) => counterpartyMatches(m, c));
+        push("counterparties", ok, `${c} ${ok ? "is" : "is not"} an allowed counterparty`);
     }
     if (mandate.payment_instruments && mandate.payment_instruments.length && q.payment_ref_sha256) {
         const h = q.payment_ref_sha256.trim().toLowerCase();

package/dist/person.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Natural persons as principals (D-29): "this agent key acts for a person who signed with an ICP-Brasil e-CPF".
+ * Privacy rules: the name is never stored or published; the CPF is never stored, published or revealed. The
+ * issuer keeps only HMAC(key, CPF) while a credential is alive, answers paying verifiers whether a CPF they
+ * already know matches, and gives each verifier its own pseudonymous subject reference for that person.
+ */
+import { type AgentKey } from "./types.js";
+import { type Challenge } from "./challenge.js";
+/** 11 digits; throws INVALID_INPUT on anything that is not a valid CPF (check digits included). */
+export declare function normalizeCpf(input: string): string;
+export declare function isValidCpf(input: string): boolean;
+/** Keyed hash of a CPF: what the issuer stores. Without the key, a CPF cannot be tested against it. */
+export declare const personHash: (keyB64: string, cpf: string) => Promise<string>;
+/**
+ * Pairwise subject reference: the same person gets a different, stable value for each verifier, so a verifier
+ * can track that person's agents on its side without two verifiers being able to link them.
+ */
+export declare const subjectRef: (keyB64: string, hash: string, verifier: string) => Promise<string>;
+/** Versioned keys from a JSON object {"1": "<base64 32 bytes>", "2": ...}; the highest version is current. */
+export declare function personKeys(json: string | undefined): {
+    current: {
+        version: number;
+        key: string;
+    };
+    all: Map<number, string>;
+} | null;
+/** Consent the person signs with the e-CPF; part of the challenge text, so the signature records it. */
+export declare const PERSON_CONSENT = "I authorize this issuer to keep a keyed hash of my CPF while this credential is valid and to answer, to verifiers who pay for each check, only whether a CPF they already have matches. My name and CPF are never stored in clear, published or revealed. / Autorizo este emissor a guardar um hash com chave do meu CPF enquanto esta credencial valer e a responder, a verificadores que pagam por consulta, apenas se um CPF que eles ja tem confere. Meu nome e meu CPF nunca sao guardados em claro, publicados ou revelados.";
+/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate). */
+export declare function personChallengeText(p: {
+    issuer: string;
+    challenge_id: string;
+    agent: AgentKey;
+    expires_at: string;
+}): string;
+/** The text a person signs with the e-CPF to see their own agents (accepted for 10 minutes after `at`). */
+export declare const personAgentsText: (at?: Date) => string;
+export declare function newPersonChallenge(p: {
+    issuer: string;
+    agent: AgentKey;
+    now?: Date;
+}): Challenge;

package/dist/person.js

@@ -0,0 +1,88 @@
+/**
+ * Natural persons as principals (D-29): "this agent key acts for a person who signed with an ICP-Brasil e-CPF".
+ * Privacy rules: the name is never stored or published; the CPF is never stored, published or revealed. The
+ * issuer keeps only HMAC(key, CPF) while a credential is alive, answers paying verifiers whether a CPF they
+ * already know matches, and gives each verifier its own pseudonymous subject reference for that person.
+ */
+import { KyaError } from "./types.js";
+import { CHALLENGE_TTL_SECONDS } from "./challenge.js";
+/** 11 digits; throws INVALID_INPUT on anything that is not a valid CPF (check digits included). */
+export function normalizeCpf(input) {
+    const d = String(input).replace(/\D/g, "");
+    if (!isValidCpf(d))
+        throw new KyaError("INVALID_INPUT", "cpf must be a valid Brazilian CPF");
+    return d;
+}
+export function isValidCpf(input) {
+    const d = String(input).replace(/\D/g, "");
+    if (d.length !== 11 || /^(\d)\1{10}$/.test(d))
+        return false;
+    const check = (len) => {
+        let sum = 0;
+        for (let i = 0; i < len; i++)
+            sum += Number(d[i]) * (len + 1 - i);
+        const r = (sum * 10) % 11;
+        return r === 10 ? 0 : r;
+    };
+    return check(9) === Number(d[9]) && check(10) === Number(d[10]);
+}
+const b64url = (u) => {
+    let s = "";
+    for (const b of u)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+const unb64 = (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+async function hmac(keyB64, message) {
+    const raw = unb64(keyB64);
+    if (raw.length < 32)
+        throw new KyaError("UPSTREAM_ERROR", "person key must be at least 32 bytes");
+    const key = await crypto.subtle.importKey("raw", raw.buffer, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return b64url(new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message))));
+}
+/** Keyed hash of a CPF: what the issuer stores. Without the key, a CPF cannot be tested against it. */
+export const personHash = (keyB64, cpf) => hmac(keyB64, `kya:cpf:${normalizeCpf(cpf)}`);
+/**
+ * Pairwise subject reference: the same person gets a different, stable value for each verifier, so a verifier
+ * can track that person's agents on its side without two verifiers being able to link them.
+ */
+export const subjectRef = (keyB64, hash, verifier) => hmac(keyB64, `kya:subject:${hash}:${verifier.toLowerCase()}`);
+/** Versioned keys from a JSON object {"1": "<base64 32 bytes>", "2": ...}; the highest version is current. */
+export function personKeys(json) {
+    if (!json)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new KyaError("UPSTREAM_ERROR", "PERSON_HMAC_KEYS is not valid JSON");
+    }
+    const all = new Map(Object.entries(parsed).map(([v, k]) => [Number(v), k]).filter(([v, k]) => Number.isInteger(v) && v > 0 && typeof k === "string"));
+    if (!all.size)
+        return null;
+    const version = Math.max(...all.keys());
+    return { current: { version, key: all.get(version) }, all };
+}
+/** Consent the person signs with the e-CPF; part of the challenge text, so the signature records it. */
+export const PERSON_CONSENT = "I authorize this issuer to keep a keyed hash of my CPF while this credential is valid and to answer, to verifiers who pay for each check, only whether a CPF they already have matches. My name and CPF are never stored in clear, published or revealed. / Autorizo este emissor a guardar um hash com chave do meu CPF enquanto esta credencial valer e a responder, a verificadores que pagam por consulta, apenas se um CPF que eles ja tem confere. Meu nome e meu CPF nunca sao guardados em claro, publicados ou revelados.";
+/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate). */
+export function personChallengeText(p) {
+    return [
+        "KYA Brasil: prove this agent key acts for me, a natural person",
+        `issuer: ${p.issuer}`,
+        `challenge: ${p.challenge_id}`,
+        `agent: ${p.agent.kind}:${p.agent.id}`,
+        "principal: person (e-CPF)",
+        `consent: ${PERSON_CONSENT}`,
+        `expires: ${p.expires_at}`
+    ].join("\n");
+}
+/** The text a person signs with the e-CPF to see their own agents (accepted for 10 minutes after `at`). */
+export const personAgentsText = (at = new Date()) => `KYA Brasil: my agents\nat: ${at.toISOString()}`;
+export function newPersonChallenge(p) {
+    const now = p.now ?? new Date();
+    const challenge_id = crypto.randomUUID();
+    const expires_at = new Date(now.getTime() + CHALLENGE_TTL_SECONDS * 1000).toISOString();
+    return { challenge_id, expires_at, text: personChallengeText({ issuer: p.issuer, challenge_id, agent: p.agent, expires_at }) };
+}

package/dist/types.d.ts

@@ -27,6 +27,11 @@ export interface PaymentInstrument {
     /** Optional human label, e.g. "corporate card, purchasing". Never the card number. */
     label?: string;
 }
+/** What a mandate allows its agent to delegate (D-30). */
+export interface DelegationPolicy {
+    max_depth: number;
+    max_ttl_seconds: number;
+}
 export interface MandateCore {
     /** Actions the agent may take on behalf of the company (free vocabulary, lowercase: buy, sell, quote, pay, sign, ...). */
     actions?: string[];
@@ -50,6 +55,11 @@ export interface MandateCore {
      * removed, case kept); empty or absent = any.
      */
     payment_instruments?: PaymentInstrument[];
+    /**
+     * Delegation to sub-agents (D-30): the agent may hand a narrower mandate to other keys, up to `max_depth`
+     * levels below it, each delegation living at most `max_ttl_seconds`. Absent = the agent cannot delegate.
+     */
+    delegation?: DelegationPolicy;
     /** Mandate validity (ISO dates); the credential never outlives it. */
     valid_from?: string;
     valid_until?: string;
@@ -67,22 +77,31 @@ export interface KybSnapshot {
     red_flags: string[];
     checked_at: string;
 }
+export interface CompanyPrincipal {
+    kind?: "company";
+    cnpj: string;
+    cnpj_formatted: string;
+    legal_name: string;
+    registration_status: string;
+}
+/** D-29: a person who signed with an e-CPF. Never a name, a CPF or a hash of it; verifiers check a CPF they know through the issuer. */
+export interface PersonPrincipal {
+    kind: "person";
+    verified_by: "icp-brasil-e-cpf";
+}
+export declare const isPersonPrincipal: (p: CompanyPrincipal | PersonPrincipal) => p is PersonPrincipal;
 /** The credential: "this agent key acts for this company, within this mandate, verified on this date". */
 export interface Credential {
     credential_id: string;
     version: 1;
     agent: AgentKey;
-    principal: {
-        cnpj: string;
-        cnpj_formatted: string;
-        legal_name: string;
-        registration_status: string;
-    };
-    /** How the company authorized it: hash of the e-CNPJ certificate that signed the challenge (never the CPF of the signer). */
+    /** A company (e-CNPJ) or, since D-29, a natural person (e-CPF) with no personal data: tell them apart by `kind`. */
+    principal: CompanyPrincipal | PersonPrincipal;
+    /** How the principal authorized it: hash of the ICP-Brasil certificate that signed the challenge. No subject for persons. */
     authorized_by: {
-        method: "icp-brasil-e-cnpj";
+        method: "icp-brasil-e-cnpj" | "icp-brasil-e-cpf";
         certificate_sha256: string;
-        certificate_subject: string;
+        certificate_subject?: string;
         issuer: string;
         signed_at: string;
     };

package/dist/types.js

@@ -1,4 +1,5 @@
 /** Shared types of KYA Brasil. Within /v1 fields are only added, never renamed or removed. */
+export const isPersonPrincipal = (p) => p.kind === "person";
 export class KyaError extends Error {
     code;
     constructor(code, message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "KYA Brasil as a library: verify and issue know-your-agent credentials for Brazilian companies without any hosted service. e-CNPJ (ICP-Brasil) CMS signature and chain validation, CRL revocation, CNPJ, agent key challenges (EVM, Ed25519 / Web Bot Auth, ERC-8004), mandate schema and evaluation (including payment instruments for card networks and acquirers), credential build, Ed25519 signing and verification, and e-CNPJ signing for the holder (A1 .pfx, or any token/HSM/cloud signer through a raw-sign callback). Pure functions: storage and network are yours.",
   "license": "MIT",
   "type": "module",