[P0-30] Formalize deployment config, secret refs, and trusted init boundary #138

New issue

Open

opened 2026-09-02 17:26:32 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:26:32 +00:00

Owner

Current status after ARDR re-audit — 2026-08-29

The original issue mixed current defects with defects already repaired on master.

Exact inspected baseline: 8fb297d146e7332fae7e38170b5b49d49530ac53.

Already repaired — preserve these

Current master already:

builds a self-contained Nix dockerTools.buildLayeredImage carrying the StarIntel application closure;
uses Compose service DNS names for CouchDB/Rabbit/Valkey;
includes Valkey and dependency health checks;
uses Compose secret files rather than checked-in production credentials;
defaults host-facing service publication to loopback bindings;
runs the server container under uid/gid 65532;
exercises the Nix-produced images through the authenticated stack test.

Do not rewrite those working deployment mechanisms as part of this issue.

Residual P0 problem

Ordinary server settings still flow through an executable Common Lisp init file selected by STAR_SERVER_INIT_FILE; secret resolution semantics are split between the shell entrypoint and application code; and several declared configuration controls still need observed-behavior proof rather than mere variable presence.

The default config path and trusted code-extension path therefore have the same authority today.

Canonical ARDR authority

Research:
lost-rob0t/starintel-auto-research/roam/research/ardr-issues/ARDR-ISSUE-191-deployment-config-secrets-contract.org

Design:
lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-044-deployment-config-trusted-init.org

Transactions: Auto-Research #191 / #192.

Design direction

Preserve current OCI/Compose packaging and add a closed typed Common Lisp deployment-config normal form:

ordinary config is inert data, never evaluated code;
schema/version is closed and unknown keys fail;
environment/data-file inputs normalize deterministically before long-lived startup;
secret-bearing fields carry secret references, not serialized secret values;
application-level secret resolution is shared by normal startup and star-server admin;
VALUE / VALUE_FILE ambiguity has one explicit tested rule;
executable Lisp startup customization remains available only as an explicitly trusted extension/hook, separate from ordinary config;
retained HTTP base-path/TLS/listener settings require observed behavior tests;
#34/#35 remain thread/concurrency authority, #36 admission authority, #37 lifecycle/readiness authority.

No new StarLang syntax or external configuration supervisor is justified.

Proposed implementation slices — PENDING OPERATOR APPROVAL

Slice 1 — pure config schema + normalizer

No network/thread/process mutation.

Mandatory RED-first targets on untouched server:

minimal valid data config has no current closed normalized representation;
unknown key rejected;
invalid port/range/type rejected;
config containing executable/read-eval form cannot execute and is rejected;
equivalent input normalizes deterministically;
redacted normalized snapshot contains no resolved secret value.

Slice 2 — unified secret-reference resolver

unreadable/empty required secret file -> typed error, no secret content;
startup and admin resolve the same *_FILE fixture;
VALUE + VALUE_FILE follows one explicit ambiguity rule;
secret bytes cannot enter config diagnostics/logs.

Slice 3 — env + inert data-file adapters

Map currently supported deployment variables into the schema; invalid values fail before long-lived startup.

Slice 4 — startup/trusted-init split

Normal deployment starts without executable init. Legacy -i / STAR_SERVER_INIT_FILE is explicitly trusted-extension compatibility and base configuration is revalidated before resource realization.

Slice 5 — observed behavior

Contract tests prove retained HTTP listener/base-path/TLS and other supported settings actually affect runtime behavior. Dead settings are removed/deprecated rather than falsely advertised.

Slice 6 — deployment regression

Existing Nix image and authenticated Compose/stack tests remain green.

Acceptance

existing repaired OCI/Compose path remains intact;
ordinary config is data-only, typed, closed and fail-fast;
trusted Lisp init is explicit and optional;
startup/admin secret semantics cannot diverge;
normalized config/status cannot expose secret values;
supported settings have observed behavior tests;
production profile rejects unsafe auth/secret combinations;
#34-#37 remain their respective runtime authorities;
no product implementation begins until canonical implementation authorization is explicitly APPROVED by the operator.

Implementation authorization

PENDING / AWAITING_OPERATOR_APPROVAL

Research readiness, design completion, issue state, publication, or machine output does not authorize implementation.

## Current status after ARDR re-audit — 2026-08-29 The original issue mixed current defects with defects already repaired on `master`. Exact inspected baseline: `8fb297d146e7332fae7e38170b5b49d49530ac53`. ### Already repaired — preserve these Current master already: - builds a self-contained Nix `dockerTools.buildLayeredImage` carrying the StarIntel application closure; - uses Compose service DNS names for CouchDB/Rabbit/Valkey; - includes Valkey and dependency health checks; - uses Compose secret files rather than checked-in production credentials; - defaults host-facing service publication to loopback bindings; - runs the server container under uid/gid 65532; - exercises the Nix-produced images through the authenticated stack test. Do **not** rewrite those working deployment mechanisms as part of this issue. ## Residual P0 problem Ordinary server settings still flow through an executable Common Lisp init file selected by `STAR_SERVER_INIT_FILE`; secret resolution semantics are split between the shell entrypoint and application code; and several declared configuration controls still need observed-behavior proof rather than mere variable presence. The default config path and trusted code-extension path therefore have the same authority today. ## Canonical ARDR authority Research: `lost-rob0t/starintel-auto-research/roam/research/ardr-issues/ARDR-ISSUE-191-deployment-config-secrets-contract.org` Design: `lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-044-deployment-config-trusted-init.org` Transactions: Auto-Research #191 / #192. ## Design direction Preserve current OCI/Compose packaging and add a closed typed Common Lisp deployment-config normal form: - ordinary config is inert data, never evaluated code; - schema/version is closed and unknown keys fail; - environment/data-file inputs normalize deterministically before long-lived startup; - secret-bearing fields carry secret references, not serialized secret values; - application-level secret resolution is shared by normal startup and `star-server admin`; - `VALUE` / `VALUE_FILE` ambiguity has one explicit tested rule; - executable Lisp startup customization remains available only as an explicitly trusted extension/hook, separate from ordinary config; - retained HTTP base-path/TLS/listener settings require observed behavior tests; - #34/#35 remain thread/concurrency authority, #36 admission authority, #37 lifecycle/readiness authority. No new StarLang syntax or external configuration supervisor is justified. ## Proposed implementation slices — PENDING OPERATOR APPROVAL ### Slice 1 — pure config schema + normalizer No network/thread/process mutation. Mandatory RED-first targets on untouched server: 1. minimal valid data config has no current closed normalized representation; 2. unknown key rejected; 3. invalid port/range/type rejected; 4. config containing executable/read-eval form cannot execute and is rejected; 5. equivalent input normalizes deterministically; 6. redacted normalized snapshot contains no resolved secret value. ### Slice 2 — unified secret-reference resolver - unreadable/empty required secret file -> typed error, no secret content; - startup and admin resolve the same `*_FILE` fixture; - VALUE + VALUE_FILE follows one explicit ambiguity rule; - secret bytes cannot enter config diagnostics/logs. ### Slice 3 — env + inert data-file adapters Map currently supported deployment variables into the schema; invalid values fail before long-lived startup. ### Slice 4 — startup/trusted-init split Normal deployment starts without executable init. Legacy `-i` / `STAR_SERVER_INIT_FILE` is explicitly trusted-extension compatibility and base configuration is revalidated before resource realization. ### Slice 5 — observed behavior Contract tests prove retained HTTP listener/base-path/TLS and other supported settings actually affect runtime behavior. Dead settings are removed/deprecated rather than falsely advertised. ### Slice 6 — deployment regression Existing Nix image and authenticated Compose/stack tests remain green. ## Acceptance - existing repaired OCI/Compose path remains intact; - ordinary config is data-only, typed, closed and fail-fast; - trusted Lisp init is explicit and optional; - startup/admin secret semantics cannot diverge; - normalized config/status cannot expose secret values; - supported settings have observed behavior tests; - production profile rejects unsafe auth/secret combinations; - #34-#37 remain their respective runtime authorities; - no product implementation begins until canonical implementation authorization is explicitly `APPROVED` by the operator. ## Implementation authorization `PENDING / AWAITING_OPERATOR_APPROVAL` Research readiness, design completion, issue state, publication, or machine output does not authorize implementation.