apikeys

package
v0.40.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrAPIKeyNotFound = errors.New("api key not found")

ErrAPIKeyNotFound is returned by Revoke when no key has the given id.

Functions

func GenerateAPIKey

func GenerateAPIKey() (id, rawKey string, err error)

GenerateAPIKey returns a new (id, rawKey) pair. The rawKey is the secret the caller presents as a bearer token; the id is the public handle. Only the hash of rawKey is ever persisted.

Types

type APIKeyRecord

type APIKeyRecord struct {
	ID         string
	Label      string
	CreatedAt  time.Time
	LastUsedAt *time.Time
	RevokedAt  *time.Time

	// Scopes nil is a full-access key. A non-nil list (possibly empty)
	// limits the key to what the scopes grant.
	Scopes []string
	// EnvID limits a scoped key to one environment and its forks. Empty
	// means any environment.
	EnvID string
	// ExpiresAt is when the key stops authenticating. Nil means never.
	ExpiresAt *time.Time
	// ActorID and ActorName pin the actor every request on the key is
	// recorded as. Empty ActorID means no pinned actor.
	ActorID   string
	ActorName string
	// CreatedBy is the principal that minted the key: "master" or a key id.
	CreatedBy string

	// FirstUse is set by Authenticate on the request that used the key for
	// the first time. It is not stored.
	FirstUse bool
}

APIKeyRecord is the metadata for a single API key. It never carries the raw key or its hash — those never leave the store.

type APIKeyStore

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

APIKeyStore persists revocable API keys in Postgres. Keys are stored as SHA-256 hashes; the raw key is shown once at creation and never again.

func NewAPIKeyStore

func NewAPIKeyStore(db *sql.DB) *APIKeyStore

NewAPIKeyStore creates a Postgres-backed API key store. It shares the same *sql.DB (and therefore the same migrations) as the state store.

func (*APIKeyStore) Authenticate

func (s *APIKeyStore) Authenticate(ctx context.Context, rawToken string) (APIKeyRecord, bool)

Authenticate reports whether rawToken matches a live key: not revoked and not past its expiry. On success it returns the key's record and bumps last_used_at on a best-effort basis; a failed bump never fails authentication. Implements the APIKeyAuthenticator interface consumed by the api package's BearerAuth.

func (*APIKeyStore) Create

func (s *APIKeyStore) Create(ctx context.Context, k NewKey, now time.Time) (APIKeyRecord, string, error)

Create generates a new API key, stores its hash + metadata, and returns the record together with the raw key. The raw key is returned exactly once and cannot be recovered afterward.

func (*APIKeyStore) List

func (s *APIKeyStore) List(ctx context.Context) ([]APIKeyRecord, error)

List returns metadata for all keys (live and revoked), newest first. It never returns key hashes or raw keys.

func (*APIKeyStore) RebindEnv added in v0.38.0

func (s *APIKeyStore) RebindEnv(ctx context.Context, fromID, toID string) error

RebindEnv moves keys scoped to one environment id to another. A live migration gives the same logical environment a new id, and its invites follow it.

func (*APIKeyStore) Revoke

func (s *APIKeyStore) Revoke(ctx context.Context, id string, now time.Time) error

Revoke marks the key with the given id revoked. Revoking an already-revoked key is idempotent (no error). Returns ErrAPIKeyNotFound if no key has that id.

func (*APIKeyStore) RevokeEnv added in v0.38.0

func (s *APIKeyStore) RevokeEnv(ctx context.Context, envID string, now time.Time) error

RevokeEnv revokes every live key scoped to envID. Destroying an environment calls it, so an invite never outlives the sandbox it was for.

type NewKey added in v0.38.0

type NewKey struct {
	Label     string
	Scopes    []string
	EnvID     string
	ExpiresAt *time.Time
	ActorID   string
	ActorName string
	CreatedBy string
}

NewKey is what Create mints.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL