Repository navigation
design: gated passthrough for Muse (hold-connection approval PoC) - #13
Conversation
Design only. Passthrough route mode (no credential rewrite), header caller key, remote listener behind a TLS terminator, hold-the-connection approval, separate approval plane, trust-model changes, comparison with issue #5, staged plan with acceptance tests, open questions for the owner. Read: issues #5 (with comments), #6, #12; docs/design/phase1.md; README Deployment models; ap-core policy/headers/canon/config/audit/error; ap-proxy forward/pipeline/lib/listener and Cargo.toml (origin/main b3f7864). Ran: git status/log, ls, grep for timeout/Semaphore/ConcurrencyLimit/ header_read/keepalive in ap-proxy and ap-core src. No build or tests; nothing run against Muse or Discord.
Design only; no code. Verification: grep of the document for leftover removed items and for hostnames or reviewer names; no tests apply. Applied: header stripping and byte-for-byte definition, request deadlines, separate caller-rejected status, hold dedupe and abandonment handling, connect-failure outcomes, approve-after-forward semantics, PoC scope cuts, stage 1 POST probe, path-token redaction, approval page details, identity removal on reload, and extra stage 2 acceptance tests. Owner answers applied: TLS terminated by a self-run terminator with a loopback-only proxy; approval page uses Basic auth plus per-page CSRF token; cooldown on by default at 60 s. Path-prefix routing with a fixed route-to-host map.
ttmuse
left a comment
There was a problem hiding this comment.
Owner review. I have read the full document. Overall: the design holds up, and I am fine with proceeding to stage 1 as planned. The sequencing is the strongest part of this proposal: measure Muse's behaviour first, build the approval machinery only after the unknowns are answered.
What matches the decisions already made:
- Routing by name only; the upstream host comes from gate configuration, never from the request.
- Discord's response returns to the caller on the same connection. The caller needs no polling endpoint and no result slot.
- The approval plane is a separate listener with an independent credential, and the caller path has no route to it.
- The #5 invariants survive in connection form: approval bound to one immutable entry whose digest is computed over the canonicalized request, single execution per entry, and expiry as a terminal recorded refusal (410, no
Retry-After), not a state to poll.
The one trade-off I want to accept explicitly, since it is my decision to make (open question 11): this PoC supersedes the hash-bound one-time-proof path sketched for the platform-vault case. In this mode the real Discord token transits the gate and can rest in its memory for up to hold_secs. Section 4.3 states the resulting limit plainly (the gate constrains the agent, not the Muse platform itself), and the compensating controls in 4.2 are the right ones for a PoC: self-run TLS terminator, token never in audit, logs, pages or notifications, held requests in memory only and bounded. Accepted for the PoC, with the understanding that user-facing text for this mode carries the same wording as 4.3.
The kill risk is timing, and the document treats it correctly. The whole hold model depends on how long Muse waits before giving up, and on whether the TLS front cuts a long idle connection. Open question 1 being a stage 1 blocker, and the sleep probe running through the real tailscale serve front, are exactly right. If the measured window turns out to be shorter than a realistic human approval, the model dies there and stage 2 should not start.
Smaller points, none of them blockers:
- Audit:
forward_startedis written before the send, which is the right order. Keeping Phase 1's behaviour that a failed audit write does not refuse the request leaves a narrow gap (an execution with no record) that is worth revisiting before this leaves PoC status. - Supersede: when a retry supersedes a held entry, the approver may be mid-read on the older one. The approval page should make a superseded entry visibly distinct, not just gone.
- Attachments (question 12) need an explicit scope answer for the pilot: Discord file uploads are multipart and will exceed
held_body_max_bytes. My default is out of scope for the pilot (denied by the cap) unless we decide otherwise.
Answers I can already give: question 7, Basic auth plus a per-page CSRF token for the PoC is fine, WebAuthn stays the later replacement, and the approval API staying client-agnostic is a requirement, not a preference. Question 9: refuse a held-route request with no Authorization before it reaches the human, as proposed. Question 3's termination point is already decided (section 4.2). Question 10 (exact pilot policy scope: message create only, or also replies, reactions, edits and deletes) I will answer separately before stage 2.
Not a merge approval: as the PR says, design first. Proceed with stage 1.
|
Owner decision on scope, following up on my review: keep this PoC as small as possible. Validate first, expand later. Concretely:
And the inverse: if a probe result kills the hold model, we stop and rethink rather than broadening the design to route around it. |
Single refusal table with X-AP-Decision on every gate refusal; verbatim response keeps upstream x-ap-*; one ordered header algorithm; framing policy; first-upstream-byte rule for allowed bodies; split disconnect cases and named detection mechanism; full-request dedupe with in-memory fingerprint; approval page headers; ACL shape and distinct ports; generic header debug record removed; tailnet identity headers ignored and stripped; pilot scope, stop rule and answered questions; proposed audit-failure requirement for writes. Doc only; no build or tests run.
Doc only; no build or tests run.
|
Second-round review of MEDIUM
LOW
Review-comment scope decisions folded in
|
Content-Type rule refuses attachments; stage 1 limited to allow/no_grant with held-route cases moved to stage 2; single-record audit for allowed requests, transitions for held; audit_unavailable applied at held write; two forward milestones; approve results table; deadline scope, 413 row, dedupe header assumption. Doc-only, no code run.
|
Review of Attachments (MEDIUM)
Stage 1 scope (MEDIUM)
Audit model (MEDIUM)
Audit-failure rule (MEDIUM, LOW)
Approve results (LOW)
Smaller items (LOW)
Owner decisions are unchanged, and the document still contains no tailnet hostnames, IPs or logins. Not merging. |
Design only. No code, no behaviour change. Refs #6.
Summary
A minimal proof of concept for gating Discord API calls made by Muse. A user creates a Muse custom connector pointing at our base URL with a caller-key header. Muse swaps its surrogate for the real Discord credential before the request reaches us. We do not swap or store credentials. We decide only whether to let the request through.
Authorization. The caller key travels in a dedicated header and is stripped before forwarding, along with front-added proxy headers./discord/api/v10/...). A route name maps to a fixed host in policy, never to a host from the request. Unknown names fail closed.tailscale serveon the owner's node, reachable only from Muse's node by ACL or tag. Tailnet identity headers are defence in depth and are stripped.default-src 'none'. Token segments of/webhooksand/interactionspaths are redacted in audit, page and notification.Stage plan
tailscale serveinterrupts a long idle connection.Single-instance only for the PoC.
Open questions for the owner
Questions 1 to 4 block stage 1. The full list is in the document, section "Open questions". It includes:
Authorizationheader when its swap fails.Already answered by the owner: self-run TLS terminator, Basic auth plus CSRF for the approval page, cooldown on by default at 60 s.
Not to be merged until the owner has reviewed.