aios/docs/gitops/isolated-writer-path-policy-v1.md

Isolated Writer Exact-Path Policy V1

This policy is an additional, service-owned authorization layer for POST /api/commit-file. It never expands a Token Policy V2 grant.

An atomic write is permitted only when all of the following agree:

1. socket peer, audience, operation, branch, base and exact path in the Token Policy V2 grant;
2. service audience, repository identity, branch, operation and exact path in AIOS_GITOPS_PATH_POLICY_FILE;
3. lexical path, resolved containment and symlink checks;
4. the configured content-size and content-profile checks;
5. operation digest, expected branch HEAD and durable operation ledger.

Any failed layer returns a fail-closed policy error. Coarse /api/file and /api/commit routes remain forbidden.

File contract

The configured path must be absolute. The parent directory must be root:gitops 0750; the regular, non-symlink file must be root:gitops 0640. JSON must use UTF-8 canonical encoding with sorted keys, compact separators and one trailing newline. Unknown fields, unsupported operations or profiles, duplicate paths, oversized policies and group/world-writable files are rejected during Writer startup.

Example:

{"allowed_branch":"patch/codex-review-test-worker-20260724","allowed_operations":{"commit_file.atomic":{"content_profile":"systemd-codex-review-worker-v1","exact_paths":["deploy/systemd/aios-codex-review-test-worker.service"],"max_content_bytes":32768}},"audience":"aios-codex-review-worker-writer.service","policy_id":"codex-review-worker-path-policy-v1","repository_identity":"aios/aios","schema_version":1}

The SHA-256 of the canonical policy is exposed in the isolated runtime status and written to the operation audit record. The request body cannot select or override the policy file.

Content profile

systemd-codex-review-worker-v1 requires the fixed Python module task_plane.workers.codex_review_test, Shadow execution, NoNewPrivileges, ProtectSystem=strict and PrivateTmp. It rejects shell execution, root user declarations, worktree paths, authorization material and plaintext credential markers.

Policy changes require a separate maintenance branch and Owner-reviewed ordinary merge commit. A task-scoped Writer must not edit its own policy file.