feat(server): add secure Streamable HTTP transport

[mohanagy]

Summary

• add miftah serve --transport http with a localhost-first Streamable HTTP host
• isolate every HTTP client in a fresh runtime and enforce bounded session lifecycle, cleanup, and shutdown
• validate host, origin, bearer authentication, request size, and session capacity without logging secrets
• expose documented typed server.http configuration and contract coverage

Validation

• npm run test:core
• npm run test:coverage (68 files, 928 passed, 11 platform skips)
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package
• focused HTTP suite and built CLI HTTP startup/shutdown smoke

npm test was also retried on the shared local host. Its moving failures were unrelated fake-upstream startup timeouts; the complete coverage run passed on the same commit. Required CI remains the merge gate.

Closes #33

Summary by CodeRabbit

• New Features

  • Added an opt-in local Streamable HTTP transport for the serve command.
  • Added configurable HTTP sessions, request limits, idle timeouts, authentication, and access controls.
  • HTTP sessions are isolated and support reconnecting, cleanup, and graceful shutdown.
  • Added public configuration and type support for HTTP server settings.

• Documentation

  • Updated setup, CLI, configuration, architecture, library API, and security guidance for HTTP serving.

• Tests

  • Added comprehensive coverage for transport selection, security, authentication, session lifecycle, limits, isolation, and shutdown.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1d7b665f-8957-42b9-8cd9-79007d86bc1f

📥 Commits

Reviewing files that changed from the base of the PR and between a4c17a7 and 5f73dad.

📒 Files selected for processing (6)

• docs/cli.md
• src/cli/main.ts
• src/config/schema.ts
• src/http/miftah-http-server.ts
• tests/http-server.test.ts
• tests/package-contract.test.ts

📝 Walkthrough

Walkthrough

The PR adds loopback-first Streamable HTTP serving, session-scoped runtimes, HTTP configuration validation, bearer authentication, session lifecycle management, CLI transport selection, documentation, and comprehensive HTTP integration tests.

Changes

Streamable HTTP serving

Layer / File(s)	Summary
HTTP configuration and session runtime contracts src/config/*, src/runtime/*, src/secrets/*, src/index.ts, tests/config-*, tests/runtime-config-resolution.test.ts, tests/public-api.test.ts	Adds server.http configuration, validation rules, public types, secret resolution, and isolated session runtime construction.
HTTP request and session lifecycle src/http/miftah-http-server.ts, tests/http-server.test.ts, package.json	Adds /mcp request validation, authentication, bounded session creation, reconnect handling, idle cleanup, shutdown behavior, and lifecycle coverage.
CLI transport selection src/cli/parse.ts, src/cli/main.ts, tests/cli-parse.test.ts	Adds `--transport <stdio
Transport and security documentation README.md, docs/architecture.md, docs/cli.md, docs/config.md, docs/library-api.md, docs/security.md	Documents HTTP serving commands, configuration bounds, loopback and authentication requirements, session isolation, and cleanup semantics.

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

Possibly related PRs

• mohanagy/miftah#46 — Both PRs extend the strict configuration schema framework.
• mohanagy/miftah#51 — Both PRs involve secret resolution and secret-value tracking.
• mohanagy/miftah#58 — This PR extends the CLI parsing and dispatch flow with transport selection.

Poem

I’m a rabbit with a server to run,
Loopback hops beneath the sun.
Sessions bloom, then cleanly close,
Tokens hide from prying nose.
HTTP joins the STDIO queue—
Carrots and MCP for you! 🐇

---

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 15.38% 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 clearly matches the main change: adding secure Streamable HTTP transport support.
Description check	✅ Passed	The description covers summary and validation, but it omits the template's dedicated Security impact section.
Linked Issues check	✅ Passed	The changes satisfy #33 by adding loopback-first HTTP serving, session isolation, security controls, cleanup, and concurrency/reconnect coverage.
Out of Scope Changes check	✅ Passed	The docs, tests, and refactors all support the new HTTP transport feature and do not appear unrelated.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-33-http-server

---

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

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 6

🤖 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 `@src/cli/main.ts`:
- Line 22: Update the HTTP startup output in the CLI entrypoint to write the
successful “Miftah HTTP server listening…” status to stdout instead of stderr,
preserving the existing message and ensuring stderr remains empty on successful
startup as documented.

In `@src/config/schema.ts`:
- Around line 649-655: Consolidate the duplicated host-canonicalization logic by
extracting the shared HTTP host and literal loopback validation helpers from
schema.ts and miftah-http-server.ts into a common utility. Update
isCanonicalHttpHost, isLiteralLoopbackBindHost, isCanonicalHost, and
isLiteralLoopbackHost to reuse the shared implementation, preserving their
current validation behavior and interfaces.

In `@src/http/miftah-http-server.ts`:
- Line 3: Remove the duplicated host-canonicalization helpers hostPattern,
isCanonicalHost, and isLiteralLoopbackHost from the HTTP server implementation,
and reuse the corresponding shared helpers httpHostPattern, isCanonicalHttpHost,
and isLiteralLoopbackBindHost from src/config/schema.ts. Update the affected
validation paths and imports while preserving their existing behavior.
- Line 500: Update the createServer configuration in the bounded-capacity HTTP
server to explicitly set requestTimeout and headersTimeout values aligned with
the existing maxSessions, sessionIdleTimeoutMs, and maxRequestBytes limits.
Choose appropriately tighter connection-level bounds so slow clients cannot hold
admission slots for the default multi-minute duration.
- Line 100: Hoist the regular expressions used by the request-handling functions
in miftah-http-server.ts—including the bracketed host/port matcher and the digit
validators—into module-scope constants. Update the code around the affected
parsing logic to reuse those constants while preserving the existing matching
behavior and flags.
- Around line 500-515: Update the server startup promise handling around
createServer and server.listen so the catch preserves the original listen
failure as the cause of the startup error. Keep the generic “Unable to start the
Miftah HTTP server” context while attaching or propagating the caught error
details, including failures such as EADDRINUSE and EACCES.

🪄 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: d0c4be18-0c98-4cd6-bc7f-da7028c2d035

📥 Commits

Reviewing files that changed from the base of the PR and between 507499e and a4c17a7.

📒 Files selected for processing (26)

• README.md
• docs/architecture.md
• docs/cli.md
• docs/config.md
• docs/library-api.md
• docs/security.md
• package.json
• src/cli/main.ts
• src/cli/parse.ts
• src/config/schema.ts
• src/config/types.ts
• src/http/miftah-http-server.ts
• src/index.ts
• src/runtime/create-miftah-runtime.ts
• src/runtime/create-runtime.ts
• src/runtime/resolve-runtime-config.ts
• src/secrets/secret-provider-availability.ts
• src/secrets/secret-resolver.ts
• tests/cli-parse.test.ts
• tests/config-public-contract.test.ts
• tests/config-runtime-parity.test.ts
• tests/config-schema-contract.test.ts
• tests/http-server.test.ts
• tests/public-api.test.ts
• tests/runtime-config-resolution.test.ts
• tests/secret-provider-availability.test.ts

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.