create-workframe 0.1.11 → 0.1.12

package/README.md

@@ -3,7 +3,7 @@
 Published on npm as **create-workframe**.
 
 ```bash
-npx create-workframe@0.1.9 MyProject
+npx create-workframe@0.1.12 MyProject
 ```
 
 Scaffolds an isolated Workframe + Hermes project on Windows, macOS, and Linux.

package/docs/security.md

@@ -0,0 +1,85 @@
+# Security
+
+Report vulnerabilities via [SECURITY.md](../../SECURITY.md) — not public GitHub issues.
+
+## Modes
+
+| Variable | Effect |
+|----------|--------|
+| `SECURE_MODE=true` | Auth on mutating routes, restricted CORS, no Docker socket on API |
+| `DEV_LOCAL_UNSAFE=true` | Development only — open CORS, relaxed auth |
+| *(neither set)* | Secure default |
+
+Never enable `DEV_LOCAL_UNSAFE` or `WORKFRAME_E2E=1` on a public HTTPS URL during the install window.
+
+## Supervisor boundary
+
+With `SECURE_MODE=true`:
+
+- Only `workframe-supervisor` mounts `/var/run/docker.sock`
+- API calls supervisor with `WORKFRAME_SUPERVISOR_TOKEN`
+- Public compose overlay removes the socket from `workframe-api`
+
+## Credentials
+
+- **BYOK default** — user keys in per-user Hermes homes
+- **`user_only` providers** — no workspace fallback
+- **Vault** — envelope encryption; not mounted on the gateway container
+- **Per-turn leases** — gateway proxy tokens instead of shared raw secrets
+
+## Agent egress and the credential broker
+
+Hermes agents need the open internet — web research, docs, public APIs, and normal tool use must stay fast and unrestricted. Security work is **not** about blocking that traffic.
+
+Workframe splits outbound traffic into two classes:
+
+| Class | Examples | Policy |
+|-------|----------|--------|
+| **General egress** | Web search, `fetch`, public HTTPS, package indexes | **Allowed** — direct from the gateway container; no broker hop, no per-action approval |
+| **Brokered egress** | LLM providers, GitHub/Vercel/Netlify when using vault credentials | **Required** — `wf_rt_*` lease + internal proxy; raw secrets stay in the API vault |
+
+```text
+Hermes (gateway)
+  ├─ general egress ──────────► internet (research, tools, public APIs)
+  └─ brokered egress ─────────► workframe-api (/internal/llm/*, /internal/action/*)
+                                    └─ vault + lease validation ─► upstream provider
+```
+
+### What “unavoidable broker” means
+
+In `public_multi_user`, credential-mediated traffic must not depend on agent cooperation alone. Concretely:
+
+1. Gateway must **not** receive raw provider API keys or the vault database.
+2. Runtime profiles use **lease tokens** (`wf_rt_*`) and internal proxy base URLs for LLM calls.
+3. Integrated action providers use `/internal/action/*` with the same lease model.
+4. Gateway must **not** join the supervisor `control-net` (already enforced in compose).
+5. Optional strict profile (`WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true`) may block **direct** outbound connections to known provider API hostnames so traffic must use the broker — general internet stays open.
+
+This is **routing and secret placement**, not disabling `terminal` or adding human approval before each tool call. Lease validation on brokered requests is in-process (milliseconds), not an operator gate.
+
+### Deployment posture
+
+| Mode | General egress | Brokered credentials |
+|------|----------------|----------------------|
+| `trusted_team` / dogfood | Unrestricted | Config + vault + leases (today) |
+| `public_multi_user` | Unrestricted (agents stay capable) | Same broker path; verify script reports posture |
+| `public_multi_user` + `WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true` | Unrestricted except provider-host deny/redirect (planned) | Network-enforced broker path |
+
+See also [Audit 0027 — Agent Vault comparison](../audits/0027-agent-vault-comparison.md) (advisory; Infisical Agent Vault as a reference pattern, not a required dependency).
+
+## Public multi-user (`public_multi_user`)
+
+| Control | Behavior |
+|---------|----------|
+| Boot | Requires HTTPS, vault KEK, SMTP, proxy token, supervisor token |
+| Auth | Invite-only after install |
+| Dashboard | Owner/admin only (`auth_request`) |
+| Runtime RBAC | Members limited to their own `u-{user}-*` profiles |
+| Gateway env | Allowlisted secrets only |
+| Supervisor | Blocks direct access to user `.env` and `auth.json` paths |
+
+Full checklist: [PUBLIC_DEPLOY.md](../../infra/compose/workframe/PUBLIC_DEPLOY.md).
+
+## Multi-user filesystem model
+
+The Hermes gateway container mounts the shared `Agents/` tree. User isolation uses per-user runtime profiles, role checks in the API, supervisor guards, and encrypted credentials. Read [PUBLIC_DEPLOY.md](../../infra/compose/workframe/PUBLIC_DEPLOY.md) before running a public multi-user install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-workframe",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Scaffold a Workframe + Hermes workspace with guided onboarding",
   "type": "module",
   "bin": {

package/scripts/sync-canonical-to-package.mjs

@@ -137,6 +137,14 @@ if (fs.existsSync(publicDeploySrc)) {
   console.log('Synced PUBLIC_DEPLOY.md -> package/docs/');
 }
 
+const securityPublicSrc = path.join(REPO_ROOT, 'docs/public/security.md');
+const securityPkgDst = path.join(PKG_ROOT, 'docs/security.md');
+if (fs.existsSync(securityPublicSrc)) {
+  fs.mkdirSync(path.dirname(securityPkgDst), { recursive: true });
+  fs.copyFileSync(securityPublicSrc, securityPkgDst);
+  console.log('Synced docs/public/security.md -> package/docs/security.md');
+}
+
 for (const name of ['LICENSE', 'NOTICE', 'SECURITY.md']) {
   const src = path.join(REPO_ROOT, name);
   const dst = path.join(PKG_ROOT, name);

package/scripts/verify-public-deploy.sh

@@ -11,6 +11,57 @@ COMPOSE_FILE="$COMPOSE_DIR/docker-compose.yml"
 fail() { echo "FAIL: $*" >&2; exit 1; }
 warn() { echo "WARN: $*" >&2; }
 ok() { echo "OK: $*"; }
+info() { echo "INFO: $*"; }
+
+gateway_container_name() {
+  local name
+  name="$(grep -A20 '^  gateway:' "$COMPOSE_FILE" | grep 'container_name:' | head -n1 | sed 's/.*container_name:[[:space:]]*//' | tr -d '\r"')"
+  printf '%s' "${name:-workframe-gateway}"
+}
+
+report_egress_posture() {
+  local gw force_broker gw_on_control internal_control
+  gw="$(gateway_container_name)"
+  force_broker="$(env_val WORKFRAME_FORCE_AGENT_EGRESS_BROKER)"
+
+  if grep -A30 '^  gateway:' "$COMPOSE_FILE" | grep -q 'control-net'; then
+    gw_on_control=yes
+  else
+    gw_on_control=no
+  fi
+  if grep -A5 'control-net:' "$COMPOSE_FILE" | grep -q 'internal:[[:space:]]*true'; then
+    internal_control=yes
+  else
+    internal_control=no
+  fi
+
+  info "egress gateway_container=$gw"
+  info "egress gateway_on_control_net=$gw_on_control (expected no)"
+  info "egress control_net_internal=$internal_control (expected yes)"
+  [[ "$gw_on_control" == "no" ]] || fail "gateway must not join control-net"
+  [[ "$internal_control" == "yes" ]] || warn "control-net is not marked internal:true"
+
+  if command -v docker >/dev/null 2>&1 && docker inspect "$gw" >/dev/null 2>&1; then
+    local nets
+    nets="$(docker inspect "$gw" --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' 2>/dev/null || true)"
+    info "egress gateway_networks=${nets:-<unknown>}"
+    if echo "$nets" | grep -qi 'control'; then
+      fail "running gateway is attached to a control network"
+    fi
+    info "egress gateway_egress_posture=unrestricted_general (broker for LLM/action providers)"
+  else
+    info "egress gateway_egress_posture=unknown (gateway container not running)"
+  fi
+
+  info "egress broker_path=config_plus_leases (/internal/llm/*, /internal/action/*)"
+  info "egress general_internet=allowed (research, terminal, public APIs)"
+  info "egress broker_latency=per-request lease validation (no human approval gate)"
+
+  if [[ "$force_broker" =~ ^(1|true|yes|on)$ ]]; then
+    fail "WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true is set but provider-host egress enforcement is not implemented yet"
+  fi
+  ok "egress posture reported"
+}
 
 [[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
 [[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
@@ -85,6 +136,9 @@ if command -v curl >/dev/null 2>&1; then
     echo "$health" | grep -q 'workframe_e2e' || warn "API health missing workframe_e2e"
     echo "$health" | grep -q 'dev_local_unsafe' || warn "API health missing dev_local_unsafe"
     ok "API health"
+    snapshot_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${API_PORT}/api/snapshot" || true)"
+    [[ "$snapshot_code" == "401" ]] || fail "anonymous /api/snapshot returned ${snapshot_code:-<empty>} (expected 401)"
+    ok "anonymous /api/snapshot denied"
   fi
   dash_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${UI_PORT}/hermes-dashboard/" || true)"
   [[ "$dash_code" == "403" ]] || warn "hermes-dashboard without session returned $dash_code (expected 403)"
@@ -92,14 +146,16 @@ else
   warn "curl not found — skipping HTTP checks"
 fi
 
-if command -v docker >/dev/null 2>&1 && docker inspect workframe-gateway >/dev/null 2>&1; then
-  gw_env="$(docker inspect workframe-gateway --format '{{range .Config.Env}}{{println .}}{{end}}')"
+if command -v docker >/dev/null 2>&1 && docker inspect "$(gateway_container_name)" >/dev/null 2>&1; then
+  gw_env="$(docker inspect "$(gateway_container_name)" --format '{{range .Config.Env}}{{println .}}{{end}}')"
   for marker in WORKFRAME_SUPERVISOR_TOKEN ZK_AUTH_ SMTP_PASS; do
     echo "$gw_env" | grep -q "$marker" && fail "gateway env contains $marker"
   done
   ok "gateway env allowlist"
 else
-  warn "workframe-gateway not running — skipping docker inspect"
+  warn "$(gateway_container_name) not running — skipping docker inspect"
 fi
 
+report_egress_posture
+
 ok "public_multi_user preflight passed"

package/workframe-api/openrouter_catalog.py

@@ -12,7 +12,7 @@ _CACHE: dict[str, Any] = {"at": 0.0, "rows": []}
 _TTL_SEC = int(__import__("os").environ.get("WORKFRAME_OPENROUTER_CATALOG_TTL", "3600"))
 
 
-def _fetch_models(api_key: str) -> list[dict[str, str]]:
+def _fetch_models(api_key: str, *, timeout: float = 45) -> list[dict[str, str]]:
     req = urllib.request.Request(
         "https://openrouter.ai/api/v1/models",
         headers={
@@ -22,7 +22,7 @@ def _fetch_models(api_key: str) -> list[dict[str, str]]:
         },
         method="GET",
     )
-    with urllib.request.urlopen(req, timeout=45) as resp:
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
         data = json.loads(resp.read())
     rows: list[dict[str, str]] = []
     for item in data.get("data") or []:
@@ -48,7 +48,7 @@ def _fetch_models(api_key: str) -> list[dict[str, str]]:
     return rows[:120]
 
 
-def live_suggestions(api_key: str = "", *, limit: int = 40) -> list[dict[str, str]]:
+def live_suggestions(api_key: str = "", *, limit: int = 40, timeout: float = 45) -> list[dict[str, str]]:
     """Return cached OpenRouter suggestions; empty without a key."""
     key = str(api_key or "").strip()
     if not key:
@@ -57,7 +57,7 @@ def live_suggestions(api_key: str = "", *, limit: int = 40) -> list[dict[str, st
     if _CACHE["rows"] and now - float(_CACHE["at"]) < _TTL_SEC:
         return list(_CACHE["rows"])[:limit]
     try:
-        rows = _fetch_models(key)
+        rows = _fetch_models(key, timeout=timeout)
     except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, OSError):
         return list(_CACHE["rows"])[:limit]
     _CACHE["at"] = now

package/workframe-api/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@workframe/workframe-api",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "private": true,
   "type": "module",
   "scripts": {
     "dev": "python3 server.py",
     "start": "python3 server.py",
-    "typecheck": "python3 -m py_compile server.py zk_auth.py email_sender.py",
+    "typecheck": "python -m py_compile server.py zk_auth.py email_sender.py profile_config_yaml.py route_registry.py && python test_public_routes.py && python test_route_registry.py && python test_billing_provider.py && python test_model_surface_consistency.py && python test_profile_model_yaml.py",
     "build": "python3 -m py_compile server.py zk_auth.py email_sender.py"
   }
 }

package/workframe-api/profile_config_yaml.py

@@ -0,0 +1,126 @@
+"""Single write path for Hermes profile config.yaml model surface (WF-033).
+
+Read path stays in server._parse_model_block_from_disk (text scan, no import cycle).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _salvage_top_level_keys(text: str) -> dict[str, Any]:
+    """Keep non-model keys when safe_load cannot parse corrupt yaml (wizard duplicates)."""
+    out: dict[str, Any] = {}
+    skip = {"model", "fallback_providers"}
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith("#") or line.startswith((" ", "\t")):
+            i += 1
+            continue
+        if ":" not in stripped:
+            i += 1
+            continue
+        key = stripped.split(":", 1)[0].strip()
+        if key in skip:
+            i += 1
+            while i < len(lines) and (not lines[i].strip() or lines[i].startswith((" ", "\t", "#"))):
+                i += 1
+            continue
+        after = stripped.split(":", 1)[1].strip()
+        if after:
+            try:
+                out[key] = yaml.safe_load(after)
+            except yaml.YAMLError:
+                out[key] = after.strip().strip("'\"")
+            i += 1
+            continue
+        block = [line]
+        i += 1
+        while i < len(lines) and (not lines[i].strip() or lines[i].startswith((" ", "\t", "#"))):
+            block.append(lines[i])
+            i += 1
+        try:
+            frag = yaml.safe_load("\n".join(block))
+            if isinstance(frag, dict) and key in frag:
+                out[key] = frag[key]
+            else:
+                out[key] = None
+        except yaml.YAMLError:
+            out[key] = None
+    return out
+
+
+def _load_cfg(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return {}
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return _salvage_top_level_keys(text)
+    return data if isinstance(data, dict) else {}
+
+
+def update_model_surface(
+    config_path: Path,
+    *,
+    default: str | None = None,
+    provider: str | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    fallback_chain: list[dict[str, str]] | None = None,
+    strip_proxy_fields: bool = False,
+    coalesce: bool = False,
+) -> None:
+    """Merge model + fallback_providers keys; preserve other top-level yaml keys.
+
+  ponytail: comments are not preserved (safe_load/safe_dump); read path uses text scan.
+  coalesce=True drops duplicate model:/fallback_providers: blocks before rewrite.
+    """
+    cfg = _load_cfg(config_path)
+    if coalesce:
+        cfg.pop("model", None)
+        cfg.pop("fallback_providers", None)
+        model: dict[str, Any] = {}
+    else:
+        model = cfg.get("model")
+        if not isinstance(model, dict):
+            model = {}
+    if default is not None:
+        model["default"] = default
+    if provider is not None:
+        model["provider"] = provider
+    if base_url is not None:
+        if base_url:
+            model["base_url"] = base_url
+        else:
+            model.pop("base_url", None)
+    if api_key is not None:
+        if api_key:
+            model["api_key"] = api_key
+        else:
+            model.pop("api_key", None)
+    if strip_proxy_fields:
+        model.pop("api_key", None)
+        model.pop("base_url", None)
+    if model:
+        cfg["model"] = model
+    if fallback_chain is not None:
+        rows = [
+            {"provider": str(e.get("provider", "")).strip(), "model": str(e.get("model", "")).strip()}
+            for e in fallback_chain
+            if isinstance(e, dict) and str(e.get("provider", "")).strip() and str(e.get("model", "")).strip()
+        ]
+        if rows:
+            cfg["fallback_providers"] = rows
+        else:
+            cfg.pop("fallback_providers", None)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(yaml.safe_dump(cfg, sort_keys=False), encoding="utf-8")