wangjia
afcd7b325c
Implements server/internal/codes/ with all required functionality:
## Generator (generator.go)
- Crockford Base32 16-char codes (15 data + 1 Crockford mod-37 check char)
- crypto/rand for unbiased random generation with rejection sampling
- Canonicalize(): I/L→1, O→0 folding, hyphen/space stripping
- Hash(): SHA-256 of canonical plaintext (only value stored in DB)
- Algorithm hard-coded; check char detects all single-char substitution errors
## Store (store.go)
- MySQL-backed via database/sql
- CreateBatch / CreateCode with ErrDuplicate on UNIQUE conflict
- FindCodeByHashForUpdate: SELECT … FOR UPDATE for row-level concurrency control
- MarkRedeemed, ExtendSubscription, CreateSubscription, GetActiveSubscriptions
- WriteAuditLog, CodeExistsByHash
- BeginTx at READ COMMITTED (FOR UPDATE provides row exclusivity)
## Service (service.go)
- Redeem(): 9-step flow with full idempotency and concurrency safety
- isLocked / recordFail / clearFail via Redis key redeem:fail:{user_id}
- SELECT … FOR UPDATE → single winner under N-concurrent redemptions
- Same-plan: extends existing subscription (max(expires_at,now)+days)
- Cross-plan: creates new subscription (max(now,latest)+days)
- Idempotent: same user re-submits → 200 without re-applying
- 5 failures → ACCOUNT_LOCKED for 1 hour (sliding window via Redis)
- CreateBatch(): generates N codes, stores hashes, returns plaintext once
- Automatic retry on hash collision (birthday probability ≈10⁻⁸)
## Webhook (webhook.go)
- POST /webhook/store/codes — outside /v1, no JWT required
- HMAC-SHA256 with hmac.Equal constant-time comparison
- ±5 min timestamp window
- Redis SetNX nonce deduplication (15-min TTL)
- Idempotent: duplicate nonce → 200; duplicate code_hash → 200
## HTTP Handler (handler.go)
- POST /v1/redeem endpoint wired to Service.Redeem
- Reads userID from context key (set by JWT middleware from auth module)
- Bilingual error responses {code, message_zh, message_en}
## Export (export.go)
- ExportCSV(): streams plaintext codes to io.Writer as CSV
- Plaintext NEVER stored in DB; only SHA-256 hash persists
## CLI (cmd/codegen/main.go)
- codegen -plan -days -count -channel -note -dsn [-out]
- Transition tool until admin panel (#8) is ready
- Outputs CSV to stdout or file; warns operator about plaintext sensitivity
## Infrastructure (skeleton)
- internal/config/config.go: env-var configuration
- internal/db/db.go: MySQL connection pool helper
- internal/redisutil/redis.go: Redis client constructor
- internal/apierr/apierr.go: bilingual error types
- migrations/001_init.sql: DDL for codes module tables
- go.mod with all dependencies
## Tests
- generator_test.go (unit, no deps):
- Format, uniqueness (10k codes, zero collisions), normalization,
check-char detection of all single-char errors, hash consistency
- webhook_test.go (unit, no deps):
- Signature rejection, missing signature, stale/future timestamp,
missing nonce, constant-time HMAC comparison
- service_test.go (//go:build integration, testcontainers):
- N=20 concurrent redeemers → exactly 1 winner
- Idempotent redeem returns success for same user
- Other-user redemption → CODE_REDEEMED + failure counted
- 5 failures → ACCOUNT_LOCKED on 6th attempt
- Same-plan extension: expires_at precision assertion
- Cross-plan creation: new subscription row
- Audit log written on every successful redemption
- CSV export: no plaintext in DB, hash present
- Webhook nonce replay: idempotent 200
- Webhook same-hash: idempotent 200, single DB row
Run unit tests: make test
Run integration tests: make test-integration (requires Docker)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
95 lines
4.4 KiB
SQL
95 lines
4.4 KiB
SQL
-- Migration 001: baseline schema for the codes module and its dependencies.
|
|
-- MySQL 8.x · InnoDB · utf8mb4 · UTC
|
|
-- Apply with: mysql -u root -p pangolin < migrations/001_init.sql
|
|
|
|
SET time_zone = '+00:00';
|
|
|
|
-- -------------------------------------------------------------------------
|
|
-- Core account tables (needed by foreign keys from subscriptions)
|
|
-- -------------------------------------------------------------------------
|
|
|
|
CREATE TABLE IF NOT EXISTS users (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
uuid CHAR(36) NOT NULL UNIQUE, -- public-facing identifier
|
|
email VARCHAR(255) NOT NULL UNIQUE,
|
|
pw_hash VARCHAR(255) NOT NULL, -- argon2id
|
|
dp_uuid CHAR(36) NOT NULL, -- data-plane UUID (sing-box)
|
|
status ENUM('active','banned') NOT NULL DEFAULT 'active',
|
|
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
|
|
-- -------------------------------------------------------------------------
|
|
-- Plan catalogue (digital values per design/CLAUDE.md §7)
|
|
-- -------------------------------------------------------------------------
|
|
|
|
CREATE TABLE IF NOT EXISTS plans (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
code ENUM('free','pro','team') NOT NULL UNIQUE,
|
|
max_devices INT NOT NULL, -- free 1 / pro 5 / team 10
|
|
daily_minutes INT NULL, -- free 10; NULL = unlimited
|
|
ad_gate BOOLEAN NOT NULL DEFAULT FALSE -- free users must watch an ad daily
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
|
|
INSERT IGNORE INTO plans (code, max_devices, daily_minutes, ad_gate) VALUES
|
|
('free', 1, 10, TRUE),
|
|
('pro', 5, NULL, FALSE),
|
|
('team', 10, NULL, FALSE);
|
|
|
|
-- -------------------------------------------------------------------------
|
|
-- Subscriptions
|
|
-- -------------------------------------------------------------------------
|
|
|
|
CREATE TABLE IF NOT EXISTS subscriptions (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
user_id BIGINT UNSIGNED NOT NULL,
|
|
plan_id BIGINT UNSIGNED NOT NULL,
|
|
expires_at DATETIME(6) NOT NULL,
|
|
source ENUM('trial','code') NOT NULL,
|
|
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
|
|
FOREIGN KEY (user_id) REFERENCES users(id),
|
|
FOREIGN KEY (plan_id) REFERENCES plans(id),
|
|
INDEX idx_user_exp (user_id, expires_at)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
|
|
-- -------------------------------------------------------------------------
|
|
-- Activation-code tables
|
|
-- -------------------------------------------------------------------------
|
|
|
|
CREATE TABLE IF NOT EXISTS code_batches (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
channel ENUM('store','tg','line','manual') NOT NULL,
|
|
created_by VARCHAR(64) NOT NULL,
|
|
note VARCHAR(255) NULL,
|
|
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
|
|
CREATE TABLE IF NOT EXISTS codes (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
-- SHA-256(canonical_plaintext) stored as 64-char hex.
|
|
-- Plaintext NEVER stored in any column.
|
|
code_hash CHAR(64) NOT NULL UNIQUE,
|
|
plan_id BIGINT UNSIGNED NOT NULL,
|
|
duration_days INT NOT NULL,
|
|
batch_id BIGINT UNSIGNED NOT NULL,
|
|
status ENUM('unused','redeemed','void') NOT NULL DEFAULT 'unused',
|
|
redeemed_by BIGINT UNSIGNED NULL, -- FK to users.id (not enforced to avoid
|
|
redeemed_at DATETIME(6) NULL, -- locking the users table on redeem)
|
|
FOREIGN KEY (plan_id) REFERENCES plans(id),
|
|
FOREIGN KEY (batch_id) REFERENCES code_batches(id),
|
|
INDEX idx_status (status)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
|
|
-- -------------------------------------------------------------------------
|
|
-- Audit log (all sensitive operations must be recorded)
|
|
-- -------------------------------------------------------------------------
|
|
|
|
CREATE TABLE IF NOT EXISTS audit_log (
|
|
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
|
actor VARCHAR(64) NOT NULL, -- e.g. "user:123" or "admin:7"
|
|
action VARCHAR(64) NOT NULL, -- e.g. "redeem", "ban", "node_drain"
|
|
target VARCHAR(128) NOT NULL, -- abbreviated; never contains plaintext codes
|
|
meta JSON NULL, -- structured context (no PII beyond IDs)
|
|
at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
|
|
INDEX idx_at (at)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|