access

Documentation

Overview

Package access keeps the named API keys issued by the gateway.

Index

• Constants
• Variables
• func CleanAccounts(in []string) ([]string, error)
• func CleanModels(in []string) ([]string, error)
• func ConfigureLAN(on, rotate bool) error
• func Default(secret string) bool
• func LANSecret() string
• func Managed(secret string) bool
• func MigrateLegacyLANKey() error
• func MigrateLegacyLANKeyBestEffort()
• func ModelAllowed(patterns []string, id string) bool
• func Named(secret string) bool
• func Path() string
• func ReplaceAccount(pid, was, now string) (int, error)
• func Restore(keys []Key) error
• func Update(action string, in Change) (string, error)
• func Window(period string, now time.Time) (start, reset time.Time)
• func WithIdentity(ctx context.Context, who Identity) context.Context
• type Change
• type Identity
  • func Authenticate(secret string) (Identity, bool)
  • func Caller(ctx context.Context) Identity
  • func (who Identity) Allows(ids ...string) bool
  • func (who Identity) AllowsAccount(pid, ref string) bool
  • func (who Identity) Limits() []*Limit
  • func (who Identity) Restricted() bool
• type Key
  • func Export() ([]Key, error)
  • func List() ([]Key, error)
  • func (k Key) Limits() []*Limit
• type Limit
  • func (l *Limit) Limited() bool
  • func (l *Limit) Per() string
  • func (l *Limit) Valid() (*Limit, error)
  • func (l *Limit) Window(now time.Time) (start, reset time.Time)

Constants

const MaxDays = 3650

MaxDays is the longest "days" cycle, ten years.

const MaxHours = 8760

MaxHours is the longest "hours" cycle, a year; a longer one is a "days" cycle.

const MaxLimits = 5

MaxLimits is how many limits one key can have (#2227).

const Prefix = "sk-magpie-key-"

Variables

var LANChanged = func() {}

LANChanged is called after sharing is turned on or off, or its key made anew: what was given the key goes on with the one there is now (the library's MCP servers relayed to an agent in a WSL distro under NAT).

var Now = time.Now

Now is when Update sets or resets a limit. A variable for the tests.

var Periods = []string{"day", "week", "month", "days", "hours"}

Periods are the windows a limit can be set for.

Functions

func CleanAccounts

func CleanAccounts(in []string) ([]string, error)

CleanAccounts is a key's account list as kept (#905): each entry "<provider>/<account>", an account named by its stable id — or by the name it is shown by, resolved to that id, so the command line reads while the list keeps what a rename doesn't move — and a key by its fingerprint; trimmed, told apart in lower case as accounts are, each once, in the order given. Every account the entry names must be one its provider has now, so a typo can't quietly hold a key to nothing; one gone later — a key rotated, an account signed out — is kept as it is, matching nothing.

func CleanModels

func CleanModels(in []string) ([]string, error)

CleanModels is a key's model list as kept (#882): each pattern trimmed, empty and repeated ones dropped. A pattern names a provider and a model, "<provider>/<model>", every model of one, "<provider>/*", or a routing group, "group/<name>".

func ConfigureLAN

func ConfigureLAN(on, rotate bool) error

ConfigureLAN starts sharing with a named key. Rotation preserves the key's identity, name and enabled state.

func Default

func Default(secret string) bool

Default says secret is the sharing key magpie itself made (the default key ConfigureLAN keeps), whether sharing is on now or not: magpie's own, never one the user brought, so a write that keeps "a caller key of the gateway's own the user put there" must not keep it (#2545: with sharing off the key stays enabled in the store, Authenticate still took it, and Rekey could no longer bring gateway.Token back). An older magpie kept it in the settings alone; that value answers too, short of its revoked mirror.

func LANSecret

func LANSecret() string

LANSecret is the key magpie shares the gateway on the local network with (the default key ConfigureLAN made), for an agent of this computer's that reaches it from beyond loopback — one in a WSL distro under NAT, whose requests the gateway takes only with a named key; "" while the gateway isn't shared, or that key is off.

func Managed

func Managed(secret string) bool

func MigrateLegacyLANKey

func MigrateLegacyLANKey() error

MigrateLegacyLANKey makes the old Settings key a normal, revocable caller key. Keep LANKey for older Magpie versions; LANKeyID marks a completed migration so the retained credential cannot resurrect a removed key.

func MigrateLegacyLANKeyBestEffort

func MigrateLegacyLANKeyBestEffort()

func ModelAllowed

func ModelAllowed(patterns []string, id string) bool

ModelAllowed says id ("<provider>/<model>") matches one of patterns, letter case aside; a "*" in a pattern stands for any run of characters, slashes too. No patterns allow every model.

func Named

func Named(secret string) bool

Named: secret has a named gateway key's form (sk-magpie-…), or is the key's own value a user gave it (Change.Secret), so a request from this computer with one is counted and limited as that key, as a sk-magpie- key is.

func Path

func Path() string

func ReplaceAccount

func ReplaceAccount(pid, was, now string) (int, error)

ReplaceAccount moves every key's account list from one of provider pid's keys to the fingerprint it has now (#1869: the key's value replaced in place), so a key held to it is held to it still. It returns how many keys it moved.

func Restore

func Restore(keys []Key) error

Restore replaces the gateway credentials when restoring their settings.

func Update

func Update(action string, in Change) (string, error)

Update writes the named key store atomically.

func Window

func Window(period string, now time.Time) (start, reset time.Time)

Window is the calendar window of period that now is in, in now's location: its start and when the next begins.

func WithIdentity

func WithIdentity(ctx context.Context, who Identity) context.Context

Types

type Change

type Change struct {
	Key  string `json:"key"`
	Name string `json:"name"`
	// Limit is what "limit-key" sets; nil or Unlimited takes the limit off.
	Limit *Limit `json:"limit,omitempty"`
	// Index is which of the key's limits "limit-key" sets and
	// "reset-limit-key" resets (#2227), counted from 0: one past the last
	// adds a limit, a nil Limit there removes that one. Without it,
	// "limit-key" makes Limit the key's only limit, and "reset-limit-key"
	// resets every one.
	Index *int `json:"index,omitempty"`
	// Models is what "models-key" sets; none lets the key use every model.
	Models []string `json:"models,omitempty"`
	// Accounts is what "accounts-key" sets (#905); none lets the key use
	// every account and key.
	Accounts []string `json:"accounts,omitempty"`
	// Quotas is what "quotas-key" sets (#2216).
	Quotas bool `json:"quotas,omitempty"`
	// Secret is the value "add-key" gives the new key, one its clients
	// already send (love1sbug on X: keys handed out from another gateway);
	// "" for one magpie makes.
	Secret string `json:"secret,omitempty"`
}

type Identity

type Identity struct {
	KeyID, KeyName string
	Limit          *Limit
	More           []Limit
	Models         []string
	Accounts       []string
	Quotas         bool
}

Identity is the gateway key a request came with, its budget, the models and the accounts it may use.

func Authenticate

func Authenticate(secret string) (Identity, bool)

Authenticate reloads the store so revocation takes effect in running gateways.

func Caller

func Caller(ctx context.Context) Identity

func (Identity) Allows

func (who Identity) Allows(ids ...string) bool

Allows says one of ids is among the key's models; any, for a key that lists none. The accounts a key may be held to say nothing of its models: they hold the candidates of a plan, not its models.

func (Identity) AllowsAccount

func (who Identity) AllowsAccount(pid, ref string) bool

AllowsAccount says the provider pid's account or key ref is among the key's accounts — "<provider>/<ref>", told apart in lower case, as accounts are. The list holds a key to some accounts **of the providers it names**: a provider it names no account of, the key uses as it always did, its every account and key. Any, for a key that lists none.

func (Identity) Limits

func (who Identity) Limits() []*Limit

Limits are the limits who's key holds it to, as Key.Limits.

func (Identity) Restricted

func (who Identity) Restricted() bool

Restricted says the key may use only the models or accounts it lists.

type Key

type Key struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Off    bool   `json:"off,omitempty"`
	LAN    bool   `json:"lan,omitempty"` // default key and durable migration marker
	Secret string `json:"secret,omitempty"`
	Masked string `json:"masked,omitempty"`
	// Limit is the key's own budget (#585); nil for none.
	Limit *Limit `json:"limit,omitempty"`
	// More are its limits after the first (#2227), each a window of its
	// own: a request passes only while every one has something left. A
	// key has them only beside a Limit, which an older magpie still reads.
	More []Limit `json:"moreLimits,omitempty"`
	// Models are the models the key may use (#882): "<provider>/<model>",
	// "<provider>/*" or a group's "group/<name>"; none for every model.
	Models []string `json:"models,omitempty"`
	// Accounts are the accounts and keys the key may use (#905), as
	// "<provider>/<account>": a signed-in account by its stable id, a
	// key by its fingerprint; none for every account, as keys always did.
	Accounts []string `json:"accounts,omitempty"`
	// Quotas lets a key held to a budget, models or accounts be told the
	// quotas of what it may use (#2216): the cards of the providers whose
	// every model it may use, of the accounts and keys it may use, names
	// and balances included. Off, it is told none (#1981).
	Quotas bool `json:"quotas,omitempty"`
}

func Export

func Export() ([]Key, error)

Export returns credentials only for the encrypted backup bundle.

func List

func List() ([]Key, error)

List never returns credentials; only the administrator's copy action does.

func (Key) Limits

func (k Key) Limits() []*Limit

Limits are k's limits, its Limit first; none for a key with no limit. Each holds the key on its own: a request passes only while all of them have something left.

type Limit

type Limit struct {
	Period string `json:"period"`
	// Days is a "days" limit's cycle, 1 to MaxDays; 0 for the others.
	Days int `json:"days,omitempty"`
	// Hours is an "hours" limit's cycle, 1 to MaxHours; 0 for the others.
	Hours      int     `json:"hours,omitempty"`
	Tokens     int64   `json:"tokens,omitempty"`
	Cost       float64 `json:"cost,omitempty"`
	CacheReads bool    `json:"cacheReads,omitempty"`
	// Since is magpie's, never the caller's (Update sets it): for "days"
	// and "hours", when the first cycle began, the limit set or last reset; for a
	// calendar period, when it was last reset, so a call before it in
	// the same window doesn't count. Zero for a calendar limit never
	// reset, as every limit from before #1509 is.
	Since time.Time `json:"since,omitzero"`
}

Limit is a gateway key's budget for a window: a calendar one in local time (#585), a day from midnight, a week from Monday's midnight, a month from the 1st's; or a cycle of Days days (#1509, period "days") or of Hours hours (#2102, period "hours", a subscription's 5-hour window's pace), the first from when the limit was set, each next one a cycle after the last. Tokens counts each call's uncached input, output (reasoning included) and cache writes, and its cache reads too when CacheReads is set; Cost is an estimate in US dollars at the prices magpie shows on the Usage page, not a vendor's bill. A cap of 0 is no cap; a limit with neither is no limit.

func (*Limit) Limited

func (l *Limit) Limited() bool

Limited: l caps something.

func (*Limit) Per

func (l *Limit) Per() string

Per is the window as a sentence ends it: "day", "week", "month", "10-day cycle" or "5-hour cycle".

func (*Limit) Valid

func (l *Limit) Valid() (*Limit, error)

Valid is l as it is kept: nil for no limit, an error for one that can't be. Since is left as it came; Update decides it.

func (*Limit) Window

func (l *Limit) Window(now time.Time) (start, reset time.Time)

Window is the window l counts in at now, in now's location: when it began and when the next begins. A "days" or "hours" cycle is counted in absolute time, 24h a day whatever the clocks do, so a restart or a change of time zone or summer time keeps it; one with no Since runs from the Unix epoch. A calendar window starts at Since instead when the key was reset in it.