{
  "openapi": "3.1.0",
  "info": {
    "title": "Noir OpenAI Guardrails API",
    "version": "1.0.0",
    "summary": "Verifiable AI safety infrastructure API for policy distribution, OPA control-plane workflows, governance evidence, and site data.",
    "description": "The Noir OpenAI Guardrails API exposes provider-style endpoints for AI safety evidence, policy distribution, OPA integration, and operational governance workflows.\n\nThe Scanner and Safety Certificate flows do not require the OpenAI SDK. Runtime enforcement is exposed through the Noir PDP/Bifrost policy distribution API and optional zero-SDK proxy integration."
  },
  "servers": [
    {
      "url": "https://openaiguardrails.org",
      "description": "Configured application origin"
    },
    {
      "url": "http://127.0.0.1:8787",
      "description": "Local API server"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Health and operational metadata."
    },
    {
      "name": "Registry",
      "description": "Registry and community data consumed by the public site."
    },
    {
      "name": "Policy Distribution",
      "description": "Noir PDP and Bifrost policy distribution endpoints."
    },
    {
      "name": "Policy Manager",
      "description": "Policy lifecycle, toggles, audit exports, and release actions."
    },
    {
      "name": "Noir Data Shapes",
      "description": "Canonical policy, audit, finding, and remediation payloads for downstream SIEM, GRC, and observability systems."
    },
    {
      "name": "OPA Control Plane",
      "description": "Import, simulate, export, and publish Rego/OPA policies."
    },
    {
      "name": "Content Operations",
      "description": "Authenticated blog submission and review workflows."
    },
    {
      "name": "Operations",
      "description": "Operational checks such as SMTP connectivity."
    },
    {
      "name": "Auth",
      "description": "Authentication callback support for the static frontend."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API service is available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/callback": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Redirect an auth provider callback back to the static account page",
        "operationId": "authCallback",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to /auth/account.html with the original query string."
          }
        }
      }
    },
    "/api/entries": {
      "get": {
        "tags": [
          "Registry"
        ],
        "summary": "List registry entries",
        "operationId": "listEntries",
        "responses": {
          "200": {
            "description": "Registry entry data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/discussions": {
      "get": {
        "tags": [
          "Registry"
        ],
        "summary": "List cached GitHub Discussions summary data",
        "operationId": "listDiscussions",
        "responses": {
          "200": {
            "description": "Discussions or graceful unavailable fallback.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscussionsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/policies": {
      "get": {
        "tags": [
          "Policy Distribution"
        ],
        "summary": "List public policy summaries",
        "operationId": "listPolicies",
        "responses": {
          "200": {
            "description": "Available PDP policies.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyListResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/v1/policy/{policyId}": {
      "get": {
        "tags": [
          "Policy Distribution"
        ],
        "summary": "Fetch a signed PDP/Bifrost policy payload",
        "description": "Returns the runtime policy package consumed by the Bifrost proxy. The example `prod-safety-alpha` policy intentionally represents a high-risk / Grade D workload so developers can test enforcement, headers, and certificate remediation flows without guessing a local policy ID.",
        "operationId": "getPolicyDistributionPayload",
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "default": "prod-safety-alpha"
            },
            "example": "prod-safety-alpha",
            "examples": {
              "gradeD": {
                "summary": "Grade D demo policy",
                "value": "prod-safety-alpha"
              }
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional ETag for cache revalidation."
          }
        ],
        "responses": {
          "200": {
            "description": "Signed policy payload for subscribers and Bifrost.",
            "headers": {
              "ETag": {
                "description": "Cache validator for policy revalidation.",
                "schema": {
                  "type": "string"
                },
                "example": "W/\"prod-safety-alpha-v2.4.1\""
              },
              "X-Noir-Policy-Version": {
                "description": "Active policy version injected by Noir/Bifrost for downstream logs and client-side verification.",
                "schema": {
                  "type": "string"
                },
                "example": "v2.4.1"
              },
              "X-Noir-Policy-Signature": {
                "description": "Detached integrity signature for the policy envelope.",
                "schema": {
                  "type": "string"
                },
                "example": "sha256-fnv-9a8b7c6d"
              },
              "X-Noir-Score": {
                "description": "Numeric governance score used by Safety Certificate and Bifrost telemetry. Lower scores indicate higher remediation urgency.",
                "schema": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "example": 64
              },
              "X-Noir-Grade": {
                "description": "Safety Certificate grade derived from policy score, vulnerabilities, and enforcement posture.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "A",
                    "B",
                    "C",
                    "D",
                    "F"
                  ]
                },
                "example": "D"
              },
              "X-Noir-Enforcement-Mode": {
                "description": "Runtime enforcement posture selected by Bifrost for this request.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "observe",
                    "warn",
                    "enforce",
                    "halt"
                  ]
                },
                "example": "enforce"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyDistributionPayload"
                }
              }
            }
          },
          "304": {
            "description": "Policy has not changed; subscriber can keep cache."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/policies/{policyId}/toggles": {
      "post": {
        "tags": [
          "Policy Manager"
        ],
        "summary": "Toggle a policy runtime control",
        "operationId": "togglePolicyControl",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "default": "prod-safety-alpha"
            },
            "example": "prod-safety-alpha",
            "examples": {
              "gradeD": {
                "summary": "Grade D demo policy",
                "value": "prod-safety-alpha"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "key",
                  "value"
                ],
                "properties": {
                  "key": {
                    "type": "string",
                    "example": "piiMasking"
                  },
                  "value": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Toggle accepted and broadcast invalidated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/policies/{policyId}/actions": {
      "post": {
        "tags": [
          "Policy Manager"
        ],
        "summary": "Perform a policy lifecycle action",
        "operationId": "runPolicyAction",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "default": "prod-safety-alpha"
            },
            "example": "prod-safety-alpha",
            "examples": {
              "gradeD": {
                "summary": "Grade D demo policy",
                "value": "prod-safety-alpha"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy action completed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/policies/{policyId}/audit-export": {
      "get": {
        "tags": [
          "Policy Manager",
          "Noir Data Shapes"
        ],
        "summary": "Export policy audit evidence",
        "description": "Exports the legal-evidence JSON payload behind the Safety Certificate and Remediation Roadmap. Security teams can ingest this document into Splunk, Datadog, GRC workflows, or evidence lockers.",
        "operationId": "exportPolicyAudit",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "policyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "default": "prod-safety-alpha"
            },
            "example": "prod-safety-alpha",
            "examples": {
              "gradeD": {
                "summary": "Grade D demo policy",
                "value": "prod-safety-alpha"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Noir audit evidence export used for Safety Certificate, Remediation Roadmap, and SIEM ingestion.",
            "headers": {
              "X-Noir-Score": {
                "description": "Numeric governance score represented in the exported certificate.",
                "schema": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "example": 64
              },
              "X-Noir-Grade": {
                "description": "Safety Certificate grade for this audit export.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "A",
                    "B",
                    "C",
                    "D",
                    "F"
                  ]
                },
                "example": "D"
              },
              "X-Noir-Policy-Version": {
                "description": "Policy version evaluated in this audit artifact.",
                "schema": {
                  "type": "string"
                },
                "example": "v2.4.1"
              },
              "X-Noir-Evidence-Hash": {
                "description": "SHA-256 digest of the canonicalized audit export.",
                "schema": {
                  "type": "string"
                },
                "example": "sha256-0d4f2b6d0e8c4b3a9f7b2a18e5a1c8d45acbeef8e4a7d18fd0e2f8f9b0c7d3e6"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditExport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/opa/imports": {
      "get": {
        "tags": [
          "OPA Control Plane"
        ],
        "summary": "List OPA imports",
        "operationId": "listOpaImports",
        "responses": {
          "200": {
            "description": "OPA import list and workflow metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpaImportsResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "tags": [
          "OPA Control Plane"
        ],
        "summary": "Import a Rego policy",
        "operationId": "importOpaPolicy",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OpaImportRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OPA policy imported and analyzed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/opa/imports/{importId}/simulate": {
      "post": {
        "tags": [
          "OPA Control Plane"
        ],
        "summary": "Simulate an imported OPA policy",
        "operationId": "simulateOpaImport",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "importId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulation result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/opa/imports/{importId}/export/{target}": {
      "get": {
        "tags": [
          "OPA Control Plane"
        ],
        "summary": "Export an imported OPA policy for a runtime target",
        "operationId": "exportOpaImport",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "importId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "target",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "bifrost",
                "wasm",
                "bundle",
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Target-specific export payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/opa/imports/{importId}/publish": {
      "post": {
        "tags": [
          "OPA Control Plane"
        ],
        "summary": "Publish imported OPA policy into Noir PDP/Bifrost distribution",
        "operationId": "publishOpaImport",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "importId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "policyId": {
                    "type": "string",
                    "default": "prod-safety-alpha",
                    "example": "prod-safety-alpha"
                  },
                  "target": {
                    "type": "string",
                    "example": "staging"
                  },
                  "approved": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OPA import published to PDP.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/blog/pending-posts": {
      "get": {
        "tags": [
          "Content Operations"
        ],
        "summary": "List pending blog posts",
        "operationId": "listPendingPosts",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Pending post queue.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Content Operations"
        ],
        "summary": "Submit a pending blog post",
        "operationId": "submitPendingPost",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Blog draft stored for review.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/ops/smtp-status": {
      "get": {
        "tags": [
          "Operations"
        ],
        "summary": "Verify SMTP configuration",
        "operationId": "getSmtpStatus",
        "responses": {
          "200": {
            "description": "SMTP connectivity check passed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "SMTP is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "SMTP verify failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Fetch this OpenAPI document",
        "operationId": "getOpenApiDocument",
        "responses": {
          "200": {
            "description": "OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/reference": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Open Scalar API Reference",
        "operationId": "getApiReference",
        "responses": {
          "200": {
            "description": "Interactive Scalar API Reference HTML.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Request validation failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid bearer token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated user lacks the required policy manager role.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "The current policy state blocks this operation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server-side operation failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": [
          "ok",
          "service",
          "ts"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "ts": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "DiscussionsResponse": {
        "type": "object",
        "properties": {
          "discussions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "unavailable": {
            "type": "boolean"
          },
          "cached": {
            "type": "boolean"
          },
          "owner": {
            "type": "string"
          },
          "repo": {
            "type": "string"
          },
          "discussionsUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "PolicyListResponse": {
        "type": "object",
        "required": [
          "ok",
          "policies"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "policies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PolicySummary"
            }
          }
        }
      },
      "PolicySummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "LIVE",
              "MAINTENANCE",
              "HALTED"
            ]
          },
          "activeVersion": {
            "type": "string"
          },
          "lastSync": {
            "type": "string",
            "format": "date-time"
          },
          "description": {
            "type": "string"
          },
          "toggles": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            }
          },
          "routing": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "PolicyDistributionPayload": {
        "type": "object",
        "required": [
          "id",
          "version",
          "status",
          "policy",
          "metadata",
          "signature"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "policy": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 64,
            "description": "Governance score surfaced as X-Noir-Score."
          },
          "grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ],
            "example": "D",
            "description": "Safety Certificate grade surfaced as X-Noir-Grade."
          },
          "enforcementMode": {
            "type": "string",
            "enum": [
              "observe",
              "warn",
              "enforce",
              "halt"
            ],
            "example": "enforce"
          },
          "bifrost_headers": {
            "$ref": "#/components/schemas/BifrostResponseHeaders"
          },
          "signature": {
            "type": "string",
            "example": "sha256-..."
          }
        }
      },
      "PolicyMutationResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "policy": {
            "$ref": "#/components/schemas/PolicySummary"
          },
          "propagation": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "PolicyActionRequest": {
        "type": "object",
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "save-draft",
              "save-version",
              "publish",
              "promote-production",
              "rollback",
              "archive"
            ]
          },
          "version": {
            "type": "string"
          },
          "policy": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "risk": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "target": {
            "type": "string",
            "example": "staging"
          }
        }
      },
      "BifrostResponseHeaders": {
        "type": "object",
        "description": "Custom response headers injected by Noir/Bifrost so applications can programmatically inspect runtime governance state.",
        "properties": {
          "X-Noir-Policy-Version": {
            "type": "string",
            "example": "v2.4.1",
            "description": "Active policy version used for the request."
          },
          "X-Noir-Policy-Signature": {
            "type": "string",
            "example": "sha256-fnv-9a8b7c6d",
            "description": "Detached signature for the policy envelope."
          },
          "X-Noir-Score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 64,
            "description": "Numeric governance score."
          },
          "X-Noir-Grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ],
            "example": "D",
            "description": "Safety Certificate grade."
          },
          "X-Noir-Enforcement-Mode": {
            "type": "string",
            "enum": [
              "observe",
              "warn",
              "enforce",
              "halt"
            ],
            "example": "enforce",
            "description": "Runtime enforcement posture."
          },
          "X-Noir-Evidence-Hash": {
            "type": "string",
            "example": "sha256-0d4f2b6d0e8c4b3a9f7b2a18e5a1c8d45acbeef8e4a7d18fd0e2f8f9b0c7d3e6",
            "description": "Canonical evidence hash for audit exports."
          }
        }
      },
      "AuditExport": {
        "type": "object",
        "description": "Legal evidence payload produced by the audit export endpoint and consumed by the Remediation Roadmap, Safety Certificate, and external SIEM/GRC systems.",
        "required": [
          "policy_id",
          "certificate_grade",
          "score",
          "findings",
          "remediation_steps",
          "sha256_hash"
        ],
        "properties": {
          "policy_id": {
            "type": "string",
            "example": "prod-safety-alpha"
          },
          "policy_version": {
            "type": "string",
            "example": "v2.4.1"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-09T20:30:00.000Z"
          },
          "environment": {
            "type": "string",
            "example": "production"
          },
          "certificate_grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ],
            "example": "D"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 64
          },
          "verdict": {
            "type": "string",
            "example": "Mandatory remediation required before release sign-off."
          },
          "bifrost_headers": {
            "$ref": "#/components/schemas/BifrostResponseHeaders"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditFinding"
            }
          },
          "remediation_steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RemediationStep"
            }
          },
          "sha256_hash": {
            "type": "string",
            "example": "sha256-0d4f2b6d0e8c4b3a9f7b2a18e5a1c8d45acbeef8e4a7d18fd0e2f8f9b0c7d3e6",
            "description": "SHA-256 hash of the canonicalized audit export JSON."
          },
          "evidence_chain": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EvidenceArtifact"
            }
          }
        },
        "example": {
          "policy_id": "prod-safety-alpha",
          "policy_version": "v2.4.1",
          "generated_at": "2026-05-09T20:30:00.000Z",
          "environment": "production",
          "certificate_grade": "D",
          "score": 64,
          "verdict": "Mandatory remediation required before release sign-off.",
          "bifrost_headers": {
            "X-Noir-Policy-Version": "v2.4.1",
            "X-Noir-Score": 64,
            "X-Noir-Grade": "D",
            "X-Noir-Enforcement-Mode": "enforce"
          },
          "findings": [
            {
              "id": "finding-prompt-injection-001",
              "severity": "critical",
              "title": "Prompt injection route can reach tool execution",
              "category": "prompt-injection",
              "status": "open",
              "evidence": "Scanner detected untrusted instruction flow into action execution."
            }
          ],
          "remediation_steps": [
            {
              "id": "remediate-001",
              "priority": "P0",
              "owner": "Security Engineering",
              "action": "Enable Bifrost strict enforcement and block tool calls on injected instructions.",
              "status": "required",
              "due_in_days": 7
            }
          ],
          "sha256_hash": "sha256-0d4f2b6d0e8c4b3a9f7b2a18e5a1c8d45acbeef8e4a7d18fd0e2f8f9b0c7d3e6"
        }
      },
      "AuditReport": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuditExport"
          }
        ],
        "description": "Alias used by Safety Certificate consumers for the same legal-evidence payload returned by AuditExport."
      },
      "AuditFinding": {
        "type": "object",
        "required": [
          "id",
          "severity",
          "title",
          "category",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "finding-prompt-injection-001"
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "low",
              "medium",
              "high",
              "critical"
            ],
            "example": "critical"
          },
          "title": {
            "type": "string",
            "example": "Prompt injection route can reach tool execution"
          },
          "category": {
            "type": "string",
            "example": "prompt-injection"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "accepted-risk",
              "remediated"
            ],
            "example": "open"
          },
          "evidence": {
            "type": "string",
            "example": "Scanner detected untrusted instruction flow into action execution."
          },
          "affected_component": {
            "type": "string",
            "example": "agent-tool-runtime"
          },
          "cwe": {
            "type": "string",
            "example": "CWE-1427"
          },
          "owasp_llm": {
            "type": "string",
            "example": "LLM01: Prompt Injection"
          }
        }
      },
      "RemediationStep": {
        "type": "object",
        "required": [
          "id",
          "priority",
          "action",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "remediate-001"
          },
          "priority": {
            "type": "string",
            "enum": [
              "P0",
              "P1",
              "P2",
              "P3"
            ],
            "example": "P0"
          },
          "owner": {
            "type": "string",
            "example": "Security Engineering"
          },
          "action": {
            "type": "string",
            "example": "Enable Bifrost strict enforcement and block tool calls on injected instructions."
          },
          "status": {
            "type": "string",
            "enum": [
              "required",
              "in-progress",
              "blocked",
              "complete"
            ],
            "example": "required"
          },
          "due_in_days": {
            "type": "integer",
            "minimum": 0,
            "example": 7
          },
          "verification": {
            "type": "string",
            "example": "Re-run Scanner and confirm Safety Certificate grade improves above C."
          }
        }
      },
      "EvidenceArtifact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "artifact-safety-certificate"
          },
          "type": {
            "type": "string",
            "example": "safety-certificate"
          },
          "sha256_hash": {
            "type": "string",
            "example": "sha256-5d41402abc4b2a76b9719d911017c592"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OpaImportsResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "positioning": {
            "type": "string"
          },
          "workflow": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "imports": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "auditLog": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "OpaImportRequest": {
        "type": "object",
        "required": [
          "source"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "sourceType": {
            "type": "string",
            "example": "rego-file"
          },
          "source": {
            "type": "string",
            "description": "Rego source text."
          }
        }
      }
    }
  }
}