net-kingdom/workplans/NK-WP-0048-security-case-types.md

---
id: NK-WP-0048
type: workplan
title: "Establish SecurityCaseTypes so that known security cases are light"
domain: infotech
repo: net-kingdom
status: active
flavor: implementation
owner: claude-code
topic_slug: netkingdom
created: "2026-10-08"
updated: "2026-10-08"
depends_on: []
related_repos:
  - ops-mason
  - ops-warden
  - key-cape
  - railiance-platform
  - informed-decision
state_hub_workstream_id: "e31f3f9d-0748-5137-b0a3-7b3ca46a66eb"
---

# NK-WP-0048 - Establish SecurityCaseTypes so that known security cases are light

## Why

The founder's direction (2026-10-08): setting up a security integration of a
kind that has been done before should be easy, meaning accept the case, then
ops-mason arranges it and ops-warden follows through. Setting up a new kind
needs ample documentation and tests and an informed-decision, because its shape
is part of the security architecture.

Today every integration is hand-built: per-client helper scripts, per-lane
custody, founder checklists. The trigger was KEY-WP-0038 (Forgejo as an OIDC
client), whose next step was going to be yet another hand-written rollout
script.

This plan continues the pattern work of NK-WP-0008 (pattern infospace),
NK-WP-0009 (tutorials) and NK-WP-0030 (scenario composition). It turns patterns
into **SecurityCaseTypes** that ops-mason and ops-warden can execute. Canon:
`canon/standards/security-case-types_v0.1.md` (proposed).

Companion plans: ops-mason `MASON-WP-0010` (materialization) and ops-warden
`WARDEN-WP-0044` (follow-through).

## Tasks

```task
id: NK-WP-0048-T01
status: done
priority: high
state_hub_task_id: "930ac3e9-20ec-5473-98cd-3fe8fddb730f"
```

### T01 — Accept the terminology and the canon

Founder review of `canon/standards/security-case-types_v0.1.md`, including its
section 10 open questions. On acceptance the canon status goes from `proposed`
to `accepted`.

2026-10-08: accepted by the founder (in session). Canon status `accepted`;
section 10's open questions are carried forward to the first type (T04, T05).

```task
id: NK-WP-0048-T02
status: done
priority: high
state_hub_task_id: "19c25d96-a55c-58f0-9168-3fdbc4955fc2"
```

### T02 — Inventory the de-facto types already built by hand

Read-only. List every security integration built so far and group them by shape.
Known starting points:

- browser OIDC relying parties on key-cape: informed-decision-approver,
  coulomb-social, user-engine portal, openbao-admin, and Forgejo (pending)
- confidential service clients with `client_credentials`: secrets-engine
  approval, requester and openbao clients, approval-engine operator
- workload KV read lanes on OpenBao: the railiance-platform credential lane
  designs and CCRs, for example `railiance-backup-offsite-lane`
- short-lived SSH certificates through ops-warden (`warden sign`)
- tunnelled operator access (ops-bridge)

For each: the repositories involved, the hand-built steps, attended human steps,
custody paths, verification evidence, and rollback (if any). Output
`docs/security-case-type-inventory.md`, ranking candidate types by how often the
shape recurs and how much manual work each instance costs today.

2026-10-08: done, `docs/security-case-type-inventory.md`. 36 of 37 CCRs are
already `request_type: workload-kv-read`, a de-facto type reviewed each time as
if it were new. Browser clients: 5 hand-built plus Forgejo, each with its own
rollout script. Confidential service clients need a registration plus two or
three KV-read CCRs each. A forge read identity is needed in bulk by
ORGREF-WP-0002-T06. Recommendation: oidc-browser-relying-party first (unblocks
the forge), workload-kv-read second (largest payoff), then forge-read-identity.

```task
id: NK-WP-0048-T03
status: done
depends_on: [NK-WP-0048-T01]
priority: high
state_hub_task_id: "e487975b-73b1-516c-971d-da4cbbb93063"
```

### T03 — Schema, template and validator

- `canon/schemas/security-case-type_v0.1.schema.json` and
  `security-case_v0.1.schema.json`
- `security-case-types/_template/` with `type.yaml`, `README.md` and tests to copy
- a validator, extending `tools/security-scenario-composer/`, that checks a type,
  checks a case against its type, and renders the case into the composer's
  deterministic plan (still `execution.permitted: false`)

Acceptance: the validator rejects missing sections, secret-shaped parameter
values, unpinned providers and cases against non-`implemented` types, with tests
for each.

2026-10-08: done. `canon/schemas/security-case-type_v0.1.schema.json` and
`security-case_v0.1.schema.json`; `tools/security-case-types/security_case_validator.py`
(`validate-type`, `validate-case`, `render`, reusing the scenario composer);
`security-case-types/_template/` (a valid, runnable example type over
`net-kingdom.local-identity`, with README sections, an example case and tests that
travel with every copy). 31 tests pass, including the composer's existing suite.

```task
id: NK-WP-0048-T04
status: done
depends_on: [NK-WP-0048-T02, NK-WP-0048-T03]
priority: high
state_hub_task_id: "2fffe112-7d55-5680-9952-78d74f44f87f"
```

### T04 — Define the first type: browser OIDC relying party

`security-case-types/oidc-browser-relying-party/`, version 1.0:

- parameters: client id, display name, exact redirect URIs, scopes, client type
  (confidential or public), MFA pin, the groups the consuming service maps,
  custody path for the secret (confidential only), consuming service and its
  owner
- composition: key-cape client registration (key-cape declares it as a playbook
  capability), secret minting into custody (railiance-platform), LLDAP group
  existence and membership (net-kingdom identity-provisioner), handover to the
  consuming service
- materialization (ops-mason) and follow-through (ops-warden) sections
- verification: discovery lists the redirect URI; a test sign-in returns the
  expected claims for one human; anonymous access to the custody path is denied
- rollback: remove exactly this client and its custody path
- README: threat model, MFA rationale, why redirect URIs are exact, which steps
  still need an attended login and how that is minimised
- reference instances: informed-decision-approver, coulomb-social, user-engine
  portal, openbao-admin

Acceptance: complete per canon section 3, tests green, status `proposed`.

2026-10-08: done. `security-case-types/oidc-browser-relying-party/` 1.0 (proposed):
`type.yaml` with 12 parameters (the custody reference is required only for
confidential clients), composition over key-cape's new
`key-cape.oidc-client-registration` declaration (contract PASS, `maturity:
planned`), materialization and follow-through, verification and rollback, all
conditional on client type where it matters. One attended step,
`register-client`, justified by the live registry being a Kubernetes Secret.
README with threat model, alternatives, an honest fit table (portal and vergabe
fit; Forgejo is the first confidential case; openbao-admin, coulomb.social and
informed-decision-approver do not fit 1.0), and known limits. Examples: Forgejo
(checked against the accepted request) and a public portal. The validator gained
`when` / `required_when` conditions and provider discovery. 43 tests pass.
ops-mason's and ops-warden's sections are drafted in the type. Their owners
review them in MASON-WP-0010-T01 and WARDEN-WP-0044-T01 before acknowledgment
(T05).

```task
id: NK-WP-0048-T05
status: wait
depends_on: [NK-WP-0048-T04, MASON-WP-0010-T01, WARDEN-WP-0044-T01]
needs_human: true
blocking_reason: "A new SecurityCaseType is acknowledged as an informed-decision by the founder."
priority: high
state_hub_task_id: "3d987d3d-0797-538b-86e4-51185a327ae2"
```

### T05 — Acknowledge the type through informed-decision

Prepare the Decision Memo from the type's README and `type.yaml` and submit it
through informed-decision's production intake. On acknowledgment the type
moves to `acknowledged`.

2026-10-08: Decision Memo prepared. Hub decision `e418263e-a71f-4f01-a970-c87c9e187c09`.
`security-case-types/oidc-browser-relying-party/decision/`: `packet.md` (question,
one act, what acknowledging does not do, the shape, alternatives, attended
steps, limits, evidence), `build_intake.py` and the built `intake.json` (memo
class `decision-record`, review group `net-kingdom-admins`, resolves the hub
decision on answer). The envelope passes informed-decision's own
`validate_submission`. Queuing it is an attended operator step, a write inside
the production dispatcher pod:

    kubectl -n state-hub exec -i deploy/state-hub-memo-dispatch -- \
      python -m api.services.memo_dispatch --queue /data/private enqueue --envelope /dev/stdin \
      < security-case-types/oidc-browser-relying-party/decision/intake.json

The answer then appears for review in informed-decision.

2026-10-08: queued by the founder (`pending`, `queued`) after one refusal: the
first envelope's idempotency key was not State Hub's stable
`state-hub.<decision>.<memo>` form, and the builder now validates against both
sides. The dispatcher delivered it to informed-decision (ledger 7 → 8
delivered). T05 waits for the founder's answer in informed-decision, which
resolves hub decision `e418263e`.

2026-10-08: ops-mason's review (MASON-WP-0010-T01) folded into the type, still
1.0 `proposed`: `secret_ref` is no longer a parameter, the type derives
`platform/workloads/keycape/{client_id}`; policies are
`workload-kv-read-keycape-{client_id}-eso` and
`workload-kv-read-keycape-{client_id}-{consuming_service}`, each with a templated
body (`read` on that one data path); new `openbao_role`
`external-secrets-keycape-{client_id}` (Kubernetes auth, ESO service account,
15m, no default policy); catalog entry `{consuming_service}-keycape-client`;
the two rollback steps on the KV path collapse into one metadata delete. The
schema and validator now require a `body` on policy and role items. 105 tests
pass. Two consequences: the delivered memo describes the type before these
changes (a case-set custody reference, two differently named policies, no ESO
role), so the founder answers on a superseded shape unless the memo is
re-sent; and Forgejo's custody path moves from the accepted request's proposed
`platform/workloads/forgejo/netkingdom-oidc-client` to
`platform/workloads/keycape/forgejo`, which key-cape (KEY-WP-0038) and
railiance-apps (RAPPS-WP-0016-T02) need to adopt in T06. ops-warden's review
(WARDEN-WP-0044-T01) is still in progress.

2026-10-08: revised memo `nk-wp-0048-t05-oidc-browser-relying-party-r2` built
(`packet.md`, `intake.json`, packet `sha256:af6435e2…`); it states that it
supersedes the first memo and passes informed-decision's and the dispatcher's
validation. It needs a new memo id because the dispatcher refuses new content
under a delivered idempotency key (`idempotency_conflict`). Queuing it is the
same attended step as above. Both memos serve hub decision `e418263e`; the
first answer resolves it, so the founder answers r2 and leaves the first memo
unanswered. key-cape and railiance-apps were told about Forgejo's new custody
path.

```task
id: NK-WP-0048-T06
status: wait
depends_on: [NK-WP-0048-T05, NK-WP-0048-T08, NK-WP-0048-T09, MASON-WP-0010-T03, WARDEN-WP-0044-T03]
blocking_reason: "Implementation needs the acknowledged type and both executors' light paths."
priority: high
state_hub_task_id: "d9b26bcf-a7c6-59a2-92a0-f913d76a203c"
```

### T06 — First KnownSecurityCase: Forgejo

Write `security-cases/forgejo-netkingdom-oidc.yaml` from the parameters the
founder accepted in KEY-WP-0038-T01 (`key-cape/docs/forgejo-oidc-client-request.yaml`),
so that acceptance carries over as the case acceptance. ops-mason materializes it;
ops-warden follows through and verifies it. The type becomes `implemented` once
this reference case is live.

This replaces the hand-built path proposed for KEY-WP-0038-T02.

```task
id: NK-WP-0048-T07
status: wait
depends_on: [NK-WP-0048-T06]
blocking_reason: "The next types follow once the first one is proven end to end."
priority: medium
state_hub_task_id: "c3c9c3ae-4f23-5ba7-9e6f-e63bcf29b9f7"
```

### T07 — Queue the next types

From the T02 ranking, open the next type drafts (likely the confidential service
client and the workload KV read lane), each to be acknowledged on its own.
Record which existing hand-built instances get adopted as cases, without
rewriting them in place.

```task
id: NK-WP-0048-T08
status: done
priority: high
state_hub_task_id: "8e519082-dc8b-5e46-b660-03d03e55dcf6"
```

### T08 — identity-provisioner: ensure service-access groups

The type's `ensure-groups` step calls `identity-provisioner groups ensure --groups
<list> --members <group=user+user;...>`. The provisioner already has idempotent
`_ensure_group` and `_add_group`, but exposes only tenant-scoped operations. Add
the general operation (create if absent, add the listed memberships, never
remove others), its rollback (remove only this case's memberships), tests, and
the ops-warden route for its service identity.

2026-10-08: done. `identity-provisioner/provisioner.py` gained
`ensure_service_groups` (`POST /v1/groups/ensure`) and `revoke_service_groups`
(`POST /v1/groups/revoke`), behind the existing service-token check. Names
matching `tenant*`, `netkingdom-*` and `lldap_*` are reserved; members must
already exist; everything is validated before any change; memberships are read
back before success; nothing else is ever removed; groups are deleted only when
asked and empty. 7 new tests (39 in the provisioner suite). The type's
`ensure-groups` step and its rollback now name these endpoints. The ops-warden
route for the provisioner's service token belongs to WARDEN-WP-0044-T01.

```task
id: NK-WP-0048-T09
status: done
priority: high
state_hub_task_id: "0ee12dfc-8260-5038-bd39-cc7fb4113be0"
```

### T09 — The `keycape-client` entry point and its declaration

Planned first as key-cape KEY-WP-0038-T04. Moved here because the machinery a
live registration needs already lives in net-kingdom, where KeyCape is deployed
(`sso-mfa/k8s/keycape/`): the contained kubectl, the cluster-identity pin and the
issuer pin. A copy in key-cape would drift.

2026-10-08: done. `sso-mfa/k8s/keycape/keycape-client.py` derives the KeyCape
client record from a case (`client-from-case`). It adds or removes exactly one
client with the existing safeguards (byte-preserving merge, exact match or
refuse, shared-reference refusal, compare-and-swap, read-back, contained errors),
requires the Deployment env binding first for confidential clients, and requires
the case acceptance record for `apply` instead of a per-client founder decision
id. 15 tests, including a regression showing that the vergabe case reproduces
its hand-built registration exactly; all 71 helper tests pass. Declaration
`capabilities/playbooks/net-kingdom.keycape-client-registration.yaml` (contract
PASS, `maturity: implemented`) replaces key-cape's draft. The type now pins it,
and for confidential clients adds `deliver-secret` (delivery from custody into
the sso namespace) and `bind-env` (Deployment env), attended in the same session
as `register-client`. The per-client helpers stay until their clients are
adopted as cases.