Browse Source

docs(claude): teach the bot briefings about AmneziaWG and PIA

`grep -ci amneziawg` returned 0 in both .github/claude/repo-context.md and
REVIEW.md while CLAUDE.md has carried the protocol for releases. The issue
analyst and the review bot could not name internal/amneziawg/,
internal/amneziawgnet/ or internal/pia/, and the mention job's inline map
enumerated ten protocols with amneziawg missing from the list.

The 3.1 obfuscation parameters are generated twice - GenerateObfuscation31 in
internal/amneziawg/params.go and generateAwgObfuscation in
frontend/src/lib/xray/amneziawg-obfuscation.ts - so REVIEW.md now names that
pair as a divergence surface next to the three link implementations. Commit
bd1c27b0 was already a bug in exactly that pair.

Also corrects the CLAUDE.md CLI list, which omitted encrypt-tokens.
Sanaei 19 hours ago
parent
commit
41db85a096
3 changed files with 23 additions and 5 deletions
  1. 15 0
      .github/claude/repo-context.md
  2. 1 1
      CLAUDE.md
  3. 7 4
      REVIEW.md

+ 15 - 0
.github/claude/repo-context.md

@@ -27,6 +27,10 @@ question it already answers.
   per inbound. Client, ad-tag and quota/expiry edits are hot-applied through the
   fork's management API (`PUT /secrets`) so connections survive, with a process
   restart as the fallback on older binaries.
+- AmneziaWG inbounds run IN-PROCESS, not as a child: `internal/amneziawgnet/`
+  drives an amneziawg-go device over a gVisor userspace netstack and relays into a
+  loopback SOCKS5 Xray inbound. `internal/amneziawg/` derives the instance and peers
+  from an inbound and generates + validates the 3.1 obfuscation parameters.
 - Storage: SQLite by default (`/etc/x-ui/x-ui.db` on Linux, the executable
   directory on Windows) or PostgreSQL (`XUI_DB_TYPE` / `XUI_DB_DSN`). The SQLite
   driver is CGo, so `CGO_ENABLED=0` builds fail.
@@ -42,6 +46,8 @@ question it already answers.
 | schema, migrations | `internal/database/`, `internal/database/model/` |
 | Xray child process + config | `internal/xray/` |
 | MTProto inbounds | `internal/mtproto/` |
+| AmneziaWG shape + embedded runtime | `internal/amneziawg/`, `internal/amneziawgnet/` |
+| PIA WireGuard client | `internal/pia/` |
 | subscription server | `internal/sub/` |
 | HTTP handlers | `internal/web/controller/` |
 | business logic | `internal/web/service/` |
@@ -112,12 +118,21 @@ Link and subscription generation is implemented three times, independently:
 A change to share-link or subscription output that touches one and not the
 others is how they drift apart.
 
+AmneziaWG's 3.1 obfuscation parameters are a second such pair: generated in Go by
+`GenerateObfuscation31` (`internal/amneziawg/params.go`) and in TS by
+`generateAwgObfuscation` (`frontend/src/lib/xray/amneziawg-obfuscation.ts`).
+Changing one without the other is how the panel and the UI hand out different
+configs for the same inbound.
+
 ## Downstream programs that must accept what the panel emits
 
 - **XTLS/Xray-core** — the Xray config the panel generates, and the VLESS/VMess
   transport and security fields.
 - **MetaCubeX/mihomo** — consumes the Clash YAML from `internal/sub/`.
 - **SagerNet/sing-box** — parses the share links the panel emits.
+- **amnezia-vpn/amneziawg-go** — the obfuscation parameters the panel generates
+  (`Jc`/`Jmin`/`Jmax`, `S1`-`S4`, `H1`-`H4`, `I1`-`I5`). Its `device/uapi.go` is the
+  symbol that decides which keys are accepted.
 - **mhsanaei/mtg-multi** — the MTProto sidecar whose TOML (`[secrets]`,
   `[secret-ad-tags]`, `[secret-limits]`) and management API
   (`PUT /secrets`, `POST /secrets/{name}/reset-quota`) `internal/mtproto/`

+ 1 - 1
CLAUDE.md

@@ -31,7 +31,7 @@ file locations when it can answer in one hop.
   built into `internal/web/dist/` (gitignored) and embedded via `embed.FS`.
 
 ## Repo map
-- `main.go` — entry point + `x-ui` CLI (run, migrate, migrate-db, setting, cert).
+- `main.go` — entry point + `x-ui` CLI (run, migrate, migrate-db, encrypt-tokens, setting, cert).
 - `internal/config/` — env parsing (XUI_DEBUG, XUI_LOG_LEVEL, XUI_LOG_FOLDER,
   XUI_BIN_FOLDER, XUI_SKIP_HSTS, XUI_PORT, XUI_DB_*).
 - `internal/database/` + `internal/database/model/` — GORM schema (~24 models;

+ 7 - 4
REVIEW.md

@@ -44,10 +44,13 @@ surface — still 🟣, but open the summary with it.
   PostgreSQL, or one that loses or overwrites operator data on upgrade or
   rollback. There are no migration files and no down-migrations.
 - A change to what the panel emits on the wire — Xray config JSON, share
-  links, subscription/Clash YAML, mtg-multi TOML — that a downstream client
-  would reject or read differently, or that makes the three independent link
-  implementations (Go `internal/util/link/` + `internal/sub/`, TS
-  `frontend/src/lib/xray/`, TS `docs/lib/xray/`) diverge from one another.
+  links, subscription/Clash YAML, mtg-multi TOML, AmneziaWG obfuscation
+  parameters — that a downstream client would reject or read differently, or
+  that makes two independent implementations of the same output diverge: the
+  three link implementations (Go `internal/util/link/` + `internal/sub/`, TS
+  `frontend/src/lib/xray/`, TS `docs/lib/xray/`), and the AmneziaWG 3.1
+  generator in Go (`internal/amneziawg/params.go`) versus TS
+  (`frontend/src/lib/xray/amneziawg-obfuscation.ts`).
 - Any edit to `.github/workflows/`: this repository runs workflows with
   secrets against a public fork stream. Untrusted expression interpolation
   into `run:` blocks, broadened permissions, weakened guards, or a job that