feat(cfsetup): recommended Cloudflare Tunnel + Access edge setup

// Package cfsetup builds the RECOMMENDED, one-click Cloudflare Tunnel + Access

// configuration the felis breakGlass TUI can offer a SysAdmin (spec §14 Zero

// Trust edge). It is deliberately "锦上添花" — icing, not a mandate: the platform

// is domain-agnostic (every FQDN is composed from the configured root_domain) and

// IdP-agnostic (felis-api validates ANY valid Cloudflare Access JWT `aud`, no

// matter which identity provider — Google Workspace, Keycloak, Microsoft Entra —

// fronts it). A SysAdmin who brings their own domain or a different Zero-Trust

// scheme is fully supported; this package only makes the common case easy.

//

// The split is honest about what this box can verify:

//

//   - PURE + UNIT-VERIFIED here: the ingress-config generation, the Access

//     application/policy request bodies, the gating preconditions, and — the one

//     load-bearing safety property — the FAIL-CLOSED guard on the recommended

//     policy (it must never serialize to public/allow-everyone or skip auth).

//   - INTEGRATION-ONLY (see runner.go): actually creating the tunnel, routing

//     DNS, and POSTing the Access app/policy. Those require the operator's OWN

//     live Cloudflare account and the interactive `cloudflared tunnel login`

//     browser consent, which this package can neither perform nor fake.

//

// Setup wires the two together behind a Runner interface so the orchestration is

// testable with a fake while the real exec/HTTP impl stays integration-only.

package cfsetup

import (

	"context"

	"errors"

	"fmt"

	"strings"

	"sigs.k8s.io/yaml"

)

// defaultPanelOrigin is where the tunnel forwards the web hostnames when the

// caller does not override it: the felis-api listen port (config defaultListen

// is 0.0.0.0:8080), reachable on the box as loopback.

const defaultPanelOrigin = "http://localhost:8080"

// defaultSessionDuration is the recommended Access session length when unset.

const defaultSessionDuration = "24h"

// catchAllService is the cloudflared sentinel that returns a bare 404 for any

// hostname not explicitly routed. cloudflared REQUIRES the final ingress rule to

// be a hostname-less catch-all; we always make it this fail-shut 404 so the

// tunnel never forwards an unexpected Host to the origin.

const catchAllService = "http_status:404"

// Gating errors — Setup refuses (with NO side effects) unless every precondition

// the operator alone can satisfy is met. The TUI surfaces these as remediation.

var (

	// ErrCloudflaredMissing means the cloudflared binary is not on PATH.

	ErrCloudflaredMissing = errors.New("cfsetup: cloudflared binary not found on PATH — install cloudflared first")

	// ErrNotLoggedIn means ~/.cloudflared/cert.pem is absent: the operator has

	// not run `cloudflared tunnel login`. That step is an interactive browser

	// consent against the operator's OWN Cloudflare account; the TUI cannot and

	// must not bypass it.

	ErrNotLoggedIn = errors.New("cfsetup: not logged in to Cloudflare — run `cloudflared tunnel login` first (browser consent on your own account)")

	// ErrNoAPIToken means no Cloudflare API token was supplied for the Access

	// application/policy calls.

	ErrNoAPIToken = errors.New("cfsetup: a Cloudflare API token is required to configure Access")

)

// AccessIdentity scopes WHO the recommended Access policy admits. At least one

// field must be set — an empty identity is refused as fail-open. The three

// dimensions map straight onto Cloudflare Access rule types and cover the

// SSO-provider case the SysAdmin may want (Google Workspace / Keycloak / Entra

// are registered in Access as IdPs; LoginMethods names their IdP ids):

//

//   - Emails       → include {email:{email}}          (specific people)

//   - EmailDomains → include {email_domain:{domain}}  (an org's SSO domain)

//   - LoginMethods → require {login_method:{id}}       (only this IdP/SSO)

type AccessIdentity struct {

	Emails       []string

	EmailDomains []string

	LoginMethods []string

}

func (id AccessIdentity) empty() bool {

	return len(id.Emails) == 0 && len(id.EmailDomains) == 0 && len(id.LoginMethods) == 0

}

// accessRule is one Cloudflare Access rule object, e.g. {"email":{"email":...}}

// or {"everyone":{}}. Modeled as a map so the include/require/exclude arrays

// serialize to exactly the shapes the Access API expects.

type accessRule map[string]map[string]any

// AccessPolicy is the request body for an Access policy (decision + the

// include/require/exclude rule arrays, which compose as OR / AND / NOT).

type AccessPolicy struct {

	Name     string       `json:"name"`

	Decision string       `json:"decision"`

	Include  []accessRule `json:"include"`

	Require  []accessRule `json:"require,omitempty"`

	Exclude  []accessRule `json:"exclude,omitempty"`

}

// AccessApplication is the request body for a self-hosted Access application

// fronting one web hostname (spec §14: the op.console SysAdmin face). The cookie

// hardening defaults are on because this guards the most privileged surface.

type AccessApplication struct {

	Name                    string   `json:"name"`

	Domain                  string   `json:"domain"`

	Type                    string   `json:"type"`

	SessionDuration         string   `json:"session_duration,omitempty"`

	AllowedIdPs             []string `json:"allowed_idps,omitempty"`

	AppLauncherVisible      bool     `json:"app_launcher_visible"`

	EnableBindingCookie     bool     `json:"enable_binding_cookie"`

	HTTPOnlyCookieAttribute bool     `json:"http_only_cookie_attribute"`

}

// BuildAccessApplication assembles a self-hosted Access application for one

// hostname. allowedIdPs, when non-empty, restricts which configured IdPs (the

// SysAdmin's chosen SSO) may satisfy the app — left empty, Access offers all

// configured IdPs.

func BuildAccessApplication(domain, name string, sessionDuration string, allowedIdPs []string) AccessApplication {

	if sessionDuration == "" {

		sessionDuration = defaultSessionDuration

	}

	return AccessApplication{

		Name:                    name,

		Domain:                  domain,

		Type:                    "self_hosted",

		SessionDuration:         sessionDuration,

		AllowedIdPs:             allowedIdPs,

		AppLauncherVisible:      false,

		EnableBindingCookie:     true,

		HTTPOnlyCookieAttribute: true,

	}

}

// BuildRecommendedPolicy assembles the recommended fail-closed Access policy that

// admits exactly the given identity. It returns an error rather than emit a

// policy that would be public — an empty identity, or any result that does not

// pass validateFailClosed, is refused here so a caller can never accidentally

// ship an open door. Scoping by LoginMethods alone yields "everyone who

// authenticates via this SSO IdP" (include everyone + require login_method),

// which is constrained, not public.

func BuildRecommendedPolicy(name string, id AccessIdentity) (AccessPolicy, error) {

	if id.empty() {

		return AccessPolicy{}, errors.New("cfsetup: recommended policy needs at least one identity (email, email domain, or SSO login method) — refusing to build a public policy")

	}

	p := AccessPolicy{Name: name, Decision: "allow"}

	for _, e := range id.Emails {

		p.Include = append(p.Include, accessRule{"email": {"email": e}})

	}

	for _, d := range id.EmailDomains {

		p.Include = append(p.Include, accessRule{"email_domain": {"domain": d}})

	}

	for _, m := range id.LoginMethods {

		p.Require = append(p.Require, accessRule{"login_method": {"id": m}})

	}

	// If the identity is scoped ONLY by SSO login method, the include set needs a

	// base match for the require to narrow; "everyone gated by require login_method"

	// is the Cloudflare-recommended authenticated-users shape and stays fail-closed.

	if len(p.Include) == 0 {

		p.Include = append(p.Include, accessRule{"everyone": {}})

	}

	if err := validateFailClosed(p); err != nil {

		return AccessPolicy{}, err

	}

	return p, nil

}

// validateFailClosed is the load-bearing safety property of this whole package,

// the analog of "never catches the genuine Mojang player" in the reclaim flow: a

// recommended Access policy that guards op.console MUST NOT be public.

//

// It is an ALLOWLIST, not a denylist — the only fail-closed design for a guard

// whose whole job is to catch shapes the current builder does not produce. The

// critical fact is that Cloudflare Access `include` rules combine as OR: a user is

// admitted if they match ANY one include rule. So an `everyone` include makes the

// whole include set public no matter what other identity rules sit beside it (the

// identity rule is pure redundancy in an OR), and only a `require` clause — which

// is AND — can narrow an `everyone` base. A denylist of known-bad shapes would

// miss both everyone-OR-identity and unrecognized public includes (e.g. an

// ip:0.0.0.0/0 rule); the allowlist refuses anything it cannot positively

// recognize as scoped.

//

// A policy passes iff: decision is "allow" (not "bypass", which skips auth, nor

// anything else); the include set is non-empty; and EITHER every include rule is a

// recognized scoped identity (email, email_domain) with no `everyone`, OR the

// include set's `everyone` base is narrowed by a constraining require clause

// (login_method / email_domain / email). Setup runs this before the policy is ever

// POSTed, so even a future builder bug cannot open the door.

func validateFailClosed(p AccessPolicy) error {

	switch p.Decision {

	case "bypass":

		return errors.New("cfsetup: refusing policy with decision \"bypass\" — it skips authentication for everyone (fail-open)")

	case "allow":

		// the only decision the recommended path emits

	default:

		return fmt.Errorf("cfsetup: refusing recommended policy with decision %q — must be \"allow\"", p.Decision)

	}

	if len(p.Include) == 0 {

		return errors.New("cfsetup: refusing policy with no include rules")

	}

	// Classify the include set against the allowlist. Each rule must positively

	// resolve to a recognized scoped identity or the `everyone` base; anything

	// else — an unrecognized type OR a degenerate empty/malformed rule with no

	// recognized key — is treated as potentially-public and refused.

	includeHasEveryone := false

	for _, r := range p.Include {

		scoped := false

		everyone := false

		for key := range r {

			switch key {

			case "email", "email_domain":

				scoped = true // a scoped identity — safe to OR into the include set

			case "everyone":

				everyone = true

			default:

				return fmt.Errorf("cfsetup: refusing policy with unrecognized include rule %q — a fail-closed policy admits only scoped identities (email, email_domain) or an \"everyone\" base narrowed by a require", key)

			}

		}

		if everyone {

			includeHasEveryone = true

		}

		if !scoped && !everyone {

			return errors.New("cfsetup: refusing an include rule that is neither a scoped identity nor \"everyone\" (empty or malformed) — fail-closed")

		}

	}

	if !includeHasEveryone {

		// Every include rule is a recognized scoped identity; the OR of scoped

		// identities is itself scoped. Fail-closed.

		return nil

	}

	// The include set admits everyone; only a constraining require (AND) can save

	// it. A require of `everyone` (or any unrecognized type) does not narrow.

	requireConstrains := false

	for _, r := range p.Require {

		for key := range r {

			switch key {

			case "login_method", "email_domain", "email":

				requireConstrains = true

			}

		}

	}

	if !requireConstrains {

		return errors.New("cfsetup: refusing policy that admits \"everyone\" with no constraining require — that is public access (fail-open)")

	}

	return nil

}

// tunnelConfig is the cloudflared config.yml shape: the tunnel UUID, its

// credentials file, and the ordered ingress rules (the last of which MUST be the

// hostname-less catch-all).

type tunnelConfig struct {

	Tunnel          string        `json:"tunnel"`

	CredentialsFile string        `json:"credentials-file"`

	Ingress         []ingressRule `json:"ingress"`

}

// ingressRule is one cloudflared ingress entry. A rule with an empty Hostname is

// the catch-all (must be last).

type ingressRule struct {

	Hostname string `json:"hostname,omitempty"`

	Service  string `json:"service"`

}

// BuildTunnelConfig renders the cloudflared config.yml that routes each web

// hostname to the local panel origin and terminates in the required fail-shut

// catch-all 404. The game host (the bare root_domain / mc. host) is deliberately

// NOT a hostname here — Minecraft stays raw protocol off the tunnel; only the

// passed web hostnames (console., op.console.) are proxied.

func BuildTunnelConfig(tunnelID, credentialsFile, panelOrigin string, hostnames []string) ([]byte, error) {

	if tunnelID == "" {

		return nil, errors.New("cfsetup: tunnel id is required")

	}

	if panelOrigin == "" {

		panelOrigin = defaultPanelOrigin

	}

	if len(hostnames) == 0 {

		return nil, errors.New("cfsetup: at least one web hostname is required")

	}

	cfg := tunnelConfig{Tunnel: tunnelID, CredentialsFile: credentialsFile}

	for _, h := range hostnames {

		if h == "" {

			return nil, errors.New("cfsetup: empty hostname in ingress")

		}

		cfg.Ingress = append(cfg.Ingress, ingressRule{Hostname: h, Service: panelOrigin})

	}

	// The mandatory trailing catch-all: anything not explicitly routed gets a bare

	// 404, never a forward to the origin.

	cfg.Ingress = append(cfg.Ingress, ingressRule{Service: catchAllService})

	return yaml.Marshal(cfg)

}

// Preconditions are the gating facts only the operator can satisfy, detected off

// the box (see DetectPreconditions in runner.go) and passed in as data so Setup

// stays unit-testable.

type Preconditions struct {

	// CloudflaredPath is the resolved cloudflared binary path; empty = not found.

	CloudflaredPath string

	// CertExists reports whether ~/.cloudflared/cert.pem is present, i.e. the

	// operator has completed `cloudflared tunnel login`.

	CertExists bool

	// APIToken is the Cloudflare API token for the Access app/policy calls.

	APIToken string

}

func (p Preconditions) check() error {

	if p.CloudflaredPath == "" {

		return ErrCloudflaredMissing

	}

	if !p.CertExists {

		return ErrNotLoggedIn

	}

	if strings.TrimSpace(p.APIToken) == "" {

		return ErrNoAPIToken

	}

	return nil

}

// Runner is the integration seam: every side-effecting step of the setup. The

// real implementation (ExecRunner in runner.go) shells out to cloudflared and

// calls the Cloudflare API and is INTEGRATION-ONLY; tests pass a fake.

type Runner interface {

	// CreateTunnel creates (or, idempotently, returns the existing) named tunnel,

	// yielding its UUID and the path to its credentials file.

	CreateTunnel(ctx context.Context, name string) (id, credentialsFile string, err error)

	// RouteDNS points hostname at the tunnel (a proxied CNAME).

	RouteDNS(ctx context.Context, tunnelID, hostname string) error

	// WriteTunnelConfig persists the rendered config.yml.

	WriteTunnelConfig(path string, contents []byte) error

	// CreateAccessApplication creates the self-hosted Access app and returns its

	// id and the issued JWT `aud` (which felis [auth] access_jwt_aud must adopt).

	CreateAccessApplication(ctx context.Context, app AccessApplication) (appID, aud string, err error)

	// CreateAccessPolicy attaches policy to the Access app.

	CreateAccessPolicy(ctx context.Context, appID string, policy AccessPolicy) error

}

// Params is the full input to Setup. Hostnames are passed in (composed by the

// caller from the configured root_domain) so this package never hardcodes a

// domain or subdomain scheme.

type Params struct {

	PanelHostname   string // console.<root_domain> (Player web)

	AdminHostname   string // op.console.<root_domain> (Operator+SysAdmin web)

	PanelOrigin     string // where the tunnel forwards; default http://localhost:8080

	TunnelName      string

	ConfigPath      string // where to write config.yml

	SessionDuration string

	AllowedIdPs     []string       // restrict the Access app to these IdPs (SSO)

	AccessIdentity  AccessIdentity // WHO the policy admits (fail-closed)

	Pre             Preconditions

}

// Result reports what Setup produced, including the Access `aud` the caller must

// write into felis [auth] access_jwt_aud to make felis-api accept the new edge.

type Result struct {

	TunnelID        string

	CredentialsFile string

	ConfigPath      string

	AccessAppID     string

	AccessAud       string

	RoutedHostnames []string

}

// Setup runs the recommended Cloudflare Tunnel + Access provisioning end to end

// behind the Runner. It is ordered so that EVERY check the box can make happens

// BEFORE any side effect: it gates on preconditions and builds + fail-closed-

// guards the policy first, returning early with no Runner calls if either fails.

// Only then does it create the tunnel, route the web hostnames (never the game

// host), write the config, create the Access app for the admin face, and attach

// the guarded policy.

func Setup(ctx context.Context, runner Runner, p Params) (*Result, error) {

	if runner == nil {

		return nil, errors.New("cfsetup: runner is required")

	}

	if p.AdminHostname == "" {

		return nil, errors.New("cfsetup: admin hostname is required")

	}

	if p.TunnelName == "" {

		return nil, errors.New("cfsetup: tunnel name is required")

	}

	// 1. Gate on operator-only preconditions — no side effects on failure.

	if err := p.Pre.check(); err != nil {

		return nil, err

	}

	// 2. Build and fail-closed-guard the policy BEFORE touching Cloudflare, so a

	//    public/unscoped policy aborts the whole run with nothing created.

	policy, err := BuildRecommendedPolicy("felis-recommended", p.AccessIdentity)

	if err != nil {

		return nil, err

	}

	if err := validateFailClosed(policy); err != nil {

		return nil, err // belt-and-suspenders: never POST an open policy

	}

	hostnames := webHostnames(p)

	origin := p.PanelOrigin

	if origin == "" {

		origin = defaultPanelOrigin

	}

	// 3. Create the tunnel.

	id, cred, err := runner.CreateTunnel(ctx, p.TunnelName)

	if err != nil {

		return nil, fmt.Errorf("cfsetup: create tunnel: %w", err)

	}

	// 4. Route DNS for each WEB hostname only (the game host stays off the tunnel).

	for _, h := range hostnames {

		if err := runner.RouteDNS(ctx, id, h); err != nil {

			return nil, fmt.Errorf("cfsetup: route dns %s: %w", h, err)

		}

	}

	// 5. Render and persist the ingress config.

	cfgBytes, err := BuildTunnelConfig(id, cred, origin, hostnames)

	if err != nil {

		return nil, err

	}

	if p.ConfigPath != "" {

		if err := runner.WriteTunnelConfig(p.ConfigPath, cfgBytes); err != nil {

			return nil, fmt.Errorf("cfsetup: write config: %w", err)

		}

	}

	// 6. Front the admin face with a self-hosted Access app.

	app := BuildAccessApplication(p.AdminHostname, "Felis SysAdmin Console", p.SessionDuration, p.AllowedIdPs)

	appID, aud, err := runner.CreateAccessApplication(ctx, app)

	if err != nil {

		return nil, fmt.Errorf("cfsetup: create access application: %w", err)

	}

	// 7. Attach the guarded fail-closed policy.

	if err := runner.CreateAccessPolicy(ctx, appID, policy); err != nil {

		return nil, fmt.Errorf("cfsetup: create access policy: %w", err)

	}

	return &Result{

		TunnelID:        id,

		CredentialsFile: cred,

		ConfigPath:      p.ConfigPath,

		AccessAppID:     appID,

		AccessAud:       aud,

		RoutedHostnames: hostnames,

	}, nil

}

// webHostnames returns the web hostnames to route, in order: panel (console.)

// first when present, then the admin (op.console.) face. The admin host is

// required; the panel host is optional (a SysAdmin may tunnel only the admin

// surface).

func webHostnames(p Params) []string {

	var hs []string

	if p.PanelHostname != "" {

		hs = append(hs, p.PanelHostname)

	}

	hs = append(hs, p.AdminHostname)

	return hs

}