{"owner":"OpenNHP","repo":"opennhp","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\r\n\r\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server/agent.toml`; lets cluster 1 js-agent knock in gmsm mode |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_jsagent2_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server2/agent.toml`; lets cluster 2 js-agent knock in gmsm mode |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n","AGENTS.md":"# AGENTS.md\r\n\r\nThis file provides guidance to Codex (Codex.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n"},"files":{"CLAUDE.md":"# CLAUDE.md\r\n\r\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server/agent.toml`; lets cluster 1 js-agent knock in gmsm mode |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_jsagent2_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server2/agent.toml`; lets cluster 2 js-agent knock in gmsm mode |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n","AGENTS.md":"# AGENTS.md\r\n\r\nThis file provides guidance to Codex (Codex.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\r\n\r\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server/agent.toml`; lets cluster 1 js-agent knock in gmsm mode |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_jsagent2_sm2_public_key` | same (derived via `--both`) | SM2 peer entry in `server2/agent.toml`; lets cluster 2 js-agent knock in gmsm mode |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n","category":"root","tokens":2417},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\r\n\r\nThis file provides guidance to Codex (Codex.ai/code) when working with code in this repository.\r\n\r\n## Project Overview\r\n\r\nOpenNHP is a Go-based Zero Trust security toolkit implementing two core protocols:\r\n- **NHP (Network-infrastructure Hiding Protocol)**: Conceals server ports, IPs, and domains from unauthorized access\r\n- **DHP (Data-content Hiding Protocol)**: Ensures data security via encryption and confidential computing\r\n\r\nThe system follows NIST Zero Trust Architecture with three core components that communicate via encrypted UDP packets using the Noise Protocol Framework.\r\n\r\n## Git Commit Requirements\r\n\r\nAll commits must be signed with a verified GPG or SSH key. Unsigned commits will fail CI checks.\r\n\r\n```bash\r\n# Sign commits (if not configured globally)\r\ngit commit -S -m \"your message\"\r\n\r\n# Amend to sign an existing commit\r\ngit commit --amend --no-edit -S\r\n```\r\n\r\n## Build Commands\r\n\r\n```bash\r\n# Full build (all components + SDKs + plugins + archive)\r\nmake\r\n\r\n# Build individual components\r\nmake agentd      # Build nhp-agent daemon\r\nmake serverd     # Build nhp-server daemon\r\nmake acd         # Build nhp-ac (access controller) daemon\r\nmake db          # Build nhp-db daemon\r\nmake kgc         # Build nhp-kgc (key generation center)\r\n\r\n# Build with eBPF support (requires clang)\r\nmake ebpf\r\n\r\n# Build plugins\r\nmake plugins\r\n\r\n# Initialize/tidy modules\r\nmake init\r\n```\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Run tests in the nhp module\r\ncd nhp && go test ./...\r\n\r\n# Run tests in the endpoints module\r\ncd endpoints && go test ./...\r\n\r\n# Run specific test file\r\ncd nhp && go test -v ./test/packet_test.go\r\n\r\n# Run benchmark tests\r\ncd nhp && go test -bench=. ./core/benchmark/\r\n```\r\n\r\n## Code Formatting\r\n\r\n**IMPORTANT**: All Go code must be properly formatted before committing. CI will fail if formatting is incorrect.\r\n\r\n### Before Committing\r\n\r\nAlways run these commands on modified Go files:\r\n\r\n```bash\r\n# Format code with gofmt\r\ngofmt -w <file.go>\r\n\r\n# Fix import grouping with goimports\r\ngoimports -w <file.go>\r\n\r\n# Or format all files in a directory\r\ngofmt -w ./path/to/package/\r\ngoimports -w ./path/to/package/\r\n```\r\n\r\n### Import Grouping Style\r\n\r\nImports must be organized into three groups separated by blank lines:\r\n\r\n1. Standard library imports\r\n2. External third-party imports\r\n3. Internal project imports\r\n\r\n```go\r\nimport (\r\n\t\"fmt\"\r\n\t\"net/http\"\r\n\r\n\t\"github.com/gin-gonic/gin\"\r\n\t\"github.com/pelletier/go-toml/v2\"\r\n\r\n\t\"github.com/OpenNHP/opennhp/nhp/common\"\r\n\t\"github.com/OpenNHP/opennhp/nhp/log\"\r\n)\r\n```\r\n\r\n### Verify Formatting\r\n\r\nCheck if files need formatting (no output means properly formatted):\r\n\r\n```bash\r\ngofmt -l <file.go>\r\ngoimports -l <file.go>\r\n```\r\n\r\n### Install goimports\r\n\r\nIf `goimports` is not installed:\r\n\r\n```bash\r\ngo install golang.org/x/tools/cmd/goimports@latest\r\n```\r\n\r\n## Docker Development\r\n\r\n```bash\r\n# Build and run the full stack\r\ncd docker && docker-compose up --build\r\n\r\n# Individual service testing\r\ndocker-compose up nhp-server\r\ndocker-compose up nhp-ac\r\ndocker-compose up nhp-agent\r\n```\r\n\r\n## Architecture\r\n\r\n### Module Structure\r\n\r\nThe codebase uses two separate Go modules with a local replace directive:\r\n\r\n- **`nhp/`**: Core protocol library\r\n  - `core/`: Packet handling, cryptography, device management, Noise Protocol implementation\r\n  - `common/`: Shared types and message definitions (AgentKnockMsg, ServerKnockAckMsg, etc.)\r\n  - `utils/`: Utility functions\r\n  - `plugins/`: Plugin handler interfaces (PluginHandler interface)\r\n  - `log/`: Logging infrastructure\r\n  - `etcd/`: Distributed configuration support\r\n\r\n- **`endpoints/`**: Daemon implementations (depends on nhp module)\r\n  - `agent/`: NHP-Agent - client that sends knock requests\r\n  - `server/`: NHP-Server - authenticates and authorizes requests\r\n  - `ac/`: NHP-AC - access controller that manages firewall rules\r\n  - `db/`: NHP-DB - Data Broker for DHP\r\n  - `kgc/`: Key Generation Center for IBC (Identity-Based Cryptography)\r\n  - `relay/`: TCP relay functionality\r\n\r\n### Core Concepts\r\n\r\n**Device Types** (defined in `nhp/core/device.go`):\r\n- `NHP_AGENT`: Client initiating access requests\r\n- `NHP_SERVER`: Central authentication/authorization server\r\n- `NHP_AC`: Access controller managing network rules\r\n- `NHP_DB`: Data Broker for DHP\r\n- `NHP_RELAY`: Packet relay\r\n\r\n**Packet Types** (defined in `nhp/core/packet.go`):\r\n- `NHP_KNK`: Agent knock request\r\n- `NHP_ACK`: Server knock acknowledgment\r\n- `NHP_AOP`: Server-to-AC operation request\r\n- `NHP_ART`: AC operation result\r\n- `NHP_REG`/`NHP_RAK`: Agent registration flow\r\n- `DHP_*`: Data Hiding Protocol messages\r\n\r\n**Cipher Schemes** (in `nhp/core/crypto.go`):\r\n- `CIPHER_SCHEME_CURVE`: Curve25519 + AES-256-GCM + BLAKE2s\r\n- `CIPHER_SCHEME_GMSM`: SM2 + SM4-GCM + SM3 (Chinese national standards)\r\n\r\n### Configuration\r\n\r\nAll daemons use TOML configuration files in their respective `etc/` directories:\r\n- `config.toml`: Base configuration (private key, listen address, log level)\r\n- `server.toml`: Remote server/peer definitions\r\n- `resource.toml`: Protected resources and auth service providers\r\n- `http.toml`: HTTP server settings (for nhp-server)\r\n\r\n### Plugin System\r\n\r\nServer plugins implement the `PluginHandler` interface (`nhp/plugins/serverpluginhandler.go`) and are built as Go plugins (`.so` files). See `examples/server_plugin/` for reference implementation.\r\n\r\nKey plugin methods:\r\n- `AuthWithNHP()`: Handle NHP protocol authentication\r\n- `AuthWithHttp()`: Handle HTTP-based authentication\r\n- `RegisterAgent()`: Agent registration\r\n- `ListService()`: Service discovery\r\n\r\n### Key Generation\r\n\r\nAll daemons support the `keygen` command:\r\n```bash\r\n./nhp-serverd keygen --curve  # Generate Curve25519 keys\r\n./nhp-serverd keygen --sm2    # Generate SM2 keys (default)\r\n```\r\n\r\n## Demo Deployment (AWS)\r\n\r\nThe `terraform/demo/` stack provisions the public demo (nhp-server, nhp-ac,\r\nnhp-relay + nginx + Let's Encrypt) in `us-east-2` on the OpenNHP demo AWS\r\naccount. The state bucket is configured at `terraform init` time via\r\n`-backend-config=\"bucket=$TF_STATE_BUCKET\"` (workflows read the\r\n`TF_STATE_BUCKET` repo variable) so the account ID is not committed in source.\r\nAll secrets live in a single AWS Secrets Manager secret: **`opennhp/demo`**.\r\n\r\n### `opennhp/demo` schema\r\n\r\nThe secret is JSON; fields are added idempotently by scripts and workflows.\r\nMissing fields are auto-generated on the next `scripts/generate-nhp-keys.sh`\r\nrun (triggered by the `deploy-demo-v2` workflow).\r\n\r\n| Field | Populated by | Used by |\r\n| --- | --- | --- |\r\n| `nhp_server_private_key` / `_public_key` | `scripts/generate-nhp-keys.sh` | server `config.toml`; peer tables on ac/relay |\r\n| `nhp_ac_private_key` / `_public_key` | same | ac `config.toml`; peer table on server |\r\n| `nhp_relay_private_key` / `_public_key` | same | relay `config.toml`; peer table on server |\r\n| `nhp_agent_private_key` / `_public_key` | same | native nhp-agent clients; `agent.toml` on server |\r\n| `nhp_jsagent_private_key` / `_public_key` | same | cluster 1 `endpoints/js-agent/` demo identity (rendered into `config.json` `clusters[0]` at deploy time); trusted by server cluster 1 only |\r\n| `nhp_jsagent2_private_key` / `_public_key` | same | cluster 2 js-agent demo identity (rendered into `config.json` `clusters[1]`); trusted by server cluster 2 only, so the two clusters use independent agent keys |\r\n| `nhp_server2_private_key` / `_public_key` | same | cluster 2 server `config.toml`; peer tables on ac2/relay |\r\n| `nhp_ac2_private_key` / `_public_key` | same | cluster 2 ac `config.toml`; peer table on server2 |\r\n| `cloudflare_api_token` | manually provisioned once | Terraform + certbot DNS-01 (`Zone:DNS:Edit` + `Zone:Zone:Read`) |\r\n| `cloudflare_zone_id` | same | Terraform DNS records for `opennhp.org` |\r\n| `stealth_ca_cert` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_CERT`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `stealth_ca_key` | `infra-demo` workflow (from GitHub Secrets `STEALTH_CA_KEY`) | `tls_locally_signed_cert.demo_nhp` |\r\n| `ssh_deploy_private_key` | manually bootstrapped (see `terraform/demo/RUNBOOK.md`); never enters Terraform state | CI SSH into EC2 hosts |\r\n| `ssh_deploy_public_key` | derived in CI via `ssh-keygen -y` and passed as `TF_VAR_deploy_public_key` | `aws_key_pair.deploy` → `ec2-user` authorized keys |\r\n| `ssh_host_keys` | `infra-demo` workflow on `apply` | CI `known_hosts` for strict host key checking |\r\n\r\n### Key-generation flow\r\n\r\n`scripts/generate-nhp-keys.sh`:\r\n\r\n1. Reads existing values from `opennhp/demo`.\r\n2. Uses each daemon's `keygen --curve --json` to fill any missing pair.\r\n3. Writes the merged object back to `opennhp/demo` (preserving unrelated fields).\r\n4. Renders `deploy/config-templates/` via `envsubst` into `deploy/configs/` for\r\n   scp to the hosts.\r\n\r\nPass `--regenerate` to the script (or `regenerate_keys=yes` on the workflow) to\r\nforce a full rotation. This breaks every registered agent/ac/relay until their\r\npeer tables are redeployed in lockstep, so use sparingly.\r\n\r\n## Protocol Flow\r\n\r\n1. Agent sends encrypted knock (`NHP_KNK`) to Server\r\n2. Server validates, sends operation request (`NHP_AOP`) to AC\r\n3. AC opens firewall, responds (`NHP_ART`) to Server\r\n4. Server sends acknowledgment (`NHP_ACK`) with access info to Agent\r\n5. Agent can now access the protected resource through AC\r\n","category":"root","tokens":2341}]}