delivery

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package delivery owns the canonical encodings the machine fetch path keys: the delivery manifest the change token covers, and the tuple the conditional cursor is bound to.

It holds encoding and nothing else. The keying lives in internal/crypto (where `crypto/hmac` and `crypto/hkdf` are confined), the authorization lives at the chokepoint, and the projection this encodes is computed by the service. Splitting it out is what makes the seam the revision-model ADR needs testable: when real values and revisions land (#50/#51), Manifest's INPUT changes and nothing else does.

Index

Constants

View Source
const CursorVersion = "v1"

CursorVersion is the tuple encoding's version, inside the signed bytes for the same reason ManifestVersion is.

View Source
const ManifestVersion = "v2"

ManifestVersion is the canonical encoding's version, carried INSIDE the signed bytes as well as on the token string. Inside matters: without it, two different encodings of the same content could produce the same token under a scheme change, which is the collision a version prefix on the outside cannot prevent.

View Source
const MaxAcknowledgedKeys = 64

MaxAcknowledgedKeys bounds the loader-control acknowledgement list a machine fetch may present (k8s ADR § 0.9). It is the single source of truth for that bound: the service refuses a longer list as a caller error BEFORE any work, and the audit registry caps the recorded list at the same number, so the two can never drift into a state where a list the service accepts is one the audit write then rejects loudly.

View Source
const OccurrenceVersion = "v1"

OccurrenceVersion is the occurrence encoding's version, inside the signed bytes for the same reason ManifestVersion is.

View Source
const RefusalHeader = "X-Hikyo-Delivery-Refusal"

RefusalHeader identifies a completed refusal from the canonical delivery operation on the client's authenticated HTTPS origin. A generic router or proxy 404 is not authority to erase a previously delivered Secret.

View Source
const RefusalVersion = "v1"
View Source
const SnapshotMaxAge = 7 * 24 * time.Hour

SnapshotMaxAge is the server-asserted maximum age of an offline delivery snapshot (ops-spec § 6). Clients bind both timestamps into snapshot AAD and refuse the ciphertext after this interval.

Variables

This section is empty.

Functions

func EncodeCursor

func EncodeCursor(c Cursor) []byte

EncodeCursor renders the tuple canonically. Every component is length-prefixed and the projection is sorted, so the encoding is injective: two different tuples cannot produce one cursor, which is what makes "recompute and compare" a sound test rather than a heuristic.

func EncodeOccurrence

func EncodeOccurrence(o Occurrence) []byte

EncodeOccurrence renders one occurrence canonically. Length-prefixed throughout, so the encoding is injective and "recompute and compare" is a sound test: a caller cannot construct bytes for a state they were not served.

The declared/undeclared discriminator is a FIELD, not an absence: encoding the undeclared case as "the declared case with empty ids" would let a key whose declaration was somehow empty collide with one that has none.

func IsLoaderControlKey

func IsLoaderControlKey(name string) bool

IsLoaderControlKey reports whether name is on the loader-control baseline — either an exact match or under a controlled prefix.

func Manifest

func Manifest(rows []Row) []byte

Manifest is the canonical encoding the change token is computed over.

Rows are sorted by key, and every field is LENGTH-PREFIXED. Both are load-bearing: an unsorted encoding would make the token a function of the database's row order, and bare concatenation would let two different manifests encode identically — ("AB", "c") and ("A", "Bc") — which is a token collision, i.e. a missed rollout.

func Unacknowledged

func Unacknowledged(mapped, acknowledged []string) (refused, extraAcks []string)

Unacknowledged applies the § 0.6 rule as SET EQUALITY between the acknowledgement and the mapped loader-control SUBSET — not merely "mapped":

  • refused: mapped keys that are on the baseline but NOT acknowledged. A sync carrying any of these fails (`LoaderControlUnacknowledged`).
  • extraAcks: acknowledged names that are NOT in the mapped loader-control subset. This catches both an acknowledgement of a key that is not mapped at all AND an acknowledgement of a mapped NON-loader-control key (e.g. mapping [PATH, API_KEY] acknowledging [PATH, API_KEY]): acknowledging API_KEY is a latent grant that would pre-authorize a later baseline extension, so it is itself a refusal.
  • a duplicate in the acknowledgement is a refusal too (surfaced via extraAcks): the acknowledgement must be exactly the mapped loader-control set, and a repeated name is not that set.

All slices empty ⇒ the acknowledgement equals the mapped loader-control set. mapped is the list of destination `secretKey`s the mapping delivers; acknowledged is `spec.acknowledgedLoaderKeys`. Order-stable and de-duplicated so the caller's condition message and the `acknowledged_keys` request parameter are deterministic.

Types

type Cursor

type Cursor struct {
	ChangeToken string
	// Projection is the caller's authorized delivery projection: the sorted
	// capability atoms it holds at the addressed environment. It is sorted by
	// the caller of EncodeCursor rather than trusted to arrive sorted.
	Projection []string
	// AuthorizationRevision is the principal's monotonic authority revision.
	AuthorizationRevision int64
	// PinGeneration is the (principal, environment) pin counter.
	PinGeneration int64
	// Mode is the delivery projection mode, normalized (never ""). It is bound
	// in so every outstanding pre-projection cursor mismatches exactly once,
	// which is the designed upgrade path — no cursor-versioning machinery.
	Mode Mode
	// PinnedHistoricalRevision is the pinned revision when the delivered
	// snapshot is a pinned NON-CURRENT revision, and 0 otherwise (unpinned, or
	// a pin still on the environment's latest). Revisions are >= 1, so 0 is an
	// unambiguous "not pinned-historical". Binding the pinned revision rather
	// than a bare bool is deliberate: it is the revision whose history the
	// delivery discloses, which is exactly what the `reveal-history` term
	// authorizes, so a cursor that names it re-binds every value re-pin without
	// leaning on the pin generation alone.
	PinnedHistoricalRevision int64
}

Cursor is the tuple a conditional fetch's cursor is bound to. The ADR is explicit that it is "never the environment's change token alone", and each component closes a distinct failure:

ChangeToken           the delivered content moved.
Projection            what this caller MAY SEE moved. Without it, a
                      workload granted `reveal` polls, the content has not
                      changed, the token matches, and it is told "current"
                      — so it runs indefinitely without the secrets it is
                      now entitled to, silently. And for a caller LACKING
                      `reveal`, a cursor derived from secret-bearing
                      content alone becomes a comparison oracle for whether
                      hidden values changed.
AuthorizationRevision the principal's authority moved at all — a grant
                      added, removed or narrowed.
PinGeneration         a pin was created, reassigned or released.
Mode                  the delivery projection (`full` vs `config-only`)
                      moved. `config-only` delivers and covers a strictly
                      smaller manifest, so a mode flip must invalidate the
                      cursor even when nothing else changed.
PinnedHistoricalRevision
                      the delivered snapshot became a pinned NON-CURRENT
                      revision (or which one it is). This closes a failure
                      the other components cannot see: when a pin that WAS
                      current is overtaken by a later publish, the pinned
                      snapshot's content, the caller's grants, the
                      authorization revision and the pin generation are all
                      unchanged — yet the secret-value authority term flips
                      from `reveal` to `reveal-history`, so a caller holding
                      `reveal` but not `reveal-history` silently loses the
                      secret's plaintext. Without this term the stale cursor
                      still matches and the fetch answers "current" for a
                      state that now discloses strictly less.

type Mode

type Mode string

Mode is the delivery projection: which keys the fetch is authorized to deliver at all. It is a SERVER-SIDE AUTHORIZED TERM (k8s ADR § Refresh), not a client-side filter — `config-only` omits `secret` keys from the delivery and from the manifest the change token covers — and it is bound into the cursor so a mode change invalidates it.

const (
	// ModeFull delivers every key the caller is authorized to see.
	ModeFull Mode = "full"
	// ModeConfigOnly omits `secret` keys entirely — from the delivery and from
	// the manifest, not presence-only.
	ModeConfigOnly Mode = "config-only"
)

func NormalizeMode

func NormalizeMode(m Mode) Mode

NormalizeMode maps the empty mode to the default. It is applied before the mode is bound into the cursor, so a cursor never encodes "" for a state that `full` also describes — the two would otherwise be one state under two cursors.

type Occurrence

type Occurrence struct {
	Declared               bool
	Name                   string
	KeyID                  string
	EntryID                string
	Classification         string
	Declaration            string
	IntendedClassification string
	IntendedType           string
}

Occurrence is what a phase-1 presence read observed for one `(key, environment)`, and what phase 2 recomputes to decide whether anything moved. Each component closes a distinct movement the ADR names:

KeyID           the declaration this name resolves to. A key deleted and
                re-created under the same name is a different key.
EntryID         WHICH value occurrence is in effect, or "" for `absent`.
                Value row ids are minted per write and never reused, so an
                edit advances this and the token stops matching — which is
                precisely what a bucket label cannot do, since `set` → `set`
                with a changed value preserves the bucket.
Classification  a reclassification moved what the key IS.
Declaration     the declaration digest: a changed rule is a changed
                declaration, and consent was given against the old one.
Name            the key's NAME. For an undeclared key it is the only
                identity there is; for a declared one it rides along so the
                two encodings can never collide.
Declared        whether the project declares this key at all. An import
                proposes keys that do not exist yet, and phase 2 must be
                able to check those did not move either — so they get a
                token naming "undeclared and absent" rather than no token,
                which is the one row an edited manifest could otherwise
                forge freely.
IntendedClassification
IntendedType    for an undeclared key, exactly what the emitted bundle line
                will declare. Phase 2 accepts the expected undeclared ->
                declared transition only when both still match.

type Presence

type Presence string

Presence is what the fetch surface reports about a key in one environment.

It is NOT part of the manifest: the change token covers DELIVERED CONTENT only (revision-model ADR), so tightening `required_in` -- which changes what a future publish may commit, not what this snapshot delivers -- must not move the token and fire a rollout wave. `set` joined the enumeration with #51: a key the snapshot delivers is `set`, and one it does not carries whichever declared rule applies to it.

const (
	// PresenceRequired is declared required in this environment.
	PresenceRequired Presence = "required"
	// PresenceForbidden is declared forbidden in this environment.
	PresenceForbidden Presence = "forbidden"
	// PresenceOptional is neither.
	PresenceOptional Presence = "optional"
	// PresenceSet is a key the snapshot actually delivers.
	PresenceSet Presence = "set"
)

type Row

type Row struct {
	Key            string
	Classification string
	// Occurrence is the server-generated value-entry identity. Including it
	// makes an accepted same-value rewrite a distinct rollout without exposing
	// plaintext equality to a publisher who lacks reveal.
	Occurrence string
	// Value is the plaintext the snapshot delivers for this key. It is the
	// third element of the ADR's triple, and it is why the token moves when a
	// value moves -- which is the whole point of a change token.
	//
	// The manifest is computed server-side, from a snapshot the server already
	// holds in plaintext for the length of the operation, and the token that
	// comes out is KEYED: it is unforgeable and un-invertible without the
	// scoped key, so it flows into logs and change-detection caches as ordinary
	// non-secret metadata. The token is change-detection material only and
	// never a workload-visible value (k8s ADR § Declared amendment); the
	// plaintext this field carries reaches an authorized consumer through the
	// fetch surface's own per-value disclosure records, never through the token.
	Value string
}

Row is one delivery-manifest entry: an ordered `(key, classification, value-or-presence)` triple, per the schema-model ADR's amendment to the revision ADR.

Classification is IN the manifest and that is the amendment's whole point: an adapter routing `secret` to a Kubernetes Secret and `config` to a ConfigMap would otherwise see an unchanged token across a reclassification and never fire the rollout that relocates the value.

Jump to

Keyboard shortcuts

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