@lemmaoracle/spec 0.0.31 → 0.0.33

package/openapi.lemma.v2.json

@@ -1,11 +1,14 @@
 {
-  "openapi": "3.0.3",
+  "openapi": "3.1.0",
   "info": {
     "title": "Lemma v2 API",
-    "version": "0.1.0",
-    "description": "REST surface derived from the Lemma v2 whitepaper SDK interface (§3, §4)."
+    "version": "0.2.0",
+    "description": "REST surface derived from the Lemma v2 whitepaper SDK interface (§3, §4). v0.2 adds the 4 Bazaar Discovery Layer products under /v1/suites/* (see x-bazaar extension)."
   },
-  "servers": [{ "url": "http://localhost:8787" }],
+  "servers": [
+    { "url": "https://api.lemma.frame00.com", "description": "Production (Base mainnet)" },
+    { "url": "http://localhost:8787", "description": "Local development" }
+  ],
   "components": {
     "securitySchemes": {
       "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
@@ -527,6 +530,242 @@
           }
         }
       }
+    },
+
+    "/v1/suites/identity/issue": {
+      "post": {
+        "operationId": "issueAgentIdentity",
+        "summary": "Agent Identity Issuance — issue a W3C VC v2 credential with Poseidon Merkle inclusion proof",
+        "description": "For AI agents that need to issue verifiable identity credentials to other agents or services, this endpoint mints a W3C VC v2 credential with Poseidon Merkle inclusion proof and Groth16 zero-knowledge verification.",
+        "tags": ["bazaar", "infrastructure", "agent-identity"],
+        "x-bazaar": {
+          "discoverable": true,
+          "schema": "agent-identity-authority-v1",
+          "category": "Infrastructure",
+          "subTags": ["agent-identity", "zk-proof", "did", "kya", "verifiable-credentials"],
+          "price": { "amount": "0.05", "currency": "USDC", "network": "base" }
+        },
+        "x-lemma-circuit": {
+          "id": "agent-identity-v1",
+          "location": "packages/agent/circuits/agent-identity-valid.circom",
+          "proofSystem": "Groth16"
+        },
+        "x-lemma-facilitator-requirement": "CDP",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "./schemas/suites/product-a-input.json" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Credential issued, anchored, and ready for downstream verification",
+            "headers": {
+              "X-Lemma-Bazaar-Schema": { "schema": { "type": "string", "const": "agent-identity-authority-v1" } },
+              "X-Lemma-Bazaar-Category": { "schema": { "type": "string", "const": "Infrastructure" } },
+              "EXTENSION-RESPONSES": {
+                "schema": { "type": "string" },
+                "description": "CDP facilitator processing status (status=accepted|processing|rejected). Returned only when settled via the CDP facilitator with discoverable: true."
+              }
+            },
+            "content": {
+              "application/json": { "schema": { "$ref": "./schemas/suites/product-a-output.json" } }
+            }
+          },
+          "400": { "description": "Validation error",          "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "401": { "description": "Authentication failure",    "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "402": {
+            "description": "Payment required (x402 challenge)",
+            "headers": {
+              "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "x402 payment challenge envelope." }
+            },
+            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "x402 challenge body. See @x402/core spec for shape." } } }
+          },
+          "404": { "description": "Subject prerequisite missing", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "500": { "description": "Internal error",             "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } }
+        }
+      }
+    },
+
+    "/v1/suites/inference/attest": {
+      "post": {
+        "operationId": "attestInference",
+        "summary": "Inference Attestation API — Groth16 attestation that a given model produced a given output",
+        "description": "For AI agents and companies running their own inference (Bedrock, OpenAI, Anthropic, Ollama), this endpoint generates a Groth16 zero-knowledge attestation that proves which model produced which output, anchored on Base mainnet. Lemma never sees raw data.",
+        "tags": ["bazaar", "inference"],
+        "x-bazaar": {
+          "discoverable": true,
+          "schema": "inference-attestation-v1",
+          "category": "Inference",
+          "subTags": ["verifiable-ai", "audit-trail", "zk-proof", "provenance", "inference-attestation", "claim-check", "model-tampering-detection"],
+          "price": { "amount": "0.07", "currency": "USDC", "network": "base" }
+        },
+        "x-lemma-circuit": {
+          "id": "attestation-commitment-v1",
+          "location": "packages/attestation/circuits/",
+          "proofSystem": "Groth16"
+        },
+        "x-lemma-facilitator-requirement": "CDP",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "./schemas/suites/product-b-input.json" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Attestation generated, anchored, and ready for downstream verification",
+            "headers": {
+              "X-Lemma-Bazaar-Schema": { "schema": { "type": "string", "const": "inference-attestation-v1" } },
+              "X-Lemma-Bazaar-Category": { "schema": { "type": "string", "const": "Inference" } },
+              "X-Lemma-Attestation": { "schema": { "type": "string" }, "description": "Compact attestation reference (id;verify=URL;circuit=name)." },
+              "X-Lemma-Attestation-Status": { "schema": { "type": "string", "enum": ["anchored", "deferred"] } },
+              "EXTENSION-RESPONSES": { "schema": { "type": "string" }, "description": "CDP facilitator processing status." }
+            },
+            "content": {
+              "application/json": { "schema": { "$ref": "./schemas/suites/product-b-output.json" } }
+            }
+          },
+          "400": { "description": "Validation error / timestamp skew", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "401": { "description": "Authentication failure",            "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "402": {
+            "description": "Payment required (x402 challenge)",
+            "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" } } },
+            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
+          },
+          "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } }
+        }
+      }
+    },
+
+    "/v1/suites/compliance/bundle": {
+      "post": {
+        "operationId": "issueComplianceBundle",
+        "summary": "Compliance Attestation Bundle (Basic) — BBS+ selective-disclosure proof for 2-3 standard attributes",
+        "description": "For AI agents that need to present compliance claims (KYC status, jurisdiction, sanctions clearance) to gated endpoints without revealing underlying data, this Basic bundle returns a BBS+ selective-disclosure proof for 2-3 standard attributes per call.",
+        "tags": ["bazaar", "infrastructure", "compliance"],
+        "x-bazaar": {
+          "discoverable": true,
+          "schema": "compliance-bundle-v1",
+          "category": "Infrastructure",
+          "subTags": ["compliance", "mica", "kyc", "bbs", "selective-disclosure", "regulatory"],
+          "price": { "amount": "0.08", "currency": "USDC", "network": "base" }
+        },
+        "x-lemma-circuit": {
+          "id": "bbs-bls12-381",
+          "proofSystem": "BBS+",
+          "library": "@lemmaoracle/sdk (noble-curves backend)"
+        },
+        "x-lemma-facilitator-requirement": "CDP",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "./schemas/suites/product-c-input.json" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Bundle generated with the requested disclosure mode",
+            "headers": {
+              "X-Lemma-Bazaar-Schema": { "schema": { "type": "string", "const": "compliance-bundle-v1" } },
+              "X-Lemma-Bazaar-Category": { "schema": { "type": "string", "const": "Infrastructure" } },
+              "EXTENSION-RESPONSES": { "schema": { "type": "string" }, "description": "CDP facilitator processing status." }
+            },
+            "content": {
+              "application/json": { "schema": { "$ref": "./schemas/suites/product-c-output.json" } }
+            }
+          },
+          "400": { "description": "Validation / unsupported attribute (Basic plan)", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "401": { "description": "Authentication failure",                          "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "402": {
+            "description": "Payment required (x402 challenge)",
+            "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" } } },
+            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
+          },
+          "404": { "description": "Subject onboarding missing", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "500": { "description": "Internal error",             "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } }
+        }
+      }
+    },
+
+    "/v1/suites/auth/challenge": {
+      "get": {
+        "operationId": "issueAuthChallenge",
+        "summary": "ZK Proof Sign-in challenge — issue a single-use nonce (free, no x402)",
+        "description": "Companion to /v1/suites/auth/proof. Returns a fresh 60-second single-use nonce that the client uses when generating the Groth16 sign-in proof. Free — payment is only required for the proof submission itself.",
+        "tags": ["bazaar", "infrastructure", "auth"],
+        "responses": {
+          "200": {
+            "description": "Nonce issued",
+            "headers": {
+              "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["nonce", "expires_at"],
+                  "properties": {
+                    "nonce": { "type": "string", "pattern": "^[0-9a-f]{32}$" },
+                    "expires_at": { "type": "string", "format": "date-time" }
+                  }
+                }
+              }
+            }
+          },
+          "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } }
+        }
+      }
+    },
+
+    "/v1/suites/auth/proof": {
+      "post": {
+        "operationId": "verifyAuthProof",
+        "summary": "ZK Proof-as-Auth (Sign-in) — verify Groth16 proof of API key possession, mint short-lived JWT",
+        "description": "For AI agents that need to call authenticated APIs without ever holding the API key — beyond the reach of prompt injection or context leaks — this endpoint accepts a Groth16 zero-knowledge proof of API key possession and returns a short-lived JWT.",
+        "tags": ["bazaar", "infrastructure", "auth"],
+        "x-bazaar": {
+          "discoverable": true,
+          "schema": "seal-identity-v1",
+          "category": "Infrastructure",
+          "subTags": ["auth", "zk-proof", "sign-in", "proof-as-auth", "credential-free", "passwordless", "api-key", "prompt-injection-defense"],
+          "price": { "amount": "0.02", "currency": "USDC", "network": "base" }
+        },
+        "x-lemma-circuit": {
+          "id": "seal-identity-v1",
+          "location": "packages/seal/circuits/",
+          "proofSystem": "Groth16"
+        },
+        "x-lemma-facilitator-requirement": "CDP",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": { "schema": { "$ref": "./schemas/suites/product-d-input.json" } }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Proof verified, JWT minted",
+            "headers": {
+              "X-Lemma-Bazaar-Schema": { "schema": { "type": "string", "const": "seal-identity-v1" } },
+              "X-Lemma-Bazaar-Category": { "schema": { "type": "string", "const": "Infrastructure" } },
+              "EXTENSION-RESPONSES": { "schema": { "type": "string" }, "description": "CDP facilitator processing status." }
+            },
+            "content": {
+              "application/json": { "schema": { "$ref": "./schemas/suites/product-d-output.json" } }
+            }
+          },
+          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "401": { "description": "Nonce expired / proof verification failed", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } },
+          "402": {
+            "description": "Payment required (x402 challenge)",
+            "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" } } },
+            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
+          },
+          "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "./schemas/bazaar/canonical-error.json" } } } }
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemmaoracle/spec",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -16,21 +16,30 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./schemas/*": "./schemas/*"
   },
   "files": [
     "dist",
-    "openapi.lemma.v2.json"
+    "schemas",
+    "openapi.lemma.v2.json",
+    "openapi.lemma.v2.bundled.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint 'src/**/*.ts'",
-    "test": "vitest run"
+    "test": "vitest run",
+    "validate:schemas": "node scripts/validate-schemas.mjs",
+    "validate:openapi": "node scripts/validate-openapi.mjs",
+    "bundle:openapi": "node scripts/bundle-openapi.mjs"
   },
   "devDependencies": {
+    "@redocly/cli": "^1.20.0",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "eslint": "^9.39.3",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-functional": "^9.0.4",

package/schemas/_headers

@@ -0,0 +1,12 @@
+/*
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, OPTIONS
+  Content-Type: application/json
+/suites/*
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, OPTIONS
+  Content-Type: application/json
+/bazaar/*
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, OPTIONS
+  Content-Type: application/json

package/schemas/bazaar/canonical-error.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/bazaar/canonical-error.json",
+  "title": "Lemma canonical error envelope",
+  "description": "Shared error envelope returned by all Bazaar product endpoints (A/B/C/D) and all internal Lemma APIs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["error", "requestId"],
+  "properties": {
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]+$",
+          "description": "Machine-readable upper-snake-case error code, e.g. VALIDATION_ERROR, NONCE_EXPIRED_OR_REUSED."
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable, action-oriented message. Should suggest the next step the caller can take."
+        },
+        "field": {
+          "type": "string",
+          "description": "Optional JSON Pointer (e.g. '/disclosure_policy/range_predicates/0/predicate') or field name pointing at the offending input."
+        },
+        "docs": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional deep link to the Lemma docs section for this error."
+        }
+      }
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^req_[0-9a-z]+$",
+      "description": "Server-assigned request identifier for log correlation."
+    }
+  }
+}

package/schemas/suites/bazaar-extension-metadata.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/bazaar-extension-metadata.json",
+  "title": "Lemma x-bazaar extension metadata",
+  "description": "Schema for the `x-bazaar` extension attached to OpenAPI operations exposed via x402 Bazaar. Used by the openapi sync CI step to validate that paths.[].post.x-bazaar entries are well-formed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["discoverable", "schema", "category"],
+  "properties": {
+    "discoverable": {
+      "type": "boolean",
+      "description": "Whether the route is registered in the CDP Bazaar Discovery Layer on first settle."
+    },
+    "schema": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+v[0-9]+$",
+      "description": "Schema identifier (kebab-case + version suffix), e.g. 'agent-identity-authority-v1'."
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "Inference",
+        "Data",
+        "Media",
+        "Search",
+        "Social",
+        "Infrastructure",
+        "Trading"
+      ],
+      "description": "One of the 7 official Bazaar categories."
+    },
+    "subTags": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+      "maxItems": 16,
+      "description": "Free-form sub-tags surfaced as semantic-search hints."
+    },
+    "price": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["amount", "currency", "network"],
+      "properties": {
+        "amount": {
+          "type": "string",
+          "pattern": "^[0-9]+(\\.[0-9]+)?$",
+          "description": "Decimal string to preserve precision."
+        },
+        "currency": {
+          "type": "string",
+          "enum": ["USDC"],
+          "description": "MVP supports USDC only."
+        },
+        "network": {
+          "type": "string",
+          "enum": ["base", "base-sepolia"],
+          "description": "Settlement network."
+        }
+      }
+    }
+  }
+}

package/schemas/suites/product-a-input.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-a-input.json",
+  "title": "Agent Identity Issuance Request",
+  "description": "⚠️ OUTDATED: This spec's proof model (Merkle tree) diverges from the current agent-identity.circom circuit (flat Poseidon6 commitment + issuer MAC). The circuit is the source of truth.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["agentId", "controllerId", "roles", "spendLimit", "expiresAt"],
+  "properties": {
+    "agentId": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^did:[a-z0-9]+:.+$",
+      "description": "DID of the agent being credentialed (subject). Example: did:key:z6Mk...",
+      "examples": ["did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSrUaYS9XVjqJzgRfBjK"]
+    },
+    "subjectId": {
+      "type": "string",
+      "format": "uri",
+      "description": "DID of the underlying real-world subject (organization, user) the agent acts on behalf of. Optional but recommended for KYA traceability."
+    },
+    "controllerId": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^did:[a-z0-9]+:.+$",
+      "description": "DID of the controller who can revoke this credential. Typically the issuer's operations key."
+    },
+    "orgId": {
+      "type": "string",
+      "description": "Organization identifier (free-form, e.g. company registration number, LEI). Used in cross-credential reconciliation."
+    },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "items": {
+        "type": "string",
+        "enum": [
+          "trader",
+          "buyer",
+          "publisher",
+          "auditor",
+          "reader",
+          "writer",
+          "custodian",
+          "validator",
+          "compliance-officer",
+          "developer",
+          "operator",
+          "support"
+        ]
+      },
+      "description": "Roles assigned to this agent. Each role implies a baseline scope set; explicit scopes below override."
+    },
+    "scopes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9_:.-]+$"
+      },
+      "description": "Fine-grained capability scopes (e.g. 'payments:send', 'data:read:financial'). Optional override over roles."
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Boolean permission map for binary capabilities. MVP supports a fixed set; custom permissions are V2.",
+      "properties": {
+        "can_settle_x402": { "type": "boolean", "description": "Authorize the agent to settle x402 micropayments." },
+        "can_request_attestation": { "type": "boolean", "description": "Authorize the agent to request a Lemma attestation bundle (product C)." },
+        "can_issue_subordinate": { "type": "boolean", "description": "Authorize the agent to issue subordinate agent credentials." },
+        "can_sign_in": { "type": "boolean", "description": "Authorize the agent to perform ZK Proof Sign-in (product D)." },
+        "can_invoke_inference": { "type": "boolean", "description": "Authorize the agent to invoke proof-anchored inference (product B)." }
+      }
+    },
+    "spendLimit": {
+      "type": "object",
+      "required": ["amount", "currency", "window"],
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "type": "string",
+          "pattern": "^[0-9]+(\\.[0-9]+)?$",
+          "description": "Maximum spend within window. String to preserve precision (USDC has 6 decimals)."
+        },
+        "currency": {
+          "type": "string",
+          "enum": ["USDC"],
+          "description": "Settlement currency. MVP supports USDC only on Base mainnet. USDT/EURC are planned for V2 — passing them returns INVALID_CURRENCY in MVP."
+        },
+        "window": {
+          "type": "string",
+          "enum": ["per-call", "daily", "weekly", "monthly"],
+          "description": "Spend limit window."
+        }
+      },
+      "description": "Financial guard rail enforced at attestation-verification time by consuming services."
+    },
+    "paymentPolicy": {
+      "type": "string",
+      "enum": ["prepaid"],
+      "default": "prepaid",
+      "description": "How the agent's payments are funded. MVP supports prepaid only. 'postpaid' and 'subscription' are V2 — passing them returns POLICY_NOT_SUPPORTED in MVP."
+    },
+    "issuedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Issuance timestamp. If omitted, Lemma uses server time."
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Expiration timestamp. Maximum 1 year from issuance per MVP policy."
+    },
+    "sourceSystem": {
+      "type": "string",
+      "description": "Free-form identifier of the system that originated the issuance (e.g. 'aws-bedrock-agentcore', 'custom-pipeline-v2'). Stored for provenance only."
+    },
+    "chainContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "chainId": { "type": "integer", "enum": [8453], "description": "Base mainnet only in MVP." },
+        "rpcUrl": { "type": "string", "format": "uri", "description": "Optional RPC endpoint reference for verifier reconciliation." }
+      }
+    }
+  }
+}