feat(consent): add app.consent config, the consent service, and ListConsentDocuments

Config is the source of truth for what a deployment asks people to accept,
and an endpoint is how a client learns it. No database, no writes, and
frontier never reads a document or parses a version string.

app.consent is a map keyed by document id, beside app.authentication and
app.pat. A map because it matches authenticate.Config keying oidc_config by
strategy name, the key enforces unique ids, and a single field stays
env-overridable. Every document in it is required at signup, so there is no
per-document required flag: an optional document would need withdrawal,
which is out of scope.

Boot validation rejects empty ids, versions and URLs, URLs that do not parse
or that a client cannot link to, and an enabled block with no documents,
which would otherwise look identical to a working deployment while asking
nobody to accept anything. The resolved set is logged at boot, because an
env override cannot alter an existing record but it can produce wrong new
ones, and that log rather than the config repo is what says what a
deployment was serving.

The service owns the config, so it owns the checks. Documents orders by id.
Resolve maps ids to their config snapshots and rejects ids config does not
know, saying nothing about completeness. ResolveAll adds the completeness
rule and compares both sets in both directions, so the error names what is
wrong. Disabled, all three are empty and no id is rejected, so one client
build works against both kinds of deployment.

ListConsentDocuments mirrors ListAuthStrategies and is unauthenticated on
purpose: the URLs are meant to be read by anyone considering an account, and
the ids are an input to an unauthenticated Authenticate, so requiring a
session to learn what to accept before the account exists is a cycle. It
joins both the authentication and the authorization skip lists, since an
endpoint missing from the second is denied by default.

The transactional write and the SDK follow separately.

Refs docs/rfcs/0002-explicit-consent-at-signup.md

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VW3nysiE4H83VQk6BroMYc

Author: rohanchkrabrty

cmd/serve.go

@@ -93,6 +93,7 @@ import (
 
 	"github.com/go-webauthn/webauthn/webauthn"
 	"github.com/raystack/frontier/config"
+	"github.com/raystack/frontier/core/consent"
 	"github.com/raystack/frontier/core/group"
 	"github.com/raystack/frontier/core/membership"
 	"github.com/raystack/frontier/core/namespace"
@@ -343,6 +344,14 @@ func buildAPIDependencies(
 	}
 	preferenceService := preference.NewService(postgres.NewPreferenceRepository(dbc), traits)
 
+	// consent config is validated here so a deployment that asks for documents
+	// it cannot serve fails at boot instead of at someone's signup
+	if err := cfg.App.Consent.Validate(); err != nil {
+		return api.Deps{}, err
+	}
+	consentService := consent.NewService(cfg.App.Consent)
+	logConsentDocuments(logger, consentService.Documents())
+
 	var tokenKeySet jwk.Set
 	if len(cfg.App.Authentication.Token.RSAPath) > 0 {
 		if ks, err := jwk.ReadFile(cfg.App.Authentication.Token.RSAPath); err != nil {
@@ -628,6 +637,7 @@ func buildAPIDependencies(
 		ResourceService:                  resourceService,
 		SessionService:                   sessionService,
 		AuthnService:                     authnService,
+		ConsentService:                   consentService,
 		DeleterService:                   cascadeDeleter,
 		MetaSchemaService:                metaschemaService,
 		BootstrapService:                 bootstrapService,
@@ -668,6 +678,26 @@ func buildAPIDependencies(
 	return dependencies, nil
 }
 
+// logConsentDocuments records the document set this deployment resolved at
+// boot. Any single field can be overridden through the environment, and an
+// override cannot alter a consent record that already exists but it can
+// produce wrong new ones, so this log — not the config repository — is what
+// says what a deployment was serving.
+func logConsentDocuments(logger *slog.Logger, documents []consent.Document) {
+	if len(documents) == 0 {
+		logger.Info("consent disabled, no documents required at signup")
+		return
+	}
+	logger.Info("consent enabled", "documents", len(documents))
+	for _, document := range documents {
+		logger.Info("consent document",
+			"id", document.ID,
+			"title", document.Title,
+			"version", document.Version,
+			"url", document.URL)
+	}
+}
+
 // StripeTransport wraps the default http.RoundTripper to add metrics.
 type StripeTransport struct {
 	Base http.RoundTripper

config/sample.config.yaml

@@ -202,6 +202,35 @@ app:
     # this is used to validate the webhook payloads
     encryption_key: "hash-secret-should-be-32-chars--"
 
+  # documents a user has to accept before an account is created.
+  # frontier stores one consent record per signup, copying each document's
+  # version and url into it, and never reads what is behind the url.
+  consent:
+    # false (the default) keeps the behaviour frontier had before consent
+    # existed: ListConsentDocuments returns an empty list and no signup is
+    # gated. true with no documents fails at boot rather than doing nothing.
+    enabled: false
+    # keyed by document id. the key is what the client sends back as
+    # accepted_document_ids, and every document listed here is required at
+    # signup — there is no per-document "required" flag.
+    # version is opaque: it is compared for equality only, so dates, semver or
+    # commit SHAs all work, and it is a version bump, not the url, that makes a
+    # new document. config is read at boot, so changing any of this needs a
+    # restart.
+    documents:
+      terms_of_service:
+        title: "Terms & Conditions"
+        version: "2026-04-01"
+        url: "https://example.org/legal/terms/2026-04-01"
+      privacy_policy:
+        title: "Privacy Policy"
+        version: "2026-04-01"
+        url: "https://example.org/legal/privacy/2026-04-01"
+      eula:
+        title: "End User License Agreement"
+        version: "2026-02-14"
+        url: "https://example.org/legal/eula/2026-02-14"
+
   # metaschema cache configuration
   metaschema:
     # how often each server reloads the metaschema cache from the database, so a

core/consent/config.go

@@ -0,0 +1,89 @@
+package consent
+
+import (
+	"fmt"
+	"net/url"
+	"sort"
+)
+
+// Config lists the documents a deployment asks people to accept before an
+// account is created. It sits at app.consent, beside app.authentication and
+// app.pat.
+//
+// Documents is keyed by document id rather than being a list: it matches
+// authenticate.Config keying oidc_config by strategy name, the key enforces
+// unique ids, and a single field stays env-overridable.
+//
+// Every document in the map is required at signup, so there is no per-document
+// required flag. An optional document would need withdrawal, which is out of
+// scope.
+type Config struct {
+	// Enabled switches the whole feature. Absent or false, frontier behaves as
+	// it did before consent existed.
+	Enabled bool `yaml:"enabled" mapstructure:"enabled" default:"false"`
+
+	// Documents is keyed by document id.
+	Documents map[string]DocumentConfig `yaml:"documents" mapstructure:"documents"`
+}
+
+type DocumentConfig struct {
+	Title string `yaml:"title" mapstructure:"title"`
+	// Version is opaque to frontier. It is copied into the consent record and
+	// compared for equality, never parsed.
+	Version string `yaml:"version" mapstructure:"version"`
+	// URL points at the document. Frontier never reads what is behind it.
+	URL string `yaml:"url" mapstructure:"url"`
+}
+
+// Validate reports whether the block can be served. It runs at boot, so bad
+// config stops the server rather than surfacing on a signup.
+//
+// A disabled block is not checked at all: nothing reads it, so a half-written
+// documents map on a deployment that has not turned consent on yet is not an
+// error. Turning it on is what makes it one.
+func (c Config) Validate() error {
+	if !c.Enabled {
+		return nil
+	}
+
+	// enabled with no documents fails here rather than silently disabling
+	// itself, which would look identical to a working deployment while
+	// asking nobody to accept anything.
+	if len(c.Documents) == 0 {
+		return fmt.Errorf("app.consent is enabled but configures no documents")
+	}
+
+	// map iteration order is random, so sort the ids to keep the error
+	// deterministic across boots.
+	for _, id := range sortedIDs(c.Documents) {
+		doc := c.Documents[id]
+		if id == "" {
+			return fmt.Errorf("app.consent has a document with an empty id")
+		}
+		if doc.Version == "" {
+			return fmt.Errorf("app.consent document %q has an empty version", id)
+		}
+		if doc.URL == "" {
+			return fmt.Errorf("app.consent document %q has an empty url", id)
+		}
+		parsed, err := url.Parse(doc.URL)
+		if err != nil {
+			return fmt.Errorf("app.consent document %q has an unparseable url %q: %w", id, doc.URL, err)
+		}
+		// url.Parse accepts a bare path, and a document the client cannot link
+		// to is as useless as one that does not parse at all.
+		if !parsed.IsAbs() || parsed.Host == "" {
+			return fmt.Errorf("app.consent document %q needs an absolute url with a host, got %q", id, doc.URL)
+		}
+	}
+	return nil
+}
+
+func sortedIDs(documents map[string]DocumentConfig) []string {
+	ids := make([]string, 0, len(documents))
+	for id := range documents {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	return ids
+}

core/consent/config_test.go

@@ -0,0 +1,145 @@
+package consent_test
+
+import (
+	"testing"
+
+	"github.com/raystack/frontier/core/consent"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConfig_Validate(t *testing.T) {
+	t.Run("accepts a fully configured block", func(t *testing.T) {
+		require.NoError(t, enabledConfig().Validate())
+	})
+
+	t.Run("accepts a disabled block", func(t *testing.T) {
+		require.NoError(t, consent.Config{}.Validate())
+	})
+
+	t.Run("does not check a disabled block", func(t *testing.T) {
+		// a half-written documents map on a deployment that has not turned
+		// consent on yet is not an error; turning it on is what makes it one
+		config := consent.Config{
+			Documents: map[string]consent.DocumentConfig{
+				"terms_of_service": {},
+			},
+		}
+
+		require.NoError(t, config.Validate())
+
+		config.Enabled = true
+		require.Error(t, config.Validate())
+	})
+
+	t.Run("rejects enabled with no documents", func(t *testing.T) {
+		// silently disabling itself would look identical to a working
+		// deployment while asking nobody to accept anything
+		err := consent.Config{Enabled: true}.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "no documents")
+	})
+
+	t.Run("rejects an empty id", func(t *testing.T) {
+		config := consent.Config{
+			Enabled: true,
+			Documents: map[string]consent.DocumentConfig{
+				"": {Title: "Terms", Version: "1", URL: "https://example.org/terms"},
+			},
+		}
+
+		err := config.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "empty id")
+	})
+
+	t.Run("rejects an empty version", func(t *testing.T) {
+		config := enabledConfig()
+		config.Documents["terms_of_service"] = consent.DocumentConfig{
+			Title: "Terms & Conditions",
+			URL:   "https://example.org/legal/terms",
+		}
+
+		err := config.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "terms_of_service")
+		assert.Contains(t, err.Error(), "empty version")
+	})
+
+	t.Run("rejects an empty url", func(t *testing.T) {
+		config := enabledConfig()
+		config.Documents["privacy_policy"] = consent.DocumentConfig{
+			Title:   "Privacy Policy",
+			Version: "2026-04-01",
+		}
+
+		err := config.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "privacy_policy")
+		assert.Contains(t, err.Error(), "empty url")
+	})
+
+	t.Run("rejects a url that does not parse", func(t *testing.T) {
+		config := enabledConfig()
+		config.Documents["eula"] = consent.DocumentConfig{
+			Title:   "End User License Agreement",
+			Version: "2026-02-14",
+			URL:     "://example.org/legal/eula",
+		}
+
+		err := config.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "eula")
+	})
+
+	t.Run("rejects a url the client cannot link to", func(t *testing.T) {
+		// url.Parse accepts a bare path, and a document nobody can open is as
+		// useless as one that does not parse at all
+		config := enabledConfig()
+		config.Documents["eula"] = consent.DocumentConfig{
+			Title:   "End User License Agreement",
+			Version: "2026-02-14",
+			URL:     "example.org/legal/eula",
+		}
+
+		err := config.Validate()
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "absolute url")
+	})
+
+	t.Run("does not require a title", func(t *testing.T) {
+		// the RFC requires ids, versions and URLs to be non-empty, and stops
+		// there; an untitled document renders badly but serves correctly
+		config := enabledConfig()
+		config.Documents["eula"] = consent.DocumentConfig{
+			Version: "2026-02-14",
+			URL:     "https://example.org/legal/eula",
+		}
+
+		require.NoError(t, config.Validate())
+	})
+
+	t.Run("names the same document on every run", func(t *testing.T) {
+		// map iteration is randomised, so a validator that walks it unsorted
+		// reports a different document each boot
+		config := consent.Config{
+			Enabled: true,
+			Documents: map[string]consent.DocumentConfig{
+				"aaa_broken": {Version: "1"},
+				"zzz_broken": {Version: "1"},
+			},
+		}
+
+		for i := 0; i < 20; i++ {
+			err := config.Validate()
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), "aaa_broken")
+		}
+	})
+}

core/consent/consent.go

@@ -0,0 +1,12 @@
+package consent
+
+// Document is one document a user has to accept before an account is created,
+// as config holds it. Frontier never reads what is behind URL, and Version is
+// opaque: it is compared for equality only, so dates, semver or commit SHAs
+// all work.
+type Document struct {
+	ID      string
+	Title   string
+	Version string
+	URL     string
+}

core/consent/errors.go

@@ -0,0 +1,14 @@
+package consent
+
+import "errors"
+
+var (
+	// ErrUnknownDocuments is returned when the caller accepts an id this
+	// deployment does not configure. The ids the client rendered can differ
+	// from config, and this is what exposes the mismatch.
+	ErrUnknownDocuments = errors.New("unknown consent document ids")
+
+	// ErrMissingDocuments is returned when the accepted ids do not cover every
+	// configured document. Every document in config is required at signup.
+	ErrMissingDocuments = errors.New("missing consent document ids")
+)