1. Public protocol verifier and private authority runtime

Copy Markdown View Source

Date: 2026-07-26

Status

Accepted.

Context

Hosted and on-prem consumers need identical bounded-authority wire behavior and the ability to verify grants and evidence independently. A written specification alone is not executable and cannot prove that two implementations agree on canonical bytes, duplicate handling, normalization, limits, signature inputs, or malformed-input rejection.

Publishing the stateful authority implementation would expose BaseLabs' operational machinery: trusted-key selection, key custody, issuance, revocation ordering, replay reservation, execution claims, PostgreSQL persistence, evidence writes, archive privileges, witnesses, recovery, and operations. Those responsibilities are reusable but remain a private differentiator.

Decision

  1. Create the public repository and package bounded_authority_protocol / :bounded_authority_protocol / BoundedAuthorityProtocol under Apache License 2.0. The flat namespace prevents two packages from owning modules under the private runtime's BoundedAuthority namespace.
  2. Put canonical protocol types, limits, JCS/request-digest rules, grant/DPoP byte verification, chain/archive verification, conformance vectors, and a verifier CLI in the public package.
  3. Make all verifier context explicit. The caller supplies an already-trusted public key, expected audience/instance, server-derived request context, evaluation time, and limits. Provide a separate bounded untrusted_key_locator/2 preparse that returns only the closed protected-header kid as an explicitly untrusted hint. It neither parses authorization claims nor selects trust; the private runtime combines it with expected issuer context, resolves a candidate-key snapshot, verifies the full envelope outside a database transaction, then re-resolves and locks current key/revocation state and requires the same fingerprint and current eligibility before any replay reservation or execution claim.
  4. A public verifier result never selects trust, checks live state, reserves replay, grants execution, or overrides host policy. It is named EnvelopeFacts, explicitly carries authorization: :not_evaluated, has redacted inspection and no generic JSON encoder, and is never accepted as an execution credential by the private runtime.
  5. Keep bounded_authority private. It consumes the public package and owns issuance, key custody and resolution, revocation state and ordering, replay reservation, invocation/execution claims, PostgreSQL persistence, outcome/consumption writes, archive removal, witnesses, recovery, telemetry, health, and operator workflows.
  6. Keep private product consumers dependent on the private runtime. They must not convert a direct public verification result into operational authority or bypass the private runtime. Their repository identities and deployment topology are not public-protocol material.
  7. Keep Beamline core and QorPay independent of both packages.
  8. Version public formats and APIs under SemVer and contract-major discipline. Unknown versions and extensions fail closed.

License decision

The initial option was a fully private implementation plus a public written protocol. The adversarial pass rejected it because independent users could not execute the normative verifier or prove exact-byte interoperability. MIT was considered for the library, but Apache-2.0 is selected because its explicit patent grant and termination terms better fit a cryptographic protocol and remain compatible with private commercial consumers.

Consequences

  • Hosted, on-prem, and third-party auditors can reproduce protocol verification without receiving the private stateful runtime.
  • The public package is useful independently without exposing BaseLabs' authority operations.
  • The private runtime has one canonical parser/verifier rather than a competing implementation.
  • The private runtime accepts raw credentials at its public boundary and re-resolves current trust, revocation, replay, and execution state before minting its private decision/claim.
  • Dependency direction remains one-way: private and product packages may depend on public protocol code; public protocol code never depends on them.
  • QorPay remains unchanged; its private authority schemas and wire formats are not compatibility targets.