Palimpsests

Repository on GitHub, which uses git. git is distributed.

The project maintains a good first issue label that marks starter tasks suitable for new or casual contributors — small, self-contained work such as documentation fixes, CLI polish, and additional test cases (the label and its initial set of tasks were curated on 2026-08-14). These tasks do not require adding core functionality, so they can be picked up by contributors who are not yet familiar with the codebase. They are discoverable as a filtered list of open issues carrying the label (see URL).
met_url:
https://github.com/Assault-Consulting/Palimpsests/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

GitHub requires 2FA as of March 2023. [osps_ac_01_01]

Two-factor authentication for the project's maintainers is provided by a Time-based One-Time Password (TOTP) authenticator application, not SMS. TOTP is a cryptographic mechanism — an HMAC-based one-time code derived from a shared secret and the current time — so it does not carry the impersonation risk of unencrypted SMS-based 2FA. All maintainers with write/admin access to the central GitHub repository authenticate with app-based TOTP (and/or hardware security keys); none rely on SMS.

Code review requirements are documented in docs/REVIEW.md, with the contributor workflow in CONTRIBUTING.md and merge authority in GOVERNANCE.md. The document covers all three required elements. How review is conducted: every change — code and documentation — lands through a pull request that a non-author must approve before merge; main is branch-protected, so required green checks plus one non-author approval are enforced, not merely requested. What must be checked: the reviewer confirms that tests ship with behavior and that coverage stays above the gate (statement ≥ 90%, branch ≥ 80%), that ruff lint is clean, that any new dependency is justified, that security-sensitive paths (audit chain, key management, the crypto boundary, untrusted-input deserialization, the capability boundary) receive extra scrutiny against SECURITY.md / THREAT_MODEL.md / ASSURANCE-CASE.md, that public API/CLI and wire-format changes are deliberate and respect the format freeze, and that documentation matches the change; changes affecting released artifacts additionally require byte-verification and a green reproducible-build job. What is acceptable: approval means the reviewer believes the change is correct, tested, within the project's security and design boundaries, and free of known issues that would argue against inclusion — a reviewer who is unsure asks rather than approves, and author confidence alone is not grounds to merge.
met_url:
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/REVIEW.md

Every proposed modification to Palimpsests is reviewed by a non-author before release, which far exceeds the 50% threshold. main is branch-protected: direct pushes are blocked, and every change — code and documentation alike — must go through a pull request that receives at least one approval from a person other than the author, plus a green required status check (ci-complete: lint, tests, and coverage across macOS/Linux/Windows), before it can be merged. These protections have been enforced since 2026-07-11 (documented in GOVERNANCE.md), which is the measurement anchor for the review-coverage figure: every merge from that date forward is non-author reviewed, so the reviewed fraction is effectively 100% and monotonically rising. The requirement is documented in GOVERNANCE.md and CONTRIBUTING.md.

Palimpsests has a reproducible build, so this is Met rather than N/A: the project publishes distribution artifacts, and both the sdist (.tar.gz) and the wheel (.whl) are bit-for-bit reproducible — building the same commit produces identical bytes. Determinism is achieved by building with hatchling via PEP 517 (fixed archive-member order, no wall-clock build time stamped into output), pinning SOURCE_DATE_EPOCH to the commit date, and fixing LC_ALL=C.UTF-8, TZ=UTC, and umask 0022. This is enforced on every push and pull request by the reproducible-build job in .github/workflows/ci.yml, which runs scripts/check_reproducible_build.sh to build the artifacts twice and fail if they differ; the job is a required check in the ci-complete gate. The release workflow builds published artifacts with the same pinned SOURCE_DATE_EPOCH/locale/umask, so released files are the reproducible ones. A step-by-step reproduction recipe is documented (docs/REPRODUCIBLE-BUILD.md) so any third party can independently rebuild a release and verify it by hash. Reproducibility covers the Python distribution artifacts; the optional native (llama.cpp) path links against a separately installed C library and is out of scope.
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/REPRODUCIBLE-BUILD.md

The test suite is invoked in the standard way for Python: python -m pytest (equivalently pytest) from the repository root, with pytest configured in the standard [tool.pytest.ini_options] section of pyproject.toml. This is the conventional Python test invocation, documented in CONTRIBUTING.md and used unchanged by the CI workflow. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project uses continuous integration. On every push to main and every pull request, GitHub Actions runs the automated test suite (pytest) and the linter (ruff) across a matrix of three operating systems (Linux, macOS, Windows) and two Python versions (3.11, 3.12). New and changed code is integrated into main frequently via pull requests, with the tests run automatically on each. Branch protection requires the checks to pass before merge. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/.github/workflows/ci.yml

A FLOSS coverage tool exists for the selected language (coverage.py, run via pytest-cov), so N/A does not apply and the project meets the bar directly. The automated pytest suite achieves 90.3% statement coverage measured over the whole src/palimpsests package; only if TYPE_CHECKING: blocks and raise NotImplementedError lines are excluded, per the standard coverage convention. The single module that reads low — the in-process ctypes backend llamacpp_backend.py, which can only run with the optional [native] extra against a real GGUF model on GPU hardware and therefore cannot be exercised in CI — is counted, not omitted: the overall figure clears 90% with it included, and that backend is validated separately on hardware (benchmarks/RUNBOOK.md). Coverage is computed on every push and pull request (pytest --cov --cov-report=json) and enforced by scripts/coverage_gate.py, which fails the build below 90% statement (and 80% branch). The coverage job is a required check in the ci-complete gate, so coverage cannot silently regress below the bar.

A FLOSS coverage tool exists for the selected language (coverage.py, run via pytest-cov with branch coverage enabled), so N/A does not apply and the project meets the bar directly. The automated pytest suite achieves 82.4% branch coverage measured over the whole src/palimpsests package, with branch = true set in the coverage configuration; only if TYPE_CHECKING: blocks and raise NotImplementedError lines are excluded, per the standard convention. The hardware-only in-process ctypes backend llamacpp_backend.py — runnable only with the optional [native] extra against a real GGUF model on GPU hardware, so not exercisable in CI — is counted, not omitted: the overall figure clears 80% with it included, and that backend is validated separately on hardware (benchmarks/RUNBOOK.md). Branch coverage is computed on every push and pull request and enforced together with statement coverage by scripts/coverage_gate.py, which fails the build below 80% branch (and 90% statement). The coverage job is a required check in the ci-complete gate, so branch coverage cannot silently regress below the bar.

Where the software makes network communication, it uses secure protocols only. Outbound network access (e.g. talking to model/back-end endpoints and to release/publishing infrastructure) goes through httpx over HTTPS/TLS — TLS 1.2+ as negotiated by the platform's TLS stack — and release publishing uses HTTPS with OIDC Trusted Publishing and Sigstore. The project does not implement or default to any insecure protocol (no plain HTTP fetch-and-trust, no FTP/telnet/SSLv3/SSHv1); an insecure transport is not enabled anywhere by default. The core product is a local-first, on-device inference engine, so most operation involves no network at all, and what network communication exists is over TLS.

The software uses TLS and supports TLS 1.2 or later. All HTTPS communication goes through httpx, which uses Python's standard TLS stack (OpenSSL via the ssl module); on the supported Python versions (3.11+) that stack negotiates TLS 1.2 and 1.3 and treats older SSL/TLS versions as disabled by default. The project does not force, pin, or fall back to any pre-1.2 protocol (no SSLv3/TLS 1.0/1.1), so TLS 1.2+ is the effective floor for every TLS connection it makes.

The project website (https://palimpsests.dev) returns the four key hardening headers with nonpermissive values on every response, configured in site/vercel.json. Content-Security-Policy: default-src 'self' with object-src 'none', frame-ancestors 'none', base-uri 'self', and upgrade-insecure-requests. Strict-Transport-Security: max-age=63072000; includeSubDomains; preload (two years). X-Content-Type-Options: nosniff. X-Frame-Options: DENY. It additionally sets Referrer-Policy and a restrictive Permissions-Policy. An external scan (securityheaders.com, 2026-08-14) grades the site A, with all key headers present; the only item below A+ is 'unsafe-inline' in script-src/style-src, tracked as a site improvement. The source repository and the download site are hosted on GitHub (and the package is published to PyPI), which are known to meet this criterion.

The project performed an internal security review in July 2026 — within the last 5 years — documented in docs/security/AUDIT-2026-07.md. It was a human review (manual examination of the audit subsystem, key management, process lifecycle, native backend, KV store, context memory, and CLI), supported by Bandit SAST and dependency/workflow review, covering the full source tree at a pinned commit plus the CI workflows and the published PyPI artifact. The review explicitly considered both the security requirements and the security boundary: the assets and properties to protect, the trust boundaries (the filesystem and the Python→C hand-off), and attacker capabilities are documented in docs/THREAT_MODEL.md, and the audit assessed the design against them — including validating the project's stated "honest boundary" (what the tamper-evident anchor does and does not guarantee; e.g., an attacker holding both the key and keychain-write access is explicitly out of scope). The review produced concrete findings (H1–H2, M1–M4, L1–L3) with severity and remediation status; most were fixed in PR #47, and the remaining items are tracked as explicit, boundary-scoped decisions.

The software uses hardening mechanisms so that a defect is less likely to become a security vulnerability. The primary mechanism is language choice: all code the project produces is written in a memory-safe language (Python), eliminating whole classes of defect-to-vulnerability paths (buffer overflows, use-after-free). The single memory-unsafe boundary — the third-party llama.cpp C library — is isolated behind an optional [native] extra, and the untrusted-input surface in front of it (the KV-state validator guarding load_state) is coverage-guided fuzzed with Atheris, so malformed input is rejected before any byte reaches C. Additional mechanisms: SQL is parameterized throughout (no injection); there is no unsafe deserialization (pickle/eval/shell=True are absent); cryptographic keys come from a CSPRNG (secrets.token_bytes); the at-rest audit store is encrypted (SQLCipher/AES-256) with the key held in the OS keychain, and the design fails closed — it refuses to open rather than fall back to plaintext if SQLCipher is unavailable; the audit chain's canonical serialization is length-prefixed so field boundaries cannot be forged; provider exception text is clipped before it enters the log to prevent secret leakage; and the CI/release pipeline runs with least-privilege permissions, SHA-pinned actions, and OIDC-scoped publishing. These mechanisms, and the security argument for them, are documented in docs/ASSURANCE-CASE.md, with the asset-to-mechanism mapping in docs/THREAT_MODEL.md. As a local-first library with no network service of its own, HTTP transport-hardening headers do not apply to the software itself; the project website's hardening headers are covered separately under hardened_site.
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/ASSURANCE-CASE.md

The project applies a dynamic analysis tool — Atheris, the Python binding for libFuzzer — as coverage-guided fuzzing. The harness (fuzz/fuzz_state_blob.py) targets the security-critical untrusted-input boundary: NativeSession.load_state, the pure-Python frame parser standing between arbitrary bytes and the C KV-state deserializer (llama_state_seq_set_data). It enforces the invariant that a malformed blob is rejected in Python (raising StateBlobError, with the backend never called) and never reaches C; any other outcome is a finding. Fuzzing runs in .github/workflows/fuzz.yml: a short deterministic regression pass on every push and pull request to main (so a previously found crash cannot silently return), plus a longer time-budgeted run nightly and on demand. Because every change to main is fuzzed and releases are cut from main, at least one dynamic analysis tool has been applied to the code before each release. Assertions are enabled during the run (the harness executes under CPython without -O). The one memory-unsafe component — the third-party llama.cpp C library — is outside the project's own code; the harness deliberately fuzzes the project's guard in front of it. (Independently, the project's automated test suite also exceeds 80% branch coverage, which on its own satisfies this criterion.)
https://github.com/Assault-Consulting/Palimpsests/blob/main/fuzz/README.md