Manage add, rotate, and retire lifecycle for Age-backed Pi providers #34

New issue

Closed

opened 2026-08-20 16:42:26 +01:00 by allod-agent · 0 comments

allod-agent commented

2026-08-20 16:42:26 +01:00

Member

Architecture

Provider configuration and credential identity remain separate sources of truth:

profiles owns endpoint, protocol, provider ID, and model metadata;
secrets owns credential aliases, target VMs, provider-to-credential selection, Age recipients, ciphertext, and credential lifecycle metadata;
inventory owns the Nexus workspace repository set;
archetypes owns generic runtime delivery, Pi command-backed authentication, managed-entry ownership, and add/update/remove reconciliation;
Nexus owns the human-operated lifecycle command;
deploy pins and verifies compatible public revisions.

The public profiles and secrets templates remain empty and synthetic. Live URLs, identifiers, target selections, recipient keys, and ciphertext stay in private deployment data.

Pi receives an api_key auth entry backed by a fixed helper command. The helper reads a user-owned, mode-0600 Age runtime credential and returns it only to Pi. The token is not embedded in auth.json, models.json, generated code, argv, environment variables, persistent plaintext, or the Nix store. This protects repository and build storage; it does not hide the runtime token from agents sharing Pi's Unix account.

Lifecycle

The Nexus command provides:

add: validate provider metadata and targets, accept a new token through hidden input when needed, and install non-secret registry data plus ciphertext;
retarget: replace one credential's complete VM target set and re-encrypt a re-entered credential to the new Age recipients;
rotate: resolve the provider's globally unique, possibly shared credential, report every affected provider/target, replace only its ciphertext, and distinguish overlap from in-place rotation;
retire: remove the provider and its credential references, deleting the current ciphertext only when no declared consumer remains;
recover: restore only transaction-recorded paths from unchanged pre-run Git heads after interruption, or preserve evidence and refuse when safe automatic recovery cannot be proven.

Retirement also reconciles the rebuilt VM: remove only previously managed auth/model entries and stale managed credential links while preserving unrelated IDs and operator-replaced links. An empty desired provider set still runs cleanup. Removing ciphertext from the current tree neither erases encrypted Git history nor revokes a provider-side token.

Provider-side issuance and revocation are service-specific human steps. Pi caches a command-backed credential for the lifetime of a process, so overlap rotation requires a rebuild, a real request from a fresh Pi process, closure of pre-rebuild Pi sessions, and only then remote revocation of the previous token. The generic tool must not claim it performed remote revocation.

Safety and validation

The token has no flag, path input, environment export, or display command. Hidden input is validated as a single RFC 6750 bearer token and piped directly to Age. Only ciphertext and non-secret JSON enter mode-0700 tmpfs staging. A durable non-secret journal records the operation, exact paths, pre-run heads, and path existence before mutation. The command never commits, pushes, rebuilds, probes an integration-specific endpoint, or revokes remotely.

Synthetic checks cover schema and recipient derivation, global provider-to-credential uniqueness, exact composition-source binding, Nexus host workspace projection, install/update/removal reconciliation, retargeting, shared-credential rotation and partial retirement, last-provider cleanup, rebuild/reboot-shaped reactivation, missing-then-present secrets, Pi-compatible concurrent writers, stale versus fresh Pi processes, Nix garbage collection, plaintext absence, dry-run, ordinary rollback, and interruption recovery. A separate private rollout plan owns migration, live inference, host rebuilds, and provider-specific revocation.

Scope

In scope: public profiles/secrets interfaces, inventory workspace declaration, the archetypes libvirt consumer and reconciler, the Nexus lifecycle command, deploy composition, and synthetic lifecycle witnesses.

Out of scope: live provider data in public history; automatic migration of an existing private integration; integration-specific Pi extensions; provider-side issuance/revocation; OAuth, arbitrary headers, HTTP endpoints, privacy/service VMs, microVM delivery, or hiding credentials from same-user agents inside the target VM.

Let the owner manage custom OpenAI-compatible Pi providers from Nexus while keeping bearer credentials Age-encrypted at rest and reconciling additions, rotations, retargeting, and removals on rebuilt libvirt dev VMs. ### Architecture Provider configuration and credential identity remain separate sources of truth: - profiles owns endpoint, protocol, provider ID, and model metadata; - secrets owns credential aliases, target VMs, provider-to-credential selection, Age recipients, ciphertext, and credential lifecycle metadata; - inventory owns the Nexus workspace repository set; - archetypes owns generic runtime delivery, Pi command-backed authentication, managed-entry ownership, and add/update/remove reconciliation; - Nexus owns the human-operated lifecycle command; - deploy pins and verifies compatible public revisions. The public profiles and secrets templates remain empty and synthetic. Live URLs, identifiers, target selections, recipient keys, and ciphertext stay in private deployment data. Pi receives an `api_key` auth entry backed by a fixed helper command. The helper reads a user-owned, mode-0600 Age runtime credential and returns it only to Pi. The token is not embedded in `auth.json`, `models.json`, generated code, argv, environment variables, persistent plaintext, or the Nix store. This protects repository and build storage; it does not hide the runtime token from agents sharing Pi's Unix account. ### Lifecycle The Nexus command provides: - `add`: validate provider metadata and targets, accept a new token through hidden input when needed, and install non-secret registry data plus ciphertext; - `retarget`: replace one credential's complete VM target set and re-encrypt a re-entered credential to the new Age recipients; - `rotate`: resolve the provider's globally unique, possibly shared credential, report every affected provider/target, replace only its ciphertext, and distinguish overlap from in-place rotation; - `retire`: remove the provider and its credential references, deleting the current ciphertext only when no declared consumer remains; - `recover`: restore only transaction-recorded paths from unchanged pre-run Git heads after interruption, or preserve evidence and refuse when safe automatic recovery cannot be proven. Retirement also reconciles the rebuilt VM: remove only previously managed auth/model entries and stale managed credential links while preserving unrelated IDs and operator-replaced links. An empty desired provider set still runs cleanup. Removing ciphertext from the current tree neither erases encrypted Git history nor revokes a provider-side token. Provider-side issuance and revocation are service-specific human steps. Pi caches a command-backed credential for the lifetime of a process, so overlap rotation requires a rebuild, a real request from a fresh Pi process, closure of pre-rebuild Pi sessions, and only then remote revocation of the previous token. The generic tool must not claim it performed remote revocation. ### Safety and validation The token has no flag, path input, environment export, or display command. Hidden input is validated as a single RFC 6750 bearer token and piped directly to Age. Only ciphertext and non-secret JSON enter mode-0700 tmpfs staging. A durable non-secret journal records the operation, exact paths, pre-run heads, and path existence before mutation. The command never commits, pushes, rebuilds, probes an integration-specific endpoint, or revokes remotely. Synthetic checks cover schema and recipient derivation, global provider-to-credential uniqueness, exact composition-source binding, Nexus host workspace projection, install/update/removal reconciliation, retargeting, shared-credential rotation and partial retirement, last-provider cleanup, rebuild/reboot-shaped reactivation, missing-then-present secrets, Pi-compatible concurrent writers, stale versus fresh Pi processes, Nix garbage collection, plaintext absence, dry-run, ordinary rollback, and interruption recovery. A separate private rollout plan owns migration, live inference, host rebuilds, and provider-specific revocation. ### Scope In scope: public profiles/secrets interfaces, inventory workspace declaration, the archetypes libvirt consumer and reconciler, the Nexus lifecycle command, deploy composition, and synthetic lifecycle witnesses. Out of scope: live provider data in public history; automatic migration of an existing private integration; integration-specific Pi extensions; provider-side issuance/revocation; OAuth, arbitrary headers, HTTP endpoints, privacy/service VMs, microVM delivery, or hiding credentials from same-user agents inside the target VM.

allod-agent referenced this issue

2026-08-20 16:48:31 +01:00

Plan managed Pi provider lifecycle #35

allod-agent changed title from ~~Provision age-encrypted custom Pi inference providers from Nexus~~ to Manage add, rotate, and retire lifecycle for Age-backed Pi providers

2026-08-20 23:03:21 +01:00

allod-agent referenced this issue from a commit

2026-08-20 23:24:11 +01:00

record Pi lifecycle review pass two

allod-agent referenced this issue from allod/inventory

2026-08-21 03:01:35 +01:00

Validate Nexus data checkouts from raw inventory #12

allod-agent referenced this issue from allod/profiles

2026-08-21 03:03:27 +01:00

Add validated Pi provider catalog contract #6

allod-agent referenced this issue from allod/secrets

2026-08-21 03:08:04 +01:00