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
- func EncodeCursor(c Cursor) []byte
- func EncodeOccurrence(o Occurrence) []byte
- func IsLoaderControlKey(name string) bool
- func Manifest(rows []Row) []byte
- func Unacknowledged(mapped, acknowledged []string) (refused, extraAcks []string)
- type Cursor
- type Mode
- type Occurrence
- type Presence
- type Row
Constants ¶
const CursorVersion = "v1"
CursorVersion is the tuple encoding's version, inside the signed bytes for the same reason ManifestVersion is.
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.
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.
const OccurrenceVersion = "v1"
OccurrenceVersion is the occurrence encoding's version, inside the signed bytes for the same reason ManifestVersion is.
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.
const RefusalVersion = "v1"
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 ¶
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 ¶
IsLoaderControlKey reports whether name is on the loader-control baseline — either an exact match or under a controlled prefix.
func Manifest ¶
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 ¶
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.
func NormalizeMode ¶
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.