@voxgig/sdkgen 4.19.1 → 4.21.0

package/project/.sdk/tm/go/feature/secrets/plugin/host.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/host.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* The host: the lifecycle state machine (§5), extension points (§6), and
  * resource capture (§8).
@@ -393,6 +393,30 @@ func (i *Inst) Export(key string, value any) { i.e.exports[key] = value }
 // Provides declares what this instance can do for others (§11.1).
 func (i *Inst) Provides(p Provided) { i.e.provides = append(i.e.provides, p) }
 
+// Capability is WHICH provider this instance is bound to for name
+// (§11.1), as a ref, or "" when nothing provides it.
+//
+// §11.1 says "the first is bound, and inst.capability(name) returns it",
+// and §11.3 gives the case that needs it: a plugin that works without
+// metrics and uses metrics when it is there has to be able to ask.
+// Host.Capability answers with the live providers RANKED -- not with the
+// one THIS instance took, and §11.4's reluctant rebinding makes those
+// differ: a better-ranked newcomer tops the ranking while the consumer
+// keeps what it had.
+//
+// A REF, not the instance: every port can return a string and a corpus
+// entry can assert on one. The selection is REMEMBERED, because this is
+// the instance asking; `remember` is false only for questions asked
+// ABOUT an instance, where answering must not create a binding.
+func (i *Inst) Capability(name string) string {
+	for _, req := range Requirements(i.e.Options) {
+		if req.Name == name {
+			return i.h.chosen(i.e, req, true)
+		}
+	}
+	return ""
+}
+
 type Position struct {
 	Index     int  `json:"index"`
 	Count     int  `json:"count"`

package/project/.sdk/tm/go/feature/secrets/plugin/order.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/order.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Ordering (§7) — one rule, one place.
  *

package/project/.sdk/tm/go/feature/secrets/plugin/point.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/point.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Extension points (§6). Three kinds, chosen because they are what the
  * two existing systems actually needed, and no more.

package/project/.sdk/tm/go/feature/secrets/plugin/ref.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/ref.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Identity: name+tag, written `name$tag` (§4).
  *

package/project/.sdk/tm/go/feature/secrets/plugin/resolve.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/resolve.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Dynamic resolution (§10.2) — name to candidate module ids.
  *

package/project/.sdk/tm/go/feature/secrets/plugin/types.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/types.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Shared types. Deliberately small: the design's §19 budget says the
  * library owns naming, configuration, lifecycle, ordering, binding and

package/project/.sdk/tm/go/feature/secrets/plugin/util.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/util.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* The handful of helpers the port needs that the canonical gets from
  * JavaScript for free: sorted map keys (Object.keys(x).sort()), a

package/project/.sdk/tm/go/feature/secrets/plugin/version.go

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/plugin 0.1.6 (go/plugin/version.go)
-// Source: https://github.com/voxgig/plugin @ 91c4936555a4ce198669ca2c578b91e27e92e5ec  [tag: sdk-20260911-2013-0]
+// Source: https://github.com/voxgig/plugin @ 721de3a1bb5ac879b5c118dd9fc55c474a8730c4  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Versions and ranges (§11.2).
  *

package/project/.sdk/tm/go/feature/secrets/plugins/aws/aws.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/aws/aws.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/aws/aws.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The aws plugin: Secrets Manager and SSM Parameter Store, with requests
 // SigV4-signed in-tree (sigv4.go, beside this file). Needs HTTPS and

package/project/.sdk/tm/go/feature/secrets/plugins/aws/sigv4.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/aws/sigv4.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/aws/sigv4.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // AWS Signature Version 4, hand-rolled.
 //

package/project/.sdk/tm/go/feature/secrets/plugins/azuresecrets/azuresecrets.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/azuresecrets/azuresecrets.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/azuresecrets/azuresecrets.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The azuresecrets plugin: Azure Key Vault. Needs HTTPS. A port of
 // typescript/plugins/azuresecrets.ts.

package/project/.sdk/tm/go/feature/secrets/plugins/boru/boru.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/boru/boru.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/boru/boru.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The boru plugin: a boru vault through its CLI, or over `boru vault
 // serve`. Needs a child process, or HTTPS in wire mode. A port of

package/project/.sdk/tm/go/feature/secrets/plugins/doppler/doppler.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/doppler/doppler.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/doppler/doppler.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The doppler plugin: Doppler, one bulk download per config. Needs
 // HTTPS. A port of typescript/plugins/doppler.ts.

package/project/.sdk/tm/go/feature/secrets/plugins/gcpsecrets/gcpsecrets.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/gcpsecrets/gcpsecrets.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/gcpsecrets/gcpsecrets.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The gcpsecrets plugin: GCP Secret Manager. Needs HTTPS. A port of
 // typescript/plugins/gcpsecrets.ts.

package/project/.sdk/tm/go/feature/secrets/plugins/hashicorp/hashicorp.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/hashicorp/hashicorp.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/hashicorp/hashicorp.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The hashicorp plugin: HashiCorp Vault, and OpenBao. Needs HTTPS, and
 // the filesystem for a kubernetes service-account JWT. A port of

package/project/.sdk/tm/go/feature/secrets/plugins/httpjson/httpjson.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/httpjson/httpjson.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/httpjson/httpjson.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The HTTP half of every plugin that speaks to a store over the wire, in
 // one place and OUTSIDE the core: a chain of built-ins never links this

package/project/.sdk/tm/go/feature/secrets/plugins/infisical/infisical.go

@@ -1,5 +1,5 @@
-// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (go/plugins/infisical/infisical.go)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/infisical/infisical.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // The infisical plugin: Infisical. Needs HTTPS. A port of
 // typescript/plugins/infisical.ts.

package/project/.sdk/tm/go/feature/secrets/plugins/minivault/format.go

@@ -0,0 +1,493 @@
+// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/plugins/minivault/format.go)
+// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// The mini vault's file format, and the key hierarchy over it.
+//
+// A port of typescript/plugins/minivault.ts, which is canonical. The
+// bytes are the contract: a vault written by any port is read by every
+// other, and testdata/fixture.skmv pins that rather than leaving it to
+// agreement.
+//
+//	magic       4   'SKMV'
+//	version     1   Format
+//	kdf         1   1 = PBKDF2-HMAC-SHA256
+//	cipher      1   1 = AES-256-GCM
+//	reserved    1   0
+//	keycount    4   uint32
+//	per key:
+//	  id        1 + bytes      the key id, PLAINTEXT
+//	  salt      1 + bytes
+//	  iters     4              PBKDF2 rounds for this key
+//	  ring      1 + iv, 4 + bytes    sealed under the passphrase
+//	  meta      1 + iv, 4 + bytes    sealed under the vault's meta key
+//	entrycount  4   uint32
+//	per entry:
+//	  id        1 + bytes      the blinded lookup id
+//	  name      1 + iv, 4 + bytes    sealed under the vault's name key
+//	  value     1 + iv, 4 + bytes    sealed under that secret's own key
+//
+// Integers are big-endian and every length precedes its bytes, so the
+// file is written with the same two primitives it is read with.
+//
+// NOTHING OUTSIDE A KEY RECORD IS PLAINTEXT. Secret names are sealed,
+// and an entry is addressed by a blinded id derived from its own key, so
+// a restricted key finds what it was granted without the file ever
+// naming the rest. What the file does show anyone is the key ids and how
+// many secrets there are.
+package minivault
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/json"
+	"sort"
+	"strconv"
+
+	"GOMODULE/feature/secrets/sekreto"
+)
+
+const (
+	magic  = "SKMV"
+	format = 1
+
+	kdfPBKDF2    = 1
+	cipherAESGCM = 1
+)
+
+// AES-256-GCM: 32-byte keys, 12-byte nonces, 16-byte tags.
+const (
+	keyLen  = 32
+	ivLen   = 12
+	tagLen  = 16
+	saltLen = 16
+)
+
+// Iterations is the PBKDF2-HMAC-SHA256 round count when a caller names
+// none.
+const Iterations = 210000
+
+// MasterKey is the key id a vault gets when a caller names none.
+const MasterKey = "master"
+
+// Additional authenticated data. Every blob is bound to its PLACE in the
+// file, so no ciphertext can be moved: a restricted key's ring cannot be
+// relabelled as the master's, and one secret's value cannot be served
+// under a name it was never written for.
+const (
+	aadRing   = "skmv1:ring:"
+	aadMeta   = "skmv1:meta:"
+	aadName   = "skmv1:name"
+	aadSecret = "skmv1:secret:"
+)
+
+// Everything a master reaches is derived from the root key, so rotating
+// is one new random value rather than a re-wrap of each part.
+const (
+	labelNames = "skmv1:names"
+	labelMeta  = "skmv1:meta"
+	labelID    = "skmv1:id"
+)
+
+func fail(text string) error {
+	return sekreto.Fail("sekreto: minivault: " + text)
+}
+
+// idMax is the largest key id the format can record.
+//
+// `small` writes a length in ONE byte. A longer id wrapped that byte and
+// the writer then appended the whole thing, so every field after it
+// shifted: a Grant with a 300-character id replaced a working vault with
+// an unreadable one, and said nothing. Checked where an id is ACCEPTED,
+// so the refusal names the id rather than the file.
+const idMax = 255
+
+func checkid(id string, what string) error {
+	if "" == id {
+		return fail(what)
+	}
+	if idMax < len(id) {
+		cut := id
+		if 32 < len(cut) {
+			cut = cut[:32]
+		}
+		return fail("key id is longer than " + strconv.Itoa(idMax) + " bytes: " + cut + "...")
+	}
+	return nil
+}
+
+// --- keys ------------------------------------------------------------
+
+func mac(key []byte, text string) []byte {
+	h := hmac.New(sha256.New, key)
+	h.Write([]byte(text))
+	return h.Sum(nil)
+}
+
+// pbkdf2sha256 is PBKDF2 with HMAC-SHA256, in-tree.
+//
+// crypto/pbkdf2 arrived in Go 1.24 and this module targets 1.21, and the
+// no-dependency rule says a missing standard-library piece is written
+// small rather than taken from a package. RFC 8018 section 5.2, with the
+// one-block-at-a-time loop the specification states.
+func pbkdf2sha256(passphrase string, salt []byte, iters int, length int) []byte {
+	out := []byte{}
+	block := make([]byte, 4)
+
+	for counter := 1; len(out) < length; counter++ {
+		binary.BigEndian.PutUint32(block, uint32(counter))
+
+		h := hmac.New(sha256.New, []byte(passphrase))
+		h.Write(salt)
+		h.Write(block)
+		u := h.Sum(nil)
+
+		t := make([]byte, len(u))
+		copy(t, u)
+
+		for round := 1; round < iters; round++ {
+			h := hmac.New(sha256.New, []byte(passphrase))
+			h.Write(u)
+			u = h.Sum(nil)
+			for index := range t {
+				t[index] ^= u[index]
+			}
+		}
+
+		out = append(out, t...)
+	}
+
+	return out[:length]
+}
+
+// kek is the key-encryption key a passphrase unwraps a ring with.
+func kek(passphrase string, salt []byte, iters int) []byte {
+	return pbkdf2sha256(passphrase, salt, iters, keyLen)
+}
+
+// secretkey is the key one named secret's value is encrypted with.
+//
+// DERIVED, never stored, for a master: it holds the root key and so
+// reaches every name, including ones written after it was made. A
+// restricted key holds the derived keys it was granted and nothing that
+// produces another, so every other name is ciphertext to it in exactly
+// the way it is to a stranger.
+func secretkey(root []byte, name string) []byte {
+	return mac(root, aadSecret+name)
+}
+
+// entryid is where a secret lives in the file, derived from its own key
+// so that finding it needs no plaintext name. One-way: an id yields
+// nothing about the key that produced it.
+func entryid(key []byte) []byte {
+	return mac(key, labelID)
+}
+
+func random(length int) ([]byte, error) {
+	out := make([]byte, length)
+	if _, err := rand.Read(out); nil != err {
+		return nil, fail("no randomness available: " + err.Error())
+	}
+	return out, nil
+}
+
+// --- sealing ---------------------------------------------------------
+
+type sealed struct {
+	IV   []byte
+	Blob []byte
+}
+
+func gcmof(key []byte) (cipher.AEAD, error) {
+	block, err := aes.NewCipher(key)
+	if nil != err {
+		return nil, fail("bad key: " + err.Error())
+	}
+	return cipher.NewGCM(block)
+}
+
+func seal(key []byte, plain []byte, aad string) (*sealed, error) {
+	iv, err := random(ivLen)
+	if nil != err {
+		return nil, err
+	}
+
+	gcm, err := gcmof(key)
+	if nil != err {
+		return nil, err
+	}
+
+	return &sealed{IV: iv, Blob: gcm.Seal(nil, iv, plain, []byte(aad))}, nil
+}
+
+// unseal returns the plaintext, or a refusal. A GCM tag that fails to
+// verify is the only evidence there is, and it cannot tell a wrong
+// passphrase from a damaged file, so `what` names the attempt and the
+// message admits both.
+func unseal(key []byte, box *sealed, aad string, what string) ([]byte, error) {
+	if len(box.Blob) < tagLen || ivLen != len(box.IV) {
+		return nil, fail(what + ": truncated")
+	}
+
+	gcm, err := gcmof(key)
+	if nil != err {
+		return nil, err
+	}
+
+	plain, err := gcm.Open(nil, box.IV, box.Blob, []byte(aad))
+	if nil != err {
+		return nil, fail(what)
+	}
+
+	return plain, nil
+}
+
+func jsonof(plain []byte, into any, what string) error {
+	if err := json.Unmarshal(plain, into); nil != err {
+		return fail("unreadable " + what)
+	}
+	return nil
+}
+
+// --- the file --------------------------------------------------------
+
+type keyRecord struct {
+	ID    string
+	Salt  []byte
+	Iters int
+	Ring  *sealed
+	Meta  *sealed
+}
+
+type entryRecord struct {
+	ID    []byte
+	Name  *sealed
+	Value *sealed
+}
+
+type vaultFile struct {
+	Keys    []*keyRecord
+	Entries []*entryRecord
+}
+
+func (file *vaultFile) key(id string) *keyRecord {
+	for _, record := range file.Keys {
+		if id == record.ID {
+			return record
+		}
+	}
+	return nil
+}
+
+func (file *vaultFile) entry(id []byte) *entryRecord {
+	for _, record := range file.Entries {
+		if bytes.Equal(id, record.ID) {
+			return record
+		}
+	}
+	return nil
+}
+
+// reader is a cursor, so that every length check is in one place: a
+// truncated vault is refused rather than read as a short one.
+type reader struct {
+	bytes []byte
+	at    int
+	err   error
+}
+
+// take reads `length` bytes, or records the refusal.
+//
+// The bound is checked as a UINT64 against what is left, never by adding
+// it to `at` in int arithmetic. On a 32-bit target a damaged vault can
+// encode a length at or above 0x80000000, which becomes a NEGATIVE int:
+// the slice bound goes backwards and the process panics instead of
+// reporting the damaged file this function exists to report.
+func (read *reader) take64(length uint64) []byte {
+	if nil != read.err {
+		return nil
+	}
+	if uint64(len(read.bytes)-read.at) < length {
+		read.err = fail("the vault file is truncated")
+		return nil
+	}
+	out := read.bytes[read.at : read.at+int(length)]
+	read.at += int(length)
+	return out
+}
+
+func (read *reader) take(length int) []byte {
+	if 0 > length {
+		read.err = fail("the vault file is truncated")
+		return nil
+	}
+	return read.take64(uint64(length))
+}
+
+func (read *reader) u8() int {
+	out := read.take(1)
+	if nil == out {
+		return 0
+	}
+	return int(out[0])
+}
+
+// u32 is only ever a COUNT, which the caller bounds against the input
+// before it allocates. A length goes through u32len instead.
+func (read *reader) u32() int {
+	out := read.take(4)
+	if nil == out {
+		return 0
+	}
+	return int(binary.BigEndian.Uint32(out))
+}
+
+func (read *reader) u32len() uint64 {
+	out := read.take(4)
+	if nil == out {
+		return 0
+	}
+	return uint64(binary.BigEndian.Uint32(out))
+}
+
+func (read *reader) small() []byte { return read.take(read.u8()) }
+func (read *reader) large() []byte { return read.take64(read.u32len()) }
+
+func (read *reader) sealed() *sealed {
+	return &sealed{IV: read.small(), Blob: read.large()}
+}
+
+func readfile(raw []byte) (*vaultFile, error) {
+	read := &reader{bytes: raw}
+
+	if magic != string(read.take(4)) {
+		if nil != read.err {
+			return nil, read.err
+		}
+		return nil, fail("not a vault file")
+	}
+
+	version := read.u8()
+	if nil != read.err {
+		return nil, read.err
+	}
+	if format != version {
+		return nil, fail("unsupported format version: " + strconv.Itoa(version))
+	}
+
+	kdf := read.u8()
+	ciph := read.u8()
+	if nil != read.err {
+		return nil, read.err
+	}
+	if kdfPBKDF2 != kdf || cipherAESGCM != ciph {
+		return nil, fail("unsupported kdf or cipher: " + strconv.Itoa(kdf) + "/" + strconv.Itoa(ciph))
+	}
+	read.u8()
+
+	file := &vaultFile{Keys: []*keyRecord{}, Entries: []*entryRecord{}}
+
+	// A COUNT IS BOUNDED BY WHAT IS LEFT. Each record carries at least a
+	// few bytes, so a file claiming four billion of them is damaged; the
+	// loop would find that out one truncation at a time, and a caller
+	// that preallocated would not.
+	keycount := read.u32()
+	if len(raw)-read.at < keycount {
+		return nil, fail("the vault file is truncated")
+	}
+	for index := 0; index < keycount && nil == read.err; index++ {
+		file.Keys = append(file.Keys, &keyRecord{
+			ID:    string(read.small()),
+			Salt:  read.small(),
+			Iters: read.u32(),
+			Ring:  read.sealed(),
+			Meta:  read.sealed(),
+		})
+	}
+
+	entrycount := read.u32()
+	if len(raw)-read.at < entrycount {
+		return nil, fail("the vault file is truncated")
+	}
+	for index := 0; index < entrycount && nil == read.err; index++ {
+		file.Entries = append(file.Entries, &entryRecord{
+			ID:    read.small(),
+			Name:  read.sealed(),
+			Value: read.sealed(),
+		})
+	}
+
+	if nil != read.err {
+		return nil, read.err
+	}
+	if read.at != len(raw) {
+		return nil, fail("the vault file has trailing bytes")
+	}
+
+	return file, nil
+}
+
+type writer struct {
+	out []byte
+}
+
+func (write *writer) u8(value int) { write.out = append(write.out, byte(value)) }
+
+func (write *writer) u32(value int) {
+	four := make([]byte, 4)
+	binary.BigEndian.PutUint32(four, uint32(value))
+	write.out = append(write.out, four...)
+}
+
+func (write *writer) small(value []byte) {
+	write.u8(len(value))
+	write.out = append(write.out, value...)
+}
+
+func (write *writer) large(value []byte) {
+	write.u32(len(value))
+	write.out = append(write.out, value...)
+}
+
+func (write *writer) sealed(value *sealed) {
+	write.small(value.IV)
+	write.large(value.Blob)
+}
+
+func writefile(file *vaultFile) []byte {
+	write := &writer{out: []byte(magic)}
+
+	write.u8(format)
+	write.u8(kdfPBKDF2)
+	write.u8(cipherAESGCM)
+	write.u8(0)
+
+	write.u32(len(file.Keys))
+	for _, record := range file.Keys {
+		write.small([]byte(record.ID))
+		write.small(record.Salt)
+		write.u32(record.Iters)
+		write.sealed(record.Ring)
+		write.sealed(record.Meta)
+	}
+
+	// SORTED BY ID, which is a blinded value: the file therefore records
+	// nothing about the order secrets were written in.
+	entries := append([]*entryRecord{}, file.Entries...)
+	sort.Slice(entries, func(left, right int) bool {
+		return 0 > bytes.Compare(entries[left].ID, entries[right].ID)
+	})
+
+	write.u32(len(entries))
+	for _, record := range entries {
+		write.small(record.ID)
+		write.sealed(record.Name)
+		write.sealed(record.Value)
+	}
+
+	return write.out
+}