addon

type Cookie struct {
	Name  string `json:"name"`
	Value string `json:"value"`
	// MaxAge is seconds. Zero is a session cookie; negative deletes.
	MaxAge int `json:"max_age"`
}

type DeclarationClass string

type FailureClass string

type FailureClassError struct {
	Addon string
	Var   string
	Value string
}

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

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

type InlineResult struct {
	// Vetoed is a module refusing this redirect. The handler answers the gate
	// refusal with it, and nothing about the add-on reaches the visitor.
	Vetoed bool
	// Destination is where the visitor goes, which is the one that was handed in
	// unless a module rewrote the query and held the grant that costs.
	Destination string
	// Rewritten is whether Destination differs from what was handed in. The
	// handler does not need it; the tests do, and so does the log line that says a
	// module changed where somebody was sent.
	Rewritten bool
}

type InstallRequest struct {
	// Manifest is `addon.json` verbatim, parsed by the same reader the boot path
	// uses so that an add-on installed through the API and one placed by hand are
	// refused for the same reasons.
	Manifest []byte
	// Module is the `.wasm`, hashed against the manifest's `sha256` before it is
	// written anywhere.
	Module []byte
}

type Installed struct {
	Name         string       `json:"name"`
	Version      string       `json:"version"`
	ABIVersion   int          `json:"abi_version"`
	SHA256       string       `json:"sha256"`
	FailureClass FailureClass `json:"failure_class"`
	Permissions  []string     `json:"permissions"`
	// Schema is the Postgres schema this add-on owns, or empty. On a removal it is
	// the orphan that has just been created: removal deletes no data, and naming
	// the schema at the moment of the act is what stops the leftover being
	// something an operator discovers later (M63, and M68's purge offer).
	Schema string `json:"schema,omitempty"`
	// Draining is set on a removal whose in-flight invocations had not finished
	// when [removeGrace] expired, so the modules were closed under them. It is a
	// fact about what this instance did, not a warning to act on.
	Draining bool `json:"draining,omitempty"`
}

type JarCookie struct {
	Name  string
	Value string
	// MaxAge is seconds, and follows the same convention a [Cookie] does: zero is
	// a session cookie, negative deletes. Negative is how an emptied jar is
	// cleared from a browser that still holds one.
	MaxAge int
}

type LoadError struct {
	// Addon is the directory the add-on was found in, which is its name: the two
	// are required to match, so this is knowable even when the manifest is the
	// thing that failed to parse.
	Addon   string
	Outcome Outcome
	Err     error
	// contains filtered or unexported fields
}

type Loaded struct {
	Manifest Manifest
	// Dir is the absolute directory the add-on was loaded from.
	Dir string
	// Schema is the Postgres schema this add-on owns, or "" for one that did not
	// declare storage.own_schema. It is derived from the name rather than recorded
	// anywhere — store.AddonSchema is the derivation — which is what makes two
	// add-ons contending for one schema impossible rather than merely unlikely: the
	// directory *is* the name and loadOne refuses a manifest that disagrees.
	Schema string
	// FailureClass is what this host **applies**, which is the manifest's answer
	// only when neither of the two things that outrank it applied. Read this rather
	// than Manifest.FailureClass: the boot log, the info gauge and the decision to
	// stop the instance all use this one, and the manifest's field is the
	// publisher's declaration rather than the outcome.
	FailureClass FailureClass
	// contains filtered or unexported fields
}

type Managed struct {
	Installed
	// Declaration is the list's CLASS column.
	Declaration DeclarationClass `json:"declaration"`
	// Declared is what the manifest asked for, which is m68.md's column and is not
	// always [Installed.Permissions] — that one is what the add-on **holds**, and a
	// permission this build publishes and grants to nobody is declarable and not
	// held.
	//
	// Both, rather than one, because they answer different questions and the
	// milestone asks for the first: *what does this add-on say it needs* is what an
	// operator agreed to when they installed it, and *what does it hold* is what
	// this build will let it do. The two are identical today — nothing declarable
	// is ungranted since M66 turned `redirect.inline` on — and the page marks the
	// difference rather than assuming it away, because the last time they diverged
	// it was for a whole phase.
	Declared []string `json:"declared_permissions"`
	// Performance is what this module cost, cumulative since this process started:
	// its invocations on the redirect path, and — since M68.5 — its outbound
	// requests, which are a different path with a different bound and sit beside
	// the redirect figures rather than inside them.
	//
	// Absent — `IsZero()`, which is `Observed()` false on **both** halves — for a
	// module with no record of either kind. The page draws a dash for whichever
	// half a module has no record of, and the API omits the whole object rather
	// than answering with one full of zeros. The two predicates ask different
	// questions and M68.5 is where they stopped coinciding: a module that has only
	// ever fetched has never run on the redirect path, so its row still draws a
	// dash there while its JSON carries the object.
	//
	// **It is in the JSON as well as on the page**, and that is the inherited *every
	// UI feature has API support* rule read as it is written: the figures are the
	// reason the manager exists, so a client that could list add-ons and not read
	// them would be a second surface with less in it. `/metrics` is not an answer
	// here — it is on a listener this product does not publish, for the reason the
	// add-on inventory is operational detail.
	Performance observability.AddonPerformance `json:"performance,omitzero"`
	// SchemaBytes is the on-disk size of the add-on's own schema, or 0 for a module
	// that declared no storage. Measured at render time; see this file's header.
	SchemaBytes int64 `json:"schema_bytes,omitempty"`
	// DeclaredSettings is how many settings the manifest declares and Configured is
	// how many have a value. The pair is what the list needs to say *3 of 5 set*
	// without reading a value it may not echo.
	//
	// **The manifest's own list, which since M69.5 is not all of [Settings].** An
	// add-on that asked for a sign-in link gets one more row on the detail page —
	// the host's consent toggle — and it is deliberately not counted here: this
	// figure answers *what did this add-on ask to be configured with*, and the
	// consent is this instance's question rather than the add-on's. Making the two
	// agree would mean calling the host's question the add-on's.
	DeclaredSettings int `json:"declared_settings"`
	ConfiguredCount  int `json:"configured_settings"`
	// Settings is the detail page's render model, and is nil on the list. Two
	// shapes rather than two types, because a list row and a detail page describe
	// one add-on and a second type would be a second thing to keep true.
	Settings []SettingView `json:"settings,omitempty"`
	// MemoryBytes is the resident guest memory of the load-time instance. What an
	// operator sizes a host by, and the number M64's bound is expressed in.
	MemoryBytes uint32 `json:"memory_bytes,omitempty"`
}

type Manifest struct {
	SchemaVersion int    `json:"schema_version"`
	Name          string `json:"name"`
	Version       string `json:"version"`

	// ABIVersion is which host ABI the module was built against. Parsed now,
	// consumed at M61, where an unsupported value becomes a refusal.
	ABIVersion int `json:"abi_version"`

	// Module is the .wasm this manifest accompanies, as a bare filename resolved
	// inside the add-on's own directory. Validation refuses a separator, so a
	// manifest cannot name a path out of it.
	Module string `json:"module"`

	// SHA256 is the digest of Module, lowercase hex. This is the load-time half
	// of the owner's "both" answer on build verification; the published-
	// provenance half belongs to the add-on's release process and is M69's.
	SHA256 string `json:"sha256"`

	FailureClass FailureClass `json:"failure_class"`

	// Permissions is what the add-on says it needs, and it is the whole of what it
	// may do: the vocabulary is abi.Permissions, every host function names the
	// grant it costs, and a call whose grant is not declared here is refused
	// (M62). Validation below refuses a token outside the vocabulary; whether a
	// declared one is actually *held* is resolveGrants', because a permission can
	// exist and be grantable by no host yet.
	Permissions []string `json:"permissions,omitempty"`

	Settings []Setting `json:"settings,omitempty"`

	// Migrations is the DDL this add-on ships, one entry per file, each with the
	// digest of the file it names.
	//
	// **Enumerated with a digest each rather than summarised**, and both halves
	// earn their place. The digest extends M60's answer from the module to the
	// DDL: the host runs these statements, an operator did not write them, and
	// the manifest is what makes them *the add-on author's* rather than whatever
	// is on disk. Enumerating closes the set — a `.sql` file present in the
	// directory and absent here refuses the add-on, so nothing can be added to
	// what the host will execute without editing the manifest that describes it.
	// A publisher computes these with the same `sha256sum` they already used for
	// the module, which is why it is a digest per file and not one aggregate over
	// a canonical ordering nobody could reproduce by hand (D247).
	//
	// Files live in the add-on's own `migrations/` directory and are goose SQL:
	// the host applies them at load, inside the schema the add-on owns, with the
	// add-on's own role. An add-on that lists any of these must also declare
	// `storage.own_schema`; validation refuses the pair being incoherent.
	Migrations []MigrationFile `json:"migrations,omitempty"`

	// CookiePrefixes is the cookie namespace this add-on owns: the request record
	// M64 hands it carries the cookies whose names begin with one of these and no
	// others, and the cookies it may set are bounded the same way.
	//
	// Declared rather than granted wholesale because this product's sessions are
	// server-side and opaque, which makes the Cookie header the credential itself
	// — an add-on handed it verbatim could act as whoever is signed in. Owner-set
	// 2026-08-18 (D232). Parsed and validated here, where the manifest's other
	// declarations live; consumed at M64, which is where a request first reaches
	// an add-on.
	CookiePrefixes []string `json:"cookie_prefixes,omitempty"`

	// SignInLabel is the words this add-on asks the sign-in page to draw, and
	// SignInPath is where inside its own M64 prefix that link should go (M69.5).
	//
	// **Two fields rather than one**, and the second is what keeps D364's rule —
	// the manifest names a need and never a destination — true on a second
	// surface. A label alone would have meant *link to my prefix root*, which is
	// a reserved meaning the ABI never gave that path: an add-on serving
	// `/addons/oidc/` at all is not thereby serving a sign-in there. Owner-
	// answered 2026-08-27.
	//
	// **Neither is a URL and neither is the target.** The host composes the href
	// from [RoutePrefix], this add-on's own name and this path, and then asserts
	// the result is still under the prefix it gave the add-on — see
	// [Loaded.SignInHref]. Validation below refuses the shapes that would try to
	// leave it (`..`, a leading `/`, a scheme, a host), so a manifest cannot name
	// a destination even before the composition is checked.
	//
	// **A label is not consent.** Declaring one is the add-on asking; the operator
	// agrees by turning on the [SignInConsentSetting] toggle on the Add-on
	// manager's detail page, and it is off until they do. An empty or absent label
	// draws nothing, so no add-on puts itself on the front door by omission.
	SignInLabel string `json:"sign_in_label,omitempty"`
	SignInPath  string `json:"sign_in_path,omitempty"`
}

type MigrationFile struct {
	// File is a bare filename inside the add-on's `migrations/` directory. The
	// same refusal the module gets: a separator, a dot entry or a name that is not
	// `.sql` is a manifest that should not load rather than a path to clean up.
	File string `json:"file"`
	// SHA256 is the digest of that file, lowercase hex — byte-identical to what
	// `sha256sum` prints, for the reason [Manifest.SHA256] is lowercase.
	SHA256 string `json:"sha256"`
}

type Minted struct {
	// Token is the session cookie's value, or empty when a second factor is owed.
	// A Secret, so that no log line, no %v and no JSON encoder anywhere can turn
	// this struct back into a credential — the same wrapping an operator's
	// configured add-on settings get, and for a stronger reason.
	Token config.Secret
	// PendingToken is the second-factor challenge, or empty. Also a Secret: it is
	// a bearer credential for one operation, and one operation is a session.
	PendingToken config.Secret
	// ExpiresAt is whichever of the two above expires.
	ExpiresAt time.Time
	// SecondFactorRequired distinguishes the two without reading either Secret.
	SecondFactorRequired bool
}

type MintedSession struct {
	ExpiresAt string `json:"expires_at"`
	// SecondFactorRequired is true when the host stopped at its own prompt. The
	// module's own `location` is then where the visitor lands *after* the prompt
	// rather than immediately — the host interposes, because the pending
	// credential is the host's and there is no shape in which a module holds one.
	SecondFactorRequired bool `json:"second_factor_required"`
}

type Options struct {
	// Dir is LINKCTRL_ADDONS_DIR. Empty means there is no host at all — Open
	// returns a nil *Host, constructs no runtime and starts no goroutine.
	Dir string

	Logger  *slog.Logger
	Metrics *observability.Metrics

	// DB is the application's own pool, used for the two things an add-on's
	// storage needs the *product's* privileges for: creating the schema and the
	// role an add-on is confined to, and reading the catalogue to enumerate and
	// measure them. No add-on's statement ever runs on it — that is what the
	// per-add-on pool in store.AddonDB is for, and the separation is the boundary
	// rather than a tidiness.
	DB *pgxpool.Pool
	// DSN is the same database, as a connection string, because an add-on's own
	// pool authenticates as a different role and a pool cannot be re-pointed at
	// one. Everything else about the connection — host, port, database, TLS — is
	// inherited from it, so there is no second connection string to configure.
	//
	// Empty means no storage: the schema is not created, the migrations are not
	// applied, and a call to a storage function answers StatusInternal after
	// saying so in the log. That is a host constructed without a database, which
	// in this product is a test and never an instance — cmd/linkctrl opens the
	// pools before it opens the host, and both of these come from the same place
	// the migrations did.
	DSN string

	// Settings is where an add-on's configured values come from, asked for the
	// settings its manifest declares. Nil means the environment, through
	// [config.AddonSettings], which is what an instance uses; a test substitutes
	// values without writing to the process environment.
	Settings func(addon string, declared []string) map[string]config.Secret

	// Overrides is where an operator's per-add-on answers come from — the two
	// names in [config.AddonOverrideNames], which are not settings and which no
	// manifest may declare. Nil means the environment, through
	// [config.AddonOverrides]; a test substitutes them without writing to the
	// process environment, which is what lets the tests that exercise them run in
	// parallel.
	Overrides func(addon string) map[string]string

	// Sessions is what answers `session_mint` (M65). Nil is a host that cannot
	// mint — every unit test in this package, and no instance — and such a host
	// answers StatusInternal rather than pretending the function is not
	// implemented, because *this host has no database* and *this ABI does not have
	// that function* are different facts and a module branches on them differently.
	Sessions SessionMinter

	// Audit is what records the two lifecycle acts (M67). Nil records nothing,
	// which is a host built by a test; an instance passes the audit service, and
	// installing code into a running server without a record of who did it is the
	// one thing this surface must not be able to do quietly.
	Audit audit.Recorder

	// LoadTimeout is how long one add-on may take to load. Zero means
	// [DefaultLoadTimeout], which is what an instance uses; a test sets a budget it
	// can afford to spend watching a module that will not return.
	LoadTimeout time.Duration

	// InlineDeadline is how long an add-on's own code may hold a redirect open
	// (M66). Zero means [DefaultInlineDeadline], and an instance sets it from
	// LINKCTRL_ADDON_INLINE_DEADLINE. Unlike LoadTimeout it is an operator's knob
	// and not only a test's, because what it bounds is somebody else's code on the
	// path this product makes a latency promise about — see redirect.go.
	InlineDeadline time.Duration

	// InstantiateDeadline is how long this host will spend starting a module for a
	// redirect-class invocation (M66, reopened). Zero means
	// [DefaultInstantiateDeadline], and an instance sets it from
	// LINKCTRL_ADDON_INSTANTIATE_DEADLINE.
	//
	// **A test sets it for a reason no other bound here has.** It is the one number
	// in this package whose right value depends on the machine, so a suite that
	// leaves it at the default is a suite asserting that this machine is fast:
	// F326 shipped because five integration tests were green here and could not
	// pass on a hosted runner. Behaviour tests therefore buy room with it, and the
	// tests that are *about* the bound set a hostile one and make a slow machine
	// reachable on any machine at all.
	InstantiateDeadline time.Duration

	// PoolSize is how many idle add-on instances this host keeps across every
	// add-on (M66.5). Zero means [DefaultPoolSize], and an instance sets it from
	// LINKCTRL_ADDON_POOL_SIZE.
	//
	// It is not a concurrency bound. What bounds invocations in flight is
	// [addonSlots] and the pool takes nothing from it; this is what may be
	// held at rest, which is the term the guest-memory ceiling gained when an
	// instance stopped being destroyed after every redirect.
	PoolSize int

	// PoolTTL is how long an idle instance is kept before it is closed for lack of
	// traffic (M66.5). Zero means [DefaultPoolTTL], and an instance sets it from
	// LINKCTRL_ADDON_POOL_TTL.
	PoolTTL time.Duration

	// RouteDeadline is how long one request to an add-on's own route may take,
	// start to finish (M68.5). Zero means [DefaultRouteDeadline], and an instance
	// sets it from LINKCTRL_ADDON_ROUTE_DEADLINE.
	//
	// **The bound m68.5.md required before anything was allowed to fetch**, and it
	// applies to every route invocation rather than only to the ones that do — a
	// deadline conditional on a permission would leave the hole open for every
	// add-on that did not declare it while being a second rule to reason about.
	//
	// It is a bound **inside** the caller's, not the first one a route handler ever
	// had. An application request already carries LINKCTRL_HTTP_REQUEST_TIMEOUT's
	// context deadline and that cancels this same context, so the value only means
	// anything while it is shorter; internal/config refuses one that is not. What
	// the margin buys is a host that is still alive when the guest is killed, and
	// what the bound buys outright is an instance slot back from a module that will
	// not return — including on an instance that has turned the request timeout
	// off. See [DefaultRouteDeadline].
	RouteDeadline time.Duration

	// FetchTimeout bounds one outbound request an add-on makes (M68.5). Zero means
	// [DefaultFetchTimeout], and an instance sets it from
	// LINKCTRL_ADDON_FETCH_TIMEOUT.
	FetchTimeout time.Duration

	// FetchMaxBytes is the largest response body an add-on's fetch may bring back
	// (M68.5). Zero means [DefaultFetchMaxBytes], and an instance sets it from
	// LINKCTRL_ADDON_FETCH_MAX_BYTES.
	FetchMaxBytes int64
}

type Orphan struct {
	Name   string `json:"name"`
	Schema string `json:"schema"`
	// Bytes is every relation in the schema that has storage, with its indexes and
	// its TOAST — store.AddonSchemaBytes, measured now.
	Bytes int64 `json:"bytes"`
	// LargeObjects is how many large objects the schema's role owns. **They are not
	// deleted by a purge** — they live outside every schema — so the number is here
	// to be honest about what is left rather than to describe what goes.
	LargeObjects int64 `json:"large_objects"`
	// IdentityLinks is how many `addon_identity_links` rows were written under this
	// name, and it is here for the same reason: **a purge deletes none of them.**
	//
	// One of the four things `PurgeAddonSchema` leaves standing, and one of the two
	// an operator is least likely to predict — the mappings are keyed on the
	// add-on's *name*, so a different module installed under a name that has been
	// used before inherits every account mapping the previous one wrote and can
	// mint a session against them on its first assertion (docs/SECURITY.md; F330
	// carries the removal-side answer). The confirmation is the point of decision
	// where that can still be acted on, so the number is measured for it rather
	// than described in prose the page does not carry.
	IdentityLinks int64 `json:"identity_links"`
	// StoredSettings is how many `addon_settings` rows were saved under this name,
	// and it is the fourth. Same key, same inheritance, same silence: a value an
	// operator typed into the manager's detail page — possibly a `secret` — is
	// keyed on the add-on's name (04800), survives both the removal and the purge,
	// and is handed to whatever is installed under that name next. **Nothing in
	// this product deletes one**: `SaveSettings` refuses a name that is not loaded,
	// so a removed add-on's rows are unreachable from every surface here. F332 in
	// docs/build-notes/deferred-findings.md carries that half. What this number
	// buys is that the point of decision says so with a figure instead of leaving
	// it to the migration's comment.
	StoredSettings int64 `json:"stored_settings"`
	// Measured says the size in [Orphan.Bytes] came from the catalogue rather than
	// from the read having failed.
	//
	// Not in the JSON: a client reading a *list* can ask again, and the list is the
	// only place this type is answered before the schema is gone. The audit record
	// is where it matters, because that row is the durable answer to *how much did
	// that delete* and `0` is what an empty schema honestly measures — so a failed
	// read written as a figure is indistinguishable from a true one, in the one
	// record that outlives the thing it describes.
	Measured bool `json:"-"`
}

type Outcome string

type RedirectAnswer struct {
	Verdict string `json:"verdict,omitempty"`
	Rewrite bool   `json:"rewrite,omitempty"`
	Query   string `json:"query,omitempty"`
}

type RedirectDecision struct {
	LinkID      uuid.UUID `json:"link_id"`
	WorkspaceID uuid.UUID `json:"workspace_id"`
	Alias       string    `json:"alias"`
	Destination string    `json:"destination"`
}

type RedirectEvent struct {
	LinkID       string `json:"link_id"`
	WorkspaceID  string `json:"workspace_id"`
	OccurredAt   string `json:"occurred_at"`
	VisitorHash  string `json:"visitor_hash"`
	IsFirstVisit bool   `json:"is_first_visit"`
	Country      string `json:"country"`
	Device       string `json:"device"`
	Browser      string `json:"browser"`
	OS           string `json:"os"`
	Language     string `json:"language"`
	ReferrerHost string `json:"referrer_host"`
	IsBot        bool   `json:"is_bot"`
}

type Request struct {
	Method string `json:"method"`
	// Path is the path *within* the add-on's prefix, always beginning with "/".
	// An add-on therefore cannot tell which prefix it was mounted under from the
	// request, which is deliberate: the prefix is its name and it knows its name.
	Path           string            `json:"path"`
	Query          string            `json:"query"`
	Cookies        map[string]string `json:"cookies"`
	ContentType    string            `json:"content_type"`
	AcceptLanguage string            `json:"accept_language"`
	Body           string            `json:"body"`
	// BodyBase64 says how to read Body, and it is the field that makes the
	// record's own sentence — "the body, base64 when it is not UTF-8" —
	// decidable. Without it a guest could not tell a base64 body from a body
	// that happens to look like base64, which is D262.
	BodyBase64 bool `json:"body_base64"`
}

type RequestIn struct {
	Method string
	// Path is already relative to the add-on's prefix, and must begin with "/".
	Path           string
	Query          string
	ContentType    string
	AcceptLanguage string
	Body           []byte
	Cookies        []*http.Cookie

	// ClientIP and UserAgent are the request's, and they are here for exactly one
	// consumer: a session minted through `session_mint` records where the sign-in
	// came from, in the same columns and by the same reduction the password path
	// uses. **Neither reaches the guest.** RequestIn is the host's input type and
	// [RequestIn.record] is what turns it into the record a module sees; neither
	// field is copied into it, no ABI record has a field for either, and
	// abi.AddressBearing fails the surface test if one ever acquires a name that
	// reads like an address. The address itself becomes a /24 or /48 prefix inside
	// internal/auth before it reaches a column, which is where every other address
	// in this product is reduced.
	ClientIP  netip.Addr
	UserAgent string

	// Identity is whoever the *host* resolved for this request, or nil for
	// nobody. It is the single source of truth about who is signed in, and
	// [RequestIn.session] is what a module is allowed to see of it.
	//
	// **One value rather than two**, which M65 is why. Two host functions have
	// opposite requirements about a session — `identity_link` refuses unless
	// somebody is signed in, `session_mint` refuses unless nobody is — and the
	// record a module sees is blanked for an add-on that did not declare
	// `session.context`. Passing the record as well would therefore have let an
	// add-on's own manifest decide whether the host noticed a session, which is
	// the wrong thing to be able to arrange from inside a manifest.
	Identity *auth.Identity
}

type Response struct {
	Status      int      `json:"status"`
	ContentType string   `json:"content_type"`
	Location    string   `json:"location"`
	SetCookie   []Cookie `json:"set_cookie"`
	Body        string   `json:"body"`
	// Jar is what the host writes to the browser for the cookies above, and it
	// is not part of the record: a module neither sends it nor sees it.
	//
	// [Host.Route] fills it and **empties SetCookie doing so**, which is the
	// structural half of F289's fix. The list a module wrote is gone by the time
	// a response leaves this package, so a writer — the one in internal/httpx, or
	// one a later milestone adds without having read this comment — has nothing
	// to loop over but the jar, and the jar is at most two cookies however many a
	// module named.
	Jar []JarCookie `json:"-"`
	// Minted is the session the host minted while this module was answering, or
	// nil. Also not part of the record: a module neither sends it nor sees it, and
	// what it holds — the session token — is the one value M65 exists to keep on
	// this side of the sandbox.
	//
	// It is on the response rather than a second return value because the two
	// travel together to exactly one place: internal/httpx writes a cookie and then
	// writes the module's answer, in that order, and a caller that ignored this
	// field would produce a page for somebody the host had already signed in.
	//
	// A module that mints and then **fails** — traps, writes no response, answers a
	// refusal — loses this, because Route returns an error and there is no response
	// to carry it on. The session row still exists and expires on its own; the
	// visitor gets a 502 and is not signed in. That is the safe direction of the two
	// and it is stated rather than fixed: writing a session cookie alongside a
	// failure page would sign somebody in on the strength of a module that crashed.
	Minted *Minted `json:"-"`
}

type SessionClaim struct {
	Subject       string   `json:"subject"`
	Issuer        string   `json:"issuer"`
	Email         string   `json:"email"`
	EmailVerified bool     `json:"email_verified"`
	DisplayName   string   `json:"display_name"`
	Groups        []string `json:"groups"`
}

type SessionContext struct {
	SignedIn       bool   `json:"signed_in"`
	UserID         string `json:"user_id"`
	Email          string `json:"email"`
	DisplayName    string `json:"display_name"`
	WorkspaceID    string `json:"workspace_id"`
	OrganizationID string `json:"organization_id"`
	Role           string `json:"role"`
}

type SessionMinter interface {
	MintFromAddonAssertion(ctx context.Context, in auth.AddonAssertion) (*auth.AddonMint, error)
	// LinkAddonIdentity is `identity_link`'s half. The actor is the *host's* —
	// resolved from the request's own session — and it is a parameter rather than
	// something the implementation looks up, because that is what makes "a module
	// names a subject and the host names the account" a property of the signature.
	LinkAddonIdentity(ctx context.Context, actor *auth.Identity,
		addon, issuer, subject string) error
}

type Setting struct {
	Name    string      `json:"name"`
	Type    SettingType `json:"type"`
	Options []string    `json:"options,omitempty"`
	Default string      `json:"default,omitempty"`

	// Origin marks a setting whose value is the origins this add-on may make
	// outbound requests to (M68.5), and it is the whole of how a destination
	// reaches the host: an origin the host will dial comes from a setting marked
	// here and filled in by the operator, and from nowhere else.
	//
	// **A flag rather than a fifth [SettingType]**, because what changes is the
	// meaning and not the input: the operator types text into the same box M68
	// already draws, and a new type would be a shape the manager has to learn to
	// render for no gain. What the flag costs is stated in [Setting.validate] —
	// such a setting is `text`, carries no default and carries no options — and
	// each of those is what keeps *the manifest declares a need, never a
	// destination* true. A default would be a host the add-on's author chose; an
	// option list would be several.
	//
	// The value an operator writes is one or more origins separated by spaces, so
	// an issuer whose token endpoint lives on a second name is two origins in one
	// field rather than a second field the add-on had to have anticipated.
	Origin bool `json:"origin,omitempty"`
}

type SettingSource string

type SettingType string

type SettingView struct {
	Name    string        `json:"name"`
	Type    SettingType   `json:"type"`
	Options []string      `json:"options,omitempty"`
	Default string        `json:"default,omitempty"`
	Source  SettingSource `json:"source"`
	// Value is the effective value for a text, select or toggle setting, and is
	// always empty for a secret.
	Value string `json:"value,omitempty"`
	// Configured is whether anything has answered this setting — the only thing
	// said about a secret that has a value.
	Configured bool `json:"configured"`
	// EnvVar is the variable that answered it, and is empty unless Source is
	// SourceEnvironment. Named so an operator who wants to change a pinned value
	// knows what to edit.
	EnvVar string `json:"env_var,omitempty"`
	// UpdatedAt is when the stored value was last written, and is nil for every
	// other source.
	UpdatedAt *time.Time `json:"updated_at,omitempty"`

	// Origin is whether this setting names where the add-on may make outbound
	// requests (M68.5), and the page renders it differently for one reason: filling
	// it in **authorizes a server-side request from this instance** to whatever is
	// typed in it. m68.5.md's second risk is exactly that — *they name an origin and
	// thereby authorize a server-side request to it; if the page does not make that
	// consequence plain, the setting reads like a URL field*.
	//
	// It rides on the view rather than being derived from the name, because the
	// declaration is the manifest's and the page must not be guessing which of an
	// add-on's fields is the dangerous one.
	Origin bool `json:"origin,omitempty"`

	// SignIn marks the one setting on this page the host declares rather than the
	// add-on: the operator's consent to that add-on's link appearing on the
	// sign-in page (M69.5). The page renders it differently for the reason
	// [SettingView.Origin] does — turning it on changes what every visitor to this
	// instance sees before they have authenticated, which is not a consequence a
	// bare checkbox conveys.
	SignIn bool `json:"sign_in,omitempty"`
}

type SignInLink struct {
	Addon string
	Label string
	Href  string
}

type URLInstallRequest struct {
	// URL is the bundle's address. https only, checked by the same
	// [checkFetchRequest] an add-on's own fetch passes through.
	URL string
	// SHA256 is what the fetched bundle must hash to, lowercase hex, supplied by
	// the operator and never read out of anything this host fetched.
	SHA256 string
}