@lemmaoracle/spec 0.0.31 → 0.0.32

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

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-a-output.json",
+  "title": "Agent Identity Issuance Response",
+  "description": "⚠️ OUTDATED: This spec does not reflect the current agent-identity.circom circuit, which uses a flat Poseidon6 commitment (5 sub-hashes + salt) with issuer MAC verification instead of the Merkle-tree model described here. The circuit is the source of truth; this schema is retained for API-compatibility reference only and should not be used to derive circuit inputs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["credentialId", "credential", "proof", "verifyUrl", "issuedAt", "expiresAt", "settlement", "requestId"],
+  "properties": {
+    "credentialId": {
+      "type": "string",
+      "format": "uri",
+      "description": "Permanent identifier of the issued credential (URN form: urn:lemma:cred:<uuid>)."
+    },
+    "credential": {
+      "type": "object",
+      "required": ["@context", "type", "issuer", "validFrom", "validUntil", "credentialSubject"],
+      "description": "W3C Verifiable Credentials v2 envelope. Subject = agentId, claims = roles+scopes+permissions+spendLimit.",
+      "properties": {
+        "@context": {
+          "type": "array",
+          "items": { "type": "string", "format": "uri" },
+          "description": "JSON-LD contexts. Always includes 'https://www.w3.org/ns/credentials/v2' + Lemma schema context."
+        },
+        "type": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "VC types. Always ['VerifiableCredential', 'AgentIdentityCredential']."
+        },
+        "issuer": { "type": "string", "format": "uri", "description": "DID of Lemma's issuer (e.g. did:web:lemma.frame00.com)." },
+        "validFrom": { "type": "string", "format": "date-time" },
+        "validUntil": { "type": "string", "format": "date-time" },
+        "credentialSubject": {
+          "type": "object",
+          "required": ["id", "roles", "spendLimit"],
+          "additionalProperties": false,
+          "properties": {
+            "id": { "type": "string", "format": "uri", "description": "Subject DID (= agentId in request)." },
+            "controller": { "type": "string", "format": "uri" },
+            "orgId": { "type": "string" },
+            "roles": { "type": "array", "items": { "type": "string" } },
+            "scopes": { "type": "array", "items": { "type": "string" } },
+            "permissions": { "type": "object" },
+            "spendLimit": { "type": "object" }
+          }
+        }
+      }
+    },
+    "proof": {
+      "type": "object",
+      "required": ["type", "merkle", "circuitId"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "const": "LemmaAgentIdentityProof2026" },
+        "merkle": {
+          "type": "object",
+          "required": ["commitmentRoot", "leafIndex", "subjectIdHash"],
+          "additionalProperties": false,
+          "properties": {
+            "commitmentRoot": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{64}$",
+              "description": "Public Poseidon Merkle root after inserting this credential's leaves (5 attributes)."
+            },
+            "leafIndex": {
+              "type": "integer",
+              "description": "Index of this credential's leaves in the Merkle tree (nLevels=20)."
+            },
+            "subjectIdHash": {
+              "type": "string",
+              "pattern": "^0x[0-9a-fA-F]{64}$",
+              "description": "Poseidon hash of the subject DID."
+            }
+          }
+        },
+        "merkleProofUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "One-time holder-only URL to retrieve the full Merkle inclusion proof."
+        },
+        "circuitId": { "type": "string", "const": "agent-identity-v1" },
+        "verifierContract": {
+          "type": "string",
+          "pattern": "^0x[0-9a-fA-F]{40}$",
+          "description": "Address of the Solidity Groth16 verifier on Base mainnet."
+        }
+      }
+    },
+    "verifyUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Public verification URL: https://verify.lemma.frame00.com/credential/<uuid>."
+    },
+    "issuedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "settlement": {
+      "type": "object",
+      "required": ["txHash", "amount", "currency", "facilitator"],
+      "additionalProperties": false,
+      "properties": {
+        "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" },
+        "amount": { "type": "string", "const": "0.05" },
+        "currency": { "type": "string", "const": "USDC" },
+        "facilitator": { "type": "string", "format": "uri" }
+      }
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^req_[0-9a-z]+$",
+      "description": "Server-assigned request identifier for log correlation."
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-b-input.json",
+  "title": "Inference Attestation Request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["model_digest", "input_hash", "output_hash", "timestamp"],
+  "properties": {
+    "model_digest": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]{64}$",
+      "description": "SHA-256 hash of a canonical model identifier (e.g. provider:model_name:version)."
+    },
+    "input_hash": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]{64}$",
+      "description": "SHA-256 hash of the canonicalised inference input. Raw input is NEVER sent to Lemma."
+    },
+    "output_hash": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]{64}$",
+      "description": "SHA-256 hash of the canonicalised inference output. Raw output is NEVER sent to Lemma."
+    },
+    "timestamp": {
+      "type": "integer",
+      "description": "Unix epoch seconds. Must be within ±300s of Lemma's server time (replay protection)."
+    },
+    "nonce": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{32}$",
+      "description": "Optional 16-byte client nonce (hex) for additional replay protection."
+    },
+    "claim_metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional metadata bound into the proof commitment as a hash; never stored in the clear.",
+      "properties": {
+        "agentId": {
+          "type": "string",
+          "format": "uri",
+          "description": "Calling agent's DID. Recommended for full audit trail; combine with product A credential."
+        },
+        "purpose": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Human-readable purpose label. Hashed before commitment."
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9_:-]+$" },
+          "maxItems": 16,
+          "description": "Free-form tags for downstream filtering (hashed)."
+        },
+        "provider": {
+          "type": "string",
+          "description": "Free-form provider identifier. Hashed before commitment."
+        }
+      }
+    }
+  }
+}

package/schemas/suites/product-b-output.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-b-output.json",
+  "title": "Inference Attestation Response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["attestationId", "proof", "verifyUrl", "anchoredAt", "settlement", "requestId"],
+  "properties": {
+    "attestationId": {
+      "type": "string",
+      "format": "uri",
+      "description": "URN of the attestation record (urn:lemma:attestation:<uuid>)."
+    },
+    "proof": {
+      "type": "object",
+      "required": ["type", "status", "circuitId"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "const": "LemmaInferenceAttestation2026" },
+        "status": {
+          "type": "string",
+          "enum": ["anchored", "deferred"],
+          "description": "'anchored' = proof generated and submitted synchronously. 'deferred' = settled but queued; use pollUrl."
+        },
+        "commitment": {
+          "type": ["string", "null"],
+          "pattern": "^0x[0-9a-fA-F]{64}$",
+          "description": "Poseidon5 commitment. null when status=deferred."
+        },
+        "groth16": {
+          "type": ["object", "null"],
+          "description": "Groth16 proof tuple. null when status=deferred."
+        },
+        "circuitId": { "type": "string", "const": "attestation-commitment-v1" },
+        "verifierContract": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
+        "pollUrl": { "type": "string", "format": "uri", "description": "Polling URL when status=deferred." }
+      }
+    },
+    "verifyUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Public verification URL: https://verify.lemma.frame00.com/attestation/<uuid>."
+    },
+    "anchoredAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Time the attestation was anchored on-chain. null when status=deferred."
+    },
+    "settlement": {
+      "type": "object",
+      "required": ["txHash", "amount", "currency", "facilitator"],
+      "additionalProperties": false,
+      "properties": {
+        "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" },
+        "amount": { "type": "string", "const": "0.07" },
+        "currency": { "type": "string", "const": "USDC" },
+        "facilitator": { "type": "string", "format": "uri" }
+      }
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^req_[0-9a-z]+$",
+      "description": "Server-assigned request identifier for log correlation."
+    }
+  }
+}

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

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-c-input.json",
+  "title": "Compliance Attestation Bundle Request (Basic MVP)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subject_did", "requested_attributes", "disclosure_policy"],
+  "properties": {
+    "subject_did": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^did:[a-z0-9]+:.+$",
+      "description": "DID of the subject. Must have a prior Lemma attestation set; otherwise INSUFFICIENT_ATTRIBUTES error."
+    },
+    "requested_attributes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "items": {
+        "type": "string",
+        "enum": ["kyc_status", "jurisdiction", "sanctions_check"]
+      },
+      "description": "MVP Basic supports up to 3 attributes. The full 8-attribute Pro set ships in V2 at $0.20/bundle. Requesting unsupported attributes returns ATTRIBUTE_NOT_IN_BASIC_PLAN."
+    },
+    "disclosure_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["full", "selective", "range_only"],
+          "description": "full = reveal all values; selective = reveal only fields in reveal_fields; range_only = prove range without revealing values."
+        },
+        "reveal_fields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Required when mode='selective'. Subset of requested_attributes."
+        },
+        "range_predicates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["field", "predicate", "value"],
+            "properties": {
+              "field": { "type": "string" },
+              "predicate": {
+                "type": "string",
+                "enum": [">=", "<=", "=="],
+                "description": "BBS+ range proof supports only inclusive bounds and equality. Strict inequalities (>, <) are not supported."
+              },
+              "value": { "type": ["string", "number"] }
+            }
+          },
+          "description": "Required when mode='range_only'."
+        }
+      }
+    },
+    "verifier_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional metadata about the verifying party. Bound into the proof for replay protection.",
+      "properties": {
+        "verifier_did": { "type": "string", "format": "uri" },
+        "nonce": { "type": "string", "minLength": 16, "maxLength": 64 },
+        "purpose": { "type": "string", "maxLength": 256 }
+      }
+    },
+    "expires_in_seconds": {
+      "type": "integer",
+      "minimum": 60,
+      "maximum": 86400,
+      "default": 3600,
+      "description": "How long the issued bundle remains valid. Default 1 hour; max 24 hours in MVP."
+    }
+  }
+}

package/schemas/suites/product-c-output.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-c-output.json",
+  "title": "Compliance Attestation Bundle Response (Basic MVP)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["bundleId", "bbs_proof", "revealed_claims", "verifyUrl", "issuedAt", "expiresAt", "settlement", "requestId"],
+  "properties": {
+    "bundleId": {
+      "type": "string",
+      "format": "uri",
+      "description": "URN of the bundle (urn:lemma:bundle:<uuid>)."
+    },
+    "bbs_proof": {
+      "type": "object",
+      "required": ["type", "proof", "publicKey", "issuerDid"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "const": "BbsBlsSignatureProof2025" },
+        "proof": { "type": "string", "description": "Base64url-encoded BBS+ selective disclosure proof." },
+        "publicKey": { "type": "string", "description": "BLS12-381 G2 public key (base64url)." },
+        "issuerDid": { "type": "string", "format": "uri", "description": "DID of Lemma's attestation issuer." }
+      }
+    },
+    "revealed_claims": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Claims actually revealed per disclosure_policy (mode='full' or 'selective'). MVP Basic supports only 3 keys. Hidden claims appear as null. Empty when mode='range_only'.",
+      "properties": {
+        "kyc_status": { "type": ["string", "null"], "enum": ["verified", "pending", "rejected", null] },
+        "jurisdiction": { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country code." },
+        "sanctions_check": { "type": ["string", "null"], "enum": ["clear", "flagged", "pending", null] }
+      }
+    },
+    "range_results": {
+      "type": "array",
+      "description": "Range predicate verification results. Present only when mode='range_only'.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["field", "predicate", "value", "result"],
+        "properties": {
+          "field": { "type": "string" },
+          "predicate": { "type": "string", "enum": [">=", "<=", "=="] },
+          "value": { "type": ["string", "number"] },
+          "result": { "type": "boolean" }
+        }
+      }
+    },
+    "verifyUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Public verification URL: https://verify.lemma.frame00.com/bundle/<uuid>."
+    },
+    "issuedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "settlement": {
+      "type": "object",
+      "required": ["txHash", "amount", "currency", "facilitator"],
+      "additionalProperties": false,
+      "properties": {
+        "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" },
+        "amount": { "type": "string", "const": "0.08" },
+        "currency": { "type": "string", "const": "USDC" },
+        "facilitator": { "type": "string", "format": "uri" }
+      }
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^req_[0-9a-z]+$",
+      "description": "Server-assigned request identifier for log correlation."
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-d-input.json",
+  "title": "ZK Proof Sign-in Request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["api_key_commitment", "zk_proof", "nonce"],
+  "properties": {
+    "api_key_commitment": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]{64}$",
+      "description": "Poseidon hash of the API key, computed client-side. The API key itself is never transmitted."
+    },
+    "zk_proof": {
+      "type": "object",
+      "required": ["pi_a", "pi_b", "pi_c", "publicSignals"],
+      "additionalProperties": false,
+      "properties": {
+        "pi_a": { "type": "array", "items": { "type": "string" } },
+        "pi_b": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } },
+        "pi_c": { "type": "array", "items": { "type": "string" } },
+        "publicSignals": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Public signals: [api_key_commitment, nonce_hash, timestamp]."
+        }
+      },
+      "description": "Groth16 proof generated with seal-identity-v1 circuit."
+    },
+    "nonce": {
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 64,
+      "description": "Server-issued nonce from GET /v1/suites/auth/challenge. Single-use, expires in 60 seconds."
+    },
+    "client_metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional client identification (binds to JWT for audit).",
+      "properties": {
+        "client_id": { "type": "string" },
+        "platform": { "type": "string", "enum": ["web", "ios", "android", "cli", "server"] },
+        "subject_type": {
+          "type": "string",
+          "enum": ["human", "agent"],
+          "default": "agent",
+          "description": "Whether the sign-in is performed by a human user or an autonomous agent."
+        }
+      }
+    }
+  }
+}

package/schemas/suites/product-d-output.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.lemma.frame00.com/suites/product-d-output.json",
+  "title": "ZK Proof Sign-in Response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["access_token", "token_type", "expires_in", "session_id", "proof_record", "settlement", "requestId"],
+  "properties": {
+    "access_token": {
+      "type": "string",
+      "description": "Short-lived JWT (default TTL 15 minutes)."
+    },
+    "token_type": { "type": "string", "const": "Bearer" },
+    "expires_in": {
+      "type": "integer",
+      "default": 900,
+      "description": "Seconds until access_token expiry. Default 900 (15 minutes)."
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Server-assigned session identifier for log correlation."
+    },
+    "proof_record": {
+      "type": "object",
+      "required": ["proofId", "verifyUrl", "anchoredAt"],
+      "additionalProperties": false,
+      "properties": {
+        "proofId": { "type": "string", "format": "uri", "description": "URN of the proof record (urn:lemma:auth:<uuid>)." },
+        "verifyUrl": { "type": "string", "format": "uri", "description": "Public verification URL: https://verify.lemma.frame00.com/auth/<uuid>." },
+        "anchoredAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "settlement": {
+      "type": "object",
+      "required": ["txHash", "amount", "currency", "facilitator"],
+      "additionalProperties": false,
+      "properties": {
+        "txHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" },
+        "amount": { "type": "string", "const": "0.02" },
+        "currency": { "type": "string", "const": "USDC" },
+        "facilitator": { "type": "string", "format": "uri" }
+      }
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^req_[0-9a-z]+$",
+      "description": "Server-assigned request identifier."
+    }
+  }
+}