store

package
v0.7.11 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package store is the local knowledge store: the knowledge packs a person keeps on this machine, sealed, under the runner home the CLI and the desktop share, so that both clients list, open, attach and export the same packs.

Each pack is one directory, <runner home>/knowledge/<pack id>/:

manifest.json  the pack's own knowledge/v1 manifest, in the clear
pack.sealed    the canonical tree tar (wiki/ and sources/), sealed with
               the core's pkg/packseal under a random data key per pack
key.json       that data key as it is wrapped: by the registry the
               person is signed in to, or, signed out, by
               this machine's key in the OS keychain; and, once
               the pack is kept in Agentry, the registry's copy

No page rests in a pack's directory in the clear. A pack is opened into a directory the caller names (an export), or into a 0700 directory inside the store that the caller removes when done (a run's attachment, a build adding to the pack; OpenScratch, Scratch); a download is checked in one before it is kept. Such directories are dot-named, so List skips them, and one a process that died left behind is swept after an hour. A data key the registry unwrapped is cached in the OS keychain (the modelkey pattern), so a pack opens offline after its first opening on a machine. The registry holds what wraps the key, so a pack kept on one install opens on a fresh one after sign-in, with nothing carried between the two.

An organization's shared pack is kept the same way, its key.json naming the organization, with one difference: its data key is never cached. It is unwrapped through the organization's route every time the pack is opened, which the registry answers only while the person is an active member, so a member who is removed keeps sealed bytes they can no longer open, and a shared pack does not open offline.

Index

Constants

View Source
const (
	// Dir is the store's directory under the runner home.
	Dir = "knowledge"
	// SealedFile is a pack's sealed tree.
	SealedFile = "pack.sealed"
	// KeyFile is a pack's wrapped data key.
	KeyFile = "key.json"
	// KeySchema is key.json's format.
	KeySchema = "knowledge-key/v1"
)

The store's fixed names.

View Source
const (
	StateEmpty    = "empty"
	StateScanning = "scanning"
	StateReady    = "ready"
	StateFailed   = "failed"
)

The states a registry's pack is in.

View Source
const (
	// VoiceDir is the voice's directory under the runner home.
	VoiceDir = "voice"
	// VoiceSealedFile is the sealed VOICE.md.
	VoiceSealedFile = "voice.sealed"
	// VoiceMetaFile is the voice's record.
	VoiceMetaFile = "voice.json"
)

The voice's fixed names.

Variables

View Source
var (
	// ErrNotFound is a pack this store does not keep.
	ErrNotFound = errors.New("no knowledge pack of that name is kept on this computer")
	// ErrNameTaken is a name (or a pack) this store already keeps.
	ErrNameTaken = errors.New("a knowledge pack of that name is already kept on this computer")
	// ErrSignedOut is a registry this machine holds no credential for.
	ErrSignedOut = errors.New("not signed in")
	// ErrKeyNotYours is a wrapped key the registry would not unwrap for
	// the account signed in: wrapped for another account, under a key
	// since destroyed, or altered (404 knowledge-key-not-found).
	ErrKeyNotYours = errors.New("the wrapped key does not open for the account signed in")
	// ErrScanning is a registry's pack being scanned (409).
	ErrScanning = errors.New("the pack is being scanned in Agentry; it can be downloaded once the scan ends")
	// ErrRemoteNotFound is a pack the registry does not keep.
	ErrRemoteNotFound = errors.New("the registry keeps no such knowledge pack")
	// ErrRemoteNameTaken is a name the account already uses in Agentry.
	ErrRemoteNameTaken = errors.New("this account already keeps a knowledge pack of that name in Agentry")
	// ErrUnconfigured is a registry that keeps no knowledge (503).
	ErrUnconfigured = errors.New("this registry keeps no knowledge packs")
	// ErrNoKeychain is an OS keychain that is not there or is disabled.
	ErrNoKeychain = errors.New("the OS keychain is not available")
	// ErrNoEntry is a keychain account with no value.
	ErrNoEntry = errors.New("no such keychain entry")
	// ErrNotExportable is a member's export of an organization's shared
	// pack its admins have not marked exportable (403
	// knowledge-not-exportable).
	ErrNotExportable = errors.New("only the organization's admins export this pack unencrypted, unless one of them marks it exportable")
	// ErrShared is a change to an organization's shared pack from this
	// computer: its admins write it in Agentry.
	ErrShared = errors.New("it is an organization's shared pack, which its admins change in Agentry, not from this computer")
	// ErrPastAgentryCap is a pack kept here that is larger than Agentry
	// keeps (knowledge.MaxBytes): a local build may make one up to
	// knowledge.MaxLocalBytes, and it stays on this computer.
	ErrPastAgentryCap = errors.New("the pack is larger than Agentry keeps")
)
View Source
var ErrScanUnconfirmed = errors.New("its scan in Agentry could not be confirmed")

ErrScanUnconfirmed is a kept pack whose scan in Agentry this client could not confirm: the error that wraps it says why.

Functions

This section is empty.

Types

type AgentryCopy

type AgentryCopy struct {
	Registry string `json:"registry"`
	// ID is the registry's own id for the pack.
	ID string `json:"id"`
	// Digest is the tree uploaded; a local digest that differs means the
	// pack changed here since.
	Digest string `json:"digest"`
}

AgentryCopy names the copy of a pack a registry keeps.

type Entry

type Entry struct {
	// Dir is the pack's directory in the store.
	Dir      string
	Manifest knowledge.Manifest
	Key      KeyRecord
}

Entry is one pack the store keeps.

func (Entry) ID

func (e Entry) ID() string

ID is the pack's id.

func (Entry) KeyHolder

func (e Entry) KeyHolder() string

KeyHolder says what the pack's data key is wrapped to, in the words the clients show (never "safe", "secure" or "private").

func (Entry) Name

func (e Entry) Name() string

Name is the pack's name.

func (Entry) Where

func (e Entry) Where() string

Where says where the pack is kept: this computer, or this computer and Agentry, and whether it changed here since its upload.

type KeyRecord

type KeyRecord struct {
	Schema string `json:"schema"`
	// Wrapper is WrapperRegistry or WrapperMachine.
	Wrapper Wrapper `json:"wrapper"`
	// Registry is the registry that wrapped the key (WrapperRegistry): the
	// one that can unwrap it, for the account signed in when it did.
	Registry string `json:"registry,omitempty"`
	// Org is the organization whose shared pack this is, by its handle:
	// its key is the organization's, unwrapped through the organization's
	// route at every open and never cached. Empty for the person's own.
	Org        string     `json:"org,omitempty"`
	WrappedKey WrappedKey `json:"wrappedKey"`
	// Agentry is the registry's copy, once the pack is uploaded.
	Agentry *AgentryCopy `json:"agentry,omitempty"`
}

KeyRecord is key.json.

type Keychain

type Keychain interface {
	// Get is an account's value; an error wrapping ErrNoEntry when there
	// is none.
	Get(account string) (string, error)
	Set(account, value string) error
	// Delete removes an account; one that is not there is not an error.
	Delete(account string) error
}

Keychain is the OS keychain, as the store uses it (OSKeychain is the real one; a test passes a map).

type OSKeychain

type OSKeychain struct{}

OSKeychain is the OS keychain (Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux), unless AGENTRY_NO_KEYRING is set.

func (OSKeychain) Delete

func (OSKeychain) Delete(account string) error

Delete implements Keychain.

func (OSKeychain) Get

func (OSKeychain) Get(account string) (string, error)

Get implements Keychain.

func (OSKeychain) Set

func (OSKeychain) Set(account, value string) error

Set implements Keychain.

type Options

type Options struct {
	// Keys is the OS keychain (nil: no cache and no machine key).
	Keys Keychain
	// Registries resolves a signed-in client for a registry's URL (nil:
	// every registry is signed out).
	Registries Registries
	// Current is the registry new packs are wrapped by and uploaded to:
	// the one the person is signed in to. Signed out of it (or none), a
	// new pack is wrapped by this machine's key.
	Current string
	// Shared resolves a signed-in client for an organization's shared
	// packs at a registry (nil: this client keeps no shared pack).
	Shared SharedRegistries
}

Options are what a Store is given rather than finds for itself.

type Registries

type Registries func(url string) (Registry, error)

Registries resolves a client for the registry at url, signed in; an error wrapping ErrSignedOut when there is no credential for it.

type Registry

type Registry interface {
	URL() string
	Wrap(ctx context.Context, dataKey []byte) (WrappedKey, error)
	Unwrap(ctx context.Context, wk WrappedKey) ([]byte, error)
	Create(ctx context.Context, name string, wk WrappedKey) (Remote, error)
	PutTree(ctx context.Context, id string, sealed []byte) (Remote, error)
	List(ctx context.Context) ([]Remote, error)
	GetTree(ctx context.Context, id string) (sealed []byte, digest string, err error)
	Delete(ctx context.Context, id string) error
}

Registry is a registry's knowledge routes, for the account signed in to it (pkg/knowledge/remote is the client; a test fakes the routes).

type Remote

type Remote struct {
	ID         string
	Name       string
	State      string
	Bytes      int64
	Files      int
	Pages      int
	Digest     string
	WrappedKey WrappedKey
	// Scan is the registry's scan report, as it wrote it; empty until one.
	Scan    json.RawMessage
	Created time.Time
	Updated time.Time
	// Shared, Org and Exportable describe an organization's shared pack
	// the organization's handle, and whether its admins marked it
	// exportable by members.
	Shared     bool
	Org        string
	Exportable bool
}

Remote is a pack as a registry describes it (GET /knowledge/packs).

type Shared

type Shared interface {
	URL() string
	Unwrap(ctx context.Context, wk WrappedKey) ([]byte, error)
	List(ctx context.Context) ([]Remote, error)
	GetTree(ctx context.Context, id string) (sealed []byte, digest string, err error)
	// Export is the pack's tree decrypted by the registry, the canonical
	// tar, and its digest: an admin's always, a member's only once the
	// pack is marked exportable (ErrNotExportable otherwise).
	Export(ctx context.Context, id string) (tree []byte, digest string, err error)
}

Shared is a registry's routes for one organization's shared packs, for the account signed in, which the registry answers only while it is an active member of the organization (the core's /orgs/{org}/knowledge/).

type SharedRegistries

type SharedRegistries func(url, org string) (Shared, error)

SharedRegistries resolves a client for org's shared packs at the registry at url, signed in; an error wrapping ErrSignedOut when there is no credential for it.

type Store

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

Store is the local knowledge store under one runner home.

func New

func New(home string, opts Options) *Store

New is the store under the runner home.

func (*Store) AgentryScan

func (s *Store) AgentryScan(ctx context.Context, name, digest string) (json.RawMessage, error)

AgentryScan is the scan record of the kept pack name as the registry that keeps its copy reports it now. The record in a pack's manifest.json is only a claim (knowledge.Scan): this asks the registry. It answers the record only when the copy there is this pack's tree: the pack was uploaded to or downloaded from that registry (its own, or its organization's for a shared pack), is ready there with digest, the tree the caller opened and verified, and has not changed here since. A pack kept on this computer only has no record to confirm: nil, and no error. Otherwise it is an error wrapping ErrScanUnconfirmed, saying why, and the caller treats the pack as not scanned.

func (*Store) Cached

func (s *Store) Cached(id string) bool

Cached says whether a pack's data key is cached here, from its presence marker alone, so the key never enters the process to answer it: the desktop's "opens offline".

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, name string, everywhere bool) (Entry, error)

Delete removes the kept pack name and its cached key; with everywhere, the copy Agentry keeps as well, first, so a refusal there leaves the pack here. A copy Agentry no longer has is not an error.

func (*Store) DeleteVoice

func (s *Store) DeleteVoice() error

DeleteVoice removes this computer's voice and its cached key.

func (*Store) Download

func (s *Store) Download(ctx context.Context, name string) (Entry, error)

Download keeps the pack named name from the current registry: its sealed tree as the registry holds it, opened with the key the registry unwraps and checked in full, then kept here under that wrapped key. A pack kept here with the same id is replaced; another pack of that name is not.

func (*Store) DownloadShared

func (s *Store) DownloadShared(ctx context.Context, org, name string) (Entry, error)

DownloadShared keeps the pack named name that org shares at the current registry: its sealed tree, opened with the key the organization's route unwraps and checked in full, then kept here under that wrapped key and the organization's name. Nothing of the key is cached; every later open asks the registry again. A pack kept here with the same id is replaced, as a download replaces one; another pack of that name, the person's own included, is not.

func (*Store) Export

func (s *Store) Export(ctx context.Context, name, dst string) (*knowledge.Pack, error)

Export writes the pack named name, in the clear, into dst (new, or an empty directory), and returns it loaded and verified. The person's own pack is opened here. An organization's shared pack is exported by the registry, which decides whether this person may (its admins always, a member only once the pack is marked exportable; ErrNotExportable otherwise), and its tree is the one Agentry keeps now.

func (*Store) Find

func (s *Store) Find(name string) (Entry, error)

Find is the pack named name.

func (*Store) Keep

func (s *Store) Keep(ctx context.Context, packDir string) (Entry, error)

Keep seals the pack at packDir into the store under a new data key, wrapped by the current registry, or signed out by this machine's key. A pack with no id is given one. The pack directory itself is not changed.

func (*Store) KeepVoice

func (s *Store) KeepVoice(ctx context.Context, text []byte, src voice.Source, by *voice.Creator, now time.Time) (v Voice, created bool, err error)

KeepVoice keeps text as this computer's voice, in place of the one it keeps, if any. A new version keeps the voice's id, its data key, its always-attach flag and when it was first made; the first voice is made with always-attach on, and created says it was the first.

func (*Store) List

func (s *Store) List() ([]Entry, error)

List is every pack the store keeps, by name. An entry that cannot be read is left out and named in the error, beside the entries that can.

func (*Store) Open

func (s *Store) Open(ctx context.Context, name, dst string) (*knowledge.Pack, error)

Open writes the pack named name, in the clear, into dst (new, or an empty directory) and returns it loaded and verified. This is the one way a kept pack's pages leave the store: into a run's copy, or an export.

func (*Store) OpenScratch

func (s *Store) OpenScratch(ctx context.Context, name string) (p *knowledge.Pack, done func(), err error)

OpenScratch opens the pack named name into a private directory inside the store, for a run to copy into its own directory, and returns it with the function that removes it. The pack's pages rest in the clear there only until done is called (a run calls it at teardown).

func (*Store) OpenVoice

func (s *Store) OpenVoice(ctx context.Context) ([]byte, Voice, error)

OpenVoice is this computer's voice and its text, opened into memory and held to the digest its record names.

func (*Store) Reseal

func (s *Store) Reseal(ctx context.Context, name, packDir string) (Entry, error)

Reseal replaces the tree of the kept pack name with the pack at packDir (an extended copy of it: the same id or none, the same name), under the same data key, so its wrapped key, and a copy the registry keeps, still fit.

func (*Store) Rewrap

func (s *Store) Rewrap(ctx context.Context) ([]string, error)

Rewrap moves every pack wrapped by this machine's key to the current registry's wrapper (at the next sign-in), and answers their names. Signed out, it does nothing.

func (*Store) Scratch

func (s *Store) Scratch() (dir string, done func(), err error)

Scratch is a fresh 0700 directory inside the store for a pack in the clear while something works on it (the Creator making a pack or adding to a kept one), and the function that removes it. Until that function is called the directory is held: no sweep in this process removes it, and it is touched as time passes so that no other process's does; once it returns, nothing in this process touches that path again. A build may run for an hour or more, and until it applies what the Creator wrote its working copy reads as old as the build: a sweep in that time (a Download in the desktop beside a build, another command's build or run) would take it for a leftover and remove it under the build.

func (*Store) SetVoiceAttach

func (s *Store) SetVoiceAttach(on bool) (Voice, error)

SetVoiceAttach sets this computer's voice's always-attach flag.

func (*Store) Upload

func (s *Store) Upload(ctx context.Context, name string) (Entry, Remote, error)

Upload sends the kept pack name to the current registry, sealed and with its wrapped key as they are, and records the registry's copy. A pack wrapped by this machine's key is rewrapped first. The registry scans what it receives: the answer is the pack as it stands there.

func (*Store) Voice

func (s *Store) Voice() (Voice, error)

Voice is the record of the voice this computer keeps, or voice.ErrNoVoice.

type Voice

type Voice struct {
	Dir  string
	Meta voice.Meta
	Key  KeyRecord
}

Voice is the voice this computer keeps, without its text.

type WrappedKey

type WrappedKey struct {
	Kind      string `json:"kind"`
	Recipient string `json:"recipient"`
	Key       []byte `json:"key"`
}

WrappedKey is a data key as a wrapper sealed it: the registry's answer kept exactly as it came (the wrapper's kind, the recipient it names, the sealed bytes), or this machine's.

type Wrapper

type Wrapper string

Wrapper is what a pack's data key is wrapped by.

const (
	// WrapperRegistry is a key the registry wrapped (POST
	// /knowledge/keys/wrap): the deployment's key on a core registry, the
	// account's certificate on SecureAgentry.
	WrapperRegistry Wrapper = "registry"
	// WrapperMachine is a key this machine wrapped, signed out.
	WrapperMachine Wrapper = "machine"
)

Jump to

Keyboard shortcuts

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