{ "openapi": "3.0.0", "info": { "title": "Treza Platform API", "description": "Hardware-isolated Trusted Execution Environments (TEEs) with cryptographic attestation and on-chain compliance.\nManage AWS Nitro Enclaves, verify attestation documents, submit ZK proofs, and sign blockchain transactions — all from a single API.\n\n**New in v2.3.0:**\n- 🔗 zkVerify integration — submit proofs, register verification keys, check job status\n- 📦 Proof aggregation — retrieve Merkle proof data for on-chain batch verification\n- 📊 PCR measurements endpoint — read Platform Configuration Register values\n- 🤖 operationId on every endpoint for AI agent and code-generation tooling\n\n**Previous in v2.2.0:**\n- 🔐 Zero-knowledge proof KYC verification endpoints\n- 🎫 Submit, retrieve, and verify KYC proofs\n- ⛓️ Blockchain integration for immutable proof storage\n- ⏰ Automatic proof expiration (7 days)\n- 📱 Device info tracking for mobile submissions\n\n**Previous in v2.1.0:**\n- 🛡️ Cryptographic attestation documents and verification\n- 📋 Developer integration tools and API endpoints\n- 🏦 Use case templates for Financial, Healthcare, and Enterprise\n- 🔐 PCR measurements and security validation\n- 📊 Business impact and compliance tracking\n\n**Previous in v2.0.0:**\n- 🔄 Enclave lifecycle management (pause, resume, terminate)\n- 📜 Comprehensive logs access (application, ECS, Step Functions, Lambda, errors)\n- 🐳 Docker Hub integration (search images, get tags)\n- 📊 Enhanced status tracking with real-time updates\n- 🎯 Individual enclave management endpoints\n", "version": "2.3.0", "contact": { "name": "Treza Support", "url": "https://trezalabs.com", "email": "support@trezalabs.com" } }, "servers": [ { "url": "https://app.trezalabs.com", "description": "Production server" }, { "url": "http://localhost:3000", "description": "Development server" } ], "paths": { "/api/enclaves": { "get": { "operationId": "listEnclaves", "summary": "Get user enclaves", "description": "Retrieve all enclaves associated with a wallet address", "tags": [ "Enclaves" ], "parameters": [ { "name": "wallet", "in": "query", "required": true, "description": "Wallet address to filter enclaves", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "List of enclaves", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclaves": { "type": "array", "items": { "$ref": "#/components/schemas/Enclave" } } } } } } }, "400": { "description": "Missing wallet address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createEnclave", "summary": "Create new enclave", "description": "Create a new secure enclave", "tags": [ "Enclaves" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "region", "walletAddress", "providerId" ], "properties": { "name": { "type": "string", "example": "Trading Bot Enclave" }, "description": { "type": "string", "example": "Secure environment for automated trading strategies" }, "region": { "type": "string", "example": "us-east-1" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" }, "providerId": { "type": "string", "example": "aws-nitro" }, "providerConfig": { "type": "object", "example": { "dockerImage": "my-app:latest", "cpuCount": 2, "memoryMiB": 512 } }, "githubConnection": { "$ref": "#/components/schemas/GitHubConnection" } } } } } }, "responses": { "201": { "description": "Enclave created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclave": { "$ref": "#/components/schemas/Enclave" } } } } } }, "400": { "description": "Missing required fields or invalid provider configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateEnclave", "summary": "Update enclave", "description": "Update an existing enclave", "tags": [ "Enclaves" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "walletAddress" ], "properties": { "id": { "type": "string", "example": "enc_123456" }, "name": { "type": "string", "example": "Updated Enclave Name" }, "description": { "type": "string", "example": "Updated description" }, "region": { "type": "string", "example": "us-west-2" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" }, "providerId": { "type": "string", "example": "aws-nitro" }, "providerConfig": { "type": "object", "example": { "dockerImage": "my-app:v2", "cpuCount": 4, "memoryMiB": 1024 } }, "githubConnection": { "$ref": "#/components/schemas/GitHubConnection" } } } } } }, "responses": { "200": { "description": "Enclave updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclave": { "$ref": "#/components/schemas/Enclave" } } } } } }, "400": { "description": "Missing required fields or invalid provider configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Enclave not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteEnclaveByQuery", "summary": "Delete enclave", "description": "Delete an existing enclave", "tags": [ "Enclaves" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Enclave ID to delete", "schema": { "type": "string", "example": "enc_123456" } }, { "name": "wallet", "in": "query", "required": true, "description": "Wallet address for authorization", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "Enclave deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Enclave deleted successfully" } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Enclave not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enclaves/{id}": { "get": { "operationId": "getEnclave", "summary": "Get specific enclave", "description": "Retrieve details for a specific enclave by ID", "tags": [ "Enclaves" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_123456" } } ], "responses": { "200": { "description": "Enclave details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclave": { "$ref": "#/components/schemas/Enclave" } } } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "enclaveLifecycleAction", "summary": "Manage enclave lifecycle", "description": "Perform lifecycle actions on an enclave (pause, resume, terminate)", "tags": [ "Enclaves" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_123456" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "walletAddress" ], "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "terminate" ], "example": "pause", "description": "Action to perform on the enclave" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } } } } }, "responses": { "200": { "description": "Lifecycle action performed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclave": { "$ref": "#/components/schemas/Enclave" }, "message": { "type": "string", "example": "Enclave pause initiated successfully" } } } } } }, "400": { "description": "Invalid action or enclave state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized - wallet mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteEnclave", "summary": "Delete specific enclave", "description": "Delete a specific enclave by ID (only if in terminal state)", "tags": [ "Enclaves" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_123456" } }, { "name": "wallet", "in": "query", "required": true, "description": "Wallet address for authorization", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "Enclave deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Enclave deleted successfully" } } } } } }, "400": { "description": "Enclave not in terminal state or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized - wallet mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enclaves/{id}/logs": { "get": { "operationId": "getEnclaveLogs", "summary": "Get enclave logs", "description": "Retrieve logs for a specific enclave from various sources", "tags": [ "Enclaves", "Logs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_123456" } }, { "name": "type", "in": "query", "required": false, "description": "Type of logs to retrieve", "schema": { "type": "string", "enum": [ "all", "ecs", "stepfunctions", "lambda", "application", "errors" ], "default": "all", "example": "application" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of log entries to return", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 50 } } ], "responses": { "200": { "description": "Logs retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsResponse" } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enclaves/{id}/pcrs": { "get": { "operationId": "getEnclavePCRs", "summary": "Get PCR measurements", "description": "Returns Platform Configuration Register values extracted from enclave CloudWatch logs.\nPCR0 = enclave image hash, PCR1 = Linux kernel hash, PCR2 = application hash, PCR8 = signing certificate hash.\n", "tags": [ "Attestation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_123456" } } ], "responses": { "200": { "description": "PCR values retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "pcrs": { "type": "object", "properties": { "pcr0": { "type": "string", "description": "Hash of the enclave image file", "example": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef" }, "pcr1": { "type": "string", "description": "Linux kernel and bootstrap hash", "example": "b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12" }, "pcr2": { "type": "string", "description": "Application hash", "example": "c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234" }, "pcr8": { "type": "string", "description": "Signing certificate hash", "example": "d4e5f67890abcdef1234567890abcdef1234567890abcdef123456" } } }, "message": { "type": "string", "example": "PCR values retrieved from enclave logs" } } } } } }, "404": { "description": "Enclave not found or no log streams available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enclaves/{id}/attestation": { "get": { "operationId": "getAttestation", "summary": "Get enclave attestation", "description": "Retrieve cryptographic attestation document and verification details for a deployed enclave", "tags": [ "Enclaves", "Attestation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_1234567890_abc123" } } ], "responses": { "200": { "description": "Attestation document and verification details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationResponse" } } } }, "400": { "description": "Attestation not available (enclave not deployed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Attestation only available for deployed enclaves" }, "status": { "type": "string", "example": "DEPLOYING" } } } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enclaves/{id}/attestation/verify": { "get": { "operationId": "getVerificationStatus", "summary": "Get verification status", "description": "Get quick verification status for an enclave", "tags": [ "Enclaves", "Attestation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_1234567890_abc123" } } ], "responses": { "200": { "description": "Verification status", "content": { "application/json": { "schema": { "type": "object", "properties": { "enclaveId": { "type": "string", "example": "enc_1234567890_abc123" }, "isVerified": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "DEPLOYED" }, "lastVerified": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z" }, "trustLevel": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW", "UNKNOWN" ], "example": "HIGH" } } } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "verifyAttestation", "summary": "Verify attestation document", "description": "Perform comprehensive verification of an attestation document", "tags": [ "Enclaves", "Attestation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Enclave ID", "schema": { "type": "string", "example": "enc_1234567890_abc123" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "attestationDocument": { "type": "string", "description": "Base64 encoded attestation document (optional)" }, "nonce": { "type": "string", "description": "Nonce for replay attack protection", "example": "a1b2c3d4e5f6" }, "challenge": { "type": "string", "description": "Challenge string for additional verification", "example": "verify_12345" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } }, "400": { "description": "Cannot verify (enclave not deployed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Can only verify deployed enclaves" }, "status": { "type": "string", "example": "DEPLOYING" } } } } } }, "404": { "description": "Enclave not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docker/search": { "get": { "operationId": "searchDockerImages", "summary": "Search Docker Hub or get repository tags", "description": "Search Docker Hub for images or get tags for a specific repository", "tags": [ "Docker" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search query for Docker images", "schema": { "type": "string", "example": "hello-world" } }, { "name": "repo", "in": "query", "required": false, "description": "Repository name to get tags for (e.g., 'library/node')", "schema": { "type": "string", "example": "library/node" } } ], "responses": { "200": { "description": "Search results or repository tags", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DockerSearchResponse" }, { "$ref": "#/components/schemas/DockerTagsResponse" } ] } } } }, "400": { "description": "Missing required query parameter (q or repo)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error or Docker Hub API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/providers": { "get": { "operationId": "listProviders", "summary": "Get available providers", "description": "Retrieve all available enclave providers or a specific provider by ID", "tags": [ "Providers" ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Specific provider ID to retrieve", "schema": { "type": "string", "example": "aws-nitro" } } ], "responses": { "200": { "description": "Provider(s) retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } }, { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/Provider" } } } ] } } } }, "404": { "description": "Provider not found (when requesting specific provider)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/github/auth": { "get": { "operationId": "getGitHubAuthUrl", "summary": "Initiate GitHub OAuth flow", "description": "Get GitHub OAuth authorization URL", "tags": [ "GitHub" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Optional state parameter for OAuth flow", "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub OAuth URL generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "authUrl": { "type": "string", "format": "uri", "example": "https://github.com/login/oauth/authorize?client_id=..." }, "state": { "type": "string", "example": "abc123" } } } } } }, "500": { "description": "GitHub client ID not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "exchangeGitHubCode", "summary": "Exchange OAuth code for access token", "description": "Exchange GitHub OAuth authorization code for access token", "tags": [ "GitHub" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "OAuth authorization code from GitHub", "example": "abcdef123456" }, "state": { "type": "string", "description": "State parameter from OAuth flow", "example": "abc123" } } } } } }, "responses": { "200": { "description": "Access token obtained successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "example": "gho_xxxxxxxxxxxxxxxxxxxx" }, "user": { "$ref": "#/components/schemas/GitHubUser" } } } } } }, "400": { "description": "Invalid authorization code or other OAuth error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "GitHub OAuth not configured or internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/github/callback": { "get": { "operationId": "gitHubOAuthCallback", "summary": "GitHub OAuth callback", "description": "Handle GitHub OAuth callback and redirect to platform", "tags": [ "GitHub" ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "OAuth authorization code", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "OAuth state parameter", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "OAuth error if any", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to platform page with success or error parameters" } } } }, "/api/github/repositories": { "get": { "operationId": "listGitHubRepos", "summary": "Get user repositories", "description": "Fetch GitHub repositories for authenticated user", "tags": [ "GitHub" ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "GitHub access token", "schema": { "type": "string", "example": "gho_xxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "List of repositories", "content": { "application/json": { "schema": { "type": "object", "properties": { "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/Repository" } } } } } } }, "400": { "description": "Access token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "listGitHubBranches", "summary": "Get repository branches", "description": "Fetch branches for a specific repository", "tags": [ "GitHub" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accessToken", "repository" ], "properties": { "accessToken": { "type": "string", "example": "gho_xxxxxxxxxxxxxxxxxxxx" }, "repository": { "type": "string", "example": "username/repo-name" } } } } } }, "responses": { "200": { "description": "List of branches", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } } } } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/api-keys": { "get": { "operationId": "listApiKeys", "summary": "Get API keys", "description": "Retrieve all API keys for the authenticated user", "tags": [ "API Keys" ], "parameters": [ { "name": "wallet", "in": "query", "required": true, "description": "Wallet address to filter API keys", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "400": { "description": "Missing wallet address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create API key", "description": "Create a new API key with specified permissions", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "permissions", "walletAddress" ], "properties": { "name": { "type": "string", "example": "Production API Key" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "enclaves:read", "enclaves:write", "tasks:read", "tasks:write", "logs:read" ] }, "example": [ "enclaves:read", "tasks:read" ] }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } } } } }, "responses": { "201": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "400": { "description": "Missing required fields or invalid permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateApiKey", "summary": "Update API key", "description": "Update an existing API key", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "walletAddress" ], "properties": { "id": { "type": "string", "example": "key_123456" }, "name": { "type": "string", "example": "Updated API Key Name" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "enclaves:read", "enclaves:write", "tasks:read", "tasks:write", "logs:read" ] }, "example": [ "enclaves:read", "enclaves:write" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } } } } }, "responses": { "200": { "description": "API key updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "400": { "description": "Missing required fields or invalid permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteApiKey", "summary": "Delete API key", "description": "Delete an existing API key", "tags": [ "API Keys" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "API key ID to delete", "schema": { "type": "string", "example": "key_123456" } }, { "name": "wallet", "in": "query", "required": true, "description": "Wallet address for authorization", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "API key deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "API key deleted successfully" } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kyc/proof": { "post": { "operationId": "submitKYCProof", "summary": "Submit ZK proof for KYC verification", "description": "Submit a zero-knowledge proof for KYC verification. The proof is validated, stored in DynamoDB,\nand optionally submitted to the blockchain for immutable verification.\n\n**Authentication:** None required (open endpoint)\n\n**Rate Limiting:** Recommended 10 requests/hour per IP\n\n**Security:** Cryptographic proof validation prevents fake submissions\n", "tags": [ "KYC" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userId", "proof" ], "properties": { "userId": { "type": "string", "description": "User identifier", "example": "user_abc123" }, "proof": { "$ref": "#/components/schemas/ZKProof" }, "deviceInfo": { "type": "object", "properties": { "platform": { "type": "string", "example": "iOS" }, "version": { "type": "string", "example": "17.0" } } } } } } } }, "responses": { "201": { "description": "Proof submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "proofId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "Unique identifier for the submitted proof" }, "blockchainProofId": { "type": "string", "example": "0x1234567890abcdef", "description": "On-chain proof identifier (if blockchain submission succeeded)" }, "verificationUrl": { "type": "string", "format": "uri", "example": "/api/kyc/proof/550e8400-e29b-41d4-a716-446655440000", "description": "URL to verify the proof" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2024-12-22T10:30:00Z", "description": "Proof expiration timestamp (7 days from submission)" }, "chainTxHash": { "type": "string", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "description": "Blockchain transaction hash (if blockchain submission succeeded)" } } } } } }, "400": { "description": "Invalid request or proof verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingFields": { "value": { "error": "Missing required fields: userId and proof" } }, "invalidFormat": { "value": { "error": "Invalid proof format" } }, "verificationFailed": { "value": { "error": "Proof verification failed" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kyc/proof/{proofId}": { "get": { "operationId": "getKYCProof", "summary": "Get proof details", "description": "Retrieve details for a specific KYC proof by ID. By default returns public data only.", "tags": [ "KYC" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "description": "Proof ID (UUID)", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "name": "includePrivate", "in": "query", "required": false, "description": "Include private proof data (requires authentication)", "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Proof details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofDetails" } } } }, "404": { "description": "Proof not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/kyc/proof/{proofId}/verify": { "get": { "operationId": "verifyKYCProof", "summary": "Verify a proof by ID", "description": "Verify the validity of a KYC proof, checking expiration and blockchain status", "tags": [ "KYC" ], "parameters": [ { "name": "proofId", "in": "path", "required": true, "description": "Proof ID (UUID)", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "proofId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "isValid": { "type": "boolean", "example": true, "description": "Whether the proof is valid and not expired" }, "publicInputs": { "type": "array", "items": { "type": "string" }, "example": [ "0x1234567890abcdef", "0xfedcba0987654321" ], "description": "Public inputs used in the proof" }, "verifiedAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Timestamp when proof was originally verified" }, "chainVerified": { "type": "boolean", "example": true, "description": "Whether the proof was verified on blockchain" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2024-12-22T10:30:00Z", "description": "Proof expiration timestamp" } } } } } }, "404": { "description": "Proof not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Proof expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Proof expired" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/tasks": { "get": { "operationId": "listTasks", "summary": "Get tasks", "description": "Retrieve tasks for the authenticated user, optionally filtered by enclave", "tags": [ "Tasks" ], "parameters": [ { "name": "wallet", "in": "query", "required": true, "description": "Wallet address to filter tasks", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } }, { "name": "enclave", "in": "query", "required": false, "description": "Optional enclave ID to filter tasks", "schema": { "type": "string", "example": "enc_123456" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } } } }, "400": { "description": "Missing wallet address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTask", "summary": "Create task", "description": "Create a new task within an enclave", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "enclaveId", "schedule", "walletAddress" ], "properties": { "name": { "type": "string", "example": "Daily Price Monitor" }, "description": { "type": "string", "example": "Monitor cryptocurrency prices and send alerts" }, "enclaveId": { "type": "string", "example": "enc_123456" }, "schedule": { "type": "string", "example": "0 9 * * *", "description": "Cron-style schedule expression" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } } } } }, "responses": { "201": { "description": "Task created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updateTask", "summary": "Update task", "description": "Update an existing task", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "walletAddress" ], "properties": { "id": { "type": "string", "example": "task_123456" }, "name": { "type": "string", "example": "Updated Task Name" }, "description": { "type": "string", "example": "Updated task description" }, "schedule": { "type": "string", "example": "0 */6 * * *" }, "status": { "type": "string", "enum": [ "running", "stopped", "failed", "pending" ], "example": "running" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } } } } }, "responses": { "200": { "description": "Task updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteTask", "summary": "Delete task", "description": "Delete an existing task", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Task ID to delete", "schema": { "type": "string", "example": "task_123456" } }, { "name": "wallet", "in": "query", "required": true, "description": "Wallet address for authorization", "schema": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" } } ], "responses": { "200": { "description": "Task deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Task deleted successfully" } } } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/zkverify/submit-proof": { "post": { "operationId": "submitZKProof", "summary": "Submit ZK proof for verification", "description": "Submit a zero-knowledge proof to the zkVerify network for verification via the Horizen relayer.\nSupports proof types: groth16, risc0, ultrahonk, ultraplonk, sp1, ezkl.\nReturns a job ID for tracking verification status.\n", "tags": [ "ZK Verification" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "proof", "publicSignals", "vk" ], "properties": { "proof": { "type": "string", "description": "The ZK proof data" }, "publicSignals": { "type": "array", "items": { "type": "string" }, "description": "Public signals / inputs for the proof" }, "vk": { "type": "string", "description": "Verification key (or vkHash if already registered)" }, "proofType": { "type": "string", "enum": [ "groth16", "risc0", "ultrahonk", "ultraplonk", "sp1", "ezkl" ], "default": "groth16", "description": "Type of zero-knowledge proof" }, "chainId": { "type": "integer", "default": 11155111, "description": "Target chain ID for attestation (default: Sepolia)" }, "userAddress": { "type": "string", "description": "Wallet address of the submitter (optional)" } } } } } }, "responses": { "200": { "description": "Proof submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "jobId": { "type": "string", "example": "job_abc123", "description": "Job ID for tracking verification status" }, "optimisticVerify": { "type": "string", "description": "Optimistic verification result" }, "message": { "type": "string", "example": "Proof submitted for verification" } } } } } }, "400": { "description": "Invalid proof data or missing fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Relayer or internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/zkverify/register-vk": { "post": { "operationId": "registerVerificationKey", "summary": "Register a verification key", "description": "Register a verification key with the zkVerify network. This should be done once per verification key\nbefore submitting proofs. The returned vkHash can be reused for subsequent proof submissions.\n", "tags": [ "ZK Verification" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vk" ], "properties": { "vk": { "type": "object", "description": "Verification key data structure (format depends on proof type)" }, "proofType": { "type": "string", "enum": [ "groth16", "risc0", "ultrahonk", "ultraplonk", "sp1", "ezkl" ], "default": "groth16", "description": "Type of zero-knowledge proof system" }, "proofOptions": { "type": "object", "properties": { "library": { "type": "string", "description": "ZK library name (e.g., snarkjs, gnark)" }, "curve": { "type": "string", "description": "Elliptic curve (e.g., bn128, bls12_381)" }, "numberOfPublicInputs": { "type": "integer", "description": "Number of public inputs in the circuit" }, "version": { "type": "string", "description": "Library version" } } } } } } } }, "responses": { "200": { "description": "Verification key registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "vkHash": { "type": "string", "description": "Hash of the registered verification key — use this in proof submissions" }, "jobId": { "type": "string", "description": "Job ID for tracking registration status" }, "message": { "type": "string", "example": "Verification key registered successfully" } } } } } }, "400": { "description": "Invalid verification key format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Relayer or internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/zkverify/job-status/{jobId}": { "get": { "operationId": "getZKJobStatus", "summary": "Get ZK proof verification job status", "description": "Check the status of a previously submitted ZK proof verification job.\nReturns the current status, proof type, and blockchain transaction details when available.\n", "tags": [ "ZK Verification" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID returned from submit-proof or register-vk", "schema": { "type": "string", "example": "job_abc123" } } ], "responses": { "200": { "description": "Job status retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "jobStatus": { "type": "object", "properties": { "jobId": { "type": "string", "example": "job_abc123" }, "status": { "type": "string", "enum": [ "pending", "processing", "verified", "failed", "aggregated" ], "example": "verified" }, "proofType": { "type": "string", "example": "groth16" }, "txHash": { "type": "string", "description": "zkVerify transaction hash" }, "blockHash": { "type": "string", "description": "Block hash containing the verification" }, "aggregationId": { "type": "string", "description": "Aggregation ID (available once aggregated)" } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Relayer or internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/zkverify/aggregation/{aggregationId}": { "get": { "operationId": "getAggregationDetails", "summary": "Get aggregation details for on-chain verification", "description": "Retrieve the aggregation data needed to verify proofs on-chain using\nzkVerify's IVerifyProofAggregation contract. Returns the Merkle proof path,\ndomain ID, leaf count, leaf index, and root hash.\n", "tags": [ "ZK Verification" ], "parameters": [ { "name": "aggregationId", "in": "path", "required": true, "description": "Aggregation ID from a completed verification job", "schema": { "type": "string", "example": "agg_xyz789" } } ], "responses": { "200": { "description": "Aggregation data for on-chain verification", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "aggregation": { "type": "object", "properties": { "aggregationId": { "type": "string" }, "root": { "type": "string", "description": "Merkle root hash" }, "domainId": { "type": "integer", "description": "Domain ID for the aggregation" }, "leafCount": { "type": "integer", "description": "Number of leaves in the Merkle tree" }, "leafIndex": { "type": "integer", "description": "Index of this proof's leaf" }, "proof": { "type": "array", "items": { "type": "string" }, "description": "Merkle proof path for on-chain verification" } } } } } } } }, "404": { "description": "Aggregation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/zkverify/aggregation/job/{jobId}": { "get": { "operationId": "getAggregationByJobId", "summary": "Get aggregation data by job ID", "description": "Convenience endpoint that fetches job status and, if the job is aggregated,\nreturns the aggregation details needed for smart contract verification in one call.\n", "tags": [ "ZK Verification" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID from a previously submitted proof", "schema": { "type": "string", "example": "job_abc123" } } ], "responses": { "200": { "description": "Aggregation data for the job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "verified", "failed", "aggregated" ] }, "aggregation": { "type": "object", "description": "Present only when status is 'aggregated'", "properties": { "aggregationId": { "type": "string" }, "root": { "type": "string" }, "domainId": { "type": "integer" }, "leafCount": { "type": "integer" }, "leafIndex": { "type": "integer" }, "proof": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Missing job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Enclave": { "type": "object", "properties": { "id": { "type": "string", "example": "enc_123456" }, "name": { "type": "string", "example": "Trading Bot Enclave" }, "description": { "type": "string", "example": "Secure environment for automated trading strategies" }, "status": { "type": "string", "enum": [ "PENDING_DEPLOY", "DEPLOYING", "DEPLOYED", "PAUSING", "PAUSED", "RESUMING", "PENDING_DESTROY", "DESTROYING", "DESTROYED", "FAILED" ], "example": "PENDING_DEPLOY" }, "region": { "type": "string", "example": "us-east-1" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" }, "providerId": { "type": "string", "example": "aws-nitro", "description": "The ID of the provider used for this enclave" }, "providerConfig": { "type": "object", "example": { "dockerImage": "my-app:latest", "cpuCount": 2, "memoryMiB": 512 }, "description": "Provider-specific configuration settings" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "githubConnection": { "$ref": "#/components/schemas/GitHubConnection" }, "error_message": { "type": "string", "example": "Deployment failed: Instance type not compatible with Nitro Enclaves", "description": "Error message if enclave failed (optional)" } } }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "example": "aws-nitro" }, "name": { "type": "string", "example": "AWS Nitro Enclaves" }, "description": { "type": "string", "example": "Secure isolated compute environments using AWS Nitro technology" }, "regions": { "type": "array", "items": { "type": "string" }, "example": [ "us-east-1", "us-west-2", "eu-west-1" ] }, "configSchema": { "type": "object", "description": "Schema defining the configuration options for this provider", "example": { "dockerImage": { "type": "string", "label": "Docker Image", "required": true, "description": "Container image to deploy" }, "cpuCount": { "type": "number", "label": "CPU Count", "defaultValue": 2, "validation": { "min": 1, "max": 8 } } } } } }, "GitHubConnection": { "type": "object", "properties": { "isConnected": { "type": "boolean", "example": true }, "username": { "type": "string", "example": "example-user" }, "selectedRepo": { "type": "string", "example": "example-user/trading-bot" }, "selectedBranch": { "type": "string", "example": "main" }, "accessToken": { "type": "string", "example": "gho_xxxxxxxxxxxxxxxxxxxx" } } }, "GitHubUser": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "login": { "type": "string", "example": "username" }, "name": { "type": "string", "example": "John Doe" }, "avatar_url": { "type": "string", "format": "uri", "example": "https://avatars.githubusercontent.com/u/12345" } } }, "Repository": { "type": "object", "properties": { "id": { "type": "integer", "example": 123456 }, "name": { "type": "string", "example": "my-repo" }, "fullName": { "type": "string", "example": "username/my-repo" }, "description": { "type": "string", "example": "A sample repository" }, "private": { "type": "boolean", "example": false }, "defaultBranch": { "type": "string", "example": "main" }, "language": { "type": "string", "example": "TypeScript" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "htmlUrl": { "type": "string", "format": "uri", "example": "https://github.com/username/my-repo" } } }, "Branch": { "type": "object", "properties": { "name": { "type": "string", "example": "main" }, "commit": { "type": "object", "properties": { "sha": { "type": "string", "example": "abc123def456" }, "url": { "type": "string", "format": "uri", "example": "https://api.github.com/repos/username/repo/commits/abc123def456" } } } } }, "Task": { "type": "object", "properties": { "id": { "type": "string", "example": "task_123456" }, "name": { "type": "string", "example": "Daily Price Monitor" }, "description": { "type": "string", "example": "Monitor cryptocurrency prices and send alerts" }, "enclaveId": { "type": "string", "example": "enc_123456" }, "status": { "type": "string", "enum": [ "running", "stopped", "failed", "pending" ], "example": "pending" }, "schedule": { "type": "string", "example": "0 9 * * *", "description": "Cron-style schedule expression" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "lastRun": { "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z", "description": "Timestamp of last execution (optional)" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "example": "key_123456" }, "name": { "type": "string", "example": "Production API Key" }, "key": { "type": "string", "example": "api_key_example_12345", "description": "The actual API key (only returned on creation)" }, "keyHash": { "type": "string", "example": "sha256_hash_of_key", "description": "SHA256 hash of the API key for storage" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "enclaves:read", "enclaves:write", "tasks:read", "tasks:write", "logs:read" ] }, "example": [ "enclaves:read", "tasks:read" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "walletAddress": { "type": "string", "example": "0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T00:00:00Z" }, "lastUsed": { "type": "string", "format": "date-time", "example": "2024-01-15T12:30:00Z", "description": "Timestamp of last usage (optional)" } } }, "ZKProof": { "type": "object", "required": [ "commitment", "proof", "publicInputs", "timestamp", "algorithm" ], "properties": { "commitment": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-fA-F]{64}$", "example": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "description": "64-character hex commitment hash" }, "proof": { "type": "string", "minLength": 65, "example": "0x1234567890abcdef...proof_data_here...987654321fedcba", "description": "Zero-knowledge proof data (minimum 65 characters)" }, "publicInputs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "0x1234567890abcdef", "0xfedcba0987654321" ], "description": "Public inputs used in the ZK proof" }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Proof generation timestamp (must be within 1 hour)" }, "algorithm": { "type": "string", "enum": [ "Pedersen-SHA256" ], "example": "Pedersen-SHA256", "description": "Cryptographic algorithm used for the proof" } } }, "ProofDetails": { "type": "object", "properties": { "proofId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "Unique proof identifier" }, "commitment": { "type": "string", "example": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "description": "Commitment hash" }, "publicInputs": { "type": "array", "items": { "type": "string" }, "example": [ "0x1234567890abcdef", "0xfedcba0987654321" ], "description": "Public inputs" }, "algorithm": { "type": "string", "example": "Pedersen-SHA256", "description": "Algorithm used" }, "verifiedAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Verification timestamp" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2024-12-22T10:30:00Z", "description": "Expiration timestamp (7 days after verification)" }, "proof": { "type": "string", "example": "0x1234567890abcdef...proof_signature_here...", "description": "Proof signature (only included when includePrivate=true)" }, "timestamp": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Original proof timestamp (only included when includePrivate=true)" } }, "required": [ "proofId", "commitment", "publicInputs", "algorithm", "verifiedAt", "expiresAt" ] }, "ProofRecord": { "type": "object", "description": "Internal proof record stored in DynamoDB", "properties": { "proofId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "userId": { "type": "string", "example": "user_abc123" }, "commitment": { "type": "string", "example": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "proof": { "type": "string", "example": "0x1234567890abcdef...proof_data..." }, "publicInputs": { "type": "array", "items": { "type": "string" }, "example": [ "0x1234567890abcdef" ] }, "algorithm": { "type": "string", "example": "Pedersen-SHA256" }, "status": { "type": "string", "enum": [ "verified", "pending", "failed", "expired" ], "example": "verified" }, "verifiedAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2024-12-22T10:30:00Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z" }, "devicePlatform": { "type": "string", "example": "iOS", "description": "Device platform (optional)" }, "deviceVersion": { "type": "string", "example": "17.0", "description": "Device version (optional)" }, "chainTxHash": { "type": "string", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "description": "Blockchain transaction hash (optional)" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "Error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Additional error details (optional)" } } }, "LogEntry": { "type": "object", "properties": { "timestamp": { "type": "integer", "format": "int64", "example": 1640995200000, "description": "Unix timestamp in milliseconds" }, "message": { "type": "string", "example": "Application started successfully" }, "source": { "type": "string", "enum": [ "ecs", "stepfunctions", "lambda", "application", "dynamodb" ], "example": "application" }, "stream": { "type": "string", "example": "ecs/treza-dev-terraform-runner/12345", "description": "Log stream name (optional)" }, "type": { "type": "string", "enum": [ "application", "stdout", "stderr", "info", "error" ], "example": "stdout", "description": "Log type (optional)" }, "logGroup": { "type": "string", "example": "/aws/nitro-enclave/enc_123456/application", "description": "CloudWatch log group (optional)" }, "function": { "type": "string", "example": "treza-dev-validation", "description": "Lambda function name for lambda logs (optional)" }, "execution": { "type": "string", "example": "deployment-enc_123456", "description": "Step Function execution name (optional)" }, "stateMachine": { "type": "string", "enum": [ "deployment", "cleanup" ], "example": "deployment", "description": "Step Function state machine type (optional)" } } }, "LogsResponse": { "type": "object", "properties": { "enclave_id": { "type": "string", "example": "enc_123456" }, "enclave_name": { "type": "string", "example": "Trading Bot Enclave" }, "enclave_status": { "type": "string", "example": "DEPLOYED" }, "logs": { "type": "object", "properties": { "ecs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "ECS deployment logs (optional)" }, "stepfunctions": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Step Functions workflow logs (optional)" }, "lambda": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Lambda function logs (optional)" }, "application": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Application logs from the enclave (optional)" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Error logs from all sources (optional)" } } } } }, "DockerImage": { "type": "object", "properties": { "name": { "type": "string", "example": "hello-world" }, "description": { "type": "string", "example": "Hello World! (an example of minimal Dockerization)" }, "stars": { "type": "integer", "example": 1500, "description": "Number of stars on Docker Hub" }, "official": { "type": "boolean", "example": true, "description": "Whether this is an official Docker image" }, "automated": { "type": "boolean", "example": false, "description": "Whether this is an automated build" }, "owner": { "type": "string", "example": "library", "description": "Image owner/namespace (optional)" } } }, "DockerTag": { "type": "object", "properties": { "name": { "type": "string", "example": "latest" }, "size": { "type": "integer", "format": "int64", "example": 13336, "description": "Image size in bytes" }, "lastUpdated": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "description": "Last updated timestamp" }, "digest": { "type": "string", "example": "sha256:abc123def456...", "description": "Image digest" } } }, "DockerSearchResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 150, "description": "Total number of search results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DockerImage" } } } }, "DockerTagsResponse": { "type": "object", "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/DockerTag" } } } }, "AttestationDocument": { "type": "object", "properties": { "moduleId": { "type": "string", "example": "nitro-enclave-enc_1234567890_abc123", "description": "Unique identifier for the enclave module" }, "digest": { "type": "string", "example": "sha384:abc123def456...", "description": "SHA-384 digest of the enclave image" }, "timestamp": { "type": "integer", "format": "int64", "example": 1702642200000, "description": "Unix timestamp when attestation was generated" }, "pcrs": { "type": "object", "properties": { "0": { "type": "string", "example": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef", "description": "PCR0: Hash of the enclave image file" }, "1": { "type": "string", "example": "b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12", "description": "PCR1: Linux kernel and bootstrap hash" }, "2": { "type": "string", "example": "c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234", "description": "PCR2: Application hash" }, "8": { "type": "string", "example": "d4e5f67890abcdef1234567890abcdef1234567890abcdef123456", "description": "PCR8: Signing certificate hash" } }, "required": [ "0", "1", "2", "8" ] }, "certificate": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----", "description": "X.509 certificate for verification" }, "cabundle": { "type": "array", "items": { "type": "string" }, "example": [ "-----BEGIN CERTIFICATE-----\nMIIB...", "-----BEGIN CERTIFICATE-----\nMIIC..." ], "description": "Certificate authority bundle" }, "publicKey": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBg...\n-----END PUBLIC KEY-----", "description": "Public key for verification (optional)" }, "userData": { "type": "string", "nullable": true, "example": "custom-user-data", "description": "User-provided data included in attestation (optional)" }, "nonce": { "type": "string", "example": "a1b2c3d4e5f6", "description": "Nonce for replay attack protection (optional)" } }, "required": [ "moduleId", "digest", "timestamp", "pcrs", "certificate", "cabundle" ] }, "AttestationVerification": { "type": "object", "properties": { "isValid": { "type": "boolean", "example": true, "description": "Whether the attestation is valid" }, "trustLevel": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "example": "HIGH", "description": "Trust level based on verification results" }, "verificationStatus": { "type": "string", "enum": [ "VERIFIED", "PENDING", "FAILED" ], "example": "VERIFIED", "description": "Current verification status" }, "integrityScore": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "example": 98.5, "description": "Integrity score as a percentage" }, "lastVerified": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Timestamp of last verification" }, "errors": { "type": "array", "items": { "type": "string" }, "example": [], "description": "List of verification errors (if any)" } }, "required": [ "isValid", "trustLevel", "verificationStatus", "integrityScore", "lastVerified" ] }, "AttestationResponse": { "type": "object", "properties": { "enclaveId": { "type": "string", "example": "enc_1234567890_abc123", "description": "Enclave identifier" }, "attestationDocument": { "$ref": "#/components/schemas/AttestationDocument" }, "verification": { "$ref": "#/components/schemas/AttestationVerification" }, "endpoints": { "type": "object", "properties": { "verificationUrl": { "type": "string", "format": "uri", "example": "https://app.trezalabs.com/api/enclaves/enc_123456/attestation/verify", "description": "URL for third-party verification" }, "apiEndpoint": { "type": "string", "format": "uri", "example": "https://app.trezalabs.com/api/enclaves/enc_123456/attestation", "description": "API endpoint for attestation data" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://app.trezalabs.com/api/enclaves/enc_123456/attestation/webhook", "description": "Webhook URL for real-time verification updates" } }, "required": [ "verificationUrl", "apiEndpoint", "webhookUrl" ] } }, "required": [ "enclaveId", "attestationDocument", "verification", "endpoints" ] }, "VerificationResult": { "type": "object", "properties": { "isValid": { "type": "boolean", "example": true, "description": "Whether the attestation verification passed" }, "trustLevel": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "example": "HIGH", "description": "Overall trust level" }, "verificationDetails": { "type": "object", "properties": { "pcrVerification": { "type": "boolean", "example": true, "description": "Whether PCR measurements are valid" }, "certificateChain": { "type": "boolean", "example": true, "description": "Whether certificate chain verification passed" }, "timestampValid": { "type": "boolean", "example": true, "description": "Whether timestamp is within acceptable range" }, "nonceMatches": { "type": "boolean", "example": false, "description": "Whether provided nonce matches (if nonce was provided)" }, "signatureValid": { "type": "boolean", "example": true, "description": "Whether cryptographic signature is valid" } }, "required": [ "pcrVerification", "certificateChain", "timestampValid", "nonceMatches", "signatureValid" ] }, "complianceChecks": { "type": "object", "properties": { "soc2": { "type": "boolean", "example": false, "description": "SOC 2 compliance status" }, "hipaa": { "type": "boolean", "example": false, "description": "HIPAA compliance status" }, "fips": { "type": "boolean", "example": true, "description": "FIPS 140-2 compliance status" }, "commonCriteria": { "type": "boolean", "example": true, "description": "Common Criteria compliance status" } }, "required": [ "soc2", "hipaa", "fips", "commonCriteria" ] }, "riskScore": { "type": "integer", "minimum": 0, "maximum": 100, "example": 5, "description": "Risk score (lower is better)" }, "recommendations": { "type": "array", "items": { "type": "string" }, "example": [ "Enclave attestation is valid and secure", "All PCR measurements match expected values", "Certificate chain verification successful" ], "description": "Security recommendations and observations" }, "verifiedAt": { "type": "string", "format": "date-time", "example": "2024-12-15T10:30:00Z", "description": "Timestamp when verification was performed" } }, "required": [ "isValid", "trustLevel", "verificationDetails", "complianceChecks", "riskScore", "recommendations", "verifiedAt" ] } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "WalletAuth": { "type": "apiKey", "in": "query", "name": "wallet", "description": "Wallet address for authentication" } } }, "security": [ { "BearerAuth": [] }, { "WalletAuth": [] } ], "tags": [ { "name": "Enclaves", "description": "Secure enclave management and lifecycle control" }, { "name": "Attestation", "description": "Cryptographic attestation and verification services" }, { "name": "KYC", "description": "Zero-knowledge proof KYC verification and management" }, { "name": "Logs", "description": "Enclave logs and monitoring" }, { "name": "Docker", "description": "Docker Hub integration and image management" }, { "name": "Providers", "description": "Enclave provider information" }, { "name": "GitHub", "description": "GitHub integration and OAuth" }, { "name": "API Keys", "description": "API key management with permissions and authentication" }, { "name": "Tasks", "description": "Task scheduling and management within enclaves" }, { "name": "ZK Verification", "description": "Zero-knowledge proof submission, verification key registration, and aggregation via zkVerify" } ] }