# proxbox-api v0.0.27.post3

v0.0.27.post3

| Field |Value |
| --- | --- |
| Canonical URL | https://emersonfelipesp.com/proxbox-api/releases/v0.0.27.post3 |
| GitHub URL | https://github.com/emersonfelipesp/proxbox-api/releases/tag/v0.0.27.post3 |
| Tag | v0.0.27.post3 |
| State | latest |
| Author | emersonfelipesp |
| Created | 2026-10-15 18:27 UTC |
| Published | 2026-10-15 19:01 UTC |
| Target | main |
| Synced | 2026-10-16 04:10 UTC |
| Assets | 0 |

## Release notes

## Summary

This post-release hardens credential and network boundaries, adds endpoint-safe
device ownership and run-correlated synchronization completion, and improves
readiness recovery when NetBox settings permissions are missing. It also adopts
FastAPI 0.143.0 telemetry controls, recognizes NetBox 4.7 as a supported runtime
window, and separates standalone Proxmox mock package publication from protected
manual image publication. It adds no database migrations.

## Release identity

| Component | Release or contract |
| --- | --- |
| proxbox-api | `0.0.27.post3` |
| Paired NetBox plugin | `netbox-proxbox 0.0.29.post5` |
| Proxmox SDK | `proxmox-sdk 0.0.15` |
| NetBox SDK | `netbox-sdk 0.0.13` |
| Python | 3.12 and 3.13 |
| Database migration | None |

## Security and network boundaries

- **Committed endpoints alone become shared SSRF authorities.** NetBox and
  Proxmox endpoint hosts remain request-scoped until their database transaction
  commits. A rejected or rolled-back endpoint can no longer leave its host in
  the process-wide allow cache.
- **SSH uses validated destinations and the credentialed connection's pinned
  key.** Terminal creation, host-key scanning, and fixed SSH commands apply the
  shared SSRF policy and connect only to validated addresses. TCP refusal or
  timeout may advance through a bounded ordered address list, but a host-key or
  authentication failure never falls through to another address. Ambient known
  hosts, SSH client configuration, agents, default keys, GSS, host-based and
  keyboard-interactive authentication, PKCS#11, X.509 trust, and client
  certificates are disabled. The negotiated server key must match the stored
  pin before a PTY or command is opened. IPv6 address family, flow information,
  and interface scope are retained through connection.
- **Firecracker provisioning has a stronger caller and transport boundary.**
  Both provisioning routes require a nonblank `X-Proxbox-Actor`. Connections
  use only validated addresses, preserve the canonical hostname for HTTP Host,
  HTTPS SNI, and certificate verification, retain scoped IPv6 identity, and use
  bounded fallback only for connection refusal and timeout. Upstream bodies and
  malformed response values are replaced with fixed client errors; the
  non-streaming route returns a sanitized HTTP 502, including when a custom
  transport fails while reading the response.
- **Settings reads fail closed without leaking credentials.** Requests carrying
  the NetBox token no longer follow redirects and reject bodies larger than
  4 MiB. An authorization denial retains the last good policy, or uses strict
  SSRF defaults on a cold start. `/health` reports the missing
  `view_proxboxpluginsettings` permission and performs rate-limited refreshes so
  readiness can recover after the permission is granted without a restart.
- **The API-key bootstrap claim remains one-shot.** Unauthenticated
  `POST /auth/register-key` is available only before the first durable key
  registration and cannot reopen after key history exists.

## Credential encryption

- **Plugin-key circular dependencies are rejected.** Creating a NetBox endpoint
  or changing its credentials returns HTTP 409 when the actual encryption
  material is the NetBox plugin key, including when that authority is recovered
  during the request. Unchanged pushes remain no-ops, and connection-only
  changes retain the existing credential ciphertext.
- **Key replacement and credential writes are coordinated.** Every persistent
  credential write captures the durable key generation and local-file identity,
  checks them again at encryption, and conditionally fences the ciphertext
  commit. A stale writer returns HTTP 409 without storing ciphertext. Key
  replacement performs its blocking SQLite work off the event loop; contention
  returns a secret-free HTTP 503 with `Retry-After`.
- **Local key replacement is visible across workers.** Cached keys are checked
  against the key-file identity on every use, and resolved material is checked
  again before cache publication. Atomic publication fsyncs the key file and
  parent directory before clearing the durable pending fence. A failed
  replacement leaves writes blocked until a successful retry, and lock
  contention cannot clear an inherited fence. A retried deletion also proves
  the directory update durable when an earlier attempt already removed the
  file.

## Synchronization and compatibility

- **Device ownership is endpoint-scoped.** The typed device sync-state records
  `proxmox_endpoint_raw_id`. A missing value remains a legacy unclaimed record,
  while a record owned by another endpoint cannot be adopted, patched, or
  restamped. Atomic NULL-to-endpoint claims use the paired plugin's row lock and
  HTTP 409 `endpoint_ownership_conflict` response, and the backend reads every
  successful claim back before proceeding. The single-device path now also
  refuses a rendered name already owned by another device before any write.
- **WebSocket runs can be correlated through completion.** Clients may send a
  bounded JSON command envelope with a `run_id`. Every progress, error, and
  terminal frame carries that identifier, and a full update ends with one
  aggregate result containing both stage outcomes. Nonzero failure counts from
  partially completed required stages reach the terminal result. Legacy
  bare-string commands and response frames remain unchanged.
- **NetBox 4.7 is in the supported runtime window.** Live 4.7.x deployments no
  longer receive the outside-window warning. The generated schema target and
  pinned `netbox-sdk 0.0.13` contract are unchanged.
- **Large synchronization orchestrators were decomposed without a contract
  change.** Full-update and virtual-machine phases now share bounded stage
  runners while retaining request ordering, events, failure isolation,
  cancellation ownership, and public signatures.

The backend and `netbox-proxbox 0.0.29.post5` may be upgraded in either order.
During a mixed-version rollout, existing synchronization contracts remain
available, but atomic device ownership claims and run-correlated WebSocket
completion require both paired releases.

| `netbox-proxbox` behavior | Device ownership behavior |
| --- | --- |
| `0.0.29.post5` with the field and atomic HTTP 409 contract | Supported; exactly one competing endpoint claim is authorized. |
| Older release that omits the field | Supported legacy mode; ownership is unclaimed and unverifiable, so synchronization continues without endpoint enforcement. |
| Version exposing the field without atomic conflict enforcement | Unsupported mismatch; read-back verification narrows the race, but a later writer can overwrite a completed claim. |

## Runtime and release operations

- **Interactive execution remains process-pinned.** `rpc_only` is the default
  and denies unrestricted SSH tickets, terminal consumption, console
  capabilities, and actorless synchronization WebSockets before effectful
  dependencies run. Explicit `legacy` mode retains authentication, endpoint
  restrictions, host-key pins, private console authentication, owned resources,
  cancellation-safe cleanup, and fail-closed checks after blocked operations.
  The authenticated status endpoint reports the local policy and deployment
  generation; local readiness does not certify a fleet cutover or complete RPC
  coverage.
- **Native telemetry is explicit.** FastAPI is pinned to 0.143.0. Automatic OTLP
  export now requires `FASTAPI_OTEL_AUTO_CONFIGURE=true` or the equivalent
  explicit application setting; an exporter endpoint alone does not enable it.
- **Standalone mock releases are package-first.** The published wheel is
  validated from an isolated environment with detached behavioral tests,
  package-index collisions fail closed, and image inputs are bound to immutable
  bases and offline dependency digests. Multi-platform image publication moved
  to a separate protected manual workflow that assembles only the current run's
  captured digests.

## Upgrade notes

1. Upgrade proxbox-api and `netbox-proxbox 0.0.29.post5` in either order, then
   restart every backend worker after installing the exact package or container.
2. Grant the NetBox service account `view_proxboxpluginsettings`. Confirm that
   `/health` recovers after the permission refresh.
3. Before changing the authenticated NetBox endpoint credentials, configure an
   independent `PROXBOX_ENCRYPTION_KEY` or local key file and confirm that
   `GET /admin/encryption/status` reports `env` or `local`.
4. Verify every SSH target remains permitted by the registered-endpoint or
   operator SSRF policy and that its stored host-key fingerprint matches the key
   presented on the credential-bearing connection.
5. Run one node synchronization and one correlated full update. Confirm that
   device ownership is stamped to the selected endpoint and that the final
   WebSocket aggregate identifies the requested run.

## Known limitations and operator actions

- Private or otherwise non-global SSH and Firecracker destinations are refused
  unless a registered endpoint or explicit operator SSRF policy permits them.
  Address fallback covers TCP reachability only; it never bypasses a host-key,
  TLS, HTTP protocol, or authentication failure.
- Key replacement still returns HTTP 409 while encrypted credentials depend on
  the current key. When all workers share the same SQLite database and local key
  file, a maintenance window that blocks endpoint changes is no longer needed.
  Restart every worker if shared-file visibility and cache revalidation cannot
  be guaranteed.
- A missing `view_proxboxpluginsettings` grant keeps cold-start readiness at
  HTTP 503 and applies strict SSRF defaults until a refresh succeeds.
- `rpc_only` local readiness is not evidence that companion services, callers,
  or the fleet are ready for cutover. Validate the shared generation and paired
  capabilities before disabling legacy compatibility.
- Standalone Proxmox mock image publication is no longer automatic after package
  publication. An authorized operator must run the protected manual image lane
  with qualified immutable inputs.

## Assets

No binary assets attached.

Source archives:

| Format |URL |
| --- | --- |
| zip | https://api.github.com/repos/emersonfelipesp/proxbox-api/zipball/v0.0.27.post3 |
| tar.gz | https://api.github.com/repos/emersonfelipesp/proxbox-api/tarball/v0.0.27.post3 |