ZDDC
cd05cd6366
A fresh ZDDC deployment grants no access to anyone until an operator
populates the root .zddc (admins) and per-project .zddc files (role
members). Until now this was only documented in comments inside the
embedded defaults.zddc.yaml, surfaced via `zddc-server show-defaults`
— operators wiring up a fresh master had no obvious doc to follow and
no startup signal when the bootstrap was missing or empty.
- README.md: new "## Deploy: bootstrap config" section between Tools
and File-naming convention. Two canonical examples (root admin-only,
per-project role members), schema essentials (verb bits, principal
forms, admins-only-at-root), and the acl: { allow: [...] } footgun
that silently drops grants.
- AGENTS.md: new "### Bootstrap config (REQUIRED — unlocks the server)"
subsection at the top of ## zddc-server. Same content as README but
with file:line citations into zddc/internal/zddc/file.go for the
schema source of truth.
- zddc-server: new warnIfNoBootstrap fires a slog.Warn at startup when
the root .zddc grants nobody anything (no admins, no acl.permissions,
no role members). Master mode only; skipped under --no-auth.
- config validator's existing no-root-.zddc fail-fast error message now
also points at the new README + AGENTS sections so all three signals
(fail-fast, runtime warning, docs) converge.
Smoke-tested all paths: empty root + default (fail-fast), empty root +
--insecure (file-missing warn), admins-only / perms-only / role-members
-only (silent), title-only and acl.allow footgun (both warn), --no-auth
(suppressed). All existing go tests pass.
Follow-up (manual, separate repo): add an analogous section to
~/src/zddc-website/reference.html.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
99 lines
7 KiB
Markdown
99 lines
7 KiB
Markdown
# 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-server` deployment grants no access to anyone until two config files are populated.** Without them, the server runs but every request returns 403. The embedded `defaults.zddc.yaml` ships 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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`](AGENTS.md). Architecture notes (single-file rationale, JS module pattern, security model) are in [`ARCHITECTURE.md`](ARCHITECTURE.md). zddc-server (optional Go HTTP server with ACL and a virtual archive index) is in [`zddc/README.md`](zddc/README.md). Example Helm charts for deploying zddc-server (production + dev) are under [`helm/`](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](https://www.gnu.org/licenses/agpl-3.0.en.html). Free to use, modify, and distribute, including commercially, under the terms of the license. Provided "as is" without warranty.
|