key-cape/workplans/KEY-WP-0038-forgejo-oidc-client.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	depends_on	related_repos
KEY-WP-0038	workplan	Forgejo as a NetKingdom OIDC client, so the forge can close	infotech	key-cape	ready	implementation	claude-code	railiance	2026-10-08	2026-10-08		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

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.

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.

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.