create-workframe 0.1.12 → 0.1.13

package/README.md

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

package/bin/create-workframe.js

@@ -535,7 +535,7 @@ services:
       context: \${WORKFRAME_HOST_PROJECT_ROOT}/workframe-supervisor
     volumes:
       - \${WORKFRAME_HOST_PROJECT_ROOT}/Agents:/opt/data
-      - \${WORKFRAME_HOST_PROJECT_ROOT}:\${WORKFRAME_HOST_PROJECT_ROOT}
+      - \${WORKFRAME_HOST_PROJECT_ROOT}:/compose
 
   workframe:
     volumes:
@@ -2527,7 +2527,7 @@ async function main() {
     copyWorkframeUiTemplate(target, [nativeSlug]);
     writeText(
       path.join(target, 'workframe-ui', 'public', 'workframe-config.json'),
-      `${JSON.stringify({ project_name: safeName, native_profile: nativeSlug }, null, 2)}\n`,
+      `${JSON.stringify({ project_name: safeName, native_profile: nativeSlug, package_version: PKG_VERSION }, null, 2)}\n`,
     );
 
     writeText(path.join(target, 'SETUP.md'), onboardingDoc({

package/bin/workframe.js

@@ -3,7 +3,7 @@
  * workframe — lifecycle CLI for generated Workframe projects.
  *
  * Commands:
- *   workframe doctor [--repair]  Diagnose stack; --repair provisions missing agent DM runtimes
+ *   workframe doctor [--repair] [--json]  Diagnose stack; --json mutation-free report
  *   workframe setup      Open Hermes setup (credentials)
  *   workframe stop       Stop all stack containers
  *   workframe start      Start the full stack (docker compose up -d)
@@ -53,9 +53,137 @@ function doctorAgentDmRuntimes(root, { repair = false } = {}) {
   return dockerCompose(root, ['exec', '-T', 'workframe-api', 'python3', '-c', py], { stdio: 'pipe' });
 }
 
+function redactPath(root, absolutePath) {
+  try {
+    const rel = path.relative(root, absolutePath);
+    if (!rel || rel.startsWith('..')) return path.basename(absolutePath);
+    return rel.split(path.sep).join('/');
+  } catch {
+    return path.basename(String(absolutePath || ''));
+  }
+}
+
+function nodeVersion() {
+  const res = spawnSync(process.execPath, ['-v'], { encoding: 'utf8' });
+  if (res.status !== 0) return null;
+  return (res.stdout || res.stderr || '').trim() || null;
+}
+
+function buildDoctorJsonReport(root, manifest, issues, checks) {
+  const decision = issues.length === 0
+    ? 'healthy'
+    : checks.docker?.status === 'fail'
+      ? 'needs_user_action'
+      : 'unhealthy';
+  return {
+    schema_version: '0.1',
+    advisory_only: true,
+    decision,
+    project: {
+      name: manifest?.project_name || path.basename(root),
+      package_version: manifest?.package_version || null,
+    },
+    checks,
+    issues,
+  };
+}
+
+function collectDoctorChecks(root, manifest) {
+  const checks = {};
+  const issues = [];
+
+  const dockerCheck = spawnSync('docker', ['info'], { encoding: 'utf8' });
+  if (dockerCheck.status !== 0) {
+    checks.docker = { status: 'fail', note: 'Docker not running or not installed' };
+    issues.push('Docker is not running or not installed.');
+  } else {
+    checks.docker = { status: 'ok', note: 'docker info succeeded' };
+  }
+
+  const nodeVer = nodeVersion();
+  checks.node = {
+    status: nodeVer ? 'ok' : 'skip',
+    version: nodeVer,
+  };
+
+  if (!manifest) {
+    checks.manifest = { status: 'fail', stack: null };
+    issues.push('No workframe-manifest.json found.');
+  } else {
+    checks.manifest = {
+      status: 'ok',
+      stack: manifest.docker?.stack || null,
+    };
+  }
+
+  const layout = { workspace: 'missing', runtime: 'missing' };
+  for (const dir of ['Files', 'Agents']) {
+    if (fs.existsSync(path.join(root, dir))) {
+      layout[dir === 'Files' ? 'workspace' : 'runtime'] = 'ok';
+    } else {
+      issues.push(`${dir}/ directory missing.`);
+    }
+  }
+  checks.layout = { status: layout.workspace === 'ok' && layout.runtime === 'ok' ? 'ok' : 'fail', ...layout };
+
+  checks.cell = {
+    deployment_mode: manifest?.security?.deployment_mode || manifest?.deployment_mode || null,
+    install_id_redacted: manifest?.install_id ? String(manifest.install_id).slice(0, 8) + '…' : null,
+    manifest_path: redactPath(root, path.join(root, 'workframe-manifest.json')),
+  };
+
+  const runtimeCandidates = [];
+  if (manifest && checks.docker?.status === 'ok') {
+    const ps = dockerCompose(root, ['ps', '--format', 'json'], { stdio: 'pipe' });
+    if (ps.status === 0 && ps.stdout) {
+      try {
+        const raw = ps.stdout.trim();
+        const containers = raw.startsWith('[')
+          ? JSON.parse(raw)
+          : raw.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+        for (const name of ['gateway', 'workframe-api', 'workframe']) {
+          const container = containers.find((c) => c.Name?.includes(name) || c.Service === name);
+          runtimeCandidates.push({
+            kind: name === 'gateway' ? 'hermes_managed' : 'workframe_service',
+            service: name,
+            status: container ? (container.State === 'running' ? 'running' : container.State || 'unknown') : 'stopped',
+          });
+          if (!container || container.State !== 'running') {
+            issues.push(`${name} container not running.`);
+          }
+        }
+      } catch {
+        runtimeCandidates.push({ kind: 'hermes_managed', service: 'gateway', status: 'unknown' });
+      }
+    }
+  } else {
+    runtimeCandidates.push({ kind: 'hermes_managed', service: 'gateway', status: 'unknown', note: 'docker unavailable' });
+  }
+  checks.runtime_candidates = runtimeCandidates;
+
+  if (!fs.existsSync(path.join(root, '.env'))) {
+    issues.push('.env file missing.');
+  }
+  if (!fs.existsSync(path.join(root, 'docker-compose.yml'))) {
+    issues.push('docker-compose.yml missing.');
+  }
+
+  return { checks, issues };
+}
+
 function cmdDoctor(root, extraArgs = []) {
   const repair = extraArgs.includes('--repair');
+  const jsonMode = extraArgs.includes('--json');
   const manifest = readManifest(root);
+
+  if (jsonMode) {
+    const { checks, issues } = collectDoctorChecks(root, manifest);
+    const report = buildDoctorJsonReport(root, manifest, issues, checks);
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(report.decision === 'healthy' ? 0 : 1);
+    return;
+  }
+
   const issues = [];
 
   console.log(repair ? 'workframe doctor --repair' : 'workframe doctor');
@@ -287,7 +415,7 @@ function usage() {
   console.log(`workframe — lifecycle CLI for Workframe projects
 
 Usage:
-  workframe doctor [--repair]     Diagnose stack; --repair provisions missing agent DM runtimes
+  workframe doctor [--repair] [--json]  Diagnose stack; --json mutation-free report
   workframe setup               Open Hermes setup (credentials)
   workframe start               Start the full stack (docker compose up -d)
   workframe stop                Stop all stack containers

package/docs/security.md

@@ -53,7 +53,7 @@ In `public_multi_user`, credential-mediated traffic must not depend on agent coo
 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.
+5. Optional strict profile (`WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true`) blocks **direct** outbound connections to known provider API hostnames via the `gateway-egress-guard` iptables sidecar (`docker-compose.egress-broker.yml`) 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.
 
@@ -63,7 +63,7 @@ This is **routing and secret placement**, not disabling `terminal` or adding hum
 |------|----------------|----------------------|
 | `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 |
+| `public_multi_user` + `WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true` | Unrestricted except provider-host deny via egress-guard sidecar | 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).
 

package/package.json

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

package/scripts/bundle-workframe-ui.mjs

@@ -59,6 +59,15 @@ if (!fs.existsSync(path.join(dist, 'index.html'))) {
 console.log(`Copying ${dist} -> ${UI_DEST}`);
 copyTree(dist, UI_DEST);
 
+const pkgVersion = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+const gitRef = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf8', cwd: REPO_ROOT });
+const buildStamp = {
+  package_version: pkgVersion,
+  bundled_at: new Date().toISOString(),
+  git_ref: gitRef.status === 0 ? gitRef.stdout.trim() : '',
+};
+fs.writeFileSync(path.join(UI_DEST, 'workframe-build.json'), `${JSON.stringify(buildStamp, null, 2)}\n`);
+
 const avatarShared = path.join(PKG_ROOT, 'shared', 'agent-avatars');
 
 function copyPresetPngs(src, dst, { keepCatalog = false } = {}) {

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

@@ -110,6 +110,7 @@ const applyScripts = [
   'setup-stack-secrets.sh',
   'bootstrap-workspace-link.sh',
   'verify-public-deploy.sh',
+  'gateway-egress-iptables.sh',
   'fix-zk-encryption-key.sh',
   'set-compose-public-url.mjs',
   'ensure-compose-host-paths.mjs',

package/scripts/verify-public-deploy.sh

@@ -20,9 +20,10 @@ gateway_container_name() {
 }
 
 report_egress_posture() {
-  local gw force_broker gw_on_control internal_control
+  local gw force_broker gw_on_control internal_control egress_overlay
   gw="$(gateway_container_name)"
   force_broker="$(env_val WORKFRAME_FORCE_AGENT_EGRESS_BROKER)"
+  egress_overlay="$COMPOSE_DIR/docker-compose.egress-broker.yml"
 
   if grep -A30 '^  gateway:' "$COMPOSE_FILE" | grep -q 'control-net'; then
     gw_on_control=yes
@@ -48,7 +49,15 @@ report_egress_posture() {
     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)"
+    if [[ "$force_broker" =~ ^(1|true|yes|on)$ ]]; then
+      if docker inspect workframe-gateway-egress-guard >/dev/null 2>&1; then
+        info "egress gateway_egress_posture=provider_hosts_blocked (egress-guard sidecar)"
+      else
+        fail "WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true but gateway-egress-guard is not running"
+      fi
+    else
+      info "egress gateway_egress_posture=unrestricted_general (broker for LLM/action providers)"
+    fi
   else
     info "egress gateway_egress_posture=unknown (gateway container not running)"
   fi
@@ -58,11 +67,60 @@ report_egress_posture() {
   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"
+    [[ -f "$egress_overlay" ]] || fail "missing $egress_overlay (required when WORKFRAME_FORCE_AGENT_EGRESS_BROKER=true)"
+    grep -q 'gateway-egress-guard' "$egress_overlay" || fail "egress overlay missing gateway-egress-guard service"
+    ok "forced broker egress overlay present"
   fi
   ok "egress posture reported"
 }
 
+report_supervisor_constraints() {
+  local public_overlay="$COMPOSE_DIR/docker-compose.public.yml"
+  if [[ -f "$public_overlay" ]]; then
+    grep -q 'WORKFRAME_SUPERVISOR_ALLOW_RAW_EXEC=0' "$public_overlay" \
+      || fail "docker-compose.public.yml must set WORKFRAME_SUPERVISOR_ALLOW_RAW_EXEC=0"
+    if grep -A30 '^  workframe-api:' "$public_overlay" | grep -q '/var/run/docker.sock'; then
+      fail "docker-compose.public.yml must not mount docker.sock on workframe-api"
+    fi
+    ok "supervisor public overlay constraints"
+  else
+    warn "docker-compose.public.yml missing — skipping supervisor overlay checks"
+  fi
+}
+
+report_broker_audit_schema() {
+  local data_dir
+  data_dir="$(cd "$ROOT" && pwd)/runtime/workframe-api-data"
+  if [[ ! -d "$data_dir" ]]; then
+    info "broker_audit schema=skipped (no runtime/workframe-api-data)"
+    return
+  fi
+  python3 - "$data_dir" <<'PY' || fail "broker_audit_events table missing (run API once or apply migration)"
+import sqlite3, sys
+from pathlib import Path
+db = Path(sys.argv[1]) / "workframe.db"
+if not db.is_file():
+    print("skip: no workframe.db yet")
+    raise SystemExit(0)
+conn = sqlite3.connect(str(db))
+row = conn.execute(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name='broker_audit_events'"
+).fetchone()
+conn.close()
+if not row:
+    raise SystemExit(1)
+PY
+  ok "broker audit schema"
+}
+
+report_backup_restore_evidence() {
+  local backup_doc="$ROOT/infra/compose/workframe/PUBLIC_DEPLOY.md"
+  [[ -f "$backup_doc" ]] || fail "missing PUBLIC_DEPLOY.md backup section"
+  grep -qi 'backup' "$backup_doc" || fail "PUBLIC_DEPLOY.md missing backup guidance"
+  grep -qi 'rollback\|restore' "$backup_doc" || fail "PUBLIC_DEPLOY.md missing restore/rollback guidance"
+  ok "backup/restore documented"
+}
+
 [[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
 [[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
 
@@ -158,4 +216,8 @@ fi
 
 report_egress_posture
 
+report_supervisor_constraints
+report_broker_audit_schema
+report_backup_restore_evidence
+
 ok "public_multi_user preflight passed"

package/workframe-api/action_proxy.py

@@ -9,8 +9,8 @@ import urllib.request
 from http.server import BaseHTTPRequestHandler
 from typing import Any, Callable
 
-import llm_proxy
-import turn_credentials
+import credential_broker
+import internal_proxy_auth
 
 UPSTREAM_BASE: dict[str, str] = {
     "github": "https://api.github.com",
@@ -21,6 +21,15 @@ UPSTREAM_BASE: dict[str, str] = {
 PROXY_PATH_RE = re.compile(r"^/internal/action/([a-z0-9_-]+)(/.*)?$", re.IGNORECASE)
 
 
+def _upstream_host(provider: str) -> str:
+    base = UPSTREAM_BASE.get(str(provider or "").strip().lower(), "")
+    return str(base).split("://", 1)[-1].split("/", 1)[0].lower()
+
+
+def authorize_internal_proxy(handler: BaseHTTPRequestHandler) -> tuple[bool, str]:
+    return internal_proxy_auth.authorize_internal_proxy(handler)
+
+
 def upstream_auth_header(provider: str, secret: str) -> dict[str, str]:
     provider = str(provider or "").strip().lower()
     secret = str(secret or "").strip()
@@ -45,24 +54,21 @@ def forward_request(
     if not base:
         return 404, {"Content-Type": "application/json"}, json.dumps({"error": "unknown provider"}).encode()
 
-    token = llm_proxy.extract_bearer(headers)
-    lease = turn_credentials.validate_lease(token)
-    if not lease:
-        return 401, {"Content-Type": "application/json"}, json.dumps({"error": "invalid lease"}).encode()
-    if str(lease.get("provider") or "").lower() != provider:
-        return 403, {"Content-Type": "application/json"}, json.dumps({"error": "provider mismatch"}).encode()
-
-    ok_profile, profile_err, profile_status = llm_proxy.validate_lease_profile(lease, headers)
-    if not ok_profile:
+    auth = credential_broker.authorize_broker_lease(
+        provider,
+        headers,
+        resolve_secret=resolve_secret,
+        broker_kind="action",
+        upstream_host=_upstream_host(provider),
+    )
+    if not auth.ok:
         return (
-            profile_status,
+            auth.status,
             {"Content-Type": "application/json"},
-            json.dumps({"error": profile_err}).encode(),
+            credential_broker.broker_error_body(auth),
         )
 
-    _env_var, secret = turn_credentials.resolve_lease_secret(lease, resolve_secret)
-    if not secret:
-        return 402, {"Content-Type": "application/json"}, json.dumps({"error": "no credential"}).encode()
+    secret = auth.secret
 
     path = subpath if subpath.startswith("/") else f"/{subpath}"
     url = f"{base.rstrip('/')}{path}"
@@ -100,7 +106,7 @@ def handle_proxy_request(
     *,
     resolve_secret: Callable[[str, str, str, str], tuple[str, str]],
 ) -> bool:
-    ok, err = llm_proxy.authorize_internal_proxy(handler)
+    ok, err = authorize_internal_proxy(handler)
     if not ok:
         handler.send_response(403)
         handler.send_header("Content-Type", "application/json")