ZDDC
f7233237cd
Replace the blanket "block every dot/underscore segment" dispatch guard with a single reserved namespace, .zddc.d/, which is admin-only at every depth. Everything else dot-prefixed is now ordinary ACL-governed content; a leading dot only hides an entry from listings (UI), not from the ACL. .zddc.d/ holds the bearer-token store, so it must stay closed even under a broad operator grant (e.g. `*: rwcd`). The path-tree cascade has no match-this-name-at-any-depth rule, so .zddc.d/ is gated by segment name via a hard rule that overrides operator ACLs — on reads in dispatch (404, existence-hidden) and on writes in authorizeAction (403 defense-in-depth for direct callers). Token validation is unaffected: it reads .zddc.d/tokens directly from the filesystem in ACLMiddleware, before the HTTP-layer gate. The segment match is case-insensitive (strings.EqualFold): ZDDC_ROOT may sit on a case-insensitive filesystem (SMB/CIFS/Azure Files) where .ZDDC.D resolves to the same dir, so a write to a case-varied path — e.g. a MOVE destination header that skips dispatch's canonical case-folding — must not slip past the gate and plant a forged token. The dispatch gate also runs BEFORE the raw .zddc view so the reserve's own cascade (/<dir>/.zddc.d/.zddc) is existence-hidden rather than leaked by ServeZddcFile. Regression tests cover both. To keep all bookkeeping inside the one reserve, relocate the last two caches under it (both regenerable, no data migration): the apps cache _app/ -> .zddc.d/apps/ and the per-directory MD-conversion cache <dir>/.converted/ -> <dir>/.zddc.d/converted/. New internal/handler/sidecar.go defines ReservedSidecar + the HasReservedSidecar / ActiveAdminForSidecar predicates used by both the dispatch read-gate and the write-path gate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .forgejo | ||
| archive | ||
| browse | ||
| classifier | ||
| form | ||
| helm | ||
| landing | ||
| pandoc | ||
| scripts | ||
| shared | ||
| tables | ||
| tests | ||
| transmittal | ||
| zddc | ||
| .gitignore | ||
| AGENTS.md | ||
| ARCHITECTURE.md | ||
| build | ||
| CLAUDE.md | ||
| deploy | ||
| dev-server | ||
| LICENSE.txt | ||
| package.json | ||
| playwright.config.js | ||
| README.md | ||
| SECURITY.md | ||
Zero Day Document Control (ZDDC)
The Universal Distributed Filing Cabinet
ZDDC is an information management convention plus a small set of single-file HTML tools. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain shared folder becomes a fully searchable, auditable archive — no server, no database, no software required to read it.
The name "Zero Day Document Control" comes from the convention itself — adopt it on day zero of a project, with no setup time. The tools are optional interfaces around the structure; the structure works without them.
For end users: https://zddc.varasys.io/ introduces the project, links to all tool channels (stable / beta / alpha), and prints copy-paste shell snippets to install on a self-hosted deployment.
Tools
| Tool | What it does |
|---|---|
| Archive Browser | Browse, search, and filter a project archive folder. Group by transmittal, export selections as ZIP. |
| Transmittal Creator | Self-contained HTML transmittal records with SHA-256 checksums and optional digital signatures. |
| Document Classifier | Spreadsheet-like bulk-renamer that copy/pastes with Excel and writes back to disk. |
| Form Renderer | Schema-driven *.form.yaml editor — every form spec auto-mounts an editable form at <name>.form.html. |
| Tables | Sortable, filterable, in-place-editable grid view over a directory of YAML rows; click a row → edit in the form renderer. Auto-mounts on any directory containing a table.yaml. |
| Browse | File-tree navigator with previews and an in-place markdown editor (YAML front matter, outline, server-side DOCX/HTML/PDF download); the everywhere-available companion to the Archive Browser when you want plain folder navigation rather than tracking-number aggregation. |
| Landing | The project picker served at the deployment root of a zddc-server. |
Each tool is published in three channels (stable, beta, alpha) as static files served from https://zddc.varasys.io/releases/. Local use: download a .html file from releases/ and open it in a browser. Server use: run zddc-server — the current-stable build of every tool is baked into the binary at compile time, so a fresh deployment Just Works with zero config. Which tool a directory URL serves is driven by the .zddc cascade: a baked-in defaults.zddc.yaml (dump it with zddc-server show-defaults) declares, per folder, default_tool (the no-slash form — archive under archive/, transmittal under staging/, browse under working/+reviewing/ (browse hosts the in-place markdown editor), classifier under incoming/, tables at archive/<party>/mdl, landing at root) and dir_tool (the trailing-slash form; defaults to browse); operators override at any level. A .zip file is also a navigable directory (GET …/Foo.zip/), and GET /dir/?zip=1 streams an ACL-filtered zip of a subtree. Override the tool source per-directory by writing an apps: entry in any .zddc file (channel/version/URL/path) — fetched once and cached in <ZDDC_ROOT>/_app/ — or drop a real .html file at any path.
Deploy: bootstrap config
A fresh
zddc-serverdeployment grants no access to anyone until two config files are populated. Without them, the server runs but every request returns 403. The embeddeddefaults.zddc.yamlships with empty role members so deployments must opt-in to authorize anyone.
Step 1. At the master root, create /.zddc (i.e. <ZDDC_ROOT>/.zddc) naming at least one admin:
admins:
- cwitt@burnsmcd.com
admins: is honored only at the root file. Admins behave as normal users by default and elevate per-request via the zddc-elevate=1 cookie (header toggle in every tool) or implicitly when authenticating with a bearer token.
Step 2. In each project, create <project>/.zddc to populate the document_controller and project_team role members:
title: "Project Phoenix"
roles:
document_controller:
members:
- dc1@burnsmcd.com
project_team:
members:
- alice@burnsmcd.com
- '*@acme.com' # external counterparty (glob)
That's it. The embedded cascade does the rest — project_team gets read across the project; document_controller gets write/create authority on the archive subtree, WORM filing rights on received/issued, and subtree-admin of working//staging//reviewing/.
Common footgun. acl: { allow: [...] } is silently ignored (the YAML parses, but ACLRules only reads permissions:). The correct shape is:
acl:
permissions:
'<principal>': <bits>
Bits are any subset of r w c d a (read / write / create / delete / admin); empty string is an explicit deny. Principals are emails, globs like *@domain.com, or role names (anything without an @).
zddc-server prints a startup warning when the root .zddc grants nobody anything — watch for it on first boot. For the full schema, run zddc-server show-defaults (dumps the embedded defaults.zddc.yaml with annotated comments).
File-naming convention
The full specification — filename format, tracking numbers, revision rules, status codes, folder naming, and the transmittal workflow — lives at https://zddc.varasys.io/reference.html.
Quick example: 123456-EL-SPC-2623_A (IFR) - Specification For Switchgear.pdf
Build & develop
git clone https://codeberg.org/VARASYS/ZDDC.git && cd ZDDC
./build # dev build of every tool (writes to dist/ only)
sh archive/build.sh # iterate on one HTML tool
./build alpha # lockstep alpha cut for all nine artifacts
./build beta # lockstep beta cut
./build release # lockstep stable, coordinated next version
./build release 1.2.0 # lockstep stable at explicit version
npm install && npx playwright install chromium && npm test # tests
./dev-server start # cache-busting HTTP on :8000
Authoritative build/release docs are in AGENTS.md. Architecture notes (single-file rationale, JS module pattern, security model) are in ARCHITECTURE.md. zddc-server (optional Go HTTP server with ACL and a virtual archive index) is in zddc/README.md. Example Helm charts for deploying zddc-server (production + dev) are under helm/.
Contributing
ZDDC is an open source project hosted on Codeberg at https://codeberg.org/VARASYS/ZDDC. Bug reports, feature requests, and pull requests welcome.
ZDDC is designed for zero configuration to start and minimal configuration overall — feature proposals are filtered through that lens.
License
GNU Affero General Public License v3.0. Free to use, modify, and distribute, including commercially, under the terms of the license. Provided "as is" without warranty.