AI Translation Notice
Translated/synchronized from the authoritative Chinese documentation (架构全景与安全决策). Check source files or Chinese docs if subtle phrasing differs.
Architecture & Security ADRs
AgentDock Bridge enforces three strict separation planes: no persisted workspace secrets on Cloudflare, no direct host command/file execution in the connector process, and no host tokens or default outbound networking inside the Linux container.
Interactive Topology Diagram
Diagram vs. Source Note: The visual diagram summarizes the four zones at a conceptual level. In actual code, client RPCs use stateless HTTP
POST /mcp(JSON-RPC 2.0 rather than SSE log streams),OAuth 2.1 + PKCE (S256), an outboundWSS /bridgeWebSocket from the host connector, and per-calldocker create+docker start --attachafterApprove.cmd.
Core Subsystem Handoff
- Cloudflare Worker (
cloud/): Routes public traffic, runsAuthCoordinator(owner-v2-*SQLite DO) for OAuth 2.1 + PKCE + refresh rotation, and forwards validated JSON-RPC envelopes viaBridgeRelay(primaryDO). - Windows Host Connector (
local/+scripts/): Decryptssecrets.dpapiin a sanitized PowerShell subprocess, re-validates envelopes (validateRequestEnvelope), enforces exact canonical SHA-256 approvals (Approve.cmd) and pre-executionRequestReceipts, checks NTFS DACLs before file replacement, and drives the Docker CLI. - Linux Sandbox (
container/): Runs PID 1runner.mjs(20s host lease watchdog, UID/GID 1000) dispatching eitherbash --noprofile --norcorfile-worker.mjs(allowExec: false+file-safety.mjs).
Follow a single call end-to-end in End-to-End Request Walkthrough or locate files in Source & Test Code Map.
Security ADRs and Migration
ADR-01: Password-Hash Generation Isolation (owner-v2-*) & CIMD Metadata Repair
To prevent downgraded CIMD or legacy grants from surviving re-authorization or password changes (R4-01), AuthStore.completeMetadata reconstructs canonical grant:* metadata on every write/list, and cloud/index.mjs namespaces AuthCoordinator as owner-v2-${sha256(OWNER_PASSWORD_HASH)}. Any password rotation invalidates all prior grants immediately; clients must re-authorize.
ADR-02: Out-of-Lock Preparation & Optimistic Revision Commits
To keep slow HTTP uploads or external CIMD/JWKS fetches from blocking all OAuth and MCP traffic (R4-03), cloud/index.mjs buffers bounded request bodies before entering AuthCoordinator, and AuthTransactions executes preparation outside AuthQueue, checking revision before synchronous SQLite commits with lane caps (authorization: 4, mcp: 32, stop: 4) and 4 retries.
ADR-03: Dedicated Stop Lane & Cleanup-Failure Fallback
To ensure a saturated control receipt cache or failed docker rm -f never prevents an owner from stopping active jobs (R4-04 / FINAL-01), stop_command has dedicated concurrency limits and StopReceipts (128 FIFO), and sandbox.mjs evaluates owner-scoped command_status/get_command/stop_command before rejecting new operations under closed = true.
ADR-04: Compact JSON Approval Budget, Merged CSP & Host Hardening
approval-store.mjs validates compact UTF-8 size (1,200,000 B) before temp-file creation; /authorize merges rather than overwrites zero-script CSP headers; Install-NodeRuntime.ps1 pins Node 24.22.1 (SHA-256 + OpenJS signature) inside ACL-verified private toolchains; windows-acl.mjs refuses atomic Linux rename over files with custom explicit NTFS DACLs.
Upgrade Checklist
- Run
pnpm install --frozen-lockfile && pnpm run check && pnpm testin the updated checkout. - Run
Stop.cmd, rebuildcontainer/Dockerfile, and re-run.\scripts\Install-Hardened.ps1 -Workspace "<workspace-path>"(preserves%USERPROFILE%\.agentdock-bridgeDPAPI secrets and receipts). - Run
pnpm run deployifcloud/orwrangler.jsoncchanged, then restart withStart.cmdand verifyStatus.cmd.
Evidence & Verification Boundaries
Verification logs for real Windows ACLs, pinned Docker runs, and live Cloudflare endpoints belong to the specific commit snapshots in SECURITY-FIXES.md. Cross-platform doc/test checks on Linux automatically skip the 15 Windows/Docker-specific cases.