feat: add default flows deployment for Authentik authentication

- Added new "default-flows" feature to deploy opinionated Authentik 2025.10 authentication flows
- Implemented ImportFlow API method to upload flow blueprints via YAML
- Added DeleteFlowBySlug helper to safely remove existing flows before updates
- Extended CLI flags with --update-existing option to control replacement of existing resources
- Updated help text and error messages to document the new default-flows feature

The changes add support

Author: CodeMonkeyCybersecurity

cmd/update/hecate.go

@@ -211,7 +211,7 @@ func init() {
 	updateHecateCmd.Flags().String("add", "", "Add a new service to Hecate (service name)")
 	updateHecateCmd.Flags().String("remove", "", "Remove a service from Hecate (service name)")
 	updateHecateCmd.Flags().String("fix", "", "Fix drift/misconfigurations for a service (service name)")
-	updateHecateCmd.Flags().String("enable", "", "Enable a feature for Hecate (feature name: self-enrollment, oauth2-signout)")
+	updateHecateCmd.Flags().String("enable", "", "Enable a feature for Hecate (feature name: self-enrollment, oauth2-signout, default-flows)")
 	updateHecateCmd.Flags().StringP("dns", "d", "", "Domain/subdomain for the service (required with --add)")
 	updateHecateCmd.Flags().StringP("upstream", "u", "", "Backend address (ip:port or hostname:port, required with --add)")
 
@@ -223,6 +223,7 @@ func init() {
 	updateHecateCmd.Flags().Bool("enable-captcha", true, "Enable captcha for self-enrollment (default: true, uses test keys initially)")
 	updateHecateCmd.Flags().Bool("disable-captcha", false, "Disable captcha protection (NOT RECOMMENDED for production)")
 	updateHecateCmd.Flags().Bool("require-approval", false, "New users inactive until admin approves (default: active immediately)")
+	updateHecateCmd.Flags().Bool("update-existing", true, "Replace existing Authentik resources when enabling default flows")
 
 	// Optional flags for --add
 	updateHecateCmd.Flags().Bool("sso", false, "Enable SSO for this route (NOTE: BionicGPT always uses Authentik forward auth regardless of this flag)")
@@ -409,7 +410,9 @@ func runEnableFeature(rc *eos_io.RuntimeContext, cmd *cobra.Command, feature str
 		return runEnableOAuth2Signout(rc, cmd)
 	case "self-enrollment":
 		return runEnableSelfEnrollment(rc, cmd)
+	case "default-flows":
+		return runEnableDefaultFlows(rc, cmd)
 	default:
-		return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  - oauth2-signout\n  - self-enrollment", feature)
+		return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  - oauth2-signout\n  - self-enrollment\n  - default-flows", feature)
 	}
 }

cmd/update/hecate_enable.go

@@ -35,6 +35,7 @@ OLD SYNTAX (deprecated, still works):
 Available features:
   oauth2-signout     - Add /oauth2/sign_out logout handlers to Authentik-protected routes
   self-enrollment    - Enable user self-registration via Authentik enrollment flow
+  default-flows      - Deploy opinionated Authentik 2025.10 default flows for an app
 
 The enable command modifies live configuration via APIs (zero-downtime):
   - Uses Caddy Admin API to inject route handlers
@@ -75,7 +76,7 @@ Examples (NEW SYNTAX - RECOMMENDED):
 		case "self-enrollment":
 			return runEnableSelfEnrollment(rc, cmd)
 		default:
-			return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  - oauth2-signout\n  - self-enrollment", feature)
+			return fmt.Errorf("unknown feature: %s\n\nAvailable features:\n  - oauth2-signout\n  - self-enrollment\n  - default-flows", feature)
 		}
 	}),
 }
@@ -191,3 +192,33 @@ func runEnableSelfEnrollment(rc *eos_io.RuntimeContext, cmd *cobra.Command) erro
 
 	return nil
 }
+
+// runEnableDefaultFlows deploys the opinionated Authentik default flows.
+func runEnableDefaultFlows(rc *eos_io.RuntimeContext, cmd *cobra.Command) error {
+	logger := otelzap.Ctx(rc.Ctx)
+
+	appName, _ := cmd.Flags().GetString("app")
+	domain, _ := cmd.Flags().GetString("dns")
+	dryRun, _ := cmd.Flags().GetBool("dry-run")
+	updateExisting, _ := cmd.Flags().GetBool("update-existing")
+
+	if appName == "" {
+		appName = hecate.BionicGPTApplicationSlug
+		logger.Info("No --app provided, defaulting to", zap.String("app", appName))
+	}
+
+	logger.Info("Enabling Authentik default flows",
+		zap.String("app", appName),
+		zap.String("domain", domain),
+		zap.Bool("dry_run", dryRun),
+		zap.Bool("replace_existing", updateExisting))
+
+	config := &hecate.DefaultFlowsConfig{
+		App:            appName,
+		Domain:         domain,
+		DryRun:         dryRun,
+		UpdateExisting: updateExisting,
+	}
+
+	return hecate.EnableDefaultFlows(rc, config)
+}

pkg/authentik/flows.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"mime/multipart"
 	"net/http"
 )
 
@@ -163,6 +164,83 @@ func (c *APIClient) UpdateFlow(ctx context.Context, pk string, updates map[strin
 	return nil
 }
 
+// DeleteFlow removes a flow by PK.
+func (c *APIClient) DeleteFlow(ctx context.Context, pk string) error {
+	url := fmt.Sprintf("%s/api/v3/flows/instances/%s/", c.BaseURL, pk)
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, url, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("flow deletion request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNotFound {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return fmt.Errorf("flow deletion failed with status %d: %s", resp.StatusCode, string(body))
+	}
+
+	return nil
+}
+
+// DeleteFlowBySlug removes a flow if it exists.
+func (c *APIClient) DeleteFlowBySlug(ctx context.Context, slug string) error {
+	flow, err := c.GetFlow(ctx, slug)
+	if err != nil {
+		return err
+	}
+	if flow == nil {
+		return nil
+	}
+	return c.DeleteFlow(ctx, flow.PK)
+}
+
+// ImportFlow uploads a blueprint YAML definition for a flow.
+func (c *APIClient) ImportFlow(ctx context.Context, yaml []byte) error {
+	url := fmt.Sprintf("%s/api/v3/flows/instances/import/", c.BaseURL)
+
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	part, err := writer.CreateFormFile("file", "flow.yaml")
+	if err != nil {
+		return fmt.Errorf("failed to create multipart form: %w", err)
+	}
+
+	if _, err := part.Write(yaml); err != nil {
+		return fmt.Errorf("failed to write flow blueprint: %w", err)
+	}
+
+	if err := writer.Close(); err != nil {
+		return fmt.Errorf("failed to finalize multipart form: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, body)
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("flow import request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusNoContent {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
+		return fmt.Errorf("flow import failed with status %d: %s", resp.StatusCode, string(body))
+	}
+
+	return nil
+}
+
 // CreateEnrollmentFlow creates a new enrollment flow
 func (c *APIClient) CreateEnrollmentFlow(ctx context.Context, name, slug, title string) (*FlowResponse, error) {
 	reqBody := map[string]interface{}{
@@ -211,30 +289,6 @@ func (c *APIClient) CreateEnrollmentFlow(ctx context.Context, name, slug, title
 	return &flow, nil
 }
 
-// DeleteFlow deletes a flow by PK
-func (c *APIClient) DeleteFlow(ctx context.Context, pk string) error {
-	url := fmt.Sprintf("%s/api/v3/flows/instances/%s/", c.BaseURL, pk)
-	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, url, nil)
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("Authorization", "Bearer "+c.Token)
-
-	resp, err := c.HTTPClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("flow deletion request failed: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
-		return fmt.Errorf("flow deletion failed with status %d: %s", resp.StatusCode, string(body))
-	}
-
-	return nil
-}
-
 // GetFlowStages retrieves all stage bindings for a flow (ordered by binding order)
 // Returns stages in execution order for the given flow
 func (c *APIClient) GetFlowStages(ctx context.Context, flowPK string) ([]StageBindingResponse, error) {