hub

type AppInstallationVerifier interface {
	VerifyAppInstallation(context.Context, int64) (VerifiedInstallation, error)
}

type EnqueueResult struct {
	Enqueued  int  `json:"enqueued"`
	Duplicate bool `json:"duplicate"`
}

type EnrolledIdentity struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name,omitempty"`
}

type EnrolledMachine struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type GitHubAppInstallationVerifier struct {
	Client        *http.Client
	AppID         int64
	PrivateKeyPEM []byte
	APIBaseURL    string
	Now           func() time.Time
}

type GitHubIdentityVerifier interface {
	ExchangeGitHubOAuthCode(context.Context, string) (string, error)
	VerifyGitHubIdentity(context.Context, string) (VerifiedGitHubIdentity, error)
}

type GitHubOAuthVerifier struct {
	Client       *http.Client
	ClientID     string
	ClientSecret string
	CallbackURL  string
	OAuthBaseURL string
	APIBaseURL   string
}

type HandlerOptions struct {
	ViewerResolver   ViewerResolver
	MachineBearer    MachineBearerResolver
	Enrollment       *MachineEnrollmentService
	Snapshots        *MachineSnapshotService
	Installations    *InstallationConnectionService
	RepositoryEvents *RepositoryEventService
	Status           *StatusService
	Projection       ProjectionProcessor
	WebhookSecret    []byte
	AllowedOrigin    string
	// Narrate receives one line for every delivery the handler itself
	// rejects, written before the response to GitHub is sent. Deliveries the
	// handler accepts are narrated by RepositoryEventService instead, so each
	// delivery produces exactly one line. Optional.
	Narrate func(narrate.Line)
	// DisableSelfHostedEnrollment unmounts POST MachineEnrollmentPath
	// (peer-connectivity#req:admin-requires-owner-credential): a self-hosted
	// hub's loopback listener is reachable through a tunnel or proxy, which is
	// not proof of the local operator, so self-hosted enrollment moves to the
	// daemon's owner-token RPC service instead. The zero value (false) mounts
	// the route exactly as before, which is what the hosted instance's own
	// OAuth-viewer-gated deployment keeps doing without changing a line here.
	DisableSelfHostedEnrollment bool
}

type IdentityInstallationBinding struct {
	IdentityID   string               `firestore:"identity_id"`
	GitHubUserID int64                `firestore:"github_user_id"`
	GitHubLogin  string               `firestore:"github_login"`
	Installation VerifiedInstallation `firestore:"installation"`
	VerifiedAt   time.Time            `firestore:"verified_at"`
}

type InstallationBindingStore interface {
	IdentityHasInstallation(context.Context, string, int64) (bool, error)
	// CompleteIdentityInstallationBinding atomically verifies and consumes the
	// pending OAuth state and upserts only the explicitly selected installation.
	// It must reject a different GitHub user when the Workbench identity already
	// has bindings. A replay or state mismatch returns ErrInvalidInstallationState.
	CompleteIdentityInstallationBinding(context.Context, InstallationStateDigest, InstallationState, time.Time, IdentityInstallationBinding) error
	ListIdentityInstallationBindings(context.Context, string) ([]IdentityInstallationBinding, error)
}

type InstallationConnectRequest struct {
	InstallationID int64 `json:"installation_id,omitempty"`
}

type InstallationConnectResponse struct {
	ConnectURL string    `json:"connect_url"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type InstallationConnectionService struct {
	States            InstallationStateStore
	AppVerifier       AppInstallationVerifier
	OAuthVerifier     GitHubIdentityVerifier
	Bindings          InstallationBindingStore
	InstallURL        string
	OAuthAuthorizeURL string
	OAuthClientID     string
	OAuthCallbackURL  string
	SuccessURL        string
	StateSecret       []byte
	StateLifetime     time.Duration
	Random            io.Reader
	Now               func() time.Time
}

type InstallationContinuation struct {
	RedirectURL string
	ExpiresAt   time.Time
	// contains filtered or unexported fields
}

type InstallationLifecycleAction string

type InstallationLifecycleEvent struct {
	DeliveryID     string                      `firestore:"delivery_id"`
	Action         InstallationLifecycleAction `firestore:"action"`
	InstallationID int64                       `firestore:"installation_id"`
	RepositoryIDs  []int64                     `firestore:"repository_ids,omitempty"`
	RepositoryID   int64                       `firestore:"repository_id,omitempty"`
	GitHubUserID   int64                       `firestore:"github_user_id,omitempty"`
}

type InstallationLifecycleStore interface {
	// ApplyInstallationLifecycle is idempotent by DeliveryID and atomically
	// removes or disables every affected entitlement before it returns success.
	// A GitHubUserAuthorizationRevoked event applies to every binding for that
	// GitHub user; RepositoryUserAccessRemoved applies only to its exact
	// installation, repository, and GitHub user tuple.
	ApplyInstallationLifecycle(context.Context, InstallationLifecycleEvent) error
}

type InstallationOpenerAuthorizationRequest struct {
	State     string `json:"state"`
	Challenge string `json:"challenge"`
}

type InstallationRedirect struct {
	RedirectURL string
	ExpiresAt   time.Time
	// contains filtered or unexported fields
}

type InstallationState struct {
	Kind                       installationStateKind `firestore:"kind"`
	IdentityID                 string                `firestore:"identity_id"`
	InstallationID             int64                 `firestore:"installation_id,omitempty"`
	BrowserContinuationDigest  string                `firestore:"browser_continuation_digest"`
	OpenerChallengeDigest      string                `firestore:"opener_challenge_digest,omitempty"`
	OpenerChallengeExpiresAt   time.Time             `firestore:"opener_challenge_expires_at,omitempty"`
	OpenerAuthorizedAt         time.Time             `firestore:"opener_authorized_at,omitempty"`
	OAuthAccessTokenCiphertext string                `firestore:"oauth_access_token_ciphertext,omitempty"`
	IssuedAt                   time.Time             `firestore:"issued_at"`
	ExpiresAt                  time.Time             `firestore:"expires_at"`
}

type InstallationStateDigest [sha256.Size]byte

type InstallationStateStore interface {
	// IssueInstallationState rejects an existing digest so a random-state
	// collision cannot overwrite another pending authorization.
	IssueInstallationState(context.Context, InstallationStateDigest, InstallationState) error
	// ReadInstallationState returns a pending, unexpired state without consuming
	// it. Store availability errors must remain distinguishable from
	// ErrInvalidInstallationState so callers can safely retry transient failures.
	ReadInstallationState(context.Context, InstallationStateDigest, time.Time) (InstallationState, error)
	// TransitionInstallationState atomically verifies current against the stored
	// pending state, consumes it, and issues next. A replay, expired state,
	// mismatch, or next-digest collision returns ErrInvalidInstallationState.
	TransitionInstallationState(context.Context, InstallationStateDigest, InstallationState, time.Time, InstallationStateDigest, InstallationState) error
	// ReplaceInstallationState atomically verifies current against the stored
	// pending state and replaces it under the same digest. It is used to retain
	// an encrypted exchanged OAuth credential before any fallible post-exchange
	// reads. A replay, expiry, or mismatch returns ErrInvalidInstallationState.
	ReplaceInstallationState(context.Context, InstallationStateDigest, InstallationState, time.Time, InstallationState) error
}

type Machine struct {
	ID         string
	Name       string
	IdentityID string
	Scopes     []MachineScope
}

type MachineBearerResolver interface {
	ResolveMachineBearer(*http.Request) (Machine, error)
}

type MachineCredentialBinding struct {
	MachineID           string         `firestore:"machine_id"`
	MachineName         string         `firestore:"machine_name"`
	IdentityID          string         `firestore:"identity_id"`
	IdentityDisplayName string         `firestore:"identity_display_name,omitempty"`
	IssuedAt            time.Time      `firestore:"issued_at"`
	Scopes              []MachineScope `firestore:"scopes"`
}

type MachineCredentialResolver interface {
	ResolveMachineCredential(context.Context, MachineTokenDigest) (MachineCredentialBinding, error)
}

type MachineCredentialStore interface {
	RotateMachineCredential(context.Context, MachineCredentialBinding, MachineTokenDigest) (MachineCredentialBinding, error)
}

type MachineEnrollmentRequest struct {
	Name string `json:"name"`
}

type MachineEnrollmentResponse struct {
	Machine    EnrolledMachine  `json:"machine"`
	Identity   EnrolledIdentity `json:"identity"`
	Token      string           `json:"token"`
	EnrolledAt time.Time        `json:"enrolled_at"`
}

type MachineEnrollmentService struct {
	Store  MachineCredentialStore
	Pepper []byte
	Random io.Reader
	Now    func() time.Time
}

type MachineIndex interface {
	HasCredential(context.Context, string) (bool, error)
}

type MachineScope string

type MachineSnapshotService struct {
	Store MachineSnapshotStore
	Now   func() time.Time
}

type MachineSnapshotStore interface {
	StoreLatest(context.Context, StoredMachineSnapshot) (MachineSnapshotStoreResult, error)
	ListLatest(context.Context) ([]StoredMachineSnapshot, error)
}

type MachineSnapshotStoreResult struct {
	Current StoredMachineSnapshot
	Updated bool
}

type MachineTokenDigest [sha256.Size]byte

type PeerAdminService struct {
	// Credentials, Index, Trust and Stats are the seams Block, Unblock,
	// Disconnect, resolvePeer and RefuseIfPeerNameCollision use. Invite does
	// not use Credentials: see Backend.
	Credentials MachineCredentialStore
	Index       MachineIndex
	Trust       PeerTrustStore
	Stats       PeerStatsStore
	// Backend is the raw document store Invite writes the credential, trust
	// and statistics documents against inside one UpdateAtomic transaction,
	// so a partial invite (a credential with no matching trust document, or
	// the reverse) can never be observed. DocumentStore's contract promises
	// serializable transaction semantics, so two concurrent invites of the
	// same name always resolve to exactly one winner with a working token;
	// the loser's writes (including its own randomly minted token) are
	// discarded by the retried transaction rather than partially applied,
	// and it observes ErrPeerExists-shaped refusal instead.
	Backend githubapp.DocumentStore
	Pepper  []byte
	Random  io.Reader
	Now     func() time.Time
	// LocalIdentityID is the fixed self-hosted identity every peer credential
	// is minted under (hub.MachineID's first argument), matching
	// ensureLocalEnrollment's "local".
	LocalIdentityID string
	// HubMachineName is the hub's own machine name. invite-and-join refuses
	// it outright: the hub is never its own peer.
	HubMachineName string
	// MemoryEngine is true when the hub's store engine is "memory". Invite
	// refuses admission in that case, per invite-and-join: a peer credential
	// minted against a store that discards on exit could never be reasoned
	// about as durable state.
	MemoryEngine bool
}

type PeerDisconnectResult struct {
	Peer         PeerRecord
	Disconnected bool
	Message      string
}

type PeerInviteResult struct {
	PeerID    string
	Name      string
	Token     string
	CreatedAt time.Time
	Rotated   bool
}

type PeerRecord struct {
	MachineID      string    `firestore:"machine_id"`
	Name           string    `firestore:"name"`
	IdentityID     string    `firestore:"identity_id"`
	NodeID         string    `firestore:"node_id,omitempty"`
	Trust          PeerTrust `firestore:"trust"`
	CreatedAt      time.Time `firestore:"created_at"`
	TrustChangedAt time.Time `firestore:"trust_changed_at"`
	ResetPending   bool      `firestore:"reset_pending"`
}

type PeerStats struct {
	MachineID        string    `firestore:"machine_id"`
	LastSeenAt       time.Time `firestore:"last_seen_at,omitempty"`
	LastConnectedAt  time.Time `firestore:"last_connected_at,omitempty"`
	WBVersion        string    `firestore:"wb_version,omitempty"`
	OS               string    `firestore:"os,omitempty"`
	Arch             string    `firestore:"arch,omitempty"`
	Protocol         int       `firestore:"protocol,omitempty"`
	RXPayloadBytes   uint64    `firestore:"rx_payload_bytes"`
	TXPayloadBytes   uint64    `firestore:"tx_payload_bytes"`
	RXMessages       uint64    `firestore:"rx_messages"`
	TXMessages       uint64    `firestore:"tx_messages"`
	RXEvents         uint64    `firestore:"rx_events"`
	TXEvents         uint64    `firestore:"tx_events"`
	Connections      uint64    `firestore:"connections"`
	ConnectedSeconds uint64    `firestore:"connected_seconds"`
}

type PeerStatsStore interface {
	// CreateStats writes a new, all-zero statistics document for machineID.
	// It is idempotent: an existing document is left untouched rather than
	// reset, so a later writer's progress survives a repeated invite.
	CreateStats(context.Context, string) error
	// GetStats reads the statistics document. found is false when none
	// exists yet.
	GetStats(context.Context, string) (stats PeerStats, found bool, err error)
}

type PeerTrust string

type PeerTrustResolver interface {
	GetPeer(context.Context, string) (record PeerRecord, found bool, err error)
}

type PeerTrustStore interface {
	// CreatePeer writes a new trust document. It fails with ErrPeerExists if
	// one already exists for record.MachineID.
	CreatePeer(context.Context, PeerRecord) error
	// GetPeer reads the trust document by MachineID. found is false, with a
	// nil error, when no peer record exists — the credential is not a peer.
	GetPeer(context.Context, string) (record PeerRecord, found bool, err error)
	// FindPeerByName reads the trust document by display name, for `<peer>`
	// arguments and invite's existing-name refusal.
	FindPeerByName(context.Context, string) (record PeerRecord, found bool, err error)
	// ListPeers returns every peer trust document, for `wb peers list`.
	ListPeers(context.Context) ([]PeerRecord, error)
	// UpdateTrust reads the current record inside a transaction, applies
	// mutate, and writes the result back — the "transactional field merge"
	// every admin write is. mutate must not change MachineID, Name,
	// IdentityID, or CreatedAt; it returns ErrPeerNotFound when machineID has
	// no trust document.
	UpdateTrust(ctx context.Context, machineID string, mutate func(*PeerRecord)) (PeerRecord, error)
}

type PendingRefresh struct {
	ID             string    `json:"id"`
	Repository     string    `json:"repository"`
	Event          string    `json:"event,omitempty"`
	QueuedAt       time.Time `json:"queued_at"`
	InstallationID string    `json:"installation_id,omitempty"`
	MachineID      string    `json:"machine_id,omitempty"`
}

type PollObservation struct {
	// Repository is the canonical `github.com/owner/repository` this
	// observation is keyed by, lowercased the way machine snapshots are.
	Repository string `firestore:"repository"`
	// FullName is `owner/repository` exactly as GitHub reported it, so a
	// rename is detected against what the API said rather than against a
	// normalisation of it.
	FullName string `firestore:"full_name"`
	// DefaultBranch is the branch name GitHub reported, without a ref prefix.
	DefaultBranch string `firestore:"default_branch"`
	// SHA is the object ID at the head of DefaultBranch.
	SHA string `firestore:"sha"`
	// ObservedAt is when the poller read those values.
	ObservedAt time.Time `firestore:"observed_at"`
}

type PollObservationStore interface {
	// LoadPollObservation returns the stored observation for a repository.
	// The boolean is false when the poller has never seen it, which is the
	// signal to record without enqueueing.
	LoadPollObservation(context.Context, string) (PollObservation, bool, error)
	// SavePollObservation replaces the observation for observation.Repository.
	SavePollObservation(context.Context, PollObservation) error
	// DeletePollObservation drops the observation a rename re-keyed away
	// from. Deleting one that is not there is not an error.
	DeletePollObservation(context.Context, string) error
}

type ProjectionProcessor interface {
	ProcessProjection(context.Context, WebhookDelivery, string) error
}

type QueuedWorkStore interface {
	// QueuedWork reads workbench_repository_event_queues/<machineID>'s
	// queued_work field. found is false when the machine has no queue-state
	// document yet — LAG then shows "-", not zero, since "no document" and
	// "a document reporting zero" are different facts once Task 3 starts
	// writing it.
	QueuedWork(ctx context.Context, machineID string) (count int64, found bool, err error)
}

type RateLimit struct {
	Known     bool
	Remaining int
	Reset     time.Time
}

type RepositoryEntitlementResolver interface {
	IdentityHasRepositoryEntitlement(context.Context, string, int64, int64) (bool, error)
}

type RepositoryEventService struct {
	Snapshots    MachineSnapshotStore
	Entitlements RepositoryEntitlementResolver
	Lifecycle    InstallationLifecycleStore
	Store        RepositoryEventStore
	PollInterval time.Duration
	Sleep        func(context.Context, time.Duration) error
	Now          func() time.Time
	// Narrate receives one line for every delivery the service decides about:
	// queued, ignored, dropped as a duplicate, or applied as a lifecycle
	// change. A delivery the service returns an error for is narrated by the
	// HTTP handler instead, so every delivery produces exactly one line.
	// Optional; the hosted instance leaves it unset.
	Narrate func(narrate.Line)
}

type RepositoryEventStatusStore interface {
	IdentityRepositoryEventStatus(context.Context, string) (*StatusDelivery, []PendingRefresh, []StatusError, error)
}

type RepositoryEventStore interface {
	EnqueueForMachines(context.Context, repositoryevent.Event, []Machine) (EnqueueResult, error)
	Poll(context.Context, Machine, string, int) (repositoryevent.PollResponse, error)
	Acknowledge(context.Context, Machine, repositoryevent.AckRequest) (repositoryevent.AckResponse, error)
}

type StatusConnection struct {
	State      string `json:"state"`
	AppName    string `json:"app_name,omitempty"`
	Account    string `json:"account,omitempty"`
	ConnectURL string `json:"connect_url,omitempty"`
}

type StatusDelivery struct {
	LastReceived     *StatusDeliveryMarker `json:"last_received,omitempty"`
	LastAcknowledged *StatusDeliveryMarker `json:"last_acknowledged,omitempty"`
}

type StatusDeliveryMarker struct {
	DeliveryID string    `json:"delivery_id,omitempty"`
	Event      string    `json:"event,omitempty"`
	OccurredAt time.Time `json:"occurred_at"`
}

type StatusError struct {
	Code           string `json:"code"`
	Message        string `json:"message"`
	Action         string `json:"action,omitempty"`
	ActionURL      string `json:"action_url,omitempty"`
	InstallationID string `json:"installation_id,omitempty"`
}

type StatusInstallation struct {
	ID                  string `json:"id"`
	Account             string `json:"account"`
	AccountType         string `json:"account_type,omitempty"`
	State               string `json:"state"`
	RepositorySelection string `json:"repository_selection,omitempty"`
	Repositories        int    `json:"repositories,omitempty"`
	ManageURL           string `json:"manage_url,omitempty"`
}

type StatusMachine struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	State      string     `json:"state,omitempty"`
	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
}

type StatusResponse struct {
	GeneratedAt      time.Time            `json:"generated_at"`
	Connection       StatusConnection     `json:"connection"`
	Installations    []StatusInstallation `json:"installations"`
	Machines         []StatusMachine      `json:"machines"`
	Delivery         *StatusDelivery      `json:"delivery,omitempty"`
	PendingRefreshes []PendingRefresh     `json:"pending_refreshes"`
	Errors           []StatusError        `json:"errors"`
}

type StatusService struct {
	Bindings  InstallationBindingStore
	Snapshots MachineSnapshotStore
	Events    RepositoryEventStatusStore
	AppName   string
	Now       func() time.Time
}

type StoredMachineSnapshot struct {
	IdentityID string                   `firestore:"identity_id"`
	MachineID  string                   `firestore:"machine_id"`
	Snapshot   machinesnapshot.Snapshot `firestore:"snapshot"`
	ReceivedAt time.Time                `firestore:"received_at"`
	Digest     string                   `firestore:"digest"`
}

type VerifiedGitHubIdentity struct {
	UserID        int64                  `json:"user_id"`
	Login         string                 `json:"login"`
	Installations []VerifiedInstallation `json:"installations"`
}

type VerifiedInstallation struct {
	ID                  int64                `json:"id" firestore:"id"`
	Account             string               `json:"account" firestore:"account"`
	AccountType         string               `json:"account_type,omitempty" firestore:"account_type,omitempty"`
	RepositorySelection string               `json:"repository_selection" firestore:"repository_selection"`
	Repositories        []VerifiedRepository `json:"repositories" firestore:"repositories"`
	State               string               `json:"state,omitempty" firestore:"state,omitempty"`
	ManageURL           string               `json:"manage_url,omitempty" firestore:"manage_url,omitempty"`
}

type VerifiedRepository struct {
	ID         int64  `json:"id" firestore:"id"`
	Repository string `json:"repository" firestore:"repository"`
}

type Viewer struct {
	Authenticated bool
	IdentityID    string
	DisplayName   string
}

type ViewerResolver interface {
	Viewer(*http.Request) (Viewer, error)
}

type WebhookDelivery struct {
	ID         string
	Event      string
	Repository string
	Payload    []byte
}

type WebhookRedeliveryRecord struct {
	// GUID is the delivery GUID GitHub keeps stable across every attempt and
	// every redelivery of one logical delivery.
	GUID string `firestore:"guid"`
	// Attempts is how many times this hub has asked GitHub to redeliver this
	// GUID. It never exceeds MaxAttempts in the redeliver package.
	Attempts int `firestore:"attempts"`
	// Abandoned is set once Attempts has been exhausted with the delivery
	// still failing. An abandoned GUID is never retried again.
	Abandoned bool `firestore:"abandoned"`
	// LastAttemptAt is when this record was last written, whether by a
	// redelivery or by being marked abandoned. It is the retention clock.
	LastAttemptAt time.Time `firestore:"last_attempt_at"`
	// LastAttemptDeliveryID is the GitHub delivery attempt id that was this
	// GUID's latest listed attempt the last time this hub acted on it. A
	// later sweep counts a redelivery attempt against this GUID only when
	// its now-latest listed attempt was answered and carries a different id
	// than this one: an id comparison, not a timestamp comparison, because
	// GitHub's delivered_at has whole-second resolution on GitHub's own
	// clock while this hub's own attempt time is local and sub-second, so a
	// fast redeliver round trip routinely lands in the same GitHub-clock
	// second as the request that caused it.
	LastAttemptDeliveryID int64 `firestore:"last_attempt_delivery_id"`
	// FirstDeliveredAt is the delivered_at of this GUID's earliest attempt
	// this hub has seen, set once when the record is first created and never
	// overwritten after. Because every uncounted redelivery creates a new
	// attempt with a fresh delivered_at, the GUID's own latest attempt never
	// ages out of the App API's listing on its own; the 72-hour bound in
	// spec/features/peer-connectivity/README.md is measured from this field,
	// not from LastAttemptAt, so an unreachable endpoint cannot keep a GUID
	// alive forever.
	FirstDeliveredAt time.Time `firestore:"first_delivered_at"`
}

type WebhookRedeliveryStore interface {
	// LoadWebhookRedelivery returns the stored record for a GUID. The boolean
	// is false when the sweep has never acted on it, which is the signal to
	// treat it as zero prior attempts.
	LoadWebhookRedelivery(ctx context.Context, guid string) (WebhookRedeliveryRecord, bool, error)
	// SaveWebhookRedelivery replaces the record for record.GUID.
	SaveWebhookRedelivery(ctx context.Context, record WebhookRedeliveryRecord) error
	// ListWebhookRedeliveries returns every stored record, for the retention
	// sweep to filter by age.
	ListWebhookRedeliveries(ctx context.Context) ([]WebhookRedeliveryRecord, error)
	// DeleteWebhookRedeliveries removes the named GUIDs' records. Deleting a
	// GUID that is not there is not an error. Callers must keep each call
	// within the store's transaction write bound.
	DeleteWebhookRedeliveries(ctx context.Context, guids []string) error
}