notarius/docs/roadmap/deployment-managed-cache-permissions.md

Deployment-Managed Cache Permissions

Status: proposed

Summary

Stop treating cache access permissions as application policy. Notarius should create chunk-plan and checkpoint state through conventional Unix filesystem semantics and leave the effective owner, group, and access policy to the operator's provisioned directories, process umask, setgid inheritance, and default ACLs.

Notarius continues to own safe paths, symlink rejection, atomic publication, cache validation, and recovery. It does not decide whether a configured cache is private to one account, shared by a trusted group, or readable under some other deployment policy.

Motivation And Current Problem

The current cache implementations enforce a policy that was stronger than the application requires:

• the chunk-plan store creates and repeatedly converges cache directories to 0700 and atomic files to 0600; and
• the checkpoint recorder supplies 0700 directory and 0600 file modes to the shared confined writer, which explicitly applies the file mode during atomic publication.

This prevents an administrator from using ordinary Unix provisioning to share one cache between a service account and trusted operator accounts. Adding a second Notarius-specific private or group configuration policy would solve that immediate symptom, but it would preserve the underlying ownership error: Notarius would still decide access policy instead of respecting the deployment.

Routine Notarius operation does not require an application-enforced private cache. Cache records can contain source-derived data, so operators must be told what they are storing, but sensitivity does not imply that Notarius should override a deliberately configured filesystem policy. API credentials remain outside cache payloads and continue to follow their existing configuration and redaction boundaries.

Target Policy

The target contract is:

Notarius creates cache entries with conventional maximum creation modes and allows the operating system to determine effective access through the process umask, inherited group ownership, and default ACLs.

Concretely:

• newly created cache directories request 0777;
• newly created cache files, including atomic temporary files, request 0666;
• the kernel applies the invoking process's umask and any applicable default ACL;
• setgid directories provisioned by the operator control inherited group ownership and, on supported Unix systems, setgid propagation to descendants;
• Notarius does not call chmod, chown, or chgrp to impose or repair a cache access policy; and
• Notarius does not reject a cache merely because its effective modes are more or less permissive than a Notarius-selected default.

This is policy inheritance, not literal copying of a parent directory's mode bits. Directories and non-executable data files appropriately have different maximum modes. A parent mode alone also does not determine child modes: an operator who needs a particular result must configure the service umask and, where appropriate, a setgid parent or default ACL.

For example, a service started with umask 0077 ordinarily creates 0700 directories and 0600 files. A trusted-group deployment can provision a setgid cache root and use umask 0007, or an equivalent default ACL, to obtain 0770 directories and 0660 files. These are deployment choices rather than configuration values interpreted by Notarius.

Public Contract

No new Notarius configuration field, environment variable, or CLI flag is introduced. In particular, do not add the previously considered cache.access: private|group setting.

Existing cache enablement, locations, chunk-plan modes, resume controls, identity, and compatibility rules remain unchanged. The behavioral change is that effective permissions on newly created cache entries are controlled by the deployment environment rather than forcibly converged by Notarius.

The policy applies uniformly to both cache families:

• canonical chunk plans; and
• invocation checkpoints.

Output and debug storage are outside this feature's scope. Their current contracts must not change incidentally through a shared helper refactor. A separate review may later consider whether the same deployment-owned policy is appropriate for those surfaces.

Filesystem And Atomic-Publication Requirements

Permission deference must cover every cache write path, not only final files:

• configured cache-family roots created by Notarius;
• chunk-plan source-digest directories;
• checkpoint identity and stage directories;
• atomic temporary files; and
• final files published by rename.

Atomic publication must not bypass the deployment policy. Go's os.CreateTemp creates a file with 0600, and applying chmod(0666) afterward would bypass the process umask. Cache writers therefore need an atomic temporary-file creation path that chooses a collision-resistant name and opens it with O_CREATE|O_EXCL and requested mode 0666, allowing the kernel to apply umask and default ACL policy at creation time.

Replacement writes publish a newly created temporary inode. Its effective permissions and ACL are therefore those selected for new entries by the current parent and process policy; Notarius does not copy mode bits or ACLs from the replaced file. Operators who require stable replacement permissions must express that policy through a stable service umask and directory default ACL.

Opening an existing cache for writing must not alter its root or descendant modes. Read-only lookup of a missing cache must remain side-effect free.

Preserved Safety And Correctness Boundaries

Deferring access policy does not weaken Notarius's filesystem correctness rules. The implementation must preserve:

• confined resolution beneath the selected cache root;
• rejection of symlinked or unexpected cache entries;
• validation of source digests, checkpoint identities, schemas, and recorded provenance;
• atomic replacement, existing synchronization behavior, cleanup of abandoned temporary files, and complete-record visibility;
• existing missing, malformed, incompatible, and operational-error recovery classifications; and
• separation of output, cache, and debug roots.

An administrator's decision to permit multiple accounts to reach one cache does not create a new Notarius guarantee for simultaneous writers. Preserve the existing atomicity and validation behavior, but do not add locking or claim transactional coordination across concurrent processes as part of this work. Concurrent writes to the same multi-file checkpoint identity remain subject to the currently documented cache behavior; the implementation documentation must state any existing limitation accurately.

Architectural Boundaries

The target removes application-owned cache modes without creating a general permission-policy framework. Chunk-plan and checkpoint storage may use different filesystem APIs internally, but both must implement the same deployment-owned result. Pipeline modules and the runner remain unaware of physical roots and filesystem access policy.

Any shared writer API must distinguish an application-enforced exact mode from an umask-filtered maximum creation mode. The cache change must not silently alter output or debug behavior merely because checkpoints currently share filesystem helpers with those surfaces.

Existing Cache Migration

Stopping permission convergence does not change existing inode modes. A cache tree created by an older Notarius version may therefore remain 0700/0600 and inaccessible to another account after upgrade.

Operators who want a different policy must either:

• remove the reconstructible cache and allow it to be recreated beneath a correctly provisioned parent and service environment; or
• stop writers and deliberately update ownership, modes, and ACLs using normal system-administration tools.

Notarius must not perform a recursive startup migration. The same rule applies when an operator wants to make a previously shared cache private: change the deployment policy and deliberately migrate or recreate existing state when an immediate whole-tree change is required.

Documentation And Decision Records

The final documentation set includes an accepted ADR titled along the lines of "Defer cache access policy to the deployment." The ADR records the durable ownership boundary so later maintenance does not reintroduce application-enforced modes solely because cache data can contain source-derived content.

The new ADR need not supersede ADR-0005 or ADR-0007: those decisions govern canonical chunk-plan reuse and checkpoint recording/reuse, while leaving exact storage permissions to operational contracts. It should reference those ADRs and the output/cache/debug separation established by ADR-0006 and refined by ADR-0007.

In the final current-behavior documentation, docs/operations.md owns cache provisioning, umask, setgid, default ACL, migration, sensitivity, and concurrent-use guidance. Architecture owns the deployment/application boundary; the configuration reference clarifies that selecting a cache path does not select its permissions; and the internal state guide explains the implemented write mechanics. The release that first contains the feature summarizes the operational change without becoming its canonical reference.

Current-behavior documentation must not describe this target behavior before the implementation lands.

Verification Expectations

Behavioral tests protect kernel-selected permissions for both cache families, non-mutation of existing roots, atomic replacement, and representative assembled CLI wiring. Existing confinement, symlink, validation, identity, reuse, and recovery coverage remains authoritative. Umask tests are POSIX-only, serialized, and restore process-global state. The default suite does not create privileged accounts or groups; setgid and default-ACL examples may be verified in a purpose-built Linux deployment environment.

Acceptance Criteria

• No cache access-mode field or application-specific private/group policy is added.
• Both chunk-plan and checkpoint writers request 0777 for new directories and 0666 for new files, including atomic temporary files.
• Effective permissions reflect the process umask and applicable default ACLs rather than a later Notarius chmod.
• Existing cache roots and descendants are not chmod-converged during reads or writes.
• A private deployment can obtain private cache state through its filesystem provisioning and umask without a Notarius-specific setting.
• A trusted-group deployment can obtain shared cache state through setgid, umask, and/or default ACL policy without a Notarius-specific setting.
• Existing cache trees are not recursively migrated.
• Chunk-plan and checkpoint enablement, lookup, recording, resume, identity, validation, confinement, atomicity, and recovery semantics remain unchanged.
• Output and debug permission behavior does not change as an incidental effect.
• Notarius performs no user/group management, ownership mutation, ACL management, privilege escalation, or cross-process locking.
• The ADR and canonical operations, architecture, configuration, and internal documentation accurately describe the implemented boundary; the next release note summarizes the change when that release is prepared.
• Focused tests and repository-wide go test ./..., go vet ./..., and go build ./cmd/notarius checks pass.