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
- Variables
- type AgentryCopy
- type Entry
- type KeyRecord
- type Keychain
- type OSKeychain
- type Options
- type Registries
- type Registry
- type Remote
- type Shared
- type SharedRegistries
- type Store
- func (s *Store) AgentryScan(ctx context.Context, name, digest string) (json.RawMessage, error)
- func (s *Store) Cached(id string) bool
- func (s *Store) Delete(ctx context.Context, name string, everywhere bool) (Entry, error)
- func (s *Store) DeleteVoice() error
- func (s *Store) Download(ctx context.Context, name string) (Entry, error)
- func (s *Store) DownloadShared(ctx context.Context, org, name string) (Entry, error)
- func (s *Store) Export(ctx context.Context, name, dst string) (*knowledge.Pack, error)
- func (s *Store) Find(name string) (Entry, error)
- func (s *Store) Keep(ctx context.Context, packDir string) (Entry, error)
- func (s *Store) KeepVoice(ctx context.Context, text []byte, src voice.Source, by *voice.Creator, ...) (v Voice, created bool, err error)
- func (s *Store) List() ([]Entry, error)
- func (s *Store) Open(ctx context.Context, name, dst string) (*knowledge.Pack, error)
- func (s *Store) OpenScratch(ctx context.Context, name string) (p *knowledge.Pack, done func(), err error)
- func (s *Store) OpenVoice(ctx context.Context) ([]byte, Voice, error)
- func (s *Store) Reseal(ctx context.Context, name, packDir string) (Entry, error)
- func (s *Store) Rewrap(ctx context.Context) ([]string, error)
- func (s *Store) Scratch() (dir string, done func(), err error)
- func (s *Store) SetVoiceAttach(on bool) (Voice, error)
- func (s *Store) Upload(ctx context.Context, name string) (Entry, Remote, error)
- func (s *Store) Voice() (Voice, error)
- type Voice
- type WrappedKey
- type Wrapper
Constants ¶
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.
const ( StateEmpty = "empty" StateScanning = "scanning" StateReady = "ready" StateFailed = "failed" )
The states a registry's pack is in.
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 ¶
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") // 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") )
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.
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.
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
// 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 ¶
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.
Org string
Exportable bool
}
Remote is a pack as a registry describes it (GET /knowledge/packs).
type Shared ¶
type Shared interface {
// 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 ¶
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 (*Store) AgentryScan ¶
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 ¶
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 ¶
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 ¶
DeleteVoice removes this computer's voice and its cached key.
func (*Store) Download ¶
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 ¶
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 ¶
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) Keep ¶
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 ¶
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 ¶
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 ¶
OpenVoice is this computer's voice and its text, opened into memory and held to the digest its record names.
func (*Store) Reseal ¶
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 ¶
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 ¶
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 ¶
SetVoiceAttach sets this computer's voice's always-attach flag.
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" )