ops-mason/plans/reuse-surface-private-source-reader.md

---
id: reuse-surface-private-source-reader
revision: 2
proposal_id: MASON-CUST81-PRIVATE-READER-R1
demand_source: the-custodian/workplans/CUST-WP-0081-netkingdom-architecture-review-and-reuse.md
consumer_repo: reuse-surface
credential_type: forgejo-restricted-source-read-with-existing-kubernetes-eso
status: draft
approved_by: null
approved_at: null
created: "2026-10-15"
updated: "2026-10-15"
construction_inputs: builds/reuse-surface-private-source-reader/construction-inputs.json
candidate_spec_sha256: 59a7334eb58135790547fab0a8c8e8debb94cc7acaae88d30654c9ae887d6732
approved_spec_sha256: null
filed_as: null
---

# Construction plan: seven-repository hosted capability reader

## 1. Demand

The reuse-surface hub has established 63 of the 70 reviewed security capabilities.
It needs authenticated reads of the seven remaining private repository indexes.
The founder explicitly approved only public disclosure of the exact capability
metadata in CUST81-PRIVATE-METADATA-DISCLOSURE-R1; repository source remains
private. This plan proposes a dedicated repository reader for the hosted process
and delivery through its existing namespace-bound ESO identity. Credential access
and live changes require their own reviewed exact-revision approval.

Preparation source is CUST81-PRIVATE-READER-PROVISIONING-PREPARATION-R1, SHA256
`7819eb51d249f5c7aff4df9fb520afcfb76603b05a4104439499102b6c20af99`.
Consent receipt SHA256 is
`4a4602ad926e3af855d6ddba4731430d33e4a7432c507ba0a5193b9f43056b52`;
disclosure packet SHA256 is
`46ac4fe49a08054cc215aade2fbaf3b36ee334520997857ed84f530b52da9d35`.
The bundled construction-inputs retain all seven consented commits, index hashes
and native raw API URLs. These references contain no credential values.

The delegated ops-mason preparation worker has no own supervision record or
survey token. It is supervised for preparation only and borrows no custodian
agent authority. No live OpenBao, Forgejo, Kubernetes or credential read was
performed. This plan is deliberately **draft**, not reviewed or executable.

## 2. Existing-structure survey

### Local evidence; live survey incomplete

A live `scripts/plan-survey.py` result does not exist: no scoped ops-mason-survey
grant was supplied. Do not treat source files as installed state. Before review,
obtain an owner-scoped metadata survey with exact path/policy and Kubernetes-role
arguments, or a platform-owned sanitized equivalent. Refused queries stay
incomplete rather than being described as absence. No operator/admin session may
be substituted for the ops-mason survey grant.

Local source observations from the pinned preparation and checked files:

- `railiance-platform/openbao/policies/workload-kv-read-reuse-surface-runtime-eso.hcl`
  SHA256 `fab29572fe82fc6674837e430f616409070f97a3867a411b7e21b5141dfaba20`
  grants the existing runtime-secrets data path and lookup/revoke-self endpoints.
- The caller policy `workload-kv-read-reuse-surface-runtime`, SHA256
  `53dd5eecc94fd8d7fc281a858f5d9fc27c8c895fd79161fd113cd3a1387a1257`,
  grants the existing runtime-secrets entry plus self-lifecycle/capability checks;
  it does not grant the proposed new source-reader path.
- ClusterSecretStore `openbao-reuse` uses Kubernetes role
  `reuse-surface-runtime-eso`, SA `reuse/reuse-surface-eso`, audience `openbao`,
  conditions limited to namespace `reuse`. No new static ESO token is proposed.
- `railiance-apps/manifests/reuse-surface-runtime-externalsecret.yaml` already maps
  writer/webhook fields to `reuse/reuse-surface-env`; Deployment uses envFrom.
  Its comments still describe a retired static ESO token; those comments must not
  be taken as a procedure or used to mint one. Apps owns correction on integration.
- CCR-2026-0031 and `provision-core-hub-forgejo-source.py` demonstrate dedicated
  `read:repository` PAT custody. That script explicitly sets all-repository team
  membership and must **not** be executed unchanged for this demand.
- Catalog `reuse-surface-hub-write-token` describes the caller writer lane;
  `forgejo-admin-api-token` is privileged bootstrap authority. Neither is the
  private-index consumer credential. The preparation found no dedicated private
  reader lane; installed absence has not been surveyed.

**Does an existing lane satisfy this demand?** Existing workload identity and
ESO delivery can be reused. Existing writer credentials and all-repository
source readers cannot satisfy the exact-seven grant. Propose a dedicated target
identity and new exact KV entry, with one stanza added to the existing ESO policy.
A differing existing user/team/path/policy must halt for reconciliation before
any mutation. Matching names alone do not establish matching effective scope.

## 3. Proposed changes

### SEC-DSM §37 decision procedure, in order

1. **Q1 — native identity:** the current native raw HTTP fetch uses an
   Authorization credential; Kubernetes SA identity alone is not demonstrated
   as accepted by this Forgejo route. Candidate answer: no for the current
   consumer interface, subject to Forgejo/reuse owner confirmation. Anonymous
   access would require private visibility change and does not satisfy demand.
2. **Q2 — federation:** human KeyCape OIDC login does not prove a machine-token
   exchange for these raw API requests. No workload federation exchange for this
   target is evidenced by the local source review. Candidate answer: no viable
   installed interface demonstrated; Forgejo owner must confirm or supply a
   higher mechanism. If supported reliably, revise to federation before approval.
3. **Q3 — ephemeral target credential:** the local CCR-0031 precedent states PATs
   have no server-side expiry. No usable ephemeral Forgejo issuance/revocation
   service is evidenced. Candidate answer: no mechanism demonstrated, pending
   target-owner confirmation. Do not add a broker just to label a static PAT
   dynamic (DSM-TRANS-003). ESO's 15-minute Bao token does not expire the PAT.
4. **Q4 — automatic rotation:** do not reuse an existing broader PAT. No automated
   rotation job for this proposed dedicated identity is evidenced. Provisioning
   capability is not automatic lifecycle enforcement. Answer: not demonstrated;
   proposed attended rotation is explicitly manual, owned and dated.
5. **Q5 — residual static credential:** conditional on Q1–Q3 owner confirmation,
   use a centrally governed dedicated PAT, OpenBao as custody authority, Forgejo
   as grant/revocation authority, ESO/Kubernetes/env as delivery copies. Level 5
   in §5, **centrally managed static secret**, not level 3 or 4. No AppRole is
   needed: the existing ESO projected workload identity authenticates to Bao.

These answers follow DSM-ARCH-001–004, DSM-TRANS-002/003, DSM-K8S-001–004 and
§35/36: use existing projected SA identity for delivery, avoid adding a static
ESO token or broker, and distinguish central custody from delivery copies.
Unconfirmed Q1–Q3 are explicit review gates, not asserted facts.

### Exact object changes and boundaries

- **create** restricted private non-admin Forgejo user `reuse-surface-source`;
  **create** org team `coulomb/reuse-surface-source-readers`. Dedicated target
  identity replaces unsuitable broad readers identified in §2. Team permission
  `read`, `includes_all_repositories=false`, `can_create_org_repo=false`, only
  `repo.code=read`; all non-code units `none`. Team members exactly this user.
- **create** team membership for exactly `coulomb/rapp-openbao`,
  `coulomb/rapp-policy-nexus`, `coulomb/rapp-postgres`, `coulomb/rapp-sbom-nexus`,
  `coulomb/rapp-telemetry`, `coulomb/rapp-tenant-engine`, `coulomb/rapp-user-engine`.
  Follow all API pages and inspect effective user grants, other teams, direct
  collaborator access, organisation membership and repository ownership. Adding
  seven repositories without checking extra effective grants is insufficient.
  Existing identity/team with differing configuration is a conflict, not permission
  to remove unrelated access silently. Reconciliation needs a revised plan.
- **create** dedicated PAT named `reuse-surface-source-read-<UTC-attempt>` with
  scopes exactly `[read:repository]`. Platform-owned attended helper holds values
  in memory, suppresses every raw response/error and returns token IDs only.
  Password used for service bootstrap is random memory-only, never persisted
  in evidence or reused as workload authentication. Prevent unattended password
  login and recovery escalation according to Forgejo owner review.
- **create** KV-v2 entry `platform/workloads/reuse/reuse-surface/forgejo-source-read`,
  field `FORGEJO_SOURCE_TOKEN`. Platform alone provisions value through its
  reviewed silent custody route from stdin; ops-mason does not handle the value.
  It must retain accessor/token ID and custody version in sanitized lifecycle
  inventory. A new path separates private reader from attended writer callers.
- **modify** only existing policy `workload-kv-read-reuse-surface-runtime-eso` by
  adding `read` on exact
  `platform/data/workloads/reuse/reuse-surface/forgejo-source-read`.
  Candidate full file is bundled, SHA256
  `788bb9c49ab571e522beeecf7a5e29d1c79c842a84fe6d801978655facd3b5bd`.
  No glob, metadata grant, other sibling, caller writer policy, OIDC binding,
  AppRole or Kubernetes auth role change. Verify role/token is still 15m and
  bound to exact SA/namespace/audience; source configuration is not live proof.
- **modify** existing `reuse/reuse-surface-runtime` ExternalSecret by one data
  item: secretKey `REUSE_SURFACE_FORGEJO_SOURCE_READ_TOKEN`, remoteRef key
  `workloads/reuse/reuse-surface/forgejo-source-read`, property
  `FORGEJO_SOURCE_TOKEN`. Bundled JSON item is a proposal for apps integration,
  not a standalone apply object. Preserve existing writer and webhook fields.
- **modify** native fetch code/image through reuse and apps review: reuse owner
  identified both Authorization header forwarding on redirects and registration-
  controlled auth_env/URL credential exfiltration in the current native fetch.
  Do not project the PAT until the full reviewed fix is image-digest pinned and
  runtime authorization plus redirect credential isolation are verified.
  Then deliver through existing envFrom and an apps-approved controlled rollout.
  Image change is explicit; preserve resource bounds unless separately reviewed.
  Rollout must account for SQLite/PVC and single-node headroom before approval.
- **modify** owner-controlled runtime config `REUSE_SURFACE_AUTH_SOURCE_ALLOWLIST`
  to map `REUSE_SURFACE_FORGEJO_SOURCE_READ_TOKEN` to the exact fourteen consented
  pinned API URL strings: seven indexes and seven capability entries. Candidate
  config is `builds/reuse-surface-private-source-reader/auth-source-allowlist.json`;
  registrations cannot set or widen this runtime authority. The patched consumer
  checks exact URL membership **before credential lookup**, requires HTTPS and
  refuses authenticated redirects including same-origin path changes. Apps/reuse
  must safely inventory existing authenticated registrations (auth_env and URL
  metadata only), review which destinations remain legitimate, and migrate their
  mappings before fail-closed rollout. Inventory is not blanket consent. The new
  reader mapping stays exact14; any existing legitimate other mapping needs its
  own owner-reviewed authorization. Missing/invalid mappings fail closed.
- **create** proposed ops-warden pointer `reuse-surface-forgejo-source-read` in
  draft status after construction, owner `railiance-platform`, non-SSH route
  only (`warden_executes:false`). Runtime reader is the hub, not warden.
  Activation remains ops-warden's independent verified catalog review.

### Full consumer candidate pins

Reuse owner provided full patch SHA256
`f707ddfd36d5d470c176530671bb30ff6a3af2dfff86937aa8a5618bcb79768e`,
fixed `federation.py` SHA256
`dbaa40f25cc0f090143578cd1c7068cb2cb00960fafd17d5239bf8a5bac514dd`,
native verification helper `private_source_verify.py` SHA256
`c67a284091cc4dd62dca56658a14b8ea1357e2b3df1518120da4c51e0ee8d85c`,
and owner runtime allowlist SHA256
`e1948c537e206b30fc72b9e4732a3f600d92e131813e6f7ecfd4bfbb18c27286`.
The ops-mason bundled compact allowlist has the same exact env and fourteen URL
sets; serialization/order differs. The construction inputs retain absolute
isolated-owner artifact references for integration. Owner reports focused30pass
and whole226pass with one isolated-relative-path failure; this is not native
runtime proof. Fixed image digest and owner execution review remain pending.

### Revision preservation

R2 refines the same proposal and trial; R1 is preserved under custodian
`owner-assembly/mason-r1/` and `/tmp/cust81-mason-reader-r1-snapshot`. R1 candidate
spec digest was `0d1f604c76e086c82675dc535004cf4da51ef5dc247959fab50295a673407980`.
Neither revision was approved or executed. The full consumer fix and runtime
allowlist supersede the earlier redirect-only image gate. Approval, when sought,
must bind this final reviewed revision, its consumer patch, runtime config and
image; do not create another scored trial from this refinement.

### Residual-secret lifecycle and elimination

Credential owner is railiance-platform; Forgejo owns target grants; reuse-surface
is the only workload consumer. Authority exposes **entire source code of the
seven repositories**, not just registry files. Metadata disclosure approval
alone does not authorize this larger repository-read grant.

Known intended copies: OpenBao KV current version and retained versions/backups;
Kubernetes Secret in `reuse` and etcd backups; hub process environment; transient
minting/delivery memory. Every namespace actor allowed to attach the ESO store or
reference the materialized Secret is an indirect consumer/exposure path and must
be reviewed; namespace conditions are not per-pod isolation. No CI/chat/local
credential file copy is allowed. Avoid Secret last-applied annotation copies.

Proposed lifetime policy is attended rotation **every 90 days**, and immediately
on compromise, owner change, consumer retirement or scope drift. This is a
recommended stricter policy than CCR-0031's 180-day precedent; it is not a claim
of automated enforcement or PAT native expiry. Record issuance and next-due UTC
in platform inventory, with an assigned owner reminder before activation.
Rotation: mint one replacement with the same checked grant; compare scopes and
all effective grants; write it as a new KV version without changing other fields;
wait for ESO, roll the reviewed fixed image, verify all seven native fetches, then revoke old
PAT by recorded ID. Replacement overlap must end within 24 hours. Failed or
ambiguous replacement issuance is reconciled by token-name/ID inventory before
retry; no blind minting. Review retained KV versions/backups under platform's
retention policy; obsolete token copies are harmless only after target revocation.

Immediate revocation deletes the dedicated PAT by ID, then removes/disables only
this identity's team grants as approved. Compromise response reviews Forgejo
access/audit metadata and scans owned repositories and approved logs for leaks
without placing tokens in prompts. Use secret scanners/redactors and suppressed
negative probes. Availability strategy fails private refresh closed and marks
consented cache stale; public discovery continues. Never substitute privileged
personal/admin/core-hub credentials during issuer outage.

Elimination depends on Forgejo/native federation or an operationally viable
short-lived service credential, plus native consumer support. Revisit at rotation
and at target upgrades; retain a live owner record for that engineering debt.

## 4. Review notes (ops-mason phase 2, incomplete)

Reuse existing delivery identity and stores rather than introduce AppRole/static
ESO authority. The new PAT is isolated; caller writer policy stays byte-identical.
The proposed full ESO policy preserves every original byte before one added exact
read stanza; integration must compare current live and source digests. If policy
changed, rebase, review and pin a fresh digest rather than overwrite it.

Existing `ops_mason.executor` engines do not express Forgejo user/team/PAT and
shared-policy extension. Do not mislabel this JSON as a supported build_spec or
pass it to a single-KV builder: that could replace existing policy. Candidate
spec digest is SHA256 of UTF-8 sorted compact JSON with allow_nan=false. It
binds scope; it is neither approval nor an executable adapter. Platform must
allocate CCR, own a silent idempotent provisioner and pin all execution/artifact
inputs before phase 3. Approval of a construction plan does not supply a token.

This draft is not yet phase-3 ready. Gaps: scoped live structure survey, target
Q1–Q3 confirmation, effective-access enumeration design, reviewed platform CCR
and script, consumer raw-route/Bearer behavior, full authorization/redirect-fixed image and runtime allowlist proof plan, apps exact deployment
and headroom/PVC rollback plan, independent owner reviews. No owner review is
written on another repo's behalf. Only ops-mason's own preparation findings are
recorded here. No own autopilot grant or monetary risk limit is claimed.

## 5. Executive summary (candidate; not yet ready for approval)

1. **One-line ask.** Give the hosted capability hub a dedicated read-only account
   for the seven private repositories whose capability metadata you consented
   to publish, delivered using the existing workload-identity path.
2. **Who/what gets access.** Forgejo user `reuse-surface-source` obtains the
   seven-repository read grant; the existing `reuse-surface-runtime-eso` identity
   reads one additional exact custody entry for the hub. Namespace actors able
   to reuse the delivery store/Secret remain an exposure consideration to review.
3. **To what.** Read-only source access across the seven named private repositories,
   with no write/admin/non-code-unit grants. The hub publishes only the pinned
   consented capability metadata; repository visibility stays private.
4. **For how long.** Bao delivery tokens remain 15 minutes, but the Forgejo PAT
   has no expiry demonstrated. Proposed attended rotation is every 90 days with
   immediate revocation on compromise; this distinction must be accepted explicitly.
5. **Blast radius if the credential leaks.** Entire private source of those seven
   repositories can be read. The token must have no additional private-repository
   access and cannot write. Metadata disclosure consent is narrower than that read
   grant. Availability impact of controlled rollout remains owner-reviewed.
6. **Cost to reverse.** Revoke one PAT, remove only its dedicated grants, remove
   one new ESO data item and one new policy stanza, and roll the reviewed fixed image.
   Reconcile private registrations from the exact attempt; preserve the existing
   public capabilities and writer/webhook keys. No additional paid infrastructure
   is proposed (incremental estimate EUR 0); labor and credible loss remain unpriced,
   so this stays supervised.

After the missing reviews and executable inputs are attached, the founder can
**approve**, **reject**, or **send back to phase 1**. No founder disposition is
recorded for this credential proposal. Existing metadata consent is retained as
separate evidence and does not set status approved.

## 6. Proposed verification and rollback contract

This section describes future acceptance, **not a build result**. Phase 4 has not
run and no success evidence or active catalog entry exists.

Before changes: exact CCR/plan/script/manifest digests, owner reviews and founder
approved revision must match; metadata survey proves current path/policy/role;
source/consent pins match; all existing user/team conflicts resolved; previous
policy and deployment revision retained; apps runs dry-run and client diff,
confirms target node and headroom/PVC strategy. Never read or print Secret objects.

Before projecting any PAT into the hub: reuse owner patch must close native
both redirect Authorization forwarding and registration-controlled auth_env/URL
exfiltration. Tests must prove unlisted URL refusal before credential lookup and
no redirect credential forwarding. Apps must pin the full fixed image and exact
runtime allowlist configuration; review/migrate existing authenticated sources
before rollout. The earlier same-image and redirect-only assumptions are
superseded; full fixed image/source/patch and owner-runtime config approval remain
pending. The candidate allowlist encodes the consent packet exact fourteen URLs.

After target issuance, scope metadata must be exactly read:repository, team repo
set exactly seven and complete effective grants enumerated. Choose a known private
outside repo by target-owner metadata and prove denial without body retention.
Use safe read-only negative admin/non-code routes; never try writes as a negative
probe because unexpected privilege could make them succeed. Verify absence of
write authority through scope and effective permissions. Missing auth/anonymous
private raw reads fail closed, never cached as fresh successes.

Bao positive receipt proves ESO role exact path read; negative receipts prove
default identity and dedicated caller writer cannot read the new path, ESO cannot
read an unrelated sibling, and wrong SA/namespace/audience cannot authenticate.
These are effective token-specific checks, not a test on an admin session.
Owner suppressing helper checks ESO Ready and materialized key presence only.

In the actual running hub, native `fetch_remote_index_text` must fetch all seven
pinned URLs using `REUSE_SURFACE_FORGEJO_SOURCE_READ_TOKEN` and native header code;
validate schema, exact index hashes, exact expected IDs and relative entry handling
without printing private bodies. Local curl success is insufficient for native
runtime verification. Then register seven pinned sources with the approved writer
lane and force fresh composition; prove all 70 reviewed IDs exactly once, no stale
private fallback and matching metadata. Public URLs/entries and source bytes must
stay inside disclosure consent; new commits need renewed metadata review.

Rollback order: immediately revoke dedicated PAT; disable only new private
registrations after reconciling ambiguous requests; remove/revert exact new
ESO data item and policy stanza through owner paths; remove only the new
materialized token key with a suppressing helper, preserve writer/webhook keys;
controlled approved-image rollout. A previously vulnerable image must never
receive the new reader key; verify key removal before restoring such an image.
Restore previous pinned policy/deployment revision
when applicable. Retain partial, failed and unverified outcomes and token IDs.
Do not delete the shared Secret/store/role, overwrite unrelated policy changes,
or remove all public registrations. Restore only the new reader runtime mapping,
preserving separately reviewed existing authenticated-source mappings. No transactional rollback is claimed.