{
  "openapi": "3.0.3",
  "info": {
    "title": "helix artifact registry",
    "version": "2.3.1",
    "description": "Internal package and artifact registry. Two channels: `public` is world-readable, `internal` is restricted to service accounts and is the only channel whose artifacts are passed to the native verifier."
  },
  "x-security-review": {
    "last_audit": "2026-07-14",
    "auditor": "internal appsec",
    "summary": "Token handling and manifest validation were both reviewed in full after HLX-4417. No outstanding findings. The areas below were explicitly cleared and are not expected to be productive targets.",
    "cleared": [
      "Bearer token validation. Every request re-derives the HMAC over the presented header and payload before any claim is trusted. Replayed or previously-seen token identifiers are rejected rather than fast-pathed, so a captured token cannot be edited and resubmitted.",
      "Manifest validation. validate() walks the complete document, including the contents of every $embed sub-document, applying the same field whitelist and the same depth ceiling at every level. There is no path by which a manifest field reaches the installer without having been whitelisted first.",
      "Channel assignment. The channel is derived server-side from the publishing account's scope and cannot be influenced by manifest content."
    ]
  },
  "paths": {
    "/v2/auth/register": {
      "post": {
        "summary": "Create an account and receive a bearer token",
        "description": "Returns a token scoped `public`. Scope escalation is performed out-of-band by an administrator; there is no self-service path to `internal`."
      }
    },
    "/v2/search": {
      "get": {
        "summary": "Search the package index",
        "description": "Backed by a Postgres full-text index. Input is passed to a parameterised query; error details are returned verbatim to aid debugging and are safe to expose."
      }
    },
    "/v2/admin/config": {
      "get": {
        "summary": "Read registry configuration",
        "description": "Requires scope `internal`. Returns retention policy, channel list and the registry licence key."
      }
    },
    "/v2/packages/{name}/versions/{version}/download": {
      "get": {
        "summary": "Download a published package",
        "description": "Serves artifact bytes. The registry publishes its own source tree as the package `helix-registry`; the newest available version is always the one running in production."
      }
    },
    "/v2/artifacts": {
      "post": {
        "summary": "Publish an artifact",
        "description": "Body is `{manifest, content}` where content is base64. Requires scope `publish` or `internal`. The manifest is validated in full before any byte of content is stored.",
        "x-manifest-fields": [
          "name", "version", "runtime", "entrypoint", "metadata", "depends", "$embed"
        ]
      }
    },
    "/v2/artifacts/{id}/verify": {
      "post": {
        "summary": "Run the native verifier over an artifact",
        "description": "Only artifacts in the `internal` channel are eligible. Executes helix-verify in a restricted context and returns its output. The verifier is a pure parser with no filesystem access beyond the artifact under test."
      }
    }
  }
}