diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..6bb556b --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,85 @@ +== Changelog + +All notable changes to `+hesiod-dns-map+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: wire conflow config validation pipeline +* feat: add stapeln.toml layer-based container definitionfrom existing +Containerfile to stapeln format.Chainguard base, security hardening, +SBOM generation.-Authored-By: Claude Opus 4.6 (1M context) +noreply@anthropic.com +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add bot directives, contractiles, and ecosystem cross-refs +* feat: implement Hesiod DNS naming system with Rust workspaceworkspace +with two crates:- hesiod-lib: HS-class TXT record types (passwd, group, +service, filsys),zone management, UDP DNS server (hickory-proto), Axum +health/metrics- hesinfo: CLI with lookup, serve, generate, validate +subcommandsincludes Nickel config schemas, K8s manifests, FlatRacoon +module, Containerfile, example zone file, and real justfile recipes. +tests passing, clippy clean.-Authored-By: Claude Opus 4.6 +noreply@anthropic.com +* feat: add AI Gatekeeper Protocol manifest +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#44) +* fix(ci): sync hypatia-scan.yml to canonical (#43) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix: set correct Groove capability type (was: custom) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix: SPDX headers (AGPL→PMPL), email, author name + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: record tech-debt audit findings (2026-05-26) (#49) +* docs(governance): CRG v2.0 STRICT audit — C (declared) -> D (honest) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking + +==== CI + +* ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#48) +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#46) +* ci: bump actions/upload-artifact SHA to current v4 (#42) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index c8d944c..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,72 +0,0 @@ - - -# Changelog - -All notable changes to `hesiod-dns-map` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: wire conflow config validation pipeline -- feat: add stapeln.toml layer-based container definition\n\nConverted from existing Containerfile to stapeln format.\nIncludes Chainguard base, security hardening, SBOM generation.\n\nCo-Authored-By: Claude Opus 4.6 (1M context) -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add bot directives, contractiles, and ecosystem cross-refs -- feat: implement Hesiod DNS naming system with Rust workspace\n\nRust workspace with two crates:\n- hesiod-lib: HS-class TXT record types (passwd, group, service, filsys),\n zone management, UDP DNS server (hickory-proto), Axum health/metrics\n- hesinfo: CLI with lookup, serve, generate, validate subcommands\n\nAlso includes Nickel config schemas, K8s manifests, FlatRacoon module\nmanifest, Containerfile, example zone file, and real justfile recipes.\n\n16 tests passing, clippy clean.\n\nCo-Authored-By: Claude Opus 4.6 -- feat: add AI Gatekeeper Protocol manifest -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#44) -- fix(ci): sync hypatia-scan.yml to canonical (#43) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix: set correct Groove capability type (was: custom) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix: SPDX headers (AGPL→PMPL), email, author name - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#49) -- docs(governance): CRG v2.0 STRICT audit — C (declared) -> D (honest) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking - -### CI - -- ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#48) -- ci: redistribute concurrency-cancel guard to read-only check workflows (#46) -- ci: bump actions/upload-artifact SHA to current v4 (#42) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..7b135db --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/hesiod-dns-map.git cd +hesiod-dns-map + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create hesiod-dns-map-dev toolbox enter hesiod-dns-map-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +hesiod-dns-map/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/hesiod-dns-map/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/hesiod-dns-map/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/hesiod-dns-map/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/hesiod-dns-map/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7d05ce0..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/hesiod-dns-map.git -cd hesiod-dns-map - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create hesiod-dns-map-dev -toolbox enter hesiod-dns-map-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -hesiod-dns-map/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/hesiod-dns-map/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/hesiod-dns-map/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/hesiod-dns-map/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/hesiod-dns-map/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..b68465c --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,403 @@ +== Security Policy + +We take security seriously and appreciate your efforts to responsibly +disclose vulnerabilities. This policy outlines how to report security +issues, what to expect, and how we recognize contributions. + +''''' + +Table of Contents + +.... + Section + + + + + Reporting a Vulnerability + + + What to Include + + + Response Timeline + + + Disclosure Policy + + + Scope + + + Safe Harbour + + + Recognition + + + Security Updates + + + Security Best Practices +.... + +Reporting a Vulnerability Preferred Method: GitHub Security Advisories +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +Navigate to Report a Vulnerability. Click "`Report a vulnerability`". +Complete the form with as much detail as possible. Submit — we’ll +receive a private notification. Benefits: + +End-to-end encryption of your report Private discussion space for +collaboration Coordinated disclosure tooling Automatic credit when the +advisory is published Alternative: Encrypted Email If you cannot use +GitHub Security Advisories, email us directly: + +.... + Email + PGP Key + + + + + security@hyperpolymath.org + Download Public Key +.... + +Fingerprint: See GPG key Steps: + +== Import our PGP key + +curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg –import + +== Verify fingerprint + +gpg –fingerprint security@hyperpolymath.org + +== Encrypt your report + +gpg –armor –encrypt –recipient security@hyperpolymath.org report.txt + +⚠️ Important: Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. + +What to Include A good vulnerability report helps us understand and +reproduce the issue quickly. Required Information + +Description: Clear explanation of the vulnerability Impact: What an +attacker could achieve (confidentiality, integrity, availability) +Affected versions: Which versions/commits are affected Reproduction +steps: Detailed steps to reproduce the issue Helpful Additional +Information + +Proof of concept: Code, scripts, or screenshots demonstrating the +vulnerability Attack scenario: Realistic attack scenario showing +exploitability CVSS score: Your assessment of severity (CVSS 3.1 +Calculator) CWE ID: Common Weakness Enumeration identifier if known +Suggested fix: If you have ideas for remediation References: Links to +related vulnerabilities, research, or advisories Example Report +Structure + +=== Summary + +{empty}[One-sentence description of the vulnerability] + +=== Vulnerability Type + +{empty}[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +=== Affected Component + +{empty}[File path, function name, API endpoint, etc.] + +=== Affected Versions + +{empty}[Version range or specific commits] + +=== Severity Assessment + +* CVSS 3.1 Score: [X.X] +* CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +=== Description + +{empty}[Detailed technical description] + +=== Steps to Reproduce + +[arabic] +. [First step] +. [Second step] +. […] + +=== Proof of Concept + +{empty}[Code, curl commands, screenshots, etc.] + +=== Impact + +{empty}[What can an attacker achieve?] + +=== Suggested Remediation + +{empty}[Optional: your ideas for fixing] + +=== References + +{empty}[Links to related issues, CVEs, research] + +Response Timeline We commit to the following response times: + +.... + Stage + Timeframe + Description + + + + + Initial Response + 48 hours + We acknowledge receipt and confirm investigation + + + Triage + 7 days + We assess severity and estimate timeline + + + Status Update + Every 7 days + Regular updates on remediation progress + + + Resolution + 90 days + Target for fix development and release + + + Disclosure + 90 days + Public disclosure after fix is available +.... + +Note: These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. + +Disclosure Policy We follow coordinated disclosure (responsible +disclosure): + +You report the vulnerability privately. We acknowledge and begin +investigation. We develop a fix and prepare a release. We coordinate +disclosure timing with you. We publish security advisory and fix +simultaneously. You may publish your research after disclosure. Our +Commitments + +We will not take legal action against researchers who follow this +policy. We will work with you to understand and resolve the issue. We +will credit you in the security advisory (unless you prefer anonymity). +We will notify you before public disclosure. We will publish advisories +with sufficient detail for users to assess risk. Your Commitments + +Report vulnerabilities promptly after discovery. Give us reasonable time +to address the issue before disclosure. Do not access, modify, or delete +data beyond what’s necessary to demonstrate the vulnerability. Do not +degrade service availability (no DoS testing on production). Do not +share vulnerability details with others until coordinated disclosure. +Disclosure Timeline + +Day 0 You report vulnerability Day 1-2 We acknowledge receipt Day 7 We +confirm vulnerability and share initial assessment Day 7-90 We develop +and test fix Day 90 Coordinated public disclosure (earlier if fix is +ready; later by mutual agreement) + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +Scope In Scope ✅ + +This repository (hyperpolymath/terrapin-ssg) and all its code Official +releases and packages published from this repository Documentation that +could lead to security issues Build and deployment configurations in +this repository Dependencies (report here, we’ll coordinate with +upstream) Out of Scope ❌ + +Third-party services we integrate with (report directly to them) Social +engineering attacks against maintainers Physical security Denial of +service attacks against production infrastructure Spam, phishing, or +other non-technical attacks Issues already reported or publicly known +Theoretical vulnerabilities without proof of concept Qualifying +Vulnerabilities We’re particularly interested in: + +Remote code execution SQL injection, command injection, code injection +Authentication/authorization bypass Cross-site scripting (XSS) and +cross-site request forgery (CSRF) Server-side request forgery (SSRF) +Path traversal / local file inclusion Information disclosure +(credentials, PII, secrets) Cryptographic weaknesses Deserialization +vulnerabilities Memory safety issues (buffer overflows, use-after-free, +etc.) Supply chain vulnerabilities (dependency confusion, etc.) +Significant logic flaws Non-Qualifying Issues + +Missing security headers on non-sensitive pages Clickjacking on pages +without sensitive actions Self-XSS (requires victim to paste code) +Missing rate limiting (unless it enables a specific attack) +Username/email enumeration (unless high-risk context) Missing cookie +flags on non-sensitive cookies Software version disclosure Verbose error +messages (unless exposing secrets) Best practice deviations without +demonstrable impact + +Safe Harbour We support security research conducted in good faith. Our +Promise If you conduct security research in accordance with this policy: + +✅ We will not initiate legal action against you ✅ We will not report +your activity to law enforcement ✅ We will work with you in good faith +to resolve issues ✅ We consider your research authorized under the +Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar +laws ✅ We waive any potential claim against you for circumvention of +security controls Good Faith Requirements To qualify for safe harbour, +you must: + +Comply with this security policy Report vulnerabilities promptly Avoid +privacy violations (do not access others’ data) Avoid service +degradation (no destructive testing) Not exploit vulnerabilities beyond +proof-of-concept Not use vulnerabilities for profit (beyond bug bounties +where offered) + +⚠️ Important: This safe harbour does not extend to third-party systems. +Always check their policies before testing. + +Recognition We believe in recognizing security researchers who help us +improve. Hall of Fame Researchers who report valid vulnerabilities will +be acknowledged in our Security Acknowledgments (unless they prefer +anonymity). Recognition includes: + +Your name (or chosen alias) Link to your website/profile (optional) +Brief description of the vulnerability class Date of report What We +Offer + +✅ Public credit in security advisories ✅ Acknowledgment in release +notes ✅ Entry in our Hall of Fame ✅ Reference/recommendation letter +upon request (for significant findings) What We Don’t Currently Offer + +❌ Monetary bug bounties ❌ Hardware or swag ❌ Paid security research +contracts + +Note: We’re a community project with limited resources. Your +contributions help everyone who uses this software. + +Security Updates Receiving Updates To stay informed about security +updates: + +Watch this repository: Click "`Watch`" → "`Custom`" → Select "`Security +alerts`" GitHub Security Advisories: Published at Security Advisories +Release notes: Security fixes noted in CHANGELOG Update Policy + +.... + Severity + Response + + + + + Critical/High + Patch release as soon as fix is ready + + + Medium + Included in next scheduled release (or earlier) + + + Low + Included in next scheduled release + + + + + + + + + + + + Version + Supported + Notes + + + + + main branch + ✅ Yes + Latest development + + + Latest release + ✅ Yes + Current stable + + + Previous minor release + ✅ Yes + Security fixes backported + + + Older versions + ❌ No + Please upgrade +.... + +Security Best Practices General + +Keep dependencies up to date Use the latest stable release Subscribe to +security notifications Review configuration against security +documentation Follow the principle of least privilege For Contributors + +Never commit secrets, credentials, or API keys Use signed commits (git +config commit.gpgsign true) Review dependencies before adding them Run +security linters locally before pushing Report any concerns about +existing code Additional Resources + +Our PGP Public Key Security Advisories Changelog Contributing Guidelines +CVE Database CVSS Calculator + +Contact + +.... + Purpose + Contact + + + + + Security issues + Report via GitHub or security@hyperpolymath.org + + + General questions + GitHub Discussions + + + Other enquiries + See README for contact information +.... + +Policy Changes This security policy may be updated from time to time. +Significant changes will be: + +Committed to this repository with a clear commit message Noted in the +changelog Announced via GitHub Discussions (for major changes) + +Thank you for helping keep terrapin-ssg and its users safe. + +''''' + +*:* - *Structure:* Clear headers, tables for scope and timelines, and +code blocks for commands. - *Clarity:* Simplified language, added +examples, and emphasized . - *Alignment:* Matched your project’s focus +on open source, education, and verification (e.g., PGP, CVSS, CWE). - +*Actionability:* Added . + +Would you like any further refinements or additions, such as integrating +your ? diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 84937e0..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,474 +0,0 @@ -# Security Policy - -We take security seriously and appreciate your efforts to responsibly disclose vulnerabilities. This policy outlines how to report security issues, what to expect, and how we recognize contributions. - ---- - - - - -Table of Contents - - - - - - - - - Section - - - - - Reporting a Vulnerability - - - What to Include - - - Response Timeline - - - Disclosure Policy - - - Scope - - - Safe Harbour - - - Recognition - - - Security Updates - - - Security Best Practices - - - - - -Reporting a Vulnerability -Preferred Method: GitHub Security Advisories -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -Navigate to Report a Vulnerability. -Click "Report a vulnerability". -Complete the form with as much detail as possible. -Submit — we'll receive a private notification. -Benefits: - -End-to-end encryption of your report -Private discussion space for collaboration -Coordinated disclosure tooling -Automatic credit when the advisory is published -Alternative: Encrypted Email -If you cannot use GitHub Security Advisories, email us directly: - - - - - - - - Email - PGP Key - - - - - security@hyperpolymath.org - Download Public Key - - - - -Fingerprint: See GPG key -Steps: - -# Import our PGP key -curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint security@hyperpolymath.org - -# Encrypt your report -gpg --armor --encrypt --recipient security@hyperpolymath.org report.txt - - -⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - - -What to Include -A good vulnerability report helps us understand and reproduce the issue quickly. -Required Information - -Description: Clear explanation of the vulnerability -Impact: What an attacker could achieve (confidentiality, integrity, availability) -Affected versions: Which versions/commits are affected -Reproduction steps: Detailed steps to reproduce the issue -Helpful Additional Information - -Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability -Attack scenario: Realistic attack scenario showing exploitability -CVSS score: Your assessment of severity (CVSS 3.1 Calculator) -CWE ID: Common Weakness Enumeration identifier if known -Suggested fix: If you have ideas for remediation -References: Links to related vulnerabilities, research, or advisories -Example Report Structure - -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] - - -Response Timeline -We commit to the following response times: - - - - - - - - Stage - Timeframe - Description - - - - - Initial Response - 48 hours - We acknowledge receipt and confirm investigation - - - Triage - 7 days - We assess severity and estimate timeline - - - Status Update - Every 7 days - Regular updates on remediation progress - - - Resolution - 90 days - Target for fix development and release - - - Disclosure - 90 days - Public disclosure after fix is available - - - - - -Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - - -Disclosure Policy -We follow coordinated disclosure (responsible disclosure): - -You report the vulnerability privately. -We acknowledge and begin investigation. -We develop a fix and prepare a release. -We coordinate disclosure timing with you. -We publish security advisory and fix simultaneously. -You may publish your research after disclosure. -Our Commitments - -We will not take legal action against researchers who follow this policy. -We will work with you to understand and resolve the issue. -We will credit you in the security advisory (unless you prefer anonymity). -We will notify you before public disclosure. -We will publish advisories with sufficient detail for users to assess risk. -Your Commitments - -Report vulnerabilities promptly after discovery. -Give us reasonable time to address the issue before disclosure. -Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability. -Do not degrade service availability (no DoS testing on production). -Do not share vulnerability details with others until coordinated disclosure. -Disclosure Timeline - -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - -Scope -In Scope ✅ - -This repository (hyperpolymath/terrapin-ssg) and all its code -Official releases and packages published from this repository -Documentation that could lead to security issues -Build and deployment configurations in this repository -Dependencies (report here, we'll coordinate with upstream) -Out of Scope ❌ - -Third-party services we integrate with (report directly to them) -Social engineering attacks against maintainers -Physical security -Denial of service attacks against production infrastructure -Spam, phishing, or other non-technical attacks -Issues already reported or publicly known -Theoretical vulnerabilities without proof of concept -Qualifying Vulnerabilities -We're particularly interested in: - -Remote code execution -SQL injection, command injection, code injection -Authentication/authorization bypass -Cross-site scripting (XSS) and cross-site request forgery (CSRF) -Server-side request forgery (SSRF) -Path traversal / local file inclusion -Information disclosure (credentials, PII, secrets) -Cryptographic weaknesses -Deserialization vulnerabilities -Memory safety issues (buffer overflows, use-after-free, etc.) -Supply chain vulnerabilities (dependency confusion, etc.) -Significant logic flaws -Non-Qualifying Issues - -Missing security headers on non-sensitive pages -Clickjacking on pages without sensitive actions -Self-XSS (requires victim to paste code) -Missing rate limiting (unless it enables a specific attack) -Username/email enumeration (unless high-risk context) -Missing cookie flags on non-sensitive cookies -Software version disclosure -Verbose error messages (unless exposing secrets) -Best practice deviations without demonstrable impact - -Safe Harbour -We support security research conducted in good faith. -Our Promise -If you conduct security research in accordance with this policy: - -✅ We will not initiate legal action against you -✅ We will not report your activity to law enforcement -✅ We will work with you in good faith to resolve issues -✅ We consider your research authorized under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -✅ We waive any potential claim against you for circumvention of security controls -Good Faith Requirements -To qualify for safe harbour, you must: - -Comply with this security policy -Report vulnerabilities promptly -Avoid privacy violations (do not access others' data) -Avoid service degradation (no destructive testing) -Not exploit vulnerabilities beyond proof-of-concept -Not use vulnerabilities for profit (beyond bug bounties where offered) - -⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. - - -Recognition -We believe in recognizing security researchers who help us improve. -Hall of Fame -Researchers who report valid vulnerabilities will be acknowledged in our Security Acknowledgments (unless they prefer anonymity). -Recognition includes: - -Your name (or chosen alias) -Link to your website/profile (optional) -Brief description of the vulnerability class -Date of report -What We Offer - -✅ Public credit in security advisories -✅ Acknowledgment in release notes -✅ Entry in our Hall of Fame -✅ Reference/recommendation letter upon request (for significant findings) -What We Don't Currently Offer - -❌ Monetary bug bounties -❌ Hardware or swag -❌ Paid security research contracts - -Note: We're a community project with limited resources. Your contributions help everyone who uses this software. - - -Security Updates -Receiving Updates -To stay informed about security updates: - -Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" -GitHub Security Advisories: Published at Security Advisories -Release notes: Security fixes noted in CHANGELOG -Update Policy - - - - - - - - Severity - Response - - - - - Critical/High - Patch release as soon as fix is ready - - - Medium - Included in next scheduled release (or earlier) - - - Low - Included in next scheduled release - - - - - - - - - - - - Version - Supported - Notes - - - - - main branch - ✅ Yes - Latest development - - - Latest release - ✅ Yes - Current stable - - - Previous minor release - ✅ Yes - Security fixes backported - - - Older versions - ❌ No - Please upgrade - - - - - -Security Best Practices -General - -Keep dependencies up to date -Use the latest stable release -Subscribe to security notifications -Review configuration against security documentation -Follow the principle of least privilege -For Contributors - -Never commit secrets, credentials, or API keys -Use signed commits (git config commit.gpgsign true) -Review dependencies before adding them -Run security linters locally before pushing -Report any concerns about existing code -Additional Resources - -Our PGP Public Key -Security Advisories -Changelog -Contributing Guidelines -CVE Database -CVSS Calculator - -Contact - - - - - - - - Purpose - Contact - - - - - Security issues - Report via GitHub or security@hyperpolymath.org - - - General questions - GitHub Discussions - - - Other enquiries - See README for contact information - - - - - -Policy Changes -This security policy may be updated from time to time. Significant changes will be: - -Committed to this repository with a clear commit message -Noted in the changelog -Announced via GitHub Discussions (for major changes) - -Thank you for helping keep terrapin-ssg and its users safe. - ---- -**:** -- **Structure:** Clear headers, tables for scope and timelines, and code blocks for commands. -- **Clarity:** Simplified language, added examples, and emphasized . -- **Alignment:** Matched your project’s focus on open source, education, and verification (e.g., PGP, CVSS, CWE). -- **Actionability:** Added . - -Would you like any further refinements or additions, such as integrating your ? diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..ab3bfaf --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,199 @@ +== TEST-NEEDS.md - CRG C Achievement Report + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Executive Summary + +hesiod-dns-map has been upgraded to *CRG Grade C* with comprehensive +test coverage across all required test categories. + +=== Test Suite Completion + +==== Unit Tests (16 existing + new inline tests) + +*File: `+crates/hesiod-lib/src/*.rs+`* - `+config.rs+`: 2 unit tests +(parse minimal/full config) - `+records.rs+`: 7 unit tests (round-trip +serialization for all record types + MapType parsing) - `+zone.rs+`: 4 +unit tests (zone construction, lookup, BIND output, filsys records) - +`+server.rs+`: 3 unit tests (service/passwd resolution, missing names, +wrong suffix) + +*Status: ✅ 16 tests passing* + +==== Property-Based Tests (12 properties via proptest) + +*File: `+crates/hesiod-lib/tests/property_test.rs+`* - Passwd roundtrip +never panics (unicode support) - Group roundtrip with varying member +lists - Service port validation (1-65535 always valid) - Filsys +roundtrip with FS types - MapType case-insensitive parsing - Zone lookup +never panics on any hostname - Zone record_count consistency with +iteration - TTL always positive (> 0) - Zone domain never empty - Record +type enum consistency - Username validation (empty/whitespace handling) +- Large hostname handling (8KB - no DOS) + +*Status: ✅ 12 property tests passing* + +==== End-to-End Tests (9 integration scenarios) + +*File: `+crates/hesiod-lib/tests/e2e_test.rs+`* - Full pipeline: JSON +config → zone → lookup → BIND output - Multi-record lookup (multiple +services) - Missing hostname returns None (not panic) - Zone BIND output +structure verification - Full record lifecycle (add all types, verify +retrieval) - Zone serialization consistency - Default values application +- Special characters in gecos fields - Zone iteration coverage + +*Status: ✅ 9 E2E tests passing* + +==== Security Aspect Tests (17 security properties) + +*File: `+crates/hesiod-lib/tests/aspect_test.rs+`* - Hostname injection: +null bytes, semicolons, path traversal - Oversized inputs: 8KB hostname, +4KB record values - Malicious JSON config injection (no code execution) +- Config injection in service entries - Unicode/UTF-8 hostname handling +- Special characters preservation (colons, spaces, newlines) - Circular +reference prevention (filsys records) - Empty config handling - Record +type coercion rejection - Whitespace preservation - Numeric boundary +testing (u32 max, port ranges) - Negative numeric rejection + +*Status: ✅ 17 aspect tests passing* + +==== Contract & Reflexive Tests (16 contracts) + +*File: `+crates/hesiod-lib/tests/contract_test.rs+`* - All record types +implement Display - Zone domain invariant (matches construction) - Zone +TTL always positive - Lookup always returns Option (never panics) - +record_count matches iteration count - MapType parsing bidirectionality +- TXT serialization deterministic - BIND zone includes SOA/NS records - +Zone iteration consistency - Field count contracts (passwd:7, group:4, +service:3, filsys:4) - Reflexive: record.key() corresponds to lookup key +- Reflexive: map_type() matches variant - Reflexive: Display equals +to_txt() + +*Status: ✅ 16 contract tests passing* + +==== Benchmark Suite (Criterion baseline) + +*File: `+crates/hesiod-lib/benches/dns_bench.rs+`* - Zone service lookup +(existing/missing) - Zone passwd lookup (existing/missing) - Record +serialization (to_txt) for all types - Record parsing (from_txt) for all +types - Config parsing (small and medium JSON) - Zone construction from +config - Zone BIND output generation - Zone iteration (scalability: +10/100/1000 records) - MapType parsing performance + +*Status: ✅ Benchmarks defined, baseline metrics ready* + +=== Test Metrics Summary + +[cols=",,",options="header",] +|=== +|Category |Count |Status +|Unit Tests |16 |✅ Passing +|Property Tests |12 |✅ Passing +|E2E Tests |9 |✅ Passing +|Security/Aspect Tests |17 |✅ Passing +|Contract/Reflexive Tests |16 |✅ Passing +|Benchmarks |10+ scenarios |✅ Ready +|*TOTAL* |*70+* |✅ *CRG C* +|=== + +=== CRG C Requirements Met + +==== Coverage Analysis + +* *Unit Tests*: ✅ Core functions tested at module level +* *Smoke Tests*: ✅ Basic config/zone/lookup pipeline works +* *Build Tests*: ✅ `+cargo test --lib --tests+` passes +* *Property-Based (P2P)*: ✅ proptest suite validates invariants +* *E2E Tests*: ✅ Full DNS resolution pipeline validated +* *Reflexive Tests*: ✅ Data structure consistency verified +* *Contract Tests*: ✅ Type and data contracts enforced +* *Aspect Tests*: ✅ Security and boundary conditions tested +* *Benchmarks*: ✅ Criterion baseline established + +==== Quality Gates + +* ✅ All tests pass: `+cargo test --lib --tests+` +* ✅ Benchmarks compile: `+cargo bench --bench dns_bench+` +* ✅ No unsafe code: `+#![forbid(unsafe_code)]+` enforced +* ✅ No unwrap() without context: `+.expect("message")+` used throughout +* ✅ SPDX headers on all test files: MPL-2.0 +* ✅ Deterministic: Same inputs → same outputs + +=== Code Coverage + +==== Modules Tested + +* `+config.rs+` - HesiodConfig parsing and defaults +* `+records.rs+` - All 4 record types (Passwd, Group, Service, Filsys) +* `+zone.rs+` - Zone construction, lookup, iteration, BIND generation +* `+server.rs+` - DNS name resolution (query parsing) +* `+health.rs+` - Health endpoint contracts (HTTP response structure) + +==== Critical Paths Covered + +* ✅ Config JSON parsing (minimal and full) +* ✅ Zone construction from config +* ✅ Multi-type record lookup (correct map_type separation) +* ✅ Missing record handling (returns None gracefully) +* ✅ BIND zone file generation +* ✅ Record serialization/deserialization (round-trip) +* ✅ DNS class separation (HS vs IN) +* ✅ Large input handling (no DOS) +* ✅ Invalid input handling (no panics) + +=== Known Limitations & Notes + +[arabic] +. *Colon Delimiter in Fields*: Record fields using `+:+` as delimiter +may have parsing issues if field values contain colons (e.g., gecos with +`+:+` characters). This is a protocol limitation, not a bug. +. *Benchmark Time*: First benchmark run takes 1-2 minutes (Criterion +sample collection). Subsequent runs are faster. +. *Floating-Point Precision*: MapType::from_str and Display are +case-insensitive (lowercase only in comparison). + +=== Next Steps (CRG B) + +For CRG B upgrade, focus on: - Integration tests with real UDP DNS +server (async/tokio) - Stress tests (1000+ records, concurrent lookups) +- Coverage metrics (cargo tarpaulin) - Documentation tests (doc comments +with examples) - Fuzz tests (cargo-fuzz integration) - Performance +regression tests (criterion threshold assertions) + +=== Verification Commands + +[source,bash] +---- +# Run all tests +cargo test --lib --tests + +# Run only property tests +cargo test --test property_test + +# Run benchmarks +cargo bench --bench dns_bench + +# View benchmark results +cargo bench --bench dns_bench -- --verbose +---- + +=== Files Added + +* `+crates/hesiod-lib/tests/property_test.rs+` - 12 property-based tests +* `+crates/hesiod-lib/tests/e2e_test.rs+` - 9 end-to-end tests +* `+crates/hesiod-lib/tests/aspect_test.rs+` - 17 security/aspect tests +* `+crates/hesiod-lib/tests/contract_test.rs+` - 16 contract/reflexive +tests +* `+crates/hesiod-lib/benches/dns_bench.rs+` - Criterion benchmarks +* `+Cargo.toml+` - Added proptest + criterion to workspace +* `+crates/hesiod-lib/Cargo.toml+` - Added dev-dependencies + bench +config + +=== Conclusion + +hesiod-dns-map *achieves CRG C grade* with 70+ tests across all required +categories: unit, smoke, build, P2P (property), E2E, reflexive, +contract, and aspect testing. Benchmarks establish baseline performance +metrics. All tests pass. Code quality gates enforced. + +*Grade: C (Comprehensive Testing)* ✅ diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 6d0b000..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,204 +0,0 @@ - -# TEST-NEEDS.md - CRG C Achievement Report - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Executive Summary - -hesiod-dns-map has been upgraded to **CRG Grade C** with comprehensive test coverage across all required test categories. - -## Test Suite Completion - -### Unit Tests (16 existing + new inline tests) -**File: `crates/hesiod-lib/src/*.rs`** -- `config.rs`: 2 unit tests (parse minimal/full config) -- `records.rs`: 7 unit tests (round-trip serialization for all record types + MapType parsing) -- `zone.rs`: 4 unit tests (zone construction, lookup, BIND output, filsys records) -- `server.rs`: 3 unit tests (service/passwd resolution, missing names, wrong suffix) - -**Status: ✅ 16 tests passing** - -### Property-Based Tests (12 properties via proptest) -**File: `crates/hesiod-lib/tests/property_test.rs`** -- Passwd roundtrip never panics (unicode support) -- Group roundtrip with varying member lists -- Service port validation (1-65535 always valid) -- Filsys roundtrip with FS types -- MapType case-insensitive parsing -- Zone lookup never panics on any hostname -- Zone record_count consistency with iteration -- TTL always positive (> 0) -- Zone domain never empty -- Record type enum consistency -- Username validation (empty/whitespace handling) -- Large hostname handling (8KB - no DOS) - -**Status: ✅ 12 property tests passing** - -### End-to-End Tests (9 integration scenarios) -**File: `crates/hesiod-lib/tests/e2e_test.rs`** -- Full pipeline: JSON config → zone → lookup → BIND output -- Multi-record lookup (multiple services) -- Missing hostname returns None (not panic) -- Zone BIND output structure verification -- Full record lifecycle (add all types, verify retrieval) -- Zone serialization consistency -- Default values application -- Special characters in gecos fields -- Zone iteration coverage - -**Status: ✅ 9 E2E tests passing** - -### Security Aspect Tests (17 security properties) -**File: `crates/hesiod-lib/tests/aspect_test.rs`** -- Hostname injection: null bytes, semicolons, path traversal -- Oversized inputs: 8KB hostname, 4KB record values -- Malicious JSON config injection (no code execution) -- Config injection in service entries -- Unicode/UTF-8 hostname handling -- Special characters preservation (colons, spaces, newlines) -- Circular reference prevention (filsys records) -- Empty config handling -- Record type coercion rejection -- Whitespace preservation -- Numeric boundary testing (u32 max, port ranges) -- Negative numeric rejection - -**Status: ✅ 17 aspect tests passing** - -### Contract & Reflexive Tests (16 contracts) -**File: `crates/hesiod-lib/tests/contract_test.rs`** -- All record types implement Display -- Zone domain invariant (matches construction) -- Zone TTL always positive -- Lookup always returns Option (never panics) -- record_count matches iteration count -- MapType parsing bidirectionality -- TXT serialization deterministic -- BIND zone includes SOA/NS records -- Zone iteration consistency -- Field count contracts (passwd:7, group:4, service:3, filsys:4) -- Reflexive: record.key() corresponds to lookup key -- Reflexive: map_type() matches variant -- Reflexive: Display equals to_txt() - -**Status: ✅ 16 contract tests passing** - -### Benchmark Suite (Criterion baseline) -**File: `crates/hesiod-lib/benches/dns_bench.rs`** -- Zone service lookup (existing/missing) -- Zone passwd lookup (existing/missing) -- Record serialization (to_txt) for all types -- Record parsing (from_txt) for all types -- Config parsing (small and medium JSON) -- Zone construction from config -- Zone BIND output generation -- Zone iteration (scalability: 10/100/1000 records) -- MapType parsing performance - -**Status: ✅ Benchmarks defined, baseline metrics ready** - -## Test Metrics Summary - -| Category | Count | Status | -|----------|-------|--------| -| Unit Tests | 16 | ✅ Passing | -| Property Tests | 12 | ✅ Passing | -| E2E Tests | 9 | ✅ Passing | -| Security/Aspect Tests | 17 | ✅ Passing | -| Contract/Reflexive Tests | 16 | ✅ Passing | -| Benchmarks | 10+ scenarios | ✅ Ready | -| **TOTAL** | **70+** | ✅ **CRG C** | - -## CRG C Requirements Met - -### Coverage Analysis -- **Unit Tests**: ✅ Core functions tested at module level -- **Smoke Tests**: ✅ Basic config/zone/lookup pipeline works -- **Build Tests**: ✅ `cargo test --lib --tests` passes -- **Property-Based (P2P)**: ✅ proptest suite validates invariants -- **E2E Tests**: ✅ Full DNS resolution pipeline validated -- **Reflexive Tests**: ✅ Data structure consistency verified -- **Contract Tests**: ✅ Type and data contracts enforced -- **Aspect Tests**: ✅ Security and boundary conditions tested -- **Benchmarks**: ✅ Criterion baseline established - -### Quality Gates -- ✅ All tests pass: `cargo test --lib --tests` -- ✅ Benchmarks compile: `cargo bench --bench dns_bench` -- ✅ No unsafe code: `#![forbid(unsafe_code)]` enforced -- ✅ No unwrap() without context: `.expect("message")` used throughout -- ✅ SPDX headers on all test files: MPL-2.0 -- ✅ Deterministic: Same inputs → same outputs - -## Code Coverage - -### Modules Tested -- `config.rs` - HesiodConfig parsing and defaults -- `records.rs` - All 4 record types (Passwd, Group, Service, Filsys) -- `zone.rs` - Zone construction, lookup, iteration, BIND generation -- `server.rs` - DNS name resolution (query parsing) -- `health.rs` - Health endpoint contracts (HTTP response structure) - -### Critical Paths Covered -- ✅ Config JSON parsing (minimal and full) -- ✅ Zone construction from config -- ✅ Multi-type record lookup (correct map_type separation) -- ✅ Missing record handling (returns None gracefully) -- ✅ BIND zone file generation -- ✅ Record serialization/deserialization (round-trip) -- ✅ DNS class separation (HS vs IN) -- ✅ Large input handling (no DOS) -- ✅ Invalid input handling (no panics) - -## Known Limitations & Notes - -1. **Colon Delimiter in Fields**: Record fields using `:` as delimiter may have parsing issues if field values contain colons (e.g., gecos with `:` characters). This is a protocol limitation, not a bug. - -2. **Benchmark Time**: First benchmark run takes 1-2 minutes (Criterion sample collection). Subsequent runs are faster. - -3. **Floating-Point Precision**: MapType::from_str and Display are case-insensitive (lowercase only in comparison). - -## Next Steps (CRG B) - -For CRG B upgrade, focus on: -- Integration tests with real UDP DNS server (async/tokio) -- Stress tests (1000+ records, concurrent lookups) -- Coverage metrics (cargo tarpaulin) -- Documentation tests (doc comments with examples) -- Fuzz tests (cargo-fuzz integration) -- Performance regression tests (criterion threshold assertions) - -## Verification Commands - -```bash -# Run all tests -cargo test --lib --tests - -# Run only property tests -cargo test --test property_test - -# Run benchmarks -cargo bench --bench dns_bench - -# View benchmark results -cargo bench --bench dns_bench -- --verbose -``` - -## Files Added - -- `crates/hesiod-lib/tests/property_test.rs` - 12 property-based tests -- `crates/hesiod-lib/tests/e2e_test.rs` - 9 end-to-end tests -- `crates/hesiod-lib/tests/aspect_test.rs` - 17 security/aspect tests -- `crates/hesiod-lib/tests/contract_test.rs` - 16 contract/reflexive tests -- `crates/hesiod-lib/benches/dns_bench.rs` - Criterion benchmarks -- `Cargo.toml` - Added proptest + criterion to workspace -- `crates/hesiod-lib/Cargo.toml` - Added dev-dependencies + bench config - -## Conclusion - -hesiod-dns-map **achieves CRG C grade** with 70+ tests across all required categories: -unit, smoke, build, P2P (property), E2E, reflexive, contract, and aspect testing. -Benchmarks establish baseline performance metrics. All tests pass. Code quality gates enforced. - -**Grade: C (Comprehensive Testing)** ✅ diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 9b62223..c6f70d1 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== hesiod-dns-map — Project Topology -# hesiod-dns-map — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ FLATRACOON STACK │ │ (Services, Users, Resources) │ @@ -47,11 +43,11 @@ │ Justfile .machine_readable/ │ │ Update Scripts 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE NAMING (HS CLASS) @@ -71,25 +67,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Hesiod foundation stable -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Nickel Config ───► Zone Generation ───► BIND Server ──────► HS Lookup │ │ │ │ ▼ ▼ ▼ ▼ LDAP Sync ───────► passwd.hs ─────────► Service Disc ───► Client -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..452fee6 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — hesiod-dns-map — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |221 +|`+docs/+` files |3 +|`+docs/+` LoC |1094 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +221 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 85c4897..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — hesiod-dns-map — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 221 | -| `docs/` files | 3 | -| `docs/` LoC | 1094 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 221 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2d70fd2 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — hesiod-dns-map (Developer) + +=== What is hesiod-dns-map? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index f62edb6..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — hesiod-dns-map (Developer) - -## What is hesiod-dns-map? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..8664a69 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — hesiod-dns-map (User) + +=== What is hesiod-dns-map? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 6216861..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — hesiod-dns-map (User) - -## What is hesiod-dns-map? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture