diff --git a/docs/decisions/pending-decisions.md b/docs/decisions/pending-decisions.md index 4fc3fac..ed777f8 100644 --- a/docs/decisions/pending-decisions.md +++ b/docs/decisions/pending-decisions.md @@ -61,3 +61,32 @@ - Secret boundary: P01 commands accept no Token, password, API Key, Cookie, Authorization header, or NAS credential fields. SQLite stores only non-sensitive metadata and future opaque credential references. - Rationale: AGENTS.md gives the architecture document higher priority, and the selected split keeps runtime connection behavior out of P01. - ADR: `ADR-0004-profile-lifecycle-and-secret-boundary.md`. + +## PD-0009: Real AstrBot Desktop Gateway contract + +- Status: open; does not block local slot persistence or Mock-based tests +- Current contract: repository-local `/desktop/v1` and protocol `1.0` are provisional development contracts created during P00. +- Missing authority: no reviewed real AstrBot Gateway implementation or server-side contract is available for endpoint, error-code, capability, event-retention, ACK, and authentication compatibility. +- Safe interim rule: keep the protocol types and dual Mock Gateway deterministic, but do not claim real AstrBot compatibility or silently adapt to AstrBot internal APIs. +- Stop boundary: changes that would require modifying AstrBot core or bypassing the stable Gateway boundary require explicit review. + +## PD-0010: Credential enrollment and token lifecycle + +- Status: open before production connection activation +- Established boundary: credential values live only in Windows Credential Manager; SQLite stores opaque references; React never receives stored access or refresh tokens. +- Required decision: define enrollment/update/delete failure atomicity, whether user-entered bootstrap credentials may pass once through bounded Tauri IPC without entering React state, and how access/refresh token rotation updates secure storage. +- Safe interim rule: P02 slot persistence accepts no credential values and cannot activate a real connection. + +## PD-0011: Authoritative server identity enrollment + +- Status: open before first real connection activation +- Candidate source: `GET /desktop/v1/server-info` returns `server_instance_id`, matching the architecture and provisional protocol. +- Required decision: define the first-contact confirmation flow, duplicate-instance warning behavior, and whether a changed identity requires a separate Profile or an explicit rebind operation. +- Safe interim rule: never overwrite an existing `server_instance_id` during background connection or reconnection. + +## PD-0012: TLS certificate fingerprint binding + +- Status: open before enabling pinned HTTPS Profiles +- Requirement: a certificate identity change freezes local-tool permission and the affected connection; TLS validation must never be disabled. +- Required decision: select a maintained Rust TLS integration that can inspect the validated peer certificate without installing a permissive verifier, and define first-contact confirmation UX. +- Safe interim rule: preserve validated HTTPS behavior and do not claim certificate pinning until the peer certificate path is implemented and tested. diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index c236918..e4e1164 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -37,7 +37,7 @@ Establish a reproducible Tauri 2 + React + TypeScript + Rust baseline and comple - Forgejo runner labels/jobs remain unverified, so the committed workflow is not claimed successful. - Real UNC execution still requires a user-authorized disposable fixture. -## P01 Foundation (active) +## P01 Foundation (completed) ### Objective @@ -72,3 +72,34 @@ Turn the P00 Spike skeleton into a durable application foundation. Under the pro - Real Tauri development startup reached the Windows executable and was then deliberately terminated. - Windows release and NSIS bundling passed. - Forgejo CI remains unverified because a compatible runner/jobs endpoint is unavailable. + +## P02 Dual Connections (active) + +### Objective + +Add durable companion and operations slot assignment, then build two independent Rust-owned REST/SSE runtimes without weakening the P01 credential and profile boundaries. + +### Ordered work + +1. Persist the two fixed connection slots and enforce that one Profile cannot occupy both slots. +2. Add bounded slot list/assign/clear IPC and a minimal settings UI for slot selection. +3. Add auto-connect validation: at most two Profiles, one per slot, with no duplicate Profile assignment. +4. Add an operations-switch guard that blocks Profile changes while an operations task is active. +5. Add duplicate `server_instance_id` detection and surface a warning without silently merging Profile identity. +6. Define the production credential enrollment/update/delete lifecycle entirely in Rust, with opaque references in SQLite and no secret values returned to React. +7. Review the provisional Gateway contract before enabling real configured connections; keep real AstrBot compatibility explicitly unclaimed until the server contract is available. +8. Implement independent REST discovery/authentication and SSE runtimes, per-Profile cancellation, replay cursors, de-duplication, retry state, and error state. +9. Integrate the existing dual-instance Mock Gateway and verify that one instance failure or auth expiry does not affect the other. +10. Add frontend/Rust/integration coverage, update protocol and progress documents, run the full stage checks, and push the branch normally without merging `main`. + +### Safety gates + +- Slot work must not accept or expose Token, password, API Key, Cookie, Authorization header, or NAS credentials. +- A server-supplied `profile_id` is never trusted; the Rust connection object binds every event to its local Profile and slot. +- A changed `server_instance_id` or certificate identity freezes the affected connection instead of silently rebinding it. +- Companion Profiles never gain local-tool authority from slot assignment alone. +- The provisional `/desktop/v1` contract and Mock Gateway are not evidence of compatibility with an unreviewed real AstrBot Gateway. + +### First increment + +Implement SQLite schema v3 for the two fixed slot assignments, bounded list/assign/clear commands, database and command tests, and a minimal Profile-slot settings surface. This increment intentionally excludes network activation and credential values. diff --git a/docs/progress.md b/docs/progress.md index 9b410b4..4158fb9 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -2,7 +2,7 @@ ## Current phase -P01 foundation is complete and published on `feat/p01-foundation`. The option A boundary is resolved: basic non-sensitive Profile metadata CRUD belongs to P01, while slots and runtime connection behavior remain in P02. +P01 foundation was merged through Forgejo PR #2 at `885abd1`. Development now continues on `feat/p02-dual-connections`, starting with persistent companion/operations slot assignment and its local safety constraints. ## Completed @@ -27,14 +27,23 @@ P01 foundation is complete and published on `feat/p01-foundation`. The option A - Re-ran a real Tauri development startup and reached the Windows executable. - Rebuilt the Windows release executable and NSIS installer. - Recorded the Profile boundary in PD-0008 and ADR-0004. +- Verified Forgejo PR #2 was merged at `885abd1553ed8f1428de7118a6f4b59f7e22a45c`. +- Fast-forwarded local `main` to the same remote merge commit without rewriting history. +- Created `feat/p02-dual-connections` from the updated `main`. +- Re-read `AGENTS.md`, the Forgejo workflow, architecture design, and implementation task documents in full for P02. +- Kept the approved HTTP Forgejo URL repository-local and prevented the machine-wide HTTP-to-SSH rewrite from changing this repository's transport. ## In progress -- No code implementation is in progress; the branch is awaiting Forgejo PR review. +- P02 first increment: SQLite schema v3 and bounded companion/operations slot assignment. +- Protocol/security review for credential lifecycle, real Gateway authentication, authoritative server identity, and certificate-change freeze behavior. ## Remaining -- Create and review the P01 Forgejo PR; do not automatically merge `main`. +- Implement and verify the P02 slot persistence and UI increment. +- Implement auto-connect validation, operations switching protection, and duplicate server-instance warnings. +- Implement the formal Rust-owned credential lifecycle without returning secret values to React. +- Implement two independent configured REST/SSE runtimes only against a reviewed contract; continue using the dual Mock Gateway for deterministic tests. - Run Forgejo CI when a compatible runner is available. - Execute a real UNC transaction only after an authorized disposable fixture is supplied. - Add the combined end-to-end test that keeps configured streams active while the real Tauri window is hidden to tray. @@ -45,7 +54,9 @@ P01 foundation is complete and published on `feat/p01-foundation`. The option A - LAN SSH `192.168.31.210:18086` responds but rejects the available public key. - Approved HTTP Git push remains operational and is not blocked. - Forgejo runner labels/jobs could not be verified; the jobs API endpoint returned 404. -- No blocker remains for the selected P01 scope. +- Real AstrBot Gateway endpoints, authentication semantics, token refresh behavior, and server identity guarantees remain unavailable for compatibility verification. +- Certificate fingerprint extraction/pinning behavior must be designed without disabling TLS validation. +- These protocol items do not block the local P02 slot-persistence increment. ## Test status @@ -64,10 +75,11 @@ P01 foundation is complete and published on `feat/p01-foundation`. The option A ## Current branch -`feat/p01-foundation` +`feat/p02-dual-connections` ## Recent commits +- `885abd1 Merge pull request 'feat(p01): add secure profile foundation and management UI' (#2) from feat/p01-foundation into main` - `b3420e4 Merge pull request 'feat(p00): bootstrap Tauri desktop and validate high-risk spikes' (#1)` - `ed74342 feat(foundation): add persistent bootstrap safeguards` - `6a1eeab docs(p01): record foundation progress and profile boundary` @@ -78,4 +90,4 @@ P01 foundation is complete and published on `feat/p01-foundation`. The option A ## Next step -Open `feat/p01-foundation → main` as a Forgejo PR, review the recorded local verification, and run CI only when a compatible runner is available. +Complete the persistent companion/operations slot increment, run the relevant frontend and Rust checks, commit it as a focused Conventional Commit, and push `feat/p02-dual-connections` normally.