@kya-brasil/core 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @kya-brasil/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+KYA Brasil as a library. Verify, or issue, know-your-agent credentials for Brazilian companies inside your own
+systems, with no hosted service in the path: the same code the reference issuer runs, as pure functions.
+
+- **e-CNPJ (ICP-Brasil)**: CMS/PKCS#7 signature validation, chain up to the ICP-Brasil roots, CNPJ read from the certificate.
+- **Revocation**: CRL verification against the issuing AC and the effect on a credential (revoke, suspend, nothing).
+- **Agent keys**: challenge text and signature checks for EVM wallets (EIP-191), Ed25519 (Web Bot Auth, RFC 9421) and ERC-8004 agents.
+- **Mandate**: schema, validation and deterministic evaluation of an intended action, including **payment instruments** for card networks, acquirers and issuers.
+- **Credential**: build, sign and verify (Ed25519 over canonical JSON), offline.
+- **CNPJ**: normalize, validate, format.
+
+Storage, network calls and keys stay yours: the library never fetches anything except an ERC-8004 lookup over
+the RPC transport you give it. Spec: [docs/SPEC.md](https://github.com/celfons/kya-brasil/blob/main/docs/SPEC.md).
+
+```sh
+npm install @kya-brasil/core
+```
+
+ESM, Node 18+, Workers, Deno and browsers (Web Crypto).
+
+## Verify a credential and an action, offline
+
+A credential from any KYA issuer (the hosted one, yours, a partner's) is checked with that issuer's public key,
+published at `<issuer>/.well-known/kya.json`.
+
+```ts
+import { verifyCredentialSignature, effectiveStatus, checkAction, hashPaymentRef } from "@kya-brasil/core";
+
+const sig = await verifyCredentialSignature(credential, issuerPublicJwk); // { valid, key_id, signed_at }
+if (!sig.valid || effectiveStatus(credential) !== "active") deny();
+// For live status (revoked or suspended after issuance) read credential.verify_url, or accept that risk until expires_at.
+
+const verdict = checkAction(credential.mandate, {
+  action: "buy",
+  amount: 4200,
+  currency: "BRL",
+  counterparty: "33000167000101",
+  spent_today: 9000,                                   // your own count; nobody else keeps it
+  payment_network: "visa",
+  payment_ref_sha256: await hashPaymentRef(tokenRef)   // the network token reference or PAR of this transaction
+});
+// verdict.allowed, verdict.checks (every rule evaluated, with its reason), verdict.not_evaluated (extensions)
+```
+
+## 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
+the network already gives (network token reference, Payment Account Reference), **never a card number**:
+
+```json
+{
+  "actions": ["buy"],
+  "max_per_operation": { "amount": 5000, "currency": "BRL" },
+  "payment_instruments": [
+    { "network": "visa", "ref_sha256": "9f2c…", "label": "purchasing" },
+    { "network": "mastercard", "ref_sha256": "a71b…" }
+  ]
+}
+```
+
+- `ref_sha256` = lowercase hex SHA-256 of the reference, UTF-8, whitespace removed, case kept. `hashPaymentRef(ref)` does exactly that.
+- `validateMandate` refuses anything that is not a 64-hex hash, labels containing long digit runs, unknown fields and duplicates, so a PAN cannot slip into a credential.
+- At authorization time, hash the reference you received and pass it to `checkAction`: the verdict says whether that instrument belongs to an agent the company (CNPJ, e-CNPJ-signed) authorized, within its limits. When the mandate has no list, or you pass no reference, the rule is not evaluated.
+
+With the hosted issuer, the same check comes back signed from
+`GET /v1/agents/{id}/allowed?payment_network=visa&payment_ref_sha256=…`, which is evidence for a later dispute.
+
+## Run your own issuer
+
+```ts
+import {
+  newChallenge, verifyAgentSignature, verifyIcpSignature, checkRevocation,
+  validateMandate, buildCredential, signCredential, importPrivateKey, generateAttestationKey
+} from "@kya-brasil/core";
+
+const key = await generateAttestationKey();               // once; keep privateKeyPkcs8 secret, publish publicJwk
+const ch = newChallenge({ issuer: "https://kya.acquirer.example", agent, cnpj });
+// The agent signs ch.text with its key; the company signs ch.text with its e-CNPJ (detached CMS).
+if (!(await verifyAgentSignature(agent, ch.text, agentSignature))) throw new Error("agent signature");
+const icp = await verifyIcpSignature({ cmsBase64: ecnpjSignature, challenge: ch.text, expectedCnpj: cnpj, anchors });
+// anchors: the ICP-Brasil roots as PEM strings (bundle in the repository: anchors/icp-brasil.pem).
+const crlDer = await fetchCrl(icp.crl_urls);             // yours: HTTP + cache
+const rev = await checkRevocation({ crlDer, serial: icp.serial_number, issuerCertificate: icp.issuer_certificate! });
+if (rev.revoked) throw new Error("certificate revoked");
+
+const credential = await signCredential(
+  buildCredential({
+    credential_id: crypto.randomUUID(), agent, cnpj,
+    legal_name, registration_status,                      // from your registration source; "UNVERIFIED" if none answered
+    certificate: { sha256: icp.certificate_sha256, subject: icp.certificate_subject, issuer: icp.issuer, signed_at: icp.signed_at },
+    mandate: validateMandate(mandate),
+    issuer: "https://kya.acquirer.example"
+  }),
+  await importPrivateKey(key.privateKeyPkcs8), key.keyId
+);
+```
+
+What the library leaves to you: persistence, the challenge's single use and expiry, fetching and caching CRLs,
+the company's registration status (the reference issuer reads the Receita's open data), key custody and the
+publication of your public key. `apps/worker` in the repository is a complete issuer built this way.
+
+## Compatibility
+
+Credentials follow `/v1` of the spec: fields are only ever added. Test vectors:
+[docs/vectors/credential-v1.json](https://github.com/celfons/kya-brasil/blob/main/docs/vectors/credential-v1.json).
+
+MIT. Issues and contributions: https://github.com/celfons/kya-brasil

package/dist/attestation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Signed attestation of an answer: "this service returned exactly this JSON at this time".
+ * Ed25519 over the SHA-256 of the canonical JSON (keys sorted, no whitespace) of the answer
+ * without `attestation` and `receipt`. WebCrypto only, so it runs on Workers and Node alike.
+ */
+import type { Attestation } from "./types.js";
+export declare function canonicalize(v: unknown): string;
+export declare function attestedPayload(answer: Record<string, unknown>): Record<string, unknown>;
+/** New Ed25519 key pair: private as PKCS#8 base64 (store as a secret), public as JWK (publish). */
+export declare function generateAttestationKey(): Promise<{
+    privateKeyPkcs8: string;
+    publicJwk: JsonWebKey;
+    keyId: string;
+}>;
+/** key_id = first 16 hex chars of SHA-256 of the raw public key. */
+export declare function keyIdOf(publicJwk: JsonWebKey): Promise<string>;
+export declare function importPrivateKey(pkcs8Base64: string): Promise<CryptoKey>;
+export declare function publicJwkFromPrivate(pkcs8Base64: string): Promise<JsonWebKey>;
+export declare function signAttestation(answer: Record<string, unknown>, privateKey: CryptoKey, keyId: string, verifyUrl: string, now?: Date): Promise<Attestation>;
+/** Recomputes the hash from the answer and checks the signature with the public key. */
+export declare function verifyAttestation(answer: Record<string, unknown>, publicJwk: JsonWebKey): Promise<{
+    valid: boolean;
+    reason?: string;
+    key_id?: string;
+    signed_at?: string;
+}>;

package/dist/attestation.js

@@ -0,0 +1,80 @@
+/**
+ * Key order of the canonical JSON: UTF-16 code units, exactly what a comparator-less sort() does. Not
+ * localeCompare: a locale-dependent order would change the signed bytes between machines and break every
+ * signature already issued.
+ */
+function byCodeUnit(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+export function canonicalize(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalize).join(",")}]`;
+    const o = v;
+    const members = Object.keys(o)
+        .filter((k) => o[k] !== undefined)
+        .sort(byCodeUnit)
+        .map((k) => JSON.stringify(k) + ":" + canonicalize(o[k]));
+    return "{" + members.join(",") + "}";
+}
+export function attestedPayload(answer) {
+    const { attestation: _a, receipt: _r, ...rest } = answer;
+    return rest;
+}
+const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)));
+const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+async function sha256(text) {
+    const bytes = new TextEncoder().encode(text);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return { hex: hex(digest), bytes: new Uint8Array(digest) };
+}
+/** New Ed25519 key pair: private as PKCS#8 base64 (store as a secret), public as JWK (publish). */
+export async function generateAttestationKey() {
+    const kp = (await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]));
+    const pkcs8 = (await crypto.subtle.exportKey("pkcs8", kp.privateKey));
+    const jwk = (await crypto.subtle.exportKey("jwk", kp.publicKey));
+    return { privateKeyPkcs8: b64(pkcs8), publicJwk: jwk, keyId: await keyIdOf(jwk) };
+}
+/** key_id = first 16 hex chars of SHA-256 of the raw public key. */
+export async function keyIdOf(publicJwk) {
+    return (await sha256(publicJwk.x ?? "")).hex.slice(0, 16);
+}
+export async function importPrivateKey(pkcs8Base64) {
+    return crypto.subtle.importKey("pkcs8", unb64(pkcs8Base64), { name: "Ed25519" }, true, ["sign"]);
+}
+export async function publicJwkFromPrivate(pkcs8Base64) {
+    const priv = await crypto.subtle.importKey("pkcs8", unb64(pkcs8Base64), { name: "Ed25519" }, true, ["sign"]);
+    const jwk = (await crypto.subtle.exportKey("jwk", priv));
+    const { d: _d, ...pub } = jwk; // drop the private part
+    return { ...pub, key_ops: ["verify"] };
+}
+export async function signAttestation(answer, privateKey, keyId, verifyUrl, now = new Date()) {
+    const payload = attestedPayload(answer);
+    const { hex: digestHex, bytes } = await sha256(canonicalize(payload));
+    const signed_at = now.toISOString();
+    const message = new TextEncoder().encode(`${digestHex}\n${signed_at}`);
+    const sig = await crypto.subtle.sign({ name: "Ed25519" }, privateKey, message);
+    void bytes;
+    return { algorithm: "ed25519", key_id: keyId, sha256: digestHex, signed_at, signature: b64(sig), verify_url: verifyUrl };
+}
+/** Recomputes the hash from the answer and checks the signature with the public key. */
+export async function verifyAttestation(answer, publicJwk) {
+    const att = answer.attestation;
+    if (!att || att.algorithm !== "ed25519")
+        return { valid: false, reason: "no ed25519 attestation in the answer" };
+    const { hex: digestHex } = await sha256(canonicalize(attestedPayload(answer)));
+    if (digestHex !== att.sha256)
+        return { valid: false, reason: "content hash mismatch: the answer was modified", key_id: att.key_id, signed_at: att.signed_at };
+    const keyId = await keyIdOf(publicJwk);
+    if (keyId !== att.key_id)
+        return { valid: false, reason: `signed with key ${att.key_id}, verifying with ${keyId}`, key_id: att.key_id, signed_at: att.signed_at };
+    const key = await crypto.subtle.importKey("jwk", publicJwk, { name: "Ed25519" }, true, ["verify"]);
+    const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, unb64(att.signature), new TextEncoder().encode(`${digestHex}\n${att.signed_at}`));
+    return ok ? { valid: true, key_id: att.key_id, signed_at: att.signed_at } : { valid: false, reason: "signature does not verify", key_id: att.key_id, signed_at: att.signed_at };
+}

package/dist/challenge.d.ts

@@ -0,0 +1,31 @@
+import { type AgentKey } from "./types.js";
+export declare const CHALLENGE_TTL_SECONDS = 900;
+export interface Challenge {
+    challenge_id: string;
+    text: string;
+    expires_at: string;
+}
+export declare function normalizeAgentKey(input: {
+    kind?: unknown;
+    id?: unknown;
+}): AgentKey;
+/** The exact text the agent signs. Line-based so wallets show it readably. */
+export declare function challengeText(p: {
+    issuer: string;
+    challenge_id: string;
+    agent: AgentKey;
+    cnpj: string;
+    expires_at: string;
+}): string;
+export declare function newChallenge(p: {
+    issuer: string;
+    agent: AgentKey;
+    cnpj: string;
+    now?: Date;
+}): Challenge;
+/** True when `signature` is the agent key's signature over `text`. Never throws on a bad signature. */
+export declare function verifyAgentSignature(agent: AgentKey, text: string, signature: string): Promise<boolean>;
+export declare const base64url: {
+    encode: (bytes: Uint8Array) => string;
+    decode: (s: string) => Uint8Array<ArrayBuffer>;
+};

package/dist/challenge.js

@@ -0,0 +1,91 @@
+/**
+ * Proof of key possession by the agent. The issuer hands out a one-time challenge; the agent
+ * signs it with its key. Three key kinds:
+ *   evm           EIP-191 personal_sign over the challenge text; address recovered and compared
+ *   web-bot-auth  Ed25519 (RFC 9421 key material) raw signature over the challenge bytes
+ *   erc8004       EIP-191 by the agent's on-chain agentWallet (resolved by the caller, see erc8004.ts)
+ * The challenge text binds agent key, CNPJ, issuer and expiry, so a signature cannot be replayed
+ * for another company or another issuer.
+ */
+import { verifyMessage, getAddress, isAddress } from "viem";
+import { KyaError } from "./types.js";
+import { parseErc8004Id } from "./erc8004.js";
+export const CHALLENGE_TTL_SECONDS = 900;
+/** Drops trailing "=" padding with a linear scan (no regex). */
+const stripPadding = (s) => {
+    let end = s.length;
+    while (end > 0 && s[end - 1] === "=")
+        end--;
+    return s.slice(0, end);
+};
+const b64u = (bytes) => stripPadding(btoa(String.fromCodePoint(...bytes)).replaceAll("+", "-").replaceAll("/", "_"));
+const unb64u = (s) => {
+    const b64 = s.replaceAll("-", "+").replaceAll("_", "/");
+    return Uint8Array.from(atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "=")), (c) => c.codePointAt(0) ?? 0);
+};
+export function normalizeAgentKey(input) {
+    if (input.kind === "evm") {
+        if (typeof input.id !== "string" || !isAddress(input.id))
+            throw new KyaError("INVALID_INPUT", "agent.id must be a 0x EVM address for kind evm");
+        return { kind: "evm", id: getAddress(input.id) };
+    }
+    if (input.kind === "web-bot-auth") {
+        if (typeof input.id !== "string")
+            throw new KyaError("INVALID_INPUT", "agent.id must be the Ed25519 public key (base64url, 32 bytes) for kind web-bot-auth");
+        let raw;
+        try {
+            raw = unb64u(input.id);
+        }
+        catch {
+            throw new KyaError("INVALID_INPUT", "agent.id is not base64url");
+        }
+        if (raw.length !== 32)
+            throw new KyaError("INVALID_INPUT", "agent.id must decode to 32 bytes");
+        return { kind: "web-bot-auth", id: b64u(raw) };
+    }
+    if (input.kind === "erc8004") {
+        const { id } = parseErc8004Id(input.id);
+        return { kind: "erc8004", id };
+    }
+    throw new KyaError("INVALID_INPUT", "agent.kind must be evm, web-bot-auth or erc8004");
+}
+/** The exact text the agent signs. Line-based so wallets show it readably. */
+export function challengeText(p) {
+    return [
+        "KYA Brasil: prove this agent key acts for a company",
+        `issuer: ${p.issuer}`,
+        `challenge: ${p.challenge_id}`,
+        `agent: ${p.agent.kind}:${p.agent.id}`,
+        `cnpj: ${p.cnpj}`,
+        `expires: ${p.expires_at}`
+    ].join("\n");
+}
+export function newChallenge(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: challengeText({ issuer: p.issuer, challenge_id, agent: p.agent, cnpj: p.cnpj, expires_at }) };
+}
+/** True when `signature` is the agent key's signature over `text`. Never throws on a bad signature. */
+export async function verifyAgentSignature(agent, text, signature) {
+    try {
+        if (agent.kind === "evm" || agent.kind === "erc8004") {
+            if (!/^0x[0-9a-fA-F]{130}$/.test(signature))
+                return false;
+            const address = agent.kind === "evm" ? agent.id : agent.wallet;
+            if (!address)
+                return false; // erc8004 without a resolved wallet: nothing to compare against
+            return await verifyMessage({ address: address, message: text, signature: signature });
+        }
+        const raw = unb64u(agent.id);
+        const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+        const sig = unb64u(signature);
+        if (sig.length !== 64)
+            return false;
+        return await crypto.subtle.verify({ name: "Ed25519" }, key, sig, new TextEncoder().encode(text));
+    }
+    catch {
+        return false;
+    }
+}
+export const base64url = { encode: b64u, decode: unb64u };

package/dist/cnpj.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CNPJ (Cadastro Nacional da Pessoa Jurídica) helpers.
+ *
+ * Since 2026 the Receita Federal accepts alphanumeric CNPJs (letters in the first
+ * 12 positions, digits in the 2 check digits). The check-digit algorithm maps each
+ * character to (ASCII code - 48), so digits keep their value and letters get 17..42.
+ */
+/** Strip punctuation and whitespace, upper-case letters. Does not validate. */
+export declare function normalizeCnpj(input: string): string;
+/** True when the string is a syntactically valid (numeric or alphanumeric) CNPJ. */
+export declare function isValidCnpj(input: string): boolean;
+/** Format as XX.XXX.XXX/XXXX-XX. Input must already be 14 chars. */
+export declare function formatCnpj(cnpj: string): string;
+/** First 8 characters: identifies the company; the remaining 4 identify the branch (0001 = HQ). */
+export declare function cnpjRoot(cnpj: string): string;
+export declare function isHeadquarters(cnpj: string): boolean;

package/dist/cnpj.js

@@ -0,0 +1,49 @@
+/**
+ * CNPJ (Cadastro Nacional da Pessoa Jurídica) helpers.
+ *
+ * Since 2026 the Receita Federal accepts alphanumeric CNPJs (letters in the first
+ * 12 positions, digits in the 2 check digits). The check-digit algorithm maps each
+ * character to (ASCII code - 48), so digits keep their value and letters get 17..42.
+ */
+const WEIGHTS_1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+const WEIGHTS_2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+/** Strip punctuation and whitespace, upper-case letters. Does not validate. */
+export function normalizeCnpj(input) {
+    return input.replace(/[^0-9A-Za-z]/g, "").toUpperCase();
+}
+function charValue(ch) {
+    return ch.charCodeAt(0) - 48;
+}
+function checkDigit(base, weights) {
+    let sum = 0;
+    for (let i = 0; i < weights.length; i++) {
+        sum += charValue(base[i]) * weights[i];
+    }
+    const mod = sum % 11;
+    return mod < 2 ? 0 : 11 - mod;
+}
+/** True when the string is a syntactically valid (numeric or alphanumeric) CNPJ. */
+export function isValidCnpj(input) {
+    const cnpj = normalizeCnpj(input);
+    if (!/^[0-9A-Z]{12}[0-9]{2}$/.test(cnpj))
+        return false;
+    if (/^(.)\1{13}$/.test(cnpj))
+        return false;
+    const d1 = checkDigit(cnpj.slice(0, 12), WEIGHTS_1);
+    const d2 = checkDigit(cnpj.slice(0, 12) + String(d1), WEIGHTS_2);
+    return cnpj[12] === String(d1) && cnpj[13] === String(d2);
+}
+/** Format as XX.XXX.XXX/XXXX-XX. Input must already be 14 chars. */
+export function formatCnpj(cnpj) {
+    const c = normalizeCnpj(cnpj);
+    if (c.length !== 14)
+        throw new Error(`Invalid CNPJ length: ${c.length}`);
+    return `${c.slice(0, 2)}.${c.slice(2, 5)}.${c.slice(5, 8)}/${c.slice(8, 12)}-${c.slice(12)}`;
+}
+/** First 8 characters: identifies the company; the remaining 4 identify the branch (0001 = HQ). */
+export function cnpjRoot(cnpj) {
+    return normalizeCnpj(cnpj).slice(0, 8);
+}
+export function isHeadquarters(cnpj) {
+    return normalizeCnpj(cnpj).slice(8, 12) === "0001";
+}

package/dist/credential.d.ts

@@ -0,0 +1,43 @@
+import type { Credential, CredentialStatus, KybSnapshot, Mandate, AgentKey } from "./types.js";
+export declare const CREDENTIAL_TTL_DAYS = 90;
+export declare function buildCredential(p: {
+    credential_id: string;
+    agent: AgentKey;
+    cnpj: string;
+    legal_name: string;
+    registration_status: string;
+    certificate: {
+        sha256: string;
+        subject: string;
+        issuer: string;
+        signed_at: string;
+    };
+    mandate: Mandate;
+    /** /v1 compatibility only; leave out (null). */
+    kyb?: KybSnapshot | null;
+    issuer: string;
+    now?: Date;
+    status?: CredentialStatus;
+    status_reason?: string | null;
+}): 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;
+    reason?: string;
+    key_id?: string;
+    signed_at?: string;
+}>;
+/** Stable hash of the credential content (what the signature covers). */
+export declare function credentialDigest(c: Credential): Promise<string>;
+/**
+ * Whether the company can still answer for an agent (D-15): only its existence as a legal entity,
+ * i.e. registration ATIVA at the Receita Federal. Sanctions, debt and risk are facts about the company
+ * for the verifier to weigh with its own screening, never a reason to deny or suspend the credential.
+ */
+/** D-24: statuses that mean "not known", not "not active": the check was off or no source answered. */
+export declare const UNKNOWN_REGISTRATION: string[];
+export declare function principalDecision(registration_status: string): {
+    ok: boolean;
+    reason: string | null;
+};
+export declare function effectiveStatus(c: Pick<Credential, "status" | "expires_at">, now?: Date): CredentialStatus;

package/dist/credential.js

@@ -0,0 +1,65 @@
+/**
+ * Credential assembly, signing and verification. The signature is an Ed25519 attestation over the
+ * SHA-256 of the canonical JSON without `attestation`, so the public key document at
+ * /.well-known/kya.json and the SDK's verifyAttestation() verify credentials and verdicts alike.
+ */
+import { attestedPayload, canonicalize, signAttestation, verifyAttestation } from "./attestation.js";
+import { formatCnpj, normalizeCnpj } from "./cnpj.js";
+export const CREDENTIAL_TTL_DAYS = 90;
+export function buildCredential(p) {
+    const now = p.now ?? new Date();
+    const cnpj = normalizeCnpj(p.cnpj);
+    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: { cnpj, cnpj_formatted: formatCnpj(cnpj), legal_name: p.legal_name, registration_status: p.registration_status },
+        authorized_by: { method: "icp-brasil-e-cnpj", certificate_sha256: p.certificate.sha256, certificate_subject: p.certificate.subject, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at },
+        mandate: p.mandate,
+        kyb_snapshot: p.kyb ?? null,
+        status: p.status ?? "active",
+        status_reason: p.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);
+    return { ...payload, attestation };
+}
+export async function verifyCredentialSignature(c, publicJwk) {
+    return verifyAttestation(c, publicJwk);
+}
+/** Stable hash of the credential content (what the signature covers). */
+export async function credentialDigest(c) {
+    const bytes = new TextEncoder().encode(canonicalize(attestedPayload(c)));
+    const d = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Whether the company can still answer for an agent (D-15): only its existence as a legal entity,
+ * i.e. registration ATIVA at the Receita Federal. Sanctions, debt and risk are facts about the company
+ * for the verifier to weigh with its own screening, never a reason to deny or suspend the credential.
+ */
+/** D-24: statuses that mean "not known", not "not active": the check was off or no source answered. */
+export const UNKNOWN_REGISTRATION = ["UNVERIFIED", "NOT_CHECKED"];
+export function principalDecision(registration_status) {
+    // Only a confirmed status other than ATIVA blocks; an unknown one is carried as a warning (D-24).
+    if (UNKNOWN_REGISTRATION.includes(registration_status))
+        return { ok: true, reason: null };
+    if (registration_status !== "ATIVA")
+        return { ok: false, reason: `company is ${registration_status} at the Receita Federal` };
+    return { ok: true, reason: null };
+}
+export function effectiveStatus(c, now = new Date()) {
+    if (c.status === "active" && Date.parse(c.expires_at) < now.getTime())
+        return "expired";
+    return c.status;
+}

package/dist/erc8004.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ERC-8004 (Trustless Agents) identities, read-only. An agent registered in an Identity Registry
+ * (an ERC-721 token) is addressed as
+ *
+ *   eip155:<chainId>:<identityRegistry>:<agentId>
+ *
+ * and signs the challenge with its `agentWallet` (the registry's reserved metadata key; defaults to the
+ * token owner). The issuer resolves that wallet on chain at registration, at proof and in the daily
+ * review, so a credential never outlives a wallet change. Nothing is written on chain in this version.
+ */
+import { type Transport } from "viem";
+/** Canonical registries (deterministic deployment, same address on every chain of its kind). */
+export declare const ERC8004_IDENTITY_REGISTRIES: Record<number, `0x${string}`>;
+export declare const DEFAULT_RPC_URLS: Record<number, string>;
+export declare const ERC8004_IDENTITY_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "getAgentWallet";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "ownerOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tokenURI";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}];
+export interface Erc8004Id {
+    chainId: number;
+    registry: `0x${string}`;
+    agentId: bigint;
+}
+/** Parses and normalizes `eip155:<chainId>:<registry>:<agentId>`; throws INVALID_INPUT otherwise. */
+export declare function parseErc8004Id(id: unknown): Erc8004Id & {
+    id: string;
+};
+export interface ResolveOptions {
+    /** RPC URL for the chain; defaults to DEFAULT_RPC_URLS[chainId]. */
+    rpcUrl?: string;
+    /** Test hook: a viem transport (e.g. custom({ request })) instead of HTTP. */
+    transport?: Transport;
+}
+/**
+ * The wallet that signs for the agent: `getAgentWallet(agentId)` (ERC-8004 reserved metadata), falling
+ * back to `ownerOf(agentId)` on registries without the getter. Throws NOT_FOUND when the token does not
+ * exist and UPSTREAM_ERROR when the chain cannot be read.
+ */
+export declare function resolveAgentWallet(ref: Erc8004Id, opts?: ResolveOptions): Promise<`0x${string}`>;
+/** Test helper: a viem transport answering eth_call from a map of function selector → ABI-encoded result. */
+export declare function mockTransport(answers: Record<string, string | Error>): Transport;