registry

type AccountSettings struct {
	// RequireVerifiedEmail: no session until the address is verified.
	RequireVerifiedEmail bool
	// WelcomeEmail sends the welcome email once the address is verified.
	WelcomeEmail bool
	// VerifyEmailTTL is how long a verification link works (account.tokens.verify_email).
	VerifyEmailTTL time.Duration
	// AllowEmailChange lets users change their own address (`POST /_auth/email`).
	AllowEmailChange bool
	// ChangeEmailTTL and RevertEmailChangeTTL are how long the confirmation
	// and the undo link of an email change work.
	ChangeEmailTTL, RevertEmailChangeTTL time.Duration
	// ResetPasswordTTL is how long a reset link works (account.tokens.reset_password).
	ResetPasswordTTL time.Duration
	// PurgeUnverifiedAfter deletes accounts that never verified; 0 is off.
	PurgeUnverifiedAfter time.Duration
	// OnSignup is the internal, async function (<database>/<function>) called for every
	// new user (account.on_signup), to create the app's profile document; OnSignupTimeout
	// is its timeout.
	OnSignup        string
	OnSignupTimeout time.Duration
}

type AdminAccess struct {
	Write   AdminRights
	ReadAll bool
}

type AdminRights uint8

type AppConfig struct {
	SchemaPath string
	RulesPath  string // rules.yaml, whether or not the file exists
	RawSchema  map[string]any
	Schema     *jsonschema.Schema
	// Paths holds every declared path (dot notation, `features.reports.enabled`);
	// a path is a branch (an object) or a leaf (a value).
	Paths map[string]ConfigPath
	// Defaults is the whole configuration with every leaf at its default.
	Defaults map[string]any
	// Rules are the read rules by path, as written; use Effective for what applies.
	Rules map[string]*rules.Rule
}

type CachePolicy struct {
	Public bool
	MaxAge int // seconds
}

type Collection struct {
	Realm         string
	Database      string
	MongoDatabase string // <realm>__<database>
	Name          string
	SchemaPath    string             // path of schema.json, for error messages
	RawSchema     map[string]any     // decoded schema.json (numbers as json.Number)
	Schema        *jsonschema.Schema // compiled draft 2020-12 schema
	Fields        map[string]Field   // dot path → field info, for query checks
	Indexes       []Index            // declared in indexes.json
	IndexPath     string             // path of indexes.json, when present
	Rules         *rules.Set         // from collection.yaml's rules:; nil allows nothing
	Erasure       *ErasurePolicy     // from collection.yaml; nil: an erase leaves the collection alone
	ErasurePath   string             // path of collection.yaml, for error messages
	SoftDelete    *SoftDelete        // from collection.yaml; nil: DELETE removes the document
	PersonalData  *PersonalData      // from collection.yaml's personal_data:; nil: owned documents, whole
	Cache         *CachePolicy       // from collection.yaml's cache:; nil: responses are private, no-cache
	CustomID      *CustomID          // from collection.yaml's custom_id:; nil: the server generates the ids

	Files map[string]*FileField // file fields from collection.yaml's files:; their schema is already in Schema and RawSchema
	// contains filtered or unexported fields
}

type ComplianceSettings struct {
	// ConsentProof lists what each consent record stores besides time, method and
	// text hash: ProofIP and ProofUserAgent. Both by default.
	ConsentProof []string
	// ConsentRetention is how long records are kept after erasure; 0 deletes them at erasure.
	ConsentRetention time.Duration
	// ConsentRetentionSet says whether realm.yaml chose a retention (0 is a choice).
	ConsentRetentionSet bool
}

type ConfigPath struct {
	Leaf        bool
	Description string
}

type Consent struct {
	Name string
	// Required consents must be accepted to have an account; optional ones can be
	// given and withdrawn at will.
	Required bool
	// Current is the version new accounts accept.
	Current string
	// Versions are the versions realm.yaml says something about, plus the current one.
	Versions map[string]*ConsentVersion
	// Texts holds the loaded texts by version and locale.
	Texts map[string]map[string]ConsentText
}

type ConsentRef struct{ Name, Version string }

type ConsentText struct {
	Body string
	Hash string // hex SHA-256 of Body
}

type ConsentVersion struct {
	// Reaccept asks users who accepted an earlier version to accept this one.
	Reaccept bool
	// ReacceptBy is the date after which open sessions of users who haven't accepted are
	// refused; the zero time means sessions continue until the user signs in again.
	ReacceptBy time.Time
}

type CookieSettings struct {
	Enabled bool
	// SameSite is lax (default), strict or none. none is for apps on another
	// site than the API (another registrable domain); lax and strict also work
	// for an app on a sibling subdomain.
	SameSite string
}

type CustomID struct {
	// User means the id must equal the id of the user creating the document.
	User bool
	// Pattern is the declared pattern as written; empty with User.
	Pattern string
	// DuplicateLimit is how many creates of an id that exists a caller may attempt per minute.
	DuplicateLimit int
	// contains filtered or unexported fields
}

type Database struct {
	Realm       string
	Name        string
	MongoName   string // <realm>__<database>
	Collections map[string]*Collection
	Functions   *Functions // from _functions/; nil when the database has none
	// contains filtered or unexported fields
}

type EmailLimits struct {
	PerKindPerHour int // emails of one kind to one recipient, per hour
	PerDay         int // emails to one recipient, per day
	PerIPPerHour   int // email-sending requests from one client address, per hour
	// The caps of custom emails from functions (ctx.email.send), whoever the
	// recipients are.
	PerFunctionPerHour   int // messages one function sends, per hour
	PerInvocation        int // messages one invocation sends
	RecipientsPerMessage int // to, cc and bcc of one message
}

type EmailSettings struct {
	Function  string // <database>/<function>: internal and async
	From      string // "Name <address>" or an address
	ReplyTo   string // optional
	PublicURL string // overrides BACKD_URL for this realm's links; no trailing slash
	Limits    EmailLimits
	// RedirectDelay is how long a hosted result page waits before it sends the
	// user on (email.redirect_delay).
	RedirectDelay time.Duration
	// Redirects are where the hosted pages send users afterwards, by flow
	// (verify_email, reset_password, change_email, invitation), when the
	// request that caused the email named no other place.
	Redirects map[string]string
	// AllowedRedirects are the origins (https://app.example.com) and app
	// schemes (acme://) that redirect_to, redirects and links may point at.
	AllowedRedirects []string
	// Links replace the hosted page of a flow with a page of the app: the
	// link in the email is this URL, with {token} replaced.
	Links map[string]string
	// Timeout is the delivery function's own timeout, set when the config is
	// loaded; email jobs lease for it.
	Timeout time.Duration
}

type ErasurePolicy struct {
	// Action applies to the documents whose _meta.owner is the user: "" leaves
	// them, ErasureDelete removes them, ErasureAnonymize applies Remove and
	// Replace and clears the owner.
	Action  string
	Remove  []string       // fields removed (anonymize)
	Replace map[string]any // fields set to a fixed value (anonymize)
	// Pull and Unset act on every document of the collection, whoever owns it:
	// the user is removed from the array field / cleared from the field. The
	// value says what the field holds: MatchEmail or MatchID.
	Pull  map[string]string
	Unset map[string]string
}

type Field struct {
	Types     []string // JSON Schema types; empty when the schema doesn't constrain it
	ItemTypes []string // for arrays: the types of the items, when declared
	// Date marks a field stored as a BSON Date (x-backd-store: date in
	// schema.json): clients send and read RFC 3339 strings, queries compare
	// dates.
	Date bool
}

type FileField struct {
	Name     string
	Multiple bool  // an array of files; otherwise at most one
	MaxFiles int   // for a multiple field
	MaxSize  int64 // bytes, per file
	// Types are the allowed content types, detected from the bytes (never the
	// client's claim): "image/png", or "image/*" for a family. Empty allows any.
	Types []string
	// Upload is UploadProxy or UploadDirect.
	Upload string
	// Download is DownloadPresigned or DownloadProxy; "" follows the realm's.
	Download string
	// PresignedTTL is how long this field's links last; 0 follows the realm's.
	PresignedTTL time.Duration
	// Cache is the Cache-Control max-age of proxied downloads of anonymously
	// readable documents; 0 means no caching.
	Cache time.Duration
	// Versions are the resized copies of an image the field declares, by name order.
	Versions []Version
	// MaxPixels lowers the instance's image pixel limit for this field; 0 follows it.
	MaxPixels int64
	// KeepMetadata stores the JPEG and PNG pictures of the field as they were sent. By default
	// their metadata (EXIF with the GPS position, XMP, comments, text chunks) is removed.
	KeepMetadata bool
}

type Function struct {
	Realm, Database, Name string
	Dir                   string // the function's folder
	Entry                 string // index.js or index.ts, relative to the project (slash-separated)
	Mode                  string
	Timeout               time.Duration
	Memory                int64 // bytes
	MaxOutput             int64 // bytes
	Concurrency           int
	RateLimit             *RateLimit  // nil: none
	Retry                 *Retry      // nil: a single attempt
	Idempotency           string      // optional or required
	Invoke                *rules.Rule // nil: only API keys may invoke
	Admin                 bool        // ctx.admin.db with full access
	ConfigWrite           bool        // ctx.admin.config: may change the realm's app configuration
	Internal              bool        // no HTTP route: only backd, scheduled runs and other functions call it
	Email                 bool        // ctx.email.send: may send custom emails through the realm's templates and delivery function
	// Push is set by `push:` in function.yaml: the function may send pushes (ctx.push.send).
	Push         *FunctionPush
	DevOnly      bool           // backd refuses to start with it unless BACKD_DEV=true (development helpers)
	Calls        []string       // functions of the same database this one may ctx.call
	Schedule     *cron.Schedule // nil: not scheduled
	ScheduleExpr string
	OnComplete   *OnComplete // nil: nothing is told when a job ends
	Timezone     string      // IANA name the schedule is read in; "UTC" unless set. Empty when not scheduled
	Overlap      string      // allow (default) or skip: what a scheduled time does while the previous run hasn't finished
	Secrets      []SecretRef
	Network      []string // hosts (host or host:port) the function may reach
	InputSchema  *jsonschema.Schema
	OutputSchema *jsonschema.Schema
}

type FunctionPush struct {
	// Kinds are the template kinds the function declares; Restricted says `kinds:` was given.
	Kinds      []string
	Restricted bool
	Audience   bool
}

type Functions struct {
	Dir       string               // the _functions directory
	Functions map[string]*Function // by name
}

type Index struct {
	Keys   []IndexKey
	Unique bool
	// TTL makes MongoDB delete a document when the date its single key holds
	// has passed (soft_delete.retention's purge_at).
	TTL bool
}

type IndexKey struct {
	Field string
	Desc  bool
}

type LoginThrottle struct {
	// AccountThreshold is how many failed attempts an account gets before
	// each new attempt must wait; IPThreshold is the same per client address
	// (IPv6 per /64), higher because a network can hide many people.
	AccountThreshold int
	IPThreshold      int
	// Window is how long a failure counts: the counter of an account or an
	// address expires this long after its last failure.
	Window time.Duration
	// MaxDelay is the longest anyone waits. It never exceeds Window.
	MaxDelay time.Duration
}

type MFASettings struct {
	// Off says users may not turn TOTP on (mfa.enabled: false). Users that already have
	// it are still asked for it: switching the feature off never weakens an account.
	Off bool
	// Issuer is the name authenticator apps show; the realm's name when empty.
	Issuer string
	// RequiredRoles are the roles whose holders must use MFA; RequiredAll means everyone.
	RequiredRoles []string
	RequiredAll   bool
}

type MagicLinkSettings struct {
	// Enabled turns the endpoints on; it needs the realm's email.
	Enabled bool
	// Signup lets an address that has no account make one (verified, by redeeming the link
	// or code), when the realm's own sign-up is open.
	Signup bool
}

type Manifest struct {
	Deno      string                    `json:"deno"`
	Source    string                    `json:"source"` // SourceHash of the project when built
	Functions map[string]ManifestBundle `json:"functions"`
}

type ManifestBundle struct {
	Bundle string `json:"bundle"` // file name in .build
	SHA256 string `json:"sha256"`
}

type Networks []netip.Prefix

type OnComplete struct {
	Function string   // a function of the same database
	On       []string // the endings that notify; every one when empty
}

type PersonalData struct {
	Export string   // ExportInclude (default) or ExportExclude
	Fields []string // only these fields (plus id and _meta); nil: whole documents
	Reason string   // why: required to exclude, and to leave fields out
}

type Provider struct {
	Name string // google, microsoft or apple
	// ClientID is the application's id with the provider (Apple: the Services ID);
	// ClientSecret names the secret that holds its secret (Apple has none: it
	// signs one from PrivateKey).
	ClientID     string
	ClientSecret string
	// NativeClientIDs (Apple: BundleIDs) are the extra audiences the ID-token
	// endpoint accepts, the ids of the mobile apps.
	NativeClientIDs []string
	// Tenant is Microsoft's: common, organizations, consumers or a tenant id.
	Tenant string
	// Apple only: the team and key that sign the client secret, the secret that
	// holds the private key, and whether a user's tokens are revoked when the
	// account goes away.
	TeamID, KeyID, PrivateKey string
	RevokeOnDelete            bool
}

type PushDelivery struct {
	Timeout       time.Duration
	RetryAttempts int
	RetryBackoff  time.Duration
	Parallelism   int
}

type PushLimits struct {
	PerMinute, PerDay int
}

type PushPlatform struct {
	Provider string
	// FCM: the service-account JSON.
	Credentials string
	// APNs: the .p8 signing key, its id, the team and the app's bundle id; Sandbox targets
	// api.sandbox.push.apple.com.
	Key           string
	KeyID, TeamID string
	Topic         string
	Sandbox       bool
	// Web Push: the VAPID private key and the contact URI (mailto: or https:).
	PrivateKey string
	Subject    string
}

type PushSettings struct {
	// Platforms holds the enabled platforms and their provider.
	Platforms map[string]PushPlatform
	// WebPublicKey is the VAPID public key (base64url, uncompressed P-256 point) browsers
	// subscribe with; WebEndpointHosts the hosts a subscription may point at: an exact host,
	// or `*.example.com` for any subdomain.
	WebPublicKey     string
	WebEndpointHosts []string
	// MaxDevicesPerUser caps a user's devices; StaleAfter removes devices not seen for that long.
	MaxDevicesPerUser int
	StaleAfter        time.Duration
	// Delivery tunes the built-in senders; Limits are the per-user limits; SendRetention is how
	// long the record of a send is kept.
	Delivery      PushDelivery
	Limits        PushLimits
	SendRetention time.Duration
}

type RateLimit struct {
	Per    string // user or ip
	Limit  int
	Window time.Duration
}

type ReadAccess struct {
	Users bool
	Data  bool
}

type Realm struct {
	Name      string
	Settings  RealmSettings // from realm.yaml
	Databases map[string]*Database
	// Email holds the parsed email templates of <realm>/email/; nil when the
	// realm doesn't configure email.
	Email *email.Templates
	// Pages are the hosted pages the links in emails open (<realm>/pages/);
	// nil when the realm doesn't configure email.
	Pages *email.Pages
	// Push holds the parsed push templates of <realm>/push/; nil when the realm has no push: section.
	Push *push.Templates
	// AppConfig is the realm's declared app configuration (<realm>/app-config/); nil when it has none.
	AppConfig *AppConfig
}

type RealmSettings struct {
	AuthEnabled bool
	Signup      string
	IdleTimeout time.Duration
	MaxLifetime time.Duration
	// AdminIdleTimeout and AdminMaxLifetime are the limits of the sessions of
	// users who hold an admin role (sessions.admin_idle_timeout and
	// sessions.admin_max_lifetime). 0 means the regular limit; set, they never
	// exceed it.
	AdminIdleTimeout time.Duration
	AdminMaxLifetime time.Duration
	// Cookie lets browser apps keep a session in an HttpOnly cookie, when
	// their login asks for it (sessions.cookie).
	Cookie            CookieSettings
	PasswordMinLength int
	// LoginThrottle is login_throttle; read it through Throttle(), which
	// fills in the defaults.
	LoginThrottle LoginThrottle
	CORSOrigins   []string
	Roles         map[string]Role
	// AdminNetworks restricts every admin API request (admin.allowed_networks);
	// empty means unrestricted.
	AdminNetworks Networks
	// ReadAccess is what read-only administrators (`admin: read`) may see
	// beyond operations (admin.read_access).
	ReadAccess ReadAccess
	// UserNetworks are the network restrictions realm.yaml sets per user
	// email (in a role's user entries).
	UserNetworks map[string]UserNetworks
	// OpenAPIPublic makes the realm's OpenAPI document readable without credentials
	// (openapi.public: true); otherwise only the realm's administrators read it.
	OpenAPIPublic bool
	// AppConfigCacheTTL is how long clients treat the app configuration as fresh
	// (app_config.cache_ttl); zero when not set: use AppConfigTTL.
	AppConfigCacheTTL time.Duration
	// AuditRetention is how long audit records are kept (audit.retention);
	// DefaultAuditRetention when not set.
	AuditRetention time.Duration
	// FunctionsMaxConcurrency caps how many function calls may run at once
	// on this backd instance (functions.max_concurrency); 0 means
	// unlimited. Applies whether or not auth is enabled.
	FunctionsMaxConcurrency int
	// FunctionsLogRetention is how long invocation records (roadmap F10)
	// are kept (functions.log_retention); DefaultLogRetention when not
	// set. Needs auth enabled, like the rest of functions.* except
	// max_concurrency: there's no system database to store them in
	// otherwise.
	FunctionsLogRetention time.Duration
	// FunctionsJobRetention is how long an async job's result (roadmap
	// F11) is kept once done (functions.job_retention); DefaultJobRetention
	// when not set. Needs auth enabled, like FunctionsLogRetention.
	FunctionsJobRetention time.Duration
	// Email is how the realm sends email (email in realm.yaml); nil when it
	// doesn't, and then no email is ever sent.
	Email *EmailSettings
	// Storage is where the realm's files live (storage in realm.yaml); nil
	// when it has none, and then it can't declare file fields.
	Storage *StorageSettings
	// Account is how the realm's accounts behave (account in realm.yaml).
	Account AccountSettings
	// Providers are the external identity providers (providers in realm.yaml),
	// by name; SignInRedirects are where a sign-in may send the user back to
	// (sign_in.allowed_redirects, normalized like email.allowed_redirects).
	Providers       map[string]*Provider
	SignInRedirects []string
	// SignInAppURL (sign_in.app_url) is where a sign-in goes back to when its
	// redirect_to is absent: the app's own address, within the allowed redirects.
	SignInAppURL string
	// MFA are the multi-factor settings (mfa in realm.yaml).
	MFA MFASettings
	// ReauthTTL is how long a re-authentication token works (reauth.ttl).
	ReauthTTL time.Duration
	// DefaultLocale and Locales are the languages of the realm (default_locale and locales in
	// realm.yaml): users' languages are mapped to them, and email and push templates exist for
	// each. Read them with Languages.
	DefaultLocale string
	Locales       []string

	// Push holds the push notification settings: nil without a push: section.
	Push *PushSettings

	// MagicLink are the settings of sign-in by emailed link and code (magic_link in realm.yaml).
	MagicLink MagicLinkSettings

	// Consents are the consents the realm asks for (consents in realm.yaml), with the texts
	// of every version once loaded; Compliance holds what their records keep and for how long.
	Consents   map[string]*Consent
	Compliance ComplianceSettings
}

type Registry struct {
	Realms map[string]*Realm
	Root   string // the CONFIG_DIR it was loaded from
}

type Retry struct {
	Attempts   int           // total attempts, the first included
	Backoff    time.Duration // the wait after the first failure; doubles after each one
	MaxBackoff time.Duration // the longest single wait
}

type Role struct {
	Description string
	// Admin is what the sessions of users holding the role may do in the
	// admin API: AllRights for `admin: true`, some areas for a list, none.
	Admin AdminRights
	// AdminRead is `admin: read` (alone or in a list): every area may be read.
	AdminRead bool
	// Users are seed assignments: normalized (trimmed, lowercased) emails.
	Users []string
}

type ScopeEntry struct {
	Database   string
	Collection string
	// Export is ExportInclude or ExportExclude.
	Export string
	// Owned: documents whose _meta.owner is the user. Always true when included.
	Owned bool
	// Fields lists the exported fields when the export is partial; nil means whole documents.
	Fields []string
	// Pull lists the arrays that hold the user, whose documents are included whoever owns them.
	Pull []string
	// Files lists the file fields whose files are part of the export.
	Files  []string
	Reason string
	// Declared: personal_data is in the collection's collection.yaml.
	Declared bool
}

type SecretRef struct {
	Realm bool
	Name  string
}

type SoftDelete struct {
	// Retention is how long a deleted document is kept before MongoDB's TTL
	// index removes it; 0 keeps it until it is purged by hand.
	Retention time.Duration
}

type StorageSettings struct {
	Provider string // storage.Provider's Name; LookupProvider gives its capabilities
	// Endpoint and Region are what backd connects to, as the provider's rules
	// resolve them; PublicEndpoint (providers that allow it) is only signed into
	// links for browsers and never connected to.
	Endpoint       string
	PublicEndpoint string
	Region         string
	Bucket         string
	// Prefix starts every object key of this instance (<prefix>/<realm>/…): each
	// backd instance sharing a bucket needs its own.
	Prefix string
	// AccessKey and SecretKey are the names of secrets of the realm's encrypted
	// store (storage.access_key: secret:NAME), never values.
	AccessKey, SecretKey string
	Download             string // DownloadPresigned or DownloadProxy: the default of the realm's fields
	PresignedTTL         time.Duration
	PendingTTL           time.Duration
	// QuotaRealm and QuotaUser are the most bytes the files of all documents of the realm, and
	// of the documents one user owns, may add up to; 0 is no limit. An upload that would pass
	// either answers 413 quota_exceeded.
	QuotaRealm, QuotaUser int64
	// HTTP is true when Endpoint or PublicEndpoint is plain http, which startup
	// allows only in development.
	HTTP bool
}

type UserNetworks struct {
	Admin Networks // the user's admin API requests; within AdminNetworks
	Login Networks // login and every request with the user's session
}

type Version struct {
	Name string
	// Params are what workers make it with; zero (no max_width or max_height) for a
	// version only functions make.
	Params imaging.Params
	// Writable lets functions make the version (with other parameters, too).
	Writable bool
}