@ar-agents/mercadopago 0.17.2 → 0.18.0

package/cookbook/29-publish-your-keys.ts

@@ -0,0 +1,193 @@
+/**
+ * Recipe 29 — Publish your sociedad-IA's Ed25519 public key (RFC-005 § 4).
+ *
+ * # Pattern
+ *
+ * Real operators rotate keys, custody privates in secrets managers, and
+ * publish public keys at /.well-known/sociedad-ia/keys. Recipe 29 is the
+ * one-time bootstrap + the recurring rotation flow:
+ *
+ *   1. Generate an Ed25519 keypair locally (Web Crypto OR Node crypto).
+ *   2. Convert public key → SPKI base64url (RFC-005 § 4 wire format).
+ *   3. Print the public key JSON the operator can copy into
+ *      apps/.../public/.well-known/sociedad-ia/keys.json.
+ *   4. Print the private key as base64url PKCS8 — to paste into the
+ *      operator's secrets manager (Vercel env `AUDIT_ED25519_PRIVATE_KEY`,
+ *      1Password, AWS Secrets Manager, etc.). NEVER commit to a repo.
+ *
+ * The same keyId can stay valid indefinitely. Rotation is additive:
+ * generate a new keypair, append to the published keys list with a
+ * later validFrom + null validUntil. Set validUntil on the previous
+ * key. Old entries signed with the rotated-out key remain verifiable
+ * because the public key stays in the published list.
+ *
+ * # When to use
+ *
+ *   - First-time setup: right after deploying your sociedad-IA. Generate
+ *     once, paste public key into your repo, paste private key into
+ *     your secrets manager.
+ *   - Scheduled rotation: at 6- or 12-month cadence.
+ *   - Incident response: if you suspect the private key was compromised.
+ *
+ * # No Web app needed
+ *
+ * Recipe 29 is a pure CLI script. Outputs the JSON snippets the
+ * operator pastes into their own infrastructure.
+ *
+ * # Edge / Node compatibility
+ *
+ * Web Crypto Ed25519 stable in Node 22+ and Vercel Edge. The script
+ * uses Web Crypto throughout so it runs anywhere.
+ */
+
+declare const process: { argv: string[]; exit: (n: number) => void; stdout: { write: (s: string) => void } } | undefined;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function b64urlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function hexEncode(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export interface GeneratedKeypair {
+  keyId: string;
+  alg: "ed25519";
+  /** base64url SPKI (DER-encoded SubjectPublicKeyInfo). */
+  publicKey: string;
+  /** Raw 32-byte Ed25519 point as hex. */
+  publicKeyRaw: string;
+  /** base64url PKCS8 (DER-encoded PrivateKeyInfo). DO NOT publish. */
+  privateKey: string;
+  validFrom: string;
+  validUntil: null;
+}
+
+/**
+ * Generate a fresh Ed25519 keypair + return both the public and private
+ * parts in the wire formats RFC-005 § 4 expects.
+ */
+export async function generateKeypair(keyId: string): Promise<GeneratedKeypair> {
+  const kp = await crypto.subtle.generateKey(
+    { name: "Ed25519" } as unknown as AlgorithmIdentifier,
+    true,
+    ["sign", "verify"],
+  );
+  const pubSpki = await crypto.subtle.exportKey("spki", (kp as CryptoKeyPair).publicKey);
+  const privPkcs8 = await crypto.subtle.exportKey("pkcs8", (kp as CryptoKeyPair).privateKey);
+  const pubSpkiBytes = new Uint8Array(pubSpki);
+  // SPKI for Ed25519 = 0x30 0x2a 0x30 0x05 0x06 0x03 0x2b 0x65 0x70 0x03 0x21 0x00 || 32-byte point
+  const pubRaw = pubSpkiBytes.slice(-32);
+  return {
+    keyId,
+    alg: "ed25519",
+    publicKey: b64urlEncode(pubSpkiBytes),
+    publicKeyRaw: hexEncode(pubRaw),
+    privateKey: b64urlEncode(new Uint8Array(privPkcs8)),
+    validFrom: new Date().toISOString(),
+    validUntil: null,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output formatting
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface PublishedKeysFile {
+  $schema: string;
+  spec: string;
+  issuer: {
+    jurisdiction: string;
+    entityId: string;
+    denominacion: string;
+  };
+  keys: Array<{
+    keyId: string;
+    alg: "ed25519";
+    publicKey: string;
+    publicKeyRaw: string;
+    validFrom: string;
+    validUntil: string | null;
+  }>;
+  note: string;
+}
+
+export function publishedKeysFromKeypair(
+  kp: GeneratedKeypair,
+  issuer: { jurisdiction: string; entityId: string; denominacion: string },
+): PublishedKeysFile {
+  return {
+    $schema: "https://ar-agents.ar/schemas/keys.v1.json",
+    spec: "https://ar-agents.ar/rfcs/005",
+    issuer,
+    keys: [
+      {
+        keyId: kp.keyId,
+        alg: kp.alg,
+        publicKey: kp.publicKey,
+        publicKeyRaw: kp.publicKeyRaw,
+        validFrom: kp.validFrom,
+        validUntil: kp.validUntil,
+      },
+    ],
+    note: "Ed25519 public key for this sociedad-IA's RFC-004/005 audit-log signatures. Private key custody lives in the operator's secrets manager.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI: tsx 29-publish-your-keys.ts <keyId> [<cuit>] [<denominacion>]
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (typeof process === "undefined") return;
+  const [, , keyIdArg, cuit, denominacionArg] = process.argv;
+  const keyId = keyIdArg ?? `${defaultKeyIdPrefix()}-${new Date().getUTCFullYear()}-${String(new Date().getUTCMonth() + 1).padStart(2, "0")}`;
+  const jurisdiction = "AR";
+  const entityId = cuit ? `ar-sociedad:${cuit}` : "ar-sociedad:replace-with-your-cuit";
+  const denominacion = denominacionArg ?? "(replace with your sociedad's denominación)";
+
+  const kp = await generateKeypair(keyId);
+  const published = publishedKeysFromKeypair(kp, { jurisdiction, entityId, denominacion });
+
+  const writeLn = (s: string) => process!.stdout.write(`${s}\n`);
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+  writeLn("# 1. Public key — drop this into:");
+  writeLn(`#    apps/<your-sociedad-app>/public/.well-known/sociedad-ia/keys.json`);
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+  writeLn(JSON.stringify(published, null, 2));
+  writeLn("");
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+  writeLn("# 2. Private key — paste into your operator's secrets manager:");
+  writeLn("#    Vercel env var: AUDIT_ED25519_PRIVATE_KEY (recommended)");
+  writeLn("#    DO NOT commit this to a repo. DO NOT publish.");
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+  writeLn(kp.privateKey);
+  writeLn("");
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+  writeLn("# 3. Verify with curl:");
+  writeLn("#    curl https://your-sociedad.example/.well-known/sociedad-ia/keys.json | jq .keys[0].publicKey");
+  writeLn("#    Should match the publicKey field in section 1 above.");
+  writeLn("# ════════════════════════════════════════════════════════════════════════");
+}
+
+function defaultKeyIdPrefix(): string {
+  return "sociedad-ia-key";
+}
+
+const isMain = typeof require !== "undefined" && require.main === module;
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    if (typeof process !== "undefined" && "exit" in process) {
+      (process as unknown as { exit: (code: number) => void }).exit(1);
+    }
+  });
+}

package/cookbook/30-submit-to-registry.ts

@@ -0,0 +1,257 @@
+/**
+ * Recipe 30 — Submit your sociedad-IA to the public /registro.
+ *
+ * # Pattern
+ *
+ * Once your sociedad-IA is deployed + scoring >= 60 on the public
+ * certifier (rating C or better), you can list it in the public
+ * registry at /registro. Recipe 30 is the pre-flight check + the
+ * PR-body generator.
+ *
+ * The flow:
+ *
+ *   1. Run recipe 28 (operator readiness) against your URL.
+ *   2. Run recipe 26 (RFC certifier) against your URL.
+ *   3. If both pass, recipe 30 produces a single Markdown block you
+ *      paste into a GitHub PR titled
+ *      "[/registro] Add <your-sociedad-name>".
+ *
+ *   4. The PR review checks (manually):
+ *      - The URL resolves
+ *      - /.well-known/agents.json is valid
+ *      - The disclosure is honest (e.g. claims "demo" not "productive"
+ *        if the sociedad doesn't actually transact)
+ *      - operatorCuit matches the entityId in the manifest
+ *
+ *   5. Merge → live in /registro within ~1 hour (next build).
+ *
+ * # When to use
+ *
+ *   - First-time: after your sociedad-IA is deployed + you want
+ *     public visibility.
+ *   - Update: same flow, just amend the existing entry by name.
+ *
+ * # No silent failures
+ *
+ * Recipe 30 refuses to produce a PR body if the readiness or certifier
+ * checks fail. Returns a remediation report instead. This prevents
+ * over-eager submission of half-built sociedades.
+ */
+
+import { certifySociedad } from "./26-certify-by-fetch";
+import { checkOperatorReadiness } from "./28-operator-onboarding-checklist";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SubmissionInput {
+  /** Display name for the registry. */
+  name: string;
+  /** Type: "demo", "productive-sociedad-ia", "library-only". */
+  type: "demo" | "productive-sociedad-ia" | "library-only";
+  /** Operator's CUIT (no formatting). */
+  operatorCuit: string;
+  /** Operator's full name (legal). */
+  operatorName: string;
+  /** Public URL of the deployed sociedad. */
+  publicUrl: string;
+  /** RFC versions claimed. */
+  rfcConformance: string[];
+  /** Plain-English honest disclosure (1-3 sentences). */
+  disclosure: string;
+}
+
+export interface SubmissionResult {
+  ok: boolean;
+  url: string;
+  certScore?: number;
+  certRating?: string;
+  readiness?: "ready" | "almost" | "blocked" | "not-deployed";
+  failures: string[];
+  prBody?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Submission pipeline
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MINIMUM_CERT_SCORE = 60;
+
+export async function buildRegistrySubmission(
+  input: SubmissionInput,
+  options: { apiBaseUrl?: string; fetchImpl?: typeof fetch } = {},
+): Promise<SubmissionResult> {
+  const failures: string[] = [];
+
+  // 1. Operator readiness (recipe 28).
+  const readiness = await checkOperatorReadiness(input.publicUrl, {
+    fetchImpl: options.fetchImpl,
+  });
+  if (readiness.readiness === "blocked") {
+    failures.push(
+      `Operator readiness is "blocked" (${readiness.passedCount}/${readiness.totalCount} items passing). Fix the blocking items before submitting.`,
+    );
+  }
+
+  // 2. RFC certifier (recipe 26).
+  const cert = await certifySociedad(input.publicUrl, {
+    fetchImpl: options.fetchImpl,
+  });
+  if (cert.score < MINIMUM_CERT_SCORE) {
+    failures.push(
+      `Certifier score ${cert.score}/${cert.rating} is below the minimum ${MINIMUM_CERT_SCORE} required for /registro listing.`,
+    );
+  }
+
+  // 3. Honesty heuristics.
+  if (
+    input.type === "productive-sociedad-ia" &&
+    !input.disclosure.toLowerCase().includes("real")
+  ) {
+    failures.push(
+      `Type is "productive-sociedad-ia" but disclosure doesn't mention "real". Be specific about what real-world transactions the sociedad performs (factura emission, MP cobros, etc.).`,
+    );
+  }
+  if (
+    input.type === "demo" &&
+    !input.disclosure.toLowerCase().includes("not a productive") &&
+    !input.disclosure.toLowerCase().includes("demo")
+  ) {
+    failures.push(
+      `Type is "demo" but disclosure doesn't say "demo" or "not a productive sociedad-IA". Be explicit so a reader doesn't confuse it with a real one.`,
+    );
+  }
+  if (!input.operatorCuit.match(/^\d{2}-\d{8}-\d$/)) {
+    failures.push(
+      `operatorCuit "${input.operatorCuit}" doesn't match CUIT format XX-XXXXXXXX-X.`,
+    );
+  }
+
+  // 4. If everything passes, generate the PR body.
+  let prBody: string | undefined;
+  if (failures.length === 0) {
+    prBody = generatePrBody(input, cert.score, cert.rating, readiness.readiness);
+  }
+
+  return {
+    ok: failures.length === 0,
+    url: input.publicUrl,
+    certScore: cert.score,
+    certRating: cert.rating,
+    readiness: readiness.readiness,
+    failures,
+    prBody,
+  };
+}
+
+function generatePrBody(
+  input: SubmissionInput,
+  certScore: number,
+  certRating: string,
+  readiness: string,
+): string {
+  return `## [/registro] Add \`${input.name}\`
+
+### What this PR does
+
+Adds the following entry to the public /registro of known sociedad-IA
+implementations:
+
+\`\`\`ts
+{
+  name: "${input.name}",
+  type: "${input.type}",
+  jurisdiction: "AR",
+  operator: "${input.operatorName}",
+  operatorCuit: "${input.operatorCuit}",
+  publicUrl: "${input.publicUrl}",
+  rfcConformance: [${input.rfcConformance.map((r) => `"${r}"`).join(", ")}],
+  disclosure: "${input.disclosure.replace(/"/g, '\\"')}",
+  status: "live",
+  listedSince: "${new Date().toISOString().slice(0, 10)}",
+}
+\`\`\`
+
+### Pre-submission checks
+
+- ✅ **Operator readiness** (recipe 28): \`${readiness}\`
+- ✅ **RFC conformance** (recipe 26): score **${certScore}/100** rating **${certRating}**
+- ✅ **CUIT format**: \`${input.operatorCuit}\` matches XX-XXXXXXXX-X
+- ✅ **Disclosure honesty**: type=\`${input.type}\` aligns with disclosure text
+
+### What I'm claiming
+
+I attest that I am the legitimate operator of this sociedad-IA. The
+\`operatorCuit\` corresponds to a real CUIT under my control. The
+\`/.well-known/agents.json\` at the public URL declares this entity.
+I will keep the deployed endpoints live for at least 90 days from
+merge; if I take the sociedad-IA down, I will open a follow-up PR
+removing the entry.
+
+### Verifier instructions for the maintainer
+
+1. \`curl https://ar-agents.ar/api/certifier?url=${input.publicUrl}\`
+   — expect score >= 60.
+2. \`curl ${input.publicUrl}/.well-known/agents.json\` — expect issuer.operatorCuit to match \`${input.operatorCuit}\`.
+3. Verify disclosure honesty by eye.
+4. Merge.
+`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI: tsx 30-submit-to-registry.ts <config.json>
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare const process: { argv: string[] } | undefined;
+
+async function main() {
+  if (typeof process === "undefined") return;
+  const configPath = process.argv[2];
+  if (!configPath) {
+    console.error("usage: tsx 30-submit-to-registry.ts <config.json>");
+    console.error("");
+    console.error("config.json shape:");
+    console.error(JSON.stringify(
+      {
+        name: "My Sociedad-IA",
+        type: "demo",
+        operatorCuit: "20-12345678-9",
+        operatorName: "Jane Doe",
+        publicUrl: "https://my-sociedad.vercel.app",
+        rfcConformance: ["rfc-001-v1", "rfc-002-v1"],
+        disclosure: "Single-library demo. Not a productive sociedad-IA.",
+      },
+      null,
+      2,
+    ));
+    return;
+  }
+  const fs = await import("node:fs/promises");
+  const cfg = JSON.parse(await fs.readFile(configPath, "utf8")) as SubmissionInput;
+
+  const result = await buildRegistrySubmission(cfg);
+
+  if (result.ok) {
+    console.log("--- PR body (copy-paste into your registry PR) ---\n");
+    console.log(result.prBody);
+  } else {
+    console.error("--- Submission blocked: failures need remediation ---\n");
+    for (const f of result.failures) console.error(`  ✗ ${f}`);
+    console.error("\n  Cert score:", result.certScore, result.certRating);
+    console.error("  Operator readiness:", result.readiness);
+    if (typeof process !== "undefined" && "exit" in process) {
+      (process as unknown as { exit: (code: number) => void }).exit(1);
+    }
+  }
+}
+
+const isMain = typeof require !== "undefined" && require.main === module;
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    if (typeof process !== "undefined" && "exit" in process) {
+      (process as unknown as { exit: (code: number) => void }).exit(1);
+    }
+  });
+}

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var core = require('@ar-agents/core');
 var ai = require('ai');
 var zod = require('zod');
 
@@ -71,19 +72,25 @@ var init_crypto = __esm({
     encoder = new TextEncoder();
   }
 });
-
-// src/errors.ts
-var MercadoPagoError = class extends Error {
-  constructor(message, status, endpoint, mpResponse) {
-    super(message);
-    this.status = status;
-    this.endpoint = endpoint;
-    this.mpResponse = mpResponse;
-    this.name = "MercadoPagoError";
-  }
+var MercadoPagoError = class extends core.ArAgentsError {
   status;
   endpoint;
   mpResponse;
+  constructor(message, status, endpoint, mpResponse, init = {}) {
+    super(message, {
+      code: init.code ?? "mp_api_error",
+      retryable: init.retryable ?? (status >= 500 || status === 429 || status === 0),
+      context: {
+        status,
+        endpoint,
+        ...mpResponse !== void 0 ? { mpResponse } : {}
+      }
+    });
+    this.name = "MercadoPagoError";
+    this.status = status;
+    this.endpoint = endpoint;
+    if (mpResponse !== void 0) this.mpResponse = mpResponse;
+  }
 };
 var MercadoPagoAuthError = class extends MercadoPagoError {
   constructor(endpoint, body) {
@@ -91,7 +98,8 @@ var MercadoPagoAuthError = class extends MercadoPagoError {
       "Mercado Pago rejected the request as unauthorized. Check the access token (TEST- prefix for sandbox, APP_USR- for production).",
       401,
       endpoint,
-      body
+      body,
+      { code: "mp_auth_failed", retryable: false }
     );
     this.name = "MercadoPagoAuthError";
   }
@@ -161,7 +169,8 @@ var MercadoPagoRateLimitError = class extends MercadoPagoError {
       `Mercado Pago rate limit hit on ${endpoint}. ${retryAfterSeconds ? `Retry after ${retryAfterSeconds}s.` : "Retry with exponential backoff."}`,
       429,
       endpoint,
-      body
+      body,
+      { code: "mp_rate_limited", retryable: true }
     );
     this.retryAfterSeconds = retryAfterSeconds;
     this.name = "MercadoPagoRateLimitError";
@@ -173,7 +182,9 @@ var MercadoPagoOverloadedError = class extends MercadoPagoError {
     super(
       `Mercado Pago appears overloaded \u2014 returned a non-JSON ${status} response for ${endpoint}. Wait a few seconds and retry.`,
       status,
-      endpoint
+      endpoint,
+      void 0,
+      { code: "mp_overloaded", retryable: true }
     );
     this.name = "MercadoPagoOverloadedError";
   }
@@ -183,7 +194,9 @@ var MercadoPagoTimeoutError = class extends MercadoPagoError {
     super(
       `Mercado Pago request timed out after ${timeoutMs}ms on ${endpoint}. Increase requestTimeoutMs or check connectivity.`,
       0,
-      endpoint
+      endpoint,
+      void 0,
+      { code: "mp_timeout", retryable: true }
     );
     this.timeoutMs = timeoutMs;
     this.name = "MercadoPagoTimeoutError";