agentprovider

type AgentTokenParams struct {
	// Name is the agent identifier's local part; the domain is the
	// provider's. A sub-agent's name carries "+discriminator".
	Name string
	// Key is the agent's public key (cnf.jwk); never the provider's.
	Key aauth.JWK
	// PS is the ps claim; ParentAgent marks a sub-agent token.
	PS          string
	ParentAgent string
	// TTL is the lifetime (default Config.TokenTTL, at most 24 hours);
	// NotAfter, when set, caps exp (a sub-agent's parent token).
	TTL      time.Duration
	NotAfter time.Time
}

type Attestation struct {
	Format string         // e.g. "webauthn", "app-attest", "play-integrity"
	Claims map[string]any // what the verifier established
}

type AttestationVerifier interface {
	VerifyAttestation(ctx context.Context, evidence json.RawMessage, key aauth.JWK) (*Attestation, error)
}

type Client struct {
	// BaseURL is the provider's issuer.
	BaseURL string
	// Paths are the provider's endpoint paths (default DefaultPaths).
	Paths Paths
	// HTTPClient makes requests; nil uses http.DefaultClient.
	HTTPClient *http.Client
}

type Config struct {
	// Issuer is the provider's server identifier: the iss of the agent
	// tokens it issues.
	Issuer string
	// Domain is the domain of the agent identifiers it issues; default the
	// issuer's host.
	Domain string
	// Key is the provider's signing key — separate from every agent's key
	// — and KeyID its kid (default: the RFC 7638 thumbprint).
	// PublishedKeys are extra keys to publish, for rotation.
	Key           crypto.Signer
	KeyID         string
	PublishedKeys []aauth.JWK
	// Registrar enables the HTTP endpoints; without it the provider only
	// issues through [Server.IssueAgentToken].
	Registrar Registrar
	// Attestation verifies attestation evidence; without it a request
	// carrying evidence is refused.
	Attestation AttestationVerifier
	// Replay remembers naming-JWT identifiers; nil uses an in-process
	// cache.
	Replay ReplayCache
	// Limiter, when set, limits issuance per presented key ("issue:"),
	// refreshes per durable key ("refresh:"), and sub-agent requests per
	// parent ("subagent:"), answered 429 rate_limited with Retry-After.
	// It is checked after the request authenticates and before the
	// Registrar is asked.
	Limiter aauth.Limiter
	// OnIssue is called for every token issued.
	OnIssue func(ctx context.Context, t IssuedToken)
	// TokenTTL is the default token lifetime (default one hour).
	TokenTTL time.Duration
	// Paths overrides endpoint paths; Metadata supplies display members
	// and callback_endpoint, event_endpoint, and localhost_callback_allowed.
	Paths    Paths
	Metadata aauth.AgentProviderMetadata
	// SignatureWindow is the HTTP signature validity window.
	SignatureWindow time.Duration
	// MaxNamingJWTLifetime is the furthest ahead a refresh's naming JWT may
	// expire (default [DefaultMaxNamingJWTLifetime]). A longer lifetime is
	// refused, not shortened: replay state is kept until the JWT expires.
	MaxNamingJWTLifetime time.Duration
	// HTTPClient makes outbound requests (revocation); nil uses
	// aauth.DiscoveryClient, which reaches only public https destinations.
	HTTPClient *http.Client
	// Logger receives operational errors; nil discards them.
	Logger *slog.Logger
	// Now returns the current time; nil means time.Now.
	Now func() time.Time
}

type IssueRequest struct {
	// Key is the presented public key; the token's cnf.jwk.
	Key aauth.JWK
	// Body is the request body (the AP's own enrollment fields).
	Body json.RawMessage
	// Attestation is the verified platform attestation, when the body
	// carried one (bootstrap §5).
	Attestation *Attestation
}

type IssuedToken struct {
	Token  string
	Claims *aauth.AgentClaims
}

type MemoryReplayCache struct {
	// MaxEntries bounds the cache; zero means [DefaultReplayCacheEntries].
	MaxEntries int
	// contains filtered or unexported fields
}

type Paths struct {
	JWKS     string
	Token    string // hwk: enrollment and single-key refresh (bootstrap §8.2)
	Refresh  string // jkt-jwt: two-key refresh (bootstrap §8.1)
	Subagent string // jwt: sub-agent issuance under a hosted AP (bootstrap §9.2)
}

type RefreshRequest struct {
	Durable     aauth.JWK
	DurableID   string // urn:jkt:sha-256:...
	Ephemeral   aauth.JWK
	Body        json.RawMessage
	Attestation *Attestation
}

type Registrar interface {
	// AuthorizeIssue authorizes an hwk-signed issuance request; r is the
	// HTTP request, so the application can read its own authentication
	// (a session, a bearer credential) from it.
	AuthorizeIssue(ctx context.Context, r *http.Request, req *IssueRequest) (*Registration, error)
	// AuthorizeRefresh authorizes a two-key refresh: look up the
	// enrollment by DurableID and re-check posture.
	//
	// The provider remembers the naming JWT's identifier only after this
	// returns successfully, so that a key that is not enrolled cannot fill
	// the replay cache. A captured request that is replayed therefore
	// reaches AuthorizeRefresh again before the replay is rejected: the
	// method must be a side-effect-free lookup, or idempotent, and must not
	// consume one-time state.
	AuthorizeRefresh(ctx context.Context, req *RefreshRequest) (*Registration, error)
	// AuthorizeSubagent applies sub-agent policy: whether this parent may
	// spawn, how many may be live, for how long.
	AuthorizeSubagent(ctx context.Context, req *SubagentRequest) (*SubagentGrant, error)
}

type Registration struct {
	// Name is the agent identifier's local part (the domain is the
	// provider's); it must be stable for the agent install (bootstrap §6).
	Name string
	// PS is the person server, carried as the ps claim.
	PS string
	// TTL is the token lifetime (default Config.TokenTTL, at most 24h).
	TTL time.Duration
}

type ReplayCache interface {
	// Remember records key until exp and reports whether it was new.
	Remember(ctx context.Context, key string, exp time.Time) (bool, error)
}

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

type SubagentGrant struct {
	// Discriminator overrides the requested one; empty keeps it, or
	// generates one when none was requested.
	Discriminator string
	// TTL is the lifetime; never later than the parent's token.
	TTL time.Duration
}

type SubagentRequest struct {
	Parent        *aauth.AgentClaims
	Key           aauth.JWK
	Discriminator string
}

type TokenResponse struct {
	AgentToken string `json:"agent_token"`
	ExpiresIn  int64  `json:"expires_in"`
}