diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml
index d6aa766..ef57260 100644
--- a/.github/workflows/governance.yml
+++ b/.github/workflows/governance.yml
@@ -3,7 +3,7 @@
# in hyperpolymath/standards instead of carrying per-repo copies.
#
# Replaces the per-repo governance scaffolding removed in the same commit:
-# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml,
+# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml,
# security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml,
# workflow-linter.yml
#
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 43930be..acab4e0 100644
--- a/ABI-FFI-README.md
+++ b/ABI-FFI-README.adoc
@@ -1,18 +1,20 @@
+== CloudflareDnsTerraform ABI/FFI Documentation
-# CloudflareDnsTerraform 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/ │
@@ -42,13 +44,13 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
▼
┌─────────────────────────────────────────────┐
│ Any Language via C ABI │
-│ - Rust, ReScript, Julia, Python, etc. │
+│ - Rust, AffineScript, Julia, Python, etc. │
└─────────────────────────────────────────────┘
-```
+....
-## Directory Structure
+=== Directory Structure
-```
+....
cloudflare_dns_terraform/
├── src/
│ ├── abi/ # ABI definitions (Idris2)
@@ -74,17 +76,19 @@ cloudflare_dns_terraform/
│
└── bindings/ # Language-specific wrappers (optional)
├── rust/
- ├── rescript/
+ ├── affinescript/
└── 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/cloudflare_dns_terraform.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 "cloudflare_dns_terraform.h"
int main() {
@@ -236,16 +251,19 @@ int main() {
cloudflare_dns_terraform_free(handle);
return 0;
}
-```
+----
Compile with:
-```bash
+
+[source,bash]
+----
gcc -o example example.c -lcloudflare_dns_terraform -L./zig-out/lib
-```
+----
-### From Idris2
+==== From Idris2
-```idris
+[source,idris]
+----
import CloudflareDnsTerraform.ABI.Foreign
main : IO ()
@@ -258,11 +276,12 @@ main = do
free handle
putStrLn "Success"
-```
+----
-### From Rust
+==== From Rust
-```rust
+[source,rust]
+----
#[link(name = "cloudflare_dns_terraform")]
extern "C" {
fn cloudflare_dns_terraform_init() -> *mut std::ffi::c_void;
@@ -281,11 +300,12 @@ fn main() {
cloudflare_dns_terraform_free(handle);
}
}
-```
+----
-### From Julia
+==== From Julia
-```julia
+[source,julia]
+----
const libcloudflare_dns_terraform = "libcloudflare_dns_terraform"
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/cloudflare_dns_terraform.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/cloudflare_dns_terraform.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..b4112bd
--- /dev/null
+++ b/CHANGELOG.adoc
@@ -0,0 +1,73 @@
+== Changelog
+
+All notable changes to `+cloudflare-dns-terraform+` 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: add UX Justfile with doctor, tour, help-me, assail recipes
+* feat: deploy UX Manifesto infrastructure
+* feat: add CLADE.a2ml — clade taxonomy declaration
+* feat: add mirror.yml workflow for GitLab/Bitbucket mirroring
+* feat: add critical security workflows
+* feat: auto-detect and add new Cloudflare domains
+* feat: add all 24 Cloudflare domains to configuration
+* feat: optimize for FREE tier + deployment guides
+
+==== Fixed
+
+* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build
+drift) (#3)
+* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout +
+Comment-step gate) (#2)
+* fix(scorecard): enforce granular permissions and add fuzzing
+placeholder
+* fix(ci): Resolve workflow-linter self-matching and metadata issues
+* fix: RSR compliance — fix SPDX headers/typos, resolve placeholders,
+rewrite stale SCM
+* fix: remove duplicate SCM files from root
+
+==== Changed
+
+* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format)
+
+==== Documentation
+
+* docs: add TEST-NEEDS.md (CRG C)
+* docs: add TEST-NEEDS.md (CRG C)
+* docs: restore README.md lost in Floor Raise campaign
+* docs: add EXPLAINME.adoc — prove-it file backing README claims
+* docs: update SCM files with project information
+* docs: add SCM checkpoint files
+
+==== CI
+
+* ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks
+* ci: migrate CodeQL Action v3 → v4
+* ci: update SHA pins for codeql-action and trufflehog
+* ci: deploy missing standard workflows (10 added)
+
+=== 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 feb75e5..0000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,69 +0,0 @@
-
-
-# Changelog
-
-All notable changes to `cloudflare-dns-terraform` 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: add UX Justfile with doctor, tour, help-me, assail recipes
-- feat: deploy UX Manifesto infrastructure
-- feat: add CLADE.a2ml — clade taxonomy declaration
-- feat: add mirror.yml workflow for GitLab/Bitbucket mirroring
-- feat: add critical security workflows
-- feat: auto-detect and add new Cloudflare domains
-- feat: add all 24 Cloudflare domains to configuration
-- feat: optimize for FREE tier + deployment guides
-
-### Fixed
-
-- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#3)
-- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#2)
-- fix(scorecard): enforce granular permissions and add fuzzing placeholder
-- fix(ci): Resolve workflow-linter self-matching and metadata issues
-- fix: RSR compliance — fix SPDX headers/typos, resolve placeholders, rewrite stale SCM
-- fix: remove duplicate SCM files from root
-
-### Changed
-
-- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format)
-
-### Documentation
-
-- docs: add TEST-NEEDS.md (CRG C)
-- docs: add TEST-NEEDS.md (CRG C)
-- docs: restore README.md lost in Floor Raise campaign
-- docs: add EXPLAINME.adoc — prove-it file backing README claims
-- docs: update SCM files with project information
-- docs: add SCM checkpoint files
-
-### CI
-
-- ci: deploy dogfood-gate, fix hypatia-scan, add pre-commit hooks
-- ci: migrate CodeQL Action v3 → v4
-- ci: update SHA pins for codeql-action and trufflehog
-- ci: deploy missing standard workflows (10 added)
-
-## 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..33c1bb9
--- /dev/null
+++ b/CODE_OF_CONDUCT.adoc
@@ -0,0 +1,340 @@
+== Code of Conduct
+
+=== Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+cloudflare-dns-terraform a harassment-free experience for everyone,
+regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal
+appearance, race, caste, colour, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+We recognise that a thriving open source community requires
+*psychological safety* — an environment where people can contribute, ask
+questions, make mistakes, and learn without fear of ridicule or
+retaliation.
+
+'''''
+
+=== Our Standards
+
+==== Expected Behaviour
+
+The following behaviours contribute to a positive environment:
+
+*Communication* - Using welcoming and inclusive language - Being
+respectful of differing viewpoints and experiences - Giving and
+gracefully accepting constructive feedback - Assuming good intent while
+addressing impact - Communicating clearly and patiently, especially with
+newcomers
+
+*Collaboration* - Focusing on what is best for the community - Showing
+empathy and kindness toward other community members - Being
+collaborative rather than competitive - Mentoring and supporting less
+experienced contributors - Celebrating others’ contributions and
+successes
+
+*Professionalism* - Accepting responsibility and apologising to those
+affected by our mistakes - Learning from the experience and avoiding
+repetition - Respecting others’ time and attention - Staying on topic in
+project spaces - Following project guidelines and conventions
+
+*Accessibility* - Using plain language and avoiding unnecessary jargon -
+Providing alt text for images and transcripts for audio/video - Being
+patient with those using assistive technologies - Accommodating
+different communication styles and needs - Recognising that not everyone
+communicates the same way
+
+==== Unacceptable Behaviour
+
+The following behaviours are considered harassment and are unacceptable:
+
+*Harassment* - The use of sexualised language or imagery, and sexual
+attention or advances of any kind - Trolling, insulting or derogatory
+comments, and personal or political attacks - Public or private
+harassment - Deliberate intimidation, stalking, or following (online or
+in-person) - Unwelcome physical contact or simulated physical contact
+(e.g., emoji) - Sustained disruption of talks, events, or online
+discussions
+
+*Discrimination* - Discriminatory jokes and language - Posting or
+threatening to post others’ personally identifying information
+("`doxing`") - Advocating for, or encouraging, any of the above
+behaviour - Microaggressions — subtle, often unintentional,
+discriminatory comments or actions
+
+*Professional Misconduct* - Publishing others’ private information
+without explicit permission - Misrepresenting affiliation or
+contributions - Plagiarism or claiming credit for others’ work -
+Retaliating against anyone who reports a Code of Conduct violation -
+Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+==== Grey Areas
+
+Some situations require judgement. When uncertain:
+
+* *Intent vs Impact*: Good intentions do not excuse harmful impact.
+Focus on making things right.
+* *Power Dynamics*: Those with more power (maintainers, employers,
+experienced contributors) must be especially mindful of their impact.
+* *Cultural Differences*: What’s acceptable varies by culture. When in
+doubt, err on the side of caution and ask.
+* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch
+up, not down.
+
+'''''
+
+=== Scope
+
+This Code of Conduct applies within all community spaces, including:
+
+*Online Spaces* - Repository discussions, issues, and pull/merge
+requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing
+lists and forums - Social media when representing the project - Video
+calls and virtual meetings
+
+*In-Person Spaces* - Conferences, meetups, and events - Workshops and
+training sessions - Any gathering where you represent the project
+
+*Representation* This Code of Conduct also applies when an individual is
+officially representing the community in public spaces. Examples
+include:
+
+* Using an official project email address
+* Posting via an official social media account
+* Acting as an appointed representative at an event
+* Speaking on behalf of the project
+
+'''''
+
+=== Enforcement
+
+==== Reporting
+
+If you experience or witness unacceptable behaviour, or have any other
+concerns, please report it as soon as possible.
+
+*How to Report*
+
+[width="99%",cols="30%,33%,37%",options="header",]
+|===
+|Method |Details |Best For
+|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters
+
+|*Private Message* |Contact any maintainer directly |Quick questions,
+minor issues
+
+|*Anonymous Form* |[Link to form if available] |When you need anonymity
+|===
+
+*What to Include*
+
+* Your contact information (unless anonymous)
+* Names/usernames of those involved
+* Description of what happened
+* When and where it occurred
+* Any witnesses
+* Any supporting evidence (screenshots, links)
+* How you would like us to respond (if you have a preference)
+
+*What Happens Next*
+
+[arabic]
+. You will receive acknowledgment within *48 hours*
+. The maintainers will review the report
+. We may ask for additional information
+. We will determine appropriate action
+. We will inform you of the outcome (respecting others’ privacy)
+
+==== Confidentiality
+
+All reports will be handled with discretion:
+
+* Reporter identity is protected by default
+* Details are shared only with those who need to know
+* We will ask before naming you in any communication
+* Anonymous reports are accepted and investigated
+
+==== Conflicts of Interest
+
+If a maintainers member is involved in an incident:
+
+* They will recuse themselves from the process
+* Another maintainer or external party will handle the report
+* We will disclose any potential conflicts
+
+'''''
+
+=== Enforcement Guidelines
+
+The maintainers will follow these guidelines in determining
+consequences:
+
+==== 1. Correction
+
+*Community Impact*: Use of inappropriate language or other behaviour
+deemed unprofessional or unwelcome.
+
+*Consequence*: A private, written warning providing clarity around the
+nature of the violation and an explanation of why the behaviour was
+inappropriate. A public apology may be requested.
+
+*Duration*: Immediate
+
+==== 2. Warning
+
+*Community Impact*: A violation through a single incident or series of
+actions.
+
+*Consequence*: A warning with consequences for continued behaviour. No
+interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, for a specified period. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+*Duration*: 1-4 weeks
+
+==== 3. Temporary Ban
+
+*Community Impact*: A serious violation of community standards,
+including sustained inappropriate behaviour.
+
+*Consequence*: A temporary ban from any sort of interaction or public
+communication with the community for a specified period. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during
+this period. Violating these terms may lead to a permanent ban.
+
+*Duration*: 1-6 months
+
+==== 4. Permanent Ban
+
+*Community Impact*: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behaviour, harassment of an
+individual, or aggression toward or disparagement of classes of
+individuals.
+
+*Consequence*: A permanent ban from any sort of public interaction
+within the community.
+
+*Duration*: Permanent (with appeal rights after 12 months)
+
+==== Enforcement Across Perimeters
+
+For contributors with elevated access (Perimeter 2 or 1):
+
+[cols=",",options="header",]
+|===
+|Level |Additional Consequence
+|Correction |Noted in contributor record
+|Warning |Access privileges may be temporarily reduced
+|Temporary Ban |Access reduced to Perimeter 3 for ban duration
+|Permanent Ban |All access revoked
+|===
+
+'''''
+
+=== Appeals
+
+If you believe an enforcement decision was made in error:
+
+[arabic]
+. *Wait 7 days* after the decision (cooling-off period)
+. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original
+Report ID]`"
+. *Explain* why you believe the decision should be reconsidered
+. *Provide* any new information not previously available
+
+*Appeals Process*
+
+* Appeals are reviewed by a different maintainers member than the
+original
+* You will receive a response within 14 days
+* The appeals decision is final
+* You may only appeal once per incident
+
+*Grounds for Appeal*
+
+* Procedural errors in the original investigation
+* New evidence not previously available
+* Disproportionate response to the violation
+* Misunderstanding of facts
+
+'''''
+
+=== Supporting Those Who Report
+
+We are committed to supporting those who report violations:
+
+*We Will* - Believe and take all reports seriously - Respect your
+privacy and confidentiality preferences - Keep you informed of progress
+(if you wish) - Take steps to protect you from retaliation - Provide
+resources if you need support
+
+*We Will Not* - Require you to confront the person directly - Dismiss
+reports without investigation - Reveal your identity without consent -
+Tolerate retaliation against reporters - Rush you to make decisions
+
+'''''
+
+=== Prevention
+
+Beyond enforcement, we actively work to prevent issues:
+
+*Onboarding* - All contributors are expected to read this Code of
+Conduct - Perimeter 2 applicants must confirm they’ve read and
+understood it - Maintainers receive additional training on enforcement
+
+*Culture* - We model the behaviour we expect - We intervene early when
+we see potential issues - We thank people for positive contributions -
+We create opportunities for diverse voices
+
+*Review* - This Code of Conduct is reviewed annually - Community
+feedback is welcomed - Changes are communicated clearly
+
+'''''
+
+=== Acknowledgments
+
+This Code of Conduct is adapted from:
+
+* https://www.contributor-covenant.org/[Contributor Covenant], version
+2.1
+* https://www.djangoproject.com/conduct/[Django Code of Conduct]
+* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of
+Conduct]
+* https://www.python.org/psf/conduct/[Python Community Code of Conduct]
+
+We thank these communities for their leadership in creating welcoming
+spaces.
+
+'''''
+
+=== Questions?
+
+If you have questions about this Code of Conduct:
+
+* Open a
+https://github.com/hyperpolymath/cloudflare-dns-terraform/discussions[Discussion]
+(for general questions)
+* Email j.d.a.jewell@open.ac.uk (for private questions)
+* Contact any maintainer directly
+
+'''''
+
+=== Summary
+
+*Be kind. Be respectful. Be collaborative.*
+
+We’re all here because we care about this project. Let’s make it a place
+where everyone can do their best work.
+
+'''''
+
+Last updated: 2025 · Based on Contributor Covenant 2.1
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index b63ac49..0000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,307 +0,0 @@
-# Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in cloudflare-dns-terraform a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
-We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation.
-
----
-
-## Our Standards
-
-### Expected Behaviour
-
-The following behaviours contribute to a positive environment:
-
-**Communication**
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Giving and gracefully accepting constructive feedback
-- Assuming good intent while addressing impact
-- Communicating clearly and patiently, especially with newcomers
-
-**Collaboration**
-- Focusing on what is best for the community
-- Showing empathy and kindness toward other community members
-- Being collaborative rather than competitive
-- Mentoring and supporting less experienced contributors
-- Celebrating others' contributions and successes
-
-**Professionalism**
-- Accepting responsibility and apologising to those affected by our mistakes
-- Learning from the experience and avoiding repetition
-- Respecting others' time and attention
-- Staying on topic in project spaces
-- Following project guidelines and conventions
-
-**Accessibility**
-- Using plain language and avoiding unnecessary jargon
-- Providing alt text for images and transcripts for audio/video
-- Being patient with those using assistive technologies
-- Accommodating different communication styles and needs
-- Recognising that not everyone communicates the same way
-
-### Unacceptable Behaviour
-
-The following behaviours are considered harassment and are unacceptable:
-
-**Harassment**
-- The use of sexualised language or imagery, and sexual attention or advances of any kind
-- Trolling, insulting or derogatory comments, and personal or political attacks
-- Public or private harassment
-- Deliberate intimidation, stalking, or following (online or in-person)
-- Unwelcome physical contact or simulated physical contact (e.g., emoji)
-- Sustained disruption of talks, events, or online discussions
-
-**Discrimination**
-- Discriminatory jokes and language
-- Posting or threatening to post others' personally identifying information ("doxing")
-- Advocating for, or encouraging, any of the above behaviour
-- Microaggressions — subtle, often unintentional, discriminatory comments or actions
-
-**Professional Misconduct**
-- Publishing others' private information without explicit permission
-- Misrepresenting affiliation or contributions
-- Plagiarism or claiming credit for others' work
-- Retaliating against anyone who reports a Code of Conduct violation
-- Other conduct which could reasonably be considered inappropriate in a professional setting
-
-### Grey Areas
-
-Some situations require judgement. When uncertain:
-
-- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right.
-- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact.
-- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask.
-- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down.
-
----
-
-## Scope
-
-This Code of Conduct applies within all community spaces, including:
-
-**Online Spaces**
-- Repository discussions, issues, and pull/merge requests
-- Project chat channels (Matrix, Discord, Slack, IRC)
-- Mailing lists and forums
-- Social media when representing the project
-- Video calls and virtual meetings
-
-**In-Person Spaces**
-- Conferences, meetups, and events
-- Workshops and training sessions
-- Any gathering where you represent the project
-
-**Representation**
-This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include:
-
-- Using an official project email address
-- Posting via an official social media account
-- Acting as an appointed representative at an event
-- Speaking on behalf of the project
-
----
-
-## Enforcement
-
-### Reporting
-
-If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible.
-
-**How to Report**
-
-| Method | Details | Best For |
-|--------|---------|----------|
-| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters |
-| **Private Message** | Contact any maintainer directly | Quick questions, minor issues |
-| **Anonymous Form** | [Link to form if available] | When you need anonymity |
-
-**What to Include**
-
-- Your contact information (unless anonymous)
-- Names/usernames of those involved
-- Description of what happened
-- When and where it occurred
-- Any witnesses
-- Any supporting evidence (screenshots, links)
-- How you would like us to respond (if you have a preference)
-
-**What Happens Next**
-
-1. You will receive acknowledgment within **48 hours**
-2. The maintainers will review the report
-3. We may ask for additional information
-4. We will determine appropriate action
-5. We will inform you of the outcome (respecting others' privacy)
-
-### Confidentiality
-
-All reports will be handled with discretion:
-
-- Reporter identity is protected by default
-- Details are shared only with those who need to know
-- We will ask before naming you in any communication
-- Anonymous reports are accepted and investigated
-
-### Conflicts of Interest
-
-If a maintainers member is involved in an incident:
-
-- They will recuse themselves from the process
-- Another maintainer or external party will handle the report
-- We will disclose any potential conflicts
-
----
-
-## Enforcement Guidelines
-
-The maintainers will follow these guidelines in determining consequences:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome.
-
-**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested.
-
-**Duration**: Immediate
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-**Duration**: 1-4 weeks
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-**Duration**: 1-6 months
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the community.
-
-**Duration**: Permanent (with appeal rights after 12 months)
-
-### Enforcement Across Perimeters
-
-For contributors with elevated access (Perimeter 2 or 1):
-
-| Level | Additional Consequence |
-|-------|----------------------|
-| Correction | Noted in contributor record |
-| Warning | Access privileges may be temporarily reduced |
-| Temporary Ban | Access reduced to Perimeter 3 for ban duration |
-| Permanent Ban | All access revoked |
-
----
-
-## Appeals
-
-If you believe an enforcement decision was made in error:
-
-1. **Wait 7 days** after the decision (cooling-off period)
-2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]"
-3. **Explain** why you believe the decision should be reconsidered
-4. **Provide** any new information not previously available
-
-**Appeals Process**
-
-- Appeals are reviewed by a different maintainers member than the original
-- You will receive a response within 14 days
-- The appeals decision is final
-- You may only appeal once per incident
-
-**Grounds for Appeal**
-
-- Procedural errors in the original investigation
-- New evidence not previously available
-- Disproportionate response to the violation
-- Misunderstanding of facts
-
----
-
-## Supporting Those Who Report
-
-We are committed to supporting those who report violations:
-
-**We Will**
-- Believe and take all reports seriously
-- Respect your privacy and confidentiality preferences
-- Keep you informed of progress (if you wish)
-- Take steps to protect you from retaliation
-- Provide resources if you need support
-
-**We Will Not**
-- Require you to confront the person directly
-- Dismiss reports without investigation
-- Reveal your identity without consent
-- Tolerate retaliation against reporters
-- Rush you to make decisions
-
----
-
-## Prevention
-
-Beyond enforcement, we actively work to prevent issues:
-
-**Onboarding**
-- All contributors are expected to read this Code of Conduct
-- Perimeter 2 applicants must confirm they've read and understood it
-- Maintainers receive additional training on enforcement
-
-**Culture**
-- We model the behaviour we expect
-- We intervene early when we see potential issues
-- We thank people for positive contributions
-- We create opportunities for diverse voices
-
-**Review**
-- This Code of Conduct is reviewed annually
-- Community feedback is welcomed
-- Changes are communicated clearly
-
----
-
-## Acknowledgments
-
-This Code of Conduct is adapted from:
-
-- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1
-- [Django Code of Conduct](https://www.djangoproject.com/conduct/)
-- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct)
-- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)
-
-We thank these communities for their leadership in creating welcoming spaces.
-
----
-
-## Questions?
-
-If you have questions about this Code of Conduct:
-
-- Open a [Discussion](https://github.com/hyperpolymath/cloudflare-dns-terraform/discussions) (for general questions)
-- Email j.d.a.jewell@open.ac.uk (for private questions)
-- Contact any maintainer directly
-
----
-
-## Summary
-
-**Be kind. Be respectful. Be collaborative.**
-
-We're all here because we care about this project. Let's make it a place where everyone can do their best work.
-
----
-
-Last updated: 2025 · Based on Contributor Covenant 2.1
diff --git a/CONSENT-CAPABILITY-GUIDE.md b/CONSENT-CAPABILITY-GUIDE.adoc
similarity index 67%
rename from CONSENT-CAPABILITY-GUIDE.md
rename to CONSENT-CAPABILITY-GUIDE.adoc
index 460e8ee..20b0b64 100644
--- a/CONSENT-CAPABILITY-GUIDE.md
+++ b/CONSENT-CAPABILITY-GUIDE.adoc
@@ -1,12 +1,18 @@
-# Consent-Aware HTTP & Capability Gateway Implementation Guide
+== Consent-Aware HTTP & Capability Gateway Implementation Guide
-## Overview
+=== Overview
-Both `consent-aware-http` and `http-capability-gateway` are realistic Cloudflare Worker prefilters, but for the NUJ WordPress/Verpex sites they should be treated as optional edge helpers rather than the only enforcement point. The canonical decision should live at origin (Varnish/OpenLiteSpeed/WordPress MU-plugin), with Cloudflare rejecting obvious failures earlier when that extra layer is worth the request budget.
+Both `+consent-aware-http+` and `+http-capability-gateway+` are
+realistic Cloudflare Worker prefilters, but for the NUJ WordPress/Verpex
+sites they should be treated as optional edge helpers rather than the
+only enforcement point. The canonical decision should live at origin
+(Varnish/OpenLiteSpeed/WordPress MU-plugin), with Cloudflare rejecting
+obvious failures earlier when that extra layer is worth the request
+budget.
-## Architecture
+=== Architecture
-```
+....
User Request
↓
Cloudflare DNS/TLS/WAF
@@ -18,22 +24,26 @@ Varnish / OpenLiteSpeed fast-fail rules
WordPress MU-plugin origin governance (canonical)
↓
Response (with audit headers and policy links)
-```
+....
----
+'''''
-## 1. Consent-Aware HTTP
+=== 1. Consent-Aware HTTP
-### What It Does:
-- Blocks requests to resources that require specific consent
-- Returns 403 with required consent levels if not granted
-- Enforces GDPR/privacy compliance at HTTP layer
-- Integrates with WokeLang's `only if okay` philosophy
+==== What It Does:
-For the NUJ sites, use this at the edge only if the origin already enforces the same policy.
+* Blocks requests to resources that require specific consent
+* Returns 403 with required consent levels if not granted
+* Enforces GDPR/privacy compliance at HTTP layer
+* Integrates with WokeLang’s `+only if okay+` philosophy
-### Use Cases:
-```javascript
+For the NUJ sites, use this at the edge only if the origin already
+enforces the same policy.
+
+==== Use Cases:
+
+[source,javascript]
+----
// Analytics API - requires analytics consent
GET /api/analytics/track
→ 403 if user hasn't consented to analytics
@@ -45,12 +55,14 @@ GET /api/personalize/recommendations
// Essential resources - always allowed
GET /api/content
→ 200 (essential, no consent needed)
-```
+----
-### Setting User Consent:
+==== Setting User Consent:
-**Frontend JavaScript:**
-```javascript
+*Frontend JavaScript:*
+
+[source,javascript]
+----
// User accepts consent via UI
function setConsent(levels) {
const consent = {
@@ -67,10 +79,12 @@ function setConsent(levels) {
// Refresh page to apply new consent
location.reload();
}
-```
+----
+
+*Consent UI Example:*
-**Consent UI Example:**
-```html
+[source,html]
+----
Cookie Consent
Choose what data you're comfortable sharing:
@@ -93,31 +107,35 @@ function setConsent(levels) {
-```
+----
-### Deployment:
+==== Deployment:
-```bash
+[source,bash]
+----
cd workers/
wrangler deploy consent-aware-http.js --name consent-gate
wrangler route add wokelang.org/* consent-gate
-```
+----
----
+'''''
-## 2. HTTP Capability Gateway
+=== 2. HTTP Capability Gateway
-### What It Does:
-- Enforces capability-based security at HTTP layer
-- Prevents privilege escalation attacks
-- Implements WokeLang's capability model for web APIs
-- Supports fine-grained access control
+==== What It Does:
-For the NUJ sites, this should mirror the origin capability gate rather than replace it.
+* Enforces capability-based security at HTTP layer
+* Prevents privilege escalation attacks
+* Implements WokeLang’s capability model for web APIs
+* Supports fine-grained access control
-### Use Cases:
+For the NUJ sites, this should mirror the origin capability gate rather
+than replace it.
-```javascript
+==== Use Cases:
+
+[source,javascript]
+----
// Generate capability token (backend)
const token = generateCapability({
capabilities: ['file.read', 'user.read'],
@@ -140,11 +158,12 @@ fetch('/api/files/document.pdf', {
}
})
→ 403 (missing file.delete capability)
-```
+----
-### Capability Token Format:
+==== Capability Token Format:
-```json
+[source,json]
+----
{
"capabilities": ["file.read", "user.read"],
"iat": 1706745600,
@@ -152,12 +171,14 @@ fetch('/api/files/document.pdf', {
"issuer": "wokelang-gateway",
"subject": "user-123"
}
-```
+----
+
+==== Backend Integration:
-### Backend Integration:
+*Generate capability token (Node.js/Deno):*
-**Generate capability token (Node.js/Deno):**
-```javascript
+[source,javascript]
+----
import jwt from 'jsonwebtoken';
function generateCapabilityToken(userId, capabilities, expiresIn = '1h') {
@@ -177,22 +198,24 @@ const token = generateCapabilityToken('user-123', [
'file.write',
'user.read'
]);
-```
+----
-### Deployment:
+==== Deployment:
-```bash
+[source,bash]
+----
wrangler deploy http-capability-gateway.js --name capability-gate
wrangler route add wokelang.org/api/* capability-gate
-```
+----
----
+'''''
-## 3. Combined Deployment (Consent + Capability)
+=== 3. Combined Deployment (Consent + Capability)
-You can chain both workers for early rejection, but keep the origin as the source of truth:
+You can chain both workers for early rejection, but keep the origin as
+the source of truth:
-```
+....
Request
↓
1. Consent Gate (checks consent cookie)
@@ -200,11 +223,12 @@ Request
2. Capability Gate (checks capability token)
↓
Origin
-```
+....
-**Terraform Configuration:**
+*Terraform Configuration:*
-```hcl
+[source,hcl]
+----
# In main.tf
resource "cloudflare_worker_route" "consent_gate" {
for_each = local.domains
@@ -221,16 +245,18 @@ resource "cloudflare_worker_route" "capability_gate" {
pattern = "${each.value.domain}/api/*"
script_name = "http-capability-gateway"
}
-```
+----
+
+'''''
----
+=== 4. Integration with WokeLang
-## 4. Integration with WokeLang
+These workers are *perfect* for WokeLang-powered sites:
-These workers are **perfect** for WokeLang-powered sites:
+==== WokeLang Backend:
-### WokeLang Backend:
-```woke
+[source,woke]
+----
// WokeLang API endpoint
to handleRequest(request: HttpRequest) {
// Capability already verified by gateway
@@ -245,10 +271,12 @@ to handleRequest(request: HttpRequest) {
return error("Capability required")
}
}
-```
+----
-### Frontend (ReScript):
-```rescript
+==== Frontend (AffineScript):
+
+[source,affinescript]
+----
// consent-ui.res
@react.component
let make = () => {
@@ -272,38 +300,48 @@ let make = () => {
}
-```
+----
+
+'''''
----
+=== 5. Real-World Example: wokelang.org
-## 5. Real-World Example: wokelang.org
+==== Setup:
-### Setup:
+[arabic]
+. *Deploy Workers:*
-1. **Deploy Workers:**
-```bash
+[source,bash]
+----
cd /var$REPOS_DIR/cloudflare-dns-terraform/workers
wrangler deploy consent-aware-http.js
wrangler deploy http-capability-gateway.js
-```
+----
-2. **Configure Routes:**
-```bash
+[arabic, start=2]
+. *Configure Routes:*
+
+[source,bash]
+----
# Consent gate on all pages
wrangler route add "wokelang.org/*" consent-aware-http
# Capability gate on APIs
wrangler route add "wokelang.org/api/*" http-capability-gateway
-```
+----
+
+[arabic, start=3]
+. *Update Terraform:*
-3. **Update Terraform:**
-```bash
+[source,bash]
+----
terraform apply # Adds routes automatically
-```
+----
-### Testing:
+==== Testing:
-```bash
+[source,bash]
+----
# Test consent gate
curl -I https://wokelang.org/api/analytics
# → 403 Consent Required (if no consent cookie)
@@ -320,15 +358,16 @@ curl https://wokelang.org/api/files/test.txt
curl -H "X-Capability-Token: eyJ..." \
https://wokelang.org/api/files/test.txt
# → 200 OK (if token has file.read)
-```
+----
----
+'''''
-## 6. Advanced Features
+=== 6. Advanced Features
-### A. Capability Delegation
+==== A. Capability Delegation
-```javascript
+[source,javascript]
+----
// Parent capability can create child capabilities
const parentToken = generateCapability({
capabilities: ['file.read', 'file.write'],
@@ -340,22 +379,24 @@ const childToken = delegateCapability(parentToken, {
capabilities: ['file.read'], // Subset only
expiresIn: 600 // Shorter lifetime
});
-```
+----
-### B. Consent Granularity
+==== B. Consent Granularity
-```javascript
+[source,javascript]
+----
// Per-resource consent
const RESOURCE_CONSENT = {
'/api/analytics/pageviews': ['analytics'],
'/api/analytics/heatmaps': ['analytics', 'functional'],
'/api/ads/targeting': ['marketing', 'personalization'],
}
-```
+----
-### C. Audit Logging
+==== C. Audit Logging
-```javascript
+[source,javascript]
+----
// Log all capability usage
async function auditCapabilityUse(capability, user, resource) {
await fetch('https://logs.wokelang.org/audit', {
@@ -368,41 +409,45 @@ async function auditCapabilityUse(capability, user, resource) {
})
});
}
-```
+----
----
+'''''
-## 7. Summary
+=== 7. Summary
-### Is it realistic? **ABSOLUTELY YES!**
+==== Is it realistic? *ABSOLUTELY YES!*
-✅ **Consent-Aware HTTP:**
-- Simple to implement (cookie-based)
-- GDPR/privacy compliant
-- Works with Cloudflare Workers
-- Integrates with any frontend
+✅ *Consent-Aware HTTP:* - Simple to implement (cookie-based) -
+GDPR/privacy compliant - Works with Cloudflare Workers - Integrates with
+any frontend
-✅ **HTTP Capability Gateway:**
-- Proven pattern (used by Google, Cloudflare, etc.)
-- More secure than role-based access control
-- Perfect for microservices
-- Prevents privilege escalation
+✅ *HTTP Capability Gateway:* - Proven pattern (used by Google,
+Cloudflare, etc.) - More secure than role-based access control - Perfect
+for microservices - Prevents privilege escalation
-### Next Steps:
+==== Next Steps:
-1. **Test workers locally:**
-```bash
+[arabic]
+. *Test workers locally:*
+
+[source,bash]
+----
wrangler dev consent-aware-http.js
-```
+----
+
+[arabic, start=2]
+. *Deploy to wokelang.org:*
-2. **Deploy to wokelang.org:**
-```bash
+[source,bash]
+----
wrangler deploy
-```
+----
+
+[arabic, start=3]
+. *Integrate with WokeLang SSG:*
-3. **Integrate with WokeLang SSG:**
-- Add consent UI to site footer
-- Generate capability tokens from WokeLang backend
-- Add audit logging
+* Add consent UI to site footer
+* Generate capability tokens from WokeLang backend
+* Add audit logging
-**Your sites will have world-class security AND privacy!** 🔒🚀
+*Your sites will have world-class security AND privacy!* 🔒🚀
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
new file mode 100644
index 0000000..47edcaf
--- /dev/null
+++ b/CONTRIBUTING.adoc
@@ -0,0 +1,110 @@
+== Clone the repository
+
+git clone https://github.com/hyperpolymath/cloudflare-dns-terraform.git
+cd cloudflare-dns-terraform
+
+== Using Guix (recommended for reproducibility)
+
+guix develop
+
+== Or using toolbox/distrobox
+
+toolbox create cloudflare-dns-terraform-dev toolbox enter
+cloudflare-dns-terraform-dev # Install dependencies manually
+
+== Verify setup
+
+just check # or: cargo check / mix compile / etc. just test # Run test
+suite
+
+....
+
+### Repository Structure
+....
+
+cloudflare-dns-terraform/ ├── 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.guix # Guix 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/cloudflare-dns-terraform/labels/good%20first%20issue) — Simple Perimeter 3 tasks
+- [`help wanted`](https://github.com/hyperpolymath/cloudflare-dns-terraform/labels/help%20wanted) — Community help needed
+- [`documentation`](https://github.com/hyperpolymath/cloudflare-dns-terraform/labels/documentation) — Docs improvements
+- [`perimeter-3`](https://github.com/hyperpolymath/cloudflare-dns-terraform/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 ea0e376..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,116 +0,0 @@
-# Clone the repository
-git clone https://github.com/hyperpolymath/cloudflare-dns-terraform.git
-cd cloudflare-dns-terraform
-
-# Using Nix (recommended for reproducibility)
-nix develop
-
-# Or using toolbox/distrobox
-toolbox create cloudflare-dns-terraform-dev
-toolbox enter cloudflare-dns-terraform-dev
-# Install dependencies manually
-
-# Verify setup
-just check # or: cargo check / mix compile / etc.
-just test # Run test suite
-```
-
-### Repository Structure
-```
-cloudflare-dns-terraform/
-├── 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/cloudflare-dns-terraform/labels/good%20first%20issue) — Simple Perimeter 3 tasks
-- [`help wanted`](https://github.com/hyperpolymath/cloudflare-dns-terraform/labels/help%20wanted) — Community help needed
-- [`documentation`](https://github.com/hyperpolymath/cloudflare-dns-terraform/labels/documentation) — Docs improvements
-- [`perimeter-3`](https://github.com/hyperpolymath/cloudflare-dns-terraform/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/DEPLOY-ALL-SITES.adoc b/DEPLOY-ALL-SITES.adoc
new file mode 100644
index 0000000..ad472e2
--- /dev/null
+++ b/DEPLOY-ALL-SITES.adoc
@@ -0,0 +1,358 @@
+== Deploy to ALL Your Websites - Complete Guide
+
+=== Goal: Set up security + DNS for ALL your domains
+
+This will: - ✅ Add security headers to ALL domains (FREE) - ✅
+Standardize DNS records across ALL domains - ✅ Optionally add
+Cloudflare consent/capability prefilters - ✅ Keep the DNS-only baseline
+at zero cost (Transform Rules remain FREE) - ✅ Optionally add
+Cloudflare Web3/IPFS hostnames where direct IPFS access is needed
+
+'''''
+
+=== Step 1: Get All Your Domains
+
+==== Option A: Via Cloudflare Dashboard
+
+[arabic]
+. Go to: https://dash.cloudflare.com
+. You’ll see a list of all domains
+. Copy the list to a text file
+
+==== Option B: Via API
+
+[source,bash]
+----
+export CLOUDFLARE_API_TOKEN='your-api-token-here'
+
+curl -s "https://api.cloudflare.com/client/v4/zones?per_page=100" \
+ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | \
+ python3 -c "import sys,json;[print(z['name']) for z in json.load(sys.stdin)['result']]"
+----
+
+==== Option C: Automated Script
+
+[source,bash]
+----
+./generate-domains-csv.sh
+----
+
+'''''
+
+=== Step 2: Edit domains.csv
+
+Open `+domains.csv+` in Excel or any spreadsheet app.
+
+==== Quick Template (copy this for each domain):
+
+[source,csv]
+----
+domain,github_user,github_repo,tunnel_id,mx_primary,mx_secondary,admin_email,ssh_fp_sha256,ssh_fp_sha256_backup,dkim_selector,tlsa_cert_hash,enable_mail,enable_tunnel,enable_ssh,enable_github_pages,enable_consent_gate,enable_capability_gate,enable_ipfs_gateway,ipfs_dnslink,pages_project
+example.com,hyperpolymath,,,,,,,,default,,false,false,false,false,false,false,false,,
+----
+
+==== Fill in these columns:
+
+[width="100%",cols="38%,31%,31%",options="header",]
+|===
+|Column |Value |Notes
+|`+domain+` |Your domain name |e.g., `+wokelang.org+`
+
+|`+github_user+` |`+hyperpolymath+` |Your GitHub username
+
+|`+github_repo+` |Repo name |If using GitHub Pages
+
+|`+admin_email+` |`+j.d.a.jewell@open.ac.uk+` |For security contacts
+
+|`+enable_github_pages+` |`+true+` or `+false+` |If using GitHub Pages
+
+|`+enable_consent_gate+` |`+false+` |Optional edge prefilter; keep
+origin enforcement as source of truth
+
+|`+enable_capability_gate+` |`+false+` |Optional `+/api/*+` prefilter;
+keep origin enforcement as source of truth
+
+|`+enable_ipfs_gateway+` |`+false+` |Requires Cloudflare Web3 gateway
+subscription
+
+|`+ipfs_dnslink+` |`+/ipns/onboarding.ipfs.cloudflare.com+` |Initial
+value before your publish script updates it
+
+|`+pages_project+` |Project name |If using Cloudflare Pages
+|===
+
+==== Leave blank:
+
+* `+tunnel_id+` - Unless using Cloudflare Tunnel
+* `+mx_*+` - Unless using email
+* `+ssh_*+` - Unless using SSH
+* `+dkim_*+` - Unless using email
+
+'''''
+
+=== Step 3: Preview Changes (DRY RUN)
+
+[source,bash]
+----
+cd /var$REPOS_DIR/cloudflare-dns-terraform
+
+# Set credentials
+export CLOUDFLARE_API_TOKEN='your-api-token-here'
+
+# Or use terraform.tfvars
+cp terraform.tfvars.example terraform.tfvars
+nano terraform.tfvars
+
+# Initialize Terraform
+terraform init
+
+# Preview what will be created (NO CHANGES YET)
+terraform plan
+----
+
+*Review the output carefully!*
+
+You should see: - `+++` = Will create (new records) - `+~+` = Will
+modify (existing records) - `+-+` = Will delete (old records)
+
+'''''
+
+=== Step 4: Deploy to ALL Domains
+
+[source,bash]
+----
+# Apply changes to ALL domains
+terraform apply
+
+# Type 'yes' when prompted
+----
+
+This will: 1. Add security headers to ALL domains (via Transform Rules -
+FREE) 2. Create standard DNS records (www, cdn, static, assets, etc.) 3.
+Add CAA records with critical flag (128) 4. Set up Cloudflare Pages
+domains (if specified)
+
+'''''
+
+=== Step 5: Verify Security Headers
+
+Test any domain:
+
+[source,bash]
+----
+# Check headers
+curl -I https://your-domain.com
+
+# Should see:
+# Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+# Content-Security-Policy: ...
+# X-Frame-Options: DENY
+# etc.
+----
+
+Online tests: - https://securityheaders.com/?q=https://your-domain.com -
+https://www.ssllabs.com/ssltest/analyze.html?d=your-domain.com
+
+'''''
+
+=== Step 6: Deploy Workers (OPTIONAL - Only if Needed)
+
+*Skip this if you don’t need consent/capability gates* (saves worker
+requests)
+
+==== If you want consent gates:
+
+[arabic]
+. Edit `+domains.csv+` and set `+enable_consent_gate=true+` for domains
+that need it
+. Deploy worker:
+
+[source,bash]
+----
+cd workers/
+wrangler deploy consent-aware-http.js
+----
+
+[arabic, start=3]
+. Apply Terraform:
+
+[source,bash]
+----
+terraform apply
+----
+
+==== If you want capability gates:
+
+[arabic]
+. Edit `+domains.csv+` and set `+enable_capability_gate=true+` for
+domains with APIs
+. Deploy worker:
+
+[source,bash]
+----
+wrangler deploy http-capability-gateway.js
+----
+
+[arabic, start=3]
+. Apply Terraform:
+
+[source,bash]
+----
+terraform apply
+----
+
+'''''
+
+=== Cost Breakdown (All Domains):
+
+==== Guaranteed FREE:
+
+* ✅ Transform Rules (security headers) - *FREE unlimited*
+* ✅ DNS records - *FREE unlimited* (Cloudflare DNS)
+* ✅ Cloudflare Pages - *FREE* (500 builds/month)
+
+==== Potentially FREE (if under limits):
+
+* ⚠️ Consent gates - *FREE* if < 100k requests/day total across ALL
+domains
+* ⚠️ Capability gates - *FREE* if < 100k requests/day total across ALL
+domains
+
+==== Example with 10 domains:
+
+....
+Domain 1: 5,000 requests/day (mostly static → Transform Rules = FREE)
+Domain 2: 3,000 requests/day (mostly static → Transform Rules = FREE)
+Domain 3: 2,000 requests/day (mostly static → Transform Rules = FREE)
+... (7 more domains)
+Total: 30,000 requests/day
+
+Workers only needed for:
+- Analytics endpoints: ~1,000 requests/day (consent gate)
+- API endpoints: ~500 requests/day (capability gate)
+
+Total worker requests: ~1,500/day = 45,000/month
+FREE tier: 3,000,000/month
+
+Cost: £0/month ✅
+....
+
+'''''
+
+=== What Gets Applied to Each Domain:
+
+==== Always (FREE via Transform Rules):
+
+* Security headers (HSTS, CSP, X-Frame-Options, etc.)
+* CAA records (Let’s Encrypt + DigiCert, flags=128)
+* SPF record
+* DMARC record
+
+==== Standard DNS (FREE):
+
+* `+www+` → CNAME to root (proxied)
+* `+static+` → CNAME to root (proxied)
+* `+assets+` → CNAME to root (proxied)
+* `+cdn+` → CNAME to root (proxied)
+* `+api+` → CNAME to root (proxied)
+* `+status+` → CNAME to root (proxied)
+* `+ci+` → CNAME to root (proxied)
+* Plus 10+ more standard subdomains
+
+==== Optional (if enabled):
+
+* GitHub Pages CNAME (if `+enable_github_pages=true+`)
+* Cloudflare Pages custom domain (if `+pages_project+` set)
+* MX/DKIM records (if `+enable_mail=true+`)
+* SSH fingerprints (if `+enable_ssh=true+`)
+* Cloudflare Tunnel (if `+enable_tunnel=true+`)
+* Consent gate (if `+enable_consent_gate=true+`)
+* Capability gate (if `+enable_capability_gate=true+`)
+
+'''''
+
+=== Rollback Plan
+
+If something goes wrong:
+
+[source,bash]
+----
+# See what Terraform created
+terraform show
+
+# Destroy specific domain
+terraform destroy -target='cloudflare_record.www["problem-domain.com"]'
+
+# Destroy everything (CAREFUL!)
+terraform destroy
+----
+
+*Note:* Terraform tracks state in `+terraform.tfstate+` - don’t delete
+this file!
+
+'''''
+
+=== Monitoring
+
+==== Set up alerts to avoid surprise charges:
+
+[arabic]
+. Go to: https://dash.cloudflare.com/[account]/notifications
+. Create alert: "`Workers Requests Threshold`"
+. Set threshold: 80,000 requests/day (80% of free tier)
+
+==== Check usage:
+
+[source,bash]
+----
+# Via dashboard
+https://dash.cloudflare.com/[account]/workers/overview
+
+# Via CLI
+wrangler tail consent-aware-http --status
+----
+
+'''''
+
+=== Maintenance
+
+==== Adding a new domain:
+
+[arabic]
+. Add row to `+domains.csv+`
+. Run `+terraform apply+`
+. Done!
+
+==== Removing a domain:
+
+[arabic]
+. Delete row from `+domains.csv+`
+. Run `+terraform apply+`
+. Terraform will remove all DNS records
+
+==== Updating all domains:
+
+[arabic]
+. Edit `+domains.csv+` (change columns for all domains)
+. Run `+terraform apply+`
+. Changes apply to all domains instantly
+
+'''''
+
+=== Summary
+
+*This will set up world-class security across ALL your websites:*
+
+✅ Security headers (HSTS, CSP, etc.) ✅ CAA with critical flag (128) ✅
+Standard DNS structure ✅ Cloudflare Pages support ✅ GitHub Pages
+support ✅ Optional consent gates ✅ Optional capability gates ✅ *All
+FREE* (unless you exceed 100k requests/day)
+
+*Total cost: £0/month for typical usage* 🎉
+
+Ready to deploy? Run:
+
+[source,bash]
+----
+terraform apply
+----
diff --git a/DEPLOY-ALL-SITES.md b/DEPLOY-ALL-SITES.md
deleted file mode 100644
index cd47dd8..0000000
--- a/DEPLOY-ALL-SITES.md
+++ /dev/null
@@ -1,310 +0,0 @@
-# Deploy to ALL Your Websites - Complete Guide
-
-## Goal: Set up security + DNS for ALL your domains
-
-This will:
-- ✅ Add security headers to ALL domains (FREE)
-- ✅ Standardize DNS records across ALL domains
-- ✅ Optionally add Cloudflare consent/capability prefilters
-- ✅ Keep the DNS-only baseline at zero cost (Transform Rules remain FREE)
-- ✅ Optionally add Cloudflare Web3/IPFS hostnames where direct IPFS access is needed
-
----
-
-## Step 1: Get All Your Domains
-
-### Option A: Via Cloudflare Dashboard
-1. Go to: https://dash.cloudflare.com
-2. You'll see a list of all domains
-3. Copy the list to a text file
-
-### Option B: Via API
-```bash
-export CLOUDFLARE_API_TOKEN='your-api-token-here'
-
-curl -s "https://api.cloudflare.com/client/v4/zones?per_page=100" \
- -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | \
- python3 -c "import sys,json;[print(z['name']) for z in json.load(sys.stdin)['result']]"
-```
-
-### Option C: Automated Script
-```bash
-./generate-domains-csv.sh
-```
-
----
-
-## Step 2: Edit domains.csv
-
-Open `domains.csv` in Excel or any spreadsheet app.
-
-### Quick Template (copy this for each domain):
-
-```csv
-domain,github_user,github_repo,tunnel_id,mx_primary,mx_secondary,admin_email,ssh_fp_sha256,ssh_fp_sha256_backup,dkim_selector,tlsa_cert_hash,enable_mail,enable_tunnel,enable_ssh,enable_github_pages,enable_consent_gate,enable_capability_gate,enable_ipfs_gateway,ipfs_dnslink,pages_project
-example.com,hyperpolymath,,,,,,,,default,,false,false,false,false,false,false,false,,
-```
-
-### Fill in these columns:
-
-| Column | Value | Notes |
-|--------|-------|-------|
-| `domain` | Your domain name | e.g., `wokelang.org` |
-| `github_user` | `hyperpolymath` | Your GitHub username |
-| `github_repo` | Repo name | If using GitHub Pages |
-| `admin_email` | `j.d.a.jewell@open.ac.uk` | For security contacts |
-| `enable_github_pages` | `true` or `false` | If using GitHub Pages |
-| `enable_consent_gate` | `false` | Optional edge prefilter; keep origin enforcement as source of truth |
-| `enable_capability_gate` | `false` | Optional `/api/*` prefilter; keep origin enforcement as source of truth |
-| `enable_ipfs_gateway` | `false` | Requires Cloudflare Web3 gateway subscription |
-| `ipfs_dnslink` | `/ipns/onboarding.ipfs.cloudflare.com` | Initial value before your publish script updates it |
-| `pages_project` | Project name | If using Cloudflare Pages |
-
-### Leave blank:
-- `tunnel_id` - Unless using Cloudflare Tunnel
-- `mx_*` - Unless using email
-- `ssh_*` - Unless using SSH
-- `dkim_*` - Unless using email
-
----
-
-## Step 3: Preview Changes (DRY RUN)
-
-```bash
-cd /var$REPOS_DIR/cloudflare-dns-terraform
-
-# Set credentials
-export CLOUDFLARE_API_TOKEN='your-api-token-here'
-
-# Or use terraform.tfvars
-cp terraform.tfvars.example terraform.tfvars
-nano terraform.tfvars
-
-# Initialize Terraform
-terraform init
-
-# Preview what will be created (NO CHANGES YET)
-terraform plan
-```
-
-**Review the output carefully!**
-
-You should see:
-- `+` = Will create (new records)
-- `~` = Will modify (existing records)
-- `-` = Will delete (old records)
-
----
-
-## Step 4: Deploy to ALL Domains
-
-```bash
-# Apply changes to ALL domains
-terraform apply
-
-# Type 'yes' when prompted
-```
-
-This will:
-1. Add security headers to ALL domains (via Transform Rules - FREE)
-2. Create standard DNS records (www, cdn, static, assets, etc.)
-3. Add CAA records with critical flag (128)
-4. Set up Cloudflare Pages domains (if specified)
-
----
-
-## Step 5: Verify Security Headers
-
-Test any domain:
-
-```bash
-# Check headers
-curl -I https://your-domain.com
-
-# Should see:
-# Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
-# Content-Security-Policy: ...
-# X-Frame-Options: DENY
-# etc.
-```
-
-Online tests:
-- https://securityheaders.com/?q=https://your-domain.com
-- https://www.ssllabs.com/ssltest/analyze.html?d=your-domain.com
-
----
-
-## Step 6: Deploy Workers (OPTIONAL - Only if Needed)
-
-**Skip this if you don't need consent/capability gates** (saves worker requests)
-
-### If you want consent gates:
-
-1. Edit `domains.csv` and set `enable_consent_gate=true` for domains that need it
-2. Deploy worker:
-```bash
-cd workers/
-wrangler deploy consent-aware-http.js
-```
-
-3. Apply Terraform:
-```bash
-terraform apply
-```
-
-### If you want capability gates:
-
-1. Edit `domains.csv` and set `enable_capability_gate=true` for domains with APIs
-2. Deploy worker:
-```bash
-wrangler deploy http-capability-gateway.js
-```
-
-3. Apply Terraform:
-```bash
-terraform apply
-```
-
----
-
-## Cost Breakdown (All Domains):
-
-### Guaranteed FREE:
-- ✅ Transform Rules (security headers) - **FREE unlimited**
-- ✅ DNS records - **FREE unlimited** (Cloudflare DNS)
-- ✅ Cloudflare Pages - **FREE** (500 builds/month)
-
-### Potentially FREE (if under limits):
-- ⚠️ Consent gates - **FREE** if < 100k requests/day total across ALL domains
-- ⚠️ Capability gates - **FREE** if < 100k requests/day total across ALL domains
-
-### Example with 10 domains:
-
-```
-Domain 1: 5,000 requests/day (mostly static → Transform Rules = FREE)
-Domain 2: 3,000 requests/day (mostly static → Transform Rules = FREE)
-Domain 3: 2,000 requests/day (mostly static → Transform Rules = FREE)
-... (7 more domains)
-Total: 30,000 requests/day
-
-Workers only needed for:
-- Analytics endpoints: ~1,000 requests/day (consent gate)
-- API endpoints: ~500 requests/day (capability gate)
-
-Total worker requests: ~1,500/day = 45,000/month
-FREE tier: 3,000,000/month
-
-Cost: £0/month ✅
-```
-
----
-
-## What Gets Applied to Each Domain:
-
-### Always (FREE via Transform Rules):
-- Security headers (HSTS, CSP, X-Frame-Options, etc.)
-- CAA records (Let's Encrypt + DigiCert, flags=128)
-- SPF record
-- DMARC record
-
-### Standard DNS (FREE):
-- `www` → CNAME to root (proxied)
-- `static` → CNAME to root (proxied)
-- `assets` → CNAME to root (proxied)
-- `cdn` → CNAME to root (proxied)
-- `api` → CNAME to root (proxied)
-- `status` → CNAME to root (proxied)
-- `ci` → CNAME to root (proxied)
-- Plus 10+ more standard subdomains
-
-### Optional (if enabled):
-- GitHub Pages CNAME (if `enable_github_pages=true`)
-- Cloudflare Pages custom domain (if `pages_project` set)
-- MX/DKIM records (if `enable_mail=true`)
-- SSH fingerprints (if `enable_ssh=true`)
-- Cloudflare Tunnel (if `enable_tunnel=true`)
-- Consent gate (if `enable_consent_gate=true`)
-- Capability gate (if `enable_capability_gate=true`)
-
----
-
-## Rollback Plan
-
-If something goes wrong:
-
-```bash
-# See what Terraform created
-terraform show
-
-# Destroy specific domain
-terraform destroy -target='cloudflare_record.www["problem-domain.com"]'
-
-# Destroy everything (CAREFUL!)
-terraform destroy
-```
-
-**Note:** Terraform tracks state in `terraform.tfstate` - don't delete this file!
-
----
-
-## Monitoring
-
-### Set up alerts to avoid surprise charges:
-
-1. Go to: https://dash.cloudflare.com/[account]/notifications
-2. Create alert: "Workers Requests Threshold"
-3. Set threshold: 80,000 requests/day (80% of free tier)
-
-### Check usage:
-
-```bash
-# Via dashboard
-https://dash.cloudflare.com/[account]/workers/overview
-
-# Via CLI
-wrangler tail consent-aware-http --status
-```
-
----
-
-## Maintenance
-
-### Adding a new domain:
-
-1. Add row to `domains.csv`
-2. Run `terraform apply`
-3. Done!
-
-### Removing a domain:
-
-1. Delete row from `domains.csv`
-2. Run `terraform apply`
-3. Terraform will remove all DNS records
-
-### Updating all domains:
-
-1. Edit `domains.csv` (change columns for all domains)
-2. Run `terraform apply`
-3. Changes apply to all domains instantly
-
----
-
-## Summary
-
-**This will set up world-class security across ALL your websites:**
-
-✅ Security headers (HSTS, CSP, etc.)
-✅ CAA with critical flag (128)
-✅ Standard DNS structure
-✅ Cloudflare Pages support
-✅ GitHub Pages support
-✅ Optional consent gates
-✅ Optional capability gates
-✅ **All FREE** (unless you exceed 100k requests/day)
-
-**Total cost: £0/month for typical usage** 🎉
-
-Ready to deploy? Run:
-```bash
-terraform apply
-```
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..c36c7fd
--- /dev/null
+++ b/PROOF-NEEDS.adoc
@@ -0,0 +1,12 @@
+== Proof needs
+
+Template ABI stubs (`+src/abi/{Types,Foreign,Layout}.idr+`) removed
+2026-06-29 — they were RSR-template placeholders ("`Replace
+CloudflareDnsTerraform with your project name`"), not real proofs, and
+created a false impression of formal verification in what is a
+Cloudflare DNS / Terraform configuration repo.
+
+This repo makes *no formal-verification claim*. There are currently no
+proof obligations. If formal guarantees are ever wanted (e.g. DNS-record
+invariants, zone-file well-formedness), add them deliberately under
+`+verification/proofs/+`.
diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md
deleted file mode 100644
index 1a2dca8..0000000
--- a/PROOF-NEEDS.md
+++ /dev/null
@@ -1,14 +0,0 @@
-
-# Proof needs
-
-Template ABI stubs (`src/abi/{Types,Foreign,Layout}.idr`) removed 2026-06-29 —
-they were RSR-template placeholders ("Replace CloudflareDnsTerraform with your
-project name"), not real proofs, and created a false impression of formal
-verification in what is a Cloudflare DNS / Terraform configuration repo.
-
-This repo makes **no formal-verification claim**. There are currently no proof
-obligations. If formal guarantees are ever wanted (e.g. DNS-record invariants,
-zone-file well-formedness), add them deliberately under `verification/proofs/`.
diff --git a/QUICK-START.md b/QUICK-START.adoc
similarity index 72%
rename from QUICK-START.md
rename to QUICK-START.adoc
index 3ce360c..77a463d 100644
--- a/QUICK-START.md
+++ b/QUICK-START.adoc
@@ -1,26 +1,29 @@
-# Quick Start - Deploy to Your 26 Domains
+== Quick Start - Deploy to Your 26 Domains
-## Step 1: List Your Domains
+=== Step 1: List Your Domains
Go to https://dash.cloudflare.com and copy all 26 domain names.
-## Step 2: Fill domains.csv
+=== Step 2: Fill domains.csv
-Open `domains.csv` in Excel and add one row per domain:
+Open `+domains.csv+` in Excel and add one row per domain:
-```csv
+[source,csv]
+----
domain,github_user,github_repo,tunnel_id,mx_primary,mx_secondary,admin_email,ssh_fp_sha256,ssh_fp_sha256_backup,dkim_selector,tlsa_cert_hash,enable_mail,enable_tunnel,enable_ssh,enable_github_pages,enable_consent_gate,enable_capability_gate,enable_ipfs_gateway,ipfs_dnslink,pages_project
wokelang.org,hyperpolymath,wokelang,,,,,,,default,,false,false,false,false,false,false,false,,wokelang
domain2.com,hyperpolymath,,,,,,,,default,,false,false,false,false,false,false,false,,
domain3.com,hyperpolymath,,,,,,,,default,,false,false,false,false,false,false,false,,
... (add all 26 domains)
-```
+----
-**Quick fill:** Just change the domain name, leave everything else as defaults!
+*Quick fill:* Just change the domain name, leave everything else as
+defaults!
-## Step 3: Deploy
+=== Step 3: Deploy
-```bash
+[source,bash]
+----
cd /var$REPOS_DIR/cloudflare-dns-terraform
# Set API token
@@ -30,10 +33,12 @@ export CLOUDFLARE_API_TOKEN='your-api-token-here'
terraform init
terraform plan # Preview
terraform apply # Deploy!
-```
+----
-## Cost: FREE
+=== Cost: FREE
-All 26 domains will use Transform Rules (FREE unlimited) for security headers.
+All 26 domains will use Transform Rules (FREE unlimited) for security
+headers.
-DNS-only records are still free. Cloudflare Web3/IPFS hostnames require a subscribed Web3 gateway product.
+DNS-only records are still free. Cloudflare Web3/IPFS hostnames require
+a subscribed Web3 gateway product.
diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc
index 8a1d0c8..e1a986c 100644
--- a/RSR_OUTLINE.adoc
+++ b/RSR_OUTLINE.adoc
@@ -146,8 +146,8 @@ project/
=== Language Tiers
-* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript
-* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix
+* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript
+* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix
* **Infrastructure**: Guix channels, derivations
=== Required Files
@@ -161,12 +161,12 @@ project/
* `.well-known/security.txt`
* `.well-known/ai.txt`
* `.well-known/humans.txt`
-* `guix.scm` OR `flake.nix`
+* `guix.scm` OR `flake.guix`
=== Prohibited
* Python outside `salt/` directory
-* TypeScript/JavaScript (use ReScript)
+* TypeScript/JavaScript (use AffineScript)
* CUE (use Guile/Nickel)
* `Dockerfile` (use `Containerfile`)
diff --git a/SECURITY-HEADERS-GUIDE.adoc b/SECURITY-HEADERS-GUIDE.adoc
new file mode 100644
index 0000000..53590f5
--- /dev/null
+++ b/SECURITY-HEADERS-GUIDE.adoc
@@ -0,0 +1,298 @@
+== Security Headers & HTTP Protocol Guide
+
+=== Quick Answers to Your Questions:
+
+==== 1. HTTP/0.9 and HTTP/1.0 - Any Value?
+
+*Short Answer: NO - Zero value in 2026.*
+
+*HTTP Protocol Timeline:* | Protocol | Year | Status | Support It? |
+|———-|——|——–|————-| | HTTP/0.9 | 1991 | Obsolete | ❌ NO | | HTTP/1.0 |
+1996 | Legacy | ❌ NO | | HTTP/1.1 | 1997 | Mature | ✅ YES (fallback
+only) | | HTTP/2 | 2015 | Modern | ✅ YES (minimum) | | HTTP/3 | 2022 |
+Cutting-edge | ✅ YES (preferred) |
+
+*Why NOT to support HTTP/0.9 or HTTP/1.0:* - ❌ No security features (no
+TLS/SSL integration) - ❌ No header support (can’t set security
+headers!) - ❌ No caching controls - ❌ No content negotiation - ❌ <
+0.01% of traffic uses these - ❌ All modern browsers/tools require at
+least HTTP/1.1
+
+*Cloudflare Configuration (Recommended):*
+
+[source,terraform]
+----
+resource "cloudflare_zone_settings_override" "http_protocol" {
+ zone_id = each.value.zone_id
+
+ settings {
+ # Minimum TLS version
+ min_tls_version = "1.2" # Drop TLS 1.0/1.1
+
+ # HTTP/2 and HTTP/3
+ http2 = "on"
+ http3 = "on"
+
+ # Drop HTTP/1.0 and older
+ # (Cloudflare does this automatically when proxying)
+ }
+}
+----
+
+*Best Practice: HTTP/3 → HTTP/2 → HTTP/1.1* - Clients negotiate downward
+automatically - No need to explicitly support HTTP/0.9 or HTTP/1.0
+
+'''''
+
+=== 2. Security Headers Solutions (Comprehensive)
+
+==== Option A: Cloudflare Transform Rules (EASIEST)
+
+*Already included in your Terraform!* (`+security-headers.tf+`)
+
+[source,bash]
+----
+terraform apply
+----
+
+This automatically adds headers to *all domains* without code!
+
+*Headers Added:* - ✅ `+Strict-Transport-Security+` (HSTS) - ✅
+`+Content-Security-Policy+` (CSP) - ✅ `+X-Frame-Options+` - ✅
+`+X-Content-Type-Options+` - ✅ `+Referrer-Policy+` - ✅
+`+Permissions-Policy+` - ✅ `+X-XSS-Protection+` - ✅ `+Cross-Origin-*+`
+policies (COEP, COOP, CORP)
+
+==== Option B: Cloudflare Pages `+_headers+` File
+
+If using Cloudflare Pages (like wokelang-ssg):
+
+[arabic]
+. Copy `+examples/_headers+` to your SSG build output
+. Cloudflare Pages automatically applies headers!
+
+*For wokelang-ssg:*
+
+[source,bash]
+----
+# In your build script
+cp _headers dist/
+----
+
+==== Option C: Meta Tags (LIMITED - Not Recommended)
+
+*Only works for CSP*, and less secure than HTTP headers:
+
+[source,html]
+----
+
+
+----
+
+*Problems:* - ❌ Can’t set HSTS via meta tag - ❌ Can’t set
+X-Frame-Options via meta tag - ❌ Browsers trust HTTP headers more than
+meta tags - ❌ Easier to bypass
+
+*Verdict:* Don’t use meta tags. Use Cloudflare Transform Rules.
+
+'''''
+
+=== 3. Email Security Records - Now Complete!
+
+==== New DNS Records Added:
+
+===== DKIM (DomainKeys Identified Mail)
+
+Proves your emails aren’t forged.
+
+*CSV Fields:*
+
+[source,csv]
+----
+dkim_selector,dkim_public_key,dkim_selector_rotation,dkim_public_key_rotation
+----
+
+*Get your DKIM key:*
+
+[source,bash]
+----
+# If using mail server
+cat /etc/opendkim/keys/default.txt
+
+# Or generate
+opendkim-genkey -s default -d yourdomain.org
+----
+
+===== BIMI (Brand Indicators)
+
+Shows your logo in email clients.
+
+*CSV Fields:*
+
+[source,csv]
+----
+bimi_logo_url,bimi_vmc_url
+----
+
+*Example:*
+
+[source,csv]
+----
+https://yourdomain.org/logo.svg,https://yourdomain.org/vmc.pem
+----
+
+===== ARC (Authenticated Received Chain)
+
+For mailing lists/forwarders.
+
+*CSV Fields:*
+
+[source,csv]
+----
+arc_selector,arc_public_key
+----
+
+===== CAA with Critical Flag (128)
+
+*Already updated in `+email-security.tf+`!*
+
+[source,terraform]
+----
+data {
+ flags = "128" # CRITICAL - Reject if CA doesn't support CAA
+ tag = "issue"
+ value = "letsencrypt.org"
+}
+----
+
+*What flags=128 means:* - Normal CAA (flags=0): CAs that don’t
+understand CAA ignore it - Critical CAA (flags=128): CAs that don’t
+understand CAA *must reject*
+
+*More secure, but:* - Some older CAs might fail - Let’s Encrypt and
+DigiCert both support it
+
+===== Additional Email Records:
+
+* ✅ SRV records for IMAP/POP3/Submission
+* ✅ Autoconfig/Autodiscover CNAMEs
+* ✅ Enhanced SPF with custom includes
+* ✅ ADSP (legacy but some use)
+
+'''''
+
+=== 4. Complete Security Stack
+
+==== DNS Level (via Terraform):
+
+* ✅ CAA with critical flag (128)
+* ✅ DNSSEC (enable in Cloudflare dashboard)
+* ✅ SPF, DMARC, DKIM, BIMI, ARC
+* ✅ TLSA for mail servers
+* ✅ SSHFP fingerprints
+
+==== HTTP Level (via Cloudflare):
+
+* ✅ HSTS with preload
+* ✅ CSP (Content Security Policy)
+* ✅ Frame protection
+* ✅ XSS protection
+* ✅ MIME sniffing protection
+* ✅ Referrer policy
+* ✅ Permissions policy
+* ✅ Cross-origin isolation
+
+==== TLS Level (via Cloudflare):
+
+* ✅ TLS 1.2+ only (drop 1.0/1.1)
+* ✅ HTTP/2 and HTTP/3
+* ✅ OCSP stapling
+* ✅ Certificate transparency
+
+'''''
+
+=== 5. Testing Your Security
+
+==== Test Headers:
+
+[source,bash]
+----
+# Check headers
+curl -I https://wokelang.org
+
+# Security headers test
+https://securityheaders.com/?q=https://wokelang.org
+
+# SSL Labs test
+https://www.ssllabs.com/ssltest/analyze.html?d=wokelang.org
+----
+
+==== Test Email Security:
+
+[source,bash]
+----
+# DMARC
+dig +short TXT _dmarc.wokelang.org
+
+# DKIM
+dig +short TXT default._domainkey.wokelang.org
+
+# SPF
+dig +short TXT wokelang.org | grep spf
+
+# MTA-STS
+curl https://mta-sts.wokelang.org/.well-known/mta-sts.txt
+----
+
+==== Test CAA:
+
+[source,bash]
+----
+dig +short CAA wokelang.org
+# Should show: 128 issue "letsencrypt.org"
+----
+
+'''''
+
+=== 6. Deployment Steps
+
+==== Step 1: Deploy DNS Records
+
+[source,bash]
+----
+cd /var$REPOS_DIR/cloudflare-dns-terraform
+terraform init
+terraform plan
+terraform apply
+----
+
+==== Step 2: Verify Headers (Automatic via Cloudflare)
+
+[source,bash]
+----
+curl -I https://wokelang.org | grep -i strict
+# Should show: Strict-Transport-Security: max-age=31536000...
+----
+
+==== Step 3: Enable HSTS Preload (Optional)
+
+Submit to: https://hstspreload.org/?domain=wokelang.org
+
+==== Step 4: Monitor
+
+* https://observatory.mozilla.org
+* https://securityheaders.com
+* https://www.hardenize.com
+
+'''''
+
+=== Summary:
+
+✅ *HTTP/0.9, HTTP/1.0* - Don’t support them (no value) ✅ *Security
+Headers* - Use Cloudflare Transform Rules (included in Terraform) ✅
+*CAA flags=128* - Now using critical flag ✅ *DKIM* - Added to
+email-security.tf ✅ *All email security* - BIMI, ARC, SRV records,
+autoconfig ✅ *Complete stack* - DNS + HTTP + TLS security
+
+*Your infrastructure is now world-class secure!* 🔒🚀
diff --git a/SECURITY-HEADERS-GUIDE.md b/SECURITY-HEADERS-GUIDE.md
deleted file mode 100644
index 2a45239..0000000
--- a/SECURITY-HEADERS-GUIDE.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# Security Headers & HTTP Protocol Guide
-
-## Quick Answers to Your Questions:
-
-### 1. HTTP/0.9 and HTTP/1.0 - Any Value?
-
-**Short Answer: NO - Zero value in 2026.**
-
-**HTTP Protocol Timeline:**
-| Protocol | Year | Status | Support It? |
-|----------|------|--------|-------------|
-| HTTP/0.9 | 1991 | Obsolete | ❌ NO |
-| HTTP/1.0 | 1996 | Legacy | ❌ NO |
-| HTTP/1.1 | 1997 | Mature | ✅ YES (fallback only) |
-| HTTP/2 | 2015 | Modern | ✅ YES (minimum) |
-| HTTP/3 | 2022 | Cutting-edge | ✅ YES (preferred) |
-
-**Why NOT to support HTTP/0.9 or HTTP/1.0:**
-- ❌ No security features (no TLS/SSL integration)
-- ❌ No header support (can't set security headers!)
-- ❌ No caching controls
-- ❌ No content negotiation
-- ❌ < 0.01% of traffic uses these
-- ❌ All modern browsers/tools require at least HTTP/1.1
-
-**Cloudflare Configuration (Recommended):**
-```terraform
-resource "cloudflare_zone_settings_override" "http_protocol" {
- zone_id = each.value.zone_id
-
- settings {
- # Minimum TLS version
- min_tls_version = "1.2" # Drop TLS 1.0/1.1
-
- # HTTP/2 and HTTP/3
- http2 = "on"
- http3 = "on"
-
- # Drop HTTP/1.0 and older
- # (Cloudflare does this automatically when proxying)
- }
-}
-```
-
-**Best Practice: HTTP/3 → HTTP/2 → HTTP/1.1**
-- Clients negotiate downward automatically
-- No need to explicitly support HTTP/0.9 or HTTP/1.0
-
----
-
-## 2. Security Headers Solutions (Comprehensive)
-
-### Option A: Cloudflare Transform Rules (EASIEST)
-
-**Already included in your Terraform!** (`security-headers.tf`)
-
-```bash
-terraform apply
-```
-
-This automatically adds headers to **all domains** without code!
-
-**Headers Added:**
-- ✅ `Strict-Transport-Security` (HSTS)
-- ✅ `Content-Security-Policy` (CSP)
-- ✅ `X-Frame-Options`
-- ✅ `X-Content-Type-Options`
-- ✅ `Referrer-Policy`
-- ✅ `Permissions-Policy`
-- ✅ `X-XSS-Protection`
-- ✅ `Cross-Origin-*` policies (COEP, COOP, CORP)
-
-### Option B: Cloudflare Pages `_headers` File
-
-If using Cloudflare Pages (like wokelang-ssg):
-
-1. Copy `examples/_headers` to your SSG build output
-2. Cloudflare Pages automatically applies headers!
-
-**For wokelang-ssg:**
-```bash
-# In your build script
-cp _headers dist/
-```
-
-### Option C: Meta Tags (LIMITED - Not Recommended)
-
-**Only works for CSP**, and less secure than HTTP headers:
-
-```html
-
-
-```
-
-**Problems:**
-- ❌ Can't set HSTS via meta tag
-- ❌ Can't set X-Frame-Options via meta tag
-- ❌ Browsers trust HTTP headers more than meta tags
-- ❌ Easier to bypass
-
-**Verdict:** Don't use meta tags. Use Cloudflare Transform Rules.
-
----
-
-## 3. Email Security Records - Now Complete!
-
-### New DNS Records Added:
-
-#### DKIM (DomainKeys Identified Mail)
-Proves your emails aren't forged.
-
-**CSV Fields:**
-```csv
-dkim_selector,dkim_public_key,dkim_selector_rotation,dkim_public_key_rotation
-```
-
-**Get your DKIM key:**
-```bash
-# If using mail server
-cat /etc/opendkim/keys/default.txt
-
-# Or generate
-opendkim-genkey -s default -d yourdomain.org
-```
-
-#### BIMI (Brand Indicators)
-Shows your logo in email clients.
-
-**CSV Fields:**
-```csv
-bimi_logo_url,bimi_vmc_url
-```
-
-**Example:**
-```csv
-https://yourdomain.org/logo.svg,https://yourdomain.org/vmc.pem
-```
-
-#### ARC (Authenticated Received Chain)
-For mailing lists/forwarders.
-
-**CSV Fields:**
-```csv
-arc_selector,arc_public_key
-```
-
-#### CAA with Critical Flag (128)
-**Already updated in `email-security.tf`!**
-
-```terraform
-data {
- flags = "128" # CRITICAL - Reject if CA doesn't support CAA
- tag = "issue"
- value = "letsencrypt.org"
-}
-```
-
-**What flags=128 means:**
-- Normal CAA (flags=0): CAs that don't understand CAA ignore it
-- Critical CAA (flags=128): CAs that don't understand CAA **must reject**
-
-**More secure, but:**
-- Some older CAs might fail
-- Let's Encrypt and DigiCert both support it
-
-#### Additional Email Records:
-- ✅ SRV records for IMAP/POP3/Submission
-- ✅ Autoconfig/Autodiscover CNAMEs
-- ✅ Enhanced SPF with custom includes
-- ✅ ADSP (legacy but some use)
-
----
-
-## 4. Complete Security Stack
-
-### DNS Level (via Terraform):
-- ✅ CAA with critical flag (128)
-- ✅ DNSSEC (enable in Cloudflare dashboard)
-- ✅ SPF, DMARC, DKIM, BIMI, ARC
-- ✅ TLSA for mail servers
-- ✅ SSHFP fingerprints
-
-### HTTP Level (via Cloudflare):
-- ✅ HSTS with preload
-- ✅ CSP (Content Security Policy)
-- ✅ Frame protection
-- ✅ XSS protection
-- ✅ MIME sniffing protection
-- ✅ Referrer policy
-- ✅ Permissions policy
-- ✅ Cross-origin isolation
-
-### TLS Level (via Cloudflare):
-- ✅ TLS 1.2+ only (drop 1.0/1.1)
-- ✅ HTTP/2 and HTTP/3
-- ✅ OCSP stapling
-- ✅ Certificate transparency
-
----
-
-## 5. Testing Your Security
-
-### Test Headers:
-```bash
-# Check headers
-curl -I https://wokelang.org
-
-# Security headers test
-https://securityheaders.com/?q=https://wokelang.org
-
-# SSL Labs test
-https://www.ssllabs.com/ssltest/analyze.html?d=wokelang.org
-```
-
-### Test Email Security:
-```bash
-# DMARC
-dig +short TXT _dmarc.wokelang.org
-
-# DKIM
-dig +short TXT default._domainkey.wokelang.org
-
-# SPF
-dig +short TXT wokelang.org | grep spf
-
-# MTA-STS
-curl https://mta-sts.wokelang.org/.well-known/mta-sts.txt
-```
-
-### Test CAA:
-```bash
-dig +short CAA wokelang.org
-# Should show: 128 issue "letsencrypt.org"
-```
-
----
-
-## 6. Deployment Steps
-
-### Step 1: Deploy DNS Records
-```bash
-cd /var$REPOS_DIR/cloudflare-dns-terraform
-terraform init
-terraform plan
-terraform apply
-```
-
-### Step 2: Verify Headers (Automatic via Cloudflare)
-```bash
-curl -I https://wokelang.org | grep -i strict
-# Should show: Strict-Transport-Security: max-age=31536000...
-```
-
-### Step 3: Enable HSTS Preload (Optional)
-Submit to: https://hstspreload.org/?domain=wokelang.org
-
-### Step 4: Monitor
-- https://observatory.mozilla.org
-- https://securityheaders.com
-- https://www.hardenize.com
-
----
-
-## Summary:
-
-✅ **HTTP/0.9, HTTP/1.0** - Don't support them (no value)
-✅ **Security Headers** - Use Cloudflare Transform Rules (included in Terraform)
-✅ **CAA flags=128** - Now using critical flag
-✅ **DKIM** - Added to email-security.tf
-✅ **All email security** - BIMI, ARC, SRV records, autoconfig
-✅ **Complete stack** - DNS + HTTP + TLS security
-
-**Your infrastructure is now world-class secure!** 🔒🚀
diff --git a/SECURITY.adoc b/SECURITY.adoc
new file mode 100644
index 0000000..327ecec
--- /dev/null
+++ b/SECURITY.adoc
@@ -0,0 +1,454 @@
+== 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
+
+* link:#reporting-a-vulnerability[Reporting a Vulnerability]
+* link:#what-to-include[What to Include]
+* link:#response-timeline[Response Timeline]
+* link:#disclosure-policy[Disclosure Policy]
+* link:#scope[Scope]
+* link:#safe-harbour[Safe Harbour]
+* link:#recognition[Recognition]
+* link:#security-updates[Security Updates]
+* link:#security-best-practices[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:
+
+[arabic]
+. Navigate to
+https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories/new[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:
+
+[width="100%",cols="50%,50%",]
+|===
+|*Email* |j.d.a.jewell@open.ac.uk
+|*PGP Key* |https://github.com/hyperpolymath.gpg[Download Public Key]
+|*Fingerprint* |`+[contact maintainer for PGP key]+`
+|===
+
+[source,bash]
+----
+# Import our PGP key
+curl -sSL https://github.com/hyperpolymath.gpg | gpg --import
+
+# Verify fingerprint
+gpg --fingerprint j.d.a.jewell@open.ac.uk
+
+# Encrypt your report
+gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk 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
+https://www.first.org/cvss/calculator/3.1[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
+
+[source,markdown]
+----
+## 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:
+
+[width="100%",cols="24%,35%,41%",options="header",]
+|===
+|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):
+
+[arabic]
+. *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/cloudflare-dns-terraform+`) 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
+link:SECURITY-ACKNOWLEDGMENTS.md[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
+https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories[Security
+Advisories]
+* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG]
+
+==== Update Policy
+
+[cols=",",options="header",]
+|===
+|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
+
+[cols=",,",options="header",]
+|===
+|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 cloudflare-dns-terraform, 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
+
+* https://github.com/hyperpolymath.gpg[Our PGP Public Key]
+* https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories[Security
+Advisories]
+* link:CHANGELOG.md[Changelog]
+* link:CONTRIBUTING.md[Contributing Guidelines]
+* https://cve.mitre.org/[CVE Database]
+* https://www.first.org/cvss/calculator/3.1[CVSS Calculator]
+
+'''''
+
+=== Contact
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|Purpose |Contact
+|*Security issues*
+|https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories/new[Report
+via GitHub] or j.d.a.jewell@open.ac.uk
+
+|*General questions*
+|https://github.com/hyperpolymath/cloudflare-dns-terraform/discussions[GitHub
+Discussions]
+
+|*Other enquiries* |See link:README.md[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 cloudflare-dns-terraform and its users
+safe._ 🛡️
+
+'''''
+
+Last updated: 2025 · Policy version: 1.0.0
diff --git a/SECURITY.md b/SECURITY.md
deleted file mode 100644
index eb354b9..0000000
--- a/SECURITY.md
+++ /dev/null
@@ -1,388 +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](#reporting-a-vulnerability)
-- [What to Include](#what-to-include)
-- [Response Timeline](#response-timeline)
-- [Disclosure Policy](#disclosure-policy)
-- [Scope](#scope)
-- [Safe Harbour](#safe-harbour)
-- [Recognition](#recognition)
-- [Security Updates](#security-updates)
-- [Security Best Practices](#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:
-
-1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories/new)
-2. Click **"Report a vulnerability"**
-3. Complete the form with as much detail as possible
-4. 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** | j.d.a.jewell@open.ac.uk |
-| **PGP Key** | [Download Public Key](https://github.com/hyperpolymath.gpg) |
-| **Fingerprint** | `[contact maintainer for PGP key]` |
-
-```bash
-# Import our PGP key
-curl -sSL https://github.com/hyperpolymath.gpg | gpg --import
-
-# Verify fingerprint
-gpg --fingerprint j.d.a.jewell@open.ac.uk
-
-# Encrypt your report
-gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk 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](https://www.first.org/cvss/calculator/3.1))
-- **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
-
-```markdown
-## 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):
-
-1. **You report** the vulnerability privately
-2. **We acknowledge** and begin investigation
-3. **We develop** a fix and prepare a release
-4. **We coordinate** disclosure timing with you
-5. **We publish** security advisory and fix simultaneously
-6. **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/cloudflare-dns-terraform`) 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](SECURITY-ACKNOWLEDGMENTS.md) (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](https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories)
-- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md)
-
-### 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 cloudflare-dns-terraform, 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](https://github.com/hyperpolymath.gpg)
-- [Security Advisories](https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories)
-- [Changelog](CHANGELOG.md)
-- [Contributing Guidelines](CONTRIBUTING.md)
-- [CVE Database](https://cve.mitre.org/)
-- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)
-
----
-
-## Contact
-
-| Purpose | Contact |
-|---------|---------|
-| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/cloudflare-dns-terraform/security/advisories/new) or j.d.a.jewell@open.ac.uk |
-| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/cloudflare-dns-terraform/discussions) |
-| **Other enquiries** | See [README](README.md) 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 cloudflare-dns-terraform and its users safe.* 🛡️
-
----
-
-Last updated: 2025 · Policy version: 1.0.0
diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc
new file mode 100644
index 0000000..50c6603
--- /dev/null
+++ b/TEST-NEEDS.adoc
@@ -0,0 +1,32 @@
+== TEST-NEEDS.md — cloudflare-dns-terraform
+
+=== CRG Grade: C — ACHIEVED 2026-04-04
+
+=== Current Test State
+
+[cols=",,",options="header",]
+|===
+|Category |Count |Notes
+|Test directories |1 |Location(s): /tests
+|CI workflows |17 |Running tests on GitHub Actions
+|Tests |Present |Configured in CI workflows
+|===
+
+=== What’s Covered
+
+* [x] Tests present and running
+* [x] CI integration active
+
+=== Still Missing (for CRG B+)
+
+* [ ] Code coverage reports (codecov integration)
+* [ ] Detailed test documentation in CONTRIBUTING.md
+* [ ] Integration tests beyond unit tests
+* [ ] Performance benchmarking suite
+
+=== Run Tests
+
+[source,bash]
+----
+(check Makefile/justfile/package.json for test command)
+----
diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md
deleted file mode 100644
index 201adc8..0000000
--- a/TEST-NEEDS.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# TEST-NEEDS.md — cloudflare-dns-terraform
-
-## CRG Grade: C — ACHIEVED 2026-04-04
-
-## Current Test State
-
-| Category | Count | Notes |
-|----------|-------|-------|
-| Test directories | 1 | Location(s): /tests |
-| CI workflows | 17 | Running tests on GitHub Actions |
-| Tests | Present | Configured in CI workflows |
-
-## What's Covered
-
-- [x] Tests present and running
-- [x] CI integration active
-
-## Still Missing (for CRG B+)
-
-- [ ] Code coverage reports (codecov integration)
-- [ ] Detailed test documentation in CONTRIBUTING.md
-- [ ] Integration tests beyond unit tests
-- [ ] Performance benchmarking suite
-
-## Run Tests
-
-```bash
-(check Makefile/justfile/package.json for test command)
-```
diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc
similarity index 90%
rename from TOPOLOGY.md
rename to TOPOLOGY.adoc
index 2186191..864b1a8 100644
--- a/TOPOLOGY.md
+++ b/TOPOLOGY.adoc
@@ -1,12 +1,8 @@
-
-
-
+== Cloudflare DNS Terraform — Project Topology
-# Cloudflare DNS Terraform — Project Topology
+=== System Architecture
-## System Architecture
-
-```
+....
┌─────────────────────────────────────────┐
│ OPERATOR / ADMIN │
│ (Excel, CSV, Terraform CLI) │
@@ -51,11 +47,11 @@
│ Extraction Scripts .machine_readable/ │
│ auto-add-new-sites contractiles/ │
└─────────────────────────────────────────┘
-```
+....
-## Completion Dashboard
+=== Completion Dashboard
-```
+....
COMPONENT STATUS NOTES
───────────────────────────────── ────────────────── ─────────────────────────────────
CORE INFRASTRUCTURE
@@ -80,25 +76,26 @@ REPO INFRASTRUCTURE
─────────────────────────────────────────────────────────────────────────────
OVERALL: █████████░ ~90% Infrastructure-as-Code stable
-```
+....
-## Key Dependencies
+=== Key Dependencies
-```
+....
domains.csv ──────► terraform plan ──────► terraform apply
│ │ │
▼ ▼ ▼
Credentials ──────► API Checks ──────────► Cloudflare Zone
-```
+....
-## 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..5188038
--- /dev/null
+++ b/docs/tech-debt-2026-05-26.adoc
@@ -0,0 +1,71 @@
+== Tech-Debt Audit — cloudflare-dns-terraform — 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 |183
+|`+docs/+` files |1
+|`+docs/+` LoC |37
+|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
+183 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 ed77f4f..0000000
--- a/docs/tech-debt-2026-05-26.md
+++ /dev/null
@@ -1,57 +0,0 @@
-
-
-# Tech-Debt Audit — cloudflare-dns-terraform — 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 | 183 |
-| `docs/` files | 1 |
-| `docs/` LoC | 37 |
-| 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 183 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/web-project-deno.json b/examples/web-project-deno.json
index 5ddd3bd..ee775a4 100644
--- a/examples/web-project-deno.json
+++ b/examples/web-project-deno.json
@@ -1,17 +1,17 @@
{
- "// NOTE": "Example deno.json for ReScript web projects",
+ "// NOTE": "Example deno.json for AffineScript web projects",
"tasks": {
- "build": "deno run -A npm:rescript",
- "clean": "deno run -A npm:rescript clean",
- "watch": "deno run -A npm:rescript -w",
+ "build": "deno run -A npm:affinescript",
+ "clean": "deno run -A npm:affinescript clean",
+ "watch": "deno run -A npm:affinescript -w",
"serve": "deno run -A jsr:@std/http/file-server .",
"test": "deno test --allow-all"
},
"imports": {
- "rescript": "^12.0.0",
- "@rescript/core": "npm:@rescript/core@^1.6.0",
- "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/",
- "proven/": "../proven/bindings/rescript/src/"
+ "affinescript": "^12.0.0",
+ "@affinescript/core": "npm:@affinescript/core@^1.6.0",
+ "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/",
+ "proven/": "../proven/bindings/affinescript/src/"
},
"compilerOptions": {
"allowJs": true,
diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc
new file mode 100644
index 0000000..b7acd6e
--- /dev/null
+++ b/llm-warmup-dev.adoc
@@ -0,0 +1,19 @@
+== LLM Warmup — cloudflare-dns-terraform (Developer)
+
+=== What is cloudflare-dns-terraform?
+
+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 a2aa27a..0000000
--- a/llm-warmup-dev.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# LLM Warmup — cloudflare-dns-terraform (Developer)
-
-## What is cloudflare-dns-terraform?
-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..a1a0efd
--- /dev/null
+++ b/llm-warmup-user.adoc
@@ -0,0 +1,19 @@
+== LLM Warmup — cloudflare-dns-terraform (User)
+
+=== What is cloudflare-dns-terraform?
+
+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 30363af..0000000
--- a/llm-warmup-user.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# LLM Warmup — cloudflare-dns-terraform (User)
-
-## What is cloudflare-dns-terraform?
-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