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

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