{
  "openapi": "3.1.0",
  "info": {
    "title": "i2x source-read consent API",
    "version": "1.4.0",
    "description": "One-use memory-only source-read permission. These routes do not fetch source, execute code or authorize persistent storage."
  },
  "security": [
    {
      "customerSession": []
    }
  ],
  "paths": {
    "/api/runs/{runId}/source-consents": {
      "parameters": [
        {
          "name": "runId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Inspect redacted consent history",
        "responses": {
          "200": {
            "description": "Consent history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "400": {
            "description": "Malformed fields, query parameters or requested lifetime"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Current human owner/maintainer step-up authority required"
          },
          "404": {
            "description": "Run or consent not visible"
          },
          "409": {
            "description": "Scope changed, expired or retained history is inconsistent"
          }
        }
      },
      "post": {
        "summary": "Grant one short-lived source-read consent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConsent"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created or replayed consent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed fields, query parameters or requested lifetime"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Current human owner/maintainer step-up authority required"
          },
          "404": {
            "description": "Run or consent not visible"
          },
          "409": {
            "description": "Scope changed, expired or retained history is inconsistent"
          }
        }
      }
    },
    "/api/runs/{runId}/source-consents/{consentDigest}/revoke": {
      "parameters": [
        {
          "name": "runId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "consentDigest",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      ],
      "post": {
        "summary": "Revoke consent without starting source work",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "maxProperties": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked consent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed fields, query parameters or requested lifetime"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Current human owner/maintainer step-up authority required"
          },
          "404": {
            "description": "Run or consent not visible"
          },
          "409": {
            "description": "Scope changed, expired or retained history is inconsistent"
          }
        }
      }
    },
    "/api/runs/{runId}/source-consents/{consentDigest}/read": {
      "parameters": [
        {
          "in": "path",
          "name": "runId",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "in": "path",
          "name": "consentDigest",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      ],
      "post": {
        "operationId": "readConsentedSource",
        "description": "Read the exact approved snapshot into bounded volatile memory. No source bytes are returned. A repeated request can reuse the same live memory entry without another provider read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "maxProperties": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Source-free read receipt and memory expiry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "consent",
                    "transfer"
                  ],
                  "properties": {
                    "consent": {
                      "$ref": "#/components/schemas/Consent"
                    },
                    "transfer": {
                      "$ref": "#/components/schemas/MemoryTransfer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Request refused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "customerSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authenticated i2x session. Mutations require a current human owner or maintainer browser session with fresh step-up authentication."
      }
    },
    "schemas": {
      "Consent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "consentDigest",
          "runId",
          "projectId",
          "repositoryId",
          "commitSha",
          "sourceDigest",
          "authorizedBy",
          "issuedAtEpochSeconds",
          "expiresAtEpochSeconds",
          "status",
          "revoked",
          "expired",
          "consumed",
          "snapshotDigest",
          "scope",
          "executionAuthorized",
          "persistentStorageAuthorized",
          "snapshot",
          "snapshotEvidence",
          "readAvailable",
          "memorySnapshot"
        ],
        "properties": {
          "consentDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "runId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "repositoryId": {
            "type": "string"
          },
          "commitSha": {
            "type": "string",
            "pattern": "^[a-f0-9]{40}$"
          },
          "sourceDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "authorizedBy": {
            "type": "string"
          },
          "issuedAtEpochSeconds": {
            "type": "integer"
          },
          "expiresAtEpochSeconds": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "authorized",
              "started",
              "completed",
              "failed"
            ]
          },
          "revoked": {
            "type": "boolean"
          },
          "expired": {
            "type": "boolean"
          },
          "consumed": {
            "type": "boolean"
          },
          "snapshotDigest": {
            "type": [
              "string",
              "null"
            ]
          },
          "scope": {
            "const": "memory_only_source_read"
          },
          "executionAuthorized": {
            "const": false
          },
          "persistentStorageAuthorized": {
            "const": false
          },
          "snapshot": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SourceSnapshot"
              }
            ]
          },
          "snapshotEvidence": {
            "enum": [
              "none",
              "digest_only",
              "runtime_observation"
            ]
          },
          "readAvailable": {
            "type": "boolean"
          },
          "memorySnapshot": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MemoryTransfer"
              }
            ]
          }
        }
      },
      "CreateConsent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commitSha",
          "ttlSeconds",
          "idempotencyKey",
          "acknowledgement"
        ],
        "properties": {
          "commitSha": {
            "type": "string",
            "pattern": "^[a-f0-9]{40}$"
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 300
          },
          "idempotencyKey": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{16,128}$"
          },
          "acknowledgement": {
            "const": "ALLOW_I2X_TO_READ_THIS_RUN_SOURCE"
          }
        }
      },
      "ConsentResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "consent"
        ],
        "properties": {
          "consent": {
            "$ref": "#/components/schemas/Consent"
          }
        }
      },
      "History": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "runId",
          "consents",
          "sourceFetchEndpointAvailable",
          "executionAuthorized",
          "persistentStorageAuthorized",
          "projectionDigest",
          "grantContext"
        ],
        "properties": {
          "version": {
            "const": "i2x-source-consents/1.4.0"
          },
          "runId": {
            "type": "string"
          },
          "consents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Consent"
            }
          },
          "sourceFetchEndpointAvailable": {
            "type": "boolean",
            "description": "True only when the bounded source-transfer session is configured."
          },
          "executionAuthorized": {
            "const": false
          },
          "persistentStorageAuthorized": {
            "const": false
          },
          "projectionDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "grantContext": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "canGrant",
              "canRevoke",
              "reasonCode",
              "maximumLifetimeSeconds",
              "repositoryName",
              "repositoryId",
              "sourceDigest"
            ],
            "properties": {
              "canGrant": {
                "type": "boolean"
              },
              "canRevoke": {
                "type": "boolean"
              },
              "reasonCode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "maximumLifetimeSeconds": {
                "type": "integer",
                "minimum": 0,
                "maximum": 300
              },
              "repositoryName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "repositoryId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceDigest": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "SourceSnapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "repositoryId",
          "commitSha",
          "treeSha",
          "sourceDigest",
          "packageDigest",
          "fileCount",
          "totalBytes",
          "excluded",
          "credentialReturned",
          "sourceWrittenToDisk",
          "productionAdmissionAllowed",
          "effectAuthority",
          "snapshotDigest"
        ],
        "properties": {
          "version": {
            "const": "i2x-github-source-snapshot/1.0.0"
          },
          "repositoryId": {
            "type": "string"
          },
          "commitSha": {
            "type": "string",
            "pattern": "^[a-f0-9]{40}$"
          },
          "treeSha": {
            "type": "string",
            "pattern": "^[a-f0-9]{40}$"
          },
          "sourceDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "packageDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "fileCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "totalBytes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 7340032
          },
          "excluded": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "enum": [
                ".git",
                "node_modules",
                ".next",
                "dist",
                "build",
                "coverage",
                "symlinks",
                "secret-like filenames"
              ]
            }
          },
          "credentialReturned": {
            "const": false
          },
          "sourceWrittenToDisk": {
            "const": false
          },
          "productionAdmissionAllowed": {
            "const": false
          },
          "effectAuthority": {
            "const": "none"
          },
          "snapshotDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      },
      "MemoryTransfer": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "runId",
          "consentDigest",
          "snapshotDigest",
          "expiresAtEpochSeconds",
          "sourcePersistence",
          "executionAuthorized"
        ],
        "properties": {
          "runId": {
            "type": "string"
          },
          "consentDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "snapshotDigest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "expiresAtEpochSeconds": {
            "type": "integer"
          },
          "sourcePersistence": {
            "const": "memory_only"
          },
          "executionAuthorized": {
            "const": false
          }
        }
      }
    }
  }
}
