From ff6890788b9cb49d2392c8cf3ae27118761bfa50 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Thu, 8 Oct 2026 19:12:09 +0200
Subject: [PATCH] Add KEY-WP-0038: Forgejo as a NetKingdom OIDC client

ORGREF-WP-0002-T04; founder-approved 2026-10-08. Counterpart: railiance-apps
RAPPS-WP-0016.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 5457@bnt-lap001
Assistant-Session: 792bf84a-3783-4f5d-a811-cded61dd2012
---
 workplans/KEY-WP-0038-forgejo-oidc-client.md | 114 +++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 workplans/KEY-WP-0038-forgejo-oidc-client.md

diff --git a/workplans/KEY-WP-0038-forgejo-oidc-client.md b/workplans/KEY-WP-0038-forgejo-oidc-client.md
new file mode 100644
index 0000000..2b5a2a8
--- /dev/null
+++ b/workplans/KEY-WP-0038-forgejo-oidc-client.md
@@ -0,0 +1,114 @@
+---
+id: KEY-WP-0038
+type: workplan
+title: "Forgejo as a NetKingdom OIDC client, so the forge can close"
+domain: infotech
+repo: key-cape
+status: ready
+flavor: implementation
+owner: claude-code
+topic_slug: railiance
+created: "2026-10-08"
+updated: "2026-10-08"
+depends_on: []
+related_repos:
+  - prj-forgejo-org-refactor
+  - railiance-apps
+  - railiance-platform
+---
+
+# KEY-WP-0038 - Forgejo as a NetKingdom OIDC client, so the forge can close
+
+## Why
+
+`forgejo.coulomb.social` is closing: private by default, no anonymous access
+(prj-forgejo-org-refactor ORGREF-WP-0002, decision
+`decisions/forge-visibility-policy.md`). The founder's condition is that Forgejo
+sign-in runs through NetKingdom **before** anything closes, so that every human,
+agent and service reader has a governed identity rather than an ad-hoc local
+account. This plan is ORGREF-WP-0002-T04. Its Forgejo-side counterpart is
+railiance-apps `RAPPS-WP-0016` (ORGREF-WP-0002-T05), which owns the Forgejo
+Helm release.
+
+## Boundaries
+
+- Registration follows the existing human browser-client pattern
+  (`docs/approval-engine-provisioning-request.yaml`, `human_registration`) and the
+  client fields validated in KEY-WP-0028. Redirect URIs are exact, never
+  wildcards.
+- The client secret goes to OpenBao through railiance-platform custody. No secret
+  value in git, State Hub, logs or chat.
+- Founder guardrail for the whole closure: tighten gradually, never lock anyone
+  out, never risk assets. Nothing in this plan changes who can read the forge
+  today. It only makes the NetKingdom path available.
+
+## Tasks
+
+```task
+id: KEY-WP-0038-T01
+status: todo
+priority: high
+```
+
+### T01 — Define what Forgejo receives
+
+Write the claim contract Forgejo consumes, as a non-secret request packet under
+`docs/`:
+
+- issuer `https://kc.coulomb.social`; confidential client `forgejo`; authorization
+  code with PKCE; scopes `openid profile email groups`
+- redirect URI
+  `https://forgejo.coulomb.social/user/oauth2/netkingdom/callback`. The
+  authentication-source name `netkingdom` must match railiance-apps'
+  configuration exactly.
+- subject and username: canonical directory subject, plus a stable
+  `preferred_username` that Forgejo can match to the existing local accounts
+  (founder and agent accounts) for linking
+- `groups` naming the Forgejo organisations and teams to map to (for example
+  `forge:coulomb:owners`, `forge:coulomb:readers`), and `principal_type` so that
+  human and service principals stay distinguishable
+- MFA: forge administrators and owners require assurance with a fresh second
+  factor; plain readers follow the client-aware MFA policy (KEY-WP-0008)
+
+Acceptance: the founder accepts the packet. The group names are agreed with
+railiance-apps.
+
+```task
+id: KEY-WP-0038-T02
+status: wait
+depends_on: [KEY-WP-0038-T01]
+blocking_reason: "Registration follows the accepted claim contract."
+priority: high
+```
+
+### T02 — Register the client and hand over its secret
+
+Register `forgejo` from the packet. Mint the client secret straight into custody
+(proposed OpenBao path `platform/workloads/forgejo/netkingdom-oidc-client`,
+custody owner railiance-platform, consumer Forgejo). Record a receipt with no
+secret value.
+
+Acceptance: discovery metadata lists the client's redirect URI. The secret is
+readable by Forgejo's custody path only.
+
+```task
+id: KEY-WP-0038-T03
+status: wait
+depends_on: [KEY-WP-0038-T02]
+blocking_reason: "Claims are verified against the registered client."
+priority: high
+```
+
+### T03 — Prove the claims for each kind of identity
+
+Before Forgejo uses the client, verify the issued ID token and UserInfo for one
+human (the founder, with MFA), one agent identity and one service identity:
+subject, `preferred_username`, `groups`, `principal_type`, assurance. Record the
+claims, minus tokens, as evidence.
+
+Decide with railiance-apps whether agents and services sign in to Forgejo at
+all, or receive scoped Forgejo tokens bound to a NetKingdom service identity
+(ORGREF-WP-0002-T06). Record the decision.
+
+Acceptance: evidence for all three principals; the agent and service decision is
+recorded. Then hand over to RAPPS-WP-0016.