232 lines
12 KiB
Markdown
232 lines
12 KiB
Markdown
# The `.zddc` grammar
|
||
|
||
This is the authoritative reference for the `.zddc` policy language: every key,
|
||
its type, how it composes across the cascade, and how the engine turns a tree of
|
||
`.zddc` files into an access decision. The design intent is **policy-as-data**:
|
||
operators express *all* per-folder behaviour in `.zddc`; `zddc-server` is the
|
||
enforcement engine that reads and applies it. Nothing here is hardcoded to
|
||
folder *names* — the embedded defaults (the per-depth tree under
|
||
`internal/zddc/defaults/`, exported as a `.zddc.zip` by `show-defaults`) are
|
||
just the bottom-most policy in the cascade and are fully overridable.
|
||
|
||
> Status: the declarative grammar below is complete and enforced today. A
|
||
> future **sandboxed expression layer** (`when:` conditions — see
|
||
> [§7](#7-extension-point-when-expressions)) is reserved for attribute-based
|
||
> rules that data alone can't express; it is *not* yet implemented.
|
||
|
||
The grammar has two executable backings, kept in lockstep with this document:
|
||
|
||
- **Layer 1 — the engine enforces whatever a `.zddc` says** (storage-agnostic):
|
||
`internal/policy/policy_test.go` (cascade scenarios) + `internal/zddc/{acl,
|
||
roles,worm}_test.go` + `internal/policy/parity_test.go` (Go ↔ OPA/Rego parity).
|
||
- **Layer 2 — the shipped defaults are correct**: `internal/handler/
|
||
defaults_matrix_test.go` (role × canonical-path × verb truth table).
|
||
|
||
---
|
||
|
||
## 1. Document model
|
||
|
||
A `.zddc` file is YAML. A directory's *effective policy* is the **cascade**: the
|
||
ordered chain of `.zddc` files from the deployment root down to that directory,
|
||
plus the embedded defaults at the bottom. Levels are indexed **root (0) → leaf
|
||
(last)**.
|
||
|
||
Four things contribute to a level beyond the on-disk file:
|
||
|
||
1. **Embedded defaults** — the per-depth tree under `internal/zddc/defaults/`
|
||
(assembled into a nested `paths:` `ZddcFile`), always the bottom of the chain
|
||
(unless fenced off; see [`inherit`](#inherit)).
|
||
2. **`.zddc.zip` policy bundles** — a `.zddc.zip` at *any* directory mounts a
|
||
policy subtree there: its members (paths with `*` wildcards) are resolved
|
||
like `paths:` and merged UNDER the on-disk `.zddc`. With `inherit:false` +
|
||
`acl.inherit:false` in its root member it becomes a self-contained island.
|
||
The embedded defaults are simply the bundle mounted at the deployment root.
|
||
3. **Virtual `paths:` contributions** — an ancestor's [`paths:`](#paths) tree
|
||
injects policy at descendant directories *that need not exist on disk*. This
|
||
is why a brand-new project resolves usable policy at every canonical URL.
|
||
4. **The on-disk `.zddc`** at the directory itself, which wins per-field over
|
||
the virtual/ancestor contributions.
|
||
|
||
Because policy is resolved for *virtual* paths, **every authorization decision
|
||
must compute the chain at the target's own directory** — never at the nearest
|
||
directory that happens to exist on disk. (Resolving at the nearest *existing*
|
||
ancestor was the cause of a real bug: a `document_controller` was denied
|
||
`create` under a not-yet-materialised `working/<party>/` because the chain was
|
||
computed at the project root.)
|
||
|
||
---
|
||
|
||
## 2. The decision pipeline
|
||
|
||
A single verb decision (`r` read, `w` write, `c` create, `d` delete, `a` admin)
|
||
is computed in this fixed order — see `internal/policy/policy.go`
|
||
(`InternalDecider.Allow`):
|
||
|
||
```
|
||
1. Active-admin bypass → if the principal is an ELEVATED admin named in an
|
||
admins: list anywhere on the chain, ALLOW everything
|
||
(WORM included). The single escape hatch.
|
||
2. WORM mask → if the directory is in a worm: zone, the effective
|
||
verbs are (normal-grant & r) | (worm-grant & rc):
|
||
write/delete/admin always stripped; create survives
|
||
only for worm: members; read via either source.
|
||
3. Normal cascade grant → otherwise, the cascade ACL decision (§4).
|
||
```
|
||
|
||
Read/elevation rules that frame the pipeline:
|
||
|
||
- **Elevation is required for admin powers** (sudo-style). A principal is an
|
||
*active* admin only when `Elevated` is true AND named (directly or via role)
|
||
in an `admins:` list on the chain. Browser sessions elevate via the
|
||
`zddc-elevate=1` cookie (set by `?admin=true`); bearer-token callers are
|
||
elevated implicitly.
|
||
- **Default-allow only on a truly empty tree**: if *no* `.zddc` exists anywhere
|
||
on the chain (`HasAnyFile == false`), everything is allowed (a bare directory
|
||
served with no policy is public). As soon as any `.zddc` exists, the default
|
||
is deny.
|
||
|
||
---
|
||
|
||
## 3. ACL evaluation (the `acl.permissions` core)
|
||
|
||
`acl.permissions` maps a **principal pattern** → a **verb string**. A principal
|
||
is an email-glob (`alice@x`, `*@acme.com`, `*`) or a **role name** (no `@`),
|
||
which expands to the role's members (§[`roles`](#roles)). Verbs are any subset
|
||
of `r w c d a`; the empty string `""` is an **explicit deny**.
|
||
|
||
Two composition rules — and they are **different on purpose**:
|
||
|
||
- **Within one level**, every matching entry (email + wildcard + role) is
|
||
**unioned** — EXCEPT an explicit-deny (`""`) match, which zeroes the grant at
|
||
that level (deny is more specific than a permissive role membership).
|
||
- **Across levels**, the **deepest level that matches the principal wins** — it
|
||
*replaces*, it does not add. A closer `.zddc` that grants you `cr` overrides
|
||
an ancestor's `r`; an ancestor grant is consulted only if no closer level
|
||
matches you at all.
|
||
|
||
> Mnemonic: *role membership unions up the tree; permissions take the deepest
|
||
> match.* Conflating these is the most common reasoning error.
|
||
|
||
---
|
||
|
||
## 4. Key reference
|
||
|
||
`✱` = honored only in the **root** `.zddc`. Cascade column says how the key
|
||
composes from leaf→root.
|
||
|
||
| Key | Type | Cascade | Meaning |
|
||
|---|---|---|---|
|
||
| `acl.permissions` | map principal→verbs | **deepest match wins** (§3) | the verb grants |
|
||
| `roles` | map name→`{members:[], reset?}` | **members union** (a `reset:true` level starts fresh) | named principal groups; referenced by `acl`/`worm`/`admins` |
|
||
| `admins` | list of principal | union (root = super-admin; deeper = subtree admin) | elevation-gated full bypass over that scope |
|
||
| `worm` | list of principal | **union** | WORM zone: strips w/d/a for all; create survives only for listed (§2) |
|
||
| `inherit` | bool (default true) | **fence** | `false` stops the cascade here — nothing below (incl. defaults) is visible |
|
||
| `default_tool` | string | deepest non-empty | tool served at `<dir>` (no slash) — sugar for `views.dir.tool` |
|
||
| `dir_tool` | string | deepest non-empty | tool served at `<dir>/` — sugar for `views.dir_slash.tool` |
|
||
| `views` | map shape→`{tool,config}` | map-merge (child wins per shape) | per-URL-shape tool + `.zddc.d/`-resolved config |
|
||
| `available_tools` | list | **concat-dedupe union** | tools the apps subsystem may auto-serve |
|
||
| `auto_own` | bool | deepest non-nil | mkdir post-hook writes a creator-owned `.zddc` |
|
||
| `auto_own_fenced` | bool | deepest non-nil | the auto-own `.zddc` is `inherit:false` (private to creator) |
|
||
| `auto_own_roles` | list | deepest non-nil | roles also granted `rwcda` in the auto-own `.zddc` |
|
||
| `history` | bool | **subtree-inheriting** (deepest set wins; crosses fences) | snapshot markdown edits to `.history/` |
|
||
| `history_globs` | list | deepest non-empty (default `["*.md"]`) | which files history applies to |
|
||
| `drop_target` | bool | **leaf-only** | this dir is a browse drag-drop upload zone |
|
||
| `virtual` | bool | deepest non-nil | never materialise on disk; treat as virtual route |
|
||
| `party_source` | string | **leaf-only** | a new `<party>/` here requires registration in `<source>/<party>.yaml` |
|
||
| `convert` | `{client,project,contractor,project_number}` | per-key latest (leaf) wins | MD→{docx,html,pdf} template variables |
|
||
| `field_codes` | map name→FieldCode | map-merge per code | tracking-number / record field vocabularies |
|
||
| `records` | map pattern→RecordRule | map-merge per pattern, per-field | per-record-type rules (filename format, defaults, locked, row scope) |
|
||
| `display` | map name→label | **leaf-only** (no upward cascade) | human labels for child entries |
|
||
| `tables` | map stem→specpath | leaf-only | legacy directory-of-YAML table view |
|
||
| `received_path` | string | leaf | links a workflow folder back to its canonical submittal |
|
||
| `planned_review_date` / `planned_response_date` | ISO date | leaf | doc-controller commitments on the canonical submittal |
|
||
| `title` | string | leaf | human title for the directory |
|
||
| `paths` | map segment→`.zddc` | recursive virtual injection (on-disk wins) | apply policy at descendant segments that need not exist |
|
||
|
||
`FieldCode` and `RecordRule` are themselves small grammars (discriminated unions
|
||
/ structured rules) — see the Go types in `internal/zddc/file.go` for their
|
||
sub-fields; they are out of scope for this top-level reference.
|
||
|
||
---
|
||
|
||
## 5. `paths:` — virtual policy injection
|
||
|
||
`paths:` is what makes the grammar express a whole project shape from one file.
|
||
Each key is a **single path segment** — a literal name or `*` (matches any
|
||
segment) — and the value is a nested `.zddc` applied at the matching child
|
||
directory. It recurses (`paths:` inside `paths:`). Matching prefers a literal
|
||
key, then falls back to `*`.
|
||
|
||
Ancestor `paths:` contributions are merged into the effective `.zddc` at each
|
||
level by `EffectivePolicy`; an on-disk `.zddc` at the matching directory wins
|
||
per-field. The embedded defaults use exactly this to define the canonical
|
||
project structure (`archive/`, `working/`, `staging/`, …) without any of those
|
||
folders existing on disk.
|
||
|
||
> **The merge trap.** When you add a new top-level key, the per-level merge in
|
||
> `walker.go` (`mergeOverlay`) must carry it from `paths:` contributions into
|
||
> `chain.Levels`, or the key silently no-ops at default-driven paths. Verify a
|
||
> new key with a *defaults-path* test, not just a hand-built `PolicyChain`.
|
||
|
||
---
|
||
|
||
## 6. Reserved namespaces (not policy keys)
|
||
|
||
- `.zddc.d/` — per-directory admin-only reserve (tokens, logs, history,
|
||
converted cache, view configs). 404 to non-admins at every depth; writes
|
||
admin-gated. Not addressable as content.
|
||
- `.zddc.zip` — a config bundle droppable at **any** directory. Its `.zddc`
|
||
members (per-depth, `*` wildcards, individually replaceable) mount a policy
|
||
subtree at that directory (see §1); it may also carry tool-HTML overrides.
|
||
The shipped baseline is the embedded bundle at the deployment root
|
||
(`show-defaults` exports it). Browsable only by an elevated admin. NOT a
|
||
cascade key — it's resolved by the engine, not declared inside a `.zddc`.
|
||
|
||
---
|
||
|
||
## 7. Extension point: `when:` expressions
|
||
|
||
The declarative keys above are *attribute-free* — they decide on principal +
|
||
path + folder behaviour, not on runtime values. Attribute-based rules ("allow
|
||
write only before the issue date", "creator may edit their own files",
|
||
"requester.dept must equal folder.dept") are the one class data can't express.
|
||
|
||
The reserved mechanism is a **pure, sandboxed expression** attached to a grant —
|
||
NOT embedded general-purpose code. Sketch (subject to design):
|
||
|
||
```yaml
|
||
acl:
|
||
permissions:
|
||
"*@acme.com":
|
||
verbs: rwc
|
||
when: 'request.now < record.issue_date && request.email == record.author'
|
||
```
|
||
|
||
Constraints that keep the engine an engine:
|
||
- A single boolean expression in a **non-Turing-complete, side-effect-free**
|
||
language (CEL or `expr`-lang), evaluated in-process per decision.
|
||
- Inputs are a fixed, read-only context (`request`, `principal`, `record`,
|
||
`folder`) — no I/O, no filesystem, no network, no unbounded loops.
|
||
- A timeout + recursion bound; a failed/erroring expression denies.
|
||
- This is distinct from raw JavaScript in `.zddc`, which is deliberately *not*
|
||
adopted: it would put arbitrary code execution in the authorization path and
|
||
break the "`.zddc` is data" guarantee.
|
||
|
||
For operators who want to replace the decision engine wholesale, the
|
||
`Decider` interface already supports an external **OPA/Rego** policy server
|
||
(`--policy-url`); `parity_test.go` keeps the built-in engine and the Rego policy
|
||
in agreement. `when:` is the lightweight in-tree complement to that heavy
|
||
out-of-process option.
|
||
|
||
---
|
||
|
||
## 8. Validation
|
||
|
||
`internal/zddc/validate.go` (`ValidateFile`) checks a `.zddc` structurally
|
||
(known keys, verb charset, role/view shapes, path-safety of configs). The browse
|
||
client mirrors a subset in `browse/js/preview-yaml.js`. **Formalizing these two
|
||
into one machine-readable schema (JSON Schema, validated server-side via
|
||
`internal/jsonschema` and shipped to the client) is the natural next step** —
|
||
it removes the client/server drift and makes this document's §4 table
|
||
machine-checkable. Until then, this file is the source of truth and the two
|
||
test layers (above) are its behavioural guarantee.
|