runtime

func ApplyEffectiveConfig ¶

func ApplyEffectiveConfig(
	ec wire.EffectiveConfig,
	enforceHTTPS *bool,
	deps *toolkit.BaseDeps,
	localPaths []toolkit.ProtectedPath,
	normalize toolkit.PathNormalizer,
	banner func(string),
	logger *slog.Logger,
)

ApplyEffectiveConfig folds the hello.ack's effective config into this session's settings. The wire contract requires the config to be applied before the server builds its tool surface, and the call site sits between the handshake and RegisterAll so the tools this session serves are bound by it from the first call.

Narrowing only: the harness can enable a protection this server did not configure — enforce HTTPS, additional protected paths — but never relax one the local policy already set. A harness that could switch local protections off would be a way around the document the operator reviewed.

enforceHTTPS is the server's config field, mutated as well as deps because the guardrail Env closes over it, so the may-run endpoint gets the same answer the URL-shaped tools do. localPaths are the protections the server derived itself; they survive the extension.

Harness-declared protected paths deny both read and write. The wire carries only the paths, not why they are protected, and the server cannot tell a tamper-target (write must be refused) from a secret (read must be refused), so it refuses both rather than guess.

The announced egress proxy (port and executable) is consumed by the egress provisioning, which the server feeds directly — see HarnessEgress.

func AuditDestinationIsDir ¶

func AuditDestinationIsDir(dest string) bool

AuditDestinationIsDir mirrors the audit package's directory detection: an explicit trailing separator, or an existing directory. A directory destination protects every session file and the manifest under it.

func AuditKeyDir ¶

func AuditKeyDir(destination string) string

AuditKeyDir returns the directory to keep the key in, or "" when there is no file destination to protect.

func AutoSealEvidence ¶

func AutoSealEvidence(
	tp policy.TransparencyPolicy,
	session string,
	plans []plan.Document,
	posture []byte,
	sink export.Sink,
	keyFile string,
	logger *slog.Logger,
)

AutoSealEvidence seals a bundle into the evidence directory at session end, adding what only exists live: the full approved plan documents and the closing posture snapshot. It never crashes shutdown — a seal failure or a panic is logged and swallowed, because a missing bundle must not turn a clean exit into a crash the host reads as instability.

func BuildRungs ¶

func BuildRungs(p RungPrimitives) map[string]RungFunc

BuildRungs assembles the rung table. The set is closed and named here; a rung absent from it is refused by the servant as unknown.

func BundleEvidence ¶

func BundleEvidence(
	auditDir, session, recordingDir, outPath, keyFile string,
	extra ...evidence.Source,
) (evidence.Manifest, error)

BundleEvidence gathers a session's evidence from an audit directory — its audit chain, the extracted verdicts, and any recording — plus any extra sources the caller supplies (the full plan documents and closing posture, for an auto-seal), and seals it into a signed (or, without a key, unsigned) archive.

func EgressStatus ¶

func EgressStatus(svc *egress.Service, cfg policy.EgressPolicy) *status.EgressStatus

EgressStatus adapts the service to the status snapshot. A nil service means egress is off, and the status field is omitted rather than reported as zero.

func EvaluatePolicy ¶

func EvaluatePolicy(
	ctx context.Context,
	devicePolicy *policy.Policy,
	reg *signals.Registry,
	envFn func() *signals.Env,
) signals.Decision

EvaluatePolicy reads every signal the policy declares and returns the decision for the startup scope.

Every signal is read live, cache bypassed: an operator running this wants the device as it is now, and a cached answer would be answering a question nobody asked. That makes it slow — seconds, on a device where every probe has to run — which is correct for a diagnostic and is exactly why the request path does not work this way.

envFn builds the evaluation environment over the server's platform probes.

func EvidenceSubdir ¶

func EvidenceSubdir(root, sub string) string

EvidenceSubdir returns a subdirectory of the evidence root, or "" when no evidence directory is configured — which disables persistence rather than failing, since a missing output directory is a configuration choice.

func ExportCredentials ¶

func ExportCredentials() export.Credentials

ExportCredentials reads the destination secrets from the environment, once.

They are never flags (argv is world-readable) and never policy fields (the document is a reviewable, checked-in artifact that the agent can read through the filesystem toolset). The names are fixed by the harness export package (see export.EnvSignedURL), which is what puts them behind both defences: the server withholds them from every child process, and ScrubSecretEnv clears them from this one.

func ExportStatus ¶

func ExportStatus(e policy.ExportPolicy, sink export.Sink) *status.ExportStatus

ExportStatus renders the export tier for the status snapshot, or nil when no bundle leaves this device.

Nil for a configured-but-unbuildable destination too, and that is the honest answer: the operator asked for export, it is not running, and reporting the provider name here would let a watcher read intent as posture. The audit chain carries the export.disabled entry that says why.

func GuardrailPaths ¶

func GuardrailPaths(cfg GuardrailPathsConfig, p *policy.Policy) []toolkit.ProtectedPath

GuardrailPaths lists the guardrail files the file tool must not touch: the credentials file (no read — a read is plaintext into the model's context — and no write), the audit log (no write), and the policy document (no write). Reading the audit log or the policy is allowed; both are meant to be inspected.

func HarnessAddress ¶

func HarnessAddress() (pipe, token string)

HarnessAddress reads the bootstrap contract from the environment. The empty string means no harness is present and the server runs standalone.

func HeartbeatFromAck ¶

func HeartbeatFromAck(ack wire.HelloAck) time.Duration

HeartbeatFromAck resolves the heartbeat cadence, defaulting when the harness leaves it unset.

func JourneyStatusMessage ¶

func JourneyStatusMessage(passed bool, failed int, missing []string) string

JourneyStatusMessage renders the run span's status description.

func KillPolicyConfig ¶

func KillPolicyConfig(devicePolicy *policy.Policy) contain.KillActionConfig

KillPolicyConfig maps the policy's containment actions to the executor's config.

func LoadPolicy ¶

func LoadPolicy(path string, reg *signals.Registry, logger *slog.Logger) (*policy.Policy, error)

LoadPolicy resolves the active device policy.

With no document the embedded default applies: the engine is present, every declared signal is evaluated and every verdict recorded, but nothing is refused. That is deliberate — an engine that arrived enforcing would start refusing tool calls on devices that worked the day before, with no operator action and no document to point at.

A named policy that fails to load is fatal. Falling back to the default would silently run a device under weaker policy than its operator wrote, which is the worst of the available outcomes.

func NewGuardrailRegistry ¶

func NewGuardrailRegistry(env EnvNames, logger *slog.Logger) *signals.Registry

NewGuardrailRegistry builds the signal registry: the tier-1 local checks, the just-in-time at-source device-posture checks, and — when the credentials are present in the environment — the authoritative tier-2 Graph and remote-policy providers.

Registering a signal only makes it available for a policy to declare. Nothing here decides whether it is evaluated; that is the policy's job.

func NewLogger ¶

func NewLogger(logFile string) (*slog.Logger, func(), error)

NewLogger returns a structured logger writing to logFile (debug level) or, if empty, to stderr (info level). stdout is never used, so it stays clean for the MCP stdio transport.

func ProvisionEgress ¶

func ProvisionEgress(
	ctx context.Context,
	devicePolicy *policy.Policy,
	auditLog *audit.AuditLog,
	logger *slog.Logger,
	harnessProxy HarnessEgress,
	enforcer egress.Enforcer,
) (*egress.Service, func(), func(), error)

ProvisionEgress starts the device egress proxy when the policy asks for it, and returns a cleanup that runs exactly once however the session ends.

It mirrors credential provisioning: two independent paths reach the teardown — the normal-exit defer and the kill executor's Finalize — and both must be safe to call, in either order.

When the harness announced a proxy, the local listener is skipped — that is the only thing skipped. Recovery still runs (rules outlive processes), the elevation refusal still applies, and OS enforcement still installs, pointed at the harness's port with the allow rule naming the harness executable. Fail-closed holds across a harness death: the firewall stands while the proxy dies, so traffic is cut rather than freed.

enforcer is the platform firewall enforcer (the harness supplies a no-op stub where none exists); it is injected rather than constructed here so each server plugs in its own.

func ProvisionExport ¶

func ProvisionExport(
	devicePolicy *policy.Policy,
	auditLog *audit.AuditLog,
	logger *slog.Logger,
) export.Sink

ProvisionExport builds the evidence-export sink for a configured destination and records the intent in the audit chain.

It returns a nil sink when export is off, so the caller does not special-case it — export.Ship is never reached with a nil sink because autoSealEvidence checks first.

A construction failure disables export with a warning rather than failing startup, the same contract as telemetry and anchoring: transparency is always on, but it never gates the session. The distinction from egress enforcement is deliberate — a policy that names applications and cannot elevate is serving a weaker posture than it describes, where an export that cannot start leaves the evidence exactly where it already was, on the device.

It must be called before ScrubSecretEnv: the credentials are read here, once, into the sink that uses them.

func ReceivingChain ¶

func ReceivingChain(
	harnessEnforcing bool,
	auditMW mcp.Middleware,
	telemetryMW mcp.Middleware,
	rugpullMWs []mcp.Middleware,
	enforceMW mcp.Middleware,
) []mcp.Middleware

ReceivingChain assembles RunStdio's receiving-middleware chain, outermost first, from the already-constructed layers. It exists as a seam so the one mode-dependent decision — how much of the local guardrail stack runs — is pinned by tests rather than buried in RunStdio.

Standalone (or under an observe-mode harness), the full stack runs: audit → telemetry (when configured) → the rug-pull layers → enforce, enforce innermost so nothing routes around it while audit and rug-pull still observe what it refuses.

Under an enforcing harness only the audit layer remains. The harness's decider already refused anything refusable before this process saw the frame, its own chain audits and fingerprints the wire, and running the local duplicates would double-decide every call — but the local audit middleware stays, because this host's chain is the record of what the process actually served, kept precisely so the harness's account of the session is not the only one.

func ReconcileEvidence ¶

func ReconcileEvidence(expected []string, artifacts []toolkit.EvidenceArtifact) (captured, missing []string)

ReconcileEvidence compares what the journey said a passing run must produce against what it actually captured.

func ResolveAuditKey ¶

func ResolveAuditKey(env EnvNames, destination string, logger *slog.Logger) []byte

ResolveAuditKey returns the key the audit chain is written under.

The operator's environment variable (EnvNames.AuditKey) wins when set: a key supplied out of band is the only arrangement that survives an attacker with write access to the box, because a key stored next to the log is readable by anyone who can rewrite the log. Absent that, a key is generated on first use and persisted with restrictive permissions.

A stderr destination gets no key: there is no file to protect, and nowhere beside it to keep one.

func ResolveStatusToken ¶

func ResolveStatusToken(t policy.TransparencyPolicy, logger *slog.Logger) (string, error)

ResolveStatusToken produces the bearer credential for the status endpoint, preferring the environment variable over the inline value.

The endpoint's POST /revoke trips the kill switch and runs the whole containment ladder, so this is a trigger credential. Every other one -- <PREFIX>AUDIT_KEY, _APPROVAL_KEY, _GRAPH_CLIENT_SECRET, _REMOTE_POLICY_TOKEN -- is read from the environment, and egress even takes the name of a variable rather than a value, on the stated grounds that the document is meant to be reviewable and checked in.

status_token was the exception: an inline secret in a document that is registered as an agent-readable protected path, and that the shell toolset reaches with no protected-path check at all. An agent served either toolset could read it and actuate containment -- the escalation the per-session sentinel token was introduced to close, and the reason the agent-facing Kill tool routes to StopGracefully rather than the ladder.

The inline form still works, because removing a schema key breaks documents that run today and unknown keys are rejected outright. It warns instead.

func RugpullVerifier ¶

func RugpullVerifier(rp *watch.RugPull, tools func() []*mcp.Tool, trip func(string)) watch.VerifyFunc

RugpullVerifier is the in-flight monitor's local rug-pull recheck. It is installed only alongside a pinned local baseline: under an enforcing harness there is none, because the fingerprints are taken from the wire where a tampered server cannot vouch for itself.

func ScrubSecretEnv ¶

func ScrubSecretEnv(env EnvNames, devicePolicy *policy.Policy, logger *slog.Logger)

ScrubSecretEnv removes the startup secrets from this process's environment, once every component that needs them holds its own copy.

It is the second of two defences, and it exists because the first cannot be complete. The server's process runner withholds every prefixed variable when it builds a child environment — but any future code path that spawns a process without going through it would inherit the parent environment as it stands. Clearing the values here means there is nothing left to inherit, whatever route a child is started by.

It also covers the two variables the prefix rule cannot know about: the egress proxy's shared secret and the status endpoint's bearer token are named *by the policy document*, so their variables can be called anything at all.

Order matters. Call this only after the audit log, the approvals client, the signal registry, the telemetry exporter and the egress proxy have been constructed; each reads its secret exactly once, at startup, into the struct that uses it.

func SentinelToken ¶

func SentinelToken(controlDir string, auditLog *audit.AuditLog, logger *slog.Logger) string

SentinelToken mints the token a kill sentinel must carry, and tells the operator what it is.

The sentinel used to be authenticated by its own existence: any file named "kill" in the control directory tripped the containment ladder. That made it the one authoritative trigger an agent could fire by itself — a single FileSystem write, or any shell redirect, and a policy with isolate or shutdown armed did exactly that. It is the escalation the design is explicit that an agent must never be able to ask for, since the agent-facing Kill tool is deliberately routed away from containment for the same reason.

The token is minted per session and written nowhere: it goes to the log and the audit chain, both of which the operator reads and neither of which the agent can write. Putting it in a file beside the sentinel would hand it back to anything that can read the control directory, which is the position the agent is in.

An empty control directory means the trigger is not configured, so there is nothing to authenticate.

func SessionStamp ¶

func SessionStamp() string

SessionStamp mints the one stamp a session's audit file, recording and evidence bundle correlate by name.

func SnapshotFn ¶

func SnapshotFn(
	startedAt time.Time,
	rp *watch.RugPull,
	hb *watch.Heartbeat,
	auditLog *audit.AuditLog,
	kill *contain.KillSwitch,
	egressSvc *egress.Service,
	egressCfg policy.EgressPolicy,
	exportSt *status.ExportStatus,
) status.SnapshotProvider

SnapshotFn builds the always-on server-status snapshot provider.

func TripFunc ¶

func TripFunc(
	trigger string,
	armed bool,
	kill *contain.KillSwitch,
	auditLog *audit.AuditLog,
	logger *slog.Logger,
) func(string)

TripFunc returns the trip function for one kill trigger. When the trigger is armed it is the switch's Trip, which runs the full containment ladder. Otherwise it is report-only: the event is still audited and logged, because transparency must not be conditional on containment — the operator sees that a trigger fired even when they chose not to act on it.

func ValidatePolicy ¶

func ValidatePolicy(path string, reg *signals.Registry) (*policy.Policy, error)

ValidatePolicy loads and validates a policy document against the signals the registry knows.

It touches no device: validation is about the document and the set of signals this build can evaluate, so it runs anywhere, including in CI on a machine with no secure enclave and no domain.

func VerifyEvidence ¶

func VerifyEvidence(zipPath, pubKeyHex string) (evidence.Report, error)

VerifyEvidence checks a bundle against its manifest and, when given, an expected public key.

func WarnExportEgress ¶

func WarnExportEgress(devicePolicy *policy.Policy, logger *slog.Logger)

warnExportEgress reports the one contradiction the policy loader cannot settle on its own.

When egress is enabled the device may only reach the hosts egress.allow names, and a signed_url destination lives entirely in an environment variable — so there is no host in the document to check it against. Worse, the export runs from the audit-close defer, which is *after* the egress cleanup defer has already stopped the proxy, so the upload cannot be routed through it either. Under scoped or global enforcement the server's own image needs an outbound allow rule or the bundle never leaves.

Said out loud rather than left to be discovered during a shutdown nobody is watching, and warned rather than refused, because the combination is legitimate.

func WithToolset ¶

func WithToolset(toolsets []string, id string) []string

WithToolset adds id to a toolset selection. A nil selection means "the default set", so it is made explicit as "default" plus id rather than collapsing to id alone, which would silently drop every default toolset.

func WriteRunRecord ¶

func WriteRunRecord(dir, name, session string, rec *runrecord.Recorder) (string, error)

WriteRunRecord serialises the trace next to the session's other evidence. Failing to write it never fails the run: the journey's verdict is already on the audit chain, and losing the richer record is not a reason to report a passing suite as broken.