Add two-tier discovery: public bootstrap and authenticated endpoints

Implement content-addressable discovery URLs with two tiers:
- Bootstrap (/d/bootstrap → /d/<hash>): no auth, returns OIDC config
- Discovery (/d/current → /d/<hash>): requires auth, returns match patterns

Changes:
- Rename OIDCConfig.Audience to ClientID (breaking config change)
- Add BootstrapAuth/BootstrapHash methods to PolicyRulesConfig
- Update discovery handler to serve both bootstrap and discovery
- Add bootstrap Link header to CA GET / response
- Add GetPublicKey/GetBootstrap to caclient for bootstrap flow
- Add AuthConfigToCommand to convert bootstrap config to auth command

Includes comprehensive unit tests and end-to-end integration test.

Author: brianm

.tasks/open/c1kdc4e1.md .tasks/closed/c1kdc4e1.md.tasks/open/c1kdc4e1.md renamed to .tasks/closed/c1kdc4e1.md

@@ -3,7 +3,7 @@ yatl_version: 1
 title: 'Two-tier discovery: public and authenticated endpoints'
 id: c1kdc4e1
 created: 2025-12-24T23:08:50.420228Z
-updated: 2025-12-24T23:09:16.320617Z
+updated: 2026-01-03T00:47:24.678182Z
 author: Brian McCallister
 priority: medium
 tags:
@@ -88,3 +88,23 @@ Authenticated discovery:
 ### Open Items
 
 - Need to add client_id to OIDC config (currently only has issuer and audience)
+
+---
+# Log: 2026-01-02T23:56:52Z Brian McCallister
+
+Started working.
+
+---
+# Log: 2026-01-03T00:36:11Z Brian McCallister
+
+-
+
+---
+# Log: 2026-01-03T00:47:20Z Brian McCallister
+
+Implemented two-tier discovery. Changes: (1) Renamed OIDCConfig.Audience to ClientID, (2) Added BootstrapHash/BootstrapAuth methods, (3) Updated discovery handler for bootstrap+discovery tiers, (4) Added bootstrap Link header to CA GET /, (5) Added Bootstrap/GetPublicKey/GetBootstrap to caclient, (6) Added AuthConfigToCommand function. All tests pass.
+
+---
+# Log: 2026-01-03T00:47:24Z Brian McCallister
+
+Closed: Implemented two-tier discovery: public bootstrap (no auth) and authenticated discovery. All 7 implementation steps complete with tests.

.tasks/open/hv3622e5.md

@@ -0,0 +1,17 @@
+---
+yatl_version: 1
+title: Explore eliminating client_secret from bootstrap - use PKCE public client flow
+id: hv3622e5
+created: 2026-01-03T00:35:10.650363Z
+updated: 2026-01-03T00:35:10.650363Z
+author: Brian McCallister
+priority: low
+tags:
+- exploration
+- oidc
+---
+
+---
+# Log: 2026-01-03T00:35:10Z Brian McCallister
+
+Created task.

CLAUDE.md

@@ -4,6 +4,40 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Correctness over convenience
+
+* Model the full error space—no shortcuts or simplified error handling. 
+* Handle all edge cases, including race conditions, signal timing, and platform differences.
+* Use the type system to encode correctness constraints.
+* Prefer compile-time guarantees over runtime checks where possible.
+
+## User experience as a primary driver
+
+* Provide structured, helpful error messages for diagnostics
+* Make progress reporting responsive and informative.
+* Maintain consistency across platforms even when underlying OS capabilities differ. Use OS-native logic rather than trying to emulate Unix on Windows (or vice versa).
+* Write user-facing messages in clear, present tense: "Epithet now supports..." not "Epithet now supported..."
+
+## Pragmatic incrementalism
+
+* "Not overly generic"—prefer specific, composable logic over abstract frameworks.
+* Evolve the design incrementally rather than attempting perfect upfront architecture.
+* Document design decisions and trade-offs in design docs
+* When uncertain, explore and iterate
+
+## Production-grade engineering
+
+* Test comprehensively, including edge cases, race conditions, and stress tests.
+* Pay attention to what facilities already exist, and aim to reuse them.
+* Getting the details right is really important!
+
+## Documentation
+
+* Use inline comments to explain "why," not just "what".
+* Module-level documentation should explain purpose and responsibilities.
+* Always use periods at the end of code comments.
+* Never use title case in headings and titles. Always use sentence case.
+
 ## Project Overview
 
 Epithet is an SSH certificate authority system that makes SSH certificates easy to use. The project is currently undergoing a v2 rewrite (see README.md for v2 architecture details).

cmd/epithet/policy.go

@@ -23,7 +23,7 @@ import (
 // This is embedded in PolicyServerCLI to enable nested config paths like policy.oidc.issuer
 type PolicyOIDCConfig struct {
 	Issuer   string `help:"OIDC issuer URL" name:"issuer"`
-	Audience string `help:"OIDC audience (client ID)" name:"audience"`
+	ClientID string `help:"OIDC client ID" name:"client-id"`
 }
 
 // PolicyServerCLI defines the CLI flags for the policy server.
@@ -74,7 +74,7 @@ func (c *PolicyServerCLI) Run(logger *slog.Logger, tlsCfg tlsconfig.Config, unif
 		"users", len(cfg.Users),
 		"hosts", len(cfg.Hosts),
 		"oidc_issuer", cfg.OIDC.Issuer,
-		"oidc_audience", cfg.OIDC.Audience)
+		"oidc_client_id", cfg.OIDC.ClientID)
 
 	// Create policy evaluator and token validator
 	ctx := context.Background()
@@ -101,7 +101,9 @@ func (c *PolicyServerCLI) Run(logger *slog.Logger, tlsCfg tlsconfig.Config, unif
 	discoveryHandler := policyserver.NewDiscoveryHandler(policyserver.DiscoveryConfig{
 		Validator:     validator,
 		MatchPatterns: matchPatterns,
-		Hash:          cfg.DiscoveryHash(),
+		DiscoveryHash: cfg.DiscoveryHash(),
+		BootstrapHash: cfg.BootstrapHash(),
+		AuthConfig:    cfg.BootstrapAuth(),
 	})
 
 	// Set up router with middleware
@@ -113,15 +115,18 @@ func (c *PolicyServerCLI) Run(logger *slog.Logger, tlsCfg tlsconfig.Config, unif
 	r.Use(middleware.Timeout(60 * time.Second))
 
 	r.Post("/", handler)
-	// Redirect endpoint: /d/current -> /d/{hash} (cached 5 min)
+	// Bootstrap redirect endpoint: /d/bootstrap -> /d/{bootstrap-hash} (cached 5 min, no auth)
+	r.Get("/d/bootstrap", policyserver.NewBootstrapRedirectHandler(cfg.BootstrapHash(), c.DiscoveryBaseURL))
+	// Discovery redirect endpoint: /d/current -> /d/{discovery-hash} (cached 5 min, requires auth)
 	r.Get("/d/current", policyserver.NewDiscoveryRedirectHandler(cfg.DiscoveryHash(), c.DiscoveryBaseURL))
-	// Content-addressed endpoint: /d/{hash} (immutable)
+	// Content-addressed endpoint: /d/{hash} (immutable, serves bootstrap or discovery based on hash)
 	r.Get("/d/*", discoveryHandler)
 
 	logger.Info("starting policy server",
 		"listen", c.Listen,
 		"ca_pubkey_length", len(caPubkey),
 		"discovery_hash", cfg.DiscoveryHash(),
+		"bootstrap_hash", cfg.BootstrapHash(),
 		"match_patterns", matchPatterns)
 
 	return http.ListenAndServe(c.Listen, r)
@@ -162,8 +167,8 @@ func (c *PolicyServerCLI) applyOverrides(cfg *policyserver.PolicyRulesConfig) {
 	if c.OIDC.Issuer != "" {
 		cfg.OIDC.Issuer = c.OIDC.Issuer
 	}
-	if c.OIDC.Audience != "" {
-		cfg.OIDC.Audience = c.OIDC.Audience
+	if c.OIDC.ClientID != "" {
+		cfg.OIDC.ClientID = c.OIDC.ClientID
 	}
 	if c.DefaultExpiration != "" {
 		if cfg.Defaults == nil {

pkg/broker/auth.go

@@ -7,9 +7,11 @@ import (
 	"io"
 	"os"
 	"os/exec"
+	"strings"
 	"sync"
 
 	"github.com/cbroglie/mustache"
+	"github.com/epithet-ssh/epithet/pkg/caclient"
 )
 
 // MaxStateBlobSize is the maximum size of the state blob (10 MiB).
@@ -132,3 +134,51 @@ func (h *Auth) Run(attrs any) (string, error) {
 
 	return h.token, nil
 }
+
+// AuthConfigToCommand converts a bootstrap auth config to an executable command string.
+// For type="oidc": constructs "<executable> auth oidc --issuer X --client-id Y --scopes Z"
+// For type="command": returns the command as-is (substituting "epithet" with os.Executable())
+// Returns an error if the auth type is unknown or if os.Executable() fails.
+func AuthConfigToCommand(auth caclient.BootstrapAuth) (string, error) {
+	switch auth.Type {
+	case "oidc":
+		// Construct the OIDC auth command
+		executable, err := os.Executable()
+		if err != nil {
+			return "", fmt.Errorf("failed to get executable path: %w", err)
+		}
+
+		// Build command: <executable> auth oidc --issuer X --client-id Y --scopes A,B,C
+		parts := []string{
+			executable,
+			"auth", "oidc",
+			"--issuer", auth.Issuer,
+			"--client-id", auth.ClientID,
+		}
+
+		if len(auth.Scopes) > 0 {
+			parts = append(parts, "--scopes", strings.Join(auth.Scopes, ","))
+		}
+
+		return strings.Join(parts, " "), nil
+
+	case "command":
+		// Use the command as-is, substituting "epithet" with the current executable
+		if auth.Command == "" {
+			return "", fmt.Errorf("command auth type requires non-empty command")
+		}
+
+		executable, err := os.Executable()
+		if err != nil {
+			return "", fmt.Errorf("failed to get executable path: %w", err)
+		}
+
+		// Replace "epithet" with the actual executable path
+		// This allows bootstrap configs to use "epithet" as a placeholder
+		cmd := strings.ReplaceAll(auth.Command, "epithet", executable)
+		return cmd, nil
+
+	default:
+		return "", fmt.Errorf("unknown auth type: %s", auth.Type)
+	}
+}

pkg/broker/auth_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/epithet-ssh/epithet/pkg/caclient"
 	"github.com/stretchr/testify/require"
 )
 
@@ -375,3 +376,99 @@ printf '\x80\x81\x82token\xff\xfe'
 	require.NoError(t, err)
 	require.Equal(t, []byte{0x80, 0x81, 0x82, 't', 'o', 'k', 'e', 'n', 0xff, 0xfe}, decoded)
 }
+
+func TestAuthConfigToCommand_OIDC(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type:     "oidc",
+		Issuer:   "https://accounts.google.com",
+		ClientID: "my-client-id",
+		Scopes:   []string{"openid", "profile", "email"},
+	}
+
+	cmd, err := AuthConfigToCommand(auth)
+	require.NoError(t, err)
+
+	// Command should contain the executable path (we can't predict exact path)
+	require.Contains(t, cmd, "auth oidc")
+	require.Contains(t, cmd, "--issuer https://accounts.google.com")
+	require.Contains(t, cmd, "--client-id my-client-id")
+	require.Contains(t, cmd, "--scopes openid,profile,email")
+}
+
+func TestAuthConfigToCommand_OIDC_NoScopes(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type:     "oidc",
+		Issuer:   "https://example.com",
+		ClientID: "test-client",
+		Scopes:   nil,
+	}
+
+	cmd, err := AuthConfigToCommand(auth)
+	require.NoError(t, err)
+
+	// Command should not contain --scopes when empty
+	require.Contains(t, cmd, "auth oidc")
+	require.Contains(t, cmd, "--issuer https://example.com")
+	require.Contains(t, cmd, "--client-id test-client")
+	require.NotContains(t, cmd, "--scopes")
+}
+
+func TestAuthConfigToCommand_Command(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type:    "command",
+		Command: "/usr/local/bin/custom-auth --tenant prod",
+	}
+
+	cmd, err := AuthConfigToCommand(auth)
+	require.NoError(t, err)
+
+	// Command should be passed through as-is
+	require.Equal(t, "/usr/local/bin/custom-auth --tenant prod", cmd)
+}
+
+func TestAuthConfigToCommand_Command_WithEpithetSubstitution(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type:    "command",
+		Command: "epithet auth oidc --issuer https://example.com",
+	}
+
+	cmd, err := AuthConfigToCommand(auth)
+	require.NoError(t, err)
+
+	// "epithet" should be replaced with actual executable path
+	require.NotContains(t, cmd, "epithet auth")
+	require.Contains(t, cmd, "auth oidc --issuer https://example.com")
+}
+
+func TestAuthConfigToCommand_Command_Empty(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type:    "command",
+		Command: "",
+	}
+
+	_, err := AuthConfigToCommand(auth)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "non-empty command")
+}
+
+func TestAuthConfigToCommand_UnknownType(t *testing.T) {
+	t.Parallel()
+
+	auth := caclient.BootstrapAuth{
+		Type: "saml",
+	}
+
+	_, err := AuthConfigToCommand(auth)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "unknown auth type: saml")
+}