keys

package
v3.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package keys keeps the owner key and the agent keys of each instance in the key file of the CLI, keys.json in the state folder.

The file has mode 0600, in a folder with mode 0700. Its accounts have the names of the legacy keychain items: "owner@<instance>" and "agent:<name>@<instance>". Each write is atomic: a temporary file in the same folder, an fsync, and a rename. A lock on the file keys.json.lock lets one process at a time read or change the file. Thus two CLIs or bridges at the same time do not lose a key.

mai 3.0 and 3.1 kept the keys in the system keychain, and the manifest of the state folder recorded each item. When the key file has no key for an account, Get reads the legacy item, writes the key to the key file, and then deletes the legacy item.

On a self-run instance, a program that can use the Docker socket controls mai fully. Thus the key file gives the same protection as the keychain, with no prompt.

Index

Constants

View Source
const FileName = "keys.json"

FileName is the name of the key file in the state folder.

Variables

View Source
var ErrBusy = errors.New("keys: the key file is busy")

ErrBusy means that a different process held the lock of the key file for more than the wait. A subsequent try can succeed.

View Source
var ErrNotFound = errors.New("keys: no key for the account")

ErrNotFound means that the key file and the legacy keychain have no key for the account.

Functions

func AgentAccount

func AgentAccount(instance, agent string) string

AgentAccount is the account of the key of one agent of an instance.

func InstanceOf

func InstanceOf(account string) string

InstanceOf gives the instance of an account: the text after the last "@". It gives "" for an account with no "@".

func OwnerAccount

func OwnerAccount(instance string) string

OwnerAccount is the account of the owner key of an instance.

Types

type Accepts

type Accepts func(account, key string) (bool, error)

Accepts tells if the server accepts the key of the account. It gives an error when it cannot tell, for example when the server does not run.

type Conflict

type Conflict struct {
	Account string
	// Checked tells if the check of the server occurred. When it is false, the other fields
	// tell nothing about the server.
	Checked bool
	// FileAccepted and LegacyAccepted tell if the server accepts the key of the key file and
	// the key of the legacy item.
	FileAccepted, LegacyAccepted bool
	// Err is the error of the check of the server, or nil.
	Err error
}

Conflict is a legacy item whose key is not the key of the key file, with the result of the check of the server. The legacy item and the key of the key file stay.

type File

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

File is the key file of the CLI. Make it with Open or Default.

func Default

func Default() (*File, error)

Default returns the key file in the state folder of the CLI, with the system keychain as the legacy keychain. With MAI_HOME, the key file has no legacy keychain, because the items of the keychain are of the home of the user and not of that folder.

func Open

func Open(dir string, legacy keychain.Store) *File

Open returns the key file in the folder dir. legacy is the keychain of mai 3.0 and 3.1, or nil for no move of legacy items.

func (*File) Accounts

func (f *File) Accounts() ([]string, error)

Accounts gives each account of the key file, sorted.

func (*File) Add

func (f *File) Add(account, key string) (stored string, added bool, err error)

Add writes the key of the account to the key file only when the file has no key for the account. The check and the write occur with one lock. Add gives the key that the file has after the call, and added tells if it is key. Thus Add never replaces a key that a different process wrote.

func (*File) Candidates

func (f *File) Candidates(instance string, recorded []string) ([]string, error)

Candidates gives each account of the instance that can have a legacy keychain item, sorted: the owner account, each account in recorded, each account that the manifest in the folder of the key file records for the instance, and each account of the instance in the key file. It ignores an account of recorded with a different instance. Thus a command finds the legacy item of an agent through its record, also when the caller gives no record.

func (*File) Check

func (f *File) Check() error

Check examines the key file and its folder, and reads no key. It gives nil when the file does not exist. "mai doctor" uses it.

func (*File) Delete

func (f *File) Delete(account string) error

Delete removes the key of the account from the key file. It gives ErrNotFound when the key file has no key for the account. It does not change the legacy keychain.

func (*File) DeleteInstance

func (f *File) DeleteInstance(instance string) ([]string, error)

DeleteInstance removes each key of the instance from the key file, and gives the accounts that it removed, sorted. The keys of the other instances stay.

func (*File) DeleteLegacy

func (f *File) DeleteLegacy(account string) error

DeleteLegacy removes the legacy keychain item of the account. An item that does not exist is not an error.

func (*File) Get

func (f *File) Get(account string) (string, error)

Get gives the key of the account. When the key file has no key for the account, Get moves the legacy keychain item of the account to the key file. It gives ErrNotFound when no key exists. When no keychain is available, Get gives ErrNotFound only when the manifest records no legacy item for the account. mai 3.0 and 3.1 did not operate with no keychain, thus then no legacy item exists.

func (*File) Has

func (f *File) Has(account string) (bool, error)

Has tells if the key file has a key for the account. It does not read the legacy keychain.

func (*File) HasLegacy

func (f *File) HasLegacy() bool

HasLegacy tells if the key file has a legacy keychain.

func (*File) HasLegacyItem

func (f *File) HasLegacyItem(account string) (bool, error)

HasLegacyItem tells if the account has a legacy keychain item. It reads no secret.

func (*File) LegacyItems

func (f *File) LegacyItems(accounts []string) ([]string, error)

LegacyItems gives each account of accounts that has a legacy keychain item, and reads no secret. When the legacy keychain is not available, the error is keychain.ErrUnavailable.

func (*File) MoveAll

func (f *File) MoveAll(accounts []string, accepts Accepts) (MoveReport, error)

MoveAll moves the legacy keychain item of each account to the key file. When the key file has a key for the account of a legacy item, also a key that a different process wrote during the move, MoveAll deletes the legacy item only when it holds the same key, or when accepts tells that the server accepts the key of the key file and refuses the key of the legacy item. When accepts tells that the server accepts only the key of the legacy item, MoveAll writes that key to the key file and deletes the legacy item. Else the legacy item stays, and the report has a conflict. When the delete of a legacy item fails, the report has a stay. accepts can be nil. The error joins the failure of each account.

func (*File) OfInstance

func (f *File) OfInstance(instance string) ([]string, error)

OfInstance gives each account of the instance in the key file, sorted.

func (*File) Path

func (f *File) Path() string

Path is the location of the key file.

func (*File) Peek added in v3.3.0

func (f *File) Peek(account string) (string, error)

Peek gives the key of the account in the key file, for a command that changes nothing. It does not read the legacy keychain, and it makes no file and no folder. It gives ErrNotFound when the key file has no key for the account.

func (*File) RemoveEmpty

func (f *File) RemoveEmpty() ([]string, error)

RemoveEmpty removes the key file and its lock file when the key file holds no key. The check and the remove of the key file occur with the lock. Thus a key that a different process writes before the remove stays. RemoveEmpty gives the accounts of a key file that stays. After the remove, a process that waited for the lock writes a new key file.

func (*File) Set

func (f *File) Set(account, key string) error

Set writes the key of the account to the key file.

type LegacyError

type LegacyError struct {
	Account string
	Err     error
}

LegacyError means that the key file has no key for the account, and that the read of its legacy keychain item failed, for example because the user refused the prompt of macOS. It is not ErrNotFound: the legacy item can hold the key. A keychain that is not available gives a LegacyError only when the manifest records a legacy item for the account. The text of the error gives the step for the user.

func (*LegacyError) Error

func (e *LegacyError) Error() string

func (*LegacyError) Unwrap

func (e *LegacyError) Unwrap() error

type ModeError

type ModeError struct {
	Path string
	Mode os.FileMode
}

ModeError means that a group or other users can read or change the key file. The CLI then refuses the file. The error tells the command that corrects the mode.

func (*ModeError) Error

func (e *ModeError) Error() string

type MoveReport

type MoveReport struct {
	// Moved holds each account whose key went from the keychain to the key file, and whose
	// legacy item MoveAll deleted.
	Moved []string
	// Cleaned holds each account whose legacy item MoveAll deleted, because the key file
	// had the same key, or because the server accepts the key of the key file and refuses
	// the key of the legacy item.
	Cleaned []string
	// Replaced holds each account whose key MoveAll replaced in the key file with the key of
	// the legacy item, because the server accepts the key of the legacy item and refuses the
	// key of the key file. MoveAll then deleted the legacy item.
	Replaced []string
	// Conflicts holds each legacy item that stays, because the key file has a different key
	// for its account, and nothing proves that the server accepts the key of the key file.
	// A conflict is not in the error of MoveAll.
	Conflicts []Conflict
	// Stays holds each legacy item whose delete failed, although the key file has the key of
	// its account. A stay is not in the error of MoveAll.
	Stays []Stay
	// Unavailable is true when no keychain is available. Then MoveAll moved no key.
	Unavailable bool
}

MoveReport tells what MoveAll did.

type Stay

type Stay struct {
	Account string
	// Err is the error of the delete.
	Err error
}

Stay is a legacy item that stays, because its delete failed. The key file has the key of its account.

Jump to

Keyboard shortcuts

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