diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 75% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index 30a4d57..fecce20 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,18 +1,20 @@ +== ZEROTIER_K8S_LINK ABI/FFI Documentation -# ZEROTIER_K8S_LINK ABI/FFI Documentation +=== Overview -## Overview +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +=== Architecture -## Architecture - -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -44,11 +46,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... zerotier-k8s-link/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -76,15 +78,17 @@ zerotier-k8s-link/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -96,13 +100,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -110,13 +115,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -124,13 +130,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -139,71 +146,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/zerotier-k8s-link.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -214,13 +228,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "zerotier-k8s-link.h" int main() { @@ -236,16 +251,19 @@ int main() { zerotier-k8s-link_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lzerotier-k8s-link -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import ZEROTIER_K8S_LINK.ABI.Foreign main : IO () @@ -258,11 +276,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "zerotier-k8s-link")] extern "C" { fn zerotier-k8s-link_init() -> *mut std::ffi::c_void; @@ -281,11 +300,12 @@ fn main() { zerotier-k8s-link_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libzerotier-k8s-link = "libzerotier-k8s-link" function init() @@ -311,27 +331,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -341,44 +364,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/zerotier-k8s-link.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/zerotier-k8s-link.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License PMPL-1.0-or-later -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] 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..b287ad9 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,71 @@ +== Changelog + +All notable changes to `+zerotier-k8s-link+` 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: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add RSR scaffolding - bot directives, AI manifest, ecosystem +refs +* feat: add FlatRacoon orchestrator manifest +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(licence): #3 isolated — clear scaffold-placeholder leak +(zerotier-k8s-link) (#51) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#48) +* fix(ci): sync hypatia-scan.yml to canonical (#47) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* 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 +* fix: remove duplicate SCM files from root + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#50) +* ci: bump actions/upload-artifact SHA to current v4 (#45) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts +* ci: deploy dogfood-gate, add Groove manifest and CRG tests + +=== 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 494387f..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Changelog - -All notable changes to `zerotier-k8s-link` 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: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add RSR scaffolding - bot directives, AI manifest, ecosystem refs -- feat: add FlatRacoon orchestrator manifest -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(licence): #3 isolated — clear scaffold-placeholder leak (zerotier-k8s-link) (#51) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#48) -- fix(ci): sync hypatia-scan.yml to canonical (#47) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- 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 -- fix: remove duplicate SCM files from root - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#50) -- ci: bump actions/upload-artifact SHA to current v4 (#45) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts -- ci: deploy dogfood-gate, add Groove manifest and CRG tests - -## 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..206b30c --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/zerotier-k8s-link.git cd +zerotier-k8s-link + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create zerotier-k8s-link-dev toolbox enter zerotier-k8s-link-dev +# Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +zerotier-k8s-link/ ├── 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/zerotier-k8s-link/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/zerotier-k8s-link/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/zerotier-k8s-link/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/zerotier-k8s-link/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 bd5685b..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/zerotier-k8s-link.git -cd zerotier-k8s-link - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create zerotier-k8s-link-dev -toolbox enter zerotier-k8s-link-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -zerotier-k8s-link/ -├── 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/zerotier-k8s-link/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/zerotier-k8s-link/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/zerotier-k8s-link/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/zerotier-k8s-link/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..6833c54 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,378 @@ +Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. Table of Contents + +.... +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 +.... + +This method ensures: + +.... +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, you may email us directly: + +Email security@hyperpolymath.org PGP Key Download Public Key Fingerprint +See GPG key + +== 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 (use 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 we’re +investigating Triage 7 days We assess severity, confirm the +vulnerability, and estimate timeline Status Update Every 7 days Regular +updates on remediation progress Resolution 90 days Target for fix +development and release (complex issues may take longer) Disclosure 90 +days Public disclosure after fix is available (coordinated with you) + +.... +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 (also known as 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 ✅ + +The following are within scope for security research: + +.... +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 ❌ + +The following are not in 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/authorisation 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 +Deserialisation vulnerabilities +Memory safety issues (buffer overflows, use-after-free, etc.) +Supply chain vulnerabilities (dependency confusion, etc.) +Significant logic flaws +.... + +Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +.... +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 authorised 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 recognising 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 Supported Versions 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 + +When using terrapin-ssg, we recommend: General + +.... +Keep dependencies up to date +Use the latest stable release +Subscribe to security notifications +Review configuration against security documentation +Follow 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. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5eb5e20..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,328 +0,0 @@ -Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. -Table of Contents - - 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 - -This method ensures: - - 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, you may email us directly: - -Email security@hyperpolymath.org -PGP Key Download Public Key -Fingerprint See GPG key - -# 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 (use 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 we're investigating -Triage 7 days We assess severity, confirm the vulnerability, and estimate timeline -Status Update Every 7 days Regular updates on remediation progress -Resolution 90 days Target for fix development and release (complex issues may take longer) -Disclosure 90 days Public disclosure after fix is available (coordinated with you) - - 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 (also known as 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 ✅ - -The following are within scope for security research: - - 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 ❌ - -The following are not in 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/authorisation 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 - Deserialisation vulnerabilities - Memory safety issues (buffer overflows, use-after-free, etc.) - Supply chain vulnerabilities (dependency confusion, etc.) - Significant logic flaws - -Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - - 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 authorised 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 recognising 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 -Supported Versions -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 - -When using terrapin-ssg, we recommend: -General - - Keep dependencies up to date - Use the latest stable release - Subscribe to security notifications - Review configuration against security documentation - Follow 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. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..f997ce5 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,275 @@ +== TEST-NEEDS.md — CRG Grade C Achievement + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Project Status + +*zerotier-k8s-link* has achieved *CRG Grade C* per the Hyperpolymath +Testing & Benchmarking Taxonomy (v1.0). + +=== Test Suite Composition + +==== Unit Tests (13 tests) + +* *configs/*: Nickel configuration file existence and structure +** network.ncl contains ZeroTier config (network_id, api_token, IP +pools, routes) +** firewall.ncl contains firewall rules with deny-by-default policies +** routes.ncl contains route definitions with valid CIDR notation +* *manifests/*: Kubernetes manifest file existence and structure +** All 6 manifest types exist (configmap, daemonset, namespace, +networkpolicy, secret, servicemonitor) +** daemonset references zerotier-system namespace +** networkpolicy has both ingress and egress rules +** secret contains placeholder values only (EXAMPLE_*) +* *ABI*: Idris2 ABI files structure +** SPDX headers present in all Nickel configs + +*Location*: `+tests/unit/config_structure_test.ts+` + +==== Smoke Tests (10 tests) + +* *Infrastructure presence* +** 4 bash scripts exist (authorize-nodes.sh, configure-routes.sh, +health-check.sh, join-network.sh) +** setup.sh exists with shell shebang +** 4 validation hooks exist (validate-codeql.sh, +validate-permissions.sh, validate-sha-pins.sh, validate-spdx.sh) +* *ABI and manifest validity* +** 3 Idris2 ABI files exist (Layout.idr, Types.idr, Foreign.idr) with +module declarations +** All Kubernetes manifests are non-empty YAML with apiVersion and kind +fields +** No hardcoded secrets in manifests +* *Manifest structure* +** root manifest file (zerotier-k8s-link.manifest.ncl) exists + +*Location*: `+tests/smoke/infra_smoke_test.ts+` + +==== Property-Based Tests (11 tests) + +* *Readability and resilience* +** All Nickel configs readable in 100-iteration loop (stability test) +* *Naming conventions* +** Nickel files follow lowercase-hyphen pattern +** Kubernetes manifests follow lowercase-hyphen-yaml pattern +** Firewall zone names are lowercase identifiers +* *Format validation* +** ZeroTier network ID is either placeholder (CHANGEME_NETWORK_ID) or 16 +hex characters +** IPv4 assignment pool start < end +** Route destinations are valid CIDR notation +** Firewall rules have required action/type fields +* *Cross-reference consistency* +** All manifests use the same namespace (zerotier-system) +** DaemonSet selector matches pod labels +** NetworkPolicy pod selector is defined + +*Location*: `+tests/property/network_property_test.ts+` + +==== End-to-End Tests (12 tests) + +* *Configuration pipeline* +** Full config pipeline reads all 3 Nickel configs without errors +** All K8s manifests cross-references are valid +* *Consistency validation* +** DaemonSet namespace matches declared namespace in namespace.yaml +** NetworkPolicy references zerotier app labels matching DaemonSet +** Routes don’t conflict with firewall deny rules +** Secret manifest contains only placeholder credentials +* *Feature coverage* +** network.ncl IPv6 pool is valid format +** ConfigMap provides auto-join configuration +** DaemonSet includes liveness/readiness probe configuration +** DaemonSet references zerotier-config and zerotier-credentials +** Firewall zones reference zerotier interface pattern (zt+) +** Routes reference network config IP pools (10.147.17.0/24) +** Network capabilities align with DaemonSet permissions + +*Location*: `+tests/e2e/network_e2e_test.ts+` + +==== Contract Tests (19 tests) + +Formal invariants enforced at all times: + +[arabic] +. *Firewall security* +* input_policy = "`DROP`" (deny-by-default) +* forward_policy = "`DROP`" (no forwarding by default) +* zerotier zone defined +. *Network configuration* +* Uses private IP ranges only (10.x.x.x, 172.16-31.x.x, 192.168.x.x) +* Both IPv4 and IPv6 pools defined +* Routes reference valid CIDR destinations +* allow_default_route = false (security) +* Firewall control plane uses port 9993 +. *Kubernetes manifests* +* DaemonSet namespace matches namespace.yaml +* ConfigMap named zerotier-config +* Secret named zerotier-credentials with placeholder values only +* NetworkPolicy has explicit ingress and egress rules +* DaemonSet uses hostNetwork=true +* DaemonSet requests NET_ADMIN capability +. *ABI compliance* +* All ABI files have module declarations +* Layout.idr imports Types module + +*Location*: `+tests/contract/network_contracts_test.ts+` + +==== Aspect Tests (14 tests) + +Cross-cutting security and quality concerns: + +* *Credential protection* +** No hardcoded API keys or tokens +** No direct echoing of secret environment variables to logs +** ZeroTier tokens are placeholders only +** No plaintext passwords in manifests +** Secret type is Opaque (secure) +* *Network security* +** No HTTP endpoints (HTTPS only) +** NetworkPolicy has both ingress and egress rules +** No world-readable permission patterns (chmod 777) +* *Infrastructure security* +** No hardcoded secrets in bash scripts +** Network config disables dangerous capabilities +** DaemonSet has security context defined +** Kubernetes RBAC doesn’t request cluster-admin + +*Location*: `+tests/aspect/security_aspect_test.ts+` + +==== Benchmark Tests (11 benchmarks) + +Performance baseline established: + +[cols=",,",options="header",] +|=== +|Operation |Time/Iteration |Iterations/sec +|read all nickel configs sequentially |257.0 µs |3,891 +|read all k8s manifests sequentially |952.5 µs |1,050 +|read network config only |955.4 µs |1,047 +|read firewall config only |1.1 ms |889.7 +|read routes config only |498.6 µs |2,005 +|read daemonset manifest only |1.1 ms |912.0 +|read networkpolicy manifest only |1.1 ms |902.8 +|read secret manifest only |303.1 µs |3,299 +|read all ABI files |481.8 µs |2,076 +|parse nickel config string content |233.1 µs |4,290 +|parse kubernetes manifest string content |150.5 µs |6,645 +|=== + +*Location*: `+tests/bench/config_bench.ts+` + +=== Test Execution + +==== Run all tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/zerotier-k8s-link +~/.deno/bin/deno test --allow-read --allow-env tests/ +---- + +==== Run benchmarks + +[source,bash] +---- +~/.deno/bin/deno bench --allow-read tests/bench/ +---- + +==== Run specific test category + +[source,bash] +---- +~/.deno/bin/deno test --allow-read --allow-env tests/unit/ +~/.deno/bin/deno test --allow-read --allow-env tests/smoke/ +~/.deno/bin/deno test --allow-read --allow-env tests/property/ +~/.deno/bin/deno test --allow-read --allow-env tests/e2e/ +~/.deno/bin/deno test --allow-read --allow-env tests/contract/ +~/.deno/bin/deno test --allow-read --allow-env tests/aspect/ +---- + +=== Test Results + +*Total tests*: 79 + +*Passed*: 79 + +*Failed*: 0 + +*Success rate*: 100% + +==== Latest test run output + +.... +test result: ok. 79 passed | 0 failed (1s) +.... + +=== Configuration Files Tested + +==== Nickel Configuration Files + +* `+configs/network.ncl+` — ZeroTier network configuration +* `+configs/firewall.ncl+` — Firewall rules and policies +* `+configs/routes.ncl+` — Static and network route definitions + +==== Kubernetes Manifest Files + +* `+manifests/configmap.yaml+` — Configuration management +* `+manifests/daemonset.yaml+` — ZeroTier daemon deployment +* `+manifests/namespace.yaml+` — Kubernetes namespace declaration +* `+manifests/networkpolicy.yaml+` — Network access policies +* `+manifests/secret.yaml+` — Sensitive credentials +* `+manifests/servicemonitor.yaml+` — Prometheus monitoring + +==== ABI/FFI Files + +* `+src/abi/Layout.idr+` — Memory layout proofs +* `+src/abi/Types.idr+` — Type definitions and C ABI compatibility +* `+src/abi/Foreign.idr+` — Foreign function interface declarations + +==== Supporting Infrastructure + +* `+setup.sh+` — Installation script +* `+scripts/authorize-nodes.sh+` — Node authorization script +* `+scripts/configure-routes.sh+` — Route configuration script +* `+scripts/health-check.sh+` — Health monitoring script +* `+scripts/join-network.sh+` — Network join script +* `+hooks/validate-codeql.sh+` — CodeQL validation +* `+hooks/validate-permissions.sh+` — Permission validation +* `+hooks/validate-sha-pins.sh+` — SHA pin validation +* `+hooks/validate-spdx.sh+` — SPDX header validation + +=== CRG C Criteria Met + +✅ *Unit tests* — 13 tests covering config structure + +✅ *Smoke tests* — 10 tests covering infrastructure presence + +✅ *Build/compilation tests* — 79 tests with Deno (build-time +validation) + +✅ *Property-based tests* — 11 tests for consistency and resilience + +✅ *E2E tests* — 12 tests for cross-component integration + +✅ *Reflexive tests* — 11 property tests (100-iteration loops, +readability) + +✅ *Contract tests* — 19 invariant-based tests + +✅ *Aspect tests* — 14 security concern tests + +✅ *Benchmarks* — 11 performance baselines established + +*Total coverage*: 79 tests + 11 benchmarks = comprehensive CRG C +validation + +=== Next Steps (CRG B Requirements) + +To achieve CRG B grade, add: + +[arabic] +. *Integration tests* — Deploy to K8s and verify network connectivity +. *Mutation tests* — Verify test sensitivity to code changes +. *Load tests* — ZeroTier throughput under traffic +. *Chaos tests* — Network failures, node restarts, credential rotation +. *Upgrade tests* — Zero-downtime upgrades of ZeroTier daemon +. *Target coverage* — 6 specific targets (see RSR template) + +=== References + +* *Testing Taxonomy*: Hyperpolymath Testing & Benchmarking Taxonomy v1.0 +* *RSR Standard*: Rhodium Standard Repositories +(https://github.com/hyperpolymath/rsr-template-repo) +* *CRG Spec*: Code Review Grading v2.0 (see MEMORY.md: crg-v2-spec.md) +* *License*: PMPL-1.0-or-later (Palimpsest License) diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index d5e56ab..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,246 +0,0 @@ -# TEST-NEEDS.md — CRG Grade C Achievement - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Project Status - -**zerotier-k8s-link** has achieved **CRG Grade C** per the Hyperpolymath Testing & Benchmarking Taxonomy (v1.0). - -## Test Suite Composition - -### Unit Tests (13 tests) -- **configs/**: Nickel configuration file existence and structure - - network.ncl contains ZeroTier config (network_id, api_token, IP pools, routes) - - firewall.ncl contains firewall rules with deny-by-default policies - - routes.ncl contains route definitions with valid CIDR notation -- **manifests/**: Kubernetes manifest file existence and structure - - All 6 manifest types exist (configmap, daemonset, namespace, networkpolicy, secret, servicemonitor) - - daemonset references zerotier-system namespace - - networkpolicy has both ingress and egress rules - - secret contains placeholder values only (EXAMPLE_*) -- **ABI**: Idris2 ABI files structure - - SPDX headers present in all Nickel configs - -**Location**: `tests/unit/config_structure_test.ts` - -### Smoke Tests (10 tests) -- **Infrastructure presence** - - 4 bash scripts exist (authorize-nodes.sh, configure-routes.sh, health-check.sh, join-network.sh) - - setup.sh exists with shell shebang - - 4 validation hooks exist (validate-codeql.sh, validate-permissions.sh, validate-sha-pins.sh, validate-spdx.sh) -- **ABI and manifest validity** - - 3 Idris2 ABI files exist (Layout.idr, Types.idr, Foreign.idr) with module declarations - - All Kubernetes manifests are non-empty YAML with apiVersion and kind fields - - No hardcoded secrets in manifests -- **Manifest structure** - - root manifest file (zerotier-k8s-link.manifest.ncl) exists - -**Location**: `tests/smoke/infra_smoke_test.ts` - -### Property-Based Tests (11 tests) -- **Readability and resilience** - - All Nickel configs readable in 100-iteration loop (stability test) -- **Naming conventions** - - Nickel files follow lowercase-hyphen pattern - - Kubernetes manifests follow lowercase-hyphen-yaml pattern - - Firewall zone names are lowercase identifiers -- **Format validation** - - ZeroTier network ID is either placeholder (CHANGEME_NETWORK_ID) or 16 hex characters - - IPv4 assignment pool start < end - - Route destinations are valid CIDR notation - - Firewall rules have required action/type fields -- **Cross-reference consistency** - - All manifests use the same namespace (zerotier-system) - - DaemonSet selector matches pod labels - - NetworkPolicy pod selector is defined - -**Location**: `tests/property/network_property_test.ts` - -### End-to-End Tests (12 tests) -- **Configuration pipeline** - - Full config pipeline reads all 3 Nickel configs without errors - - All K8s manifests cross-references are valid -- **Consistency validation** - - DaemonSet namespace matches declared namespace in namespace.yaml - - NetworkPolicy references zerotier app labels matching DaemonSet - - Routes don't conflict with firewall deny rules - - Secret manifest contains only placeholder credentials -- **Feature coverage** - - network.ncl IPv6 pool is valid format - - ConfigMap provides auto-join configuration - - DaemonSet includes liveness/readiness probe configuration - - DaemonSet references zerotier-config and zerotier-credentials - - Firewall zones reference zerotier interface pattern (zt+) - - Routes reference network config IP pools (10.147.17.0/24) - - Network capabilities align with DaemonSet permissions - -**Location**: `tests/e2e/network_e2e_test.ts` - -### Contract Tests (19 tests) -Formal invariants enforced at all times: - -1. **Firewall security** - - input_policy = "DROP" (deny-by-default) - - forward_policy = "DROP" (no forwarding by default) - - zerotier zone defined - -2. **Network configuration** - - Uses private IP ranges only (10.x.x.x, 172.16-31.x.x, 192.168.x.x) - - Both IPv4 and IPv6 pools defined - - Routes reference valid CIDR destinations - - allow_default_route = false (security) - - Firewall control plane uses port 9993 - -3. **Kubernetes manifests** - - DaemonSet namespace matches namespace.yaml - - ConfigMap named zerotier-config - - Secret named zerotier-credentials with placeholder values only - - NetworkPolicy has explicit ingress and egress rules - - DaemonSet uses hostNetwork=true - - DaemonSet requests NET_ADMIN capability - -4. **ABI compliance** - - All ABI files have module declarations - - Layout.idr imports Types module - -**Location**: `tests/contract/network_contracts_test.ts` - -### Aspect Tests (14 tests) -Cross-cutting security and quality concerns: - -- **Credential protection** - - No hardcoded API keys or tokens - - No direct echoing of secret environment variables to logs - - ZeroTier tokens are placeholders only - - No plaintext passwords in manifests - - Secret type is Opaque (secure) - -- **Network security** - - No HTTP endpoints (HTTPS only) - - NetworkPolicy has both ingress and egress rules - - No world-readable permission patterns (chmod 777) - -- **Infrastructure security** - - No hardcoded secrets in bash scripts - - Network config disables dangerous capabilities - - DaemonSet has security context defined - - Kubernetes RBAC doesn't request cluster-admin - -**Location**: `tests/aspect/security_aspect_test.ts` - -### Benchmark Tests (11 benchmarks) -Performance baseline established: - -| Operation | Time/Iteration | Iterations/sec | -|-----------|----------------|----------------| -| read all nickel configs sequentially | 257.0 µs | 3,891 | -| read all k8s manifests sequentially | 952.5 µs | 1,050 | -| read network config only | 955.4 µs | 1,047 | -| read firewall config only | 1.1 ms | 889.7 | -| read routes config only | 498.6 µs | 2,005 | -| read daemonset manifest only | 1.1 ms | 912.0 | -| read networkpolicy manifest only | 1.1 ms | 902.8 | -| read secret manifest only | 303.1 µs | 3,299 | -| read all ABI files | 481.8 µs | 2,076 | -| parse nickel config string content | 233.1 µs | 4,290 | -| parse kubernetes manifest string content | 150.5 µs | 6,645 | - -**Location**: `tests/bench/config_bench.ts` - -## Test Execution - -### Run all tests -```bash -cd /var/mnt/eclipse/repos/zerotier-k8s-link -~/.deno/bin/deno test --allow-read --allow-env tests/ -``` - -### Run benchmarks -```bash -~/.deno/bin/deno bench --allow-read tests/bench/ -``` - -### Run specific test category -```bash -~/.deno/bin/deno test --allow-read --allow-env tests/unit/ -~/.deno/bin/deno test --allow-read --allow-env tests/smoke/ -~/.deno/bin/deno test --allow-read --allow-env tests/property/ -~/.deno/bin/deno test --allow-read --allow-env tests/e2e/ -~/.deno/bin/deno test --allow-read --allow-env tests/contract/ -~/.deno/bin/deno test --allow-read --allow-env tests/aspect/ -``` - -## Test Results - -**Total tests**: 79 -**Passed**: 79 -**Failed**: 0 -**Success rate**: 100% - -### Latest test run output -``` -test result: ok. 79 passed | 0 failed (1s) -``` - -## Configuration Files Tested - -### Nickel Configuration Files -- `configs/network.ncl` — ZeroTier network configuration -- `configs/firewall.ncl` — Firewall rules and policies -- `configs/routes.ncl` — Static and network route definitions - -### Kubernetes Manifest Files -- `manifests/configmap.yaml` — Configuration management -- `manifests/daemonset.yaml` — ZeroTier daemon deployment -- `manifests/namespace.yaml` — Kubernetes namespace declaration -- `manifests/networkpolicy.yaml` — Network access policies -- `manifests/secret.yaml` — Sensitive credentials -- `manifests/servicemonitor.yaml` — Prometheus monitoring - -### ABI/FFI Files -- `src/abi/Layout.idr` — Memory layout proofs -- `src/abi/Types.idr` — Type definitions and C ABI compatibility -- `src/abi/Foreign.idr` — Foreign function interface declarations - -### Supporting Infrastructure -- `setup.sh` — Installation script -- `scripts/authorize-nodes.sh` — Node authorization script -- `scripts/configure-routes.sh` — Route configuration script -- `scripts/health-check.sh` — Health monitoring script -- `scripts/join-network.sh` — Network join script -- `hooks/validate-codeql.sh` — CodeQL validation -- `hooks/validate-permissions.sh` — Permission validation -- `hooks/validate-sha-pins.sh` — SHA pin validation -- `hooks/validate-spdx.sh` — SPDX header validation - -## CRG C Criteria Met - -✅ **Unit tests** — 13 tests covering config structure -✅ **Smoke tests** — 10 tests covering infrastructure presence -✅ **Build/compilation tests** — 79 tests with Deno (build-time validation) -✅ **Property-based tests** — 11 tests for consistency and resilience -✅ **E2E tests** — 12 tests for cross-component integration -✅ **Reflexive tests** — 11 property tests (100-iteration loops, readability) -✅ **Contract tests** — 19 invariant-based tests -✅ **Aspect tests** — 14 security concern tests -✅ **Benchmarks** — 11 performance baselines established - -**Total coverage**: 79 tests + 11 benchmarks = comprehensive CRG C validation - -## Next Steps (CRG B Requirements) - -To achieve CRG B grade, add: - -1. **Integration tests** — Deploy to K8s and verify network connectivity -2. **Mutation tests** — Verify test sensitivity to code changes -3. **Load tests** — ZeroTier throughput under traffic -4. **Chaos tests** — Network failures, node restarts, credential rotation -5. **Upgrade tests** — Zero-downtime upgrades of ZeroTier daemon -6. **Target coverage** — 6 specific targets (see RSR template) - -## References - -- **Testing Taxonomy**: Hyperpolymath Testing & Benchmarking Taxonomy v1.0 -- **RSR Standard**: Rhodium Standard Repositories (https://github.com/hyperpolymath/rsr-template-repo) -- **CRG Spec**: Code Review Grading v2.0 (see MEMORY.md: crg-v2-spec.md) -- **License**: PMPL-1.0-or-later (Palimpsest License) diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 03adfc7..936691a 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== zerotier-k8s-link — Project Topology -# zerotier-k8s-link — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ ZEROTIER CENTRAL │ │ (Network Controller / API) │ @@ -41,11 +37,11 @@ │ Justfile Automation .machine_readable/ │ │ Nickel configs (ncl) 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE OVERLAY @@ -66,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████░░░░░ ~50% Scaffolding stable, Deploy maturing -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Network ID ──────► Join Script ──────► DaemonSet Pod ──────► Virtual Interface │ │ │ │ ▼ ▼ ▼ ▼ API Token ───────► Authorize ──────► Encrypted Mesh ──────► Private Route -``` +.... -## 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..aaecfe9 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,70 @@ +== Tech-Debt Audit — zerotier-k8s-link — 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:* `+2026-05-22+`. + +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 + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 11 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+PMPL-1.0-or-later+` +|Manifest licence |`+PMPL-1.0-or-later+` +|Body classifier |`+PMPL-1.0-or-later+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |199 +|`+docs/+` files |5 +|`+docs/+` LoC |803 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=199 docs=5/803+` +|=== + +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 6a3e4fb..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,62 +0,0 @@ - - -# Tech-Debt Audit — zerotier-k8s-link — 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:** `2026-05-22`. - -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 - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 11 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `PMPL-1.0-or-later` | -| Manifest licence | `PMPL-1.0-or-later` | -| Body classifier | `PMPL-1.0-or-later` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 199 | -| `docs/` files | 5 | -| `docs/` LoC | 803 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=199 docs=5/803` | - - -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/examples/README.adoc b/examples/README.adoc new file mode 100644 index 0000000..6a176cc --- /dev/null +++ b/examples/README.adoc @@ -0,0 +1,48 @@ +== ZeroTier K8s Link Examples + +Example configurations and deployment guides for ZeroTier overlay +networking in Kubernetes. + +=== Available Examples + +==== link:./basic-deployment.md[basic-deployment.md] + +Complete walkthrough of deploying ZeroTier to a Kubernetes cluster, +including: - Prerequisites and setup - Credential configuration - +Deployment process - Node authorization - Health checking - +Troubleshooting tips + +=== Quick Start + +[source,bash] +---- +# 1. Set credentials +export ZEROTIER_NETWORK_ID="your-network-id" +export ZEROTIER_API_TOKEN="your-api-token" + +# 2. Deploy +just deploy + +# 3. Authorize nodes +just authorize-nodes + +# 4. Verify +just mesh-status +---- + +=== Use Cases + +* *Multi-cloud K8s clusters*: Connect nodes across AWS, GCP, Azure, +on-prem +* *IPFS overlay*: Private IPFS network over ZeroTier mesh +* *Secure microservices*: End-to-end encrypted service communication +* *Development environments*: Secure access to remote K8s clusters + +=== Related Projects + +* https://github.com/hyperpolymath/flatracoon-netstack[flatracoon-netstack] +- Complete network stack +* https://github.com/hyperpolymath/twingate-helm-deploy[twingate-helm-deploy] +- External access layer +* https://github.com/hyperpolymath/ipfs-overlay[ipfs-overlay] - IPFS +integration diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index e3520ec..0000000 --- a/examples/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# ZeroTier K8s Link Examples - -Example configurations and deployment guides for ZeroTier overlay networking in Kubernetes. - -## Available Examples - -### [basic-deployment.md](./basic-deployment.md) -Complete walkthrough of deploying ZeroTier to a Kubernetes cluster, including: -- Prerequisites and setup -- Credential configuration -- Deployment process -- Node authorization -- Health checking -- Troubleshooting tips - -## Quick Start - -```bash -# 1. Set credentials -export ZEROTIER_NETWORK_ID="your-network-id" -export ZEROTIER_API_TOKEN="your-api-token" - -# 2. Deploy -just deploy - -# 3. Authorize nodes -just authorize-nodes - -# 4. Verify -just mesh-status -``` - -## Use Cases - -- **Multi-cloud K8s clusters**: Connect nodes across AWS, GCP, Azure, on-prem -- **IPFS overlay**: Private IPFS network over ZeroTier mesh -- **Secure microservices**: End-to-end encrypted service communication -- **Development environments**: Secure access to remote K8s clusters - -## Related Projects - -- [flatracoon-netstack](https://github.com/hyperpolymath/flatracoon-netstack) - Complete network stack -- [twingate-helm-deploy](https://github.com/hyperpolymath/twingate-helm-deploy) - External access layer -- [ipfs-overlay](https://github.com/hyperpolymath/ipfs-overlay) - IPFS integration diff --git a/examples/basic-deployment.adoc b/examples/basic-deployment.adoc new file mode 100644 index 0000000..1464b71 --- /dev/null +++ b/examples/basic-deployment.adoc @@ -0,0 +1,113 @@ +== Basic ZeroTier K8s Deployment Example + +This guide shows how to deploy ZeroTier to a Kubernetes cluster for +encrypted overlay networking. + +=== Prerequisites + +* Kubernetes cluster (v1.20+) +* kubectl configured +* ZeroTier Central account +* Network created in ZeroTier Central + +=== Step 1: Get Network Credentials + +[arabic] +. Log into https://my.zerotier.com +. Create a network (or use existing) +. Note the Network ID (16 characters) +. Generate an API token: Account → API Access Tokens + +=== Step 2: Configure Environment + +[source,bash] +---- +export ZEROTIER_NETWORK_ID="a0cbf4b62a123456" +export ZEROTIER_API_TOKEN="your-api-token-here" +---- + +=== Step 3: Deploy to Cluster + +[source,bash] +---- +# Deploy all components +just deploy + +# Or manually: +kubectl apply -f manifests/namespace.yaml +kubectl apply -f manifests/secret.yaml +kubectl apply -f manifests/configmap.yaml +kubectl apply -f manifests/daemonset.yaml +kubectl apply -f manifests/networkpolicy.yaml +---- + +=== Step 4: Authorize Nodes + +Option A: Use API (recommended): + +[source,bash] +---- +just authorize-nodes +---- + +Option B: Manual authorization in ZeroTier Central: 1. Go to your +network page 2. Scroll to "`Members`" section 3. Check the boxes next to +your K8s nodes 4. Save + +=== Step 5: Verify Connectivity + +[source,bash] +---- +# Check deployment status +just status + +# View logs +just logs + +# Check mesh health +just health-check a0cbf4b62a123456 + +# View mesh status from pods +just mesh-status +---- + +=== Expected Output + +.... +$ just mesh-status +=== Mesh Status from K8s Nodes === +200 listnetworks a0cbf4b62a123456 flatracoon-k8s-mesh 10.147.17.1/24 OK PRIVATE ztmesh123 +200 listpeers +.... + +=== Troubleshooting + +==== Nodes not joining + +* Check pod logs: `+kubectl -n zerotier-system logs daemonset/zerotier+` +* Verify credentials in secret +* Ensure network exists in ZeroTier Central + +==== Nodes joined but not authorized + +* Run `+just authorize-nodes+` +* Or manually authorize in ZeroTier Central web UI + +==== Cannot reach other nodes + +* Check firewall rules allow UDP 9993 +* Verify nodes show "`OK`" status in `+zerotier-cli listnetworks+` +* Check routing configuration + +=== Integration with IPFS + +To bind IPFS to the ZeroTier interface: + +[source,bash] +---- +# Get ZeroTier interface name +ZT_IFACE=$(zerotier-cli listnetworks | awk '{print $8}' | tail -1) + +# Configure IPFS +ipfs config Addresses.Swarm --json '["/'${ZT_IFACE}'/tcp/4001"]' +---- diff --git a/examples/basic-deployment.md b/examples/basic-deployment.md deleted file mode 100644 index ba49bf7..0000000 --- a/examples/basic-deployment.md +++ /dev/null @@ -1,104 +0,0 @@ -# Basic ZeroTier K8s Deployment Example - -This guide shows how to deploy ZeroTier to a Kubernetes cluster for encrypted overlay networking. - -## Prerequisites - -- Kubernetes cluster (v1.20+) -- kubectl configured -- ZeroTier Central account -- Network created in ZeroTier Central - -## Step 1: Get Network Credentials - -1. Log into https://my.zerotier.com -2. Create a network (or use existing) -3. Note the Network ID (16 characters) -4. Generate an API token: Account → API Access Tokens - -## Step 2: Configure Environment - -```bash -export ZEROTIER_NETWORK_ID="a0cbf4b62a123456" -export ZEROTIER_API_TOKEN="your-api-token-here" -``` - -## Step 3: Deploy to Cluster - -```bash -# Deploy all components -just deploy - -# Or manually: -kubectl apply -f manifests/namespace.yaml -kubectl apply -f manifests/secret.yaml -kubectl apply -f manifests/configmap.yaml -kubectl apply -f manifests/daemonset.yaml -kubectl apply -f manifests/networkpolicy.yaml -``` - -## Step 4: Authorize Nodes - -Option A: Use API (recommended): -```bash -just authorize-nodes -``` - -Option B: Manual authorization in ZeroTier Central: -1. Go to your network page -2. Scroll to "Members" section -3. Check the boxes next to your K8s nodes -4. Save - -## Step 5: Verify Connectivity - -```bash -# Check deployment status -just status - -# View logs -just logs - -# Check mesh health -just health-check a0cbf4b62a123456 - -# View mesh status from pods -just mesh-status -``` - -## Expected Output - -``` -$ just mesh-status -=== Mesh Status from K8s Nodes === -200 listnetworks a0cbf4b62a123456 flatracoon-k8s-mesh 10.147.17.1/24 OK PRIVATE ztmesh123 -200 listpeers -``` - -## Troubleshooting - -### Nodes not joining -- Check pod logs: `kubectl -n zerotier-system logs daemonset/zerotier` -- Verify credentials in secret -- Ensure network exists in ZeroTier Central - -### Nodes joined but not authorized -- Run `just authorize-nodes` -- Or manually authorize in ZeroTier Central web UI - -### Cannot reach other nodes -- Check firewall rules allow UDP 9993 -- Verify nodes show "OK" status in `zerotier-cli listnetworks` -- Check routing configuration - -## Integration with IPFS - -To bind IPFS to the ZeroTier interface: - -```bash -# Get ZeroTier interface name -ZT_IFACE=$(zerotier-cli listnetworks | awk '{print $8}' | tail -1) - -# Configure IPFS -ipfs config Addresses.Swarm --json '["/'${ZT_IFACE}'/tcp/4001"]' -``` diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..98e2f00 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — zerotier-k8s-link (Developer) + +=== What is zerotier-k8s-link? + +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: PMPL-1.0-or-later +* 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 42b9f5b..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — zerotier-k8s-link (Developer) - -## What is zerotier-k8s-link? -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: PMPL-1.0-or-later -- 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..59cbb0a --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — zerotier-k8s-link (User) + +=== What is zerotier-k8s-link? + +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: PMPL-1.0-or-later +* 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 7e4e233..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — zerotier-k8s-link (User) - -## What is zerotier-k8s-link? -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: PMPL-1.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture