remotefetch

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package remotefetch is the directory tier's outbound client (#71, multi-instance ADR § The outbound client).

It is a NEW OUTBOUND SURFACE ON THE SERVER, and the threat model's amendment enumerates it as one class — configured remote hikyo instances — under the full user-configured-outbound control set. Every exported knob below is one of that set's normative members, and the package exists as its own package so the set is enforced in one place rather than re-derived per caller.

Nothing here runs on a timer: there is deliberately no background poller (the system-architecture ADR fixed no generic job framework, and a standing authenticated heartbeat toward every remote for a health dot nobody is looking at is exactly what that rules out). A directory fetch happens because a holder of instance-directory is looking at the directory. Separately, an authorized administrator creating a pairing invitation can trigger one TLS-only probe of the configured public origin to discover its certificate fingerprint. That probe uses ordinary CA and hostname verification, sends no HTTP request to the origin, and honors the explicit HTTPS CONNECT proxy. Startup, invitation listing and local requester preparation never probe.

Index

Constants

View Source
const (
	// Deadline bounds one remote's entire fetch, connect through body read.
	// Rhymes with row 17's HTTP header/read timeout scale.
	Deadline = 10 * time.Second

	// ResponseCap bounds the bytes read from one remote. Rhymes with row 19's
	// adapter response cap. A directory listing is org and project names and
	// counts; a megabyte is already generous for it, which is the point — the
	// cap exists to bound a hostile or broken peer, not to fit the payload.
	ResponseCap = 1 << 20 // 1 MiB

	// RemoteCount caps configured entries. Ops-catalogue value (multi-instance
	// § "Remote count cap": 25) — twenty-five entries is a fleet, not a
	// rounding error.
	RemoteCount = 25

	// FanOut caps parallel fetches, matching the four-concurrent-per-org
	// pattern in rows 17 and 19. With RemoteCount at 25 this makes a full
	// directory view at most seven sequential rounds of a ten-second deadline
	// in the pathological all-unreachable case.
	FanOut = 4

	// CoalesceWindow is how long concurrent viewers share one in-flight fetch.
	// It exists so a card open on several screens is one connection per remote,
	// not one per human — the per-viewer rate below bounds a single human, and
	// this bounds the crowd.
	CoalesceWindow = 5 * time.Second

	// ViewerTriggerRate bounds how often ONE holder of instance-directory may
	// trigger a fetch round. Human card-refresh scale: six a minute is a person
	// clicking refresh, and anything faster is not a person.
	ViewerTriggerRate = 6 // per minute, per viewer

	// AggregateTriggerRate bounds the WHOLE INSTANCE, and it is the cap that
	// actually protects the fleet. The ADR is explicit that per-viewer limiting
	// alone does not bound many principals: fifty viewers each politely under
	// their own limit is still fifty times the traffic at every remote. Rhymes
	// with row 17's fail-closed default budget.
	AggregateTriggerRate = 60 // per minute, instance-wide

	// WorkspaceSessionIdle and WorkspaceSessionAbsolute are the ratified
	// HARD-SHORT pair (owner, 2026-08-13), deliberately matching ops-spec row
	// 5's reveal window and cap: a workspace is a disclosure surface, and its
	// header-borne bearer is extractable and replayable outside the browser.
	// The shell's liveness poll (currently every 5 seconds) keeps an open tab
	// alive, so idle means the session dies 15 minutes after the tab closes.
	WorkspaceSessionIdle     = 15 * time.Minute
	WorkspaceSessionAbsolute = 4 * time.Hour

	// HandoffExpiry bounds the single-use handoff transaction. Authorization-
	// code analogue, rhyming with row 7. The ADR says "expires in minutes"; ten
	// is the loosest reading of that, chosen because the ceremony inside the
	// popup may include a full OIDC round trip with an unfamiliar IdP.
	HandoffExpiry = 10 * time.Minute
)

The multi-instance ADR's composable-maxima entries (#71, amending the ops spec #32).

RATIFIED by the owner on 2026-08-13. The directory bounds and handoff expiry remain exactly as proposed for #71. The workspace lifetime pair was ratified with the hard-short values below after the ADR's extractable-bearer residual was dispositioned. If a value moves, it moves here and nowhere else.

They are colocated in this package deliberately. Three of them (WorkspaceSessionIdle, WorkspaceSessionAbsolute, HandoffExpiry) are not outbound-client concerns at all and would naturally live beside the workspace service — but they are one ADR's one catalogue addition, and splitting them across packages is how half a table gets ratified and the other half forgotten. One block, one review.

View Source
const (
	MaxOrgs            = 1000
	MaxProjectsPerOrg  = 1000
	MaxListingNameLen  = 200
	MaxIdentityLen     = 128
	MaxVersionStringLn = 64
)

Ingest caps. Foreign bytes are bounded BEFORE they are parsed and again after: ResponseCap bounds the transfer, and these bound the structure, so a peer that answers within a megabyte still cannot hand this instance a hundred thousand org names to hold in memory or render.

Variables

View Source
var ErrPinMismatch = errors.New("remotefetch: server public key does not match the pinned fingerprint")

ErrPinMismatch is the pin failure, surfaced as its own error so the caller can map it to its own outcome rather than parsing a TLS error string.

Functions

func CanonicalRemoteURL

func CanonicalRemoteURL(raw string) (string, error)

CanonicalRemoteURL validates and returns the ONE spelling of a remote origin: scheme://host[:port], with no trailing slash.

`https://peer.example/` and `https://peer.example` are the same origin and a human types either, so both are accepted — but exactly one is stored and used, because the other one concatenates into `https://peer.example//api/v1/ instance/directory`. A double slash is a different path to most routers and an outright 404 to some, so the difference between the two spellings would show up as an unreachable remote with no explanation.

func Dials

func Dials() uint64

Dials returns the number of outbound connections originated since process start. Monotonic, never reset — a test takes a delta.

func EncodePairedCredential

func EncodePairedCredential(token string, key ed25519.PrivateKey) (string, error)

EncodePairedCredential creates a sealed-storage payload, never a wire bearer. Its reserved prefix makes malformed paired state an error instead of fallback.

func SPKIFingerprint

func SPKIFingerprint(cert *x509.Certificate) string

SPKIFingerprint is the pinned value: base64(sha256(SubjectPublicKeyInfo)).

It is over the PUBLIC KEY, not the certificate, so an ordinary certificate renewal that keeps the key does not break a pin and force every viewing instance through the re-add ceremony. This is the same construction the CLI's local trust store uses; one fingerprint spelling for the whole product.

func ValidateRemoteURL

func ValidateRemoteURL(raw string) error

ValidateRemoteURL enforces the ADR's URL grammar: a canonical https origin and nothing else.

The fetch path is appended by the client from the API contract and NEVER from configuration, which is why a path, query or fragment here is an error rather than something to strip: a stored value that carries one was either a mistake or an attempt to steer the request, and silently normalising it would hide both. Userinfo is refused because a credential belongs in the entry's sealed column, not in a URL that appears in logs and audit payloads.

Types

type Attempted

type Attempted struct {
	ID      string
	Listing Listing
	Outcome Outcome
	Err     error
}

Attempted is a target for which Directory was called. Err is diagnostic detail; Outcome is the closed operator-visible result even when Err is nil.

func (*Attempted) TargetID

func (r *Attempted) TargetID() string

type Client

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

Client performs pinned fetches under one Config.

func New

func New(cfg Config) (*Client, error)

New builds a client, refusing an incomplete or unsafe configuration loudly.

func (*Client) Directory

func (c *Client) Directory(ctx context.Context, origin, pin, credential string) (Listing, Outcome, error)

Directory performs one authenticated fetch against one remote.

It returns the outcome ALWAYS — including on success — because the caller writes that outcome to the snapshot either way, and a caller that had to infer "ok" from a nil error would eventually infer it wrongly. The error is the detail for logs; the outcome is the operator-visible state.

Nothing about the response is trusted before it is bounded: the body is read through a limit reader at ResponseCap, parsed, and then length-capped field by field. A peer that overruns any cap is a fetch failure by name, not a silently truncated listing.

func (*Client) FetchAll

func (c *Client) FetchAll(ctx context.Context, targets []Target) []Result

FetchAll runs one fan-out round under the configured cap.

The cap is a semaphore rather than a worker pool because the bound the ADR states is on CONCURRENT CONNECTIONS, not on goroutines: with RemoteCount at 50 and FanOut at 4, a pathological all-unreachable directory is thirteen sequential rounds of the per-remote deadline, which is the arithmetic the bound was chosen for. FetchAll returns exactly one ordered result per target. A target the round never reached is NotAttempted: it produced no evidence about the remote, and inventing `unreachable` for it would persist a failure snapshot and an audit event for a connection nobody opened.

Cancellation can prevent an attempt in three scheduling windows: before the scheduler reaches a target, after a slot is granted but before Directory is called, or while the next target waits for a full slot. The first two are context_cancelled; the waiting target is slot_not_acquired. None calls Directory.

func (*Client) PairingFinish

func (c *Client) PairingFinish(ctx context.Context, origin, pin, exchange, message, proof string, out any) error

func (*Client) PairingSPKIPin

func (c *Client) PairingSPKIPin(ctx context.Context, origin string, trustedNativeLeaf *x509.Certificate) (string, error)

PairingSPKIPin observes the configured serving origin's TLS identity using normal CA and hostname verification. A currently loaded native certificate can be an additional trust anchor; the pin always comes from the observed public peer, which can present a different certificate at a TLS proxy. It sends no HTTP request to the origin. Call only after administrator authorization; construction performs no I/O.

func (*Client) PairingStart

func (c *Client) PairingStart(ctx context.Context, origin, pin, capability, publicJWK string, out any) error

PairingStart and PairingFinish are fixed authentication-protocol paths. They use exactly the directory client's pinned TLS, redirect and response bounds.

func (*Client) RoundBudget

func (c *Client) RoundBudget(n int) time.Duration

RoundBudget is the honest whole-round maximum for n targets: the number of WAVES the fan-out cap forces, each allowed its per-remote deadline, plus one deadline of margin for scheduling.

A flat multiple of the per-remote deadline is what this replaced, and it was a lie at fleet scale: at 50 remotes and a fan-out of 4 the round needs thirteen waves, so a two-deadline budget cancelled forty-two requests that had never had their own chance. They came back `unreachable` and were persisted as fetch failures — the round manufacturing evidence about remotes it never dialled.

type Config

type Config struct {
	// Deadline bounds one remote's whole fetch, connect through body read.
	Deadline time.Duration
	// ResponseCap bounds the bytes read from one remote. Foreign bytes are
	// parsed only after being bounded.
	ResponseCap int64
	// FanOut bounds how many remotes are fetched in parallel.
	FanOut int
	// Proxy, when set, is the ONLY way egress traverses a forward proxy:
	// explicit instance configuration, never ambient environment discovery.
	// It is used with CONNECT so TLS and the pin verify end-to-end against the
	// remote — a proxy is a network hop, never a trust party — and a
	// plaintext-to-proxy URL is refused at construction.
	Proxy *url.URL
}

Config is the composable-maxima catalogue's outbound half. Zero values are refused rather than defaulted: a bound that silently defaults is a bound nobody chose, and the ops spec is where these numbers are ratified.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig is the owner-ratified Config every production caller builds from. New() still refuses an incomplete Config, so this is the only place the numbers enter the system — a caller that wants different bounds has to say so explicitly rather than inherit a silent default.

type Listing

type Listing struct {
	Identity string     `json:"identity"`
	Version  string     `json:"version"`
	Orgs     []OrgEntry `json:"orgs"`
	// OrgCount and ProjectCount are on the WIRE but are not the source of
	// truth: they are len() of what is beside them, sent so a client can show
	// a number without walking the tree. boundListing REFUSES a listing whose
	// counts disagree with its own names — a peer that says "12 orgs" and
	// sends 3 is either broken or lying, and picking one of the two numbers
	// would be picking which lie to believe.
	OrgCount     int `json:"org_count"`
	ProjectCount int `json:"project_count"`
}

Listing is the served directory: what the connection credential authorizes, exhaustively. Instance identity, version, and the NAMES of orgs and projects. No values, no keys, no environments, no membership, no settings, no audit — and there is deliberately no field here that could hold one.

Counts are not fields: they are len(). A count beside the names it counts is a second copy of the same fact that can disagree with it.

func (Listing) CountProjects

func (l Listing) CountProjects() int

CountProjects is the total across every org, computed from the names. The wire field is checked against it on ingest and is never trusted instead.

type NotAttempted

type NotAttempted struct {
	ID     string
	Reason NotAttemptedReason
}

NotAttempted is local evidence only: the target produced no remote outcome.

func (*NotAttempted) TargetID

func (r *NotAttempted) TargetID() string

type NotAttemptedReason

type NotAttemptedReason string

NotAttemptedReason says where local scheduling stopped before Directory was called. It must never be persisted as remote health or a fetch-failure audit.

const (
	NotAttemptedContextCancelled NotAttemptedReason = "context_cancelled"
	NotAttemptedSlotNotAcquired  NotAttemptedReason = "slot_not_acquired"
)

type OrgEntry

type OrgEntry struct {
	Name     string   `json:"name"`
	Projects []string `json:"projects"`
}

OrgEntry is one organisation's name and its projects' names.

type Outcome

type Outcome string

Outcome is the closed result enum the snapshot's `last_outcome` column and the `remote.fetch_failed` audit event both carry. A failure's KIND is the operator-visible part: "unreachable" and "credential-rejected" are different states because the operator's fix differs, and collapsing them into one "error" is what makes a directory card useless.

const (
	OutcomeOK Outcome = "ok"
	// OutcomeUnreachable is any transport-level failure: DNS, connection
	// refused, timeout, TLS handshake other than a pin mismatch.
	OutcomeUnreachable Outcome = "unreachable"
	// OutcomeCredentialRejected is a 401 or 403 — a revoked or expired
	// directory credential, loud and distinct from unreachability.
	OutcomeCredentialRejected Outcome = "credential-rejected"
	// OutcomePinMismatch is the hard, loud entry error. Never a retry-through.
	OutcomePinMismatch Outcome = "pin-mismatch"
	// OutcomeRedirectRefused: a redirect response is a fetch failure BY NAME,
	// never followed. Following one would let a compromised or misconfigured
	// remote move the credential's destination after the pin was confirmed.
	OutcomeRedirectRefused Outcome = "redirect-refused"
	// OutcomeIdentityConflict is the same instance identity arriving from two
	// different entries — a restored clone left running. Both entries are
	// marked duplicated and neither is served as current.
	OutcomeIdentityConflict Outcome = "identity-conflict"
	// OutcomeSelfConnected is an entry that returned THIS instance's identity.
	// Refused loudly at the authenticated fetch, and re-checked on every
	// subsequent one, so a URL that later comes to resolve to the instance
	// itself fails at fetch time rather than rendering it as its own remote.
	OutcomeSelfConnected Outcome = "self-connected"
)

func ClassifyError

func ClassifyError(err error, statusCode int) Outcome

ClassifyError maps a transport or status failure to its outcome. It is exported because the snapshot writer and the audit event must agree about what happened, and two independent mappings would eventually disagree.

type Result

type Result interface {
	TargetID() string
	// contains filtered or unexported methods
}

Result is the closed result union for one input target. Both variants carry target identity, so FetchAll can preserve cardinality and order without turning local scheduling state into a remote Outcome.

type Target

type Target struct {
	ID         string
	Origin     string
	Pin        string
	Credential string
}

Target is one remote to fetch in a fan-out round.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL