Merge pull request #103 from bbartling/chore/openclaw-auth-preflight-tooling

Chore/openclaw auth preflight tooling

Author: bbartling

openclaw/HANDOFF_PROTOCOL.md

@@ -52,8 +52,17 @@ So the loop is **mailbox-style**: `issues_log.md` is the inbox/outbox; log files
 | Who | Role |
 |-----|------|
 | **You (human)** | Run gateway, paste prompts, commit/push, decide when to escalate |
-| **Cursor / “senior”** | Architecture, code fixes, script changes, doc structure, triage of hard failures |
-| **OpenClaw / “junior”** | Execute repeatable commands, capture logs, file issues, small safe edits you allow |
+| **Cursor / “senior”** | Architecture, Open-FDD product fixes, code-path hardening, commit SHAs for retest |
+| **OpenClaw / tester** | Execute repeatable bench checks, capture logs, file/comment on issues, maintain OpenClaw-side tooling/context |
+
+## Current GitHub contract (2026-03-27)
+
+Use GitHub as the handoff surface.
+
+- **Cursor agents** provide: commit SHA + issue IDs + explicit acceptance criteria.
+- **OpenClaw** responds with: pass/fail, exact query/payload, expected vs actual, UTC timestamps, bench URLs/context, and harness-drift vs product-defect classification.
+- **OpenClaw does not edit product code** during this loop unless the human explicitly changes that rule.
+- **Cursor does not assume parity failures are product bugs** until OpenClaw confirms healthy auth preflight and bench context.
 
 ## Failure classification required in handoffs
 

openclaw/README.md

@@ -23,8 +23,8 @@ OpenClaw may run on a different machine than Open-FDD. For split setup details s
 ## Current bench reality (keep this straight)
 
 - Bench/frontend/backend/BACnet reachability can be healthy while auth context is still wrong.
-- Current direct authenticated check has failed with `FORBIDDEN: Invalid API key`.
-- Treat this as **launcher/env/runtime-context drift** unless proven otherwise.
+- Missing or invalid `OFDD_API_KEY` should be treated as **launcher/env/runtime-context drift** unless proven otherwise.
+- If Open-FDD is running on another machine, load the active `.env` into the shell or point `OPENCLAW_STACK_ENV` at it before calling auth-sensitive APIs.
 - **Do not delete or bury issue `#92`**; keep it as likely real product parity tracking once auth is healthy.
 - Do not frame auth-context drift itself as a confirmed product bug without clean repro under known-good auth.
 

openclaw/SKILL.md

@@ -77,6 +77,9 @@ Do not blend security hardening notes into unrelated defect triage without clear
 - Do not treat coding changes as the primary goal.
 - Keep issue/evidence trail in `openclaw/issues_log.md`.
 - Use `openclaw/HANDOFF_PROTOCOL.md` for Cursor/OpenClaw handoff discipline.
+- In the current operating model: **Cursor = product engineer, OpenClaw = tester**.
+- When Cursor provides a commit SHA + issue IDs + acceptance criteria, retest the live bench against that SHA, do **no product-code edits**, and post evidence back to GitHub.
+- Healthy auth preflight is required before drawing frontend/API parity conclusions.
 
 ## References to read first
 

openclaw/bench/e2e/2_sparql_crud_and_frontend_test.py

@@ -158,14 +158,17 @@ def _load_env_file(path: str) -> None:
 
 def _load_stack_env() -> None:
     repo_root = SCRIPT_DIR.parent.parent.parent
-    candidate_envs = [
-        repo_root / "stack" / ".env",
-        Path(os.getcwd()) / ".env",
-        SCRIPT_DIR / ".env",
-    ]
     extra = os.environ.get("OPENCLAW_STACK_ENV", "").strip()
+    candidate_envs: list[Path] = []
     if extra:
         candidate_envs.append(Path(extra))
+    candidate_envs.extend(
+        [
+            repo_root / "stack" / ".env",
+            Path(os.getcwd()) / ".env",
+            SCRIPT_DIR / ".env",
+        ]
+    )
     home_stack = Path.home() / ".openclaw" / "workspace" / "open-fdd" / "stack" / ".env"
     candidate_envs.append(home_stack)
     for env_path in candidate_envs:
@@ -179,6 +182,37 @@ def _load_stack_env() -> None:
 # Mutable container so main() can set timeout without `global` (SPARQL on large graphs can exceed 30s).
 _HTTP_TIMEOUT_SEC: dict[str, float] = {"sec": 120.0}
 
+def _auth_preflight(api_url: str) -> tuple[bool, str | None]:
+    """Fail fast when backend auth is enabled but the harness has no usable key."""
+    code, _, err = _request(api_url, "GET", "/sites")
+    if code == 200:
+        if API_KEY:
+            print("Auth preflight: OK (authenticated backend access available).")
+        else:
+            print("Auth preflight: OK (backend accepted anonymous access).")
+        return True, None
+    if code == 401:
+        if API_KEY:
+            return (
+                False,
+                "Auth preflight FAIL — backend rejected OFDD_API_KEY (401 Unauthorized). "
+                "Treat this as auth/runtime-context drift before triaging product bugs.",
+            )
+        return (
+            False,
+            "Auth preflight FAIL — backend requires OFDD_API_KEY but none was loaded. "
+            "Load stack/.env or set OFDD_API_KEY (for split setups you can point OPENCLAW_STACK_ENV at the active .env).",
+        )
+    if code == 403:
+        return (
+            False,
+            "Auth preflight FAIL — backend rejected OFDD_API_KEY (403 Forbidden). "
+            "Treat this as auth/runtime-context drift before triaging product bugs.",
+        )
+    if code == 0:
+        return False, f"Auth preflight FAIL — transport error while checking /sites: {err}"
+    return False, f"Auth preflight FAIL — GET /sites -> {code}{f' — {err}' if err else ''}"
+
 
 def _format_api_error(body: dict | list | None, fallback_text: str = "") -> str:
     """Extract human message from Open-FDD JSON error body or raw text."""

openclaw/bench/e2e/4_hot_reload_test.py

@@ -57,6 +57,9 @@ def _load_env_file(path: str) -> None:
 
 
 def _load_stack_env() -> None:
+    extra = os.environ.get("OPENCLAW_STACK_ENV", "").strip()
+    if extra:
+        _load_env_file(extra)
     _load_env_file(str(REPO_ROOT / "stack" / ".env"))
     _load_env_file(os.path.join(os.getcwd(), ".env"))
     _load_env_file(str(SCRIPT_DIR / ".env"))
@@ -67,6 +70,38 @@ def _load_stack_env() -> None:
 API_KEY = os.environ.get("OFDD_API_KEY", "").strip()
 
 
+def _auth_preflight(api_url: str) -> tuple[bool, str | None]:
+    code, body = _request(api_url, "GET", "/sites")
+    if code == 200:
+        if API_KEY:
+            print("Auth preflight: OK (authenticated backend access available).")
+        else:
+            print("Auth preflight: OK (backend accepted anonymous access).")
+        return True, None
+    detail = ""
+    if isinstance(body, dict):
+        detail = str(body.get("detail") or body.get("message") or "").strip()
+    if code == 401:
+        if API_KEY:
+            return (
+                False,
+                "Auth preflight FAIL — backend rejected OFDD_API_KEY (401 Unauthorized). "
+                "Treat this as auth/runtime-context drift before triaging product bugs.",
+            )
+        return (
+            False,
+            "Auth preflight FAIL — backend requires OFDD_API_KEY but none was loaded. "
+            "Load stack/.env or set OFDD_API_KEY (for split setups you can point OPENCLAW_STACK_ENV at the active .env).",
+        )
+    if code == 403:
+        return (
+            False,
+            "Auth preflight FAIL — backend rejected OFDD_API_KEY (403 Forbidden). "
+            "Treat this as auth/runtime-context drift before triaging product bugs.",
+        )
+    return False, f"Auth preflight FAIL — GET /sites -> {code}{f' — {detail}' if detail else ''}"
+
+
 def _request(api_url: str, method: str, path: str, json_body: dict | None = None) -> tuple[int, dict | list]:
     try:
         import httpx
@@ -327,6 +362,11 @@ def main() -> int:
     else:
         print(f"API URL: {api_url}")
 
+    auth_ok, auth_err = _auth_preflight(api_url)
+    if not auth_ok:
+        print(auth_err, file=sys.stderr)
+        return 1
+
     site_id_for_faults = None
     if verify_faults:
         site_id_for_faults = _resolve_site_identifier(api_url, site_hint)