apikey

type Config struct {
	Store Store
	Log   authlog.Log

	// TouchInterval bounds how often a key's last-used time is written.
	//
	// Recording it on every request would turn a read into a write on the
	// hottest path a machine integration has, for a field nobody reads more
	// precisely than "today". Five minutes is close enough to answer "is this
	// key still in use" and cheap enough to be free.
	TouchInterval time.Duration

	// DefaultTTL bounds a key with no explicit expiry. Zero means keys can be
	// minted that never expire, which is sometimes what a deployment wants and
	// should always be a decision rather than a default.
	DefaultTTL time.Duration

	// Limiter and FailureLimit bound how many times one key identifier may be
	// presented wrongly.
	//
	// Both or neither; nil is a manager nobody wired a limiter into. What this
	// stops is somebody grinding secrets against a key id they have learned —
	// the id is the public half and turns up in logs and configuration, and
	// without a limit the only thing between it and the secret is how fast they
	// can ask.
	//
	// A success clears the window, so an integration that was misconfigured for
	// a minute is not locked out for the rest of the hour once it is fixed.
	Limiter      *throttle.Limiter
	FailureLimit throttle.Limit

	// Cache keeps verified keys in memory, and is told to stop.
	//
	// Nil, the default, reads the row on every request. A cache built by
	// [NewKeyCache] means most requests do not, and that a revocation or a
	// rotation reaches every replica on the transaction that performed it.
	Cache *KeyCache

	// FailureCache keeps the "no failures for this key" answer in memory.
	//
	// Nil, the default, counts rows on every request — including every
	// successful one, since the limit is checked before the key is looked up. A
	// cache built by [NewFailureCache] means the integration that never gets its
	// key wrong stops paying for the caller who does.
	//
	// Separate from [Config.Cache] because they answer different questions and
	// are withdrawn by different writes, not because a deployment would sensibly
	// want one and not the other: [auth.New] builds both or neither.
	FailureCache *FailureCache

	Now func() time.Time
}

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

type FailureCacheConfig struct {
	// TTL is how long "no failures" may be reused with no invalidation
	// arriving. Zero or less caches nothing.
	TTL time.Duration

	// MaxEntries bounds the map. Zero takes the package default.
	MaxEntries int

	// Now is the clock, for tests.
	Now func() time.Time
}

type Key struct {
	ID        uuid.UUID
	TenantID  uuid.UUID
	AccountID uuid.UUID

	// Kind is whose key it is: an integration's, with a service account of its
	// own, or a person's.
	Kind Kind

	Name string

	// KeyID is the public half. It is what a person sees in a list, what a log
	// line names, and what a rate limit counts against — including for keys
	// that do not exist, which is the case that matters.
	KeyID      string
	SecretHash []byte

	// Scopes are permission keys, the same ones RBAC uses. Sharing the
	// vocabulary is what keeps a key from ever being able to express more than
	// a role could.
	Scopes []string
	// CIDRAllowList restricts where the key may be used from. Empty means
	// anywhere.
	CIDRAllowList []netip.Prefix

	CreatedAt          time.Time
	CreatedByAccountID *uuid.UUID
	ExpiresAt          *time.Time
	LastUsedAt         *time.Time
	RevokedAt          *time.Time
}

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

type KeyCacheConfig struct {
	// TTL is how long a verified key may be reused with no invalidation
	// arriving. Zero or less caches nothing.
	TTL time.Duration

	// MaxEntries bounds the map. Zero takes the package default.
	MaxEntries int

	// Now is the clock, for tests.
	Now func() time.Time
}

type Kind string

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

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

type MintInput struct {
	TenantID uuid.UUID
	// AccountID is the account the key acts as. Every write the key makes is
	// stamped with it, so a machine's changes are attributable to something
	// rather than to nobody.
	//
	// For an integration this is a service account of its own, which is what
	// makes "the integration did it" a thing the audit trail can say. For a
	// personal key it is the person, and must equal CreatedByAccountID.
	AccountID uuid.UUID

	// Kind is whose key this is. The zero value is an integration key, because
	// that is the one with the sharper failure mode if it is wrong: a personal
	// key mistaken for an integration acts as a person who can be deactivated,
	// which fails safely, while the reverse would silently widen what the key
	// can reach.
	Kind Kind

	Name string

	Scopes        []string
	CIDRAllowList []netip.Prefix
	ExpiresAt     *time.Time

	// CreatedByAccountID is the person who minted it.
	CreatedByAccountID *uuid.UUID
}

type Minted struct {
	Key *Key
	// Secret is the whole value to hand over. It is not recoverable: showing
	// it again would mean storing something worth stealing.
	Secret string
}

type Store interface {
	Insert(ctx context.Context, k *Key) error
	// ByKeyID reads a key by its public half, or nil when there is none.
	ByKeyID(ctx context.Context, keyID string) (*Key, error)
	// Find reads a key by identifier within a tenant.
	Find(ctx context.Context, tenantID, id uuid.UUID) (*Key, error)
	// TouchLastUsed records that a key was used.
	TouchLastUsed(ctx context.Context, id uuid.UUID, at time.Time) error
	// Revoke kills a key.
	Revoke(ctx context.Context, tenantID, id uuid.UUID, at time.Time) error
	// SetExpiry ends a key at a chosen time, for a rotation's overlap window.
	SetExpiry(ctx context.Context, tenantID, id uuid.UUID, at time.Time) error
	// List returns a tenant's keys, newest first.
	List(ctx context.Context, tenantID uuid.UUID) ([]*Key, error)

	// InTx runs fn inside one transaction, joining one already in progress.
	//
	// Here for the reason [session.Store] has it: a revocation and the
	// notification that withdraws the cached copy of what was revoked have to
	// commit together, or a replica can be told to forget something that was
	// never revoked — or, worse, not told about one that was.
	InTx(ctx context.Context, fn func(ctx context.Context) error) error
}