claudeproxy

type Denial struct {
	Reason  DenyReason
	Message string
	Status  int
}

type DenyReason string

type Event struct {
	Kind      EventKind `json:"kind"`
	SessionID string    `json:"session_id,omitempty"`

	// Which rule admitted this pipeline, and which pipeline it was.
	RuleID     string `json:"rule_id,omitempty"`
	RuleName   string `json:"rule_name,omitempty"`
	Project    string `json:"project,omitempty"`
	Subject    string `json:"subject,omitempty"`
	Repository string `json:"repository,omitempty"`
	Ref        string `json:"ref,omitempty"`
	Workflow   string `json:"workflow,omitempty"`
	Actor      string `json:"actor,omitempty"`
	RunID      string `json:"run_id,omitempty"`

	// What a run relay session stands on (Task 20435): the lease and grant
	// its credential came from, the executor its run was dispatched to, the
	// identity its spend is charged to, and the kind of credential it spends
	// ("oauth_token", "api_key") — never the credential.
	LeaseID      string `json:"lease_id,omitempty"`
	GrantID      string `json:"grant_id,omitempty"`
	ExecutorID   string `json:"executor_id,omitempty"`
	Payer        string `json:"payer,omitempty"`
	UpstreamKind string `json:"upstream_kind,omitempty"`

	// Request shape, for allowed and denied relays.
	Method string `json:"method,omitempty"`
	Path   string `json:"path,omitempty"`
	Model  string `json:"model,omitempty"`
	Status int    `json:"status,omitempty"`

	// Reason is set on a refusal.
	Reason DenyReason `json:"reason,omitempty"`

	// Spend attributable to this event.
	InputTokens  int64 `json:"input_tokens,omitempty"`
	OutputTokens int64 `json:"output_tokens,omitempty"`

	Detail string    `json:"detail,omitempty"`
	At     time.Time `json:"at"`
}

type EventKind string

type MessageRequest struct {
	Model     string `json:"model"`
	MaxTokens *int   `json:"max_tokens,omitempty"`
	Stream    bool   `json:"stream,omitempty"`
}

type MintRequest struct {
	Policy Policy

	RuleID     string
	RuleName   string
	Project    string
	Subject    string
	Repository string
	Ref        string
	Workflow   string
	Actor      string
	RunID      string
	RunURL     string

	// TTL is the session lifetime, clamped to [MinTTL, MaxTTL].
	TTL time.Duration

	// Claims is the verified assertion the pipeline federated with, recorded
	// with the session for the hub that restores it (Task 20390). Opaque
	// here, never read, never retained in memory past the record's write.
	Claims json.RawMessage

	// A run relay session's binding (Task 20435); see Session.
	LeaseID    string
	GrantID    string
	ExecutorID string
	Payer      string

	// Upstream, when set, is the credential this session relays with in
	// place of the proxy's. It must validate.
	Upstream *Upstream
}

type Minted struct {
	Session *Session

	// Token is the only copy. It is not stored, and a caller that loses it
	// must mint again.
	Token string

	// BaseURL is what the pipeline sets ANTHROPIC_BASE_URL to.
	BaseURL string
}

type Options struct {
	// Upstream is the credential and endpoint to relay to.
	Upstream Upstream

	// PathPrefix is stripped from the incoming path before the API surface
	// is matched, e.g. "/api/ci/anthropic".
	PathPrefix string

	// Transport overrides the upstream HTTP transport. Tests point this at
	// an httptest server.
	Transport http.RoundTripper

	// Now overrides the clock.
	Now func() time.Time

	// Fallback, when set, is offered every request whose credential names a
	// session this registry has never heard of, before it is refused
	// (Task 20354). Several hub processes may serve one control plane, each
	// with its own registry, and a sandbox's request reaches whichever of
	// them the network sends it to; the hub forwards it to the process that
	// minted the session. It reports whether it answered the request.
	// Credentials naming a session this registry knows — right or wrong
	// token, live or expired — are always decided here.
	Fallback func(w http.ResponseWriter, r *http.Request, sessionID string) bool

	// Admit, when set, is asked before a Messages API request is relayed —
	// after the policy accepted it, before its request is counted — and a
	// denial it returns refuses the request as the policy's do. A run relay
	// holds the identity paying for the run to its daily budgets here (Task
	// 20435). Counting tokens and listing models spend nothing and are not
	// asked about.
	Admit func(s *Session, model string) *Denial

	// OnSpend, when set, is told what each relayed response spent, as the
	// upstream reported it, once the response has been relayed — on the
	// request's goroutine, after the session's counters include it.
	OnSpend func(s *Session, sp Spend)

	// ExplainClosed answers a token whose session this registry closed —
	// revoked, its lease ended, its run over — with a 403 naming why, rather
	// than the 401 an unknown token gets (Task 20435). Measured against
	// Claude Code, a 401 is retried 11 times over about three minutes before
	// the harness gives up, and a 403 ends it at once. Only the holder of the
	// session's token learns the reason: the token must hash to the closed
	// session's.
	ExplainClosed bool

	// UserAgent replaces the client's User-Agent upstream. Empty uses
	// "cloop-ci-proxy/1".
	UserAgent string

	// Unauthenticated is the message a request with no usable token gets.
	// Empty uses the CI relay's, which tells a pipeline to federate again.
	Unauthenticated string

	// SessionUpstreams says every session carries the credential it relays
	// with (MintRequest.Upstream) and the proxy holds none of its own (Task
	// 20435): a run relay spends the credential the run's grant holds. The
	// proxy's Upstream may then be empty, and a session without a credential
	// of its own is refused rather than relayed with something else.
	SessionUpstreams bool
}

type Policy struct {
	// Models is a glob allowlist of model IDs. Empty denies everything: the
	// caller resolves "unset" to the hub default before minting.
	Models []string `json:"models"`

	// MaxOutputTokens clamps `max_tokens` on every request. Zero uses
	// DefaultMaxOutputTokens.
	MaxOutputTokens int `json:"max_output_tokens,omitempty"`

	// MaxRequests caps the session's lifetime request count. Zero means
	// unlimited, which the minting path does not produce.
	MaxRequests int `json:"max_requests,omitempty"`

	// MaxBodyBytes bounds one request body. Zero uses DefaultMaxBodyBytes.
	MaxBodyBytes int64 `json:"max_body_bytes,omitempty"`
}

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

type Registry struct {

	// OnEvent receives audit events. It is called on the calling goroutine,
	// so a sink that blocks blocks a request.
	OnEvent func(Event)

	// Store, if set, records every session and keeps the record in step
	// (durable.go), so another hub process can restore it. Nil keeps
	// sessions in memory only, as every registry did before Task 20390.
	Store SessionStore
	// contains filtered or unexported fields
}

type RestoreRequest struct {
	// Record is the session as its Store recorded it, with the policy and
	// deadline the caller holds it to now — never wider than recorded.
	Record SessionRecord
	// From names the hub process the session was taken over from, for the
	// restored row.
	From string
	// Detail, when set, is added to the restored row: what the caller
	// narrowed.
	Detail string
	// Upstream is the credential a run relay session relays with, re-derived
	// by the caller from the lease it took over (Task 20435) — never read
	// from the record, which holds none. Required when the record names an
	// upstream kind, and must be of that kind.
	Upstream *Upstream
}

type Session struct {
	ID     string
	Policy Policy

	// Provenance: which rule admitted which pipeline. Recorded at mint so an
	// audit entry describes the identity that was actually accepted, not
	// whatever the rule says today.
	RuleID     string
	RuleName   string
	Project    string
	Subject    string
	Repository string
	Ref        string
	Workflow   string
	Actor      string
	RunID      string
	RunURL     string

	// What a run relay session stands on (Task 20435): the secret lease and
	// grant its upstream credential came from, the executor the run was
	// dispatched to, and the identity its spend is charged to. Empty for a
	// CI session.
	LeaseID    string
	GrantID    string
	ExecutorID string
	Payer      string

	IssuedAt time.Time
	// ExpiresAt is the deadline the session was minted or restored with.
	// Extend moves the effective one; see Deadline.
	ExpiresAt time.Time
	// contains filtered or unexported fields
}

type SessionRecord struct {
	ID string
	// TokenSHA256 is the hex SHA-256 of the session token.
	TokenSHA256 string
	Policy      Policy

	RuleID     string
	RuleName   string
	Project    string
	Subject    string
	Repository string
	Ref        string
	Workflow   string
	Actor      string
	RunID      string
	RunURL     string
	// Claims is the verified assertion the session was minted for, as the
	// hub chose to record it: opaque to this package, which never reads it.
	// The hub holds a restored session to its rule against it. A run relay
	// session's is the hub's account of the run it serves (Task 20435).
	Claims json.RawMessage

	// A run relay session's binding (Task 20435). UpstreamKind names the kind
	// of credential it spends — never the credential, which the process
	// restoring it re-derives from the lease.
	LeaseID      string
	GrantID      string
	ExecutorID   string
	Payer        string
	UpstreamKind string

	IssuedAt  time.Time
	ExpiresAt time.Time
	// RenewedAt is when an extension last moved ExpiresAt, zero for none.
	RenewedAt time.Time

	// Usage and LastUsed are what the session had spent when it was last
	// checkpointed.
	Usage    Usage
	LastUsed time.Time
}

type SessionRenewer interface {
	RenewSession(id string, expiresAt, renewedAt time.Time) error
}

type SessionStore interface {
	// SaveSession records a session this process now serves.
	SaveSession(rec SessionRecord) error
	// CheckpointSession records what a session this process serves has
	// spent so far.
	CheckpointSession(id string, u Usage, lastUsed time.Time) error
	// CloseSession records that a session this process served has ended,
	// and why, with what it spent.
	CloseSession(id, reason string, at time.Time, u Usage) error
}

type Spend struct {
	// Model is the model the upstream answered with, else the one asked for.
	Model string
	// Status is the upstream's HTTP status.
	Status int
	// Input, Output, CacheRead and CacheWrite are the response's token
	// counts; CacheWrite1h is the part of CacheWrite written to the
	// one-hour cache, which the API prices higher than the five-minute one.
	Input, Output, CacheRead, CacheWrite, CacheWrite1h int64
}

type Upstream struct {
	// BaseURL is the API origin. Empty uses DefaultUpstream.
	BaseURL string

	// APIKey is sent as x-api-key.
	APIKey string

	// AuthToken is sent as Authorization: Bearer.
	AuthToken string

	// OAuth marks AuthToken as a claude.ai OAuth token — what `claude
	// setup-token` prints and CLAUDE_CODE_OAUTH_TOKEN carries — rather than a
	// gateway's bearer. The relay then names the API's OAuth beta beside
	// whatever betas the client asked for (OAuthBeta). Measured against the
	// real API on 2026-10-16 (Task 20435), a token was accepted with and
	// without it; the API's own documentation for OAuth callers asks for it,
	// and a header the API ignores costs nothing where one it starts to
	// require would cost every relayed run.
	OAuth bool
}

type Usage struct {
	Requests     int64 `json:"requests"`
	Denied       int64 `json:"denied"`
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
	CacheRead    int64 `json:"cache_read_input_tokens,omitempty"`
	CacheWrite   int64 `json:"cache_creation_input_tokens,omitempty"`
	BytesUp      int64 `json:"bytes_up"`
	BytesDown    int64 `json:"bytes_down"`
}