{"path":"ARCHITECTURE.md","size":2952,"locked":false,"binary":false,"truncated":false,"content":"# ARCHITECTURE & SECURITY SPECIFICATION — AgentSafeWorkspace SDK\n\n### Layered Defense Architecture\n\n```\n+-------------------------------------------------------------+\n|               LLM TOOL INVOCATION / AGENT LOOP             |\n+-------------------------------------------------------------+\n                              |\n                              v\n+-------------------------------------------------------------+\n|                AGENT SAFE WORKSPACE BARRIER                 |\n|                                                             |\n|   1. Path Containment Filter (assertPathContained)          |\n|      - Path normalization, root prefix validation           |\n|                                                             |\n|   2. Secret Shield Filter (assertNotSecretFile)             |\n|      - Blacklist: .env*, .npmrc, id_rsa, .pem, .key         |\n|                                                             |\n|   3. Symlink Barrier (lstat + O_NOFOLLOW)                   |\n|      - Rejects symlink traversal at descriptor level        |\n|                                                             |\n|   4. Command Policy Engine (CommandPolicyEngine)            |\n|      - Regex blacklist: rm -rf /, sudo, curl | bash         |\n|      - Whitelist prefix validation                          |\n|                                                             |\n|   5. SHA-256 Audit Chainer                                  |\n|      - Cryptographic log of all approved/blocked events     |\n+-------------------------------------------------------------+\n                              |\n                              v\n+-------------------------------------------------------------+\n|                HOST OPERATING SYSTEM & FILESYSTEM           |\n+-------------------------------------------------------------+\n```\n\n### Threat Model Matrix\n\n| Threat Class | Attack Scenario | Defense Mechanism | Test Evidence |\n| :--- | :--- | :--- | :--- |\n| **Path Traversal** | Agent invokes `read_file(\"../../etc/passwd\")` | Strict normalization against resolved root path. Rejects if target does not start with `rootPath + path.sep`. | `test_adversarial: Vector 1` (PASS) |\n| **Symlink Escape** | Repo contains `link -> /Users/target/.ssh` | Pre-flight `lstatSync` and POSIX `O_NOFOLLOW` flag during file descriptor open. | `test_adversarial: Vector 6` (PASS) |\n| **Secret Exfiltration** | Agent attempts reading `.env` or `id_rsa` | Explicit secret file and extension blacklist checks before file descriptor allocation. | `test_adversarial: Vectors 3, 4, 5` (PASS) |\n| **Destructive Commands**| Agent executes `rm -rf /` or `sudo reboot` | Regular expression guard blocks dangerous shell commands and privilege escalation. | `test_adversarial: Vector 7` (PASS) |\n| **Tampering of Logs** | Rogue subagent deletes or alters trace | Forward-chained SHA-256 hash log (`hash = sha256(event + prevHash)`). | `test_adversarial: Vector 9` (PASS) |\n"}