@kya-brasil/agent-tools 0.5.3 → 0.6.0

package/README.md

@@ -19,7 +19,7 @@ Node 18+ (global `fetch`, WebCrypto). ESM.
 ## Verifier: you receive an action from someone else's agent
 
 ```ts
-import { createKyaClient, verifyAttestation, verifyCredentialOffline, companyText, signWithECnpj } from "@kya-brasil/agent-tools";
+import { createKyaClient, verifyAttestation, verifyCredentialOffline, companyText, signWithECnpj, hashPaymentRef } from "@kya-brasil/agent-tools";
 
 const kya = createKyaClient({ privateKey: process.env.KYA_PAYER_PK as `0x${string}` }); // wallet optional
 
@@ -34,6 +34,8 @@ if (!verdict.allowed) reject(verdict.reason);
 await verifyAttestation(verdict);                          // local Ed25519 check of the issuer's signature
 
 // max_per_day: pass your own spent_today; the issuer does not record acts.
+// Payment instrument (card networks, acquirers, D-25): pass the hash of the token reference or PAR you received,
+// never the card number: { payment_network: "visa", payment_ref_sha256: await hashPaymentRef(tokenRef) }
 
 const offline = await verifyCredentialOffline(credential);   // issuer down: signature + expires_at only,
                                                              // live_status "unknown" (your risk until expires_at)

package/dist/auth.d.ts

@@ -80,8 +80,8 @@ export interface LocalVerdict {
 }
 /**
  * Local evaluation of the reserved mandate fields: actions, max_per_operation, currencies, counterparties
- * (with `*.` wildcards), valid_from / valid_until. `max_per_day` is listed as not evaluated: only the issuer
- * knows nothing of it either: pass your own spent_today to ctx.allowed.
+ * (with `*.` wildcards), payment_instruments (when you pass payment_ref_sha256), valid_from / valid_until, and
+ * max_per_day when you pass spent_today (nobody else counts it: the issuer keeps no record of acts).
  */
 export declare function checkMandate(mandate: Mandate, q: ActionQuery, now?: Date): LocalVerdict;
 export interface KyaAuth {

package/dist/auth.js

@@ -73,7 +73,7 @@ export async function signRequest(p) {
         headers[KYA_HEADERS.content] = contentSha256;
     return headers;
 }
-const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "valid_from", "valid_until"];
+const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until"];
 function normalizeCounterparty(c) {
     const t = c.trim();
     const digits = t.replace(/\D/g, "");
@@ -88,8 +88,8 @@ function normalizeCounterparty(c) {
 }
 /**
  * Local evaluation of the reserved mandate fields: actions, max_per_operation, currencies, counterparties
- * (with `*.` wildcards), valid_from / valid_until. `max_per_day` is listed as not evaluated: only the issuer
- * knows nothing of it either: pass your own spent_today to ctx.allowed.
+ * (with `*.` wildcards), payment_instruments (when you pass payment_ref_sha256), valid_from / valid_until, and
+ * max_per_day when you pass spent_today (nobody else counts it: the issuer keeps no record of acts).
  */
 export function checkMandate(mandate, q, now = new Date()) {
     const checks = [];
@@ -116,9 +116,21 @@ export function checkMandate(mandate, q, now = new Date()) {
         });
         push("counterparties", ok, `${c} ${ok ? "is" : "is not"} an allowed counterparty`);
     }
+    if (mandate.max_per_day && q.amount !== undefined && q.spent_today !== undefined) {
+        const total = q.amount + q.spent_today;
+        const same = !q.currency || q.currency.toUpperCase() === mandate.max_per_day.currency;
+        push("max_per_day", same && total <= mandate.max_per_day.amount, same ? `${total} today (incl. this one) vs ceiling ${mandate.max_per_day.amount} ${mandate.max_per_day.currency}` : `ceiling is in ${mandate.max_per_day.currency}, operation in ${q.currency}`);
+    }
+    const instruments = Array.isArray(mandate.payment_instruments) ? mandate.payment_instruments : [];
+    if (instruments.length && q.payment_ref_sha256) {
+        const h = q.payment_ref_sha256.trim().toLowerCase();
+        const net = q.payment_network?.trim().toLowerCase();
+        const hit = instruments.find((p) => p.ref_sha256 === h && (!net || p.network === net));
+        push("payment_instruments", !!hit, hit ? `${hit.network} instrument ${h.slice(0, 12)}… is authorized` : `instrument ${net ? `${net} ` : ""}${h.slice(0, 12)}… is not in the mandate`);
+    }
     const not_evaluated = Object.keys(mandate).filter((k) => !RESERVED.includes(k));
-    if (mandate.max_per_day)
-        not_evaluated.push("max_per_day (only the issuer knows today's registered total)");
+    if (mandate.max_per_day && q.spent_today === undefined)
+        not_evaluated.push("max_per_day (pass spent_today: the issuer keeps no record of acts)");
     return { allowed: checks.every((c) => c.ok), checks, not_evaluated };
 }
 const headerOf = (headers, name) => {

package/dist/index.d.ts

@@ -27,6 +27,12 @@ export interface Mandate {
     };
     currencies?: string[];
     counterparties?: string[];
+    /** D-25: instruments the agent may use, as SHA-256 of the network's token reference or PAR (see hashPaymentRef). */
+    payment_instruments?: {
+        network: string;
+        ref_sha256: string;
+        label?: string;
+    }[];
     valid_from?: string;
     valid_until?: string;
     [k: string]: unknown;
@@ -93,7 +99,16 @@ export interface ActionQuery {
     currency?: string;
     counterparty?: string;
     spent_today?: number;
+    /** D-25: network of the payment instrument used (visa, mastercard, elo, pix, ...). */
+    payment_network?: string;
+    /** D-25: SHA-256 hex of its token reference or PAR (hashPaymentRef); never a card number. */
+    payment_ref_sha256?: string;
 }
+/**
+ * SHA-256 (lowercase hex) of a payment reference as mandates store it (D-25): UTF-8, whitespace removed, case
+ * kept. Use it on a network token reference or PAR, never on a card number.
+ */
+export declare function hashPaymentRef(ref: string): Promise<string>;
 export interface Verdict {
     credential_id: string;
     status: CredentialStatus;
@@ -185,7 +200,8 @@ export interface KyaClient {
     }): Promise<Registration>;
     /** Free: send both signatures; the credential is issued if the e-CNPJ is valid and not revoked, the CNPJ matches and the company is ATIVA. */
     prove(credentialId: string, proof: Proof): Promise<{
-        credential: Credential; /** /v1 compatibility, always empty. */
+        credential: Credential; /** D-24: e.g. registration status not confirmed (issued anyway). */
+        warnings?: string[]; /** /v1 compatibility, same as warnings. */
         kyb_warnings: string[];
     }>;
     /** $0.10: renewal challenge (then renewProve). */
@@ -198,7 +214,8 @@ export interface KyaClient {
         };
     }>;
     renewProve(credentialId: string, proof: Proof): Promise<{
-        credential: Credential; /** /v1 compatibility, always empty. */
+        credential: Credential; /** D-24: e.g. registration status not confirmed (issued anyway). */
+        warnings?: string[]; /** /v1 compatibility, same as warnings. */
         kyb_warnings: string[];
     }>;
     /** Free: the company revokes at once. signed_text must be "KYA Brasil: revoke <id>\n<nonce>", signed with the e-CNPJ. */

package/dist/index.js

@@ -23,6 +23,17 @@ import { privateKeyToAccount } from "viem/accounts";
 import * as pkijs from "pkijs";
 import { toBase64Url } from "./base64url.js";
 export const DEFAULT_BASE_URL = "https://kya-br-agents.marcelfons.workers.dev";
+/**
+ * SHA-256 (lowercase hex) of a payment reference as mandates store it (D-25): UTF-8, whitespace removed, case
+ * kept. Use it on a network token reference or PAR, never on a card number.
+ */
+export async function hashPaymentRef(ref) {
+    const clean = ref.replace(/\s+/g, "");
+    if (!clean)
+        throw new Error("empty payment reference");
+    const d = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(clean)));
+    return Array.from(d, (b) => b.toString(16).padStart(2, "0")).join("");
+}
 export class KyaError extends Error {
     code;
     status;
@@ -102,8 +113,8 @@ export function createKyaClient(opts = {}) {
         {
             name: "kya_check_action", priceUsd: 0.01,
             description: "Signed verdict ($0.01): may this agent perform this action (action, amount, currency, counterparty) under its company mandate, and is the credential active right now? Use before accepting an order, a payment or a signature from an agent.",
-            parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "Your CNPJ, domain or wallet address" }, spent_today: { type: "number" } }, required: ["credential_id"], additionalProperties: false },
-            execute: async (a) => client.allowed(String(a.credential_id), { action: a.action, amount: a.amount, currency: a.currency, counterparty: a.counterparty, spent_today: a.spent_today })
+            parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "Your CNPJ, domain or wallet address" }, spent_today: { type: "number" }, payment_network: { type: "string", description: "visa, mastercard, elo, pix, ..." }, payment_ref_sha256: { type: "string", description: "SHA-256 hex of the payment token reference or PAR used (never a card number)" } }, required: ["credential_id"], additionalProperties: false },
+            execute: async (a) => client.allowed(String(a.credential_id), { action: a.action, amount: a.amount, currency: a.currency, counterparty: a.counterparty, spent_today: a.spent_today, payment_network: a.payment_network, payment_ref_sha256: a.payment_ref_sha256 })
         },
         {
             name: "kya_verify_paid", priceUsd: 0.01,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed credential, revocation and company registration checked daily against the Receita's open data, no third-party service), check an action against its mandate, or give your own agent a credential. Sign in with KYA middleware (Hono, Express, Workers) and request signing. x402 payments (USDC on Base) handled for you. Adapters for Vercel AI SDK, LangChain, OpenAI and Anthropic.",
   "license": "MIT",
   "type": "module",
@@ -58,7 +58,7 @@
     "viem": "^2.57.5"
   },
   "devDependencies": {
-    "@kya-br/core": "workspace:*",
+    "@kya-brasil/core": "workspace:*",
     "@peculiar/asn1-schema": "^2.3.15",
     "@peculiar/asn1-x509": "^2.3.15",
     "@peculiar/x509": "^2.1.0",