Document v1 external readiness gates

README.md

@@ -165,6 +165,8 @@ Read the [Security boundary](docs/security.md) and [threat model](docs/threat-mo
 - [OAuth guide](docs/oauth-support.md) — native remote OAuth and upstream-owned OAuth
 - [CLI reference](docs/cli.md) — commands, diagnostics, exit codes, logs, and [Troubleshooting](docs/cli.md#troubleshooting)
 - [Console guide](docs/console-api.md) — optional local dashboard and API
+- [v1 external evaluation](docs/v1-evaluation.md) — privacy-safe workflows, unaided first-use checks, and returning-user evidence
+- [independent security review brief](docs/independent-security-review.md) — review scope, deliverables, disclosure, and closure gates
 - [Security boundary](docs/security.md), [Threat model](docs/threat-model.md), [OAuth and Console security design](docs/oauth-console-threat-model.md), and [Architecture](docs/architecture.md)
 - [profile credential isolation](docs/config.md#profile-credential-isolation), [routing context](docs/config.md#routing-context), and [provider routing matchers](docs/config.md#provider-routing-matchers)
 - [Provider adapters](docs/provider-adapters.md), [plugins](docs/plugins.md), and [library API](docs/library-api.md)

docs/independent-security-review.md

@@ -0,0 +1,66 @@
+# Independent security review brief
+
+This brief defines the external review required by issues #37 and #39. It turns the public [threat model](threat-model.md) into a reviewable engagement without claiming that a review has happened.
+
+## Target and independence
+
+The engagement baseline is the current published release, `@lubab/miftah@0.5.8`. Before work starts, the maintainer and reviewer must record the exact commit and package version under review, the upstream dependencies or fixtures used, the operating systems exercised, and the review dates. The eventual v1 release candidate must receive either a final review at its exact commit or a reviewer-accepted delta review from the recorded baseline.
+
+The reviewer supplies an independence declaration covering employment, contribution, financial, and other material relationships with Miftah and its maintainers. A maintainer self-review, automated scanner, dependency report, or AI-only review is useful input but does not satisfy this independent gate.
+
+## Review scope
+
+Review the security claims and boundaries in [`threat-model.md`](threat-model.md), [`security.md`](security.md), and the OAuth and Console threat model. At minimum, cover:
+
+- configuration schema, migration, safe writes, permissions, symlink and replacement races;
+- secret references, environment and OS-vault boundaries, credential envelopes, and redaction;
+- child-process launch and shutdown, executable resolution, Windows job containment, and output handling;
+- profile, runtime, connection, OAuth, and container isolation, including wrong-account and cross-profile failure paths;
+- local HTTP, Console authorization, Origin and CSRF checks, loopback OAuth callback validation, state, issuer, PKCE, timeout, and cancellation;
+- routing, policy, approvals, connection locking, identity evidence, and fail-closed behavior;
+- audit integrity and the documented limits of local tamper evidence;
+- plugins, provider adapters, package contents, dependency and supply-chain boundaries;
+- denial-of-service, resource exhaustion, malformed upstream messages, and cleanup behavior.
+
+Include relevant Linux, macOS, and Windows paths when the implementation differs. The review may exclude a live third-party provider or unsupported client only when the report names the exclusion and explains how fixtures, code review, or residual risk cover it.
+
+## Expected methods
+
+The reviewer chooses the exact method, but the report must distinguish source review, automated testing or scanning, manual adversarial testing, and documentation analysis. Exercise negative paths and boundary violations, not only happy-path behavior. Validate important claims against the packaged artifact as well as source when packaging can change the result.
+
+Miftah maintainers provide architecture and setup help, answer scope questions, and reproduce findings. They do not constrain severity, suppress an in-scope result, or author the reviewer's conclusions.
+
+## Deliverables and disclosure
+
+The reviewer provides:
+
+1. a private report with target identifiers, scope, exclusions, methods, findings, severity and rationale, affected versions, reproduction guidance, and recommended remediation;
+2. a remediation-verification addendum that records the exact fix commit or package for every critical or high finding and the independent reviewer's retest result or written acceptance;
+3. a public completion summary naming the reviewer or organization when permitted, review dates, target, scope, exclusions, severity counts, remediation status, and residual limitations without exploit-enabling detail;
+4. the signed or otherwise attributable independence declaration.
+
+Send vulnerability details through the private process in [`SECURITY.md`](../SECURITY.md). Do not open a public GitHub issue with credentials, private provider data, or an unpatched exploit. Public issue #37 should link only the completion summary and safe remediation evidence.
+
+## Closure gate
+
+The review gate closes only when:
+
+- the external reviewer has delivered the required report and independence declaration;
+- there is no unresolved critical or high-severity finding in the reviewed v1 target;
+- every critical or high finding has an exact remediation commit, regression test where practical, and independent reviewer retest or written verification acceptance by that reviewer;
+- the public completion summary states the exact target, scope, exclusions, severity counts, and remediation status;
+- any change between the reviewed target and the v1 release candidate has been included in the review or accepted by the independent reviewer through a documented delta assessment.
+
+Medium and lower findings must have a documented disposition, owner, and timeframe. Acceptance of residual risk must name the decision maker and rationale. Passing existing CI or publishing this brief does not satisfy the gate.
+
+## Maintainer handoff checklist
+
+- [ ] Freeze and record the exact review target.
+- [ ] Provide build, test, architecture, threat-model, and safe fixture instructions.
+- [ ] Confirm a private reporting channel and response contacts from `SECURITY.md`.
+- [ ] Receive and archive the independence declaration and private report.
+- [ ] Triage findings without changing reviewer-authored severity evidence.
+- [ ] Remediate and add regression coverage.
+- [ ] Obtain independent reviewer verification or written acceptance by that reviewer.
+- [ ] Publish the safe completion summary and link it from #37.
+- [ ] Reconcile the final v1 candidate against the reviewed target before closing #39.

docs/oauth-console-validation.md

@@ -41,10 +41,11 @@ OAuth and Console are being validated for a pre-v1 feature release. Passing this
 
 ## External design-partner evidence
 
-Snapshot date: 2026-07-22.
+Snapshot date: 2026-08-11. Evaluator target: `@lubab/miftah@0.5.8`.
 
 - Interested external users: 5
 - Recorded completed external workflows: 0
 - Recorded returning external users: 0
+- Recorded unaided README evaluators: 0
 
-The external design-partner gate remains open. Closing it requires five external users to complete real multi-account workflows and at least three to return after setup. Record only deidentified workflow, setup friction, return behavior, and rejected assumptions; never record credentials, OAuth codes, tokens, provider payloads, or personal account identifiers.
+The external design-partner gate remains open. Use the [v1 external evaluation](v1-evaluation.md) protocol to define a completed real workflow, a later-session return, unaided participation, version pinning, and the deidentified public record. Never record credentials, OAuth codes, tokens, provider payloads, or personal account identifiers.

docs/threat-model.md

@@ -123,7 +123,7 @@ These are design boundaries, not permission to ignore them. Use separate OS iden
 
 ## Independent review status
 
-**Current project status (2026-07-14): not yet commissioned.** This document does not claim an independent review, an external finding count, or remediation of findings that have not been reported. The maintainer-authored controls above are implementation statements, not a substitute for external assurance.
+**Current project status (2026-08-11): not yet commissioned.** The [independent security review brief](independent-security-review.md) defines the target, independence, scope, deliverables, disclosure path, and closure gate. This document does not claim an independent review, an external finding count, or remediation of findings that have not been reported. The maintainer-authored controls above are implementation statements, not a substitute for external assurance.
 
 The planned independent review scope is the security-critical implementation and its tests: configuration/schema parsing; secret resolution and redaction; child-process and Windows Job Object containment; profile/runtime and container isolation; local HTTP ingress/session handling; routing, policy, approval, and identity boundaries; audit confidentiality/integrity; local plugins and dependency/supply-chain controls; and denial-of-service/capacity behavior. Reviewers should test negative paths and trust-boundary crossings, not only happy-path configuration.
 

docs/v1-evaluation.md

@@ -0,0 +1,138 @@
+# v1 external evaluation
+
+This protocol turns external Miftah use into comparable, privacy-safe evidence for issues #25, #88, #202, and #290. It is the shared evidence path for the product wedge, OAuth and Console validation, first-use product contract, and README redesign.
+
+The current evaluator target is the published `@lubab/miftah@0.5.8`. Record the exact package version, upstream MCP version or immutable image reference, client, operating system, provider class, and authentication owner for every attempt. If the target changes, do not combine results until the participant repeats the affected steps on the new target.
+
+This document is a protocol, not completed evidence. The gates remain open until the deidentified results are linked from the relevant GitHub issues.
+
+## Closure gates
+
+The evidence set must include:
+
+- five completed multi-account workflows from external participants, with at least three distinct providers represented across the set;
+- three returning users who independently use or verify the configured connector in a later session;
+- three unaided evaluators who start from the README and can identify Miftah's value, fit, account model, authentication path, and safe first success without maintainer coaching;
+- explicit records of setup friction, recovery attempts, rejected assumptions, and failures as well as successful outcomes.
+
+One person may contribute to more than one gate, but each gate keeps its own evidence. A maintainer, contributor to the evaluated build, synthetic fixture, or automated test does not count as an external participant.
+
+## Privacy and consent
+
+Ask the participant for consent before recording evidence. Collect no tokens, OAuth codes, raw configuration, logs, account or organization names, private URLs, provider payloads, or personal identifiers. The participant should redact screenshots and quotations before sharing them.
+
+Use identifiers such as `P1` and provider classes such as `source control` or `analytics`. Public issue comments contain only the deidentified rollup. If a failure might be a vulnerability, stop the public workflow and use the private process in [`SECURITY.md`](../SECURITY.md).
+
+## Participant workflow
+
+### 1. Start without maintainer coaching
+
+Give the participant only the repository URL and the task below. The maintainer may observe and answer safety questions, but must not select a setup path, command, profile name, authentication method, or recovery step.
+
+> Configure one existing MCP service through Miftah with two named profiles for the same provider. Confirm which profile is active, safely verify the intended account when the upstream supports it, switch profiles deliberately, and repeat the verification. Stop if a step asks you to paste a secret into shared configuration or evidence.
+
+Record where the participant starts, what they expect Miftah to do, and whether they correctly identify who owns authentication.
+
+### 2. Pin and identify the target
+
+Install the evaluator target and record its reported version:
+
+```bash
+npm install -g @lubab/miftah@0.5.8
+miftah version
+```
+
+Do not count an attempt when the installed version cannot be established or the upstream is floating without an immutable version or image reference.
+
+### 3. Configure and validate two profiles
+
+The participant chooses the documented terminal wizard, browser Console, preset, or reviewed local/remote setup path. Before connecting a client, they run the equivalent checks for their config and both profiles:
+
+```bash
+miftah validate --config <config-path>
+miftah doctor --config <config-path>
+miftah test-profile --config <config-path> --profile <profile-a>
+miftah test-profile --config <config-path> --profile <profile-b>
+```
+
+Passing diagnostics demonstrates only what each command reports. It does not prove provider scopes, account identity, or a successful real workflow.
+
+### 4. Connect, verify, switch, and recover
+
+In a supported client, the participant:
+
+1. connects the single Miftah connector and calls `miftah_current_profile`;
+2. performs a bounded read-only upstream action or configured identity probe to verify the intended account, recording `not verified` when the upstream cannot prove identity safely;
+3. calls `miftah_use_profile` to select the other named profile and accepts or rejects any required approval deliberately;
+4. repeats the current-profile and safe identity check, then completes one useful provider workflow;
+5. follows the documented diagnostic or reauthorization path for any failure without exposing credentials.
+
+A completed workflow requires a real upstream result under the intended profile, not only successful configuration, login, health, or tool listing. Wrong-account ambiguity, unexplained recovery, cross-profile leakage, or maintainer intervention prevents the attempt from counting as complete, but remains important failure evidence.
+
+### 5. Return later
+
+A returning user is a participant who, in a later session after the original setup session has ended, independently launches or reconnects the same reviewed connector, confirms its version and selected profile, and completes or verifies a useful provider action without setup coaching. Merely responding to a follow-up message does not count.
+
+Record the elapsed interval, whether configuration or credentials changed, the first command or UI path used, and any new friction.
+
+## README comprehension check
+
+For each of the three unaided evaluators, ask them to explain before setup:
+
+- the problem Miftah solves and when a direct MCP entry is simpler;
+- the one-connector, named-profile account model;
+- whether Miftah, the upstream, or the provider owns authentication for their chosen path;
+- how they would validate configuration and verify the selected account safely;
+- where audit, policy, identity, OAuth, client support, platform limits, and recovery guidance live.
+
+Then observe their first safe success. Record the first point of confusion and the first page or command that resolves it. Do not count a comprehension gate that was answered through maintainer explanation.
+
+## Deidentified evidence template
+
+Copy one section per attempt into a private working note, remove sensitive material, and publish only the final deidentified fields:
+
+```text
+Participant: P1
+External and unaffiliated with evaluated build: yes/no
+Consent to deidentified public rollup: yes/no
+Date and return date (if any): YYYY-MM-DD / YYYY-MM-DD or none
+Miftah package and reported version: @lubab/miftah@0.5.8 / ...
+Upstream immutable version or image: ...
+Provider class / auth owner: ... / Miftah, upstream, or provider
+Client / OS: ... / ...
+Setup path chosen without coaching: ...
+Two same-provider profiles configured: yes/no
+validate / doctor outcomes: pass, fail, or not run
+test-profile <profile-a> outcome: pass, fail, or not run
+test-profile <profile-b> outcome: pass, fail, or not run
+Initial and switched profile confirmed: yes/no
+Identity evidence: verified, not verified, or mismatched
+Real workflow outcome: completed/failed, with deidentified description
+Recovery attempted and outcome: ...
+README comprehension outcome and first confusion: ...
+Later-session return outcome: completed/failed/not attempted
+Maintainer intervention before completion: none or description
+Safe deidentified quote (optional): ...
+```
+
+## Public rollup
+
+Maintain this table in the tracking issue or link to an equivalent deidentified record. Do not replace missing results with projections.
+
+| Participant | Version | Provider class | Client / OS | Two profiles | Real workflow | Unaided README | Later return | Evidence link |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| P1 | pending | pending | pending | pending | pending | pending | pending | pending |
+| P2 | pending | pending | pending | pending | pending | pending | pending | pending |
+| P3 | pending | pending | pending | pending | pending | pending | pending | pending |
+| P4 | pending | pending | pending | pending | pending | n/a | pending | pending |
+| P5 | pending | pending | pending | pending | pending | n/a | pending | pending |
+
+Map the final evidence explicitly:
+
+- issue #25: five real multi-account workflows and product-wedge learning;
+- issue #88: OAuth, Console, recovery, compatibility, and three returning users;
+- issue #202: three unaided participants can discover trust, auth, account, client, and recovery controls;
+- issue #290: three unaided participants achieve the README's safe first-use contract;
+- issue #39: at least three real providers are represented, the independent security review is closed, and the final v1 target is reconciled under the [independent review brief](independent-security-review.md); provider evidence alone cannot close this release gate.
+
+Failed attempts are learning, not completion. Keep every issue open until its own acceptance criteria are supported by linked evidence.