feat: add local authenticated Console control API

[mohanagy]

Closes #85

What changed

• adds an explicitly launched miftah console control process bound only to literal 127.0.0.1
• adds one-use terminal bootstrap authentication, in-memory browser sessions, exact Host/Origin checks, CSRF protection, rate/body/header/session bounds, security headers, and clean shutdown
• adds versioned /api/v1 endpoints for redacted health/config/profile/connection metadata, atomic connection creation, OAuth connect/reauth/disconnect, and allowlisted Console audit records
• reuses the typed in-process OAuth/configuration application services and keeps this API separate from MCP transport, sessions, and authentication
• documents the process/security boundary and updates CLI/package contracts

TDD and security evidence

Focused regressions were observed failing before their fixes for the missing server/routes, bootstrap expiry, rate limits, backup-path redaction, inherited __proto__ connection lookup, and audit-health filesystem-path disclosure.

Validated on Node 22.22.3:

• focused Console/OAuth suite: 33 passed
• npm run test:core: 404 passed, 23 platform skips
• npm run typecheck
• npm run lint
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package: 18 passed, including packed-binary Console startup/shutdown

The full local npm test run still reproduces the existing workstation-only upstream startup timeout cascade tracked separately; no Console test failed. Current-head CI remains the clean-host release gate.

Summary by CodeRabbit

• New Features
  • Added an optional local Console control API launched with miftah console.
  • Supports health and configuration details, OAuth connection management, status checks, credential rotation, and redacted audit records.
  • Added configurable ports, one-time bootstrap credentials, browser sessions, and clean shutdown handling.
• Security
  • Restricted access to loopback with session expiration, CSRF protection, origin/host validation, rate limits, and redacted responses.
  • Connection changes are validated, audited, and fail safely when audit storage is unavailable.
• Documentation
  • Added comprehensive Console API, CLI, architecture, security, and threat-model documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an explicitly launched, loopback-only Console control API with typed application services, OAuth connection operations, browser-session security, auditing, CLI support, documentation, and integration and contract tests.

Changes

Console control plane

Layer / File(s)	Summary
Typed Console application services src/console/console-application-service.ts, tests/console-application-service.test.ts	Defines typed health, metadata, connection, mutation, and audit interfaces; delegates OAuth operations and enforces redacted, fail-closed auditing.
Authenticated Console HTTP server src/console/console-server.ts, tests/console-server.test.ts	Adds loopback /api/v1 routing with one-use bootstrap credentials, bounded HttpOnly sessions, Host/Origin and CSRF checks, request limits, redacted responses, credential rotation, and shutdown handling.
Console CLI launch and contracts src/cli/parse.ts, src/cli/main.ts, tests/cli-parse.test.ts, tests/package-contract.test.ts	Adds miftah console, optional port validation, lifecycle signal handling, bootstrap output, rotation, and installed-CLI startup coverage.
Documentation and security contracts README.md, CHANGELOG.md, docs/*, tests/oauth-console-threat-model-docs-contract.test.ts	Documents the Console API, process and MCP boundaries, bootstrap/session controls, auditing, endpoint behavior, and implemented security decisions.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• [Epic] Optional local Miftah Console and standards-based OAuth control plane #78 — Covers the broader Console API and OAuth lifecycle roadmap implemented by this change.
• [Console] Build the optional first-run Miftah Console #86 — Describes the future browser Console UI that can consume this backend API.
• [Security] Publish a threat model and complete an external security review #37 — Covers the OAuth and Console security controls documented and tested here.

Possibly related PRs

• mohanagy/miftah#91 — Updates the threat-model artifacts and contract expectations for the implemented Console controls.
• mohanagy/miftah#182 — Provides the OAuth CLI and lifecycle service behavior used by the Console application service.

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant ConsoleCLI
  participant ConsoleServer
  participant ApplicationService
  Operator->>ConsoleCLI: Launch miftah console
  ConsoleCLI->>ConsoleServer: Start loopback listener
  Operator->>ConsoleServer: Exchange one-use bootstrap credential
  ConsoleServer->>ApplicationService: Invoke authenticated API operation
  ApplicationService->>ConsoleServer: Return metadata, status, audit, or mutation result

Loading

Poem

A rabbit hops where loopback calls,
A bootstrap key unlocks the walls.
CSRF guards each careful change,
Redacted logs keep secrets strange.
The Console sleeps when shutdown’s near—
Clean and audited, year by year.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 4.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding a local authenticated Console control API.
Description check	✅ Passed	The description covers the change, security impact, and validation results, though it doesn't follow the repo template exactly.
Linked Issues check	✅ Passed	The changes implement the loopback-only authenticated Console API, redacted metadata endpoints, CSRF/origin defenses, audit logging, and explicit launch requirements from #85.
Out of Scope Changes check	✅ Passed	The modified docs, tests, CLI, and console runtime files all support the Console control API scope with no clear unrelated additions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/85-console-api

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/console-api.md`:
- Around line 15-20: Update the Console API documentation for POST
/api/v1/sessions and every /connections/:ref/(connect|reauth|credential) action,
including DELETE, to specify the required application/json Content-Type and
accepted JSON payload (such as {} where appropriate), matching the unconditional
parsing and validation behavior in the console server.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bae34bb8-9eb6-4716-af19-1f53b05f2728

📥 Commits

Reviewing files that changed from the base of the PR and between 84b1927 and 968e10e.

📒 Files selected for processing (18)

• CHANGELOG.md
• README.md
• docs/architecture.md
• docs/cli.md
• docs/console-api.md
• docs/oauth-console-threat-model.md
• docs/oauth-support.md
• docs/security.md
• docs/threat-model.md
• src/cli/main.ts
• src/cli/parse.ts
• src/console/console-application-service.ts
• src/console/console-server.ts
• tests/cli-parse.test.ts
• tests/console-application-service.test.ts
• tests/console-server.test.ts
• tests/oauth-console-threat-model-docs-contract.test.ts
• tests/package-contract.test.ts

The sole actionable thread was fixed in 255ded2 with a focused failing-then-passing documentation contract test and is resolved. CodeRabbit current-head status is green but explicitly rate-limited, so this stale CHANGES_REQUESTED decision is dismissed under the documented maintainer exception.