go-authgate
diff --git a/‎.env.example‎
Lines changed: 13 additions & 0 deletions b/‎.env.example‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions b/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/ARCHITECTURE.md‎
Lines changed: 14 additions & 0 deletions b/‎docs/ARCHITECTURE.md‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎docs/CONFIGURATION.md‎
Lines changed: 49 additions & 0 deletions b/‎docs/CONFIGURATION.md‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎internal/config/config.go‎
Lines changed: 115 additions & 7 deletions b/‎internal/config/config.go‎
Lines changed: 115 additions & 7 deletions
@@ -29,6 +29,19 @@ SESSION_SECRET=session-secret-change-in-production
 # JWT_EXPIRATION_JITTER=30m        # Max random jitter added to access token expiry (default: 30m)
 #                                  # Prevents thundering herd when many tokens expire simultaneously
 #                                  # Example: JWT_EXPIRATION=8h + JWT_EXPIRATION_JITTER=30m → token lifetime [8h, 8h30m)
+# JWT_EXPIRATION_MAX=24h           # Hard cap on any token profile's access TTL (default: 24h). Startup fails if a profile exceeds this.
+# REFRESH_TOKEN_EXPIRATION_MAX=2160h # Hard cap on any token profile's refresh TTL (default: 2160h / 90 days).
+
+# Token Profiles — per-OAuthApplication TTL presets (short / standard / long).
+# Each OAuth client selects one profile via the "Token Lifetime" admin UI; tokens
+# issued for that client use the preset's access & refresh TTLs. The "standard"
+# profile inherits JWT_EXPIRATION / REFRESH_TOKEN_EXPIRATION by default.
+# TOKEN_PROFILE_SHORT_ACCESS_TTL=15m    # Short access token TTL (default: 15m)
+# TOKEN_PROFILE_SHORT_REFRESH_TTL=24h   # Short refresh token TTL (default: 24h)
+# TOKEN_PROFILE_STANDARD_ACCESS_TTL=    # Defaults to JWT_EXPIRATION
+# TOKEN_PROFILE_STANDARD_REFRESH_TTL=   # Defaults to REFRESH_TOKEN_EXPIRATION
+# TOKEN_PROFILE_LONG_ACCESS_TTL=24h     # Long access token TTL (default: 24h)
+# TOKEN_PROFILE_LONG_REFRESH_TTL=2160h  # Long refresh token TTL (default: 2160h / 90 days)
 
 # Database
 DATABASE_DRIVER=sqlite
 
@@ -109,6 +109,7 @@ In addition to Device Code Flow, AuthGate supports Authorization Code Flow with
 
 - `OAuthApplication` - Supports both Device Flow and Auth Code Flow with per-client toggles (`EnableDeviceFlow`, `EnableAuthCodeFlow`)
 - `OAuthApplication.ClientType` - "confidential" (with secret) or "public" (PKCE only)
+- `OAuthApplication.TokenProfile` - Per-client token lifetime preset: `short` (15min / 1d), `standard` (default, 10h / 30d), or `long` (24h / 90d). Preset TTLs are defined in `config.TokenProfiles` and overridable via `TOKEN_PROFILE_*` env vars; hard caps are enforced via `JWT_EXPIRATION_MAX` / `REFRESH_TOKEN_EXPIRATION_MAX`. Changes to a client's profile take effect on the next token issuance and refresh.
 - `UserAuthorization` - Per-app consent grants (one record per user+app pair)
 - `AccessToken` - Unified storage for both access and refresh tokens (distinguished by `token_category` field)
 - `User.IsActive` - Boolean (default `true`) controlling whether a user may log in. Disabling revokes all of the user's tokens and `RequireAuth` clears any live session on the next request. Guards prevent self-disable and disabling the last *active* admin.
 
@@ -339,6 +339,20 @@ AuthGate supports refresh tokens following RFC 6749 with configurable rotation m
 - `ENABLE_REFRESH_TOKENS=true` - Feature flag (default: enabled)
 - `ENABLE_TOKEN_ROTATION=false` - Enable rotation mode (default: disabled, uses fixed mode)
 
+### Per-Client Token Lifetime Profiles
+
+Each `OAuthApplication` carries a `token_profile` field (one of `short`, `standard`, `long`; defaults to `standard`) so admins can tune token lifetimes per client without editing base config. Resolution happens on every issuance and every refresh, so a profile change takes effect on the next token issued to that client — in-flight tokens keep the lifetime they were issued with.
+
+- **`short`** — 15m access / 24h refresh. For admin consoles and other high-value clients where a leaked token's blast radius must be tightly bounded.
+- **`standard`** — defaults to `JWT_EXPIRATION` / `REFRESH_TOKEN_EXPIRATION`. For typical web and SPA clients. Because it mirrors the base config by default, the token service returns `(0, 0)` from its TTL resolver here — which tells the local provider to take its normal issuance path, including `JWT_EXPIRATION_JITTER`. Explicit short/long profiles (and any `standard` that has been diverged from the base) bypass jitter and use the profile TTL exactly.
+- **`long`** — 24h access / 90d refresh. For CLI tools, IoT devices, and long-lived automation where frequent re-auth is user-hostile.
+
+All three profiles are bounded by `JWT_EXPIRATION_MAX` and `REFRESH_TOKEN_EXPIRATION_MAX`; the server refuses to start if any configured profile exceeds its cap.
+
+**Scope:** TokenProfile applies to access and refresh tokens issued through the device-code and authorization-code grants. The `client_credentials` grant is governed separately by `CLIENT_CREDENTIALS_TOKEN_EXPIRATION` so M2M token lifetimes can stay tight regardless of per-client profile choices made for user-facing flows.
+
+**Auditability:** Every profile change is logged at `WARNING` severity with the prior value (`previous_token_profile`) so incident response can trace lifetime changes across the fleet.
+
 ### Grant Type Support
 
 - `urn:ietf:params:oauth:grant-type:device_code` - Device authorization flow (returns access + refresh)
 
@@ -8,6 +8,7 @@ This guide covers all configuration options for AuthGate, including environment
 - [TLS / HTTPS](#tls--https)
 - [Bootstrap and Shutdown Timeouts](#bootstrap-and-shutdown-timeouts)
 - [Generate Strong Secrets](#generate-strong-secrets)
+- [Token Lifetime Profiles](#token-lifetime-profiles)
 - [Default Test Data](#default-test-data)
 - [OAuth Third-Party Login](#oauth-third-party-login)
 - [Service-to-Service Authentication](#service-to-service-authentication)
@@ -83,6 +84,22 @@ ENABLE_TOKEN_ROTATION=false         # Enable rotation mode (default: fixed mode)
 # Client Credentials Flow (RFC 6749 §4.4)
 # CLIENT_CREDENTIALS_TOKEN_EXPIRATION=1h  # Access token lifetime for client_credentials grant (default: 1h)
 #                                           # Keep short — no refresh token means no rotation mechanism
+#                                           # Governed independently from per-client TokenProfile (see below)
+
+# Per-Client Token Lifetime Profiles
+# Each OAuth client selects one of three presets: "short", "standard" (default), or "long".
+# "standard" defaults to JWT_EXPIRATION / REFRESH_TOKEN_EXPIRATION above; overrides below
+# let you tailor the short/long presets without touching the base defaults.
+# TOKEN_PROFILE_SHORT_ACCESS_TTL=15m       # Short profile access token lifetime (default: 15m)
+# TOKEN_PROFILE_SHORT_REFRESH_TTL=24h      # Short profile refresh token lifetime (default: 24h)
+# TOKEN_PROFILE_STANDARD_ACCESS_TTL=10h    # Standard profile access TTL (default: JWT_EXPIRATION)
+# TOKEN_PROFILE_STANDARD_REFRESH_TTL=720h  # Standard profile refresh TTL (default: REFRESH_TOKEN_EXPIRATION)
+# TOKEN_PROFILE_LONG_ACCESS_TTL=24h        # Long profile access TTL (default: 24h)
+# TOKEN_PROFILE_LONG_REFRESH_TTL=2160h     # Long profile refresh TTL (default: 90 days)
+#
+# Hard caps — enforced at startup. No profile may exceed these values.
+# JWT_EXPIRATION_MAX=24h                   # Upper bound for any access-token profile (default: 24h)
+# REFRESH_TOKEN_EXPIRATION_MAX=2160h       # Upper bound for any refresh-token profile (default: 90d)
 
 # OAuth Configuration (optional - for third-party login)
 # GitHub OAuth
@@ -354,6 +371,38 @@ If `JWT_KEY_ID` is not set, it is automatically derived from the SHA-256 hash of
 
 ---
 
+## Token Lifetime Profiles
+
+AuthGate assigns every OAuth client one of three **token lifetime presets** so admins can tune access and refresh token durations to each client's risk profile without touching the base JWT configuration. The preset is selectable from the admin UI (**Admin → OAuth Clients → Token Lifetime**) and recorded on the client as `token_profile`.
+
+### Profiles
+
+| Profile      | When to use                                                    | Default access TTL           | Default refresh TTL           |
+| ------------ | -------------------------------------------------------------- | ---------------------------- | ----------------------------- |
+| `short`      | High-security apps (admin consoles, financial dashboards)      | 15 min                       | 24 h                          |
+| `standard`   | Typical web/SPA clients (default for new clients)              | `JWT_EXPIRATION` (10 h)      | `REFRESH_TOKEN_EXPIRATION` (30 d) |
+| `long`       | CLI tools, IoT devices, long-lived background jobs             | 24 h                         | 90 d                          |
+
+Defaults are overridable per environment via the `TOKEN_PROFILE_*` variables listed in [Environment Variables](#environment-variables).
+
+### Hard caps
+
+`JWT_EXPIRATION_MAX` and `REFRESH_TOKEN_EXPIRATION_MAX` bound every profile's TTL. The server refuses to start if any configured profile exceeds its cap — this guarantees that a stray env override cannot issue tokens longer than the operator intends.
+
+### Jitter behavior
+
+`JWT_EXPIRATION_JITTER` is applied only when the resolved access-token TTL matches the base `JWT_EXPIRATION` (the `standard`-profile default). Explicit `short`/`long` overrides — and a `standard` profile that has been explicitly diverged from the base config — use the profile's TTL exactly, with no jitter added. This keeps jitter working for the high-volume default path (preventing refresh thundering herds) while respecting operator-chosen short/long lifetimes precisely.
+
+### Client Credentials independence
+
+The `client_credentials` grant is governed by `CLIENT_CREDENTIALS_TOKEN_EXPIRATION` and **ignores** the client's TokenProfile. M2M tokens carry a larger blast radius than user-delegated tokens (no refresh, no user-revoke UI), so their lifetime is managed separately and is typically kept much shorter than user-facing tokens. If you need per-client M2M TTLs, open an issue — it will require a dedicated field on TokenProfile rather than overloading the existing access TTL.
+
+### Changing a profile
+
+Updates take effect on the **next token issuance or refresh**. Existing tokens retain the lifetime they were originally issued with; AuthGate does not retroactively shorten live tokens. Every TokenProfile change is recorded in the audit log at `WARNING` severity with the previous value (`previous_token_profile`) for forensic traceability.
+
+---
+
 ## Default Test Data
 
 The server initializes with default test accounts:
 
@@ -7,6 +7,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/go-authgate/authgate/internal/models"
+
 	"github.com/joho/godotenv"
 )
 
@@ -36,6 +38,14 @@ const (
 	AlgES256 = "ES256"
 )
 
+// TokenProfile defines the access and refresh token lifetimes for a named preset.
+// Clients reference a profile by name via OAuthApplication.TokenProfile (see
+// models.TokenProfile* constants) and the TTL is resolved at token issuance.
+type TokenProfile struct {
+	AccessTokenTTL  time.Duration
+	RefreshTokenTTL time.Duration
+}
+
 type Config struct {
 	// Server settings
 	ServerAddr  string
@@ -100,6 +110,17 @@ type Config struct {
 	EnableRefreshTokens    bool          // Feature flag to enable/disable refresh tokens (default: true)
 	EnableTokenRotation    bool          // Enable token rotation mode (default: false, fixed mode)
 
+	// Token lifetime hard caps. Any TokenProfile value that exceeds these is rejected
+	// during Validate(). Prevents a misconfigured profile from silently extending token
+	// lifetime far beyond the security intent.
+	JWTExpirationMax          time.Duration // env: JWT_EXPIRATION_MAX (default: 24h)
+	RefreshTokenExpirationMax time.Duration // env: REFRESH_TOKEN_EXPIRATION_MAX (default: 2160h / 90d)
+
+	// TokenProfiles maps a profile name ("short" / "standard" / "long") to its TTLs.
+	// Populated in Load() from the TOKEN_PROFILE_*_ACCESS_TTL / TOKEN_PROFILE_*_REFRESH_TTL env
+	// vars; the "standard" profile falls back to JWTExpiration / RefreshTokenExpiration.
+	TokenProfiles map[string]TokenProfile
+
 	// Client Credentials Flow settings (RFC 6749 §4.4)
 	ClientCredentialsTokenExpiration time.Duration // Access token lifetime for client_credentials grant (default: 1h, same as JWTExpiration)
 
@@ -251,6 +272,31 @@ func Load() *Config {
 		dsn = getEnv("DATABASE_DSN", "")
 	}
 
+	// Resolve base JWT settings first — the "standard" profile inherits these,
+	// so the map must be built after the values are known.
+	jwtExpiration := getEnvDuration("JWT_EXPIRATION", 10*time.Hour)
+	refreshTokenExpiration := getEnvDuration("REFRESH_TOKEN_EXPIRATION", 720*time.Hour)
+	tokenProfiles := map[string]TokenProfile{
+		models.TokenProfileShort: {
+			AccessTokenTTL:  getEnvDuration("TOKEN_PROFILE_SHORT_ACCESS_TTL", 15*time.Minute),
+			RefreshTokenTTL: getEnvDuration("TOKEN_PROFILE_SHORT_REFRESH_TTL", 24*time.Hour),
+		},
+		models.TokenProfileStandard: {
+			AccessTokenTTL: getEnvDuration("TOKEN_PROFILE_STANDARD_ACCESS_TTL", jwtExpiration),
+			RefreshTokenTTL: getEnvDuration(
+				"TOKEN_PROFILE_STANDARD_REFRESH_TTL",
+				refreshTokenExpiration,
+			),
+		},
+		models.TokenProfileLong: {
+			AccessTokenTTL: getEnvDuration("TOKEN_PROFILE_LONG_ACCESS_TTL", 24*time.Hour),
+			RefreshTokenTTL: getEnvDuration(
+				"TOKEN_PROFILE_LONG_REFRESH_TTL",
+				2160*time.Hour,
+			), // 90 days
+		},
+	}
+
 	return &Config{
 		ServerAddr:  getEnv("SERVER_ADDR", ":8080"),
 		BaseURL:     getEnv("BASE_URL", "http://localhost:8080"),
@@ -259,7 +305,7 @@ func Load() *Config {
 		IsProduction: getEnvBool("ENVIRONMENT", false) ||
 			getEnv("ENVIRONMENT", "") == "production",
 		JWTSecret:           getEnv("JWT_SECRET", "your-256-bit-secret-change-in-production"),
-		JWTExpiration:       getEnvDuration("JWT_EXPIRATION", 10*time.Hour),
+		JWTExpiration:       jwtExpiration,
 		JWTSigningAlgorithm: getEnv("JWT_SIGNING_ALGORITHM", AlgHS256),
 		JWTPrivateKeyPath:   getEnv("JWT_PRIVATE_KEY_PATH", ""),
 		JWTKeyID:            getEnv("JWT_KEY_ID", ""),
@@ -302,12 +348,12 @@ func Load() *Config {
 		HTTPAPIMaxRetryDelay:      getEnvDuration("HTTP_API_MAX_RETRY_DELAY", 10*time.Second),
 
 		// Refresh Token settings
-		RefreshTokenExpiration: getEnvDuration(
-			"REFRESH_TOKEN_EXPIRATION",
-			720*time.Hour,
-		), // 30 days
-		EnableRefreshTokens: getEnvBool("ENABLE_REFRESH_TOKENS", true),
-		EnableTokenRotation: getEnvBool("ENABLE_TOKEN_ROTATION", false),
+		RefreshTokenExpiration:    refreshTokenExpiration,
+		EnableRefreshTokens:       getEnvBool("ENABLE_REFRESH_TOKENS", true),
+		EnableTokenRotation:       getEnvBool("ENABLE_TOKEN_ROTATION", false),
+		JWTExpirationMax:          getEnvDuration("JWT_EXPIRATION_MAX", 24*time.Hour),
+		RefreshTokenExpirationMax: getEnvDuration("REFRESH_TOKEN_EXPIRATION_MAX", 2160*time.Hour),
+		TokenProfiles:             tokenProfiles,
 
 		// Client Credentials Flow settings
 		ClientCredentialsTokenExpiration: getEnvDuration(
@@ -680,5 +726,67 @@ func (c *Config) Validate() error {
 		)
 	}
 
+	return c.validateTokenProfiles()
+}
+
+// validateTokenProfiles checks that every profile has positive TTLs and that
+// no profile's TTL exceeds the configured hard caps (JWT_EXPIRATION_MAX /
+// REFRESH_TOKEN_EXPIRATION_MAX). The standard / short / long profiles must all
+// be present. When TokenProfiles and both caps are left at their zero values
+// (e.g. a hand-built *Config used in an ad-hoc unit test) validation is
+// skipped — Load() always populates these, so this gate only affects real
+// startup, not consumers who only care about unrelated fields.
+func (c *Config) validateTokenProfiles() error {
+	if len(c.TokenProfiles) == 0 && c.JWTExpirationMax == 0 && c.RefreshTokenExpirationMax == 0 {
+		return nil
+	}
+	if c.JWTExpirationMax <= 0 {
+		return fmt.Errorf(
+			"JWT_EXPIRATION_MAX must be a positive duration (got %s)",
+			c.JWTExpirationMax,
+		)
+	}
+	if c.RefreshTokenExpirationMax <= 0 {
+		return fmt.Errorf(
+			"REFRESH_TOKEN_EXPIRATION_MAX must be a positive duration (got %s)",
+			c.RefreshTokenExpirationMax,
+		)
+	}
+
+	requiredProfiles := []string{
+		models.TokenProfileShort,
+		models.TokenProfileStandard,
+		models.TokenProfileLong,
+	}
+	for _, name := range requiredProfiles {
+		profile, ok := c.TokenProfiles[name]
+		if !ok {
+			return fmt.Errorf("token profile %q is missing from TokenProfiles", name)
+		}
+		if profile.AccessTokenTTL <= 0 {
+			return fmt.Errorf(
+				"token profile %q access TTL must be a positive duration (got %s)",
+				name, profile.AccessTokenTTL,
+			)
+		}
+		if profile.RefreshTokenTTL <= 0 {
+			return fmt.Errorf(
+				"token profile %q refresh TTL must be a positive duration (got %s)",
+				name, profile.RefreshTokenTTL,
+			)
+		}
+		if profile.AccessTokenTTL > c.JWTExpirationMax {
+			return fmt.Errorf(
+				"token profile %q access TTL %s exceeds JWT_EXPIRATION_MAX %s",
+				name, profile.AccessTokenTTL, c.JWTExpirationMax,
+			)
+		}
+		if profile.RefreshTokenTTL > c.RefreshTokenExpirationMax {
+			return fmt.Errorf(
+				"token profile %q refresh TTL %s exceeds REFRESH_TOKEN_EXPIRATION_MAX %s",
+				name, profile.RefreshTokenTTL, c.RefreshTokenExpirationMax,
+			)
+		}
+	}
 	return nil
 }