diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index dc53ac6..faf0149 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,19 +1,22 @@ ## Stack - -- **Language:** -- **Key deps:** +- **Language:** Kubernetes manifests, Bash Make targets, SOPS-encrypted secret custody +- **Key deps:** Keycloak (SSO/MFA), age/SOPS, KeePassXC-based credential custody, repo-local git hooks ## Dev Commands ```bash -# TODO: Fill in the standard commands for this repo - -# Install dependencies - -# Run tests - -# Lint / type check - -# Build / package (if applicable) +make help # list all targets +make hooks && make hooks-test # secrets-guard git hooks +make check-secrets # fail if anything under secrets/ is unencrypted +make sops-edit FILE=secrets/foo.yaml # edit encrypted file +make sops-custody-check # validate custody age key without writing to disk +make sops-custody-run COMMAND='...' # run one command with temporary custody key +make creds-init # one-time credential custody setup +make creds-generate # generate service secrets + KeePassXC guide +make creds-bundle # age-encrypt ops bundle for offsite storage ``` + +Credential material never lands in Git, State Hub, or logs — the hooks and +check-secrets enforce this. Deployment of identity services runs through the +S2/S5 railiance repos, not from here. diff --git a/README.md b/README.md index cc34b85..81e3e74 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ # NetKingdom NetKingdom provides a dynamic self optimizing full circle security-platform for kubernetes deployed IT-infrastructures. + +## Security Infrastructure Documents + +- [secrets-engine security infrastructure boundary](docs/secrets-engine-security-infrastructure-boundary.md) + defines how secrets-engine participates in the NetKingdom security + infrastructure and how it interacts with OpenBao, flex-auth, user-engine, + ops-warden, ops-bridge, info-tech-canon, State Hub, and agents. diff --git a/docs/responsibility-map.md b/docs/responsibility-map.md index d866bd1..2dbeae5 100644 --- a/docs/responsibility-map.md +++ b/docs/responsibility-map.md @@ -76,6 +76,17 @@ and what NetKingdom is responsible for (meta-orchestration). | **Repo owns** | operating these stateful services to durability/recovery guarantees behind stable interfaces | | **NetKingdom orchestrates** | which platform services a scenario needs; runtime secret-authority boundaries (platform-root vs tenant) and policies; backup/DR requirements; the identity-integration point; runtime-secret-trust readiness | +### `secrets-engine` — secret workflow and delivery orchestration + +| | | +| --- | --- | +| **Resources held** | non-secret secret-lane catalog, stage policy model, delivery-mode contracts, OpenBao apply/delivery plans, readiness and evidence records | +| **Repo owns** | workflow and automation mechanics for approved secret establishment, provisioning, verification, delivery, rotation, revocation, and deactivation | +| **NetKingdom orchestrates** | secret organization concepts; build/test/production stage boundaries; which systems participate in decisions and delivery; OpenBao/flex-auth/user-engine/ops-warden/ops-bridge/info-tech-canon interaction boundaries; the rule that OpenBao remains custody and audit backend | + +See `docs/secrets-engine-security-infrastructure-boundary.md` for the canonical +cross-system boundary and interaction model. + ### `key-cape` — identity | | | diff --git a/docs/secrets-engine-security-infrastructure-boundary.md b/docs/secrets-engine-security-infrastructure-boundary.md new file mode 100644 index 0000000..5cd2ba5 --- /dev/null +++ b/docs/secrets-engine-security-infrastructure-boundary.md @@ -0,0 +1,363 @@ +# NetKingdom Security Infrastructure Boundary + +## Purpose + +This document defines how `secrets-engine` participates in the NetKingdom +security infrastructure. It is the first place agents and operators should read +when they need to understand responsibility boundaries, system interactions, +secret organization, and stage-specific policy concepts. + +`secrets-engine` is the workflow and interaction layer for approved secret work. +OpenBao remains the custody, policy, lease, and audit backend. + +## Core Responsibility + +`secrets-engine` turns an approved secret request into a safe, reviewable, +auditable sequence of actions: + +1. Resolve the catalog entry and stage. +2. Verify the decision or approval state. +3. Render a plan for OpenBao metadata, value provisioning, verification, and + delivery. +4. Apply only allowed OpenBao changes through the minimal stage role. +5. Provision or confirm the value without exposing it in coordination systems. +6. Deliver the secret to a workload or command without printing it. +7. Record non-secret evidence for audit, troubleshooting, and readiness. +8. Rotate, revoke, deactivate, or mark compromised secrets through the same + catalog and decision model. + +## Boundary Map + +| System | Owns | secrets-engine interaction | Must not do | +| --- | --- | --- | --- | +| OpenBao | Secret custody, ACL policy enforcement, leases, response wrapping, audit logs | Use OpenBao through constrained build, test, and production roles; write policies, auth roles, metadata, and values only through validated plans | Treat OpenBao UI/CLI as the routine operator interface; bypass decision checks; store raw values outside OpenBao | +| flex-auth | Authorization decisions and policy reasoning | Ask whether an actor may establish, access, rotate, or deactivate a cataloged secret for a purpose | Store or deliver secret values; become the vault | +| user-engine / key-cape | Human and service identity, user lifecycle, claims, groups, MFA/OIDC context | Consume stable identity claims and service identities for OpenBao auth bindings and decision checks | Own secret lifecycle policy; mint provider tokens | +| ops-warden | SSH certificate issuance and credential routing front door | Route non-SSH credential requests to secrets-engine; show catalog readiness and safe next commands | Vend API keys, provider tokens, database passwords, or OpenBao tokens | +| ops-bridge | Remote execution, tunnels, transport, and operator connectivity | Consume secrets through `secrets-engine exec` or scoped delivery when a remote operation needs credentials | Persist secrets in tunnel configs, logs, or reusable shell state | +| info-tech-canon | Canonical terminology, governance patterns, stage taxonomy, naming conventions, documentation profiles | Reuse canon terms for stage, catalog, approval, delivery, evidence, rotation, and deactivation concepts | Act as runtime authority or store secret values | +| State Hub | Non-secret workstreams, decisions, progress, review comments, and evidence pointers | Read decisions and write non-secret progress/evidence | Store raw secret values, tokens, wrapped tokens, passwords, or private keys | +| llm-connect / agents | Reasoning and task execution | Receive non-secret plans and use exec-time delivery only when needed | Place secrets in prompts, chat, model context, or logs | + +## System-of-Systems Position + +`secrets-engine` sits between request/decision systems and OpenBao operations. +It is not the source of identity, authorization, or custody. It is the place +where those systems are composed into an operator- and agent-usable workflow. + +```text +request / ops-warden route + | + v +State Hub decision <---- flex-auth authorization + | + v +secrets-engine catalog + plan + policy guard + | + v +OpenBao role/policy/value operations + | + v +verification + evidence + safe delivery + | + v +workload, CI job, operator command, or ops-bridge task +``` + +## Core Concepts + +### Secret Lane + +A secret lane is the governed path for one secret use case. It joins a catalog +id, owner, stage, OpenBao location, fields, consumer binding, approval model, +delivery modes, verification checks, and revocation behavior. + +Example catalog id: + +```text +whynot-design-npm-publish +``` + +### Catalog Entry + +A catalog entry is non-secret metadata. It is the primary object agents and +operators should reference. It must never contain raw secret values. + +Required concepts: + +- catalog id; +- stage; +- owner domain, repo, workload, or service; +- OpenBao backend mount/path and fields; +- allowed consumers and identity claims; +- allowed delivery modes; +- approval/decision requirement; +- verification requirements; +- rotation, revocation, and compromised/deactivated behavior; +- evidence expectations. + +### Stage + +A stage is a security boundary. The initial stages are: + +- `build`; +- `test`; +- `production`. + +Short aliases such as `prod` may exist in CLI flags, but catalog and policy +documents should normalize to the canonical names above. + +### Decision + +A decision is the non-secret approval state that allows a secret lane to be +created, changed, delivered, rotated, or deactivated. Decisions live outside the +vault, usually in State Hub and/or flex-auth. A production action must fail +closed without an approved decision, except for explicit break-glass flows. + +### Delivery Mode + +A delivery mode defines how a secret reaches a consumer without becoming visible +in normal coordination surfaces. + +Initial allowed modes: + +- exec-time environment injection; +- exec-time temporary config file; +- response-wrapped handoff; +- local bootstrap file import for setup only; +- non-production generated test value. + +Denied modes: + +- chat; +- prompts or model context; +- Git; +- State Hub message body; +- command-line argument containing the raw value; +- normal logs; +- long-lived untracked local files. + +### Evidence + +Evidence is non-secret proof that an action happened and what its result was. +Evidence may include catalog id, actor, stage, decision id, OpenBao path, field +names, lease accessor, timestamps, audit request ids, and pass/fail status. It +must not include raw secret values. + +## Stage Policy Model + +### Build + +Purpose: + +- local development; +- disposable integration experiments; +- generated or synthetic values; +- quick iteration before stronger policy is justified. + +Allowed direction: + +- manage build-stage metadata and values under build prefixes; +- generate fake or low-impact values; +- use lightweight decisions or repo-owner approval; +- support fast `exec` flows for development commands. + +Restrictions: + +- no production mounts or paths; +- no broad OpenBao sys/auth administration; +- no reuse of build values in test or production; +- short TTLs by default. + +### Test + +Purpose: + +- staging and integration verification; +- proving delivery, rotation, and negative checks; +- rehearsing production policy with lower impact. + +Allowed direction: + +- manage approved test-stage metadata and values; +- run positive and negative access verification; +- use provider tokens or service credentials with test-only scope; +- record evidence before a similar production lane is considered ready. + +Restrictions: + +- no production values; +- no production auth roles; +- stricter identity binding than build; +- explicit denial checks for unrelated consumers. + +### Production + +Purpose: + +- real workload secrets; +- real provider tokens; +- auditable delivery to production-capable consumers. + +Allowed direction: + +- apply approved production metadata such as ACL policies and auth roles; +- provision values only through approved custody modes; +- deliver values through exec-time or workload-scoped mechanisms; +- record evidence and readiness state. + +Restrictions: + +- no action without approved decision, except explicit break-glass; +- no broad `platform-root`, `platform-admin`, or wildcard admin semantics; +- no raw value printing; +- no default raw reads by agents; +- rotation, revocation, and compromised/deactivated states must be expressible. + +## OpenBao Role Layers + +The initial OpenBao-facing roles are: + +| Role | Stage | Main capability | +| --- | --- | --- | +| `secrets-engine-build` | build | Manage approved build-stage metadata and values under build prefixes. | +| `secrets-engine-test` | test | Manage approved test-stage metadata and values and run verification. | +| `secrets-engine-prod` | production | Apply approved production metadata and perform constrained delivery/provisioning actions. | + +A temporary bootstrap credential may be used to create these roles and policies. +Bootstrap credentials must be local-only, outside repositories, mode 0600, +revocable, and tracked as temporary setup material. + +## Secret Organization + +The catalog is the stable interface. Physical OpenBao paths may evolve, but +catalog entries must keep enough structure to enforce stage and ownership. + +Recommended logical dimensions: + +```text +stage / tenant-or-org / workload-or-service / bundle / field +``` + +Recommended OpenBao path shape when a shared mount is used: + +```text +/workloads//// +``` + +If a mount is already stage-specific, the stage may be represented by the mount +instead: + +```text +/workloads/// +``` + +The catalog must make the resolved stage explicit in either case. Existing +legacy paths should be represented by catalog metadata before being normalized. + +## Policy Families + +The engine should distinguish policy families rather than treating every +OpenBao policy as a free-form string: + +| Family | Purpose | +| --- | --- | +| catalog-read | Read non-secret catalog metadata and readiness. | +| stage-applier | Apply metadata inside one stage boundary. | +| value-provisioner | Write or import secret values under approved custody. | +| delivery-runner | Fetch and inject a value only into a child process or workload-specific config. | +| verifier | Run positive/negative checks without printing values. | +| revoker | Revoke leases, deactivate lanes, or mark compromised state. | +| auditor | Produce non-secret reports and evidence summaries. | + +Production policy families should be split so that metadata apply, value +provisioning, and value delivery do not automatically imply each other. + +## Main Interaction Flows + +### Establish a Secret Lane + +1. Actor requests a cataloged secret lane. +2. flex-auth and/or State Hub records an approval decision. +3. secrets-engine renders the OpenBao policy/auth/value plan. +4. Operator or agent reviews the plan. +5. secrets-engine applies allowed metadata through the minimal stage role. +6. Secret value is provisioned by approved custody mode. +7. Positive and negative verification run. +8. Catalog readiness becomes resolvable for ops-warden and consumers. + +### Use a Secret + +1. Consumer asks ops-warden or secrets-engine for a catalog id. +2. secrets-engine checks catalog, stage, readiness, identity, and decision state. +3. secrets-engine fetches the value through OpenBao using a delivery role. +4. The value is injected only into the child process or temporary config. +5. Temporary material is removed. +6. Non-secret evidence is recorded. + +Target shape: + +```bash +secrets-engine exec --catalog whynot-design-npm-publish -- npm publish +``` + +### Rotate a Secret + +1. Rotation request is linked to the existing catalog entry. +2. New value is provisioned under approved custody. +3. Consumers are switched or verified. +4. Old value is revoked or deactivated. +5. Evidence records old/new version identifiers without raw values. + +### Mark Compromised or Deactivated + +1. Actor marks the lane compromised or requests deactivation. +2. secrets-engine blocks delivery immediately where possible. +3. OpenBao leases/tokens are revoked. +4. Related policies or auth roles are disabled if required. +5. ops-warden readiness becomes not resolvable. +6. Evidence and follow-up tasks are recorded. + +## Explicit Non-responsibilities + +secrets-engine must not: + +- replace OpenBao; +- make identity or authorization decisions by itself; +- issue SSH certificates; +- establish network tunnels; +- persist raw secret values outside OpenBao as normal operation; +- put secrets into prompts, chat, State Hub, Git, or logs; +- make production changes without an approved decision; +- normalize insecure bootstrap shortcuts into permanent operations. + +## First Pilot + +The first pilot lane is: + +```text +catalog id: whynot-design-npm-publish +field: NPM_AUTH_TOKEN +consumer: whynot-design npm publish workflow +``` + +The pilot should prove: + +- a catalog entry can describe the lane without a raw value; +- an approved decision can drive OpenBao policy and auth role creation; +- provisioning can happen without secret disclosure; +- positive and negative verification can be recorded; +- `secrets-engine exec` can deliver the token to `npm publish` safely; +- ops-warden can route to secrets-engine and report readiness. + +## Canonicalization Tasks + +These concepts should be aligned with info-tech-canon as the implementation +hardens: + +- stage names and aliases; +- catalog entry schema terms; +- decision states and evidence vocabulary; +- delivery mode names; +- compromised, deactivated, rotated, ready, and resolvable states; +- standard OpenBao path and policy naming patterns. diff --git a/workplans/NK-WP-0001-sso-mfa-platform.md b/workplans/NK-WP-0001-sso-mfa-platform.md index a3aa6eb..91a749c 100644 --- a/workplans/NK-WP-0001-sso-mfa-platform.md +++ b/workplans/NK-WP-0001-sso-mfa-platform.md @@ -9,7 +9,8 @@ topic_slug: netkingdom state_hub_workstream_id: 39263c4b-ef70-4053-b782-350834b7e1be created: "2026-02-28" updated: "2026-03-21" -superseded_by: NK-WP-0003--- +superseded_by: NK-WP-0003 +--- # SSO & MFA Platform — Keycloak + privacyIDEA on Kubernetes diff --git a/workplans/NK-WP-0002-local-identity.md b/workplans/NK-WP-0002-local-identity.md index ad97d03..9d66ddc 100644 --- a/workplans/NK-WP-0002-local-identity.md +++ b/workplans/NK-WP-0002-local-identity.md @@ -3,7 +3,7 @@ id: NK-WP-0002 type: workplan title: "Local Identity — Bootstrap User Store & Minimal OIDC" domain: infotech -status: completed +status: finished owner: worsch topic_slug: netkingdom state_hub_workstream_id: 7c9021b1-319c-4b4a-a8be-0642239a1893 diff --git a/workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md b/workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md index a9e5d59..7701a06 100644 --- a/workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md +++ b/workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md @@ -4,7 +4,7 @@ type: workplan title: Recursive platform identity and security architecture domain: infotech repo: net-kingdom -status: done +status: finished owner: Bernd Worsch topic_slug: netkingdom created: 2026-05-17 diff --git a/workplans/NK-WP-0007-object-storage-sts-credential-vending.md b/workplans/NK-WP-0007-object-storage-sts-credential-vending.md index 7c0aa98..7146bba 100644 --- a/workplans/NK-WP-0007-object-storage-sts-credential-vending.md +++ b/workplans/NK-WP-0007-object-storage-sts-credential-vending.md @@ -4,7 +4,7 @@ type: workplan title: Object Storage STS Credential Vending domain: infotech repo: net-kingdom -status: done +status: finished owner: codex topic_slug: netkingdom planning_priority: high diff --git a/workplans/NK-WP-0010-genesis-security-pattern-completion.md b/workplans/NK-WP-0010-genesis-security-pattern-completion.md index 951c2e6..6cd3231 100644 --- a/workplans/NK-WP-0010-genesis-security-pattern-completion.md +++ b/workplans/NK-WP-0010-genesis-security-pattern-completion.md @@ -4,7 +4,7 @@ type: workplan title: Genesis Security Pattern Completion domain: infotech repo: net-kingdom -status: done +status: finished owner: codex topic_slug: netkingdom planning_priority: medium