Merge pull request #192 from aojea/refactor_control_plane

Fix postgres volume mounting on GKE and switch E2E tests to dynamic b…

Author: aojea

.github/k8s/sam-control-plane-template.yaml

@@ -41,6 +41,8 @@ spec:
       labels:
         app: sam-db-${ENV_NAME}
     spec:
+      securityContext:
+        fsGroup: 999
       containers:
       - name: postgres
         image: postgres:16-alpine
@@ -51,6 +53,8 @@ spec:
           value: sam
         - name: POSTGRES_PASSWORD
           value: sam-secret-password
+        - name: PGDATA
+          value: /var/lib/postgresql/data/pgdata
         ports:
         - containerPort: 5432
           protocol: TCP
@@ -81,9 +85,20 @@ spec:
       labels:
         app: sam-control-plane-${ENV_NAME}
     spec:
+      initContainers:
+      - name: wait-for-db
+        image: busybox:1.36.1
+        command: ['sh', '-c', 'until nc -z -w3 sam-db-${ENV_NAME} 5432; do echo waiting for db; sleep 1; done']
       containers:
       - name: sam-control-plane
         image: ghcr.io/google/sam-control-plane:${IMAGE_TAG}
+        env:
+        - name: ADMIN_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: sam-control-plane-secret-${ENV_NAME}
+              key: admin-token
+              optional: true
         ports:
         - containerPort: 8080
           protocol: TCP
@@ -109,6 +124,7 @@ spec:
         - "--issuer=https://auth.sam-mesh.dev,https://container.googleapis.com/v1/projects/${GCP_PROJECT_ID}/locations/${CLUSTER_REGION}/clusters/${CLUSTER_NAME}"
         - "--allowed-audiences=sam-mesh-audience,sam-hub-audience"
         - "--policy-file=/etc/sam/policies/policies.yaml"
+        - "--admin-token=$(ADMIN_TOKEN)"
         resources:
           requests:
             cpu: 100m

.github/workflows/deploy.yaml

@@ -222,6 +222,20 @@ jobs:
 
 
 
+      - name: Provision Control Plane Secrets
+        run: |
+          export ENV_NAME="${{ vars.ENV_NAME }}"
+          export NAMESPACE="sam-${ENV_NAME}"
+          if ! kubectl get secret sam-control-plane-secret-${ENV_NAME} -n ${NAMESPACE} >/dev/null 2>&1; then
+            echo "Generating a new random 32-byte hex key for admin-token..."
+            ADMIN_TOKEN=$(openssl rand -hex 32)
+            kubectl create secret generic sam-control-plane-secret-${ENV_NAME} \
+              --namespace=${NAMESPACE} \
+              --from-literal=admin-token="${ADMIN_TOKEN}"
+          else
+            echo "sam-control-plane-secret-${ENV_NAME} already exists in namespace ${NAMESPACE}. Skipping generation."
+          fi
+
       - name: Deploy Control Plane and Routers
         run: |
           print_rollout_diagnostics() {

cmd/sam-control-plane/main.go

@@ -38,7 +38,6 @@ var (
 	keyGracePeriod        time.Duration
 	leaseDuration         time.Duration
 	adminToken            string
-	bootstrapToken        string
 	insecureSkipTLSVerify bool
 	logLevel              string
 	autoApproveEnrollment bool
@@ -101,7 +100,6 @@ func main() {
 				InsecureSkipTLSVerify: insecureSkipTLSVerify,
 				PolicyPath:            policyFile,
 				BiscuitTimeout:        10 * time.Second,
-				BootstrapToken:        bootstrapToken,
 				AdminToken:            adminToken,
 				AutoApproveEnrollment: autoApproveEnrollment,
 			}
@@ -135,7 +133,6 @@ func main() {
 	rootCmd.Flags().DurationVar(&keyGracePeriod, "key-grace-period", 1*time.Hour, "Key grace period for rotated keys.")
 	rootCmd.Flags().DurationVar(&leaseDuration, "lease-duration", 15*time.Minute, "Router lease registration TTL.")
 	rootCmd.Flags().StringVar(&adminToken, "admin-token", "", "Token for authenticating policy REST API requests")
-	rootCmd.Flags().StringVar(&bootstrapToken, "bootstrap-token", "", "Pre-shared bootstrap token for bypassing OIDC verification")
 	rootCmd.Flags().BoolVar(&insecureSkipTLSVerify, "insecure-skip-tls-verify", false, "Skip TLS verification for OIDC providers")
 	rootCmd.Flags().StringVar(&logLevel, "log-level", "info", "Log level (debug, info, warn, error)")
 	rootCmd.Flags().BoolVar(&autoApproveEnrollment, "auto-approve-enrollment", false, "Auto-approve valid bootstrap token enrollment requests")

internal/controlplane/config.go

@@ -32,7 +32,6 @@ type Options struct {
 	InsecureSkipTLSVerify bool
 	BiscuitTimeout        time.Duration
 	PolicyPath            string // Optional: path to bootstrap policy configuration
-	BootstrapToken        string // Optional: pre-shared bootstrap token for bypassing OIDC verification (e.g. for router enrollment)
 	AdminToken            string // Optional: administrative bearer token for protecting policy and enrollment queue REST APIs
 	AutoApproveEnrollment bool   // If true, valid bootstrap token enrollment requests are immediately approved without administrative manual gate
 }

internal/controlplane/server.go

@@ -123,30 +123,7 @@ func (s *Server) Start() error {
 		}
 	}
 
-	// Seed the initial command-line bootstrap token if provided
-	if s.config.BootstrapToken != "" {
-		hash := sha256.Sum256([]byte(s.config.BootstrapToken))
-		tokenID := fmt.Sprintf("%x", hash)
-		_, err := s.store.GetBootstrapToken(ctx, tokenID)
-		if err == storage.ErrNotFound {
-			logger.Infof("Seeding initial bootstrap token into database (ID: %s)...", tokenID)
-			tokenRecord := &storage.BootstrapToken{
-				ID:          tokenID,
-				TokenHash:   tokenID,
-				Role:        api.RoleRouter,
-				MaxUsages:   10000,
-				UsagesCount: 0,
-				Description: "Command Line Seeded Token",
-				CreatedAt:   time.Now(),
-				ExpiresAt:   time.Now().Add(365 * 24 * time.Hour),
-			}
-			if err := s.store.SaveBootstrapToken(ctx, tokenRecord); err != nil {
-				return fmt.Errorf("failed to save initial bootstrap token: %w", err)
-			}
-		} else if err != nil {
-			return fmt.Errorf("failed to check initial bootstrap token state: %w", err)
-		}
-	}
+
 
 	// Initialize OIDC Providers
 	if err := s.discoverProviders(); err != nil {
@@ -928,9 +905,19 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
 	existingReq, err := s.store.GetEnrollmentRequest(ctx, req.PeerId)
 	if err == nil {
 		// Request already exists, return status
-		resp := &api.BootstrapEnrollResponse{
-			Status:       existingReq.Status,
-			BiscuitToken: existingReq.BiscuitToken,
+		var resp *api.BootstrapEnrollResponse
+		if existingReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED {
+			resp, err = s.buildApprovedBootstrapEnrollResponse(ctx, existingReq.BiscuitToken, existingReq.ResolvedAt)
+			if err != nil {
+				logger.Errorf("Failed to build approved response: %v", err)
+				http.Error(w, "Internal server error", http.StatusInternalServerError)
+				return
+			}
+		} else {
+			resp = &api.BootstrapEnrollResponse{
+				Status:       existingReq.Status,
+				BiscuitToken: existingReq.BiscuitToken,
+			}
 		}
 		s.writeEnrollResponse(w, resp)
 		return
@@ -1006,9 +993,11 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
 			logger.Errorf("Failed to increment token usage: %v", err)
 		}
 
-		resp := &api.BootstrapEnrollResponse{
-			Status:       api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED,
-			BiscuitToken: biscuitBytes,
+		resp, err := s.buildApprovedBootstrapEnrollResponse(ctx, biscuitBytes, enrollReq.ResolvedAt)
+		if err != nil {
+			logger.Errorf("Failed to build approved response: %v", err)
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+			return
 		}
 		s.writeEnrollResponse(w, resp)
 		return
@@ -1052,12 +1041,22 @@ func (s *Server) HandleEnrollStatus(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	resp := &api.BootstrapEnrollResponse{
-		Status:       enrollReq.Status,
-		BiscuitToken: enrollReq.BiscuitToken,
-	}
-	if enrollReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING {
-		resp.PollIntervalSeconds = 30
+	var resp *api.BootstrapEnrollResponse
+	if enrollReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED {
+		resp, err = s.buildApprovedBootstrapEnrollResponse(ctx, enrollReq.BiscuitToken, enrollReq.ResolvedAt)
+		if err != nil {
+			logger.Errorf("Failed to build approved response: %v", err)
+			http.Error(w, "Internal server error", http.StatusInternalServerError)
+			return
+		}
+	} else {
+		resp = &api.BootstrapEnrollResponse{
+			Status:       enrollReq.Status,
+			BiscuitToken: enrollReq.BiscuitToken,
+		}
+		if enrollReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING {
+			resp.PollIntervalSeconds = 30
+		}
 	}
 	s.writeEnrollResponse(w, resp)
 }
@@ -1350,3 +1349,34 @@ func (s *Server) HandleAdminRevoke(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(respData)
 }
+
+func (s *Server) buildApprovedBootstrapEnrollResponse(ctx context.Context, biscuitToken []byte, resolvedAt *time.Time) (*api.BootstrapEnrollResponse, error) {
+	_, pubKey, err := s.store.GetCurrentKey(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to retrieve signing key: %w", err)
+	}
+
+	activeRouters, err := s.store.GetActiveRouters(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to retrieve active routers: %w", err)
+	}
+
+	var routerAddrs []string
+	for _, r := range activeRouters {
+		routerAddrs = append(routerAddrs, r.Addresses...)
+	}
+
+	expiration := time.Now().Add(api.BiscuitTokenTTL).Unix()
+	if resolvedAt != nil {
+		expiration = resolvedAt.Add(api.BiscuitTokenTTL).Unix()
+	}
+
+	return &api.BootstrapEnrollResponse{
+		Status:         api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED,
+		BiscuitToken:  biscuitToken,
+		HubPublicKey:  pubKey,
+		HubAddresses:  routerAddrs,
+		Expiration:     expiration,
+	}, nil
+}
+

internal/controlplane/server_test.go

@@ -128,7 +128,7 @@ func setupTestServer(t *testing.T, oidcIssuer string) (*Server, storage.Store, s
 		KeyRotationInterval:   12 * time.Hour,
 		KeyGracePeriod:        10 * time.Minute,
 		InsecureSkipTLSVerify: true,
-		BiscuitTimeout:        1 * time.Second,
+		BiscuitTimeout:        10 * time.Second,
 	}
 
 	srv, err := NewServer(opts, store)
@@ -583,6 +583,9 @@ func TestEnrollmentWorkflow(t *testing.T) {
 	if len(statusResp.BiscuitToken) == 0 {
 		t.Fatalf("biscuit token is empty")
 	}
+	if len(statusResp.HubPublicKey) == 0 {
+		t.Fatalf("hub public key is empty")
+	}
 
 	// Verify Biscuit router rights
 	_, cpPub, err := store.GetCurrentKey(context.Background())

site/content/docs/quickstart.md

@@ -40,15 +40,18 @@ Expand-Archive -Path "sam.zip" -DestinationPath "$env:ProgramFiles\sam"
 
 ## 2. Join the Mesh
 
-To register your node with the mesh and obtain a cryptographic identity token (Biscuit), run the OIDC authorization flow. 
+To register your node with the mesh and obtain a cryptographic identity token (Biscuit), you can use either the interactive OIDC authorization flow or the non-interactive bootstrap token flow. 
 
-### Using the Binary
+### Option A: Interactive OIDC Flow (Default)
+
+The interactive flow uses your browser to authenticate your identity against Dex (OIDC):
+
+#### Using the Binary
 ```bash
 sam-node join https://bananas.sam-mesh.dev
 ```
 
-### Using Docker
-Create a local directory to persist your node identity:
+#### Using Docker
 ```bash
 mkdir -p $(pwd)/sam-data
 docker run -it \
@@ -57,7 +60,26 @@ docker run -it \
   join --data-dir /data https://bananas.sam-mesh.dev
 ```
 
-The CLI will output a Device Authorization URL (if headless/Docker) or open your browser (if using the binary natively). Once authenticated, the node registers and saves the identity to `~/.config/sam-mesh/agent.db` (or `/data/agent.db` in Docker).
+The CLI will output a Device Authorization URL (if headless/Docker) or open your browser natively. Once authenticated, the node registers and saves the identity database.
+
+### Option B: Non-Interactive Bootstrap Flow (Headless)
+
+If you are deploying a headless server or router and have a generated bootstrap token from the Control Plane API:
+
+#### Using the Binary
+```bash
+sam-node join --bootstrap-token <your-token> https://bananas.sam-mesh.dev
+```
+
+#### Using Docker
+```bash
+docker run -it \
+  -v $(pwd)/sam-data:/data \
+  ghcr.io/google/sam-node:latest \
+  join --data-dir /data --bootstrap-token <your-token> https://bananas.sam-mesh.dev
+```
+
+*Note: In non-interactive mode, unless the Hub runs with `--auto-approve-enrollment`, the enrollment request remains **PENDING** until approved manually by a network administrator.*
 
 ---
 

site/content/docs/user/control-plane-configuration.md

@@ -153,3 +153,61 @@ Administrators can immediately revoke any active session to disable a node's abi
   }
   ```
 * **Enforcement**: Revoked nodes are marked as banned in the database. When the node next attempts a proactive `/refresh` handshake, the request is denied with a `403 Forbidden` status, and the node's local daemon immediately terminates.
+
+---
+
+## 6. Headless Node Enrollment (Bootstrap Token Flow)
+
+To enroll a headless server, router, or background daemon that cannot complete interactive OIDC authentication, SAM supports a **Bootstrap Token** flow.
+
+### Step 1: Generate a Bootstrap Token
+
+An administrator with the `admin-token` can dynamically generate a time-bounded, single-use bootstrap token:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <your-admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"role": "sam:role:node", "ttl_hours": 24, "max_usages": 1, "description": "Headless node deployment token"}' \
+  http://<control-plane-ip>:8080/admin/bootstrap-tokens
+```
+
+This returns a JSON response containing the plaintext token:
+```json
+{
+  "id": "62e92ffca...",
+  "token": "sam-bt-72fb0175788dee0...",
+  "role": "sam:role:node",
+  "expires_at": "2026-07-12T15:00:00Z"
+}
+```
+
+### Step 2: Request Enrollment on the Node
+
+Run the node `join` command with the generated token:
+
+```bash
+sam-node join --bootstrap-token sam-bt-72fb0175788dee0... http://<control-plane-ip>:8080
+```
+
+The node submits its enrollment request and waits (polls) for approval.
+
+### Step 3: Approve the Enrollment
+
+Administrators can review pending enrollment requests:
+
+```bash
+# List all pending enrollments
+curl -H "Authorization: Bearer <your-admin-token>" http://<control-plane-ip>:8080/admin/enrollments
+```
+
+To approve the request and issue the node its identity Biscuit:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <your-admin-token>" \
+  http://<control-plane-ip>:8080/admin/enrollments/<request-id>/approve
+```
+
+Alternatively, you can boot the control plane with `--auto-approve-enrollment` to automatically approve all valid bootstrap token requests without manual gates.
+