259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
---
|
|
id: RAPPS-WP-0016
|
|
type: workplan
|
|
title: "Forgejo sign-in through NetKingdom, before the forge closes"
|
|
domain: infotech
|
|
repo: railiance-apps
|
|
status: active
|
|
flavor: implementation
|
|
owner: claude-code
|
|
topic_slug: railiance
|
|
created: "2026-10-08"
|
|
updated: "2026-10-18"
|
|
depends_on:
|
|
- KEY-WP-0038
|
|
related_repos:
|
|
- prj-forgejo-org-refactor
|
|
- key-cape
|
|
- railiance-platform
|
|
state_hub_workstream_id: "f6b1d6f6-0abb-5774-87b9-bf3cfb640a3b"
|
|
---
|
|
|
|
# RAPPS-WP-0016 - Forgejo sign-in through NetKingdom, before the forge closes
|
|
|
|
## 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 sign-in
|
|
runs through NetKingdom first. railiance-apps owns the Forgejo Helm release
|
|
(`docs/forgejo-on-railiance01.md`: S5 Helm release, ingress, operator Makefile),
|
|
so the Forgejo side lands here. This plan is ORGREF-WP-0002-T05. The NetKingdom
|
|
side is key-cape `KEY-WP-0038`.
|
|
|
|
## Boundaries
|
|
|
|
- **Founder guardrail:** tighten gradually; never lock anyone out; never risk
|
|
assets; never reach a state that is hard to repair. Every step keeps the
|
|
current sign-in path working until the new one is proven.
|
|
- **No visibility change** in this plan. Repositories, packages and
|
|
`REQUIRE_SIGNIN_VIEW` are ORGREF-WP-0002-T08.
|
|
- **Configuration in git.** The authentication source is declared in
|
|
`helm/forgejo-values.yaml` (`gitea.oauth`), with its secret drawn from an
|
|
ExternalSecret over OpenBao. No click-ops, and no secret value in git.
|
|
- Open registration is already disabled (`service.DISABLE_REGISTRATION: true`).
|
|
This plan keeps it that way.
|
|
|
|
## Tasks
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "98004ed0-83e6-5f6e-9b18-15b8b2aec2e7"
|
|
```
|
|
|
|
### T01 — Make the local administrator a sealed break-glass
|
|
|
|
Before anything about sign-in changes: confirm the local administrator account
|
|
works, keep its credential only in OpenBao, and document recovery (who, how,
|
|
where it is logged) in `docs/forgejo-on-railiance01.md`. Verify one break-glass
|
|
sign-in and record it without the credential.
|
|
|
|
Acceptance: a recorded break-glass sign-in, with the recovery path written down.
|
|
This is the "never lock ourselves out" floor for every later step.
|
|
|
|
Done 2026-10-17: founder sealed `forgejo_admin` into OpenBao
|
|
`platform/workloads/forgejo/break-glass-admin` (version 1) and verified a local
|
|
sign-in (HTTP 200, site admin): `docs/evidence/2026-10-17-forgejo-breakglass-signin.json`.
|
|
Recovery path: `docs/forgejo-on-railiance01.md` § Break-glass administrator.
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T02
|
|
status: wait
|
|
depends_on: [RAPPS-WP-0016-T01, KEY-WP-0038-T02]
|
|
blocking_reason: "Break-glass done (T01); needs the NetKingdom client registered with its secret in custody (KEY-WP-0038-T02)."
|
|
priority: high
|
|
state_hub_task_id: "13cd3aec-c87d-5d3f-a421-39d8ff131edd"
|
|
```
|
|
|
|
### T02 — Add the NetKingdom authentication source
|
|
|
|
- an ExternalSecret delivering the `forgejo` client secret from OpenBao to a
|
|
Secret in the `forgejo` namespace. Custody path is
|
|
`platform/workloads/keycape/forgejo`, field `CLIENT_SECRET`, read by ESO through
|
|
Kubernetes-auth role `external-secrets-keycape-forgejo-forgejo`, which carries
|
|
only policy `workload-kv-read-keycape-forgejo-forgejo` (net-kingdom 074b3a0;
|
|
replaces the earlier `platform/workloads/forgejo/netkingdom-oidc-client` proposal). The
|
|
SA/SecretStore/ExternalSecret shape follows the NK-WP-0048
|
|
`deliver-consumer-secret` receipt contract
|
|
(`docs/evidence/nk48-t16-owner-review/owner-review-railiance-apps.json`)
|
|
- `gitea.oauth`: name `netkingdom` (must match the redirect URI registered in
|
|
key-cape), provider `openidConnect`, auto-discovery from
|
|
`https://kc.coulomb.social/.well-known/openid-configuration`, scopes
|
|
`openid profile email groups`, group-claim name `groups`
|
|
- `oauth2_client` settings: no automatic account creation for unknown subjects;
|
|
account linking to existing local accounts by username after a successful
|
|
local sign-in (so the founder and agent accounts keep their history)
|
|
- Helm upgrade with the previous revision noted for rollback
|
|
|
|
Local password sign-in stays enabled.
|
|
|
|
Acceptance: the "Sign in with netkingdom" option appears. Local sign-in still
|
|
works. Rollback is one `helm rollback` to the noted revision.
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T03
|
|
status: wait
|
|
depends_on: [RAPPS-WP-0016-T02]
|
|
blocking_reason: "Linking and team mapping follow a working authentication source."
|
|
priority: high
|
|
state_hub_task_id: "81f072aa-c316-511e-a2cd-21dd1b1d0a00"
|
|
```
|
|
|
|
### T03 — Link accounts and map groups to teams
|
|
|
|
- The founder links their account through NetKingdom (MFA), then signs in again
|
|
through NetKingdom only and sees the same repositories, organisations and
|
|
admin rights.
|
|
- Map NetKingdom groups (names agreed in KEY-WP-0038-T01) to organisation teams:
|
|
owners and readers at least. Create the read-only teams that
|
|
ORGREF-WP-0002-T06 consumers will use.
|
|
- Apply KEY-WP-0038-T03's decision on agents and services: NetKingdom sign-in, or
|
|
scoped tokens bound to service identities.
|
|
|
|
Acceptance: founder and one agent work through NetKingdom; group-to-team mapping
|
|
verified by adding and removing one test membership; break-glass still works.
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T04
|
|
status: wait
|
|
depends_on: [RAPPS-WP-0016-T03]
|
|
needs_human: true
|
|
blocking_reason: "Restricting local password sign-in is a founder decision once NetKingdom sign-in is proven."
|
|
priority: medium
|
|
state_hub_task_id: "32c54737-c40f-5fde-9b91-163f8dcb0068"
|
|
```
|
|
|
|
### T04 — Decide on local password sign-in
|
|
|
|
Once NetKingdom sign-in has been used for a while without problems, the founder
|
|
decides whether local password sign-in is turned off for everyone except
|
|
break-glass. This is not required to close the forge; it is the next tightening
|
|
step, taken separately.
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T05
|
|
status: wait
|
|
depends_on: [RAPPS-WP-0016-T02]
|
|
blocking_reason: "Waits for net-kingdom's answer to the Apps 1.3 needs-change record (the-custodian docs/changes/netkingdom-target-2026-10-17/nk48-1.3-owner-review/owner-review-railiance-apps.json: RAPPS-1.3-C1..C3) and the re-frozen 1.3 candidate."
|
|
priority: medium
|
|
state_hub_task_id: "728786c9-f1f9-5983-a6a4-dea21faf67f5"
|
|
```
|
|
|
|
### T05 — Apps owner seams for NK-WP-0048 consumer steps
|
|
|
|
Implement the real Apps capabilities behind the `deliver-consumer-secret` and
|
|
`hand-over` adapters, as owner-run paths (option C): `owner_apply` /
|
|
`owner_remove` emitting `netkingdom.consumer-secret-delivery.v1` receipts from the
|
|
T02 objects; a consumer verifier that observes Forgejo sign-in and the T03
|
|
positive/negative group probes; and a committed-evidence hand-over receipt store.
|
|
See the owner-review record for the contract.
|
|
|
|
Acceptance: receipts produced from the live T02/T03 run validate against the
|
|
adapters' checks with no value-bearing keys.
|
|
|
|
## Also in scope: stale node credential
|
|
|
|
The k3s `registries.yaml` on railiance01 still holds a login for the frozen Gitea
|
|
host `92.205.130.254` (ORGREF-WP-0002-T02). Coordinate its removal with the node
|
|
owner when ORGREF-WP-0002-T06 adds the forge registry login, in the same change.
|
|
|
|
|
|
## T06 — Package the reviewed consumer source through the Apps build path
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T06
|
|
status: done
|
|
priority: high
|
|
```
|
|
|
|
Completed 2026-10-18, source build tooling only. The existing Apps Makefile now
|
|
has explicit prepare, public-dependency acquisition, offline build, artifact
|
|
verification and local OCI export targets for the pinned official Forgejo11.0.3
|
|
source plus reviewed multi-value claim patch. Source/toolchains/locks/compiler
|
|
inputs/base image are fixed. Third-party application source stays in a new /tmp
|
|
workspace; Apps holds the release input lock, patch and build recipe.
|
|
|
|
The original build profile produced identical frontend assets, bindata sources
|
|
and complete static executable in two workspaces, and identical local OCI
|
|
archives in two no-cache exports. Independent review then found host process
|
|
argv visibility through /proc (APPSBUILD-R1-F01). The revised recipe adds a
|
|
private PID namespace; exact source and synthetic canary regression are separately
|
|
reviewed. The original full builds are historical r1-profile evidence; no full
|
|
r2 build is claimed. Original packet/review and failure history remain in
|
|
Custodian apps-forgejo-release-build-r1 and apps-release-independent-review-r1;
|
|
the correction is apps-forgejo-release-build-r2. This is coordinator source
|
|
integration after independent technical review, not formal owner assent or image
|
|
admission. Helm values, deployed image, local sign-in and visibility are unchanged.
|
|
NK-WP-0048-T39 remains progress for the full release acceptance scope.
|
|
|
|
## T07 — Keep the client secret out of process arguments
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T07
|
|
status: progress
|
|
priority: high
|
|
```
|
|
|
|
Implement and independently review a real Forgejo add/update --secret-file path
|
|
and the actual chart helper/mount adaptation. Preserve the existing CLIENT_SECRET
|
|
key and custody route; use no agent-value argument or environment fallback. Test
|
|
bounded stable nofollow file reads, exact existing minted-secret encoding,
|
|
mutual exclusion/update preservation, fixed errors and actual Helm rendering.
|
|
Private mount identity/reader set and new package/type revisions need explicit
|
|
owner/runtime admission. The in-progress isolated candidate is Custodian
|
|
forgejo-private-input-r1; source completion is distinct from T02 native delivery.
|
|
|
|
## T08 — Provide a transactional application-source inverse and durable recovery
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T08
|
|
status: progress
|
|
priority: high
|
|
```
|
|
|
|
Implement actual owner database primitives that record operation intent/outcome
|
|
in the same durable database, compare complete raw persisted before/post/current
|
|
source state privately, and serialize conflicting application writers at the DB
|
|
boundary. Never emit stored credential/config bytes or delete/detach linked users
|
|
or a preexisting/shared source. SQLite and PostgreSQL transaction semantics must
|
|
be tested against the real app packages; unsupported backends refuse.
|
|
|
|
T05 and NK-WP-0048-T34 additionally require actual authenticated execution and
|
|
fresh inverse sessions, admitted evidence/recovery and exclusion of every release
|
|
writer, including Helm/runtime writers. The candidate DB primitive alone does
|
|
not establish those facilities. Helm rollback/omission does not remove persisted
|
|
OAuth sources: verify the exact app-state inverse before any image downgrade.
|
|
If links prevent removal, retain the extended image and reconcile. The earlier
|
|
T02 single-Helm-rollback statement is not sufficient recovery for this extension;
|
|
its historical text is retained and corrected here.
|
|
|
|
## T09 — Enforce authenticated Access Engine decisions in the application path
|
|
|
|
```task
|
|
id: RAPPS-WP-0016-T09
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Use the producer-owned decision format/canonical bytes and independently admitted
|
|
signer/policy/request pins. Forgejo must verify the caller's issuer/tenant and
|
|
assurance facts, obtain and authenticate the exact Access Engine resource/action
|
|
decision, and refuse missing, stale, wrong-pin, unavailable or malformed replies.
|
|
Keep the original three-group any-of access set as policy input; its local
|
|
compatibility gate is not a substitute PDP or an architecture exception. An
|
|
issuer allowed/denied claim cannot manufacture authorization. Source integration
|
|
needs real provider/callback/session wiring and meaningful producer-consumer
|
|
positive/adverse tests before re-freezing the case and package. Existing break-
|
|
glass/local account and linking behavior remain within the declared owner scope.
|