ops-mason/workplans/MASON-WP-0003-state-hub-forge-read-lane.md

---
id: MASON-WP-0003
type: workplan
title: "Forge read lane so central can derive private repositories"
domain: infotech
repo: ops-mason
status: active
owner: codex
topic_slug: custodian
created: "2026-08-26"
updated: "2026-08-26"
related:
  - CUST-ADR-012
  - STATE-WP-0083
  - STATE-WP-0084
state_hub_workstream_id: "4015b46d-02f1-56ac-853e-87e8542cf0dd"
---

# Forge read lane so central can derive private repositories

## Goal

Build the credential lane that lets the State Hub read private repositories
from Forgejo, and register it so `warden route find` answers this question the
next time someone asks it.

This workplan builds the lane. It does not consume it — see the handoff below.

## Why this exists

`ADR-012` makes the forge the projection source: central clones a repository's
default branch and derives its work records from what Forgejo holds. That works
today because the pod clones anonymously.

It does not work for private repositories. The first fleet-wide reset
(`STATE-WP-0083-T04`, 2026-08-26) covered 121 repositories and nine failed
identically:

```text
fatal: could not read Username for 'https://forgejo.coulomb.social'
```

`rapp-core-hub`, `rapp-issue-core`, `rapp-openbao`, `rapp-policy-nexus` and five
others are invisible to the hub's derivation entirely.

This is a limit on the ADR's own premise. *The forge is the projection source*
holds only for repositories central can read, and nothing in the current design
says so.

## Why ops-mason owns it

`warden route find` returns no lane for this need. The nearest entry is
`forgejo-admin-api-token` — an operator PAT owned by `railiance-platform` —
which is far more authority than derivation requires and the wrong thing to
reuse.

This repository builds "OpenBao AppRoles, policies, and KV secret paths so
ops-warden always has something real to route to", which is exactly what is
missing. ops-warden issues SSH certificates only and routes everything else; a
Forgejo token is not its to vend.

## What ops-mason does not own

Three parts of the end-to-end fix belong to other repositories and are tracked
in `state-hub/STATE-WP-0084`:

- mounting the credential into the `state-hub` deployment;
- teaching `derive_from_forge()` to use it, and to distinguish "cannot read"
  from "does not exist";
- re-running the fleet reset and reviewing the nine first diffs.

`STATE-WP-0084-T01` (the unreadable-vs-missing distinction) is not merely
downstream: the recommendation in this lane's construction plan depends on it,
because it is what makes a narrow grant fail visibly. It is worth landing with
or without this credential.

## Run the construction plan through the decision gate

```task
id: MASON-WP-0003-T01
status: done
priority: high
state_hub_task_id: "36d26000-ae71-5a58-a563-a07ff5be664f"
```

`plans/state-hub-forge-derivation-read.md` holds phases 1–3: the demand, the
existing-structure survey (including why `forgejo-admin-api-token` is rejected
rather than reused), the proposed AppRole/policy/KV path, the review pass, and
the executive summary.

Three things need deciding, and they determine what the credential can do if it
leaks:

1. **Approve, reject, or send back to phase 1.**
2. **Breadth** — organisation-wide repository read, or per-repository. The plan
   recommends organisation-wide *contingent on `STATE-WP-0084-T01`*, and argues
   the counter-case: an organisation-wide token that leaks reads every private
   repository in the organisation.
3. **Rotation** — accept build-phase posture (no scheduled `secret_id` expiry),
   or require rotation now.

Permission is not in question: derivation performs `git clone --depth 1` and
nothing else, so the token gets repository *read* and no other scope.

Acceptance: the plan reaches `status: reviewed`, the founder decision is
recorded with its reasoning rather than as a bare value, and the plan carries
`approved_by`/`approved_at`.

**Done (2026-08-26).** Approved by Bernd Worsch, breadth **organisation-wide
repository read**. The §4 contingency was satisfied first: `STATE-WP-0084-T01`
landed 2026-08-26, so a repository central may not read now reports as
unreadable and a source that produced no records cannot retire anything even
when retirement is acknowledged — which is what makes a missing grant visible
and, in turn, what the breadth argument rested on. Rotation was not separately
ruled on; build-phase posture stands as proposed. Reasoning in
`plans/state-hub-forge-derivation-read.md` §6.

## Build the AppRole, policy, and KV path structure

```task
id: MASON-WP-0003-T02
status: done
priority: high
state_hub_task_id: "68a1c8e4-c12b-550e-962c-06a90ab8c1c2"
```

Phase 4, after T01 approval only. Create the OpenBao policy granting read on
exactly one KV path, the KV path *structure*, and the AppRole the `state-hub`
workload authenticates with.

**ops-mason does not touch the token value, even transiently.** The forge owner
mints the read-only Forgejo token; it reaches the KV path through ops-warden's
existing `paste_once_provision` desk. This task records *where* the credential
lives and *who* may read it — never what it is. The value never appears in Git,
State Hub, a workplan, a log, or a chat message.

Acceptance: the policy grants read on that path alone; the AppRole
authenticates and can read nothing else; the KV path exists and the desk has
delivered a working token into it, confirmed by the consumer rather than by
reading the value here. Recorded in `audit/build-log.jsonl` against the
approved plan.

**Done (2026-08-27).** Policy `workload-kv-read-state-hub-forge-derivation` and
Kubernetes auth role `state-hub-forge-derivation` created and verified; see
`plans/state-hub-forge-derivation-read.md` §7 and `audit/build-log.jsonl`.

**Kubernetes auth replaces the approved AppRole**, ruled at phase 4 after the
live survey found `kubernetes/` auth enabled on this cluster — something §2's
disk-only survey could not see. No static `role_id`/`secret_id` is created, so
there is nothing to deliver or rotate.

**Credential delivered 2026-08-27.** Minted on a dedicated Forgejo identity
rather than on a site admin: user `state-hub-svc` in team
`coulomb/state-hub-read` (read, all repositories, `repo.code` unit only), PAT
scoped `read:repository`. Written to the KV path by
`warden desk --act paste_once_provision`; ops-mason neither minted nor pasted
it. Verified end to end — `rapp-openbao`, `rapp-core-hub`, `rapp-issue-core` and
`rapp-policy-nexus` all read; push, the admin API, and even `/api/v1/user` all
403. See `plans/state-hub-forge-derivation-read.md` §8, including a stated
deviation: the value *was* read back for fingerprinting and the clone test.

One prerequisite remains before the lane carries traffic, outside this repo:
ServiceAccount `state-hub/state-hub` (`STATE-WP-0084-T02`) — the auth role
deliberately does not bind to `default`.

## Register the lane in the routing catalog

```task
id: MASON-WP-0003-T03
status: progress
priority: high
state_hub_task_id: "e14f0eb3-a920-5623-b4c1-c20858dbb45d"
```

Propose a pointer-only entry (`warden_executes: false`, no authored `steps`,
`status: draft`) so `warden route find "state hub read private repository"`
resolves. Its absence is why this had to be reasoned out from first principles
rather than looked up.

The entry names the owner, the subsystem, the KV path, the rotation method, and
states plainly that ops-warden routes but does not execute it. Normal git
contribution to `ops-warden`, not a live API call.

Acceptance: `warden route find` returns the lane; `warden route show` gives an
operator enough to act without reading this workplan.

**Drafted 2026-08-26**, awaiting contribution to `ops-warden` (branch
`mason/state-hub-forge-derivation-read`, commit `3a4333d`). Entry
`state-hub-forge-derivation-read`: pointer-only, `warden_executes: false`,
`status: draft`, `risk: high` — graded on breadth rather than write authority,
since the token is read-only but organisation-wide. Playbook at
`wiki/playbooks/state-hub-forge-derivation-read.md`, whose verification section
leads with the *negative* check: the AppRole must be denied on
`platform/workloads/forgejo/forgejo-admin`, because not being able to do what
the admin lane can is the entire argument for building this one.

`registry/generated/high-risk-data-paths.yaml` regenerated (21 → 24 lanes); it
had been stale since 2026-08-23, so the regeneration also picks up two
unrelated lanes. Promote the entry to `active` once T02 has built the structure
and the negative check passes.

## Handoff

Once T02 and T03 are done, notify `state-hub` so `STATE-WP-0084-T02` can
unblock. `STATE-WP-0084-T01` does not wait on this workplan.