feat(api): tiered cumulative quota + self-service registration

Anonymous callers get a free cumulative quota (1000 calls per IP); once exhausted they get 403 quota_exhausted and must register. Public users can self-register (email+password) to obtain a higher-quota API key, view usage, and regenerate the key. Quota counters live in Redis; the public API stays read-only except for the registration writes. - migration 0011: app_user table + api_key.quota_total + 'registered' tier - ratelimit: IncrTotal/TotalUsed/CopyTotal lifetime counters - middleware: enforce cumulative quota + X-Quota-* headers - store: RegisterUser/Authenticate/RegenerateKey (bcrypt) - handlers: POST /api/v1/register, /account, /account/regenerate - admin: quota_total column + registered tier - public: 'API 密钥' account page + API docs quota section Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-06-21 07:26:41 +00:00
parent 7f66aad779
commit 7434e5195e
22 changed files with 1157 additions and 43 deletions
@@ -0,0 +1,169 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+)
+
+// ErrEmailTaken is returned when registering an email that already exists.
+var ErrEmailTaken = errors.New("email already registered")
+
+// Account is a self-registered public-API user and its current key metadata.
+type Account struct {
+	ID              string `json:"id"`
+	Email           string `json:"email"`
+	KeyID           string `json:"-"`
+	KeyPrefix       string `json:"key_prefix"`
+	RateLimitPerMin int    `json:"rate_limit_per_min"`
+	QuotaTotal      int64  `json:"quota_total"`
+}
+
+// bcryptDummyHash is compared against on unknown-email logins to keep timing
+// roughly constant and avoid leaking which emails are registered.
+const bcryptDummyHash = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
+
+func isUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	return errors.As(err, &pgErr) && pgErr.Code == "23505"
+}
+
+// RegisterUser creates an account plus a self-issued API key with the given
+// per-minute rate and cumulative quota, returning the plaintext key (shown
+// once). Email uniqueness is case-insensitive; ErrEmailTaken signals a dupe.
+func (s *Store) RegisterUser(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, err error) {
+	email = strings.TrimSpace(email)
+	pwHash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return "", Account{}, err
+	}
+	key, keyHash, prefix, err := apikey.Generate()
+	if err != nil {
+		return "", Account{}, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return "", Account{}, err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	var keyID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
+		 VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
+		"user:"+strings.ToLower(email), prefix, keyHash, email, ratePerMin, quotaTotal,
+	).Scan(&keyID); err != nil {
+		return "", Account{}, err
+	}
+
+	var userID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO app_user (email, password_hash, api_key_id) VALUES ($1,$2,$3) RETURNING id`,
+		email, string(pwHash), keyID,
+	).Scan(&userID); err != nil {
+		if isUniqueViolation(err) {
+			return "", Account{}, ErrEmailTaken
+		}
+		return "", Account{}, err
+	}
+
+	if err = tx.Commit(ctx); err != nil {
+		return "", Account{}, err
+	}
+	return key, Account{
+		ID: userID, Email: email, KeyID: keyID, KeyPrefix: prefix,
+		RateLimitPerMin: ratePerMin, QuotaTotal: quotaTotal,
+	}, nil
+}
+
+// Authenticate verifies an email/password pair and returns the account with its
+// current (non-revoked) key metadata. Returns ErrNotFound on unknown email or
+// wrong password.
+func (s *Store) Authenticate(ctx context.Context, email, password string) (Account, error) {
+	email = strings.TrimSpace(email)
+	var (
+		userID, pwHash string
+		keyID          *string
+	)
+	err := s.pool.QueryRow(ctx,
+		`SELECT id, password_hash, api_key_id FROM app_user WHERE lower(email) = lower($1)`, email,
+	).Scan(&userID, &pwHash, &keyID)
+	if errors.Is(err, pgx.ErrNoRows) {
+		_ = bcrypt.CompareHashAndPassword([]byte(bcryptDummyHash), []byte(password))
+		return Account{}, ErrNotFound
+	}
+	if err != nil {
+		return Account{}, err
+	}
+	if err := bcrypt.CompareHashAndPassword([]byte(pwHash), []byte(password)); err != nil {
+		return Account{}, ErrNotFound
+	}
+
+	acct := Account{ID: userID, Email: email}
+	if keyID != nil {
+		acct.KeyID = *keyID
+		_ = s.pool.QueryRow(ctx,
+			`SELECT key_prefix, rate_limit_per_min, quota_total
+			 FROM api_key WHERE id = $1 AND revoked_at IS NULL`, *keyID,
+		).Scan(&acct.KeyPrefix, &acct.RateLimitPerMin, &acct.QuotaTotal)
+	}
+	return acct, nil
+}
+
+// RegenerateKey verifies credentials, revokes the account's current key, and
+// issues a fresh one with the same rate/quota, returning the plaintext key and
+// the previous key id (so cumulative usage can be carried over). Returns
+// ErrNotFound on bad credentials.
+func (s *Store) RegenerateKey(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, oldKeyID string, err error) {
+	cur, err := s.Authenticate(ctx, email, password)
+	if err != nil {
+		return "", Account{}, "", err
+	}
+	key, keyHash, prefix, err := apikey.Generate()
+	if err != nil {
+		return "", Account{}, "", err
+	}
+
+	oldKeyID = cur.KeyID
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return "", Account{}, "", err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if oldKeyID != "" {
+		if _, err = tx.Exec(ctx,
+			`UPDATE api_key SET revoked_at = now() WHERE id = $1`, oldKeyID); err != nil {
+			return "", Account{}, "", err
+		}
+	}
+	var newKeyID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
+		 VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
+		"user:"+strings.ToLower(cur.Email), prefix, keyHash, cur.Email, ratePerMin, quotaTotal,
+	).Scan(&newKeyID); err != nil {
+		return "", Account{}, "", err
+	}
+	if _, err = tx.Exec(ctx,
+		`UPDATE app_user SET api_key_id = $1 WHERE id = $2`, newKeyID, cur.ID); err != nil {
+		return "", Account{}, "", err
+	}
+	if err = tx.Commit(ctx); err != nil {
+		return "", Account{}, "", err
+	}
+
+	cur.KeyID = newKeyID
+	cur.KeyPrefix = prefix
+	cur.RateLimitPerMin = ratePerMin
+	cur.QuotaTotal = quotaTotal
+	return key, cur, oldKeyID, nil
+}
@@ -0,0 +1,99 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+)
+
+func testStore(t *testing.T) *Store {
+	t.Helper()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		t.Skipf("database not reachable: %v", err)
+	}
+	var hasUser bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.app_user') IS NOT NULL").Scan(&hasUser); err != nil || !hasUser {
+		pool.Close()
+		t.Skip("migrations not applied")
+	}
+	t.Cleanup(pool.Close)
+	return New(pool)
+}
+
+func TestRegisterAuthenticateRegenerate(t *testing.T) {
+	s := testStore(t)
+	ctx := context.Background()
+	email := fmt.Sprintf("user-%d@example.com", time.Now().UnixNano())
+
+	t.Cleanup(func() {
+		_, _ = s.pool.Exec(ctx, "DELETE FROM app_user WHERE lower(email)=lower($1)", email)
+		_, _ = s.pool.Exec(ctx, "DELETE FROM api_key WHERE owner_email=$1", email)
+	})
+
+	key, acct, err := s.RegisterUser(ctx, email, "supersecret", 300, 100000)
+	if err != nil {
+		t.Fatalf("register: %v", err)
+	}
+	if key == "" || acct.KeyPrefix == "" || acct.QuotaTotal != 100000 || acct.RateLimitPerMin != 300 {
+		t.Fatalf("unexpected account: %+v key=%q", acct, key)
+	}
+
+	// The issued key resolves via the public auth path with its quota attached.
+	k, err := s.APIKeyByHash(ctx, apikey.Hash(key))
+	if err != nil {
+		t.Fatalf("APIKeyByHash: %v", err)
+	}
+	if k.QuotaTotal != 100000 || k.RateLimitPerMin != 300 {
+		t.Fatalf("key metadata mismatch: %+v", k)
+	}
+
+	// Duplicate email is rejected.
+	if _, _, err := s.RegisterUser(ctx, email, "anotherpass", 300, 100000); !errors.Is(err, ErrEmailTaken) {
+		t.Fatalf("expected ErrEmailTaken, got %v", err)
+	}
+
+	// Wrong password fails; correct password authenticates.
+	if _, err := s.Authenticate(ctx, email, "wrong"); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("expected ErrNotFound for bad password, got %v", err)
+	}
+	got, err := s.Authenticate(ctx, email, "supersecret")
+	if err != nil {
+		t.Fatalf("authenticate: %v", err)
+	}
+	if got.KeyPrefix != acct.KeyPrefix {
+		t.Fatalf("authenticate key prefix = %q want %q", got.KeyPrefix, acct.KeyPrefix)
+	}
+
+	// Regeneration revokes the old key and issues a new one.
+	newKey, regen, oldKeyID, err := s.RegenerateKey(ctx, email, "supersecret", 300, 100000)
+	if err != nil {
+		t.Fatalf("regenerate: %v", err)
+	}
+	if newKey == key || oldKeyID != acct.KeyID || regen.KeyID == oldKeyID {
+		t.Fatalf("regenerate did not rotate key: old=%s new=%+v", oldKeyID, regen)
+	}
+	if _, err := s.APIKeyByHash(ctx, apikey.Hash(key)); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("old key should be revoked, got %v", err)
+	}
+	if _, err := s.APIKeyByHash(ctx, apikey.Hash(newKey)); err != nil {
+		t.Fatalf("new key should be active: %v", err)
+	}
+}
@@ -453,6 +453,7 @@ type APIKey struct {
 	ID              string
 	Name            string
 	RateLimitPerMin int
+	QuotaTotal      int64
 }

 // APIKeyByHash returns the active (non-revoked) key matching a SHA-256 hash,
@@ -460,9 +461,9 @@ type APIKey struct {
 func (s *Store) APIKeyByHash(ctx context.Context, hash string) (*APIKey, error) {
 	var k APIKey
 	err := s.pool.QueryRow(ctx,
-		`SELECT id, name, rate_limit_per_min
+		`SELECT id, name, rate_limit_per_min, quota_total
 		 FROM api_key WHERE key_hash = $1 AND revoked_at IS NULL`, hash,
-	).Scan(&k.ID, &k.Name, &k.RateLimitPerMin)
+	).Scan(&k.ID, &k.Name, &k.RateLimitPerMin, &k.QuotaTotal)
 	if errors.Is(err, pgx.ErrNoRows) {
 		return nil, ErrNotFound
 	}