Files
sam 4707427759 feat: trust configured proxies for webhook intake
- add trusted proxy settings, migration, API, and UI
- derive client addresses from X-Forwarded-For behind trusted hops
- enforce delivery policy for listener batches and record denials
2026-11-22 22:29:36 +11:00

510 lines
18 KiB
Go

package governance
import (
"context"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"net/mail"
"net/url"
"strings"
"time"
"github.com/google/uuid"
)
type (
IdentityID string
Kind string
Lifecycle string
CommandType string
)
const (
SystemID IdentityID = "00000000-0000-5000-8000-000000000001"
KindSystem Kind = "system"
KindBot Kind = "bot"
KindServiceAccount Kind = "service_account"
KindUser Kind = "user"
LifecycleActive Lifecycle = "active"
LifecycleSuspended Lifecycle = "suspended"
LifecycleRetired Lifecycle = "retired"
CommandRename CommandType = "rename"
CommandSuspend CommandType = "suspend"
CommandReactivate CommandType = "reactivate"
CommandRetire CommandType = "retire"
)
var (
ErrInvalidIdentity = errors.New("invalid identity")
ErrIdentityNotFound = errors.New("identity not found")
ErrIdentityConflict = errors.New("identity version conflict")
ErrSystemImmutable = errors.New("system identity is immutable")
ErrIllegalTransition = errors.New("illegal identity lifecycle transition")
ErrNoCredential = errors.New("no credential presented")
ErrCredentialRejected = errors.New("credential rejected")
ErrProviderUnavailable = errors.New("identity provider unavailable")
ErrSubjectUnbound = errors.New("credential subject is not bound to an identity")
ErrIdentityInactive = errors.New("identity may not act")
ErrSetupComplete = errors.New("administrator has already been set up")
)
// Identity is a persistent actor (user, bot, service account, or system) and
// its lifecycle state.
type Identity struct {
ID IdentityID `json:"id"`
Kind Kind `json:"kind"`
DisplayName string `json:"display_name"`
Lifecycle Lifecycle `json:"lifecycle"`
Version int64 `json:"version"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// IdentityCommand is a lifecycle or rename mutation applied to an Identity.
type IdentityCommand struct {
Type CommandType
DisplayName string
}
// IdentityEvent records one applied IdentityCommand.
type IdentityEvent struct {
IdentityID IdentityID
Type CommandType
From Lifecycle
To Lifecycle
DisplayName string
At time.Time
}
// IdentityAudit attributes an identity change to an actor and source.
type IdentityAudit struct {
ActorID IdentityID
Source, RequestID string
At time.Time
}
// IdentityRepository persists identities and their lifecycle events.
type IdentityRepository interface {
List(context.Context) ([]Identity, error)
Get(context.Context, IdentityID) (Identity, error)
ResolveLegacyName(context.Context, string) (Identity, error)
Create(context.Context, Identity, IdentityAudit) (Identity, error)
Apply(context.Context, IdentityID, int64, IdentityCommand, IdentityAudit) (Identity, error)
}
// SystemIdentity returns the singleton built-in system identity.
func SystemIdentity() Identity {
return Identity{ID: SystemID, Kind: KindSystem, DisplayName: "System", Lifecycle: LifecycleActive, Version: 1}
}
// StableID derives a version 5 UUID from legacyName using SHA-256 so fixed
// identities resolve deterministically across restarts.
func StableID(legacyName string) IdentityID {
sum := sha256.Sum256([]byte("archie.identity.v1\x00" + strings.ToLower(strings.TrimSpace(legacyName))))
var id uuid.UUID
copy(id[:], sum[:16])
id[6] = id[6]&0x0f | 0x50
id[8] = id[8]&0x3f | 0x80
return IdentityID(id.String())
}
// OperatorID is the person identity used by an instance operator.
func OperatorID() IdentityID { return StableID("operator") }
// AgentID is the bot identity workflows run as.
func AgentID() IdentityID { return StableID("agent") }
// NewIdentity validates and constructs an active Identity at version 1.
func NewIdentity(id IdentityID, kind Kind, displayName string) (Identity, error) {
value := Identity{
ID: id,
Kind: kind,
DisplayName: strings.TrimSpace(displayName),
Lifecycle: LifecycleActive,
Version: 1,
}
if err := value.Validate(); err != nil {
return Identity{}, err
}
return value, nil
}
// FromLegacyName builds the bot identity for a configured name.
func FromLegacyName(legacyName string) (Identity, error) {
return NewIdentity(StableID(legacyName), KindBot, legacyName)
}
// Agent reports whether k acts on its own rather than for a person: an agent
// serves one organisation.
func (k Kind) Agent() bool { return k == KindBot || k == KindServiceAccount }
// ValidDisplayName reports whether name is non-empty after trimming.
func ValidDisplayName(name string) bool { return strings.TrimSpace(name) != "" }
// Validate checks that i has a valid id, display name, kind, and lifecycle.
func (i Identity) Validate() error {
if i.ID == "" || !ValidDisplayName(i.DisplayName) {
return fmt.Errorf("%w: ID and display name are required", ErrInvalidIdentity)
}
switch i.Kind {
case KindSystem, KindBot, KindServiceAccount, KindUser:
default:
return fmt.Errorf("%w: unknown kind %q", ErrInvalidIdentity, i.Kind)
}
switch i.Lifecycle {
case LifecycleActive, LifecycleSuspended, LifecycleRetired:
default:
return fmt.Errorf("%w: unknown lifecycle %q", ErrInvalidIdentity, i.Lifecycle)
}
if i.Kind == KindSystem && (i.ID != SystemID || i.Lifecycle != LifecycleActive) {
return ErrSystemImmutable
}
if i.ID == SystemID && i.Kind != KindSystem {
return ErrSystemImmutable
}
return nil
}
// CanAct reports whether an identity may perform actions.
func (i Identity) CanAct() bool { return i.Lifecycle == LifecycleActive }
// ApplyIdentity applies command to i and returns the updated identity and event.
func ApplyIdentity(i Identity, command IdentityCommand) (Identity, IdentityEvent, error) {
if i.ID == SystemID || i.Kind == KindSystem {
return Identity{}, IdentityEvent{}, ErrSystemImmutable
}
event := IdentityEvent{IdentityID: i.ID, Type: command.Type, From: i.Lifecycle, To: i.Lifecycle, At: time.Now().UTC()}
switch command.Type {
case CommandRename:
name := strings.TrimSpace(command.DisplayName)
if name == "" {
return Identity{}, IdentityEvent{}, fmt.Errorf("%w: display name is required", ErrInvalidIdentity)
}
i.DisplayName, event.DisplayName = name, name
case CommandSuspend:
if i.Lifecycle != LifecycleActive {
return Identity{}, IdentityEvent{}, ErrIllegalTransition
}
i.Lifecycle, event.To = LifecycleSuspended, LifecycleSuspended
case CommandReactivate:
if i.Lifecycle != LifecycleSuspended {
return Identity{}, IdentityEvent{}, ErrIllegalTransition
}
i.Lifecycle, event.To = LifecycleActive, LifecycleActive
case CommandRetire:
if i.Lifecycle != LifecycleActive && i.Lifecycle != LifecycleSuspended {
return Identity{}, IdentityEvent{}, ErrIllegalTransition
}
i.Lifecycle, event.To = LifecycleRetired, LifecycleRetired
default:
return Identity{}, IdentityEvent{}, fmt.Errorf("%w: unknown command %q", ErrInvalidIdentity, command.Type)
}
i.Version++
return i, event, nil
}
// Subject is what an identity provider asserts about a caller. Issuer is part
// of the key because two providers can assert the same subject string for
// different people.
type Subject struct {
Issuer string `json:"issuer"`
Subject string `json:"subject"`
}
// EmailSubject is the placeholder binding of a person added by email until
// their first sign-in claims it.
func EmailSubject(issuer, email string) Subject {
return Subject{Issuer: issuer, Subject: "email:" + strings.ToLower(strings.TrimSpace(email))}
}
// Validate checks that s names both an issuer and a subject.
func (s Subject) Validate() error {
if strings.TrimSpace(s.Issuer) == "" || strings.TrimSpace(s.Subject) == "" {
return fmt.Errorf("%w: issuer and subject are required", ErrInvalidIdentity)
}
return nil
}
// Credential is what a provider-issued token proved.
type Credential struct {
Subject Subject
Email string
Scopes []string
Expires time.Time
}
// Verifier checks a presented bearer token against an identity provider.
type Verifier interface {
Verify(ctx context.Context, rawToken string) (Credential, error)
}
// SubjectResolver resolves a provider subject to its bound identity.
type SubjectResolver interface {
ResolveSubject(context.Context, Subject) (Identity, error)
ClaimSubject(ctx context.Context, placeholder, subject Subject) (Identity, error)
}
// SubjectBinding resolves and binds verified provider subjects to identities.
type SubjectBinding interface {
SubjectResolver
BindSubject(context.Context, IdentityID, Subject, IdentityAudit) error
}
// LoginFlow is the browser authorization flow an identity provider requires.
type LoginFlow interface {
AuthCodeURL(ctx context.Context, state string) (string, string, error)
Exchange(ctx context.Context, code, codeVerifier string) (ProviderSession, error)
}
// ProviderSession is what a completed provider authorization flow yields.
type ProviderSession struct {
Credential Credential
Token string
Expires time.Time
}
// AuthenticateCredential verifies rawToken and resolves it to an active identity.
func AuthenticateCredential(ctx context.Context, subjects SubjectResolver, verifier Verifier, rawToken string) (Identity, Credential, error) {
if strings.TrimSpace(rawToken) == "" {
return Identity{}, Credential{}, ErrNoCredential
}
if verifier == nil {
return Identity{}, Credential{}, fmt.Errorf("%w: no identity provider is configured", ErrCredentialRejected)
}
credential, err := verifier.Verify(ctx, rawToken)
if err != nil {
return Identity{}, Credential{}, fmt.Errorf("%w: %w", ErrCredentialRejected, err)
}
value, err := ResolveCredential(ctx, subjects, credential)
if err != nil {
return Identity{}, Credential{}, err
}
return value, credential, nil
}
// ResolveCredential maps a verified credential to its active identity.
func ResolveCredential(ctx context.Context, subjects SubjectResolver, credential Credential) (Identity, error) {
if err := credential.Subject.Validate(); err != nil {
return Identity{}, fmt.Errorf("%w: %w", ErrCredentialRejected, err)
}
value, err := subjects.ResolveSubject(ctx, credential.Subject)
if errors.Is(err, ErrIdentityNotFound) && credential.Email != "" {
value, err = subjects.ClaimSubject(ctx, EmailSubject(credential.Subject.Issuer, credential.Email), credential.Subject)
}
if err != nil {
if errors.Is(err, ErrIdentityNotFound) {
return Identity{}, fmt.Errorf("%w: %s", ErrSubjectUnbound, credential.Subject.Subject)
}
return Identity{}, err
}
if !value.CanAct() {
return Identity{}, fmt.Errorf("%w: %s is %s", ErrIdentityInactive, value.ID, value.Lifecycle)
}
return value, nil
}
// PersonalTokenIssuer is the subject issuer a personal API token binds under.
// The subject is the token's SHA-256, so the store never holds the token.
const PersonalTokenIssuer = "archie-token"
const (
personalTokenPrefix = "archie_pat_"
lastUsedGranularity = time.Minute
)
// NewPersonalToken returns a fresh personal API token and the subject it binds as.
func NewPersonalToken() (string, Subject, error) {
var secret [32]byte
if _, err := rand.Read(secret[:]); err != nil {
return "", Subject{}, err
}
raw := personalTokenPrefix + hex.EncodeToString(secret[:])
subject, _ := PersonalTokenSubject(raw)
return raw, subject, nil
}
// PersonalTokenSubject returns the subject a presented token binds as, or
// false when the credential is not a personal token.
func PersonalTokenSubject(raw string) (Subject, bool) {
if !strings.HasPrefix(raw, personalTokenPrefix) {
return Subject{}, false
}
sum := sha256.Sum256([]byte(raw))
return Subject{Issuer: PersonalTokenIssuer, Subject: hex.EncodeToString(sum[:])}, true
}
// PersonalToken is one personal API token as its owner sees it.
type PersonalToken struct {
ID string `json:"id"`
Name string `json:"name"`
CreatedAt time.Time `json:"created_at"`
ExpiresAt *time.Time `json:"expires_at"`
LastUsedAt *time.Time `json:"last_used_at"`
}
// PersonalTokenStore persists personal API tokens for an identity.
type PersonalTokenStore interface {
BindPersonalToken(ctx context.Context, id IdentityID, subject Subject, name string, expiresAt *time.Time, audit IdentityAudit) error
SubjectsOf(ctx context.Context, id IdentityID, issuer string) ([]PersonalToken, error)
UnbindSubject(context.Context, IdentityID, Subject, IdentityAudit) error
PersonalTokenOf(context.Context, Subject) (PersonalToken, error)
TouchPersonalToken(context.Context, Subject, time.Time) error
}
// UsePersonalToken admits a presented token, refusing expired tokens and
// recording last use at most once per minute.
func UsePersonalToken(ctx context.Context, store interface {
PersonalTokenOf(context.Context, Subject) (PersonalToken, error)
TouchPersonalToken(context.Context, Subject, time.Time) error
}, subject Subject, now time.Time,
) error {
token, err := store.PersonalTokenOf(ctx, subject)
if err != nil {
return err
}
if token.ExpiresAt != nil && !now.Before(*token.ExpiresAt) {
return ErrIdentityNotFound
}
if token.LastUsedAt == nil || now.Sub(*token.LastUsedAt) >= lastUsedGranularity {
return store.TouchPersonalToken(ctx, subject, now)
}
return nil
}
// PersonalTokens manages personal API tokens for the authenticated principal.
type PersonalTokens interface {
AddPersonalToken(ctx context.Context, subject Subject, name string, expiresAt *time.Time) error
ListPersonalTokens(ctx context.Context) ([]PersonalToken, error)
RevokePersonalToken(ctx context.Context, id string) error
}
// AccountSessionLifetime bounds a password or passkey account session.
const AccountSessionLifetime = 7 * 24 * time.Hour
// AccountRegistration carries the fields needed to register an account or
// bootstrap the instance owner.
type AccountRegistration struct {
PublicURL string `json:"public_url"`
WorkspaceName string `json:"workspace_name"`
OrganisationName string `json:"organisation_name"`
Email string `json:"email"`
DisplayName string `json:"display_name"`
Password string `json:"password"`
Role string `json:"role"`
}
// Validate normalises email and display name and checks their bounds.
func (r *AccountRegistration) Validate() error {
r.Email = strings.ToLower(strings.TrimSpace(r.Email))
address, err := mail.ParseAddress(r.Email)
r.DisplayName = strings.TrimSpace(r.DisplayName)
if err != nil || address.Address != r.Email || len(r.Email) > 254 || r.DisplayName == "" || len(r.DisplayName) > 200 {
return ErrInvalidIdentity
}
return nil
}
// AccountSession is an authenticated user session issued after sign-in.
type AccountSession struct {
Identity Identity
Token string
Expires time.Time
}
// Accounts manages local password accounts and sessions.
type Accounts interface {
AccountSetupRequired(context.Context) (bool, error)
RegisterAccount(context.Context, AccountRegistration, bool) (Identity, error)
SignInAccount(ctx context.Context, email, password string) (AccountSession, error)
ResolveAccountSession(context.Context, string) (Identity, error)
SignOutAccount(context.Context, string) error
ChangeAccountPassword(ctx context.Context, current, next string) error
}
// AccountSecurity guards authenticator changes with recent authentication and
// single-use recovery codes.
type AccountSecurity interface {
OpenAccountSession(context.Context, time.Time) (AccountSession, error)
RequireFreshAccountSession(context.Context, string) error
CreateAccountRecovery(context.Context) (string, error)
RecoverAccount(ctx context.Context, email, code, password string) error
}
// AuthenticationSettings stores the instance's public origin, its trusted
// reverse proxies and the OIDC parameters.
type AuthenticationSettings struct {
PublicURL string `json:"public_url"`
OIDCIssuer string `json:"oidc_issuer"`
OIDCAudience string `json:"oidc_audience"`
OIDCClientID string `json:"oidc_client_id"`
// TrustedProxies are the addresses and CIDR ranges of reverse proxies whose
// X-Forwarded-For header webhook intake uses as the client address.
TrustedProxies []string `json:"trusted_proxies"`
}
// Validate checks that PublicURL is a valid origin, the trusted proxies are
// addresses or ranges, and OIDC fields are paired.
func (s AuthenticationSettings) Validate() error {
if !validInstanceOrigin(s.PublicURL) {
return ErrInvalidIdentity
}
if _, err := normalizeProxies(s.TrustedProxies); err != nil {
return err
}
if s.OIDCIssuer == "" {
if s.OIDCClientID != "" || s.OIDCAudience != "" {
return ErrInvalidIdentity
}
return nil
}
if !validProviderIssuer(s.OIDCIssuer) || strings.TrimSpace(s.OIDCClientID) == "" || strings.TrimSpace(s.OIDCAudience) == "" {
return ErrInvalidIdentity
}
return nil
}
func validInstanceOrigin(raw string) bool {
u, err := url.Parse(raw)
if err != nil || u.Hostname() == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {
return false
}
return (u.Path == "" || u.Path == "/") && (u.Scheme == "https" || u.Scheme == "http")
}
func validProviderIssuer(raw string) bool {
u, err := url.Parse(raw)
if err != nil || u.Hostname() == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {
return false
}
return u.Scheme == "https" || (u.Scheme == "http" && u.Hostname() == "localhost")
}
// AuthenticationSettingsStore reads and saves instance authentication settings.
type AuthenticationSettingsStore interface {
AuthenticationSettings(context.Context) (AuthenticationSettings, error)
SaveAuthenticationSettings(context.Context, AuthenticationSettings) error
}
// Passkey is a registered WebAuthn credential.
type Passkey struct {
ID string `json:"id"`
Name string `json:"name"`
}
// PasskeyCeremony is an in-flight WebAuthn registration or login ceremony.
type PasskeyCeremony struct {
Token string
Options []byte
}
// Passkeys manages WebAuthn passkey registration and sign-in.
type Passkeys interface {
BeginPasskey(context.Context, bool) (PasskeyCeremony, error)
FinishPasskey(ctx context.Context, token string, response []byte, registration bool, name string) (AccountSession, error)
ListPasskeys(context.Context) ([]Passkey, error)
DeletePasskey(context.Context, string) error
}