fix(auth-guard): lazy provider + enforce secret minimum length at startup (#439)

* fix(examples): defer auth-guard session setup out of the init hook

The generated app registers the auth provider from its init() hook, before
the env-contract validation runs. The hook called authguard.MustAuthProvider(),
which constructed Sessions eagerly and panicked when GOWDK_AUTH_SESSION_SECRET
was unset or shorter than the required 32 bytes — so a secret misconfiguration
crashed the binary with a stack trace at startup instead of returning the
generated env-contract error.

Replace MustAuthProvider with a lazy AuthProvider that resolves Sessions inside
Principal on the first request, and point the generated hook at it. A missing
or short secret now surfaces as the clean "GOWDK_AUTH_SESSION_SECRET is required"
startup error (verified by running the built binary with the secret unset).

* fix(env): enforce SecretEnv minimum length at build and startup

Follow-up to the lazy auth provider: deferring Sessions() construction meant a
present-but-too-short GOWDK_AUTH_SESSION_SECRET no longer failed at init, and
the env contract only checked for empty secrets — so a weak signing key let the
binary start and only failed the first guarded request.

Add SecretEnv.MinBytes and enforce it in both the build-time env validation
(gowdk.EnvConfig.Validate) and the generated runtime contract
(internal/appgen validateEnvContract), parse it from executable and AST configs
(internal/project), register the new short_secret diagnostic, and set
MinBytes: 32 on the auth-guard example's session and CSRF secrets.

A short secret now fails fast with "GOWDK_AUTH_SESSION_SECRET must be at least
32 bytes" at startup (verified by running the built binary). Tests added for
both the build-time validation and the generated contract.

* fix(config): bounds-check int64->int narrowing for SecretEnv.MinBytes

CodeQL flagged the unchecked int64->int conversion when parsing
SecretEnv.MinBytes from the AST config path. Route it through a new
parseInt helper that clamps out-of-range values to the platform int
range so a malformed config value cannot wrap into a small or negative
length on 32-bit platforms. Add a LoadConfigFile regression test that
enforces MinBytes end-to-end through the AST path.

Author: cssbruno

examples/auth-guard/apphooks/auth_guard_hooks.go.txt

@@ -13,5 +13,8 @@ func GOWDKGuardRegistry() gowdkguard.Registry {
 }
 
 func GOWDKAuthProvider() gowdkauth.Provider {
-	return authguard.MustAuthProvider()
+	// Lazy provider: never construct Sessions at init time, so a missing or
+	// too-short GOWDK_AUTH_SESSION_SECRET surfaces as the generated env-contract
+	// startup error rather than an init-time panic.
+	return authguard.AuthProvider()
 }

examples/auth-guard/gowdk.config.go

@@ -13,8 +13,8 @@ var Config = gowdk.Config{
 	},
 	Env: gowdk.EnvConfig{
 		Secrets: []gowdk.SecretEnv{
-			{Name: "GOWDK_AUTH_SESSION_SECRET", Required: true},
-			{Name: "GOWDK_CSRF_SECRET", Required: true},
+			{Name: "GOWDK_AUTH_SESSION_SECRET", Required: true, MinBytes: 32},
+			{Name: "GOWDK_CSRF_SECRET", Required: true, MinBytes: 32},
 		},
 	},
 	Build: gowdk.BuildConfig{

examples/auth-guard/src/authguard/auth.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"crypto/subtle"
 	"fmt"
+	"net/http"
 	"os"
 	"strings"
 	"sync"
@@ -113,12 +114,21 @@ func RequireSession(ctx guard.Context) error {
 	return nil
 }
 
-func MustAuthProvider() gowdkauth.Provider {
-	sessions, err := Sessions()
-	if err != nil {
-		panic(err)
-	}
-	return sessions.Provider()
+// AuthProvider returns a Provider that resolves the session manager lazily on
+// the first request. The generated app registers the provider from its init()
+// hook, which runs before the app's env-contract validation. Building Sessions
+// here (as the previous MustAuthProvider did) would panic on a missing or
+// too-short GOWDK_AUTH_SESSION_SECRET and crash with a stack trace instead of
+// the clean startup error. Deferring construction to Principal keeps secret
+// misconfiguration on the normal validation path.
+func AuthProvider() gowdkauth.Provider {
+	return gowdkauth.ProviderFunc(func(request *http.Request) (*gowdkauth.Principal, error) {
+		sessions, err := Sessions()
+		if err != nil {
+			return nil, err
+		}
+		return sessions.Principal(request)
+	})
 }
 
 func Sessions() (*gowdkauth.Sessions, error) {

gowdk.go

@@ -67,6 +67,11 @@ type EnvVar struct {
 type SecretEnv struct {
 	Name     string
 	Required bool
+	// MinBytes rejects a present-but-too-short secret at build time and at
+	// generated-app startup. Zero means no minimum. This lets the env contract
+	// fail fast on a weak signing key instead of deferring the failure to the
+	// first request that constructs the signer.
+	MinBytes int
 }
 
 // EnvValidationError describes one invalid or missing env contract entry.
@@ -123,9 +128,14 @@ func (config EnvConfig) Validate(lookup func(string) (string, bool)) error {
 			continue
 		}
 		diagnostics = append(diagnostics, validateEnvDuplicate(seen, name, "Secrets")...)
-		if lookup != nil && secret.Required {
-			if value, ok := lookup(name); !ok || strings.TrimSpace(value) == "" {
+		if lookup != nil {
+			value, ok := lookup(name)
+			trimmed := strings.TrimSpace(value)
+			switch {
+			case secret.Required && (!ok || trimmed == ""):
 				diagnostics = append(diagnostics, EnvValidationError{Code: "missing_required_secret", Name: name, Message: fmt.Sprintf("%s is required but is not set", name)})
+			case secret.MinBytes > 0 && trimmed != "" && len(trimmed) < secret.MinBytes:
+				diagnostics = append(diagnostics, EnvValidationError{Code: "short_secret", Name: name, Message: fmt.Sprintf("%s must be at least %d bytes", name, secret.MinBytes)})
 			}
 		}
 	}

internal/appgen/appgen_test.go

@@ -1386,6 +1386,39 @@ func TestGenerateWiresEnvContractValidation(t *testing.T) {
 	}
 }
 
+func TestGenerateEnvContractEnforcesSecretMinBytes(t *testing.T) {
+	root := t.TempDir()
+	outputDir := filepath.Join(root, "dist")
+	appDir := filepath.Join(root, "generated-app")
+	writeTestFile(t, filepath.Join(outputDir, "index.html"), "<main>Home</main>")
+
+	result, err := GenerateWithOptions(outputDir, appDir, Options{
+		Config: gowdk.Config{Env: gowdk.EnvConfig{
+			Secrets: []gowdk.SecretEnv{
+				{Name: "GOWDK_TEST_SESSION_SECRET", Required: true, MinBytes: 32},
+			},
+		}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	payload, err := os.ReadFile(result.PackagePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := string(payload)
+	for _, expected := range []string{
+		`value := strings.TrimSpace(os.Getenv("GOWDK_TEST_SESSION_SECRET"))`,
+		`missing = append(missing, "GOWDK_TEST_SESSION_SECRET is required but is not set")`,
+		`} else if len(value) < 32 {`,
+		`missing = append(missing, "GOWDK_TEST_SESSION_SECRET must be at least 32 bytes")`,
+	} {
+		if !strings.Contains(source, expected) {
+			t.Fatalf("expected generated env contract to enforce the secret minimum %q:\n%s", expected, source)
+		}
+	}
+}
+
 func TestGenerateRunsRateLimitAndGuardsBeforeContractExecution(t *testing.T) {
 	root := t.TempDir()
 	outputDir := filepath.Join(root, "dist")

internal/appgen/source_env.go

@@ -1,6 +1,7 @@
 package appgen
 
 import (
+	"fmt"
 	"go/ast"
 	"go/token"
 
@@ -14,7 +15,7 @@ func envRuntimeValidationRequired(config gowdk.EnvConfig) bool {
 		}
 	}
 	for _, secret := range config.Secrets {
-		if secret.Required {
+		if secret.Required || secret.MinBytes > 0 {
 			return true
 		}
 	}
@@ -35,10 +36,9 @@ func validateEnvContractDecl(config gowdk.EnvConfig) []ast.Decl {
 		stmts = append(stmts, appendMissingEnvStmt(variable.Name))
 	}
 	for _, secret := range config.Secrets {
-		if !secret.Required {
-			continue
+		if stmt := appendSecretEnvStmt(secret); stmt != nil {
+			stmts = append(stmts, stmt)
 		}
-		stmts = append(stmts, appendMissingEnvStmt(secret.Name))
 	}
 	stmts = append(stmts,
 		&ast.IfStmt{
@@ -64,6 +64,43 @@ func appendMissingEnvStmt(name string) ast.Stmt {
 	}
 }
 
+// appendSecretEnvStmt validates one secret env var. A required secret with no
+// minimum keeps the existing empty-only check. A secret with MinBytes also
+// rejects a present-but-too-short value, so a weak signing key fails the env
+// contract at startup instead of deferring to the first request.
+func appendSecretEnvStmt(secret gowdk.SecretEnv) ast.Stmt {
+	if secret.MinBytes <= 0 {
+		if secret.Required {
+			return appendMissingEnvStmt(secret.Name)
+		}
+		return nil
+	}
+	appendMissing := func(message string) ast.Stmt {
+		return assign([]ast.Expr{id("missing")}, call(id("append"), id("missing"), stringLit(message)))
+	}
+	getenv := define([]ast.Expr{id("value")}, call(sel("strings", "TrimSpace"), call(sel("os", "Getenv"), stringLit(secret.Name))))
+	tooShort := &ast.BinaryExpr{X: call(id("len"), id("value")), Op: token.LSS, Y: intLit(secret.MinBytes)}
+	shortStmt := block(appendMissing(fmt.Sprintf("%s must be at least %d bytes", secret.Name, secret.MinBytes)))
+	if !secret.Required {
+		// Optional secret: only enforce the minimum when a value is present.
+		return &ast.IfStmt{
+			Init: getenv,
+			Cond: &ast.BinaryExpr{
+				X:  &ast.BinaryExpr{X: id("value"), Op: token.NEQ, Y: stringLit("")},
+				Op: token.LAND,
+				Y:  tooShort,
+			},
+			Body: shortStmt,
+		}
+	}
+	return &ast.IfStmt{
+		Init: getenv,
+		Cond: &ast.BinaryExpr{X: id("value"), Op: token.EQL, Y: stringLit("")},
+		Body: block(appendMissing(secret.Name + " is required but is not set")),
+		Else: &ast.IfStmt{Cond: tooShort, Body: shortStmt},
+	}
+}
+
 func validateEnvContractStmt(config gowdk.EnvConfig) []ast.Stmt {
 	if !envRuntimeValidationRequired(config) {
 		return nil

internal/diagnostics/registry.go

@@ -159,6 +159,7 @@ var Registry = []Code{
 	{Code: "route_method_conflict", Area: "routing", Stability: StabilityStable, Severity: SeverityError, Summary: "two generated handlers claim the same method and route pattern"},
 	{Code: "secret_env_in_vars", Area: "config", Stability: StabilityStable, Severity: SeverityError, Summary: "secret-looking environment variable is declared as a normal variable"},
 	{Code: "secret_env_name_required", Area: "config", Stability: StabilityStable, Severity: SeverityError, Summary: "secret environment contract entry is missing a name"},
+	{Code: "short_secret", Area: "config", Stability: StabilityStable, Severity: SeverityError, Summary: "secret environment variable is shorter than its required minimum length"},
 	{Code: "spa_disabled", Area: "routing", Stability: StabilityExperimental, Severity: SeverityInfo, Summary: "SPA route binding is disabled for this generated route lane"},
 	{Code: "spa_dynamic_route_missing_paths", Area: "routing", Stability: StabilityStable, Severity: SeverityError, Summary: "dynamic SPA route is missing paths declarations"},
 	{Code: "ssr_disabled", Area: "routing", Stability: StabilityExperimental, Severity: SeverityInfo, Summary: "SSR route binding is disabled for this generated route lane"},

internal/project/config.go

@@ -6,6 +6,7 @@ import (
 	"go/ast"
 	"go/parser"
 	"go/token"
+	"math"
 	"os"
 	"path"
 	"strconv"
@@ -467,6 +468,8 @@ func parseSecretEnv(expression ast.Expr) (gowdk.SecretEnv, bool, error) {
 			secret.Name = parseString(keyValue.Value)
 		case "Required":
 			secret.Required = parseBool(keyValue.Value)
+		case "MinBytes":
+			secret.MinBytes = parseInt(keyValue.Value)
 		case "Default", "Value":
 			return gowdk.SecretEnv{}, false, fmt.Errorf("Env.Secrets entries cannot declare %s; secret values must come from the runtime environment", key.Name)
 		}
@@ -1050,6 +1053,21 @@ func parseBool(expression ast.Expr) bool {
 	return ok && identifier.Name == "true"
 }
 
+// parseInt narrows a parsed integer literal to int, clamping values that fall
+// outside the platform int range so a malformed config value cannot wrap into a
+// small or negative length on 32-bit platforms.
+func parseInt(expression ast.Expr) int {
+	value := parseInt64(expression)
+	switch {
+	case value > math.MaxInt:
+		return math.MaxInt
+	case value < math.MinInt:
+		return math.MinInt
+	default:
+		return int(value)
+	}
+}
+
 func parseInt64(expression ast.Expr) int64 {
 	switch typed := expression.(type) {
 	case *ast.BasicLit:

internal/project/config_test.go

@@ -268,6 +268,35 @@ var Config = gowdk.Config{
 	}
 }
 
+func TestLoadConfigFileEnforcesSecretMinBytes(t *testing.T) {
+	const name = "GOWDK_TEST_SESSION_SECRET"
+	t.Setenv(name, "too-short")
+
+	root := t.TempDir()
+	path := filepath.Join(root, DefaultConfigFile)
+	if err := os.WriteFile(path, []byte(`package app
+
+import "github.com/cssbruno/gowdk"
+
+var Config = gowdk.Config{
+	Env: gowdk.EnvConfig{
+		Secrets: []gowdk.SecretEnv{
+			{Name: "GOWDK_TEST_SESSION_SECRET", Required: true, MinBytes: 32},
+		},
+	},
+}
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// The AST config path must carry MinBytes through to validation; without it
+	// a non-empty short secret would pass the contract and only fail at runtime.
+	_, err := LoadConfigFile(path)
+	if err == nil || !strings.Contains(err.Error(), "GOWDK_TEST_SESSION_SECRET must be at least 32 bytes") {
+		t.Fatalf("expected short-secret validation error, got %v", err)
+	}
+}
+
 func TestLoadConfigFileRejectsSecretEnvMisuse(t *testing.T) {
 	root := t.TempDir()
 	path := filepath.Join(root, DefaultConfigFile)

internal/publicapi/gowdk_test.go

@@ -100,6 +100,30 @@ func TestEnvConfigValidateReportsMissingRequiredNames(t *testing.T) {
 	}
 }
 
+func TestEnvConfigValidateRejectsShortSecret(t *testing.T) {
+	config := gowdk.EnvConfig{
+		Secrets: []gowdk.SecretEnv{
+			{Name: "GOWDK_TEST_SESSION_SECRET", Required: true, MinBytes: 32},
+		},
+	}
+
+	short := config.Validate(func(string) (string, bool) { return "too-short", true })
+	if short == nil || !strings.Contains(short.Error(), "GOWDK_TEST_SESSION_SECRET must be at least 32 bytes") {
+		t.Fatalf("expected short-secret error, got %v", short)
+	}
+
+	missing := config.Validate(func(string) (string, bool) { return "", true })
+	if missing == nil || !strings.Contains(missing.Error(), "GOWDK_TEST_SESSION_SECRET is required but is not set") {
+		t.Fatalf("expected missing-secret error, got %v", missing)
+	}
+
+	if err := config.Validate(func(string) (string, bool) {
+		return "0123456789ABCDEF0123456789ABCDEF", true
+	}); err != nil {
+		t.Fatalf("expected a 32-byte secret to pass, got %v", err)
+	}
+}
+
 func TestBuildConfigDebugAssets(t *testing.T) {
 	if !(gowdk.BuildConfig{}).DebugAssets() {
 		t.Fatal("expected omitted build mode to include debug assets")