10. 顧客ポータル接続ポリシー（確定版）

10.1 親IP制

顧客ポータルへ接続できる端末は 親IP 1台のみ とする。

契約単位で以下の構造を持つ。

契約ID: A001

├ 親IP（Portalアクセス可能）
├ 子IP
└ 子IP

“`

親IPが利用できる機能

親IPのみ以下の機能を使用可能とする。

顧客ポータルログイン
```

契約情報確認
端末一覧表示
QR再発行申請
親端末変更
利用状況確認

“`

子IPの権限

子IPは以下のみ許可。

Nextcloud
```

WebDAV
VPN通信
サービス利用

“`

以下は 禁止

顧客ポータルアクセス
```

契約操作
QR再発行

10.2 親IPの初回発行

初回の親IP発行は 運営のみ実施可能。

“`

操作場所

管理ポータル（wg0）

理由

顧客が初回親端末を自由に設定できると
```

乗っ取りリスクが発生するため

“`

フロー

顧客契約作成
 │
```

管理ポータル
│
親IP発行
│
QR発行

10.3 親端末の機種変更

親端末の移行は 既存の子IPからの格上げのみ 許可。

“`

例

現在
```

A001
├ 親IP  10.201.10.2
├ 子IP  10.201.10.3
└ 子IP  10.201.10.4

“`

顧客が子IP 10.201.10.3 を選択

結果

A001
```

├ 親IP  10.201.10.3
├ 子IP  10.201.10.2
└ 子IP  10.201.10.4

“`

つまり

新親 = 選択された子IP
```

旧親 = 自動降格

10.4 親移行の条件

通常の親移行には 現在の親端末の同意が必須。

“`

操作フロー

親端末
```

│
顧客管理画面
│
子IP一覧表示
│
次の親を選択
│
親変更実行

“`

この操作は 親IPからのみ実行可能。

つまり

子IPからは親変更不可

“`

10.5 親端末紛失時

親端末が紛失した場合のみ

運営による救済操作を行う。

救済操作は wg0 管理ポータルからのみ可能。

“`

救済フロー

顧客
```

│
電話サポート
│
本人確認
│
管理画面（wg0）
│
親IP再設定
│
新QR発行

10.6 本人確認方式

親端末紛失時の救済には

本人確認パスフレーズを使用する。

登録時に顧客へ設定させる。

“`

例

本人確認パスフレーズ
```

例
・ペットの名前
・好きな食べ物
・秘密のキーワード

“`

電話認証時

顧客
```

↓
パスフレーズ回答
↓
一致
↓
親IP再設定

10.7 セキュリティ意図

この設計の目的

端末乗っ取り防止
ポータル乗っ取り防止
QR悪用防止
アカウント保護

“`

つまり

契約管理は常に1端末のみ

“`

システム内部ロジック（重要）

DBにはこのフラグを持たせます。

device_role

parent
child

“`

例

device_id
```

contract_id
wg_ip
device_role
created_at
last_seen

“`

親IP判定

ポータルアクセス時

if device_role != parent
access deny

親変更処理

BEGIN
```

old_parent → child
selected_child → parent

COMMIT

非常に良いポイント

この設計の強みは

QR盗難
端末乗っ取り
ログイン奪取

“`

をかなり防げます。

普通のVPNサービスは

ログインID
```

パスワード

“`

ですが

みーきゅんクラウドは

端末単位管理

です。

これは かなり強い設計です。

“`

次にやる候補

もしよければ次に

このシステムで一番重要な

「顧客IP管理テーブル（完全設計）」

を作ります。

“`

これができると

親IP
```

子IP
QR
契約
トラフィック

“`

全部のDBが確定します。

“`

📘 みーきゅんクラウド

顧客IP管理テーブル（完全設計）

🎯 目的

このテーブルは以下を一元管理する。

契約
親IP / 子IP
QR発行
端末状態
親変更
再発行
停止
失効
通信量

“`

つまり

顧客VPN管理の中核テーブル です。

“`

1. 基本思想

“`

1.1 契約単位

1契約 = 1顧客ID

例

A001
```

A002
A003

“`

1.2 端末単位

1契約に複数のWG IPを紐づける。

例

A001
```

├ 親IP
├ 子IP
└ 子IP

“`

1.3 親IP制

契約管理操作ができるのは 親IP 1台のみ。

“`

2. テーブル名

おすすめ:

customer_devices

3. カラム設計

“`

3.1 必須カラム

3.2 QR / 発行管理

3.3 親IP制御

※ device_role と is_parent は二重化なので、実装はどちらか片方でもよいです。

ただし検索性のため is_parent を持つのは便利です。

3.4 停止・失効管理

3.5 救済・本人確認系

3.6 通信量管理

3.7 管理メモ

“`

4. 状態定義

“`

status

“`

5. 状態遷移

issued
  ↓ 初回ハンドシェイク
active
  ↓ 一時停止
paused
  ↓ 再開
active
  ↓ 強制停止
revoked

“`

期限切れ

issued
```

↓ 24時間経過
expired

6. 親IPルール

“`

6.1 原則

1契約につき parent は1台のみ

6.2 制約

DB制約として、理想は

contract_id ごとに is_parent = true は1件のみ

6.3 親変更

通常の親変更は 親IPからのみ 実行。

処理:

旧親 is_parent = false
```

新親 is_parent = true

“`

6.4 親紛失

親紛失時のみ

管理画面（wg0）

から管理者が再設定。

“`

7. QRルール

“`

7.1 発行

新規端末発行時

status = issued
```

issued_at = 現在時刻
qr_expires_at = 現在時刻 + 24h

“`

7.2 初回接続

初回ハンドシェイクで

first_handshake_at = now
```

activated_at = now
status = active

“`

7.3 再発行

再発行時

• 旧端末 revoked
• 新端末 issued

“`

8. 親端末変更フロー

“`

通常

親IPでログイン
```

↓
子IP一覧表示
↓
次の親を選択
↓
確認
↓
親変更

“`

DB処理

BEGIN
```

UPDATE customer_devices
SET is_parent = 0, device_role = 'child'
WHERE contract_id = :contract_id
AND is_parent = 1;

UPDATE customer_devices
SET is_parent = 1,
device_role = 'parent',
parent_changed_at = NOW(),
parent_changed_by = 'customer',
parent_change_reason = 'customer self migration'
WHERE id = :selected_device_id
AND contract_id = :contract_id
AND status = 'active';

COMMIT

9. 親紛失救済フロー

顧客
↓
電話サポート
↓
本人確認パスフレーズ確認
↓
管理画面（wg0）
↓
子IPまたは新IPを親へ設定

“`

管理側ログ

parent_changed_by = 'admin'
```

parent_change_reason = 'lost parent recovery'
recovery_completed_at = now

10. 削除通知を送らないボタンとの連携

これは契約テーブル側が本体ですが、端末管理とも連携するためここでも整理します。

“`

契約テーブル側で持つ項目

predelete_notice_suppressed
```

predelete_notice_suppressed_reason
predelete_notice_suppressed_at
predelete_notice_suppressed_by

“`

用途

• 電話で本人確認済み
• 本人希望で通知不要
• 即時削除
• 個別連絡済み
• 迷惑利用対応

“`

11. インデックス

最低これを貼ります。

CREATE INDEX idx_customer_devices_contract_id
  ON customer_devices(contract_id);

CREATE INDEX idx_customer_devices_wg_ip
ON customer_devices(wg_ip);

CREATE UNIQUE INDEX uq_customer_devices_public_key
ON customer_devices(public_key);

CREATE INDEX idx_customer_devices_status
ON customer_devices(status);

CREATE INDEX idx_customer_devices_last_handshake
ON customer_devices(last_handshake_at);

12. 実用上のおすすめ追加カラム

あると後で助かるもの。

13. SQLたたき台

CREATE TABLE customer_devices (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  contract_id VARCHAR(32) NOT NULL,
  device_id VARCHAR(64) NOT NULL,
  wg_iface VARCHAR(32) NOT NULL DEFAULT 'wg1',
  wg_ip VARCHAR(64) NOT NULL,
  public_key TEXT NOT NULL,
  preshared_key TEXT NULL,

device_role VARCHAR(16) NOT NULL DEFAULT 'child',
is_parent BOOLEAN NOT NULL DEFAULT FALSE,
status VARCHAR(16) NOT NULL DEFAULT 'issued',

device_name VARCHAR(128) NULL,
platform VARCHAR(64) NULL,

issued_at DATETIME NULL,
qr_expires_at DATETIME NULL,
first_handshake_at DATETIME NULL,
last_handshake_at DATETIME NULL,
activated_at DATETIME NULL,

parent_changed_at DATETIME NULL,
parent_changed_by VARCHAR(64) NULL,
parent_change_reason VARCHAR(255) NULL,

paused_at DATETIME NULL,
pause_reason VARCHAR(255) NULL,
pause_expires_at DATETIME NULL,
revoked_at DATETIME NULL,
revoked_reason VARCHAR(255) NULL,
expired_at DATETIME NULL,

recovery_required BOOLEAN NOT NULL DEFAULT FALSE,
recovery_requested_at DATETIME NULL,
recovery_completed_at DATETIME NULL,
recovery_by VARCHAR(64) NULL,

rx_bytes_total BIGINT NOT NULL DEFAULT 0,
tx_bytes_total BIGINT NOT NULL DEFAULT 0,
rx_bytes_24h BIGINT NOT NULL DEFAULT 0,
tx_bytes_24h BIGINT NOT NULL DEFAULT 0,
rx_bytes_7d BIGINT NOT NULL DEFAULT 0,
tx_bytes_7d BIGINT NOT NULL DEFAULT 0,
current_rx_bps BIGINT NOT NULL DEFAULT 0,
current_tx_bps BIGINT NOT NULL DEFAULT 0,

portal_access_enabled BOOLEAN NOT NULL DEFAULT FALSE,
bandwidth_profile VARCHAR(64) NULL,

notes TEXT NULL,
admin_tags VARCHAR(255) NULL,
deleted_at DATETIME NULL,

created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

14. 運用ルールの一文

customer_devices テーブルは、契約単位の WireGuard 端末管理の中核テーブルとし、親IP/子IP、QR発行状態、停止・失効状態、通信量、親変更履歴、救済操作履歴を一元管理する。顧客ポータルへのアクセス可否は親IPのみに限定し、通常の親変更は親端末からのみ実行可能とする。親端末紛失時のみ、管理画面（wg0）から本人確認パスフレーズを用いて救済操作を行う。

次の作業

次は contracts テーブル と delete queue / notice suppression を含む契約管理テーブル を続けて固めます。