{
  "openapi": "3.1.0",
  "info": {
    "title": "Sealith Agent API",
    "version": "1.3.0",
    "description": "Purpose-bound secure handoff and governed commerce APIs for AI agents. Business plan or higher is required."
  },
  "servers": [
    {
      "url": "https://www.sealith.com"
    }
  ],
  "security": [
    {
      "AgentToken": []
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use an Agent Token secret issued from the Sealith dashboard."
      }
    },
    "schemas": {
      "Recipient": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": ["string", "null"]
          }
        }
      },
      "TransferPayload": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "fileName",
              "fileSizeBytes",
              "mimeType",
              "recipients",
              "salt",
              "ivFile",
              "ivWrap",
              "passcodeHash",
              "expiresAt",
              "maxDownloads",
              "passcodeDeliveryMode",
              "sensitivityLevel"
            ],
            "properties": {
              "resourceType": {
                "type": "string",
                "enum": ["file"],
                "default": "file"
              },
              "fileName": {
                "type": "string",
                "maxLength": 255
              },
              "fileSizeBytes": {
                "type": "integer",
                "minimum": 1
              },
              "mimeType": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/Recipient"
                }
              },
              "message": {
                "type": ["string", "null"],
                "maxLength": 500
              },
              "purpose": {
                "type": ["string", "null"],
                "maxLength": 200
              },
              "allowedUse": {
                "type": "string",
                "enum": ["view_only", "summarize_allowed", "internal_use_only", "no_external_sharing"],
                "default": "view_only"
              },
              "recipientType": {
                "type": "string",
                "enum": ["human", "ai_agent", "external_org"],
                "default": "human"
              },
              "salt": {
                "type": "string"
              },
              "ivFile": {
                "type": "string"
              },
              "ivWrap": {
                "type": "string"
              },
              "passcodeHash": {
                "type": "string"
              },
              "senderAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "systemAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"],
                "enum": [1, 3, 5, 10, 20, null]
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "sensitivityLevel": {
                "type": "string",
                "enum": ["public", "internal", "confidential", "restricted"]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "resourceType",
              "title",
              "targetUrl",
              "targetDomain",
              "recipients",
              "passcodeHash",
              "expiresAt",
              "maxDownloads",
              "passcodeDeliveryMode",
              "sensitivityLevel"
            ],
            "properties": {
              "resourceType": {
                "type": "string",
                "enum": ["url"]
              },
              "title": {
                "type": "string",
                "maxLength": 255
              },
              "targetUrl": {
                "type": "string",
                "format": "uri"
              },
              "targetDomain": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/Recipient"
                }
              },
              "message": {
                "type": ["string", "null"],
                "maxLength": 500
              },
              "purpose": {
                "type": ["string", "null"],
                "maxLength": 200
              },
              "allowedUse": {
                "type": "string",
                "enum": ["view_only", "summarize_allowed", "internal_use_only", "no_external_sharing"],
                "default": "view_only"
              },
              "recipientType": {
                "type": "string",
                "enum": ["human", "ai_agent", "external_org"],
                "default": "human"
              },
              "passcodeHash": {
                "type": "string"
              },
              "senderAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "systemAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"],
                "enum": [1, 3, 5, 10, 20, null]
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "sensitivityLevel": {
                "type": "string",
                "enum": ["public", "internal", "confidential", "restricted"]
              }
            }
          }
        ]
      },
      "WorkPassportRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reviewPolicy": {
            "type": "string",
            "enum": ["policy_based", "human_review"],
            "default": "policy_based"
          },
          "contentHashSha256": {
            "type": ["string", "null"],
            "pattern": "^[a-fA-F0-9]{64}$"
          },
          "contentHashSource": {
            "type": "string",
            "enum": ["client_calculated", "provider_metadata"],
            "default": "client_calculated"
          },
          "provenanceAssertions": {
            "type": "array",
            "maxItems": 12,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["kind", "status"],
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": ["c2pa", "watermark", "provider_metadata", "user_declaration", "other"]
                },
                "status": {
                  "type": "string",
                  "enum": ["detected", "declared", "unknown", "conflict"]
                },
                "issuer": { "type": ["string", "null"], "maxLength": 120 },
                "referenceId": { "type": ["string", "null"], "maxLength": 240 },
                "verifier": { "type": ["string", "null"], "maxLength": 120 }
              }
            }
          },
          "sourceReferences": {
            "type": "array",
            "maxItems": 24,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["referenceId"],
              "properties": {
                "referenceId": { "type": "string", "maxLength": 240 },
                "hashSha256": {
                  "type": ["string", "null"],
                  "pattern": "^[a-fA-F0-9]{64}$"
                },
                "relationship": {
                  "type": "string",
                  "enum": ["source", "template", "policy", "supporting_evidence"],
                  "default": "source"
                }
              }
            }
          }
        }
      },
      "WorkPassportSummary": {
        "type": "object",
        "required": ["workId", "schemaVersion", "reviewPolicy", "bindingStrength"],
        "properties": {
          "workId": { "type": "string" },
          "schemaVersion": { "type": "string", "const": "sealith.work.v1" },
          "reviewPolicy": { "type": "string", "enum": ["policy_based", "human_review"] },
          "bindingStrength": {
            "type": "string",
            "enum": ["descriptor_only", "client_declared_hash", "provider_metadata_hash"]
          }
        }
      },
      "WorkPassportView": {
        "type": "object",
        "required": ["workId", "manifest", "signature", "signatureAlgorithm", "keyId", "signatureValid", "lifecycleStatus", "evidenceStrength", "events"],
        "properties": {
          "workId": { "type": "string" },
          "manifest": { "type": "object", "additionalProperties": true },
          "signature": { "type": "string" },
          "signatureAlgorithm": { "type": "string", "const": "HMAC-SHA256" },
          "keyId": { "type": "string" },
          "signatureValid": { "type": "boolean" },
          "lifecycleStatus": {
            "type": "string",
            "enum": ["draft", "review_required", "approved", "rejected", "released", "revoked"]
          },
          "evidenceStrength": {
            "type": "string",
            "enum": ["verified_identity", "reported_provenance", "unknown", "conflict"]
          },
          "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "TransferCreateInput": {
        "type": "object",
        "required": ["purpose", "jobId", "aiProvider", "aiClient", "transfer"],
        "properties": {
          "purpose": {
            "type": "string",
            "maxLength": 120
          },
          "jobId": {
            "type": "string",
            "maxLength": 160
          },
          "aiProvider": {
            "type": "string",
            "maxLength": 80
          },
          "aiModel": {
            "type": ["string", "null"],
            "maxLength": 120
          },
          "aiClient": {
            "type": "string",
            "maxLength": 80
          },
          "workPassport": {
            "oneOf": [
              { "$ref": "#/components/schemas/WorkPassportRequest" },
              { "type": "null" }
            ]
          },
          "transfer": {
            "$ref": "#/components/schemas/TransferPayload"
          }
        }
      },
      "TransferCreateResponse": {
        "type": "object",
        "required": ["transferId", "uploadUrl", "expiresIn", "shareUrlPath", "passcodeScheduledSendAt"],
        "properties": {
          "transferId": {
            "type": "string"
          },
          "uploadUrl": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "expiresIn": {
            "type": "integer"
          },
          "shareUrlPath": {
            "type": "string"
          },
          "passcodeScheduledSendAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "purpose": {
            "type": ["string", "null"]
          },
          "allowedUse": {
            "type": "string",
            "enum": ["view_only", "summarize_allowed", "internal_use_only", "no_external_sharing"]
          },
          "recipientType": {
            "type": "string",
            "enum": ["human", "ai_agent", "external_org"]
          },
          "approvalRequired": {
            "type": "boolean"
          },
          "approvalReasons": {
            "type": "array",
            "items": { "type": "string" }
          },
          "workPassport": {
            "$ref": "#/components/schemas/WorkPassportSummary"
          }
        }
      },
      "TransferRecipientStatus": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Recipient"
          },
          {
            "type": "object",
            "properties": {
              "notifiedUrlAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "notifiedPasscodeAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "firstAccessedAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "downloadCount": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "TransferStatusResponse": {
        "type": "object",
        "required": ["transfer"],
        "properties": {
          "transfer": {
            "type": "object",
            "required": [
              "id",
              "fileName",
              "fileSizeBytes",
              "mimeType",
              "recipients",
              "status",
              "expiresAt",
              "maxDownloads",
              "totalDownloadCount",
              "passcodeDeliveryMode",
              "passcodeScheduledSendAt",
              "createdAt"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "fileName": {
                "type": "string"
              },
              "fileSizeBytes": {
                "type": "integer"
              },
              "mimeType": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TransferRecipientStatus"
                }
              },
              "status": {
                "type": "string"
              },
              "expiresAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"]
              },
              "totalDownloadCount": {
                "type": "integer"
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "passcodeScheduledSendAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "purpose": {
                "type": ["string", "null"]
              },
              "allowedUse": {
                "type": "string",
                "enum": ["view_only", "summarize_allowed", "internal_use_only", "no_external_sharing"]
              },
              "recipientType": {
                "type": "string",
                "enum": ["human", "ai_agent", "external_org"]
              },
              "createdAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "resourceType": {
                "type": "string",
                "enum": ["file", "url", "text"]
              },
              "title": {
                "type": ["string", "null"]
              },
              "targetUrl": {
                "type": ["string", "null"],
                "format": "uri"
              },
              "targetDomain": {
                "type": ["string", "null"]
              },
              "workPassport": {
                "oneOf": [
                  { "$ref": "#/components/schemas/WorkPassportView" },
                  { "type": "null" }
                ]
              }
            }
          }
        }
      },
      "FinalizeTransferInput": {
        "type": "object",
        "required": ["shareUrl"],
        "properties": {
          "shareUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "AppendAuditContextInput": {
        "type": "object",
        "required": ["transferId", "purpose", "note"],
        "properties": {
          "transferId": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "jobId": {
            "type": ["string", "null"]
          },
          "note": {
            "type": "string"
          },
          "result": {
            "type": ["string", "null"]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "AccessLogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": ["string", "null"]
          },
          "sequence": {
            "type": ["integer", "null"]
          },
          "eventHash": {
            "type": ["string", "null"]
          },
          "previousHash": {
            "type": ["string", "null"]
          },
          "canonicalPayloadHash": {
            "type": ["string", "null"]
          },
          "hashAlgorithm": {
            "type": ["string", "null"]
          },
          "eventTime": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "eventType": {
            "type": "string"
          },
          "actorType": {
            "type": "string"
          },
          "actorId": {
            "type": ["string", "null"]
          },
          "actorName": {
            "type": ["string", "null"]
          },
          "actorEmail": {
            "type": ["string", "null"]
          },
          "tokenId": {
            "type": ["string", "null"]
          },
          "purpose": {
            "type": ["string", "null"]
          },
          "jobId": {
            "type": ["string", "null"]
          },
          "scope": {
            "type": ["string", "null"]
          },
          "success": {
            "type": "boolean"
          },
          "errorCode": {
            "type": ["string", "null"]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "createdAt": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "LogsResponse": {
        "type": "object",
        "required": ["logs"],
        "properties": {
          "logs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccessLogEntry"
            }
          }
        }
      },
      "OkResponse": {
        "type": "object",
        "required": ["ok"],
        "properties": {
          "ok": {
            "type": "boolean"
          }
        }
      },
      "TransferSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "resourceType": { "type": "string", "enum": ["file", "url", "text"] },
          "fileName": { "type": "string" },
          "title": { "type": ["string", "null"] },
          "status": { "type": "string" },
          "recipients": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": { "type": "string" },
                "name": { "type": ["string", "null"] },
                "firstAccessedAt": { "type": ["string", "null"], "format": "date-time" },
                "downloadCount": { "type": "integer" }
              }
            }
          },
          "totalDownloadCount": { "type": "integer" },
          "maxDownloads": { "type": ["integer", "null"] },
          "expiresAt": { "type": ["string", "null"], "format": "date-time" },
          "purpose": { "type": ["string", "null"] },
          "jobId": { "type": ["string", "null"] },
          "sensitivityLevel": { "type": ["string", "null"] },
          "createdAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "TransferListResponse": {
        "type": "object",
        "required": ["transfers", "total"],
        "properties": {
          "transfers": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TransferSummary" }
          },
          "total": { "type": "integer" }
        }
      },
      "BulkRevokeInput": {
        "type": "object",
        "required": ["action", "transferIds"],
        "properties": {
          "action": { "type": "string", "enum": ["revoke"] },
          "transferIds": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 1,
            "maxItems": 20
          },
          "reason": { "type": ["string", "null"], "maxLength": 200 }
        }
      },
      "BulkRevokeResponse": {
        "type": "object",
        "required": ["ok", "revokedCount"],
        "properties": {
          "ok": { "type": "boolean" },
          "revokedCount": { "type": "integer" }
        }
      },
      "OrgUsageResponse": {
        "type": "object",
        "properties": {
          "plan": { "type": "string" },
          "limits": {
            "type": "object",
            "properties": {
              "maxMonthlyTransfers": { "type": ["integer", "null"] },
              "maxFileSizeMB": { "type": ["integer", "null"] },
              "maxRecipients": { "type": ["integer", "null"] },
              "maxRetentionDays": { "type": ["integer", "null"] }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "currentMonthTransfers": { "type": "integer" },
              "remainingMonthlyTransfers": { "type": ["integer", "null"] },
              "resetAt": { "type": ["string", "null"] }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "mcp": { "type": "boolean" },
              "agentTokens": { "type": "boolean" },
              "archive": { "type": "boolean" },
              "openNotification": { "type": "boolean" },
              "auditCsvExport": { "type": "boolean" }
            }
          }
        }
      },
      "AuditVerifyResponse": {
        "type": "object",
        "required": ["ok", "checked", "verified", "legacy", "failures"],
        "properties": {
          "ok": { "type": "boolean" },
          "checked": { "type": "integer" },
          "verified": { "type": "integer" },
          "legacy": { "type": "integer" },
          "failures": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "sequence": { "type": ["integer", "null"] },
                "reason": { "type": "string" }
              }
            }
          },
          "latestHash": { "type": ["string", "null"] },
          "summary": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": ["string", "null"]
          },
          "issues": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "status": {
            "type": ["string", "null"]
          },
          "email": {
            "type": ["string", "null"]
          },
          "maxFileSizeMB": {
            "type": ["integer", "null"]
          },
          "maxDays": {
            "type": ["integer", "null"]
          },
          "maxMonthlyTransfers": {
            "type": ["integer", "null"]
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid Agent Token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "agent_unauthorized": {
                "value": {
                  "error": "agent_unauthorized"
                }
              },
              "invalid_agent_token": {
                "value": {
                  "error": "invalid_agent_token"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Plan or policy restriction",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Transfer not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "not_found"
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "Schema validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "invalid_request",
              "issues": {}
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/commerce/orders": {
      "post": {
        "summary": "Create a governed commerce order",
        "operationId": "createCommerceOrder",
        "description": "Creates an eSIM purchase, eSIM top-up, or Threes booking order. A policy may return await_human_approval before any payment challenge is exposed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["sku", "purpose", "jobId", "payerAddress", "payerAccountType", "idempotencyKey", "payload"],
                "properties": {
                  "sku": { "type": "string", "enum": ["esim.purchase", "esim.topup", "threes.booking"] },
                  "purpose": { "type": "string", "minLength": 1, "maxLength": 120 },
                  "jobId": { "type": "string", "minLength": 1, "maxLength": 160 },
                  "payerAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
                  "payerAccountType": { "type": "string", "enum": ["eoa", "smart_account"] },
                  "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 160 },
                  "payload": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created or an existing idempotent order returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["orderId"],
                  "properties": {
                    "orderId": { "type": "string" },
                    "quoteId": { "type": "string" },
                    "approvalStatus": { "type": "string", "enum": ["not_required", "pending", "approved", "rejected", "expired"] },
                    "approvalRequestId": { "type": ["string", "null"] },
                    "nextAction": { "type": ["string", "null"], "enum": ["await_human_approval", "submit_payment", null] },
                    "payment": { "type": ["object", "null"], "additionalProperties": true }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/commerce/orders/{orderId}": {
      "get": {
        "summary": "Get canonical commerce order state",
        "operationId": "getCommerceOrder",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Approval, payment, risk, fulfillment, delivery, and provider state",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/commerce/orders/{orderId}/relay": {
      "post": {
        "summary": "Relay an approved EIP-3009 JPYC payment",
        "operationId": "relayCommercePayment",
        "description": "Rejected while Human Approval is pending, rejected, or expired.",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
        },
        "responses": {
          "200": { "description": "Relay submitted or previously submitted transaction returned" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/InvalidRequest" }
        }
      }
    },
    "/api/agent/transfers": {
      "get": {
        "summary": "List and search handoffs",
        "operationId": "listHandoffs",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keyword search across fileName, title, purpose, jobId, recipient emails" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft", "active", "revoked", "expired", "exhausted"] } },
          { "name": "resourceType", "in": "query", "schema": { "type": "string", "enum": ["file", "url", "text"] } },
          { "name": "recipientEmail", "in": "query", "schema": { "type": "string", "format": "email" } },
          { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD inclusive start" },
          { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD inclusive end" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "List of transfers matching filters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TransferListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "summary": "Create a file or URL handoff",
        "operationId": "createSecureHandoff",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferCreateInput"
              },
              "example": {
                "purpose": "contract_review",
                "jobId": "job_20260423_001",
                "aiProvider": "anthropic",
                "aiModel": "claude-sonnet-4",
                "aiClient": "claude_code",
                "workPassport": {
                  "reviewPolicy": "human_review",
                  "sourceReferences": [
                    {
                      "referenceId": "policy://legal/contract-release-v1",
                      "relationship": "policy"
                    }
                  ]
                },
                "transfer": {
                  "fileName": "nda.pdf",
                  "fileSizeBytes": 524288,
                  "mimeType": "application/pdf",
                  "recipients": [
                    {
                      "email": "legal@example.com",
                      "name": "Legal"
                    }
                  ],
                  "message": "Please review.",
                  "salt": "base64url-salt",
                  "ivFile": "base64url-file-iv",
                  "ivWrap": "base64url-wrap-iv",
                  "passcodeHash": "argon2id-passcode-hash",
                  "senderAccessiblePasscode": null,
                  "systemAccessiblePasscode": "kms-wrapped-passcode",
                  "expiresAt": "2026-04-30T12:00:00.000Z",
                  "maxDownloads": 3,
                  "passcodeDeliveryMode": "B",
                  "sensitivityLevel": "confidential"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer metadata. File handoffs include uploadUrl; URL handoffs return null for uploadUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/agent/transfers/{id}": {
      "get": {
        "summary": "Get handoff status",
        "operationId": "getSecureHandoffStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/finalize": {
      "post": {
        "summary": "Finalize uploaded handoff",
        "operationId": "finalizeSecureHandoff",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FinalizeTransferInput"
              },
              "example": {
                "shareUrl": "https://www.sealith.com/r/tr_xxxxxxxxxxxxxxxx"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer finalized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/revoke": {
      "post": {
        "summary": "Revoke handoff",
        "operationId": "revokeSecureHandoff",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/logs": {
      "get": {
        "summary": "Read audit logs",
        "operationId": "getSecureHandoffLogs",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit log entries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/receive": {
      "post": {
        "summary": "Receive a handoff as an AI recipient",
        "operationId": "receiveSecureHandoff",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["transferId", "passcode", "purpose"],
                "properties": {
                  "transferId": { "type": "string" },
                  "passcode": { "type": "string" },
                  "purpose": { "type": "string" },
                  "recipientEmail": { "type": "string", "format": "email" }
                }
              },
              "example": {
                "transferId": "tr_xxxxxxxxxxxxxxxx",
                "passcode": "A2b!C3d@E4f#G5h$",
                "purpose": "contract_review",
                "recipientEmail": "legal@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "For file and text handoffs, returns a signed download URL and crypto parameters. For URL handoffs, returns targetUrl metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "resourceType": { "type": "string", "enum": ["file", "text"] },
                        "signedUrl": { "type": "string" },
                        "fileName": { "type": "string" },
                        "fileSizeBytes": { "type": "integer" },
                        "mimeType": { "type": "string" },
                        "ciphertext": {
                          "type": "object",
                          "properties": {
                            "expiresIn": { "type": "integer" }
                          }
                        },
                        "crypto": {
                          "type": "object",
                          "properties": {
                            "salt": { "type": "string" },
                            "ivFile": { "type": "string" },
                            "ivWrap": { "type": "string" }
                          }
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "senderEmail": { "type": "string", "nullable": true },
                            "senderDisplayName": { "type": "string", "nullable": true },
                            "message": { "type": "string", "nullable": true }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "resourceType": { "type": "string", "enum": ["url"] },
                        "link": {
                          "type": "object",
                          "properties": {
                            "targetUrl": { "type": "string", "format": "uri" },
                            "targetDomain": { "type": "string" },
                            "title": { "type": "string" }
                          }
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "senderEmail": { "type": "string", "nullable": true },
                            "senderDisplayName": { "type": "string", "nullable": true },
                            "message": { "type": "string", "nullable": true }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/bulk": {
      "post": {
        "summary": "Bulk revoke handoffs",
        "operationId": "bulkRevokeHandoffs",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BulkRevokeInput" },
              "example": {
                "action": "revoke",
                "transferIds": ["tr_xxxxxxxxxxxxxxxx", "tr_yyyyyyyyyyyyyyyy"],
                "reason": "プロジェクト終了のため"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfers revoked",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BulkRevokeResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/org/usage": {
      "get": {
        "summary": "Get organization plan limits and usage",
        "operationId": "getOrgUsage",
        "responses": {
          "200": {
            "description": "Plan limits and current month usage statistics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrgUsageResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/agent/org/audit/verify": {
      "get": {
        "summary": "Verify audit log chain integrity",
        "operationId": "verifyAuditIntegrity",
        "responses": {
          "200": {
            "description": "SHA-256 hash chain verification result for all audit logs",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuditVerifyResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/agent/audit-context": {
      "post": {
        "summary": "Append audit context",
        "operationId": "appendAuditContext",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppendAuditContextInput"
              },
              "example": {
                "transferId": "tr_xxxxxxxxxxxxxxxx",
                "purpose": "contract_review",
                "jobId": "job_20260423_001",
                "note": "Key clauses extracted for human review.",
                "result": "needs_human_review",
                "metadata": {
                  "model": "gpt-5.4",
                  "reviewCount": 4
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit context appended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  }
}