# WG Paid / MGTS — архитектурный план VM121 V2

## 1. Назначение

VM121 — пользовательский и коммерческий control plane.

VM121 отвечает за:

- пользователей и подтверждённые email;
- invite и их погашение;
- magic-link authentication;
- планы и права доступа;
- квоты конфигураций по протоколам;
- пользовательские connection profiles;
- WireGuard/AmneziaWG credentials;
- выдачу `.conf` и QR;
- desired state включения/отключения peer;
- provisioning jobs;
- audit;
- в будущем — платежи, продления и referrals.

VM121 не отвечает за:

- selector `cs1…cs5`;
- выбор egress/VPN slot;
- загрузку selector;
- аварийное перераспределение;
- topology state VM100/VM101.

## 2. Три слоя

```text
VM121
  identity / invite / grant / protocol quota / connection profile
  credential generation and desired peer state
                  |
                  | enable/disable without selector
                  v
VM100
  wg_paid + awg_paid inbound peer lifecycle
  protocol-aware peer validation
  one common selector ownership
  least-loaded allowed selector assignment
  topology-aware redistribution
                  |
                  v
VM101
  public UDP entry/DNAT
  selector -> mark -> table -> current egress VPN
```

## 3. Пользовательские протоколы

### WireGuard

- server interface on VM100: `wg_paid`;
- existing public endpoint currently reaches VM100 through VM101;
- protocol code: `wireguard`.

### AmneziaWG

- planned server interface on VM100: `awg_paid`;
- separate server keypair;
- separate UDP listen port;
- separate tunnel address pool;
- separate public endpoint/DNAT on VM101;
- protocol code: `amneziawg`;
- client configuration contains AWG obfuscation parameters in addition to WireGuard-compatible keys.

VM101 remains transport edge. It does not manage users or selectors for the new protocol.

## 4. Protocol-independent selector model

Selector assignment belongs to a connection profile on VM100, not to a VM121 subscription.

VM100 must support assignments for several inbound interfaces:

```text
wireguard  wg_paid   10.253.x.x  -> csN
amneziawg awg_paid  10.254.x.x  -> csN
```

The exact AWG pool is confirmed by live diagnostics before implementation.

All active protocols contribute to common selector load counts. VM100 selects among the selector classes currently permitted by topology state.

VM121 sends:

- protocol code;
- public key;
- PSK where applicable;
- tunnel IP;
- desired enabled state;
- idempotency/operation ID.

VM121 never sends `cs1…cs5`.

## 5. Quotas

A plan or invite contains per-protocol quotas:

```text
wireguard: 3
amneziawg: 3
```

This intentionally permits up to three WireGuard profiles and three AmneziaWG profiles.

The first version does not attempt to prove that six profiles represent only three physical devices. It also does not count simultaneous sessions across protocols.

Future protocols are added as rows in a protocol quota table, not as new columns.

## 6. Connection profile

One downloadable configuration is one `ConnectionProfile`.

Fields include:

- user;
- access grant;
- protocol;
- display name;
- status;
- credential revision;
- tunnel IP;
- validity;
- desired/runtime state.

The user account shows separate sections:

- WireGuard configurations: used/limit;
- AmneziaWG configurations: used/limit.

## 7. Private material

Repeated download and QR require recoverable private configuration.

Baseline:

- private key and PSK encrypted at rest;
- master key outside DB, Git, image and public reports;
- key version stored with ciphertext;
- plaintext only in memory during authenticated delivery;
- `Cache-Control: no-store`;
- no private material in logs or STEP publications.

## 8. Invite and magic link

Invite grants a reusable business entitlement template:

- plan;
- per-protocol quotas;
- invite validity;
- grant validity;
- max redemptions;
- issuer;
- note.

Registration:

```text
invite -> email -> magic link -> verified user -> access grant -> account
```

Login:

```text
email -> generic response -> one-time magic link -> session -> account
```

No password.

## 9. Payment-ready model

Invite, admin grant, migration, referral and payment all create or modify the same `AccessGrant`.

Payment integration must not create a separate provisioning model.

## 10. Migration of existing home users

1. Private inventory of current users and their existing configurations.
2. Personal invite with chosen WG/AWG quotas.
3. User verifies email and enters account.
4. User creates new WG Paid and/or AWG Paid profile.
5. New profile is verified end to end.
6. Existing home configuration remains during overlap.
7. Old access is disabled only after explicit successful migration.

## 11. Publication policy

Before publication as Project Sources:

- perform exact live read-only audit;
- resolve current DB schema and indexes;
- confirm VM100 AWG package/interface capabilities;
- confirm VM101 external UDP/DNAT requirements;
- update global roadmap;
- publish current-state/gap register and V2 documents together.