Skip to content

0.5.15-todo.md

Latest commit

 

History

History
226 lines (181 loc) · 11.6 KB

0.5.15-todo.md

File metadata and controls

226 lines (181 loc) · 11.6 KB
Raw

Airlock 0.5.15 — TODO

Accepted 0.5.15 feature scope

The owner has accepted these packages into 0.5.15 implementation planning:

  1. Airlock-native virtual-key store and virtual-key management.
  2. Provider/configuration visibility or CRUD in the authenticated Admin/TUI control plane.
  3. A startup warning when a configured provider credential has no enabled provider alias.
  4. Secure host-console TUI administration for containerized Airlock.
  5. A single TUI admin console that can safely manage multiple Airlock instances, applying either instance-specific or explicitly approved system-wide configuration changes.

This releases the packages from scope-selection limbo; it does not waive their documented security, architecture, and HITL design gates. The initial provider slice remains read-only unless a separate durable configuration-owner decision approves CRUD. Claude Code subscription-preserving pass-through is out of scope for 0.5.15.

Fleet management begins as a control-plane design/research package. Each instance remains authoritative for its local runtime state and enforces its own Admin policy; the TUI must not gain raw SSH, Docker-socket, or systemd control. Whether a reviewed desired-state system may own instance or system-wide configuration is a separate architecture/HITL decision.

Accepted repair: typed threat-backoff response

Status: accepted 0.5.15 implementation scope.

Airlock's Fast Guardian threat gate currently raises a plain ValueError when it places a client in, or finds it already in, threat backoff. LiteLLM then serializes that Airlock decision as an untyped HTTP 500 (type: None, code: 500) instead of a rate limit. This is distinct from the provider circuit-breaker contract covered by UN-16: the provider is not necessarily rate-limiting the request.

Implement an Airlock-owned, typed threat-backoff exception and proxy handler. Both the request that creates the backoff and later requests rejected while it remains active must return an OpenAI-compatible HTTP 429 with an accurate Retry-After header. The body must use a stable Airlock-specific type/code and identify the source as threat_backoff, without disclosing heuristic details, client identity, or request content.

Acceptance criteria

  1. The Fast Guardian never raises a plain ValueError for threat backoff; it raises a typed Airlock rate-limit exception instead.
  2. The proxy maps that exception to HTTP 429, a whole-second Retry-After, and an OpenAI-shaped error body with stable type, code, and an airlock source of threat_backoff.
  3. The response distinguishes this local protection from both a provider 429 and an Airlock provider circuit-breaker quarantine, without relying on message parsing.
  4. Focused tests cover the initial block, an active-backoff retry, response headers/body, and preservation of existing provider and admission 429 contracts.
  5. Documentation describes the contract and tells clients to honor Retry-After; it must not characterize a threat-backoff response as a DeepSeek/provider rate limit.

Accepted scope: provider configuration in Admin and the TUI

Status: accepted 0.5.15 implementation-planning scope. The approved design baseline is read-only visibility; CRUD remains separately gated on durable configuration ownership, security review, and HITL.

Airlock now has explicit configured-provider aliases, but configuration remains a reviewed file-and-restart operation. Evaluate whether operators can safely inspect the provider/model list and perform provider configuration through the authenticated Admin control plane and the host-console TUI.

Design and implementation gates

  1. Inventory what the Admin API and TUI already expose about configured providers, aliases, stable bases, credential presence, health, and discovery. Verify source, freshness, authorization, and redaction.
  2. Decide separately whether the initial feature is read-only visibility or controlled configuration CRUD. Do not treat a TUI list as authorization to edit provider policy.
  3. If configuration is included, define durable configuration ownership, validation, atomic/restart semantics, rollback, audit, and secret-manager integration. Never expose API-key values or accept them through an insecure local UI field.
  4. Preserve the existing gateway, model-allowlist, routing-override, and provider-specific tool boundaries. Any provider/model change must remain explicit; discovery results must not become served aliases automatically.
  5. Obtain architecture/security review and HITL approval before implementation.

Accepted scope: configured-key / missing-provider-alias startup warning

Status: accepted 0.5.15 implementation-planning scope. Implementation must remain redacted, advisory, and no-network, subject to the documented security and architecture gates.

An operator can supply a provider API key while no model_list entry enables that provider. This is often an accidental incomplete deployment and should be visible without disclosing a secret, the key's value, or a raw provider error.

Design and implementation gates

  1. Define the precise condition from the resolved effective configuration: a recognized provider credential is present, but no explicitly configured model alias uses that provider. Do not warn for a configured alias whose upstream call later fails, and do not infer enabled models from discovery.
  2. Emit one bounded, redacted startup warning per provider through Airlock's normal structured logger. This should naturally reach console output, systemd journal, and container stdout/stderr according to deployment.
  3. Evaluate a source-labelled TUI/Admin status warning as a companion view, rather than a separate unstructured notification path. It must obey the existing Admin authorization and never reveal secret values.
  4. Specify suppression/deduplication, reload/restart behavior, provider-name allowlisting, and tests for native, systemd, and container launch contexts. Absence of a credential, a configured provider alias, and an unknown environment variable must not produce a warning.
  5. Obtain security review and HITL approval before implementation.

Accepted scope: host-console TUI administration of containerized Airlock

Status: accepted 0.5.15 implementation-planning scope. The separately authenticated control-plane design, topology, and credential lifecycle remain security/HITL gates; Docker-network reachability is not authorization.

The current Admin and FathomDB operational-read bridge deliberately trusts only same-host loopback traffic. That works when Airlock and airlock tui are both native processes. A host-console TUI connecting through a Docker-published port, or a TUI/operator client in a separate container on an Airlock Docker bridge, arrives at Airlock from a container-network address rather than 127.0.0.1. Neither must inherit loopback privilege. Treating a Docker bridge peer as loopback could let another container impersonate the local operator.

Design and implementation gates

Evaluate a separately authenticated control-plane path before accepting it into 0.5.15:

  1. Compare a TLS endpoint with scoped Admin credentials against a host-local trusted proxy that validates the operator before forwarding identity over an isolated channel. Define the supported deployment topology precisely.
  2. Preserve distinct authorization for read-only snapshots, operational history, and destructive controls; no broad re-use of the inference proxy credential.
  3. Establish listener, container-network, token rotation, audit, and failure semantics. A bridge-network source address alone is never sufficient proof of host-operator identity.
  4. Test both supported non-loopback control-plane topologies: a host-console TUI through a loopback-published Docker port, and an approved TUI/operator client in a separate bridged container. Cover rejected unauthenticated, wrong-scope, and other-container access, with no operational-data leak in error paths.
  5. Obtain security review and HITL approval before exposing Admin beyond direct process loopback.

Until then, the supported safe patterns are a native Airlock/TUI pair, or a TUI run inside the Airlock container. A container may publish its inference port to host loopback, but that alone does not grant either a host-console TUI or a bridged peer-container Admin privilege.

Evaluation candidate: Claude Code subscription-preserving gateway

Status: research complete and explicitly out of scope for 0.5.15. Retain the finding for a later release; do not implement or release it in this train.

Anthropic now documents a gateway flow in which Claude Code uses only ANTHROPIC_BASE_URL and retains its existing claude.ai subscription login. The gateway must transparently preserve Anthropic's evolving Messages protocol and OAuth capability. Airlock's present dogfooding route instead uses an Airlock credential and an upstream Anthropic API key, so it is API-billed.

Future-release decision requirements

Evaluate this as a design-only candidate before accepting it into 0.5.15:

  1. Reproduce the base-URL-only path without an Airlock gateway credential or upstream Anthropic API key; record only redacted structural evidence.
  2. Characterize protocol compatibility, especially streaming, evolving anthropic-beta/body capability pairs, error forwarding, and optional endpoints.
  3. Design a safe initial operating mode. It must not claim compatibility for request-mutating guardrails without proof that they preserve Claude Code capability semantics.
  4. Define credential/logging boundaries and obtain independent security and compatibility review.
  5. Bring the result to HITL: include a bounded pass-through slice, postpone, or reject.

Codex is not included in this candidate. Its documented subscription and alternative-provider paths do not currently establish an equivalent, supported self-hosted subscription-pass-through gateway protocol.

Research: Claude Code subscription gateway finding.

Deferred from 0.5.14: virtual-key management

Status: deferred from 0.5.15 and transferred to 0.6.0 on 2026-08-16. Delivery remains dependent on the 0.6.0 identity/keystore contract and its documented architecture/security/HITL gates; it is no longer 0.5.15 scope.

Carried draft scope

  • DFR-32: authenticated administrators manage masked virtual keys, create a key with a one-time secret reveal, and revoke a key through an explicit management seam.
  • DAC-32: tests must cover creation, one-time reveal, revocation, policy/spend display, unauthorized actions, and absence of key material from logs, UI snapshots, and subsequent reads.

Carried architecture constraints

  • Reconcile with 0.6.0 tenant-key/keystore and identity work before design.
  • Reuse an existing management/persistence seam or defer again; do not create a competing durable credential store.
  • Read views remain bounded, source-labeled, and off the inference hot path.

Required work before implementation

  1. Re-review the 0.6.0 keystore/identity contract and decide the ownership, persistence, authentication, authorization, and API boundaries.
  2. Ratify or revise DFR-32/DAC-32 as 0.5.15 requirements.
  3. In 0.6.0, allocate the B5 foundation before Slice 60, then write/update the management design and run the normal RED/GREEN/review/verification workflow.

Source evidence: 0.5.14 draft requirements and allocation, architecture review, and Slice 6 review.