diff --git a/CHANGELOG.md b/CHANGELOG.md index 5601e61..da7d55b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,16 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). description, alongside the existing missing-transcript advisory — moving the ACR 504 authoring-tool support forward (RM8). +- **Public evaluation path for the first release candidate (2026-07-18).** The + README now begins with a five-minute, synthetic-data-only walkthrough instead of + making a prospective adopter infer the first useful command from the architecture + description. `docs/TRY-LEDGER.md` explains exactly what the executable demo proves + and what it does not. `docs/reviews/` adds bounded packets for a community + archivist pilot, an independent threat-model review, and a manual + assistive-technology review; none represent completed human review. The new + `docs/RELEASE-0.1.0.md` checklist separates repository-verifiable work from the + owner-controlled PyPI and human-review prerequisites before a real `v0.1.0` tag. + - **Portfolio-standards conformance remediation (2026-07-11).** Closed all five current Tier-1 checker failures with a Python runtime pin, complete CFF metadata, canonical README applicability declarations, ADR 0000, and a discoverable diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f654c62..d015fd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,11 @@ If you have not yet, read [`README.md`](README.md) for what the project is and w [`SECURITY.md`](SECURITY.md) for how to report a vulnerability. The [Code of Conduct](CODE_OF_CONDUCT.md) applies to every interaction. +If you are offering community-archivist, threat-model, or manual accessibility +feedback rather than code, start with the bounded, synthetic-data-only +[`docs/reviews/`](docs/reviews/README.md) packet. It makes clear what evidence is +being requested and what a review does not certify. + ## Standards this repo is held to ledger is one repo in a personal portfolio governed by a shared set of engineering diff --git a/README.md b/README.md index e453380..ba22973 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,41 @@ institutional customer. > against your own threat model before entrusting real, high-stakes records — see > [`SECURITY.md`](./SECURITY.md) and [`docs/THREAT-MODEL.md`](./docs/THREAT-MODEL.md). +## Start here + +The fastest honest way to evaluate ledger is to run its synthetic end-to-end proof. +It creates a temporary archive only; it never uses or contacts real people or real +records. + +```sh +git clone https://github.com/ChelseaKR/ledger.git +cd ledger +make install +make demo +``` + +In a few minutes, the demo ingests a synthetic oral history, keeps a synthetic +contributor identity in the encrypted vault, verifies a replicated BagIt bag, then +checks every rendered HTML/JSON/log/metadata surface for an identity leak. It also +shows a recorded consent change tightening public access. Read the expected output +and what it does *not* prove in [the five-minute walkthrough](docs/TRY-LEDGER.md). + +If you are evaluating ledger for a community, use the right path for the question +you are asking: + +| I want to… | Start with… | +| --- | --- | +| See the core safety and preservation flow work | [Five-minute synthetic walkthrough](docs/TRY-LEDGER.md) | +| Assess it with a community archivist, using no real records | [Partner-pilot packet](docs/reviews/community-archivist-pilot.md) | +| Review the threat model or accessibility claims | [Review packet](docs/reviews/README.md) | +| Decide whether a real collective can adopt it | [Adoption checklist](docs/ADOPTING.md) and [threat model](docs/THREAT-MODEL.md) | +| Self-host an archive | [Self-host runbook](infra/README.md) — after the adoption checklist | + +**What this is not:** a hosted service, a production-ready archive, legal advice, or +evidence that a third party has audited ledger. The demo proves specific, automated +properties over synthetic data; it does not establish safety for any particular +community or deployment. + **Why this domain.** Queer history is disproportionately undocumented, and the documentation that exists is fragile. It lives on a single laptop, a dead Facebook group, a hosted service that changes its terms, a shoebox under someone's bed. The people best placed to keep it are often the people diff --git a/docs/RELEASE-0.1.0.md b/docs/RELEASE-0.1.0.md new file mode 100644 index 0000000..d1203bc --- /dev/null +++ b/docs/RELEASE-0.1.0.md @@ -0,0 +1,43 @@ +# Release checklist — ledger 0.1.0 + +**Status:** release candidate; not yet a published release. + +This checklist separates work that is verifiable from the repository from the +owner-controlled and human-review prerequisites that cannot honestly be automated. +`v0.1.0` must not be pushed until every required item is checked. + +## Required before tagging + +- [ ] Independent threat-model/security review is completed, its approved findings + are recorded, and public claims are updated. See + [the review packet](reviews/threat-model-review.md). +- [ ] Manual NVDA/Firefox and VoiceOver/Safari review passes are completed and dated. + See [the accessibility review packet](reviews/manual-accessibility-review.md). +- [ ] The accountable owner reviews and signs the residual-risk register. +- [ ] A signed annotated tag signer identity is documented and approved. +- [ ] `ledger-archive` is registered on PyPI and a trusted publisher is configured + for `ChelseaKR/ledger`, `.github/workflows/release.yml`, environment `pypi`. +- [ ] The GitHub `pypi` environment exists with the intended protection rule. +- [ ] `CHANGELOG.md` has a dated `## [0.1.0]` section that reflects the exact tag. +- [ ] `CITATION.cff`'s release date matches the tag date. +- [ ] `make verify` passes at the exact commit to be tagged. + +## Tag and verify + +- [ ] Create and verify a signed annotated `v0.1.0` tag at the checked commit. +- [ ] Push the tag and let `release.yml` run its full gate, build, SBOM, + provenance, cosign signing, trusted PyPI publishing, and post-publication + checksum verification. +- [ ] Confirm the GitHub Release contains the wheel, source distribution, SBOM, and + signatures and that its notes match `CHANGELOG.md`. +- [ ] Install the published package into a clean environment and run `ledger --help`. + +## Rollback and communication + +- [ ] If the tagged release or artifacts fail verification, stop publication and + document the failed attempt; do not retag a different commit with the same version. +- [ ] If a released artifact needs withdrawal, follow `SECURITY.md`, record the reason + in the changelog, and publish a new fixed version rather than silently replacing + `0.1.0`. +- [ ] Announce only the verified scope: pre-1.0 reference implementation, synthetic + demo available, and no claim of production suitability beyond completed evidence. diff --git a/docs/TRY-LEDGER.md b/docs/TRY-LEDGER.md new file mode 100644 index 0000000..6f59f5c --- /dev/null +++ b/docs/TRY-LEDGER.md @@ -0,0 +1,81 @@ +# Try ledger in five minutes + +This walkthrough gives a prospective community, archivist, or reviewer a small, +repeatable way to see ledger's core preservation and disclosure path. It uses only +synthetic data created at run time. It does **not** need an account, a networked +service, or a real contributor. + +## What you will see + +The executable demo does five concrete things: + +1. Creates a temporary archive with the narrowest disclosure default. +2. Ingests a synthetic oral history and stores a synthetic contributor identity in + the encrypted identity vault, separate from the record. +3. Replicates the BagIt bag to a second local location and verifies its fixity. +4. Serves the record locally, then checks the HTML, JSON, health endpoint, request + log, and on-disk metadata for an identity or sealed-field leak. +5. Records a consent change and verifies that it removes the record from anonymous + browsing. + +The run leaves its temporary directory printed in the terminal so a reviewer can +inspect the synthetic artifacts. Do not substitute real names or records for the +synthetic values. + +## Run it + +You need Python 3.12+ and [uv](https://docs.astral.sh/uv/). + +```sh +git clone https://github.com/ChelseaKR/ledger.git +cd ledger +make install +make demo +``` + +The important success lines are: + +```text +PASS: contributor identity absent from every public surface +``` + +and the summary stating that the synthetic bag was replicated and verified and that +the consent change tightened disclosure. A non-zero exit is a failed proof, not an +inconclusive result. + +## Interpret the result correctly + +A passing demo is evidence for the specific exercised properties: the checked +synthetic identity does not leak through the tested surfaces, a copy verifies against +its fixity data, and the exercised consent change affects anonymous disclosure. It is +not evidence that: + +- ledger is safe for real records or for every threat model; +- sealed content is encrypted at rest (it is not by default; see + [the adoption checklist](ADOPTING.md)); +- an independent security, cryptography, legal, or accessibility review has happened; +- an archive has community governance, full-disk encryption, TLS, off-box replicas, + or a safe key-custody arrangement. + +Those are adoption and human-review questions. The next honest step is the +[community-archivist pilot packet](reviews/community-archivist-pilot.md), followed +by the [adoption checklist](ADOPTING.md) before any real record is considered. + +## Browse a synthetic archive locally + +For an interactive look at the interface, the browser accessibility harness can seed +a synthetic archive and serve it on loopback: + +```sh +cd tools/a11y_browser +python -m serve_demo +``` + +Open the local address it prints (normally `http://127.0.0.1:8099`). The seeded +records, grants, and identities are synthetic. Stop the server with `Ctrl-C` when +finished. + +The [AWS showcase runbook](../infra/aws/README.md) describes an optional public, +synthetic-only demonstration deployment. It creates billable infrastructure and +requires a domain, so it is deliberately an operator decision rather than a default +quickstart. diff --git a/docs/reviews/README.md b/docs/reviews/README.md new file mode 100644 index 0000000..8050c4c --- /dev/null +++ b/docs/reviews/README.md @@ -0,0 +1,26 @@ +# Review packet + +ledger is a pre-1.0 reference implementation. Automated checks and committed +analysis are useful evidence, but they are not a substitute for a community partner +or an independent human review. This directory makes those reviews bounded, +synthetic-data-only, and useful to both reviewer and maintainer. + +| Review | Who it is for | Timebox | Output | +| --- | --- | --- | --- | +| [Community archivist pilot](community-archivist-pilot.md) | A community archivist or mutual-aid steward | 60–90 minutes | Workflow observations and adoption conditions | +| [Threat-model review](threat-model-review.md) | An independent security, privacy, or applied-cryptography reviewer | 2–4 hours | Findings, threat-model corrections, and residual-risk decision | +| [Manual accessibility review](manual-accessibility-review.md) | A screen-reader and keyboard user, ideally paid for their expertise | 60–90 minutes per AT/browser pair | Dated assistive-technology findings and ACR updates | + +## Safety boundary for every review + +- Use only the repository's synthetic records and sentinel identities. +- Do not paste real names, sealed fields, screenshots, logs, or archive content into + an issue, pull request, or review report. +- A reviewer may report a flaw by shape (for example, “a sealed field rendered to an + anonymous viewer on a route”), never by reproducing sensitive content. +- A review invitation, completed checklist, or issue label does **not** turn into a + completed independent review until a named reviewer has submitted dated findings. + +For vulnerability reporting, use [SECURITY.md](../../SECURITY.md), not a public +issue. For contribution rules, including the redaction-safe rule, see +[CONTRIBUTING.md](../../CONTRIBUTING.md). diff --git a/docs/reviews/community-archivist-pilot.md b/docs/reviews/community-archivist-pilot.md new file mode 100644 index 0000000..1850095 --- /dev/null +++ b/docs/reviews/community-archivist-pilot.md @@ -0,0 +1,73 @@ +# Community archivist pilot packet + +## Purpose + +Invite one community archivist or mutual-aid steward to evaluate whether ledger's +workflow is understandable, appropriately scoped, and worth a supervised future +pilot. This is **not** a request to deposit real material, adopt the software, or +vouch for its safety. + +## Invitation text + +> I maintain an open-source, pre-1.0 reference implementation for a community +> archive called ledger. It combines preservation packaging (BagIt, PREMIS, Dublin +> Core) with consent-based selective disclosure. I am looking for feedback on a +> synthetic, local-only walkthrough—not real records, not a production deployment, +> and not an endorsement. Would you be open to a 60–90 minute paid or otherwise +> mutually agreed review of the workflow and its adoption checklist? Your feedback +> would be recorded only with your consent, and you may keep it private. + +Adapt the compensation and contact details before sending. Do not imply that the +reviewer is responsible for security certification, legal advice, or the safety of a +future deployment. + +## Before the session + +- Agree on compensation, confidentiality, and whether any feedback may be quoted. +- Share [Try ledger in five minutes](../TRY-LEDGER.md), + [the adoption checklist](../ADOPTING.md), and + [the threat model](../THREAT-MODEL.md). +- Run the demo together or have the reviewer run it locally. Use synthetic data only. +- Make clear that the session is discovery, not a real-data pilot and not evidence of + demand or community approval. + +## Suggested 60–90 minute agenda + +1. **Context (10 min).** What kind of records and governance constraints does the + reviewer work with? Do not collect sensitive archive details. +2. **Walkthrough (20 min).** Run `make demo` and browse the synthetic local archive. +3. **Workflow critique (20 min).** Ask where a contributor, steward, or community + governor would be confused, blocked, or put at risk. +4. **Adoption conditions (15 min).** Read the adoption checklist together. Which + conditions are non-negotiable, missing, or inappropriate for a small collective? +5. **Close (5 min).** Confirm whether follow-up is welcome and what, if anything, + may be made public. + +## Questions to answer + +- Does the contributor-safety model use words and controls a community can understand? +- Are the differences between public, community, steward, and sealed access clear? +- Does the interface honestly communicate what is withheld and why? +- Which operational requirements would stop a real deployment first? +- What evidence would the reviewer need before considering a supervised pilot? +- What should ledger explicitly *not* do or claim? + +## Review record + +Record only what the reviewer authorizes. A concise report should state: + +```text +Date: +Reviewer role or organization (only if approved): +Scope completed: +Synthetic-only confirmation: yes/no +What was clear: +What was confusing or unsafe: +Adoption conditions: +Concrete follow-up requested: +Permission to publish this summary: yes/no/edited version only +``` + +Do not add a reviewer’s name, quote, or approval to this repository without explicit +written permission. A session with no publishable result is still valuable discovery; +it is not a public endorsement. diff --git a/docs/reviews/manual-accessibility-review.md b/docs/reviews/manual-accessibility-review.md new file mode 100644 index 0000000..7d3e449 --- /dev/null +++ b/docs/reviews/manual-accessibility-review.md @@ -0,0 +1,59 @@ +# Manual accessibility review packet + +## Purpose + +This is a concise, reviewer-facing companion to the project’s full +[manual assistive-technology review cadence](../accessibility/MANUAL-REVIEW-CADENCE.md). +It is for a screen-reader and keyboard user to assess the actual locally served +synthetic archive. It does not replace paid accessibility expertise or constitute a +WCAG certification. + +## Set up the synthetic review site + +```sh +git clone https://github.com/ChelseaKR/ledger.git +cd ledger +make install +cd tools/a11y_browser +python -m serve_demo +``` + +Open the local address printed by the command (normally `http://127.0.0.1:8099`). +The site uses synthetic data only. Stop the local server with `Ctrl-C` when done. + +## Suggested path + +Use one assistive-technology/browser combination per pass. The project seeks both: + +- NVDA with Firefox on Windows; and +- VoiceOver with Safari on macOS. + +Exercise the canonical pages and states: + +1. Browse page: landmarks, skip link, list/table equivalence, focus order. +2. Search: query label, result count and any status announcement. +3. Content-warning interstitial: warning announced before underlying content and + clear “proceed” choice. +4. Record after proceeding: warning still available and reading order makes sense. +5. Contribution form: labels, instructions, validation and error announcement. +6. Steward console: keyboard-only controls and status feedback. + +The full page list and detailed criteria are in the +[manual-review cadence](../accessibility/MANUAL-REVIEW-CADENCE.md). + +## Report template + +```text +Date: +Reviewer name or pseudonym (only if approved): +AT/browser and versions: +Keyboard-only path completed: yes/no +Pages and states completed: +Findings (include severity and synthetic reproduction): +What worked well: +May the maintainer publish this report or attribution: yes/no/edited only +``` + +Please do not include real personal, archive, or contributor data. The maintainer +will record agreed findings in the manual-review cadence and update the ACR where the +evidence changes the documented conformance position. diff --git a/docs/reviews/threat-model-review.md b/docs/reviews/threat-model-review.md new file mode 100644 index 0000000..8b95cc8 --- /dev/null +++ b/docs/reviews/threat-model-review.md @@ -0,0 +1,54 @@ +# Independent threat-model review packet + +## Scope + +This packet is for an independent security, privacy, or applied-cryptography +reviewer. It asks for scrutiny of ledger's stated guarantees and residual risks; it +does not ask a reviewer to certify the whole system or to handle real archive data. + +The maintainer's current position is deliberately narrow: the repository has automated +tests for disclosure and integrity properties, but it has **not** had an independent +security or cryptography audit. A review may narrow, correct, or strengthen that +position; it must not be summarized as an audit until the reviewer says so in writing. + +## Read first + +- [Threat model](../THREAT-MODEL.md) +- [Residual-risk register](../audits/residual-risk-register.md) +- [Architecture](../ARCHITECTURE.md) +- [Adoption checklist](../ADOPTING.md) +- [Five-minute synthetic walkthrough](../TRY-LEDGER.md) + +Relevant code boundaries include `src/ledger/access/`, `identity.py`, `consent.py`, +`dualcontrol.py`, `replicate.py`, `tombstones.py`, `server.py`, and the associated +`tests/` disclosure and preservation suites. + +## Questions worth answering + +1. Does the stated threat model distinguish identity secrecy, content secrecy, + metadata leakage, traffic analysis, and raw-host compromise clearly enough? +2. Does the identity-vault design have an unaccounted-for access path, key-custody + assumption, logging boundary, or recovery failure mode? +3. Can an access policy or grant be bypassed through a rendered route, API route, + export, replica, backup, error, or timing signal that the model overlooks? +4. Are the consent, takedown, and replica-propagation claims accurate when a replica + is unavailable or hostile? +5. Which residual risks should block a real-data pilot, and what narrower claims are + justified today? + +## Review method + +- Work only with synthetic fixtures and a local checkout. +- Use `make demo` to observe the intended disclosure proof. +- Run focused tests where useful: `pytest -m disclosure` and `pytest -m preservation`. +- Report reproduction steps using synthetic values or neutral placeholders. +- Send a security vulnerability through the private channel in `SECURITY.md`; do not + publish an exploitable proof of concept in a public issue. + +## Deliverable + +Ask for a short, dated memo with findings grouped as: critical / high / medium / low / +informational, affected claim or code boundary, synthetic reproduction or rationale, +recommended disposition, and whether the reviewer consents to being named. The +maintainer should log the result in the residual-risk register and update public +claims before describing the review externally.