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 is an exact, fail-closed unit grammar. The only sections are [Unit], [Service] and [Install]. Each section has a directive allowlist; every single-value directive and every repeated Environment, ReadOnlyPaths and ReadWritePaths entry must match the governed Shadow unit contract exactly.

The profile fixes the Python module task_plane.workers.codex_review_test, User=aiman, Group=gitops, the controlled /usr/libexec/aios-codex-review-test-worker/current working directory, all hardening switches and the three permitted environment variables. It grants read access only to the authoritative bare repository and the versioned worker artifact, and write access only to the worker runtime, state and cache directories.

Unknown sections or directives are rejected, including lifecycle hooks, credential injection, environment imports, root images, bind mounts, capability expansion, devices, sockets and top-level writable paths. The parser also rejects duplicate sections, duplicate single-value directives, empty resets, continuation lines, CRLF, NUL, non-UTF-8 surrogate content, overlong lines and Unicode lookalike directive names. It does not use ConfigParser(strict=False) or silently merge repeated values.

Production credentials, if later authorized, must be supplied by a separately governed deployment drop-in. They are not permitted in the source unit or this content profile.

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