console

type Approval struct {
	Approved bool
	// Auto is never set: auto mode is gone.
	//
	// Deprecated: it goes in the next minor release.
	Auto bool
	// Retype: the human typed Screen.Retype.
	Retype bool
	// Refusal is the answer to send when neither Approved nor Retype: the
	// human denied (with the reason they typed after "n"), the approval
	// timed out, the client left, or no finger matched. For a Pending
	// request it is the pending answer (PendingResp).
	Refusal ipc.Response
	// Pending: an AsyncApprover took the request; it is decided elsewhere.
	Pending *Pending
}

type Approver interface {
	Approve(ctx context.Context, d Decision) Result
	// Mode is the audit value: "session" or "desktop+fingerprint".
	Mode() string
}

type Ask struct {
	// Frame is the colour of the screen's frame.
	Frame string
	// Production asks for the profile name typed instead of "y".
	Production bool
	// Retype, when set, is an answer that asks to retype values; Ask then
	// returns Approval.Retype. RetypeNote follows it in the prompt:
	// "(<Retype> to retype<RetypeNote>) ". An answer equal to the approval
	// answer is not offered.
	Retype, RetypeNote string
	// For names the decision in the fingerprint prompt (Decision.For); ""
	// is "to approve the request above".
	For string
	// Screen is the approval screen (Decision.Screen).
	Screen *Screen
}

type Asker struct {
	IO       IO
	Approver Approver
	// Profile is the profile name, typed to approve on production.
	Profile string
	// Lock names the product in a pending answer (kit.Product.Name).
	Lock string
	// End ends the session (too many non-matching fingers); nil: ignored.
	End func(reason string)
	// Waiting, when set, is told when a decision starts (true) and ends
	// (false) waiting for the human.
	Waiting func(on bool)
}

type AsyncApprover interface {
	Approver
	// Submit hands d over. Pending.Ticket is set even when err is not nil
	// (the hub refused it or is unreachable): the request stays pending,
	// is never asked on the terminal instead, and the approver pushes the
	// ticket again.
	Submit(ctx context.Context, d Decision) (Pending, error)
}

type Backend interface {
	// Methods are the product's IPC methods, beyond the console's own
	// (hello, status, change.request, logout). A name the console serves
	// is refused at start.
	Methods() map[string]Handler
	// Connect opens a session with the credentials the console obtained
	// (asked, from the OS keychain, or from Vault) to the policy in force
	// (c.Policy). It is called at start and again after a lost connection
	// or an expired login. The console wipes c.Secret once Connect returns.
	// The session handed back to the backend (Env.Session, Checks) may be
	// wrapped: Unwrap returns the backend's own.
	Connect(ctx context.Context, c Credentials) (Session, error)
	// Checks audits a new session: what the backend account can do beyond
	// the profile (a red warning, typed "continue" to go on), or a reason
	// to refuse it. On a production profile every finding refuses.
	Checks(ctx context.Context, s Session) []Finding
	// LoadPolicy reads the current policy from the config files. The
	// console calls it at start and every PolicyPoll.
	LoadPolicy() (Policy, error)
	// Status is the product's part of the status method's answer.
	Status(s Session) any
}

type Beller interface {
	Bell()
}

type ChangeFormatter interface {
	FormatChanges(changes []config.Change) []string
}

type ConnectionComparer interface {
	ConnectionChanged(old, next Policy) bool
}

type Credentials struct {
	User string
	// Secret is nil for a profile with credentials "none".
	Secret []byte
	// Policy is the approved policy in force, the one to connect to: a
	// backend reads its endpoint from it, never from the config files (an
	// unconfirmed edit). Reconnections pass the policy in force then. Nil
	// when the console that calls Connect has none (a product's own tests).
	Policy Policy
}

type Decision struct {
	// Prompt is the typed prompt, already framed by the caller.
	Prompt string
	// Expected is the typed answer: "y" (any case) or the production
	// profile name (exact).
	Expected string
	// Production selects the exact match.
	Production bool
	// Retype is the typed answer that asks to retype placeholders ("" when
	// not offered).
	Retype string
	// For names the decision in the fingerprint prompt ("to approve the
	// request"): a finger is never offered without saying what it decides.
	For string
	// Screen is the approval screen the decision is about (nil for the
	// console's own decisions). A terminal approver ignores it: the screen
	// is already on the terminal; an AsyncApprover sends it on.
	Screen *Screen
}

type EndError struct {
	Reason string
	Err    error
}

type Env interface {
	// Approve shows s and hands it to the approver: under Run, lockhub
	// decides (the answer is Pending). The decision is audited before
	// Approve returns.
	Approve(ctx context.Context, id int64, s Screen) Approval
	// Auto is always false: auto mode is gone, lockhub decides.
	//
	// Deprecated: it goes in the next minor release.
	Auto() bool
	// ShowResults reports the clear results switch (Ctrl-O).
	ShowResults() bool
	// UnmaskAllowed reports whether clients may ask for unmasked output
	// (:unmask), each such request approved by the human.
	UnmaskAllowed() bool
	// Session returns the live session, reconnecting first when the login
	// expired (credentials_ttl, a Vault lease) or the connection was lost
	// (Lost).
	Session(ctx context.Context) (Session, error)
	// Lost drops the session after a lost connection: the next Session
	// reconnects.
	Lost()
	// Policy is the approved policy in force.
	Policy() Policy
	// Audit writes rec as is; AuditBase stamps b with the profile and the
	// client behind ctx first.
	Audit(rec audit.Record)
	AuditBase(ctx context.Context, b audit.Base)
	// Println writes one console line; Safe escapes client text for it.
	Println(line string)
	Safe(s string) string
	// Sanitizer scrubs error text for a client or the audit log.
	Sanitizer() *sanitize.Sanitizer
	// Level levels a response time (Options.Quantum) from start.
	Level(ctx context.Context, start time.Time)
	// End ends the session after the current request.
	End(reason string)
}

type Finding struct {
	// Refuse stops the console (or the reconnection) whatever the profile.
	Refuse bool
	Text   string
}

type Handler func(ctx context.Context, req ipc.Request, env Env) ipc.Response

type Hub struct {
	Client   *hubclient.Client
	Store    *plans.Store
	Instance string
	// contains filtered or unexported fields
}

type HubOptions struct {
	// URL is the hub's base URL ("http://lockhub:8443").
	URL string
	// KeyFile holds the pinned hub key (hubclient.ReadHubKey).
	KeyFile string
	// Instance is the lock instance's name (hubclient.ValidInstance).
	Instance string
	// PlainHTTP lets URL be http:// to a hub on a network of its own
	// (--hub-plain-http, hubclient.Config.PlainHTTP).
	PlainHTTP bool
	// DevicesFile holds the approval devices this lock pins
	// (--devices-file, hubclient.ReadDevices): decisions taken on a device
	// must carry its signature, and the clear screen is sealed to each.
	DevicesFile string
	// RequireDevice lists the risk classes whose approvals must be signed
	// by a pinned device (--require-device, comma-separated).
	RequireDevice string
	// SealClear seals the clear screen to the pinned devices
	// (--seal-clear, hubclient.Config.SealClear).
	SealClear bool
	// FacadeKeysFile holds the facade keys this lock pins
	// (--facade-keys-file, hubclient.ReadFacades): a reveal (Ctrl-O on a
	// local facade) is sealed only to a key one of them signed.
	FacadeKeysFile string
	// Home is the lock's home volume, where the instance key lives
	// (hubclient.InstanceKey, made by `hub-key`); "" is the user's home.
	Home string
}

type HubTicket struct {
	// PlanID is the plan in Hub.Store, made by Caller.
	PlanID string
	Caller plans.Caller
	Risk   ticket.Risk
	// Masked is the screen as it leaves the lock (render.MaskScreen).
	Masked render.MaskedScreen
	// Requester and Workspace are shown by the hub (display only).
	Requester ticket.Requester
	Workspace string
}

type IO interface {
	Println(s string)
	// Ask prints prompt and reads one line. It returns false when no answer
	// came within timeout, when ctx ended (Ctrl-C, client gone) or when the
	// terminal is closed.
	Ask(ctx context.Context, prompt string, timeout time.Duration) (string, bool)
	// AskSecret reads a line with echo off.
	AskSecret(ctx context.Context, prompt string) ([]byte, error)
}

type Isolation struct {
	Product kit.Product
	Sys     *sysconf.Config
	Display sysconf.Display
	Self    int
	GID     int
	// Desktop is the desktop shape; Verifier is then its fingerprint
	// reader (nil at level 1 and in the session shape).
	Desktop  bool
	Verifier fingerprint.Verifier
	// contains filtered or unexported fields
}

type IsolationEnv struct {
	LoadSys       func() (*sysconf.Config, error)
	Display       func() sysconf.Display
	UID           func() int
	UserName      func() (string, error)
	LoginUID      func() (int, bool)
	TerminalOwner func() (int, bool)
	ClientAllowed func(sys *sysconf.Config, uid int) bool
	ClientGID     func(sys *sysconf.Config) (int, error)
	// AccountExists reports whether uid names an account.
	AccountExists func(uid int) bool
	// Relay reports a session opened through a relay (sysconf.SessionRelay).
	Relay func() string
	// MachinectlUIDs lists the callers of running `machinectl shell`
	// processes (sysconf.MachinectlShellUIDs).
	MachinectlUIDs func() ([]int, bool)
	// DesktopEnv reports <PREFIX>DESKTOP=1: the desktop shape is asked for.
	DesktopEnv func() bool
	// DisplaySet reports a non-empty DISPLAY.
	DisplaySet func() bool
	// ParentChain lists the ancestors of the process, from the parent up
	// (sysconf.ParentChain).
	ParentChain func() ([]sysconf.Proc, error)
	// NewVerifier opens the fingerprint reader of user.
	NewVerifier func(user string) (fingerprint.Verifier, error)
	// EnrolledTimeout bounds the start-up question to fprintd; past it, the
	// reader counts as unavailable. 0 is 10s.
	EnrolledTimeout time.Duration
	// AllowSameUser lets the console run without a separated setup, in the
	// agent's account. Only a product's test build sets it (a build tag):
	// no config file, flag, environment variable or client may.
	AllowSameUser bool
}

type Key int

type KeySource interface {
	Keys() <-chan Key
	SetKeyHandler(func(Key))
}

type LineSource interface {
	Lines() <-chan string
}

type Loop struct {
	IO IO
	// Handle serves one request (required).
	Handle func(ctx context.Context, req ipc.Request) ipc.Response
	// Command runs a line typed by the human between requests.
	Command func(ctx context.Context, line string)
	// Key handles a control key pressed between prompts; with a KeySource
	// IO it also handles the keys pressed during a prompt.
	Key func(Key)
	// Tick runs every second (session timeouts).
	Tick func()
	// Poll runs every PolicyPoll (config file changes).
	Poll func()
	// Ended reports the end of the session (required); End ends it.
	Ended func() bool
	End   func(reason string)
	// Refresh runs after every event (the status row); Clear on return.
	Refresh func()
	Clear   func()
	// PeerAllowed decides which clients are served, from the kernel's
	// credentials of the peer. Nil serves the console's own account only.
	PeerAllowed func(ipc.Cred) bool
}

type Options struct {
	// Profile is the profile to serve; ProjectRoot the project whose
	// config holds it ("" for the user config).
	Profile     string
	ProjectRoot string
	IO          IO
	// AllowUnmask and ShowResults are the start-up switches (both refused
	// at level 2; ShowResults refused at level 1 too).
	AllowUnmask, ShowResults bool
	// Auto is refused: auto mode is gone, lockhub decides every request.
	//
	// Deprecated: kept so that products still setting it build; Run
	// refuses it. It goes in the next minor release.
	Auto bool
	// StateDir is the state base (kit.StateBase() when empty).
	StateDir string
	// TTY is the console's terminal device (nil when unknown).
	TTY *os.File
	// Now defaults to time.Now.
	Now func() time.Time
	// Quantum levels response times (Env.Level): 0 is ResponseQuantum, a
	// negative value none.
	Quantum time.Duration
	// Sanitizer scrubs error text; nil is sanitize.New().
	Sanitizer *sanitize.Sanitizer
	// Isolation replaces the system the isolation checks read (tests and
	// a product's test build); nil is RealIsolationEnv.
	Isolation *IsolationEnv
	// Harden replaces Harden (tests).
	Harden func() error
	// VaultRead replaces secrets.VaultRead (tests).
	VaultRead func(ctx context.Context, path string) (*secrets.VaultCredentials, error)
	// Keychain replaces the product's OS keychain (tests).
	Keychain *secrets.Keychain
	// Ready, when set, is told the socket path once the console listens.
	Ready func(socket string)
	// Hub decides requests on lockhub (HubOptions): required, Run refuses
	// to start without it (ErrNoHub), unless PolicyOnly.
	Hub HubOptions
	// PolicyOnly runs a console that serves its policy and decides no
	// request: the console of a lock whose requests are decided by another
	// process's hub (lockhttp's, whose gate asks lockhub; `lox up` starts
	// such a console without hub flags). It starts without Hub, which must
	// then be empty (ErrPolicyOnlyHub), and without OnHub; every request a
	// handler hands to Env.Approve is refused (ErrPolicyOnly), never asked
	// here. The console's own decisions (its policy at start and at a
	// loosening, :unmask) are still asked on its terminal.
	PolicyOnly bool
	// OnHub, when set, is called with the console's hub once it is open,
	// before any request is served: where a product registers its
	// hubclient.Recompute (hub.Client.SetRecompute). It runs before the
	// policy review, so Run may still fail and close the hub; Run sets the
	// client's OnRequest itself (Hub.Requests), replacing any set here.
	OnHub func(*Hub)
}

type Outcome int

type PIIBackend interface {
	// PIIRules returns the mask and allow rules of p.
	PIIRules(p Policy) (mask, allow []string)
	// CheckMask validates a pattern sent by a client and returns its
	// canonical form; an error is shown to the client (invalid params).
	CheckMask(pattern string) (string, error)
	// SaveMask adds the canonical pattern to the config file as it is on
	// disk, so the human's unconfirmed edits are neither lost nor applied.
	SaveMask(pattern string) error
	// WithMask returns p with the canonical pattern added (canonical form,
	// sorted lists); p itself is not changed.
	WithMask(p Policy, pattern string) Policy
}

type Pending struct {
	// Ticket is the id the agent presents to run the request once decided.
	Ticket string
	// Instance is the lock instance the ticket is on (hub mode).
	Instance string
}

type Policy interface {
	config.Policy
	Profile() Profile
}

type PolicyApplier interface {
	ApplyPolicy(p Policy) error
}

type Profile struct {
	Name       string
	Production bool
	// Where names the backend for the human (host:port, a path): it is
	// shown escaped.
	Where string
	// Host, Port and DefaultPort name the OS keychain item of the secret
	// ("<profile>@<host>:<port>").
	Host              string
	Port, DefaultPort int
	// User is the backend account; "" asks the human (or comes from Vault).
	User string
	// Credentials is config.CredentialsAsk, CredentialsKeychain,
	// CredentialsVault or CredentialsNone; VaultPath is read for "vault".
	Credentials string
	VaultPath   string
	// CredentialsTTL asks for the secret again (and reconnects) once the
	// connection is that old; 0 keeps it for the session.
	CredentialsTTL time.Duration
	// IdleTimeout ends the session after that long without activity,
	// MaxSession after that long in all. 0 takes 20m and 4h.
	IdleTimeout, MaxSession time.Duration
}

type Result struct {
	Outcome Outcome
	Answer  string
	Err     error
}

type Screen struct {
	// Header follows the profile name on the top line ("db / shop · tier read").
	Header string
	// Requester names the client; "" takes the peer behind the request.
	Requester string
	// Note is the agent's one-line reason (untrusted, escaped, audited).
	Note string
	// Body are the lines of the request; Warnings are shown in red.
	Body     []string
	Warnings []string
	// Production forces the production prompt; the profile's own flag
	// always does.
	Production bool
	// NeverAuto is never approved without a human's own decision on it,
	// by the hub's auto mode or a renewal (an unmasked read, a
	// destructive-looking operation): ticket.Flags.NeverAuto.
	NeverAuto bool
	// Red frames the screen in red outside production too.
	Red bool
	// Retype, when set, is an answer that asks to retype values; Approve
	// then returns Approval.Retype.
	Retype string
	// Record, when set, turns the decision record into the product's own
	// (with its fields); nil writes the audit.Base.
	Record func(audit.Base) audit.Record
	// Hub is the plan and masked screen for the hub, in hub mode
	// (HubOf(env) not nil); a request without one is refused there.
	Hub *HubTicket
}

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

type ServerConfig struct {
	Product kit.Product
	Backend Backend
	// Policy is the approved policy the server enforces.
	Policy Policy
	// StateDir and ApprovedKey locate the approved policy file ("" keeps
	// adoptions in memory).
	StateDir    string
	ApprovedKey string
	Session     Session
	Audit       *audit.Log
	IO          IO
	// Approver takes every human decision; nil means typed approvals.
	Approver Approver
	// Level is the isolation level (2: every decision takes a finger, and
	// a typed answer alone never widens anything).
	Level int
	// Boundary names the desktop boundary for the status screen.
	Boundary string
	Now      func() time.Time
	// AllowUnmask and ShowResults are the switches at start.
	AllowUnmask, ShowResults bool
	// Auto is refused by NewServer: auto mode is gone, lockhub decides.
	//
	// Deprecated: kept so that products still setting it build; it goes
	// in the next minor release.
	Auto bool
	// Reconnect opens a new session (credentials, Connect, Checks) under
	// the profile in force; nil (and ReconnectPolicy nil) means a lost
	// connection ends the console. An EndError it returns ends the session
	// with its reason.
	Reconnect func(ctx context.Context, p Profile) (Session, error)
	// ReconnectPolicy, when set, is used instead of Reconnect and gets the
	// whole policy in force.
	ReconnectPolicy func(ctx context.Context, p Policy) (Session, error)
	// Quantum levels response times (Env.Level).
	Quantum time.Duration
	// PeerAllowed decides which clients are served; nil: the console's own
	// account.
	PeerAllowed func(ipc.Cred) bool
	// Sanitizer scrubs error text; nil is sanitize.New().
	Sanitizer *sanitize.Sanitizer
	// Refused is the fingerprint of a loosening the human refused at start,
	// not announced again until the files change.
	Refused string
	// RefuseProduction re-applies the start-up refusals of a production
	// profile (an X11 session, core dumps that could not be disabled) when
	// the policy in force becomes production; nil refuses nothing.
	RefuseProduction func() error
	// Hub is the console's hub (Run sets it, HubOptions being required);
	// nil for a policy-only console (Options.PolicyOnly) and in tests of
	// the server itself.
	Hub *Hub
}

type Session interface {
	Close() error
}

type Sized interface {
	Width() int
}

type StatusAnswerer interface {
	StatusAnswer(c StatusResult, s Session) any
}

type StatusLine interface {
	SetStatus(string)
}

type StatusLiner interface {
	StatusLineParts(v StatusView) (suffix string, parts []string)
}

type StatusResult struct {
	Profile    string `json:"profile"`
	Production bool   `json:"production"`
	// AutoApprove is always false: auto mode is gone, lockhub decides.
	//
	// Deprecated: kept on the wire for older clients; it goes in the next
	// minor release.
	AutoApprove    bool `json:"auto_approve"`
	AllowUnmask    bool `json:"allow_unmask"`
	ShowResults    bool `json:"show_results"`
	IdleTimeoutInS int  `json:"idle_timeout_in_s"`
	SessionEndsInS int  `json:"session_ends_in_s"`
	// Level is the security level: 0 session shape, 1 or 2 desktop shape.
	Level   int `json:"level"`
	Product any `json:"product,omitempty"`
}

type StatusRower interface {
	StatusRows(v StatusView) [][2]string
}

type StatusView struct {
	// Status is the console's part of the status answer (Product unset:
	// the status row is drawn every second, Backend.Status is not called
	// for it).
	Status StatusResult
	// Profile and Policy are the approved policy in force.
	Profile Profile
	Policy  Policy
	// ShowResults and AllowUnmask are the switches.
	ShowResults, AllowUnmask bool
	// Auto is always false: auto mode is gone, lockhub decides.
	//
	// Deprecated: it goes in the next minor release.
	Auto bool
	// Pending: a loosening awaits :review. Requests counts the change
	// requests queued.
	Pending  bool
	Requests int
	// Boundary names the desktop boundary ("" in the session shape); Level
	// is the security level (2: every decision takes a finger).
	Boundary string
	Level    int
	// Session is the live session, nil while disconnected.
	Session Session
}

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

type Withdrawer interface {
	Withdraw(ctx context.Context, d Decision, ticket, reason string) error
}

type Worder interface {
	Words() Words
}

type Words struct {
	// AutoStart, AutoOn, Manual, NoAutoProduction, NoAutoHub, StatusAuto,
	// StatusManual and ReviewAuto are never printed: auto mode is gone,
	// lockhub decides every request.
	//
	// Deprecated: kept so that products still setting them build; they go
	// in the next minor release.
	AutoStart, AutoOn, Manual, NoAutoProduction, NoAutoHub, StatusAuto, StatusManual, ReviewAuto string
	// ResultsOn is printed when the clear results are switched on;
	// StatusResults is their row of :status when on.
	ResultsOn, StatusResults string
	// UnmaskAsk is the question that allows unmasked output; UnmaskOff is
	// printed when it is turned off.
	UnmaskAsk, UnmaskOff string
	// ChangeQueued words a change request from a client (already escaped).
	ChangeQueued func(change string) string
	// Reconnecting is printed before a reconnection.
	Reconnecting string
	// TTLReached is printed when credentials_ttl ends a connection.
	TTLReached func(ttl time.Duration, credentials string) string
	// ProductionChecks words the end of a session whose checks found
	// something once the profile became production: the console line and
	// the end reason.
	ProductionChecks func(p Profile, findings []Finding) (line, reason string)
	// ConnLost is the error a Handler gets from Env.Session when the
	// connection is lost and cannot be opened again.
	ConnLost string
}