key

type APIKey struct {
	ID         id.KeyID          `json:"id"`
	TenantID   id.TenantID       `json:"tenant_id"`
	Name       string            `json:"name"`
	Prefix     string            `json:"prefix"` // "nxs_" + first 8 chars (for display)
	Hash       string            `json:"-"`      // SHA-256 of the raw key, hex (never exposed). The raw key carries 256 random bits, so an unsalted hash is enough.
	Scopes     []string          `json:"scopes"` // ["completions", "embeddings", "models"]
	Status     Status            `json:"status"`
	ExpiresAt  *time.Time        `json:"expires_at,omitempty"`
	LastUsedAt *time.Time        `json:"last_used_at,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
	CreatedAt  time.Time         `json:"created_at"`
}

type CreateInput struct {
	TenantID string            `json:"tenant_id"`
	Name     string            `json:"name"`
	Scopes   []string          `json:"scopes,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
	// ExpiresAt, when set, must be in the future.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

type Events interface {
	EmitKeyCreated(ctx context.Context, keyID id.KeyID, tenantID id.TenantID)
	EmitKeyRevoked(ctx context.Context, keyID id.KeyID)
}

type ListOptions struct {
	TenantID string `json:"tenant_id,omitempty"`
	Status   Status `json:"status,omitempty"`
	Limit    int    `json:"limit,omitempty"`
	Cursor   string `json:"cursor,omitempty"`

	// Now is the clock reading the status filter derives expiry against.
	// The zero value means the wall clock. key.Service sets it from its own
	// clock, so ListPage and Count agree with Get under WithClock.
	Now time.Time `json:"-"`
}

type ListResult struct {
	Items      []*APIKey `json:"items"`
	NextCursor string    `json:"next_cursor"`
}

type Option func(*service)

type Service interface {
	// Create generates a new API key. Returns the full key (only time it's visible).
	Create(ctx context.Context, input *CreateInput) (*APIKey, string, error)

	// Ensure makes sure the key whose raw value is rawKey exists, so an
	// operator can supply the first admin key from config. A key with that
	// value, found by prefix and a constant-time hash compare, is returned
	// with created false, in any status: a revoked key stays revoked.
	// Otherwise Ensure checks in as Create does (tenant exists, scopes known,
	// expiry), stores the key and reports it. A rawKey that is not "nxs_"
	// and 64 lowercase hex digits gives ErrInvalid. No error carries rawKey.
	Ensure(ctx context.Context, rawKey string, in *CreateInput) (k *APIKey, created bool, err error)

	// Validate checks a raw API key and returns the associated key record.
	Validate(ctx context.Context, rawKey string) (*APIKey, error)

	// Get returns one key, with its expiry derived: an active key whose
	// ExpiresAt has passed reads expired. Every store derives expiry the same
	// way in its List and Count, so the status filter and the items agree.
	Get(ctx context.Context, id string) (*APIKey, error)

	// Revoke deactivates an API key.
	Revoke(ctx context.Context, id string) error

	// List returns keys for a tenant (hashed, never shows full key).
	List(ctx context.Context, tenantID string) ([]*APIKey, error)

	// ListPage returns one page of keys, newest first. The store applies the
	// status filter with expiry derived, and every item carries its effective
	// status: an active key whose ExpiresAt has passed is expired.
	ListPage(ctx context.Context, opts *ListOptions) (*ListResult, error)

	// Count returns how many keys match opts, with the same filter semantics
	// as ListPage. Limit and Cursor are ignored.
	Count(ctx context.Context, opts *ListOptions) (int, error)

	// Rotate creates a replacement for an active key and revokes the old one.
	// It is not atomic across backends: if the revoke fails, the new key is
	// revoked too (best effort) and the error is returned.
	Rotate(ctx context.Context, oldKeyID string) (*APIKey, string, error)
}

type Status string

type Store interface {
	// Insert stores k. A key whose Hash is already stored is refused with
	// ErrDuplicate, and nothing is written: the hash is unique in every store.
	Insert(ctx context.Context, k *APIKey) error
	FindByID(ctx context.Context, id string) (*APIKey, error)
	// FindByPrefix returns every key whose prefix is prefix, in any status.
	// Prefixes are not unique, so a caller must check the hash. None found
	// is an empty slice and a nil error.
	FindByPrefix(ctx context.Context, prefix string) ([]*APIKey, error)
	// TouchLastUsed sets only LastUsedAt, so it can never undo a concurrent
	// revoke. It returns ErrNotFound when the key does not exist.
	TouchLastUsed(ctx context.Context, id string, at time.Time) error
	Update(ctx context.Context, k *APIKey) error
	Delete(ctx context.Context, id string) error
	ListByTenant(ctx context.Context, tenantID string) ([]*APIKey, error)
	List(ctx context.Context, opts *ListOptions) (*ListResult, error)
	// Count returns how many keys match opts, with List's filter semantics.
	// Limit and Cursor are ignored. nil opts counts every key.
	Count(ctx context.Context, opts *ListOptions) (int, error)
}

type TenantFinder interface {
	FindByID(ctx context.Context, id string) (*tenant.Tenant, error)
}