v0.4.0 harden jwt, scram, credential handling

doc.go

@@ -1,53 +1,20 @@
+// Package auth provides independent Argon2id password hashing, Argon2-SCRAM
+// challenge/response authentication, HS256/RS256 JWTs, and opaque token utilities.
+//
+// NewCredential provisions a SCRAM credential in one KDF pass. ScramServer holds
+// validated credential copies and bounded, single-use handshakes. ScramClient
+// performs one exchange at a time and must verify the server's final signature
+// before the application trusts the authentication result.
+//
+// The SCRAM exchange uses a package-specific Argon2id/JSON protocol; it is not
+// interoperable with the standard SASL SCRAM-SHA-256 mechanism. Applications must
+// supply authenticated TLS, request limits, rate limits, and authorization.
+//
+// NewJWT and NewJWTRSA create reusable, concurrent token managers. Configure an
+// issuer and audience for each service. ValidateToken requires expiration and a
+// nonempty subject; it returns only the nested "extra" application claims. The
+// one-off HS256 helpers retain their existing API for consumers such as chess.
+//
+// See the README and doc/security-audit.md for limits, migration, transport
+// requirements, persistence, and deployment guidance.
 package auth
-
-/*
-Package auth provides modular authentication components:
-
-# Argon2 Password Hashing
-
-Standalone password hashing using Argon2id:
-
-	hash, err := auth.HashPassword("password123")
-	err = auth.VerifyPassword("password123", hash)
-
-	// With custom parameters
-	hash, err := auth.HashPassword("password123",
-		auth.WithTime(5),
-		auth.WithMemory(128*1024))
-
-# JWT Token Management
-
-JSON Web Token generation and validation:
-
-	// HS256 (symmetric)
-	jwtMgr, _ := auth.NewJWT(secret)
-	token, _ := jwtMgr.GenerateToken("user1", claims)
-	userID, claims, _ := jwtMgr.ValidateToken(token)
-
-	// RS256 (asymmetric)
-	jwtMgr, _ := auth.NewJWTRSA(privateKey)
-
-	// One-off operations
-	token, _ := auth.GenerateHS256Token(secret, "user1", claims, 1*time.Hour)
-
-# SCRAM-SHA256 Authentication
-
-Server and client implementation for SCRAM:
-
-	// Server
-	server := auth.NewScramServer()
-	defer server.Stop()
-	server.AddCredential(credential)
-
-	// Client
-	client := auth.NewScramClient(username, password)
-
-# HTTP Authentication Parsing
-
-Utility functions for HTTP headers:
-
-	username, password, _ := auth.ParseBasicAuth(header)
-	token, _ := auth.ParseBearerToken(header)
-
-Each module can be used independently without initializing other components.
-*/