Ruslan Akchurin
Where secrets goPart 26 min read
Published
Updated

Delivery is a transaction

The API call is only one step.

The API write is only the visible step; a delivery transaction must record who accepted the value, which outputs and wiring changed, and the receipt the next rotation uses for comparison.

The slot comes before the value

The has to exist before the value, or the first paste chooses path, owner, and visibility at the most exposed moment. With the slot declared first, the application gets a stable path or reference while the handoff supplies material outside the application contract.

The value owner is the person or automation that first brings material into the route: third-party paste, generated credential, or controlled import. Each path has a different exposure window. Imported third-party material still has a local plaintext moment somewhere, even when the rest of the design is careful.

The honest target is narrower than pretending entry disappeared. A recorded transaction minimises persistence in shell history, logs, temporary files, failed paste flows, and infrastructure state. It records which authority accepted the value and when the value became wrapped material rather than uncontrolled text.

Authority is the part teams leave implicit when the workflow spreads across files, consoles, and scripts. Source control, the build runner, the runtime platform, and central platforms make different authority choices. The reviewable design names which one holds the route. The weak design pretends no authority was chosen, so the last layer to write the value becomes the authority by default.

Outputs reconcile together

Permissions split by action. Rendering, writing, consuming, and wiring are different grants; bundling them behind broad read access destroys the boundary the transaction is meant to record.

The transaction has to reconcile those surfaces as one operation because partial success is still state: a rendered file without the destination write, a moved manifest with an old path still live. Treating those as separate chores hides the behaviour that breaks rotation later.

A delivery transaction ties route to receipt A delivery transaction begins with a declared slot, accepts a value through controlled entry, wraps the value before persistence, reconciles several output surfaces, emits machine-readable wiring, and records a receipt for later drift checks. The receipt is the single accent because it is the durable proof that connects the route to those checks. DELIVERY TRANSACTION route · wiring · receipt declared slot service · env · key controlled entry owner named wrapped value plaintext minimised reconcile outputs together runtime path consume deployment ref wire local render render write surface receipt only machine-readable wiring paths · refs · manifests applied receipt proof boundary · drift basis drift check
A delivery transaction ties route to receipt

Wiring has to be emitted with the apply. Copying it afterwards splits the receipt from the destination writes. A README path guides a person; deployment code needs generated wiring tied to that same receipt.

Reconciliation also has to respect destination semantics. Whole-project patches, one-secret writes, split plain-and-secret destinations, and have different failure shapes. The receipt has to keep those shapes visible.

A delivery transaction's job is provisioning, wiring, receipts, and drift evidence, and it stops there. It does not handle how the application reads the value at runtime, unless the authority chosen for the route also owns that access. Runtime brokers, platform-native injection, and direct store reads remain valid consumption paths. Delivery is the reconcile-time operation that gets each surface into the state the declared slot requires.

The receipt survives the operator

An apply that changes secrets without durable state leaves the next rotation as investigation. The operator remembers which values were pasted, which destinations were written, and which local files were rendered. The system remembers only that the store has a value.

Applied state is the receipt of the transaction. It records the slot, value version or fingerprint, value owner, writer, outputs, grants, wiring artefacts, destination results, and proof boundary. It also marks stale receipts as superseded so an old valid apply cannot pass as current truth.

delivery.lock.json
{
  // Stable slot identity. The value can rotate without changing the consumer contract.
  "slot": "payments/nonprod/PAYMENT_API_KEY",
  "value": {
    // Monotonic value generation, used to distinguish rotation from re-apply.
    "version": 7,
    // Drift proof for readable outputs. Keyed so the receipt is not a password oracle.
    "fingerprint": "hmac-sha256:<keyed-value-fingerprint>"
  },
  "fingerprint_key": {
    // The key that protects the fingerprint is stored only in wrapped form.
    "wrapped_to": ["payments/nonprod"],
    "ciphertext": "wrapped:<redacted>"
  },
  "authority": {
    // Who introduced the material, who applied it, and which authority signed the receipt.
    "value_owner": "platform-import",
    "writer": "ci-apply",
    "signed_by": "receipt-authority"
  },
  "recipients": [
    {
      // The receipt pins key material as well as recipient name.
      "identity": "payments/nonprod",
      "key_fingerprint": "sha256:<recipient-public-key>"
    }
  ],
  "outputs": {
    "runtime_store": {
      // Runtime path plus the strongest proof this destination can support.
      "path": "secret://nonprod/payments/PAYMENT_API_KEY",
      "proof": "value-fingerprint"
    },
    "deployment_reference": {
      // Wiring emitted for deployment code, tied back to the same receipt.
      "path": "env://PAYMENT_API_KEY",
      "proof": "wiring-hash"
    },
    "build_secret": {
      // Write-only output: the receipt proves the write path rather than plaintext equality.
      "path": "ci://payments/PAYMENT_API_KEY",
      "proof": "write-receipt-only"
    },
    "local_render": {
      // Local development output. This proof is tied to the pull event.
      "path": ".env.local",
      "proof": "render-receipt-only"
    }
  },
  // Old receipts stay audit-visible, but this one is the current truth.
  "supersedes": "receipt:6",
  // Detached authority covers the receipt rather than the plaintext value.
  "signature": "<detached-signature>"
}

The receipt omits plaintext and unwrapped fingerprint keys. It records proof limits per output instead of treating every destination as equality-checkable. That makes the local-render proof narrower than a value fingerprint: the live file can change after pull. The fingerprint is authority-bound; a bare hash of a password-sized secret would make the receipt an oracle for anyone who can read it.

Proof boundaries belong in that receipt. A readable destination supports value or fingerprint comparison. A write-only destination records a narrower fact set: attempt, destination, version, metadata, and receipt. Hiding that limit overstates the later drift check.

Drift then has three surfaces to compare: declared state, applied state, and live state. Drift includes value mismatch, missing path, widened permission, absent local render, changed destination name, and a write-only output that no longer verifies beyond its last receipt.

"Put it in the store" is too small once those facts matter. Storage is one node in the operation. The transaction is the reviewable unit because it says which apply changed state, which wiring moved with it, and which proof is strong enough for the next check.

The next part tests the substitute most teams already have: the working bundle around the store. The question is whether that bundle produces one transaction object or leaves the evidence split across its parts.