@opengroundplan/core 0.1.1

package/templates/layers/auth-jwt/files/internal/auth/service.go

@@ -0,0 +1,213 @@
+// Package auth issues and verifies this service's own JWT access tokens, hashes passwords
+// with Argon2id, and rotates opaque refresh tokens with replay detection.
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/hex"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Refresh tokens are opaque "id.secret", not JWTs — they must be revocable server-side.
+const (
+	refreshSecretBytes = 32
+	separator          = "."
+)
+
+type TokenPair struct {
+	AccessToken  string
+	RefreshToken string
+	ExpiresIn    time.Duration
+}
+
+type Principal struct {
+	ID    string
+	Email string
+	Roles []string
+}
+
+type Service struct {
+	config  Config
+	users   UserStore
+	refresh RefreshTokenStore
+	tokens  TokenIssuer
+	hasher  Hasher
+
+	decoyOnce sync.Once
+	decoyHash string
+}
+
+func NewService(config Config, users UserStore, refresh RefreshTokenStore) *Service {
+	return &Service{
+		config:  config,
+		users:   users,
+		refresh: refresh,
+		tokens:  NewTokenIssuer(config),
+		hasher:  NewHasher(config),
+	}
+}
+
+func (s *Service) Register(ctx context.Context, email, password string, roles []string) (*Principal, error) {
+	existing, err := s.users.FindByEmail(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+	// Same error as a bad login, so registration cannot be used to enumerate accounts.
+	if existing != nil {
+		return nil, ErrInvalidCredentials
+	}
+
+	id, err := RandomID()
+	if err != nil {
+		return nil, err
+	}
+	hash, err := s.hasher.Hash(password)
+	if err != nil {
+		return nil, err
+	}
+
+	user, err := s.users.Create(ctx, UserRecord{
+		ID:           id,
+		Email:        NormalizeEmail(email),
+		PasswordHash: hash,
+		Roles:        roles,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &Principal{ID: user.ID, Email: user.Email, Roles: user.Roles}, nil
+}
+
+func (s *Service) Login(ctx context.Context, email, password string) (*TokenPair, error) {
+	user, err := s.users.FindByEmail(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+
+	// Verify against a decoy when the account is unknown, so both paths cost one Argon2 pass.
+	stored := s.decoy()
+	if user != nil {
+		stored = user.PasswordHash
+	}
+	if !s.hasher.Verify(stored, password) || user == nil {
+		return nil, ErrInvalidCredentials
+	}
+
+	sid, err := RandomID()
+	if err != nil {
+		return nil, err
+	}
+	return s.issue(ctx, *user, sid)
+}
+
+// Refresh rotates the pair. Presenting a spent token means it leaked, so the session dies.
+func (s *Service) Refresh(ctx context.Context, refreshToken string) (*TokenPair, error) {
+	id, secret, ok := strings.Cut(refreshToken, separator)
+	if !ok || id == "" {
+		return nil, ErrInvalidToken
+	}
+
+	record, err := s.refresh.FindByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now()
+	if record == nil || record.RevokedAt != nil || !record.ExpiresAt.After(now) {
+		return nil, ErrInvalidToken
+	}
+	if subtle.ConstantTimeCompare([]byte(record.SecretHash), []byte(hashSecret(secret))) != 1 {
+		return nil, ErrInvalidToken
+	}
+
+	if record.UsedAt != nil {
+		if err := s.refresh.RevokeSession(ctx, record.SID, now); err != nil {
+			return nil, err
+		}
+		return nil, ErrRefreshReused
+	}
+
+	user, err := s.users.FindByID(ctx, record.UserID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil {
+		return nil, ErrInvalidToken
+	}
+
+	if err := s.refresh.MarkUsed(ctx, record.ID, now); err != nil {
+		return nil, err
+	}
+	return s.issue(ctx, *user, record.SID)
+}
+
+func (s *Service) Logout(ctx context.Context, refreshToken string) error {
+	id, _, ok := strings.Cut(refreshToken, separator)
+	if !ok {
+		return nil
+	}
+
+	record, err := s.refresh.FindByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	// Silent on unknown tokens: logout must not report whether a session existed.
+	if record == nil {
+		return nil
+	}
+	return s.refresh.RevokeSession(ctx, record.SID, time.Now())
+}
+
+func (s *Service) VerifyAccess(raw string) (*AccessClaims, error) { return s.tokens.VerifyAccess(raw) }
+
+func (s *Service) issue(ctx context.Context, user UserRecord, sid string) (*TokenPair, error) {
+	id, err := RandomID()
+	if err != nil {
+		return nil, err
+	}
+	secret, err := randomString(refreshSecretBytes)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.refresh.Save(ctx, RefreshRecord{
+		ID:         id,
+		UserID:     user.ID,
+		SID:        sid,
+		SecretHash: hashSecret(secret),
+		ExpiresAt:  time.Now().Add(s.config.RefreshTTL),
+	}); err != nil {
+		return nil, err
+	}
+
+	access, err := s.tokens.SignAccess(user.ID, sid, user.Roles)
+	if err != nil {
+		return nil, err
+	}
+
+	return &TokenPair{
+		AccessToken:  access,
+		RefreshToken: id + separator + secret,
+		ExpiresIn:    s.config.AccessTTL,
+	}, nil
+}
+
+// Built once; rebuilding per login would make unknown accounts slower, not equal.
+func (s *Service) decoy() string {
+	s.decoyOnce.Do(func() {
+		filler, err := RandomID()
+		if err != nil {
+			return
+		}
+		s.decoyHash, _ = s.hasher.Hash(filler)
+	})
+	return s.decoyHash
+}
+
+func hashSecret(secret string) string {
+	sum := sha256.Sum256([]byte(secret))
+	return hex.EncodeToString(sum[:])
+}

package/templates/layers/auth-jwt/files/internal/auth/store.go

@@ -0,0 +1,138 @@
+package auth
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The layer ships interfaces plus an in-memory implementation, so it composes with
+// whatever database layer the repo chose — or none, during development.
+
+type UserRecord struct {
+	ID           string
+	Email        string
+	PasswordHash string
+	Roles        []string
+}
+
+type RefreshRecord struct {
+	ID     string
+	UserID string
+	// SID groups every rotation of one login.
+	SID string
+	// SecretHash is SHA-256 of the secret half — the plaintext is never stored.
+	SecretHash string
+	ExpiresAt  time.Time
+	UsedAt     *time.Time
+	RevokedAt  *time.Time
+}
+
+type UserStore interface {
+	FindByEmail(ctx context.Context, email string) (*UserRecord, error)
+	FindByID(ctx context.Context, id string) (*UserRecord, error)
+	Create(ctx context.Context, user UserRecord) (*UserRecord, error)
+}
+
+type RefreshTokenStore interface {
+	Save(ctx context.Context, record RefreshRecord) error
+	FindByID(ctx context.Context, id string) (*RefreshRecord, error)
+	MarkUsed(ctx context.Context, id string, at time.Time) error
+	// RevokeSession kills every token in a session — logout and replay detection.
+	RevokeSession(ctx context.Context, sid string, at time.Time) error
+}
+
+func NormalizeEmail(email string) string { return strings.ToLower(strings.TrimSpace(email)) }
+
+// InMemoryUserStore is development and test only: process memory, so every restart
+// logs everyone out.
+type InMemoryUserStore struct {
+	mu   sync.RWMutex
+	byID map[string]UserRecord
+}
+
+func (s *InMemoryUserStore) FindByEmail(_ context.Context, email string) (*UserRecord, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	needle := NormalizeEmail(email)
+	for _, user := range s.byID {
+		if NormalizeEmail(user.Email) == needle {
+			found := user
+			return &found, nil
+		}
+	}
+	return nil, nil
+}
+
+func (s *InMemoryUserStore) FindByID(_ context.Context, id string) (*UserRecord, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if user, ok := s.byID[id]; ok {
+		return &user, nil
+	}
+	return nil, nil
+}
+
+func (s *InMemoryUserStore) Create(_ context.Context, user UserRecord) (*UserRecord, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.byID == nil {
+		s.byID = map[string]UserRecord{}
+	}
+	s.byID[user.ID] = user
+	return &user, nil
+}
+
+type InMemoryRefreshTokenStore struct {
+	mu   sync.RWMutex
+	byID map[string]RefreshRecord
+}
+
+func (s *InMemoryRefreshTokenStore) Save(_ context.Context, record RefreshRecord) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.byID == nil {
+		s.byID = map[string]RefreshRecord{}
+	}
+	s.byID[record.ID] = record
+	return nil
+}
+
+func (s *InMemoryRefreshTokenStore) FindByID(_ context.Context, id string) (*RefreshRecord, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if record, ok := s.byID[id]; ok {
+		return &record, nil
+	}
+	return nil, nil
+}
+
+func (s *InMemoryRefreshTokenStore) MarkUsed(_ context.Context, id string, at time.Time) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if record, ok := s.byID[id]; ok {
+		record.UsedAt = &at
+		s.byID[id] = record
+	}
+	return nil
+}
+
+func (s *InMemoryRefreshTokenStore) RevokeSession(_ context.Context, sid string, at time.Time) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	for id, record := range s.byID {
+		if record.SID == sid && record.RevokedAt == nil {
+			record.RevokedAt = &at
+			s.byID[id] = record
+		}
+	}
+	return nil
+}

package/templates/layers/auth-jwt/files/internal/auth/token.go

@@ -0,0 +1,83 @@
+package auth
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// 128 bits — the floor for a value an attacker may guess offline.
+const idBytes = 16
+
+type AccessClaims struct {
+	// SID is the session id, shared with the refresh-token family so one logout kills both.
+	SID   string   `json:"sid"`
+	Roles []string `json:"roles"`
+	jwt.RegisteredClaims
+}
+
+type TokenIssuer struct{ config Config }
+
+func NewTokenIssuer(config Config) TokenIssuer { return TokenIssuer{config: config} }
+
+func (t TokenIssuer) SignAccess(subject, sid string, roles []string) (string, error) {
+	now := time.Now()
+	jti, err := RandomID()
+	if err != nil {
+		return "", err
+	}
+
+	claims := AccessClaims{
+		SID:   sid,
+		Roles: roles,
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   subject,
+			Issuer:    t.config.Issuer,
+			Audience:  jwt.ClaimStrings{t.config.Audience},
+			IssuedAt:  jwt.NewNumericDate(now),
+			NotBefore: jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(t.config.AccessTTL)),
+			ID:        jti,
+		},
+	}
+	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(t.config.Secret)
+}
+
+func (t TokenIssuer) VerifyAccess(raw string) (*AccessClaims, error) {
+	claims := &AccessClaims{}
+
+	_, err := jwt.ParseWithClaims(raw, claims, func(*jwt.Token) (any, error) {
+		return t.config.Secret, nil
+	},
+		// Allow-list the algorithm: without it a token may nominate its own.
+		jwt.WithValidMethods([]string{JWTAlgorithm}),
+		jwt.WithIssuer(t.config.Issuer),
+		jwt.WithAudience(t.config.Audience),
+		jwt.WithExpirationRequired(),
+	)
+	if err != nil {
+		if errors.Is(err, jwt.ErrTokenExpired) {
+			return nil, ErrTokenExpired
+		}
+		return nil, ErrInvalidToken
+	}
+
+	// A valid signature proves the payload is ours, not that it carries what we need.
+	if claims.Subject == "" || claims.SID == "" {
+		return nil, ErrInvalidToken
+	}
+	return claims, nil
+}
+
+func RandomID() (string, error) { return randomString(idBytes) }
+
+func randomString(size int) (string, error) {
+	buffer := make([]byte, size)
+	if _, err := rand.Read(buffer); err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(buffer), nil
+}

package/templates/layers/auth-jwt/files/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "jose": "^6.2.3",
+    "@node-rs/argon2": "^2.0.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
+}

package/templates/layers/auth-jwt/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["pyjwt>=2.13.0", "pwdlib[argon2]>=0.3.0"]

package/templates/layers/auth-jwt/files/src/__solutionName.dot__.Auth/AuthException.cs

@@ -0,0 +1,39 @@
+using Microsoft.AspNetCore.Http;
+
+namespace {{ solutionName | dot }}.Auth;
+
+public enum AuthErrorCode
+{
+    MissingToken,
+    InvalidToken,
+    TokenExpired,
+    InvalidCredentials,
+    RefreshReused,
+    Forbidden,
+}
+
+/// <summary>
+/// Carries a stable code and HTTP status. Never widen the code for anything the client
+/// sees — naming the failing check turns login into a user enumeration oracle.
+/// </summary>
+public sealed class AuthException(AuthErrorCode code) : Exception(code.ToString())
+{
+    /// <summary>Wire codes match the other stacks this layer targets.</summary>
+    private static readonly Dictionary<AuthErrorCode, string> Wires = new()
+    {
+        [AuthErrorCode.MissingToken] = "missing_token",
+        [AuthErrorCode.InvalidToken] = "invalid_token",
+        [AuthErrorCode.TokenExpired] = "token_expired",
+        [AuthErrorCode.InvalidCredentials] = "invalid_credentials",
+        [AuthErrorCode.RefreshReused] = "refresh_reused",
+        [AuthErrorCode.Forbidden] = "forbidden",
+    };
+
+    public AuthErrorCode Code { get; } = code;
+
+    public string Wire => Wires[Code];
+
+    public int Status => Code == AuthErrorCode.Forbidden
+        ? StatusCodes.Status403Forbidden
+        : StatusCodes.Status401Unauthorized;
+}

package/templates/layers/auth-jwt/files/src/__solutionName.dot__.Auth/AuthOptions.cs

@@ -0,0 +1,35 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace {{ solutionName | dot }}.Auth;
+
+/// <summary>Bound from the "Auth" configuration section — the only place a default lives.</summary>
+public sealed class AuthOptions
+{
+    public const string SectionName = "Auth";
+
+    /// <summary>HS256 gains nothing from a key shorter than its digest.</summary>
+    public const int MinSecretBytes = 32;
+
+    [Required, MinLength(MinSecretBytes)]
+    public string Secret { get; init; } = string.Empty;
+
+    [Required]
+    public string Issuer { get; init; } = "{{ solutionName | kebab }}";
+
+    [Required]
+    public string Audience { get; init; } = "{{ solutionName | kebab }}";
+
+    [Range(1, int.MaxValue)]
+    public int AccessTtlSeconds { get; init; } = {{ authAccessTtlSeconds }};
+
+    [Range(1, int.MaxValue)]
+    public int RefreshTtlSeconds { get; init; } = {{ authRefreshTtlSeconds }};
+
+    /// <summary>OWASP minimum for PBKDF2-HMAC-SHA256.</summary>
+    [Range(1, int.MaxValue)]
+    public int Pbkdf2Iterations { get; init; } = 600_000;
+
+    public TimeSpan AccessTtl => TimeSpan.FromSeconds(AccessTtlSeconds);
+
+    public TimeSpan RefreshTtl => TimeSpan.FromSeconds(RefreshTtlSeconds);
+}

package/templates/layers/auth-jwt/files/src/__solutionName.dot__.Auth/AuthService.cs

@@ -0,0 +1,132 @@
+using System.Security.Cryptography;
+using System.Text;
+using Microsoft.Extensions.Options;
+
+namespace {{ solutionName | dot }}.Auth;
+
+public sealed record TokenPair(string AccessToken, string RefreshToken, int ExpiresIn);
+
+public sealed record Principal(string Id, string Email, IReadOnlyList<string> Roles);
+
+public sealed class AuthService(
+    IOptions<AuthOptions> options,
+    IUserStore users,
+    IRefreshTokenStore refreshTokens,
+    JwtTokenService tokens,
+    PasswordHasher hasher)
+{
+    // Refresh tokens are opaque "id.secret", not JWTs — they must be revocable server-side.
+    private const int RefreshSecretBytes = 32;
+    private const char Separator = '.';
+
+    private readonly AuthOptions _options = options.Value;
+    private readonly Lazy<string> _decoyHash = new(() => hasher.Hash(NewId()));
+
+    public async Task<Principal> RegisterAsync(
+        string email,
+        string password,
+        IReadOnlyList<string>? roles = null,
+        CancellationToken ct = default)
+    {
+        // Same error as a bad login, so registration cannot be used to enumerate accounts.
+        if (await users.FindByEmailAsync(email, ct) is not null)
+        {
+            throw new AuthException(AuthErrorCode.InvalidCredentials);
+        }
+
+        var user = await users.CreateAsync(
+            new UserRecord(NewId(), InMemoryUserStore.Normalize(email), hasher.Hash(password), roles ?? []),
+            ct);
+
+        return new Principal(user.Id, user.Email, user.Roles);
+    }
+
+    public async Task<TokenPair> LoginAsync(string email, string password, CancellationToken ct = default)
+    {
+        var user = await users.FindByEmailAsync(email, ct);
+
+        // Verify against a decoy when the account is unknown, so both paths cost one KDF pass.
+        var ok = PasswordHasher.Verify(user?.PasswordHash ?? _decoyHash.Value, password);
+        if (user is null || !ok)
+        {
+            throw new AuthException(AuthErrorCode.InvalidCredentials);
+        }
+
+        return await IssueAsync(user, NewId(), ct);
+    }
+
+    /// <summary>Rotates the pair. Presenting a spent token means it leaked, so the session dies.</summary>
+    public async Task<TokenPair> RefreshAsync(string refreshToken, CancellationToken ct = default)
+    {
+        var (id, secret) = Split(refreshToken);
+        var record = await refreshTokens.FindByIdAsync(id, ct);
+        var now = DateTimeOffset.UtcNow;
+
+        if (record is null || record.RevokedAt is not null || record.ExpiresAt <= now)
+        {
+            throw new AuthException(AuthErrorCode.InvalidToken);
+        }
+
+        if (!CryptographicOperations.FixedTimeEquals(
+                Convert.FromHexString(record.SecretHash), HashSecret(secret)))
+        {
+            throw new AuthException(AuthErrorCode.InvalidToken);
+        }
+
+        if (record.UsedAt is not null)
+        {
+            await refreshTokens.RevokeSessionAsync(record.Sid, now, ct);
+            throw new AuthException(AuthErrorCode.RefreshReused);
+        }
+
+        var user = await users.FindByIdAsync(record.UserId, ct)
+            ?? throw new AuthException(AuthErrorCode.InvalidToken);
+
+        await refreshTokens.MarkUsedAsync(record.Id, now, ct);
+        return await IssueAsync(user, record.Sid, ct);
+    }
+
+    public async Task LogoutAsync(string refreshToken, CancellationToken ct = default)
+    {
+        var (id, _) = Split(refreshToken);
+        var record = await refreshTokens.FindByIdAsync(id, ct);
+
+        // Silent on unknown tokens: logout must not report whether a session existed.
+        if (record is not null)
+        {
+            await refreshTokens.RevokeSessionAsync(record.Sid, DateTimeOffset.UtcNow, ct);
+        }
+    }
+
+    private async Task<TokenPair> IssueAsync(UserRecord user, string sid, CancellationToken ct)
+    {
+        var id = NewId();
+        var secret = Convert.ToHexString(RandomNumberGenerator.GetBytes(RefreshSecretBytes));
+
+        await refreshTokens.SaveAsync(
+            new RefreshRecord(id, user.Id, sid, Convert.ToHexString(HashSecret(secret)),
+                DateTimeOffset.UtcNow.Add(_options.RefreshTtl)),
+            ct);
+
+        return new TokenPair(
+            tokens.CreateAccessToken(user.Id, sid, user.Roles),
+            string.Concat(id, Separator, secret),
+            _options.AccessTtlSeconds);
+    }
+
+    // Hashes the raw string: a client-supplied secret must never reach a format-strict parser.
+    private static byte[] HashSecret(string secret) => SHA256.HashData(Encoding.UTF8.GetBytes(secret));
+
+    private static string NewId() => Convert.ToHexString(RandomNumberGenerator.GetBytes(16));
+
+    private static (string Id, string Secret) Split(string refreshToken)
+    {
+        var at = refreshToken.IndexOf(Separator);
+        if (at <= 0)
+        {
+            throw new AuthException(AuthErrorCode.InvalidToken);
+        }
+
+        return (refreshToken[..at], refreshToken[(at + 1)..]);
+    }
+}

package/templates/layers/auth-jwt/files/src/__solutionName.dot__.Auth/AuthServiceCollectionExtensions.cs

@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+
+namespace {{ solutionName | dot }}.Auth;
+
+public static class AuthServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers the auth stack and the JwtBearer scheme. Options are validated at startup
+    /// so a missing secret fails the boot rather than the first login.
+    /// </summary>
+    public static IServiceCollection AddJwtAuth(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddOptions<AuthOptions>()
+            .Bind(configuration.GetSection(AuthOptions.SectionName))
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        services.AddSingleton<JwtTokenService>();
+        services.AddSingleton<PasswordHasher>();
+        services.AddScoped<AuthService>();
+
+        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer();
+
+        // Configured through the options pipeline so AuthOptions is injected rather than
+        // resolved from a second container built during registration.
+        services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
+            .Configure<IOptions<AuthOptions>>((jwt, auth) =>
+            {
+                jwt.TokenValidationParameters = JwtTokenService.ValidationParameters(auth.Value);
+                // Keep the raw "sub"/"roles" names instead of the legacy SOAP claim URIs.
+                jwt.MapInboundClaims = false;
+            });
+
+        services.AddAuthorization();
+        return services;
+    }
+
+    /// <summary>Registers the process-memory stores. Replace both before shipping.</summary>
+    public static IServiceCollection AddInMemoryAuthStores(this IServiceCollection services)
+    {
+        services.AddSingleton<IUserStore, InMemoryUserStore>();
+        services.AddSingleton<IRefreshTokenStore, InMemoryRefreshTokenStore>();
+        return services;
+    }
+}