.cairn-state/ must be invisible and unreachable from every user surface

Cordy commented

2026-08-09 03:17:09 +00:00

Owner

Depends on #152 (prefix decided). The reserved prefix holds ciphertext credentials; no user-facing surface may list, read, write, share, or deliver into it — including admins, whose unscoped view addresses the whole backend.

Surfaces to gate, each with a test:

REST file API (list/download/upload/mkdir/rename/copy/delete) — .cairn-state filtered from root listings and rejected as a path component.
WebDAV — same paths via the DAV handler.
Trash/restore — cannot restore into it.
Share links — creation on a .cairn-state path refused; existing-share resolution cannot traverse into it.
Peering delivery — the recipient path is already constrained to /home/…, add the explicit test anyway.
Spaces — a space named .cairn-state (or the prefix appearing under /spaces) cannot be created.

Implementation choice to make: one guard at the storage-driver boundary (a reserved decorator innermost, mirroring how scope works outermost) versus per-surface checks. The decorator is one place to be right; record the choice. Note the guard must NOT block the statestore itself — it goes through the raw driver below the decorator.

Also: root listings for unscoped admins hide the prefix (like dotfiles are handled today, but enforced server-side, not cosmetically).

Depends on #152 (prefix decided). The reserved prefix holds ciphertext credentials; no user-facing surface may list, read, write, share, or deliver into it — including admins, whose unscoped view addresses the whole backend. **Surfaces to gate, each with a test:** - REST file API (list/download/upload/mkdir/rename/copy/delete) — `.cairn-state` filtered from root listings and rejected as a path component. - WebDAV — same paths via the DAV handler. - Trash/restore — cannot restore into it. - Share links — creation on a `.cairn-state` path refused; existing-share resolution cannot traverse into it. - Peering delivery — the recipient path is already constrained to `/home/…`, add the explicit test anyway. - Spaces — a space named `.cairn-state` (or the prefix appearing under `/spaces`) cannot be created. Implementation choice to make: one guard at the storage-driver boundary (a `reserved` decorator innermost, mirroring how scope works outermost) versus per-surface checks. The decorator is one place to be right; record the choice. Note the guard must NOT block the statestore itself — it goes through the raw driver below the decorator. Also: root listings for unscoped admins hide the prefix (like dotfiles are handled today, but enforced server-side, not cosmetically).

Cordy added this to the v0.6 — Stateless instance (state-in-backend) milestone

2026-08-09 03:17:09 +00:00

Cordy referenced this issue

2026-08-09 03:17:59 +00:00

v0.6 acceptance: the delete-the-volume dogfood #159

Cordy referenced this issue

2026-08-09 03:18:12 +00:00

State-in-backend: instance state lives encrypted in the storage backend, not on local disk #138

Cordy referenced this issue

2026-08-09 03:41:14 +00:00

v0.6 ADR: state store abstraction — envelope, atomicity, and the config/state line (gates the milestone) #152

Cordy referenced this issue

2026-08-09 03:41:24 +00:00

State-in-backend: instance state lives encrypted in the storage backend, not on local disk #138

Cordy referenced this issue from a commit

2026-08-09 06:33:41 +00:00

feat(#155): reserved-prefix storage decorator (innermost, D9)

Cordy referenced this issue from a commit

2026-08-09 06:34:09 +00:00

test(#155): reserved decorator - hidden listings, blocked ops, raw passthrough

forgejo-actions referenced this issue from a commit

2026-08-09 06:48:09 +00:00

feat: #155 reserved-prefix guard, #156 instance lock, #160 setup mode + storage card (splices)

Cordy referenced this issue

2026-08-09 06:54:56 +00:00

v0.6 session 3: reserved-prefix guard (#155), instance lock (#156), storage connect + setup mode (#160) #165

Cordy referenced this issue from a commit

2026-08-09 06:55:16 +00:00

Merge pull request 'v0.6 session 3: reserved-prefix guard (#155), instance lock (#156), storage connect + setup mode (#160)' (#165) from feat-s3-guards into main

Cordy commented

2026-08-09 07:02:26 +00:00

Author

Owner

Shipped in v0.5.5 (PR #165), live on the dogfood.

Implementation choice, recorded: one guard at the storage-driver boundary — internal/storage/reserved, an INNERMOST decorator mirroring scope's outermost position — rather than per-surface checks. Every surface this issue lists (REST file API, WebDAV, trash/restore, share resolution, spaces, peering delivery) addresses storage through the decorated stack, so one guard covers them all, unscoped admins included, enforced server-side. The statestore holds the raw driver captured before the wrap, so state operations pass underneath by construction (proven by test TestRawDriverBelowGuardStillReachesState).

Scope decisions: /.cairn-state AND /.cairn are blocked as root subtrees — the posix state directory holds the same secret class (auth verifiers, peering credentials) and was previously admin-downloadable. The .cairn-state name is additionally blocked as a segment anywhere, so a space or folder named after the prefix cannot be created on any surface (covers the spaces requirement without touching spaces code). A deep directory legitimately named .cairn remains ordinary content. Blocked paths answer ErrNotFound, never "forbidden": confirming existence would leak what the guard hides. Like scope, the decorator does NOT embed storage.Driver — every method explicit, so an interface addition can never silently bypass it. Usage forwarded for quota.

Tests: root listing hides both entries; all eight ops (List/Stat/Open/Write/Delete/Mkdir/Rename/Copy, both directions for the two-path ops) return ErrNotFound on six representative reserved paths; the sentinel still satisfies fs.ErrNotExist (the #153 lesson, now regression-tested); nested .cairn allowed; ordinary content untouched.

Shipped in **v0.5.5** (PR #165), live on the dogfood. **Implementation choice, recorded:** one guard at the storage-driver boundary — `internal/storage/reserved`, an INNERMOST decorator mirroring scope's outermost position — rather than per-surface checks. Every surface this issue lists (REST file API, WebDAV, trash/restore, share resolution, spaces, peering delivery) addresses storage through the decorated stack, so one guard covers them all, unscoped admins included, enforced server-side. The statestore holds the raw driver captured *before* the wrap, so state operations pass underneath by construction (proven by test `TestRawDriverBelowGuardStillReachesState`). Scope decisions: `/.cairn-state` AND `/.cairn` are blocked as root subtrees — the posix state directory holds the same secret class (auth verifiers, peering credentials) and was previously admin-downloadable. The `.cairn-state` *name* is additionally blocked as a segment anywhere, so a space or folder named after the prefix cannot be created on any surface (covers the spaces requirement without touching spaces code). A deep directory legitimately named `.cairn` remains ordinary content. Blocked paths answer `ErrNotFound`, never "forbidden": confirming existence would leak what the guard hides. Like scope, the decorator does NOT embed `storage.Driver` — every method explicit, so an interface addition can never silently bypass it. `Usage` forwarded for quota. Tests: root listing hides both entries; all eight ops (List/Stat/Open/Write/Delete/Mkdir/Rename/Copy, both directions for the two-path ops) return ErrNotFound on six representative reserved paths; the sentinel still satisfies `fs.ErrNotExist` (the #153 lesson, now regression-tested); nested `.cairn` allowed; ordinary content untouched.

Cordy closed this issue

2026-08-09 07:02:30 +00:00

Rows
Columns

.cairn-state/ must be invisible and unreachable from every user surface #155