# Companion App — Phase 2 Session Prompt (Loopback Endpoint Security Core)

**Use this to seed a fresh chat session.** Start that session on a **thinking model (Opus)** — Phase 2
is a full 🧠 phase (adversarial security reasoning), not Hybrid.

---

## 0. Copy-paste prompt (paste this into the new session)

```text
You are continuing the Knowtation Companion App build on the Muse branch feat/companion-app.
This is PHASE 2 — Loopback Endpoint Security Core. It is a 🧠 Thinking phase: DNS-rebinding and
cross-origin abuse are adversarial; the defense must be argued against an attacker model, not
pattern-matched. Stay on a thinking model for the whole phase.

FIRST, read these in full (do not skip):
  - docs/COMPANION-APP-DESIGN-AND-AUTHORIZATION-GATE.md  (esp. §4 the 8 loopback controls;
    §13 Phase 0 Decision Record D1–D3; §12 phase table; the "DOES NOT approve (no code)" list)
  - docs/COMPANION-APP-MODEL-ROUTING-AND-ENRICHMENT-ARCHITECTURE.md  (§3 client-side constraint,
    §5 OAuth, §8.1 localhost security, §8.3 prompt injection)
  - docs/COMPANION-APP-PHASE-1-ADAPTER-SEAM.md  (the seam this phase plugs into)
  - lib/model-runtime-lane.mjs  (Phase 1 output: selectLane/isManagedLane/enforceConsentPolicy)
  - hub/bridge/server.mjs  (the service the companion evolves from — auth/token/CORS patterns)
  - hub/gateway/gateway-cors-middleware.mjs and test/gateway-cors-middleware.test.mjs (existing
    Origin/CORS handling to stay consistent with)

RESOLVE THIS SCOPE QUESTION BEFORE WRITING ANY SOCKET CODE (ask me):
  The gate's "DOES NOT approve" list forbids "opening any new local HTTP listener / loopback model
  endpoint in any repo." Phase 0 is now accepted, which unblocks companion implementation per the
  gate's own logic — but the actual listening socket is the single most security-critical surface.
  Proposed scope (mirrors how Phase 1 shipped pure, testable logic with no I/O):
    Phase 2 builds the REQUEST-GUARD as pure, fully-tested functions (token verify, Host allowlist,
    Origin/Sec-Fetch-Site check, rate-limit decision, ambient-authority boundary) WITHOUT binding a
    real socket. The actual listener bind is deferred to Phase 5 (companion shell) or a separate
    explicit gate. Confirm this scope, or get my approval to open a real loopback listener now.

THEN produce, in order:
  1. A short adversarial THREAT MODEL section (attacker capabilities: malicious web page in the
     user's browser, DNS-rebinding to make a remote origin appear same-origin, a local non-browser
     process, a prompt-injection payload in a note body). For each, the exact control that stops it.
  2. lib/companion-loopback-guard.mjs — pure functions, no I/O, no env reads:
       verifyLoopbackRequest({ method, headers, token, expectedToken, allowedHosts, now, rateState })
         → { allow: boolean, status: 200|401|403|429, reason: string }
     enforcing gate §4 items 1,2,3,5,6,8 at the request-decision level. Fail-closed on anything
     ambiguous or missing. Constant-time token comparison (no early-exit string compare). Never
     include the token/JWT/note body in the returned reason or any thrown error.
  3. The 7-tier test suite test/companion-loopback-guard-*.test.mjs. The SECURITY tier is the
     centerpiece and must cover, at minimum: missing token (401), wrong token (401, constant-time),
     bad Host header → DNS-rebinding rejection (403), cross-site Origin/Sec-Fetch-Site rejection
     (403), no-wildcard-CORS, rate-limit trip (429), no ambient authority (guard exposes only the
     inference decision — never vault/canister/JWT), note-body-as-data (an injection string in the
     body cannot alter headers, host, or the decision), and NO secret in any output/log/error.
  4. docs/COMPANION-APP-PHASE-2-LOOPBACK-SECURITY.md — the accepted design + the guard contract +
     the threat-model→control mapping + what Phase 5 must do to bind the socket safely.

CONSTRAINTS:
  - Muse-canonical (knowtation). Commit on feat/companion-app via `muse code add` + `muse commit`.
    Do NOT open a docs-only PR to main (owner policy). Do NOT use git/gh for knowtation work.
  - Aaron's standards: 7 test tiers + strong docstrings; no temporary fixes; no assumptions stated
    as fact (verify against source); fail-closed on ambiguous permissions; security first.
  - Honor gate §4: "A future implementation that omits any of items 1–3, 5, or 6 fails this gate."
  - Verify the full suite is green before committing. Give a plain-language + technical summary and
    a clear recommendation when done (Rule #7).

When Phase 2 is complete and committed, recommend whether Phase 3 (OAuth native/public client,
PKCE + loopback redirect, JWT in OS keychain) is the next 🧠 session or whether to batch it.
```

---

## 1. Where we are (state at end of this session)

**Branch:** `feat/companion-app` (Muse-canonical, knowtation). Two prior commits on it:
- Phase 0 Decision Record (gate §13, D1–D3) — `444d712`.
- Phase 1 seam + 7-tier tests — `06bcc48`; revised by `d2354ec` (D1.3(2) gate + org-privacy ordering).

**Scooling cross-repo:** `feat/phase3e5-authorization-checklist` commit `3282480` added
`lane_policy_denied` to `ModelResponse` and updated the mock adapter. (Scooling uses git, not Muse.)

**Phase 0 (accepted decisions):**
- **D1** — tenancy + owner-vs-member billing/consent. Owner is billing principal for ops on the
  owner partition; delegate managed-lane spend is default-OFF (`delegatedManagedAllowed`); delegated
  companion/openrouter enrichment is default-OFF (`delegatedEnrichmentAllowed`, D1.3(2), ratified).
  Prerequisite: a separate tenancy implementation gate (auto-owner provisioning, role store, invites,
  effective/owner billing identity) before any companion phase writes to a delegated partition.
- **D2** — lane matrix + default-lane logic + client-side-inference hard constraint, mapped to
  Scooling `runtimeLaneSchema`.
- **D3** — derived-artifact storage per tier (Convenience = cloud; Privacy-max = local-only or
  client-encrypted, never host-readable nor under a server-held key).

**Phase 1 (built, tested, committed):** `lib/model-runtime-lane.mjs` — `selectLane`, `isManagedLane`,
`enforceConsentPolicy`. Pure functions, 120 tests across 7 tiers, all green. This is the seam Phase 2
plugs into: **Phase 2's guard sets `companionAvailable = true` in the Phase 1 `LaneCapabilities` only
after the loopback request passes the token + Host/Origin checks.**

## 2. What Phase 2 is (gate §12, row 2 — 🧠 Thinking)

> **Loopback endpoint security core** — per-session bearer token, `Host`/`Origin` allowlist,
> DNS-rebinding defense, non-predictable port, loopback bind, no ambient authority, untrusted-input
> handling (§4 items 1–8). Depends on Phase 1. This phase, and its security tests in Phase 9, are the
> highest-leverage place for a thinking model.

## 3. The 8 mandatory controls (gate §4 — verbatim intent)

1. **Bearer token on every request** — high-entropy, per-session, OS keychain; `401` without the
   exact token, before any model work. **(hard-fail if omitted)**
2. **Strict `Host` header allowlist** — accept only `127.0.0.1:<port>` / `localhost:<port>`; else
   `403`. Primary DNS-rebinding defense. **(hard-fail)**
3. **Strict `Origin`/`Sec-Fetch-Site`** — reject cross-site origins; no wildcard CORS; no reflecting
   arbitrary `Origin`. **(hard-fail)**
4. **Non-predictable ephemeral port** — defense-in-depth, never the sole control.
5. **Loopback bind only** — `127.0.0.1`, never `0.0.0.0`. **(hard-fail)**
6. **No ambient authority** — exposes only model inference; never vault read/write, the canister
   client, or the stored JWT. **(hard-fail)**
7. **Untrusted-input handling** — note bodies are passed to the model strictly as data, never as
   instructions or as a source of headers/URLs (prompt-injection threat model, brief §8.3).
8. **Rate limiting + minimal logging** — bound request rate; never log token, JWT, or note bodies.

## 4. Threat model to reason against (do not pattern-match — argue each)

- **Malicious web page in the user's browser** issuing `fetch` to `http://127.0.0.1:<port>`. Stopped
  by: bearer token (1) it cannot know + Origin/Sec-Fetch-Site (3).
- **DNS-rebinding** — attacker rebinds a domain to `127.0.0.1` so the browser treats it as
  same-origin; the request arrives with the attacker's `Host`. Stopped by: strict `Host` allowlist (2).
- **Local non-browser process** probing the port. Stopped by: token (1) + non-predictable port (4).
- **Prompt injection in a note body** trying to set headers / change the URL / issue instructions.
  Stopped by: untrusted-input handling (7) — body is data only.
- **Secret exfiltration via logs/errors.** Stopped by: minimal logging (8) + never echoing
  token/JWT/body in any output.

## 5. Proposed deliverables (confirm scope first — see §0 scope question)

- `lib/companion-loopback-guard.mjs` — pure `verifyLoopbackRequest(...)` returning an allow/deny +
  HTTP status + reason; constant-time token compare; fail-closed. **No socket binding in Phase 2.**
- `test/companion-loopback-guard-*.test.mjs` — 7 tiers; security tier is the centerpiece.
- `docs/COMPANION-APP-PHASE-2-LOOPBACK-SECURITY.md` — accepted design + guard contract + threat→control
  map + the safe-bind checklist Phase 5 must satisfy when it opens the real listener.

## 6. Definition of done

- Scope question resolved with the owner before any socket code.
- Guard enforces §4 items 1,2,3,5(as a documented bind-time obligation),6,7,8 at the decision level.
- 7-tier suite green; security tier covers every threat in §4 above.
- Constant-time token comparison; no secret in any return value, log, or error.
- Committed on `feat/companion-app` via Muse; no docs-only PR to `main`.
- Plain + technical summary with a recommendation (Rule #7), and a Phase 3 go/batch recommendation.

## 7. Open questions to settle at session start

1. **Scope:** pure guard now, socket bind deferred to Phase 5 (recommended) — or approve a real
   loopback listener in Phase 2?
2. **Rate-limit shape:** token-bucket vs fixed-window; per-session vs per-port. (Pick one, justify.)
3. **Host allowlist source:** does the guard receive the bound port from the caller (recommended,
   keeps it pure) or read it itself? (Recommended: caller passes `allowedHosts`.)