httpapi

type Authenticator interface {
	// AuthenticateRequest returns the principal the request's verified
	// credentials name. It never reads a tenant from the body, query or path.
	AuthenticateRequest(ctx context.Context, r *http.Request) (identity.Principal, error)
}

type Authorizer interface {
	// AuthorizeSessionList covers the tenant-scoped session list.
	AuthorizeSessionList(ctx context.Context, principal identity.Principal) error

	// AuthorizeSessionRead covers status, journal and gate reads.
	AuthorizeSessionRead(ctx context.Context, principal identity.Principal, session sessionwire.SessionID) error

	// AuthorizeObjectRead covers a session-scoped object body.
	AuthorizeObjectRead(ctx context.Context, principal identity.Principal, session sessionwire.SessionID, object sessionwire.ObjectReference) error

	// AuthorizeControl covers create, input, interrupt, restore and gate
	// response. Its signature is identical to the ClientLink authorizer's
	// because §8.1 makes the REST control routes and the ClientLink RPCs
	// alternatives obeying one admission contract, so one implementation
	// answers both.
	AuthorizeControl(ctx context.Context, principal identity.Principal, session sessionwire.SessionID, kind sessionstore.CommandKind) error
}

type CommandDelivery interface {
	Deliver(ctx context.Context, tenant sessionwire.TenantID, session sessionwire.SessionID, delivery sessionwire.HostLinkCommandDelivery) error
}

type ControlAdmitter interface {
	AdmitCreate(ctx context.Context, principal identity.Principal, req sessionwire.CreateRequest) (sessionstore.DispositionInboxEntry, bool, error)
	AdmitInput(ctx context.Context, principal identity.Principal, req sessionwire.InputRequest) (sessionstore.DispositionInboxEntry, bool, error)
	AdmitInterrupt(ctx context.Context, principal identity.Principal, req sessionwire.InterruptRequest) (sessionstore.DispositionInboxEntry, bool, error)
	AdmitRestore(ctx context.Context, principal identity.Principal, req sessionwire.RestoreRequest) (sessionstore.DispositionInboxEntry, bool, error)
	AdmitGateResponse(ctx context.Context, principal identity.Principal, req sessionwire.GateResponseRequest) (sessionstore.DispositionInboxEntry, bool, error)
}

type Directory interface {
	// Candidates returns one bounded page of the Hosts currently offering
	// capacity for one launch target, most free capacity first. A target
	// nothing advertises is an empty page rather than an error.
	//
	// # The error contract, which is part of the signature
	//
	// A failure that came from SessionStore must leave a
	// *sessionstore.HostTargetError reachable by errors.As. This package reads
	// the code to decide whether the condition is the deployment's -- a
	// backend outage is a retryable 503 -- or a fault in Factory's own
	// request, and anything it cannot classify is answered as an internal
	// fault by DEFAULT, because advertising an unknown condition as retryable
	// would tell every client to hammer it.
	//
	// The consequence for an implementer is the one that is easy to get wrong:
	// an adapter that wraps the store's error in a type of its own WITHOUT
	// keeping the original unwrappable turns every directory outage into
	// internal_error, silently, and no test in this package would see it --
	// the fake returns store errors directly. Wrap with %w or return the
	// store's error.
	Candidates(ctx context.Context, req sessionstore.ListCompatibleHostsRequest) (sessionstore.HostTargetPage, error)
}

type GateOwners interface {
	GateResponsesAnswerable(ctx context.Context, tenant sessionwire.TenantID, session sessionwire.SessionID, record sessionstore.CatalogRecord) (bool, error)
}

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

type GuardConfig struct {
	// CSRF is the composed origin and CSRF configuration. It is validated
	// again here rather than assumed: a Guard built from an unvalidated
	// configuration is a guard with no trusted origins, which fails closed but
	// fails at every request rather than at composition.
	CSRF identity.CSRFConfig

	// Credentials answers which credential a request presents. It is the
	// concrete Authenticator rather than an interface, because the answer must
	// come from the one implementation of the precedence rule and a seam here
	// would be a second place to state it; see internalidentity.Authenticator's
	// CredentialSource.
	Credentials *internalidentity.Authenticator

	// Clock decides token expiry.
	Clock internalidentity.Clock
}

type IDSource interface {
	NewUUID() (string, error)
}

type LaunchTemplate struct {
	// Key is the launch target's identity: the triple SessionStore files an
	// advertisement under, so a configured template and an advertised one are
	// the same value rather than two spellings of one.
	Key sessionstore.HostTargetKey

	// Capabilities are the presentation strings this deployment publishes for
	// the agent. They are optional, and Core omits an empty list.
	Capabilities []string
}

type ObjectLimits struct{ MaxPageBytes, MaxVerificationBytes uint64 }

type ObjectPolicy interface {
	AuthorizeReference(context.Context, identity.Principal, sessionstore.CatalogEntry, sessionwire.ObjectReference) (sessionstore.ObjectKind, error)
}

type ObjectReader interface {
	GetObjectMetadata(context.Context, sessionstore.GetObjectMetadataRequest) (sessionwire.ObjectMetadata, error)
	GetObject(context.Context, sessionstore.GetObjectRequest) (io.ReadCloser, error)
}

type Reason string

type RouteLimits struct {
	// MaxRequestBytes is the inclusive ceiling on a request body, applied while
	// READING rather than by trusting Content-Length.
	MaxRequestBytes int64

	// RequestTimeout bounds the work a handler may do, as a deadline on the
	// request's context.
	//
	// It is a deadline and not a response guillotine, and the difference is
	// worth stating because it bounds the claim. Every dependency call this
	// package makes takes the context, so the deadline is what actually stops
	// the work; a guillotine that raced a handler already writing bytes could
	// not produce a JSON envelope, which is the property step 2 asks for.
	// Bounding the SOCKET -- a peer that never finishes sending a header, or
	// never reads a response -- is http.Server's ReadHeaderTimeout and
	// WriteTimeout, and belongs to the task that builds the server (A9.1).
	RequestTimeout time.Duration
}

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

type RouterConfig struct {
	// Credentials authenticates a request and derives its operation context.
	//
	// It is the CONCRETE authenticator rather than the Authenticator interface
	// this package declares, for the reason GuardConfig.Credentials is: the
	// operation context must record which credential authenticated the
	// request, NewOperationContext is a method so that answer comes from the
	// same derivation the authentication used, and a seam here would be a
	// second place for an edge to state it wrongly. A wrong answer there is a
	// CSRF guard that skips, silently.
	Credentials *internalidentity.Authenticator

	// Authorizer decides every public operation.
	Authorizer Authorizer

	// Reads is the durable read plane.
	Reads SessionReader
	// ObjectPolicy proves committed-reference permission; nil fails closed.
	ObjectPolicy ObjectPolicy
	// ResolveObjectStore consumes the full immutable catalog pin, including
	// RuntimeSessionID and ProtocolMode, and must refuse unknown configurations.
	// Reads stay in canonical authenticated tenant/session scope. Any runtime
	// namespace translation belongs to the resolved adapter, never this handler.
	// Production resolver/public server composition remains A9's obligation.
	ResolveObjectStore func(context.Context, sessionstore.SessionBinding) (ObjectReader, error)
	ObjectLimits       ObjectLimits

	// Directory is the observed Host target directory, read by /v1/agents to
	// learn which configured launch targets are currently advertised.
	Directory Directory

	// Admissions is the durable command plane the control routes admit into.
	//
	// A nil Admissions FAILS CLOSED rather than being rejected by NewRouter,
	// and that is ObjectPolicy's rule for ObjectPolicy's reason: a deployment
	// composed for durable reading alone -- which is what factory.New builds
	// today, and every test of the read plane -- is a supported composition,
	// and requiring a command plane it never calls would make the read surface
	// unbuildable. A control request against such a composition is answered
	// 503 unavailable, which says the deployment cannot carry it out now
	// rather than that the caller's command was refused.
	Admissions ControlAdmitter

	// GateOwners overlays the gates read's answerability with the gate
	// response write path's own owner check (see serveSessionGates). nil
	// leaves every stored answerability as it is; the composition always
	// supplies the admission service.
	GateOwners GateOwners

	// Realtime is the optional ClientLink entry point mounted at /v1/realtime.
	//
	// A nil Realtime FAILS CLOSED rather than being rejected by NewRouter, for
	// Admissions' reason and with Admissions' answer: a deployment composed
	// for durable reading alone is supported, and a realtime request against
	// one is answered 503 unavailable -- the deployment cannot carry it out
	// now, rather than the route not existing.
	//
	// It is a SUPPLIER and not a handler because the two halves have different
	// lifetimes. The router is built by factory.New and the ClientLink node is
	// RUN by factory.Server.Start -- clientlink.NewHandler runs it before it
	// returns, deliberately, so a composition cannot succeed and then refuse
	// every connection -- so a handler field would force New to acquire a
	// lifetime. A supplier answering nil until Start has run gives the same
	// 503, from the same line, with no second code path.
	Realtime func() http.Handler

	// Delivery is the optional local wake-up for an already admitted command.
	//
	// Nil means no attempt is made, which changes NO response: the durable
	// record is the acknowledgement and delivery is best effort either way.
	// An attempt runs AFTER the answer, off the request, and is owned by the
	// router until StopWakes. See Router.deliverAdmitted and wakes.
	Delivery CommandDelivery

	// Logger receives what the router recovers from and has no response to
	// carry it in: today, a delivery seam that panicked inside a wake. Nil
	// takes slog.Default.
	Logger *slog.Logger

	// Department is the launch targets this deployment is configured to offer.
	//
	// It may be EMPTY, and an empty Department is a supported composition
	// rather than a degenerate one: a Factory serving an existing tenant's
	// durable session history needs no launchable agent at all. It answers
	// /v1/agents with an empty list, which is the truthful answer.
	//
	// Every entry is validated by NewRouter. See LaunchTemplate for why the
	// deployment supplies these at all, and Router.serveAgents for why the
	// aggregate they produce is not tenant-scoped.
	Department []LaunchTemplate

	// Guard is the origin and CSRF guard, mounted around the mux and inside
	// authentication; see Guard's own documentation for both reasons.
	Guard *Guard

	// IDs mints the per-request identifier.
	IDs IDSource

	// UI is the optional single-page application. It is served only OUTSIDE
	// the API version segment; see Router.ServeHTTP.
	//
	// # What the router sets on its responses, and what it does not
	//
	// The router sets X-Content-Type-Options, Referrer-Policy and
	// X-Frame-Options before this handler runs, so a bundle server that sets
	// none of them is still covered. It does NOT set a
	// Content-Security-Policy: the API's is default-src 'none', which would
	// forbid a document its own scripts and styles, and there is no policy
	// this package can write for a bundle it has never seen.
	//
	// So a UI handler owes its own Content-Security-Policy, and this package
	// DECLINES to interpose rather than being unable to.
	//
	// The distinction matters because the earlier wording -- "nothing here can
	// check that" -- is false at the layer that has the reader. ServeHTTP does
	// not hand this handler the raw writer; it wraps it in a recordingWriter,
	// which already implements WriteHeader, so the PRESENCE of a policy this
	// handler set is observable at that seam with machinery that exists today.
	//
	// What no code here can judge is ADEQUACY. A present Content-Security-
	// Policy may be default-src * and worth nothing, and the policy a bundle
	// needs is a fact about the bundle's own scripts, styles, fonts and
	// connect targets -- which this package has never seen. A presence check
	// would therefore fail a correct deployment that sets its policy at the
	// edge, in a meta tag, or on the document alone rather than on every asset,
	// and pass one whose policy is empty of meaning. Refusing at run time is
	// worse still: it turns a header opinion into an outage.
	//
	// Enforcement at COMPOSITION is what would be worth having, and it is not
	// available -- there is nothing to inspect in an http.Handler before it
	// serves. So the obligation is stated here, on the field a composer
	// supplies, which is the earliest place a human reads it.
	//
	// Every header above is a DEFAULT rather than a floor. They are written to
	// the header map before this handler is invoked, and net/http's header map
	// stays mutable until WriteHeader, so a UI that must be embedded in a
	// parent application can Set or Del X-Frame-Options itself.
	UI http.Handler
	// UIRoutes serves application-owned /ui/ paths after authentication,
	// origin/CSRF checks and AuthorizeUIRoute. It does not handle public assets.
	UIRoutes         http.Handler
	AuthorizeUIRoute func(context.Context, identity.Principal, string, string) error

	// Limits bounds bodies and work. Its zero value takes DefaultRouteLimits.
	Limits RouteLimits
}

type SessionReader interface {
	ListSessions(ctx context.Context, req sessionstore.ListSessionsRequest) (sessionstore.SessionPage, error)
	GetCatalogEntry(ctx context.Context, req sessionstore.GetCatalogEntryRequest) (sessionstore.CatalogEntry, error)
	ReadPublicJournal(ctx context.Context, req sessionstore.ReadPublicJournalRequest) (sessionwire.JournalPage, error)
	ReadGates(ctx context.Context, req sessionstore.ReadGatesRequest) (sessionwire.GatePage, error)
	GetObject(ctx context.Context, req sessionstore.GetObjectRequest) (io.ReadCloser, error)
	GetObjectMetadata(ctx context.Context, req sessionstore.GetObjectMetadataRequest) (sessionwire.ObjectMetadata, error)
}