@kya-brasil/core 0.8.0 → 0.10.0

package/README.md

@@ -87,6 +87,22 @@ const sig = await a3.sign(readSigningLink(link).text);       // the text from a
 `openToken({ library, pin })` in `@kya-brasil/agent-tools` (and the `kya-sign --pkcs11` command) already wires
 `C_Sign` into `ecnpjSigner`.
 
+### Cloud certificates (PSC)
+
+`CloudSignatureProvider` is the interface for an e-CNPJ held by an ICP-Brasil PSC: `authorizationUrl` (OAuth with
+PKCE), `exchangeCode` returning a session with `certificates()` and `signHash(sha256)`. No PSC is implemented here
+(each has its own contract); implement it for yours from
+[examples/cloud-provider](https://github.com/celfons/kya-brasil/tree/main/examples/cloud-provider) and then:
+
+```ts
+import { cloudSigner, pkcePair, newState } from "@kya-brasil/core";
+const { verifier, challenge } = await pkcePair();
+const url = await provider.authorizationUrl({ redirectUri, state: newState(), codeChallenge: challenge });
+// … the person approves, your redirect URI gets ?code=…&state=…
+const signer = await cloudSigner(await provider.exchangeCode({ code, redirectUri, codeVerifier: verifier }));
+const ecnpj_signature = await signer.sign(challengeText);
+```
+
 ## Run your own issuer
 
 ```ts

package/dist/cloud-sign.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cloud e-CNPJ (D-28): the certificate lives at an ICP-Brasil PSC (prestador de serviço de confiança) and signs
+ * after the holder approves, usually on the phone. Each PSC has its own contract, registration and API details,
+ * so this project ships the interface only: whoever has an agreement with a PSC implements CloudSignatureProvider
+ * for it and plugs it into the three entry points (this library, `kya-sign --cloud`, the /sign page of a
+ * self-hosted issuer). The KYA side (PKCE, single-use state, the CMS, what is signed) is done here.
+ *
+ * Typical PSC flow (OAuth 2.0 authorization code with PKCE): send the person to authorizationUrl, get a code at
+ * the redirect URI, exchange it for a session, read the certificate, sign hashes. Ask the PSC for the narrowest
+ * session it offers (one signature, minutes of lifetime).
+ */
+import { type ECnpjSigner } from "./ecnpj-sign.js";
+/** An authorized session at the PSC: the certificate and a way to sign one SHA-256 hash. */
+export interface CloudSession {
+    /** Signer certificate first, then the chain if the PSC returns it (DER). */
+    certificates(): Promise<Uint8Array[]>;
+    /**
+     * RSA PKCS#1 v1.5 signature over a SHA-256 hash (32 bytes) computed by the caller: what PSC APIs usually
+     * call a "raw" or "PKCS1" signature of a hash. Return the signature bytes.
+     */
+    signHash(sha256: Uint8Array): Promise<Uint8Array>;
+    /** Revoke or forget the session at the PSC, when it supports it. */
+    close?(): Promise<void>;
+}
+/** One PSC. Implement it with your own registration (client id/secret, redirect URIs) and the PSC's API. */
+export interface CloudSignatureProvider {
+    /** Short id used in URLs and on the command line, e.g. "my-psc". Lowercase letters, digits, "-". */
+    readonly id: string;
+    /** Name shown to the person, e.g. "BirdID", "VIDaaS". */
+    readonly name: string;
+    /**
+     * Where to send the person to log in and approve. Must carry `state` and the PKCE `codeChallenge` (S256) so the
+     * code comes back to `redirectUri` bound to this request. `loginHint` may carry a CNPJ/CPF when the PSC accepts it.
+     */
+    authorizationUrl(p: {
+        redirectUri: string;
+        state: string;
+        codeChallenge: string;
+        loginHint?: string;
+    }): string | Promise<string>;
+    /** Exchanges the code for a session (server or CLI side: this is where a client secret would be used). */
+    exchangeCode(p: {
+        code: string;
+        redirectUri: string;
+        codeVerifier: string;
+    }): Promise<CloudSession>;
+}
+/** PKCE (RFC 7636, S256): a random verifier kept by us and the challenge sent to the PSC. */
+export declare function pkcePair(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/** A random, single-use OAuth state value. */
+export declare const newState: () => string;
+/** Valid provider ids: what can safely go in a URL path or a CLI flag. */
+export declare const isProviderId: (id: string) => boolean;
+/**
+ * An e-CNPJ signer over a PSC session: the CMS is built here, the PSC only signs the SHA-256 of the signed
+ * attributes. Same interface as openPfx (A1) and openToken (A3), so everything downstream is unchanged.
+ */
+export declare function cloudSigner(session: CloudSession): Promise<ECnpjSigner>;

package/dist/cloud-sign.js

@@ -0,0 +1,49 @@
+/**
+ * Cloud e-CNPJ (D-28): the certificate lives at an ICP-Brasil PSC (prestador de serviço de confiança) and signs
+ * after the holder approves, usually on the phone. Each PSC has its own contract, registration and API details,
+ * so this project ships the interface only: whoever has an agreement with a PSC implements CloudSignatureProvider
+ * for it and plugs it into the three entry points (this library, `kya-sign --cloud`, the /sign page of a
+ * self-hosted issuer). The KYA side (PKCE, single-use state, the CMS, what is signed) is done here.
+ *
+ * Typical PSC flow (OAuth 2.0 authorization code with PKCE): send the person to authorizationUrl, get a code at
+ * the redirect URI, exchange it for a session, read the certificate, sign hashes. Ask the PSC for the narrowest
+ * session it offers (one signature, minutes of lifetime).
+ */
+import { ecnpjSigner } from "./ecnpj-sign.js";
+import { KyaError } from "./types.js";
+const toArrayBuffer = (u) => u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+const b64url = (u) => {
+    let s = "";
+    for (const b of u)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+/** PKCE (RFC 7636, S256): a random verifier kept by us and the challenge sent to the PSC. */
+export async function pkcePair() {
+    const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
+    const challenge = b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+    return { verifier, challenge };
+}
+/** A random, single-use OAuth state value. */
+export const newState = () => b64url(crypto.getRandomValues(new Uint8Array(24)));
+/** Valid provider ids: what can safely go in a URL path or a CLI flag. */
+export const isProviderId = (id) => /^[a-z0-9][a-z0-9-]{0,31}$/.test(id);
+/**
+ * An e-CNPJ signer over a PSC session: the CMS is built here, the PSC only signs the SHA-256 of the signed
+ * attributes. Same interface as openPfx (A1) and openToken (A3), so everything downstream is unchanged.
+ */
+export async function cloudSigner(session) {
+    const certificates = await session.certificates();
+    if (!certificates.length)
+        throw new KyaError("CERTIFICATE_INVALID", "the cloud provider returned no certificate");
+    return ecnpjSigner({
+        certificates,
+        sign: async (data) => {
+            const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", toArrayBuffer(data)));
+            const sig = await session.signHash(hash);
+            if (!sig?.length)
+                throw new KyaError("UPSTREAM_ERROR", "the cloud provider returned an empty signature");
+            return sig;
+        }
+    });
+}

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/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

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

package/dist/index.js

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

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

@@ -67,22 +67,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.8.0",
+  "version": "0.10.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",