diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} 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/ │ @@ -49,11 +48,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 -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── 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 @@ -101,13 +102,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 @@ -115,13 +117,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 @@ -129,13 +132,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 { @@ -144,71 +148,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/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,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 "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,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 @@ -346,44 +366,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/{{project}}.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/{{project}}.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 MPL-2.0 -## 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..d78ad8c --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,66 @@ +== Changelog + +All notable changes to `+twingate-helm-deploy+` 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 + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#47) +* fix(ci): sync hypatia-scan.yml to canonical (#46) +* 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: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement +* fix: SPDX headers (AGPL→PMPL), email, author name + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#49) +* ci: bump actions/upload-artifact SHA to current v4 (#44) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts +* ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks + +=== 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 bb2c0b0..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,63 +0,0 @@ - - -# Changelog - -All notable changes to `twingate-helm-deploy` 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 - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#47) -- fix(ci): sync hypatia-scan.yml to canonical (#46) -- 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: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement -- fix: SPDX headers (AGPL→PMPL), email, author name - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#49) -- ci: bump actions/upload-artifact SHA to current v4 (#44) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts -- ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks - -## 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 bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +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..608e4c0 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/twingate-helm-deploy.git cd +twingate-helm-deploy + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create twingate-helm-deploy-dev toolbox enter +twingate-helm-deploy-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +twingate-helm-deploy/ ├── 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/twingate-helm-deploy/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/twingate-helm-deploy/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/twingate-helm-deploy/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/twingate-helm-deploy/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 a79f0d7..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/twingate-helm-deploy.git -cd twingate-helm-deploy - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create twingate-helm-deploy-dev -toolbox enter twingate-helm-deploy-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -twingate-helm-deploy/ -├── 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/twingate-helm-deploy/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/twingate-helm-deploy/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/twingate-helm-deploy/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/twingate-helm-deploy/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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index fd95f90..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +0,0 @@ - -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. 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 762bf01..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,332 +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..f8cc43b --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — twingate-helm-deploy + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Zig FFI tests |1 |`+ffi/zig/test/integration_test.zig+` +|Test infrastructure |Present |`+tests/+` directory structure +|=== + +=== What’s Covered + +* [x] Zig FFI integration tests +* [x] Test framework infrastructure + +=== Still Missing (for CRG B+) + +* [ ] Helm chart validation tests +* [ ] Twingate connector tests +* [ ] Kubernetes deployment tests +* [ ] Network security property tests +* [ ] Performance benchmarks + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/twingate-helm-deploy && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index f9a113f..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,33 +0,0 @@ - -# TEST-NEEDS.md — twingate-helm-deploy - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Zig FFI tests | 1 | `ffi/zig/test/integration_test.zig` | -| Test infrastructure | Present | `tests/` directory structure | - -## What's Covered - -- [x] Zig FFI integration tests -- [x] Test framework infrastructure - -## Still Missing (for CRG B+) - -- [ ] Helm chart validation tests -- [ ] Twingate connector tests -- [ ] Kubernetes deployment tests -- [ ] Network security property tests -- [ ] Performance benchmarks - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/twingate-helm-deploy && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index bf01a51..cec0559 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== twingate-helm-deploy — Project Topology -# twingate-helm-deploy — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ TWINGATE CLOUD │ │ (Access Control Plane) │ @@ -44,11 +37,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Mustfile / Helm 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE DEPLOYMENT @@ -69,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production-ready ingress -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Twingate Cloud ──► Access Token ────► Connector Pod ─────► Secure Ingress │ │ │ │ ▼ ▼ ▼ ▼ Helm Values ─────► K8s Context ──────► Network Policy ───► Target Service -``` +.... -## 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..4833e81 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — twingate-helm-deploy — 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 |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |173 +|`+docs/+` files |5 +|`+docs/+` LoC |891 +|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 +173 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 d30ae27..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — twingate-helm-deploy — 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 | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 173 | -| `docs/` files | 5 | -| `docs/` LoC | 891 | -| 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 173 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/examples/basic-deployment.adoc b/examples/basic-deployment.adoc new file mode 100644 index 0000000..c4038a3 --- /dev/null +++ b/examples/basic-deployment.adoc @@ -0,0 +1,55 @@ +== Twingate Connector Deployment Guide + +Deploy Twingate Connector to Kubernetes for zero-trust network access. + +=== Prerequisites + +* Kubernetes cluster +* Helm 3+ +* Twingate account with network created +* Access/refresh tokens from Twingate + +=== Quick Start + +[arabic] +. Get credentials from Twingate Admin Console +. Set environment variables: + +[source,bash] +---- +export TWINGATE_ACCESS_TOKEN="your-access-token" +export TWINGATE_REFRESH_TOKEN="your-refresh-token" +---- + +[arabic, start=3] +. Configure secrets: + +[source,bash] +---- +just configure-secrets +---- + +[arabic, start=4] +. Deploy: + +[source,bash] +---- +just deploy production +---- + +[arabic, start=5] +. Verify: + +[source,bash] +---- +just status +just health-check +---- + +=== Integration with ZeroTier + +Route Twingate traffic through ZeroTier overlay: - Deploy +zerotier-k8s-link first - Twingate connector automatically uses ZeroTier +mesh + +See: https://github.com/hyperpolymath/zerotier-k8s-link diff --git a/examples/basic-deployment.md b/examples/basic-deployment.md deleted file mode 100644 index dfc6322..0000000 --- a/examples/basic-deployment.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Twingate Connector Deployment Guide - -Deploy Twingate Connector to Kubernetes for zero-trust network access. - -## Prerequisites -- Kubernetes cluster -- Helm 3+ -- Twingate account with network created -- Access/refresh tokens from Twingate - -## Quick Start - -1. Get credentials from Twingate Admin Console -2. Set environment variables: -```bash -export TWINGATE_ACCESS_TOKEN="your-access-token" -export TWINGATE_REFRESH_TOKEN="your-refresh-token" -``` - -3. Configure secrets: -```bash -just configure-secrets -``` - -4. Deploy: -```bash -just deploy production -``` - -5. Verify: -```bash -just status -just health-check -``` - -## Integration with ZeroTier - -Route Twingate traffic through ZeroTier overlay: -- Deploy zerotier-k8s-link first -- Twingate connector automatically uses ZeroTier mesh - -See: https://github.com/hyperpolymath/zerotier-k8s-link diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..c1df621 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — twingate-helm-deploy (Developer) + +=== What is twingate-helm-deploy? + +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 505188a..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — twingate-helm-deploy (Developer) - -## What is twingate-helm-deploy? -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..f629afb --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — twingate-helm-deploy (User) + +=== What is twingate-helm-deploy? + +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 27dcb31..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — twingate-helm-deploy (User) - -## What is twingate-helm-deploy? -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