Skip to content

docs(pairing): plan TUI QR bootstrap and E2EE mobile pairing (refs #785) - #8

Open
CompleteDotTech wants to merge 6 commits into
mainfrom
agent/issue-785-plan-tui-qr-bootstrap-and-end
Open

docs(pairing): plan TUI QR bootstrap and E2EE mobile pairing (refs #785)#8
CompleteDotTech wants to merge 6 commits into
mainfrom
agent/issue-785-plan-tui-qr-bootstrap-and-end

Conversation

@CompleteDotTech

@CompleteDotTech CompleteDotTech commented Aug 30, 2026

Copy link
Copy Markdown
Owner

Summary

Implements the plan deliverable for the TUI QR bootstrap and end-to-end encrypted mobile pairing issue: a concrete, code-cited plan document at docs/architecture/mobile-device-pairing-tui-bootstrap-plan.md, sibling to the pairing protocol contract and delivery train it elaborates.

The plan covers:

  • coven device command family — pair, pair --scope, countdown/status/cancel, device administration, with a compatibility alias for the existing coven memory mobile surface (crates/coven-cli/src/mobile_memory/).
  • Canonical CBOR pairing offer — versioned, deterministic encoding with pairing_session, fresh ephemeral key, host fingerprint pin, rendezvous hints, requested_capabilities_hash, and expiry; carried by a Universal Link fragment (camera hand-off) plus the existing custom scheme; diagnostic TS types and JSON Schema delta included.
  • Noise_XK_25519_ChaChaPoly_SHA256 handshake — pattern evaluation table (XX/KK/XK/IK) with the recommendation justified by the QR-pinned host key; transcript binding of offer bytes (prologue), versions, keys, capabilities, and nonces; secret erasure on every terminal path; bounded handshake attempts.
  • Rendezvous relay MVP — outbound-only connections from both endpoints using the existing bounded opaque room relay (crates/coven-relay/src/ws.rs), with room/token derivation rules, frame bounds, and a direct-LAN fallback.
  • Human verification — six-word phrase (existing 2,048-word list) re-derived from the final Noise handshake hash; both-endpoint confirmation.
  • Capability binding — contract-vocabulary to DeviceScope mapping (crates/coven-cli/src/mobile_memory/grant.rs), sorted canonical capabilities hash, hard-blocked export scopes.
  • Adversarial test matrix — replay, substitution, MITM, downgrade, relay, malformed input, bounded attempts, cross-correlation, cancellation, plus golden vectors, each mapped to a test level and the issue's acceptance criteria.
  • Workstream graph D1–D6 with exit criteria and PR slicing, plus eight maintainer decision points (each a recommendation with alternatives considered).

Current state is documented with citations to the shipped pairing v2 implementation (pairing.rs, grant.rs, auth.rs, gateway.rs, identity.rs), so reviewers can verify every claim against code. Docs-only change: no code, build, or dependency modifications.

Issue

Refs OpenCoven#785 (parent OpenCoven#784).

Per the delivery plan's merge policy ("avoid closing a plan issue until its acceptance criteria are demonstrated, not merely scaffolded"), this PR does not close OpenCoven#785 — the issue stays open for the implementation slice it plans.

Test plan

Local checks run for this docs-only change (checked):

  • python scripts/check-secrets.py — passed (current tree + history)
  • python3 scripts/check-coven-privacy.py --staged — passed
  • git diff --check — clean
  • python3 scripts/check-api-contract-docs-test.py / check-api-contract-docs.py — passed
  • check-coven-privacy-test.py (114 tests), check-secrets-test.py (33 tests) — passed

Deferred to CI (unchecked):

  • CI policy-guard and routed docs-only jobs on the PR merge commit

Rust/TS builds are intentionally not exercised locally: no cargo/rustc toolchain in the authoring environment and the diff contains no code.

Vehicle note: opened in the fork CompleteDotTech/coven as the CI vehicle — this token cannot write to OpenCoven/coven. Re-target upstream once write access is restored. Refs OpenCoven#785.

@CompleteDotTech CompleteDotTech self-assigned this Aug 30, 2026
@CompleteDotTech
CompleteDotTech marked this pull request as ready for review August 30, 2026 15:54
@CompleteDotTech CompleteDotTech mentioned this pull request Aug 30, 2026
Merged
6 tasks
@CompleteDotTech
docs(automations): record Coven Automations v1 program status (coven#…
44b540e 
…854) (OpenCoven#861)

Adds one dated status/decision record for issue OpenCoven#854 in docs/superpowers/plans/.

Independently verified against main @ 1364cec (2026-08-30): the coven#816
foundation series (PR OpenCoven#846, PR OpenCoven#847, parts 6-8 commits) landed the durable
local scheduler core - definitions, SQLite definition/occurrence/run records
with unique occurrence fencing, RRULE planning, bounded leases with expiry
recovery, latest-only misfire / overlap refusal, the 60s daemon tick with
scheduled dispatch, shared launch path, health and run history,
non-destructive paused legacy import, and coven.automations.* control
actions. Records what is still absent for v1 (versioned protocol schemas,
authority/receipt binding, deterministic-time contract, SDK surface,
conformance/chaos/SLO gates, live Beads mutation), the gate-by-gate verdict,
and the critical path. The program issue remains open; this record closes
no issue.

Refs OpenCoven#854.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs: plan cryptographic fresh-user and biometric assurance proofs (c…
fb302f2 
…oven#815) (OpenCoven#871)

* docs: plan cryptographic fresh-user and biometric assurance proofs (coven#815)

Specify COVEN-ASSURANCE/1, an independently verifiable step-up proof so
request authentication can satisfy FreshUserVerification/FreshBiometric
grant requirements without trusting client-asserted assurance levels.

The plan defines: possession/step-up key separation; binding the optional
step-up authorization key and its declared assurance class into the
pairing-v2 transcript; a separate authorization-key store; canonical
proof bytes over device, grant, revocation epoch, exact request or
DeviceActionIntent digest, server-issued single-use challenge, window,
and requested assurance; server-side effective assurance computed as
min(claimed, class ceiling) and passed to DeviceGrant::authorize;
fail-closed possession-only degradation; rotation/revocation semantics;
iOS/Android platform mapping; a self-verifying synthetic golden vector;
and TypeScript/JSON Schema for implementers. Every claim cites the
current mobile_memory code path it builds on.

No code changes: this is the design artifact the issue asks for.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs(mobile): specify COVEN-ASSURANCE/1 step-up assurance proofs

Add docs/design/mobile-assurance-step-up-v1.md, the plan and
implementation contract for issue OpenCoven#815: a separately enrolled,
platform-policy-protected step-up authorization key, bound into the
pairing-v2 transcript before grant issuance, whose fresh signatures
over canonical COVEN-ASSURANCE/1 bytes (device, grant, revocation
epoch, exact request or DeviceActionIntent digest, single-use server
challenge, validity window, requested assurance) are the only way to
raise assurance above possession. The server verifies the signature,
computes effective assurance itself, and passes it to
DeviceGrant::authorize; absent/invalid/expired/replayed proofs fail
closed. Covers storage separate from the possession key, replay
protection independent of request nonces, rotation/revocation
semantics, iOS/Android key-policy mapping, a security-invariant
mapping, TypeScript types + JSON Schema, and a portable golden vector.
Design artifact only; no behavior change.

Refs OpenCoven#815

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs: operationalize Coven Automations v1 tracker roadmap and drift c…
fcc026c 
…heck (coven#859) (OpenCoven#862)

Establish the GitHub-side half of the OpenCoven#859 operational delivery graph:

- docs/roadmaps/coven-automations-v1.md: program roadmap with canonical
  tracker roles, sync metadata, P0/P1/P2 policy, generated outcome-mapping
  table, dependency graph, release gates, active blockers, and drift
  detection usage. The mapping table block is generated by
  docs/roadmaps/drift-check.mjs --render and verified on every run.
- docs/roadmaps/coven-automations-v1.mapping.json: machine-readable
  one-to-one Bead <-> GitHub mapping for OpenCoven#854, OpenCoven#816, OpenCoven#855, OpenCoven#856, OpenCoven#857,
  and OpenCoven#858, with explicit dependencies, acceptance gates, dispositions,
  and evidence links. Bead IDs stay null (warn-level W010) until
  provisioning lands through OpenCoven/coven-cave#5220 per the
  operational correction on OpenCoven#859; no competing Beads store is created
  in this repository.
- docs/roadmaps/drift-check.mjs: credential-free, offline drift check
  covering state, priority, parent/dependency, evidence, generated-mirror,
  duplicate/missing mapping, cycle, and sensitive-payload drift classes,
  with --beads-export cross-checking and --selftest proving detection.
- docs/superpowers/plans/2026-08-30-issue-859-coven-automations-v1-...md:
  dated status/decision record: what exists on main (automations series
  landed 2026-08-28 via PRs OpenCoven#846/OpenCoven#847), pre-change integrity report,
  decisions D1-D7, verdict against the OpenCoven#859 acceptance criteria,
  remaining work, critical path, and the initial evidence packet.

Refs OpenCoven#859



fix: keep automation tracker docs scanner-safe

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-785-plan-tui-qr-bootstrap-and-end branch from 4ea617f to b98362d Compare August 30, 2026 17:47
CompleteDotTech and others added 3 commits August 30, 2026 13:48
@CompleteDotTech
docs: consolidate Coven security policy, threat boundary, and support…
957715f 
… claims

* docs: consolidate Coven security policy, threat boundary, and support claims

Replace the duplicated SECURITY.md (repository policy plus a copied
organization-wide disclosure addendum) with one Coven-specific operational
security contract that visibly separates:

- supported release family and security-supported surfaces, with
  experimental/disabled surfaces (AFS mount backend, OpenClaw plugin,
  remote transports) marked explicitly;
- enforced properties today, each tied to its normative contract and
  verification family (Rust authority checks, capability advertisement,
  pre-effect validation, owner-protected local transport, redaction and
  artifact defaults, secret/privacy guards, explicit mutation replay);
- residual risk and safe configuration (same-user trust vs sandboxing,
  raw-artifact opt-in, retention limits, untrusted harnesses, AgentFS
  mount posture synced with OpenCoven#779);
- private reporting via GitHub Security Advisories as the primary path,
  with no personal-channel dependency and no unsupported response-time
  commitment, plus scoped third-party dependency/provider handling;
- design goals (session/memory/agent isolation) moved out of guarantees,
  cross-referencing OpenCoven#803/OpenCoven#804 instead of claiming unimplemented A2A
  isolation.

Removes the stale OpenTrust-scope addendum, the personal Discord DM
reporting path, and the 48-hour/14-day response promises that no
accountable process currently backs.

Refs OpenCoven#808

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix: document tokenized invite URL privacy rule

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs(pairing): plan TUI QR bootstrap and E2EE mobile pairing (refs Op…
de85cf4 
…enCoven#785)

Add the implementation plan for issue OpenCoven#785: the coven device command
family, canonical CBOR pairing offer with Universal Link encoding,
Noise_XK handshake with QR-pinned host authentication, rendezvous relay
MVP on coven-relay, six-word human verification derived from the
handshake hash, scope selection and capability binding, the adversarial
test matrix, and the maintainer decision points.

Extends the accepted mobile-device-trust architecture and elaborates
PR 3 + the rendezvous slice of PR 4 of the pairing delivery train.
Docs-only change; cross-links the delivery plan to the new plan.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
chore(pairing): retrigger CI for the plan PR (no content change)
008eb85 
The pull_request opened event raced the fork's lazy workflow
registration, so no run was created. This empty commit re-emits the
synchronize event; it changes no content.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-785-plan-tui-qr-bootstrap-and-end branch from b98362d to 008eb85 Compare August 30, 2026 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@CompleteDotTech CompleteDotTech

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Plan: TUI QR bootstrap and end-to-end encrypted mobile pairing

1 participant

@CompleteDotTech