deb11df783
Bind broker sessions to Linux SO_PEERCRED and /proc starttime ancestry, fence runtime generations, persist cryptographic single-use cycle tokens, and enforce protected Unix socket/state posture.\n\ncloses #828
67 lines
4.8 KiB
Markdown
67 lines
4.8 KiB
Markdown
# WI-1 Scratchpad — Authenticated external lease broker
|
|
|
|
- **Issue:** Gitea #828
|
|
- **Milestone:** 188 — Compaction-Refresh Mechanism (M1: Claude + Pi)
|
|
- **Branch:** `feat/828-lease-broker`
|
|
- **Starting HEAD:** `d801d6c4c8a984d6a95033c49714210018d3d9a8`
|
|
- **Session role:** Orchestrator coordinating implementation; Mos retains merge authority.
|
|
|
|
## Objective
|
|
|
|
Implement the ratified WI-1 product lease broker under `packages/mosaic/`: Linux `SO_PEERCRED` identity, broker-minted logical session IDs, `(pid,starttime)` launcher anchors with per-hop `/proc` starttime revalidation, sibling-substitution rejection, same-PID runtime-generation revocation, crypto-RNG single-use token persistence, and protected Unix-socket posture.
|
|
|
|
## Authority verification
|
|
|
|
Verified before code on session start; all exact SHA-256 values matched:
|
|
|
|
- BUILD-BRIEF: `89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b`
|
|
- SPEC-v5: `a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433`
|
|
- Ratification: `bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67`
|
|
- P6 planner ruling: `b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09`
|
|
- WI-0 Gate0 evidence: `5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d`
|
|
|
|
## Locked constraints
|
|
|
|
- Build against the ratified design; do not re-derive it.
|
|
- Product code only in `packages/mosaic`; Gate0 Python probes are reference prototypes and are not shipped.
|
|
- Caller-supplied/asserted `session_id` is refused.
|
|
- Tokens use the operating-system CSPRNG via Python `secrets`; never `Math.random` or model output.
|
|
- Socket parent directory mode `0700`, socket mode `0600` minimum; document distinct-principal deployment as the stronger T-C-closing posture.
|
|
- Red-first TDD for six named cases; new-code coverage >=85%.
|
|
- No merge. PR must say `closes #828`; exact 40-character head handed to Mos for Opus-SECREV and independent review.
|
|
|
|
## Plan
|
|
|
|
1. Load security/testing/docs guidance and inspect existing `packages/mosaic` architecture.
|
|
2. Write the six required tests first and capture RED evidence.
|
|
3. Implement minimal broker modules and CLI/runtime integration necessary for product use.
|
|
4. Run focused tests with coverage, package gates, then full repository gates/suite.
|
|
5. Run author-side review/remediation, commit `closes #828`, queue guard, push, and open PR through Mosaic wrappers.
|
|
6. Send PR number + exact head SHA to `web1:mosaic-100`; stop without merging.
|
|
|
|
## Risks / boundaries
|
|
|
|
- Same-UID counterfeit socket replacement remains the disclosed T-C residual unless broker runs under a distinct principal; filesystem modes alone are minimum hardening, not a complete authenticity proof.
|
|
- `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` were already modified at session start and must not be included in this PR.
|
|
- Repository Woodpecker pipelines exist; CI is the canonical build path. No manual image build/deploy is in scope.
|
|
|
|
## Progress / evidence
|
|
|
|
- 2026-07-18 session start: mandatory mission files and orchestration guides loaded.
|
|
- STEP 0: all four authority hashes matched; artifacts read in full.
|
|
- Branch/HEAD confirmed; issue #828 open; Gate0 evidence hash confirmed.
|
|
- Initial RED: focused Vitest acceptance suite failed 11/11 because the product daemon did not exist; the expected missing-product failure was observed before implementation.
|
|
- Review-remediation RED: partial/zero-progress state writes, nested corrupt state, symlink state, canonical starttime, and duplicate-anchor generation behavior failed before their fixes. Real socket RED/GREEN runs were executed by the unrestricted parent harness because the delegated worker sandbox denies `AF_UNIX.bind()`.
|
|
- Product implementation added at `packages/mosaic/framework/tools/lease-broker/daemon.py`; Gate0 probe scripts were read as references but not copied or shipped.
|
|
- Independent Codex code review round 1 found 2 blockers + 1 should-fix (connection stall/crash, partial writes, packet-dependent framing); all were remediated with tests.
|
|
- Independent Codex code review round 2 found 2 blockers + 1 relevant should-fix (half-close contract ambiguity, incomplete persisted-state validation, symlink/non-regular state); all were remediated with tests and documentation. Pre-existing `.mosaic/*` session dirt remains excluded from the PR.
|
|
- Unrestricted focused situational suite: `35/35` GREEN.
|
|
- New Python product module coverage: `90%` (`356` statements, `36` missed), above the user-required 85%.
|
|
- Root typecheck and lint gates passed after remediation; final package/full-suite/format evidence is recorded below before push.
|
|
|
|
## Coordinator handoff requirements
|
|
|
|
1. Mandatory Opus-SECREV on the exact PR head; no GPT/terra substitute.
|
|
2. Independent exact-head code review and exact-head RoR before Mos-authorized merge.
|
|
3. Mos retains merge authority; this WI author stops after PR + full 40-character head handoff.
|