Implement Creer v1.3: optional mTLS transport and Docker Compose

Add CREER_SSL_* peer/server TLS settings with shared peer_httpx_client,
dev cert + run scripts, docs/MTLS.md, and a two-node docker compose demo
alongside HMAC trust from v1.2.

Co-authored-by: Sanath S Patil <sanathpatil8861@gmail.com>

Author: cursoragent

.gitignore

@@ -7,3 +7,8 @@
 **/out/
 *.pyc
 .pytest_cache/
+certs/*.pem
+certs/*.key
+certs/*.csr
+certs/*.srl
+!certs/.gitkeep

PLAN.md

@@ -2,23 +2,15 @@
 
 ## Done
 
-- **v0.1** — FastAPI planner/generator + VS Code write-to-workspace (+ optional git)
-- **v0.2** — Preview, GitHub create/push, templates, overwrite protection, `/creer` chat
-- **v0.3** — Streaming, offline/local models, bake-ins, SecretStorage + GIT_ASKPASS
-- **v0.4** — Stream cancel, selectable license/CI bake-ins, quality gates
-- **v0.5** — Content diff preview before write, multi-root workspace targeting, installable JSON/YAML template packs
-- **v0.6** — Pack marketplace + remote URL install/delete, side-by-side conflict diffs, publish packaging
-- **v0.7** — Self-hosted pack registry (`/registry` + download), extension icon, Browse Pack Registry, release changelog
-- **v0.8** — Federated registry (`/registry/federated` + peers), Browse Federated Registry UI, GitHub Actions release + CI (artifact-first; signed publish when secrets exist)
-- **v0.9** — Peer status/probe UX (`creer.registryPeers`, Manage Registry Peers), federated browse enrichment, GitHub Release on tag + `RELEASE.md`
-- **v1.0** — Stable foundation: optional registry write auth (Bearer / `X-Creer-Token`), `GET /registry/discover`, federated `discover=true`, SecretStorage registry token + Discover peers UX
-- **v1.1** — Discovery hardening: peer policy (SSRF / private IP blocks, allow/deny, max hops); extension surfaces policy errors, `creer.federationMaxHops` / `creer.warnPrivatePeers`, blocked-discover UX
-- **v1.2** — HMAC peer trust: backend `trust` blocks + peer_meta `trust_status` (`signed` | `unsigned` | `invalid` | `skipped`); extension `creer.requireSignedPeers`, trust badges/summaries; env `CREER_PEER_TRUST_SECRET` + `CREER_PEER_TRUST_MODE`
+- **v0.1–v1.0** — Core scaffold, templates/packs, streaming, GitHub, marketplace, federation, auth, discovery
+- **v1.1** — Discovery hardening (SSRF / allow-deny / hop budget)
+- **v1.2** — HMAC signed peer trust
+- **v1.3** — Optional TLS/mTLS transport for peers + Docker Compose multi-peer demo (`docs/MTLS.md`)
 
-## Optional next
+## Optional next (human)
 
-- Human: configure `VSCE_PAT` / `OVSX_PAT` repository secrets; tag `v1.2.0` (see [`RELEASE.md`](RELEASE.md)) — agents cannot set GitHub Actions secrets
-- Mutual TLS between registries (optional future / human infra — not required for HMAC peer trust)
+- Configure `VSCE_PAT` / `OVSX_PAT` and tag a release ([`RELEASE.md`](RELEASE.md)) — agents cannot set GitHub Actions secrets
+- Production CA / cert rotation for mTLS deployments
 
 ## Non-goals
 

README.md

@@ -2,116 +2,41 @@
 
 AI-powered repo scaffolding inside your workspace.
 
-**Current version: 1.2.0** (HMAC peer trust)
-
-## Architecture
-
-```
-creer/
-├── backend/     # Python FastAPI AI engine (+ packs/ + registry)
-├── extension/   # VS Code extension (icon in media/)
-└── .github/     # CI + release workflows
-```
+**Current version: 1.3.0**
 
 ## Quick start
 
 ```bash
-# Backend
+# Backend (local)
 cd backend && python -m venv venv && source venv/bin/activate
 pip install -r requirements.txt && cp .env.example .env
 uvicorn main:app --reload --port 8000
 
+# Or Docker multi-peer demo
+docker compose up --build
+# A: http://localhost:8000  B: http://localhost:8001
+curl -s http://localhost:8000/registry/federated | head
+
 # Extension
 cd extension && npm install && npm run compile
-# F5 → Creer: Create New Repo
-```
-
-## Registry & federation (v0.7–v1.2)
-
-Self-hosted pack catalog plus optional multi-host federation, write auth, peer policy, and HMAC peer trust:
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/registry?q=&source=` | Searchable pack list (may include a `trust` block when signing is enabled) |
-| `GET` | `/registry/federated?q=&source=&peers=&discover=&max_hops=` | Local + peer merge; `discover=true` expands peers; `max_hops` caps hop depth (0–2); peers carry `trust_status` |
-| `GET` | `/registry/discover` | Peer discovery (policy-filtered; may include a `trust` block) |
-| `GET` | `/registry/peers` | Peer health + configured URLs (+ trust when verified) |
-| `POST` | `/registry/peers/probe` | Probe one peer `{ url }` (auth when configured; may 400 on policy; may include trust) |
-| `GET` | `/registry/packs/{id}` | Pack metadata |
-| `GET` | `/registry/packs/{id}/download` | Portable JSON pack (installable URL) |
-| `GET` | `/marketplace` | Curated featured view |
-| `POST` | `/packs/install` | Install pack from URL (auth when configured) |
-| `DELETE` | `/packs/{id}` | Delete installed pack (auth when configured) |
-
-When the backend sets `CREER_REGISTRY_TOKEN`, mutating routes expect `Authorization: Bearer <token>` and/or `X-Creer-Token`.
-
-### Peer policy env vars (v1.1)
-
-Backend peer/federation policy (SSRF and private-IP hardening). The extension surfaces 400 `detail` strings and per-peer `error` / optional `policy` fields.
-
-| Env | Purpose |
-|---|---|
-| `CREER_FEDERATION_MAX_HOPS` | Default max discovery hops (0–2; default 1). Extension may also send `max_hops` on federated browse when the backend accepts it. |
-| `CREER_PEER_ALLOWLIST` | Comma-separated hostnames/URLs; if non-empty, only these peers may be contacted |
-| `CREER_PEER_DENYLIST` | Comma-separated hostnames/URLs always blocked |
-| `CREER_ALLOW_PRIVATE_PEERS` | When true (`1`/`true`/`yes`), allow loopback/private/link-local peers (default off) |
-
-### HMAC peer trust env vars (v1.2)
-
-Shared-secret HMAC-SHA256 signing/verification for peer registry and discover responses. Federated `peer_meta` (and probe) include `trust_status`: `signed` | `unsigned` | `invalid` | `skipped`. Signed responses attach a `trust` block `{ alg: "HMAC-SHA256", kid: "default", sig: "<hex>" }`.
-
-| Env | Purpose |
-|---|---|
-| `CREER_PEER_TRUST_SECRET` | Shared HMAC secret used to sign outbound registry/discover and verify peer payloads. Empty = signing/verification disabled. |
-| `CREER_PEER_TRUST_MODE` | `off` (default) \| `optional` \| `required`. `off`: never verify (outbound still signed when secret set). `optional`: verify when a signature is present; accept unsigned; mark `trust_status`. `required`: reject peer payloads without a valid HMAC (treated as fetch error). |
-
-Mutual TLS between registries remains an **optional future** concern and is left to human/infra configuration — HMAC peer trust does not require mTLS.
-
-Extension settings: `creer.registryPeers`, `creer.showPeerStatus`, `creer.federatedDiscover` (`discover=true`), `creer.federationMaxHops` (`max_hops`), `creer.warnPrivatePeers`, `creer.requireSignedPeers` (client-side filter of unsigned/invalid/skipped peer packs), `creer.registryToken` (deprecated plaintext — prefer SecretStorage).
-
-Commands: **Browse Federated Registry**, **Manage Registry Peers** (Discover peers; private-host warning; policy-blocked suggestions; trust badges), **Set / Clear Registry Token**.
-
-Install from another Creer host:
-
-```bash
-curl -X POST http://localhost:8000/packs/install \
-  -H 'Content-Type: application/json' \
-  -d '{"url":"http://other-host:8000/registry/packs/fastapi-crud/download"}'
 ```
 
-Set `CREER_PUBLIC_BASE_URL` for absolute download links in registry responses.
-Set `CREER_REGISTRY_PEERS` for backend-configured federated discovery.
-Set `CREER_REGISTRY_TOKEN` to require write auth on install/delete/probe.
-Use `creer.registryPeers` in the extension for client-side extra peers when browsing.
-Set matching `CREER_PEER_TRUST_SECRET` (and `CREER_PEER_TRUST_MODE`) on peers to enable HMAC trust; enable `creer.requireSignedPeers` in the extension to hide unsigned peer packs.
-
-## Extension commands
+## Highlights
 
-| Command | Title |
+| Area | Features |
 |---|---|
-| `creer.createRepo` | Create New Repo |
-| `creer.createRepoFromChat` | Create from Chat Prompt |
-| `creer.browseMarketplace` | Browse Pack Marketplace |
-| `creer.browseRegistry` | Browse Pack Registry |
-| `creer.browseFederatedRegistry` | Browse Federated Registry |
-| `creer.manageRegistryPeers` | Manage Registry Peers |
-| `creer.installPackFromUrl` | Install Pack from URL |
-| `creer.setGitHubToken` / `clearGitHubToken` | GitHub SecretStorage token |
-| `creer.setRegistryToken` / `clearRegistryToken` | Registry write SecretStorage token |
+| Scaffold | Plan → preview → stream generate → content/conflict diffs → write |
+| Packs | Templates, JSON/YAML packs, marketplace, registry download |
+| Federation | Peers, discover, hop budget, SSRF policy, HMAC trust, optional mTLS |
+| Ops | Docker Compose, CI/release workflows, `RELEASE.md` |
 
-## CI & publishing
+## TLS / mTLS
 
-- **CI** (`.github/workflows/ci.yml`): pytest + extension compile on push/PR
-- **Release** (`.github/workflows/release.yml`): tag `v*` → package `.vsix`, create GitHub Release with attachment; publish to Marketplace / Open VSX only when `VSCE_PAT` / `OVSX_PAT` secrets are set
+See [`docs/MTLS.md`](docs/MTLS.md). Generate dev certs with `./scripts/gen-dev-certs.sh`, then set `CREER_SSL_*` and use `./scripts/run_backend.sh`.
 
-See [`RELEASE.md`](RELEASE.md) and [`extension/PUBLISH.md`](extension/PUBLISH.md). Package locally:
-
-```bash
-cd extension && npm run compile && npm run package
-# → creer-1.2.0.vsix (includes media/icon.png)
-```
+## Publishing
 
-Signed Marketplace / Open VSX publish requires your own `VSCE_PAT` / `OVSX_PAT` (never commit tokens). Agents cannot set GitHub Actions secrets — that remains a human step.
+Human step for Marketplace / Open VSX tokens — [`RELEASE.md`](RELEASE.md).
 
 ## License
 

RELEASE.md

@@ -1,4 +1,4 @@
-# Releasing Creer v1.0.0
+# Releasing Creer
 
 Exact steps for a human maintainer to cut a tagged release with GitHub Release + optional Marketplace / Open VSX publish.
 
@@ -8,51 +8,32 @@ In GitHub → **Settings → Secrets and variables → Actions**, add:
 
 | Secret | Purpose |
 |---|---|
-| `VSCE_PAT` | Azure DevOps PAT with Marketplace **Acquire** + **Publish** (publisher must match `extension/package.json` → `publisher`) |
-| `OVSX_PAT` | Open VSX access token from [open-vsx.org](https://open-vsx.org/) |
+| `VSCE_PAT` | Azure DevOps PAT with Marketplace **Acquire** + **Publish** |
+| `OVSX_PAT` | Open VSX access token |
 
-Both are optional. If neither is set, the release workflow still builds the `.vsix`, uploads it as an artifact, and (on tag pushes) creates a **GitHub Release** with the `.vsix` attached. Marketplace / Open VSX publish is skipped with `No publish tokens configured — artifact only`.
+Both optional. Without them the workflow still builds a `.vsix` artifact and (on tags) a GitHub Release.
 
-Never commit PATs. Prefer repo secrets over exporting tokens in shared shells.
+**Cloud agents cannot configure these secrets.**
 
-**Note:** Cloud agents cannot configure GitHub Actions secrets — a human must set `VSCE_PAT` / `OVSX_PAT` before signed Marketplace / Open VSX publish.
-
-## 2. Bump & verify locally
+## 2. Verify locally
 
 ```bash
-# Confirm extension version is 1.0.0
-grep '"version"' extension/package.json
-
-cd extension
-npm ci
-npm run compile
-npm run package
-# → creer-1.0.0.vsix
+grep '"version"' extension/package.json   # e.g. 1.3.0
+cd extension && npm ci && npm run compile && npm run package
+# → creer-1.3.0.vsix
 ```
 
-Smoke-test: `code --install-extension creer-1.0.0.vsix` (or Cursor equivalent) against a running backend.
-
-## 3. Tag v1.0.0 and push
-
-From a clean `main` (or the release commit):
+## 3. Tag and push
 
 ```bash
-git tag -a v1.0.0 -m "Creer v1.0.0"
-git push origin v1.0.0
+git tag -a v1.3.0 -m "Creer v1.3.0"
+git push origin v1.3.0
 ```
 
-Tag pattern `v*` triggers [`.github/workflows/release.yml`](.github/workflows/release.yml).
-
-## 4. What the workflow does
-
-1. **build** — `npm ci` → `compile` → `vsce package` → upload `creer-vsix` artifact  
-2. **github-release** (tag pushes only) — create a GitHub Release and attach the `.vsix` (`contents: write`)  
-3. **publish** — if `VSCE_PAT` / `OVSX_PAT` secrets exist, publish to Marketplace / Open VSX; otherwise artifact-only
+## 4. Workflow
 
-You can also run the workflow via **Actions → Release → Run workflow** (`workflow_dispatch`) for a package/artifact without a tag (no GitHub Release job in that case).
+See `.github/workflows/release.yml` — build → GitHub Release on tags → optional Marketplace/Open VSX when secrets exist.
 
 ## 5. After release
 
-- Confirm the GitHub Release page lists `creer-1.0.0.vsix`
-- If secrets were set, confirm Marketplace / Open VSX listing updated to 1.0.0
-- See [`extension/PUBLISH.md`](extension/PUBLISH.md) for manual `vsce` / `ovsx` publish from a laptop
+Confirm the GitHub Release lists the `.vsix`. If secrets were set, confirm Marketplace / Open VSX listings.

backend/.env.example

@@ -57,3 +57,13 @@ CREER_OFFLINE=
 # optional: verify when signature present; accept unsigned; mark trust_status
 # required: reject peer payloads without a valid HMAC (treated as fetch error)
 # CREER_PEER_TRUST_MODE=off
+
+# Optional TLS for uvicorn (v1.3). Used by scripts/run_backend.sh.
+# CREER_SSL_CERTFILE=../certs/server.pem
+# CREER_SSL_KEYFILE=../certs/server-key.pem
+
+# Optional mTLS client material for outbound peer calls (v1.3).
+# CREER_SSL_CA_CERTS=../certs/ca.pem
+# CREER_SSL_CLIENT_CERT=../certs/client.pem
+# CREER_SSL_CLIENT_KEY=../certs/client-key.pem
+# CREER_SSL_VERIFY=true

backend/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/federation.py

@@ -7,8 +7,6 @@
 from typing import Any
 from urllib.parse import urljoin, urlparse
 
-import httpx
-
 from config import CREER_PUBLIC_BASE_URL, CREER_REGISTRY_PEERS
 from app.auth import registry_auth_required
 from app.peer_policy import (
@@ -18,9 +16,10 @@
     policy_summary,
 )
 from app.peer_trust import evaluate_peer_trust, sign_payload, trust_mode
+from app.http_client import peer_httpx_client
 from app.registry import list_registry, registry_count
 
-FEDERATION_VERSION = "1.2.0"
+FEDERATION_VERSION = "1.3.0"
 _MAX_PEERS = 8
 _DISCOVER_TIMEOUT = 3.0
 
@@ -172,7 +171,7 @@ def _fetch_peer_registry(
 
     url = f"{base}/registry"
     try:
-        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        with peer_httpx_client(timeout=timeout) as client:
             resp = client.get(url, params=params or None)
             resp.raise_for_status()
             data = resp.json()
@@ -222,7 +221,7 @@ def fetch_peer_discover(
 
     url = f"{base}/registry/discover"
     try:
-        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        with peer_httpx_client(timeout=timeout) as client:
             resp = client.get(url)
             resp.raise_for_status()
             data = resp.json()
@@ -374,7 +373,7 @@ def probe_peer(base_url: str, timeout: float = 5.0) -> dict[str, Any]:
     trust_status: str | None = None
 
     try:
-        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        with peer_httpx_client(timeout=timeout) as client:
             # Prefer /health for liveness + version (+ registry_count when present)
             try:
                 hresp = client.get(f"{base}/health")

backend/app/http_client.py

@@ -0,0 +1,40 @@
+"""Shared httpx client for outbound peer calls (optional TLS / mTLS)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from config import (
+    CREER_SSL_CA_CERTS,
+    CREER_SSL_CLIENT_CERT,
+    CREER_SSL_CLIENT_KEY,
+    CREER_SSL_VERIFY,
+)
+
+
+def peer_httpx_client(timeout: float = 8.0) -> httpx.Client:
+    """
+    Build an httpx.Client for federation/peer requests.
+
+    - verify: CA bundle path, True, or False (CREER_SSL_VERIFY)
+    - cert: client cert/key tuple when both CREER_SSL_CLIENT_* are set
+    """
+    verify: Any
+    if not CREER_SSL_VERIFY:
+        verify = False
+    elif CREER_SSL_CA_CERTS:
+        verify = CREER_SSL_CA_CERTS
+    else:
+        verify = True
+
+    kwargs: dict[str, Any] = {
+        "timeout": timeout,
+        "follow_redirects": True,
+        "verify": verify,
+    }
+    if CREER_SSL_CLIENT_CERT and CREER_SSL_CLIENT_KEY:
+        kwargs["cert"] = (CREER_SSL_CLIENT_CERT, CREER_SSL_CLIENT_KEY)
+
+    return httpx.Client(**kwargs)

backend/app/registry.py

@@ -104,7 +104,7 @@ def matches(item: dict[str, Any]) -> bool:
 
     return sign_payload(
         {
-            "version": "1.2.0",
+            "version": "1.3.0",
             "base_url": CREER_PUBLIC_BASE_URL or None,
             "items": items,
         }

backend/config.py

@@ -47,3 +47,24 @@ def _clamp_federation_max_hops(raw: str | None) -> int:
 CREER_PEER_TRUST_SECRET = os.getenv("CREER_PEER_TRUST_SECRET", "").strip()
 # Peer trust verification mode: off | optional | required (default off)
 CREER_PEER_TRUST_MODE = os.getenv("CREER_PEER_TRUST_MODE", "off").strip().lower() or "off"
+
+# Optional TLS for uvicorn / peer mTLS (v1.3+)
+CREER_SSL_CERTFILE = os.getenv("CREER_SSL_CERTFILE", "").strip() or None
+CREER_SSL_KEYFILE = os.getenv("CREER_SSL_KEYFILE", "").strip() or None
+CREER_SSL_CA_CERTS = os.getenv("CREER_SSL_CA_CERTS", "").strip() or None
+CREER_SSL_CLIENT_CERT = os.getenv("CREER_SSL_CLIENT_CERT", "").strip() or None
+CREER_SSL_CLIENT_KEY = os.getenv("CREER_SSL_CLIENT_KEY", "").strip() or None
+# Verify peer TLS certificates (default true). Set false only for broken local experiments.
+CREER_SSL_VERIFY = os.getenv("CREER_SSL_VERIFY", "true").lower() not in (
+    "0",
+    "false",
+    "no",
+)
+
+
+def tls_server_configured() -> bool:
+    return bool(CREER_SSL_CERTFILE and CREER_SSL_KEYFILE)
+
+
+def mtls_client_configured() -> bool:
+    return bool(CREER_SSL_CLIENT_CERT and CREER_SSL_CLIENT_KEY)