relyingparty

type AccessChange struct {
	// PrincipalID is the SystemAuth principal, the token's sub.
	PrincipalID string
	// OrganizationID scopes the change to one organization; empty means
	// every organization.
	OrganizationID string
	// ChangedAt is when SystemAuth recorded the change, on its clock.
	ChangedAt time.Time
	// Reason says why access changed, such as membership_removed or
	// deactivated. It is opaque here: SystemAuth's registry of reasons grows
	// without a migration, so a value this package does not know is not an
	// error.
	Reason string
}

type AccessChangePoller struct {
	// contains filtered or unexported fields
}

type AccessChangeSink interface {
	Record(AccessChange)
}

type AccessChangeSource interface {
	AccessChangesSince(ctx context.Context, since time.Time) ([]AccessChange, error)
}

type AccessTokenClaims struct {
	gojwt.RegisteredClaims

	ClientID string   `json:"client_id,omitempty"`
	Scopes   []string `json:"scp,omitempty"`

	// Confirmation is the cnf claim (RFC 7800); its JKT binds the token to
	// a DPoP key (RFC 9449).
	Confirmation *TokenConfirmation `json:"cnf,omitempty"`

	// Raw holds every claim of the verified token.
	Raw map[string]any `json:"-"`
}

type AccessTokenVerifier interface {
	VerifyAccessToken(ctx context.Context, raw string) (*AccessTokenClaims, error)
}

type AuthError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type AuthMethod string

type AuthenticatedPrincipal struct {
	// ID is the app-local principal ID (for a client-credentials token
	// without a local principal, the OAuth client ID).
	ID string
	// Type is the principal type: human, service, ... or "client" for a
	// client-credentials token.
	Type string
	// Subject is the SystemAuth subject (sf_principal_id), when known.
	Subject string
	// Method is how the request authenticated.
	Method AuthMethod
	// Scopes are the access token's scopes (empty for sessions, which
	// carry the principal's full access).
	Scopes []string
	// Memberships are the principal's organization memberships.
	Memberships []Membership
}

type BFF struct {
	// contains filtered or unexported fields
}

type BFFConfig struct {
	// Client is the SystemAuth relying-party client (required).
	Client *Client

	// Principals resolves SystemAuth identities to app-local principals
	// (required).
	Principals PrincipalStore

	// Memberships supplies organization memberships (with the session's
	// SystemAuth claims). Default: ClaimsMemberships.
	Memberships MembershipSource

	// Apps, when set, lists the deployment's application catalog in the
	// session response ("apps"), for the product switcher. Use
	// appcatalog.Static when the catalog is in the process, or
	// appcatalog.Remote to read what SystemAuth publishes. A shell shows the
	// entries the person holds a role in for the current organization.
	Apps appcatalog.Source

	// Revocation, when set, makes the BFF refresh a session's tokens and
	// claims from SystemAuth when a change to the principal's access was
	// recorded after the claims were obtained (ADR-010). The session is not
	// ended: the person stays signed in with reduced claims. If SystemAuth
	// refuses the refresh (deactivation, revocation) the session ends.
	Revocation *RevocationCache

	// Sessions stores browser sessions. Default: in-memory (single
	// instance); use pgstore.NewSessionStore in production.
	Sessions SessionStore

	// LoginStates stores in-flight logins. Default: in-memory (single
	// instance); use pgstore.NewLoginStateStore in production.
	LoginStates LoginStateStore

	// BasePath is where the handler is mounted. Default: "/bff".
	BasePath string

	// SessionLifetime is the absolute session lifetime. Default: 12h.
	SessionLifetime time.Duration

	// LoginErrorPath, when set, is the app's sign-in page. A browser whose
	// sign-in fails at GET {BasePath}/auth/login or the callback is then
	// redirected there with ?error=<CODE> (LOGIN_FAILED, INVALID_STATE,
	// EMAIL_NOT_VERIFIED, ACCOUNT_CONFLICT, ACCOUNT_DISABLED,
	// INVALID_RETURN_TO, UNKNOWN_PROVIDER or INTERNAL_ERROR) instead of
	// shown a JSON error. A request that asks for JSON (Accept:
	// application/json without text/html) still gets JSON. It must pass the
	// same checks as a return_to, typically a path such as "/login". Empty
	// keeps the JSON errors.
	LoginErrorPath string

	// DefaultReturnTo is where users land after login when no return_to is
	// given. Default: "/".
	DefaultReturnTo string

	// AllowedOrigins are absolute origins (scheme://host[:port]) that may be
	// post-login return_to targets and may call the BFF's state-changing
	// endpoints. The origin of the Client's RedirectURL is always allowed.
	AllowedOrigins []string

	// SignOutURL is SystemAuth's sign-out page, where a browser that signed
	// out of the app goes next to end its SystemAuth login session, so the
	// next sign-in asks who it is instead of resuming that session.
	// Signing out there also ends the person's sessions in the other apps,
	// through the back-channel logout. Default: the issuer's /logout. "-"
	// leaves it out, for an issuer without one.
	SignOutURL string

	// InsecureCookies drops the __Host- prefix and the Secure flag for
	// local development over plain HTTP. Never enable in production;
	// NewBFF logs a warning when it is set.
	InsecureCookies bool

	// Logger receives operational errors. Default: slog.Default().
	Logger *slog.Logger
}

type BackchannelOption func(*backchannelHandler)

type BearerConfig struct {
	// Tokens verifies SystemAuth JWT access tokens. Nil disables them.
	Tokens AccessTokenVerifier

	// Principals resolves token subjects to app-local principals
	// (required).
	Principals PrincipalStore

	// Memberships supplies organization memberships. Default:
	// ClaimsMemberships, which reads a JWT access token's claims.
	Memberships MembershipSource

	// Sessions, when set, also accepts a BFF cookie session for requests
	// without credentials, so one middleware protects an API used by both
	// the browser and programmatic clients.
	Sessions *BFF

	// AllowClientTokens accepts client-credentials access tokens (subject
	// equal to the client ID, no local principal) as a "client" principal.
	AllowClientTokens bool

	// ServicePrincipals accepts SystemAuth service accounts: a verified
	// access token whose subject has no local principal and whose
	// principal_type claim is "service" creates one with
	// PrincipalStore.CreatePrincipal (VerifiedIdentity.Service), since a
	// service account never signs in. The principal store must support
	// service identities. Without it such a token is refused as an unknown
	// principal.
	ServicePrincipals bool

	// Revocation, when set, refuses a JWT access token issued before a
	// recorded change to its principal's access (ADR-010). The refusal is
	// a 401 invalid_token "token expired", which makes the client refresh
	// and obtain claims that reflect the change.
	Revocation *RevocationCache

	// Organization names the organization a request addresses, so that a
	// change to the principal's access in another organization does not
	// refuse it. Without it every change to the principal applies.
	Organization func(r *http.Request) string

	// DPoP verifies the proofs that come with DPoP-bound access tokens (a
	// cnf.jkt claim), presented with the "DPoP" authorization scheme (RFC
	// 9449). SystemAuth binds every token it issues unless the client is a
	// legacy bearer exception, so DPoP is required whenever Tokens is set,
	// unless AllowBearerTokens is. A DPoP-bound token presented with the
	// Bearer scheme is always refused, so a stolen bound token does not
	// work as a bearer token.
	DPoP *DPoPConfig

	// AllowBearerTokens also accepts unbound JWT access tokens with the
	// Bearer scheme, as SystemAuth issues to clients registered with its
	// allow_bearer_tokens exception. It is an explicit opt-in: by default
	// an access token without cnf.jkt is refused, since whoever holds a
	// bearer token can use it.
	AllowBearerTokens bool

	// Logger receives storage errors. Default: slog.Default().
	Logger *slog.Logger
}

type CacheOption func(*RevocationCache)

type Client struct {
	// contains filtered or unexported fields
}

type Config struct {
	// Issuer is the SystemAuth issuer URL (required).
	Issuer string

	// ClientID is this application's OAuth client ID at SystemAuth
	// (required).
	ClientID string

	// ClientSecret is the client secret for confidential clients. Leave it
	// empty for public clients (PKCE is always used).
	ClientSecret string

	// RedirectURL is the absolute callback URL registered with SystemAuth,
	// e.g. https://app.example.com/bff/auth/callback (required).
	RedirectURL string

	// Scopes requested at login. Default: DefaultScopes.
	Scopes []string

	// AccessTokenAudience, when set, is required in the "aud" of JWT access
	// tokens accepted by VerifyAccessToken. Set it when this application is
	// an API that clients request tokens for with an audience parameter;
	// tokens from any client carrying the audience are then accepted.
	AccessTokenAudience string

	// AcceptedClientIDs lists the OAuth clients whose JWT access tokens
	// VerifyAccessToken accepts, by the token's client_id claim. Default:
	// ClientID alone when AccessTokenAudience is empty, and any client when
	// it is set. List other clients here, for example service clients that
	// call this API with client-credentials tokens; include ClientID to keep
	// accepting this application's own tokens.
	AcceptedClientIDs []string

	// HTTPClient is used for all calls to SystemAuth. Default:
	// http.DefaultClient.
	HTTPClient *http.Client

	// DPoPKey is the key the Client proves possession of to SystemAuth
	// (RFC 9449): every token request carries a proof by it, so the tokens
	// SystemAuth issues are bound to it, and refreshing them needs it.
	// Default: a key generated when the Client is created, which suits one
	// instance. When several instances share sessions, give them all the
	// same key (dpop.DeserializeKeyPairJSON, from a secret), or a refresh
	// on another instance than the one that signed in is refused.
	DPoPKey *dpop.KeyPair
}

type DPoPConfig struct {
	// Verification sets the proof age window and clock skew. Access token
	// binding (the ath claim) is always required. Zero values use
	// dpop.DefaultVerificationConfig.
	Verification dpop.VerificationConfig

	// ReplayCache rejects a proof whose jti has been used before
	// (required).
	ReplayCache DPoPReplayCache

	// BaseURL is the scheme and host clients use to reach this API, such as
	// "https://api.example.com"; a proof's htu must equal BaseURL plus the
	// request path. If empty, the scheme comes from the connection and the
	// host from the Host header. Forwarded headers are never trusted, so
	// set BaseURL behind a proxy that terminates TLS.
	BaseURL string
}

type DPoPReplayCache interface {
	// Use records key until expiresAt and reports whether it was already
	// recorded (a replay).
	Use(ctx context.Context, key string, expiresAt time.Time) (replayed bool, err error)
}

type IDTokenClaims struct {
	gojwt.RegisteredClaims

	Nonce           string `json:"nonce,omitempty"`
	AuthorizedParty string `json:"azp,omitempty"`
	AuthTime        int64  `json:"auth_time,omitempty"`
	Email           string `json:"email,omitempty"`
	EmailVerified   bool   `json:"email_verified,omitempty"`
	// EmailVerifiedAt is SystemForge's email_verified_at extension: when
	// the email was verified, as a NumericDate (seconds since the epoch,
	// which may arrive in floating-point form); nil when absent.
	EmailVerifiedAt *gojwt.NumericDate `json:"email_verified_at,omitempty"`
	Name            string             `json:"name,omitempty"`
	Picture         string             `json:"picture,omitempty"`
	SID             string             `json:"sid,omitempty"`

	// Raw holds every claim of the verified token.
	Raw map[string]any `json:"-"`
}

type KeySet struct {
	// contains filtered or unexported fields
}

type LoginState struct {
	// Nonce is the OIDC nonce sent in the authorization request.
	Nonce string
	// Verifier is the PKCE code verifier.
	Verifier string
	// ReturnTo is the validated post-login target.
	ReturnTo string
	// ExpiresAt bounds how long the login may take.
	ExpiresAt time.Time
}

type LoginStateStore interface {
	// Put stores state.
	Put(ctx context.Context, state string, data LoginState) error
	// Take returns and removes the state, or ErrInvalidState when it is
	// unknown, already used or expired.
	Take(ctx context.Context, state string) (LoginState, error)
}

type LogoutTokenClaims struct {
	gojwt.RegisteredClaims

	SID    string                     `json:"sid,omitempty"`
	Nonce  string                     `json:"nonce,omitempty"`
	Events map[string]json.RawMessage `json:"events"`
}

type LogoutTokenVerifier interface {
	VerifyLogoutToken(ctx context.Context, raw string) (*LogoutTokenClaims, error)
}

type Membership struct {
	ID               string
	OrganizationID   string
	OrganizationName string
	OrganizationSlug string
	// OrganizationType is personal, team or enterprise, when known.
	OrganizationType string
	// Role is the organization role: owner, admin, member or collaborator.
	Role     string
	JoinedAt time.Time
	// Applications maps an application identifier to the principal's role
	// there. An application absent from the map is one the principal may
	// not open. Sources that do not know application roles leave it nil.
	Applications map[string]string
}

type MembershipLister interface {
	// Memberships lists the principal's organization memberships.
	Memberships(ctx context.Context, principalID string) ([]Membership, error)
}

type MembershipQuery struct {
	// Principal is the resolved app-local principal.
	Principal *Principal

	// Subject is the SystemAuth subject (sf_principal_id), when known.
	Subject string

	// Claims are the verified SystemAuth claims seen for this request: the
	// ID token and UserInfo claims stored with a BFF session, or the claims
	// of a JWT access token. Nil for API keys.
	Claims map[string]any

	// AccessToken returns a valid SystemAuth access token for the request
	// (the presented JWT, or a session's token, refreshed when it is about
	// to expire). It is nil when the request has none, as with an API key.
	// It is lazy so that sources reading claims never trigger a refresh.
	AccessToken func(ctx context.Context) (string, error)
}

type MembershipSource interface {
	Memberships(ctx context.Context, q MembershipQuery) ([]Membership, error)
}

type MembershipSourceFunc func(ctx context.Context, q MembershipQuery) ([]Membership, error)

type MemoryLoginStateStore struct {
	// contains filtered or unexported fields
}

type MemoryPrincipalStore struct {
	// contains filtered or unexported fields
}

type MemorySessionStore struct {
	// contains filtered or unexported fields
}

type Metadata struct {
	Issuer                string `json:"issuer"`
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	TokenEndpoint         string `json:"token_endpoint"`
	UserinfoEndpoint      string `json:"userinfo_endpoint,omitempty"`
	JWKSURI               string `json:"jwks_uri"`
	RevocationEndpoint    string `json:"revocation_endpoint,omitempty"`
}

type PollerOption func(*AccessChangePoller)

type Principal struct {
	// ID is the app-local principal ID.
	ID string
	// Type is the principal type (human, service, ...). Default "human".
	Type string
	// SFPrincipalID is the linked SystemAuth principal ID (the OIDC sub);
	// empty when not linked yet.
	SFPrincipalID string
	// Email is the principal's email.
	Email string
	// EmailVerified reports whether the app considers Email verified.
	EmailVerified bool
	// Name is the display name.
	Name string
	// AvatarURL is the avatar URL.
	AvatarURL string
	// Active reports whether the principal may sign in.
	Active bool
	// Managed reports a managed principal, which has no email.
	Managed bool
	// CreatedAt and UpdatedAt are record timestamps.
	CreatedAt time.Time
	UpdatedAt time.Time
}

type PrincipalStore interface {
	// FindBySubject returns the principal linked to the SystemAuth subject
	// (sf_principal_id), or ErrPrincipalNotFound.
	FindBySubject(ctx context.Context, subject string) (*Principal, error)

	// FindByEmail returns the principal with this email (case-insensitive),
	// or ErrPrincipalNotFound.
	FindByEmail(ctx context.Context, email string) (*Principal, error)

	// LinkSubject sets sf_principal_id on an existing principal. It returns
	// ErrSubjectLinked if the subject is already linked to a principal.
	LinkSubject(ctx context.Context, principalID, subject string) error

	// CreatePrincipal creates an active human principal linked to
	// identity.Subject, with a verified email or, when identity.Managed,
	// with or without an email. When identity.Service is set it creates a
	// principal of type service without an email instead; a store that
	// cannot returns an error, and an application must not enable
	// BearerConfig.ServicePrincipals with it. It returns ErrSubjectLinked if
	// the subject was linked concurrently and ErrEmailConflict if the email
	// is taken.
	CreatePrincipal(ctx context.Context, identity VerifiedIdentity) (*Principal, error)

	// RecordLogin refreshes profile fields from identity after a sign-in.
	RecordLogin(ctx context.Context, principalID string, identity VerifiedIdentity, at time.Time) error

	// GetPrincipal returns a principal by app-local ID, or
	// ErrPrincipalNotFound.
	GetPrincipal(ctx context.Context, id string) (*Principal, error)
}

type RequestAuthenticator struct {
	// contains filtered or unexported fields
}

type RevocationCache struct {
	// contains filtered or unexported fields
}

type Session struct {
	// PrincipalID is the app-local principal.
	PrincipalID string
	// Subject is the SystemAuth principal ID (sf_principal_id).
	Subject string
	// SID is the SystemAuth session ID ("sid" claim of the ID token), when
	// SystemAuth issues one. Back-channel logout deletes sessions by SID or
	// Subject.
	SID string
	// Claims are the verified ID token claims, overlaid with the UserInfo
	// claims, captured at sign-in.
	// A MembershipSource can read SystemAuth-issued memberships from them.
	Claims map[string]any
	// ClaimsIssuedAt is when Claims were obtained from SystemAuth, or, after
	// a refresh forced by an access change, the earliest time a
	// RevocationCache accepts (ADR-010). Zero for a session created before
	// the field existed: CreatedAt stands in.
	ClaimsIssuedAt time.Time
	// AccessToken, RefreshToken and IDToken are the SystemAuth tokens.
	AccessToken  string
	RefreshToken string
	IDToken      string
	// AccessTokenExpiresAt is when AccessToken expires.
	AccessTokenExpiresAt time.Time
	// CreatedAt is when the session was established.
	CreatedAt time.Time
	// ExpiresAt is the absolute session expiry.
	ExpiresAt time.Time
}

type SessionStatus struct {
	Authenticated bool       `json:"authenticated"`
	UserID        string     `json:"user_id,omitempty"`
	ExpiresAt     *time.Time `json:"expires_at,omitempty"`
	User          *User      `json:"user,omitempty"`
	// Apps is the deployment's application catalog (BFFConfig.Apps), in
	// order, for a signed-in session.
	Apps []appcatalog.App `json:"apps,omitempty"`
}

type SessionStore interface {
	// Create stores session under token.
	Create(ctx context.Context, token string, session Session) error
	// Get returns the session for token, or ErrSessionNotFound when it is
	// unknown or expired.
	Get(ctx context.Context, token string) (Session, error)
	// Update replaces the session for token (e.g. after a token refresh).
	// It returns ErrSessionNotFound for an unknown token.
	Update(ctx context.Context, token string, session Session) error
	// Delete removes the session. Deleting an unknown token is not an error.
	Delete(ctx context.Context, token string) error
	// DeleteBySubject removes every session of a SystemAuth subject and
	// returns how many were removed (for back-channel logout).
	DeleteBySubject(ctx context.Context, subject string) (int, error)
	// DeleteBySID removes every session established under a SystemAuth
	// session ID and returns how many were removed.
	DeleteBySID(ctx context.Context, sid string) (int, error)
}

type SignOutResponse struct {
	// SignOut, when set, is where the browser goes next to end its
	// SystemAuth login session.
	SignOut *SystemAuthSignOut `json:"signOut,omitempty"`
}

type SystemAuthSignOut struct {
	URL      string `json:"url"`
	ReturnTo string `json:"returnTo"`
}

type TokenConfirmation struct {
	// JKT is the JWK SHA-256 thumbprint of the DPoP key the token is bound
	// to.
	JKT string `json:"jkt,omitempty"`
}

type User struct {
	ID          string           `json:"id"`
	Email       string           `json:"email,omitempty"`
	Managed     bool             `json:"managed,omitempty"`
	Name        string           `json:"name"`
	AvatarURL   string           `json:"avatar_url,omitempty"`
	Memberships []UserMembership `json:"memberships"`
	CreatedAt   time.Time        `json:"created_at"`
	UpdatedAt   *time.Time       `json:"updated_at,omitempty"`
}

type UserInfo struct {
	Subject       string `json:"sub"`
	Email         string `json:"email,omitempty"`
	EmailVerified bool   `json:"email_verified,omitempty"`
	// EmailVerifiedAt is SystemForge's email_verified_at extension: when
	// the email was verified, as a NumericDate (seconds since the epoch,
	// which may arrive in floating-point form); nil when absent.
	EmailVerifiedAt *gojwt.NumericDate `json:"email_verified_at,omitempty"`
	Name            string             `json:"name,omitempty"`
	Picture         string             `json:"picture,omitempty"`

	// Raw holds every returned claim.
	Raw map[string]any `json:"-"`
}

type UserMembership struct {
	ID               string    `json:"id"`
	OrganizationID   string    `json:"organization_id"`
	OrganizationName string    `json:"organization_name"`
	OrganizationSlug string    `json:"organization_slug"`
	OrganizationType string    `json:"organization_type,omitempty"`
	Role             string    `json:"role"`
	JoinedAt         time.Time `json:"joined_at"`
	// Applications maps application identifiers to the user's role there.
	Applications map[string]string `json:"applications,omitempty"`
}

type VerifiedIdentity struct {
	// Subject is the OIDC sub: the SystemAuth principal ID. Applications
	// store it as sf_principal_id.
	Subject string
	// Email is the SystemAuth-reported email.
	Email string
	// EmailVerified reports whether SystemAuth asserts Email is verified.
	EmailVerified bool
	// EmailVerifiedAt is when SystemAuth verified Email (the
	// email_verified_at claim); zero when it is not verified or the time
	// was not sent.
	EmailVerifiedAt time.Time
	// Name is the display name.
	Name string
	// Picture is the avatar URL.
	Picture string
	// Managed reports a managed principal (the managed claim): a human
	// without an email whose managers control the account (ADR-005).
	// Managed identities have no email.
	Managed bool
	// Service reports a service account (a principal_type of "service" in
	// an access token): created with type service and no email, never by
	// signing in. See BearerConfig.ServicePrincipals.
	Service bool
}