forge

type AuthConfig struct {
	Env      string `mapstructure:"env"      json:"env"      yaml:"env"`
	Value    string `mapstructure:"value"    json:"value"    yaml:"value"`
	Keychain string `mapstructure:"keychain" json:"keychain" yaml:"keychain"`
}

type Authenticator interface {
	// Login runs the provider's interactive authentication flow, surfacing any
	// user-facing step through p, and returns a usable API token on success. It
	// blocks until the user completes the flow, ctx is cancelled, or the flow's own
	// deadline (e.g. the device-code expiry) elapses.
	//
	// Returns [ErrNotSupported] when interactive login is unavailable in the
	// provider's current configuration; the caller then falls back to manual entry.
	Login(ctx context.Context, p Prompter) (token string, err error)
}

type ChecksumProvider interface {
	// DownloadChecksumManifest returns the raw bytes of the checksums
	// manifest for the given release.
	//
	// The implementation MUST enforce maxBytes and return an error when the
	// response exceeds it, so a hostile server cannot stream indefinitely.
	// Enforcement belongs here, at the trust boundary, not in the caller: a
	// provider reaching a URL of its own composition is the only code that
	// sees the response before it is buffered. [DefaultMaxChecksumsSize] is
	// a reasonable bound, but the CALLER chooses the value and passes it —
	// tools shipping unusually large artefacts legitimately raise it.
	//
	// Returns [ErrNotSupported] when the provider is configured in a
	// way that disables checksum retrieval (e.g. the Direct
	// provider's `checksum_url_template` param is empty). The caller
	// treats [ErrNotSupported] exactly like "provider does not
	// implement this interface" — fall back to asset-by-name lookup
	// if one is available, otherwise respect the require_checksum
	// policy.
	DownloadChecksumManifest(ctx context.Context, rel Release, maxBytes int64) ([]byte, error)
}

type Config interface {
	GetString(key string) string
	Sub(key string) Config
}

type DeviceCode struct {
	// UserCode is the short code the user types at VerificationURI.
	UserCode string
	// VerificationURI is where the user enters UserCode to authorize the request.
	VerificationURI string
	// VerificationURIComplete, when non-empty, is a URL that pre-fills the code
	// (some providers supply it so the user need not type UserCode).
	VerificationURIComplete string
	// ExpiresIn is how long UserCode remains valid.
	ExpiresIn time.Duration
}

type KeyManager interface {
	// UploadKey registers publicKey — an OpenSSH-format public key ("ssh-ed25519
	// AAAA… comment") — under the given human-readable name on the authenticated
	// account. The provider resolves its own credentials (as for the release
	// [Provider]); name is a label the user will see in the account's key list.
	UploadKey(ctx context.Context, name string, publicKey []byte) error
}

type Prompter interface {
	// ShowDeviceCode presents a device-authorization prompt to the user — typically
	// "open dc.VerificationURI and enter dc.UserCode". It returns once the prompt has
	// been shown; the [Authenticator] then polls the provider for completion. A
	// non-nil error aborts the login.
	ShowDeviceCode(ctx context.Context, dc DeviceCode) error
}

type Provider interface {
	GetLatestRelease(ctx context.Context, owner, repo string) (Release, error)
	GetReleaseByTag(ctx context.Context, owner, repo, tag string) (Release, error)
	ListReleases(ctx context.Context, owner, repo string, limit int) ([]Release, error)

	// DownloadReleaseAsset opens a stream of the asset's bytes.
	//
	// The second return value is a REDIRECT URL, and it is a security
	// boundary rather than a convenience. Some APIs answer an asset request
	// with a redirect to storage the client is expected to follow itself
	// (this is go-github's behaviour, which surfaces the location instead of
	// following it). A provider that receives such a redirect and does NOT
	// follow it returns the location here, with a nil or empty reader.
	//
	// Callers are expected to REFUSE a non-empty redirect rather than follow
	// it: following one would fetch bytes from a host the caller never
	// vetted, defeating the point of pinning the API host. Return "" whenever
	// the body is served directly, which is the common case — three of the
	// four first-party providers always do.
	DownloadReleaseAsset(ctx context.Context, owner, repo string, asset ReleaseAsset) (io.ReadCloser, string, error)
}

type ProviderFactory func(source ReleaseSourceConfig, cfg Config) (Provider, error)

type Release interface {
	GetName() string
	GetTagName() string
	GetBody() string
	GetDraft() bool
	GetAssets() []ReleaseAsset
}

type ReleaseAsset interface {
	GetID() int64
	GetName() string
	GetBrowserDownloadURL() string
}

type ReleaseSourceConfig struct {
	Type    string
	Host    string
	Owner   string
	Repo    string
	Private bool
	// Params holds provider-specific configuration key/value pairs.
	// Keys use snake_case. Valid keys are documented per provider.
	Params map[string]string
}

type SignatureProvider interface {
	// DownloadSignature returns the raw bytes of the detached
	// signature over the checksums manifest for the given release.
	//
	// As with [ChecksumProvider.DownloadChecksumManifest], the
	// implementation MUST enforce maxBytes. The two are deliberately
	// symmetric: an implementer should never have to remember which of the
	// two capped for them. [DefaultMaxSignatureSize] is a reasonable bound,
	// chosen by the caller.
	//
	// Returns [ErrNotSupported] when the provider is configured in a
	// way that disables signature retrieval (e.g. the Direct
	// provider's `signature_url_template` param is empty, or no
	// signature file was uploaded to Bitbucket). The caller treats
	// [ErrNotSupported] exactly like "provider does not implement this
	// interface" — fall back to asset-by-name lookup if one is
	// available, otherwise respect the require_signature policy.
	DownloadSignature(ctx context.Context, rel Release, maxBytes int64) ([]byte, error)
}

type TokenConfig interface {
	GetString(key string) string
}

type TrustOption func(*trustPolicy)