Interface IKeyMintLedger
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
The durable, write-ahead record of every key handle this framework has INTENDED TO MINT for a data subject: the enumeration an erasure destroys from, and the only thing that makes one read of the retention registry sufficient.
public interface IKeyMintLedger
Remarks
The guarantee. Every handle holding a data subject's personal fields has a row here before any key material exists at that handle. An erasure therefore learns the complete set of handles it must decide about by reading this ledger, rather than by re-deriving candidates from configuration that may have changed since the data was written.
It records an INTENT, not a completed mint, and the name says so deliberately. A crash between the row and the mint leaves a row for which no key was ever created. That row is correct and permanent: it says this framework intended to place data at that handle, which is exactly what an erasure needs to know.
Why that matters, stated as the failure it removes. A subject's fields are placed under a key named by a handle derived from the subject and the obligation class the data belongs to. If the derivation consulted the retention registry, the write and the erasure would each read that registry at their own instant: a declaration added between them leaves the erasure sparing a handle that was never minted while destroying the one holding the data, and a declaration removed between them leaves a live key for a subject reported erased. Neither raises. Both end in a completed certificate. With this ledger the derivation needs no registry read at all, so the two instants cannot disagree.
THE ROW IS WRITTEN AND DURABLE BEFORE THE MINT, AND THE ORDER IS THE WHOLE CONTRACT. Mint-then-record admits a crash that leaves live key material with no row — never enumerated, never destroyed, and a certificate issued over it. Record-then-mint leaves a row with no key, which the erasure handles. One order fails silently and catastrophically; the other does not. Implementations MUST NOT reorder this. Returning is not durability: a write acknowledged before it is durable — an unreplicated acknowledgement, a deferred commit, a session-consistency write — reproduces the mint-then-record failure exactly, because a crash loses the row while the key survives. An implementation returns only once the row would survive the loss of the process that wrote it.
IMPLEMENTATIONS MUST BE DURABLE, and this is a requirement the sibling ledger does not have. Losing a row here is not the mirror of losing a destruction record — it is the opposite. A lost destruction record fails safe: no tombstone is produced and the read proceeds. A lost mint row fails CATASTROPHICALLY: the erasure enumerates fewer handles than exist, destroys what it found, and certifies. Inverting the polarity inverts which implementations may be volatile, so a store that does not survive a process restart must not supply this ledger in any deployment whose erasures are relied upon.
This is the OPPOSITE write order from IKeyDestructionLedger, and the asymmetry is not an inconsistency. That ledger records a destruction only AFTER it completed, because a tombstone must be sound: a row asserting a destruction that did not happen reports recoverable data as erased. This ledger must be complete: a handle missing a row is a key nothing will ever look for. Soundness wants the record last; completeness wants it first.
A ROW IS NEVER EVIDENCE OF COVERAGE. It says a handle was intended, and nothing more. It is not evidence that the key exists, that it was destroyed, or that an erasure covered it. Only a positive destruction record — or an erasure's own destruction of the handle in the pass that is certifying — discharges a handle. If anything ever reads the ABSENCE of a row as "no key ever existed here" and serves an erasure tombstone on that basis, this ledger has become a tombstone source and the soundness failure described above reappears in full.
ROWS ARE INSERT-ONLY AND PERMANENT. There is no update and no delete. Nothing may remove a row — no sweep, no expiry, no administrative reset, and least of all the erasure of the subject it names: a handle that has been destroyed keeps its row, because a later erasure of the same subject must still learn that the handle existed.
Keyed by the handle, carrying NO generation and NO obligation class. Existence is a per-handle fact; destruction is a per-generation fact. A row carrying a generation would need updating when a handle is re-minted, which makes the row mutable and rebuilds a create-or-rotate race one layer down. The obligation class is omitted for a different reason — sufficiency, not derivability: the owner and the subject token are the only key an erasure can enumerate by, and the class is not needed for that, so storing it buys nothing. (The class is a derivation input, but so are the owner and the token, and those two ARE stored because the enumeration needs them. An implementer must not "fix" the apparent inconsistency by dropping them.)
A handle is at most 81 characters and round-trips exactly. That is the bound the shipped derivation produces — a 64-character digest, optionally composed with a separator and a 16-character obligation-class discriminator. An implementation whose column cannot store 81 characters whole must refuse rather than truncate: a truncated handle is a row that matches no envelope, which is an omission from the enumeration.
Consumer obligation: this store is on the write path and MUST fail closed. Recording the intent makes this ledger a write-availability dependency of the first personal-data write per subject and obligation class. The usual rule that cross-cutting infrastructure fails open is inapplicable here: failing open mints a key that nothing will ever enumerate, which is the catastrophic direction. An implementation that cannot write the row throws, and the write fails.
Scope: this binds data written after it was adopted. Fields encrypted before this ledger existed have no rows, so an erasure cannot enumerate them from here. Handles derived the old way remain reachable by derivation, and an erasure continues to destroy the subject's own handle unconditionally; what it cannot do is discover a handle it was never told about. An absent row therefore does not distinguish "this handle was never recorded" from "this data predates me", and no caller may treat the absence as either.
Properties
IsDurable
Gets a value indicating whether a recorded row survives the loss of the process that wrote it, so an enumeration can never silently under-report.
bool IsDurable { get; }
Property Value
- bool
true when a row, once recorded, outlives the writing process; false for a ledger that holds its rows only in memory.
Remarks
This exists because the durability requirement above was stated as prose and nothing could check it. Every clause of that requirement is an obligation on the DEPLOYMENT — "a store that does not survive a process restart must not supply this ledger" — and a client had no way to tell a durable ledger from a volatile one, through this interface or through the type. A volatile implementation's empty enumeration is a CONFORMING answer: the documented meanings of empty are "no fields were ever written" and "the fields predate this ledger", and "the rows were discarded" is indistinguishable from both. So the catastrophic direction this contract exists to remove was reachable through an implementation that violated nothing.
It is a property of the implementation, deliberately, and NOT a separately registrable marker. A capability token that can be registered apart from the thing it attests can be registered truthfully-looking over an implementation that does not have the property — which is how an advertised-but-unwired guarantee gets through a startup check that reads the token. Reading it off the implementation makes a false claim require lying in the implementation itself.
A ledger that never answers an enumeration reports true, and that is not a loophole. The property is about whether an enumeration can UNDER-REPORT. An implementation that refuses to enumerate at all — the one a deployment performing no erasure registers — cannot under-report, because it never reports. It fails loudly instead, which is the behaviour this property exists to distinguish from.
Startup validation refuses a composition that relies on erasure while its mint ledger reports false, unless the consumer has stated the choice by name. It is not a hint.
Methods
ListHandlesAsync(TenantId, string, CancellationToken)
Lists every handle recorded for this data subject under this owner — the set an erasure must decide about.
Task<MintLedgerSnapshot> ListHandlesAsync(TenantId tenantId, string dataSubjectIdHash, CancellationToken cancellationToken)
Parameters
tenantIdTenantIdThe owner the host resolved for this erasure.
dataSubjectIdHashstringThe data subject's pseudonymisation token.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<MintLedgerSnapshot>
The recorded handles at one instant, split into those whose key creation was confirmed and those still pending, without duplicates and in no guaranteed order. An empty snapshot means no row exists for this subject under this owner — which covers a subject who never had personal fields written, and a subject whose fields predate this ledger. Those two are not distinguished here, and neither may be read as evidence that a subject's data was covered.
Remarks
Matched on the PARAMETERS ordinally, and on nothing else. No folding, no trimming, no prefix matching: two owners differing only in case are two owners, and a row belonging to one must never be enumerated for the other. NO AMBIENT TENANT TERM PARTICIPATES. This enumeration is addressed by (owner, subject) rather than by the ledger's own key, so unlike every other read on a store of this kind the owner term is load-bearing rather than redundant — and an ambient term ANDed onto it can only turn the correct set into a smaller one, which here means handles an erasure fails to destroy.
This is a complete enumeration or it is a failure. There is no paging and no limit, because a truncated answer is a handle an erasure does not destroy — the set is bounded by the obligation classes one subject's data appears in, which is small. An implementation whose backend pages internally MUST drain every continuation, and MUST throw rather than return a short set.
Being unable to READ the ledger is an exception, never an empty set, and an absent or uninitialised schema is a read failure rather than an empty answer. Collapsing those into "no rows" reports a subject as having no handles, which is precisely the state in which an erasure destroys nothing and certifies.
The two sets come from ONE read because the second exists to close a window. See MintLedgerSnapshot for why a pending row is the only observable that can separate a write in flight from a write abandoned, and why an erasure that finds one must not certify.
MarkMintedAsync(string, CancellationToken)
Records that the key behind this handle has been created, moving the row from pending to minted.
Task MarkMintedAsync(string keyHandle, CancellationToken cancellationToken)
Parameters
keyHandlestringThe handle whose key creation has been confirmed.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task
A task that completes when the row records the confirmation.
Remarks
Called AFTER the key exists, and it is the second half of a two-step write whose first half is deliberately useless on its own. The intent row cannot say whether the key was created, because it is written before the creation is attempted. This call is what supplies that fact, and the fact is what lets an erasure tell a write that is mid-flight from a write that was abandoned — two states that are otherwise identical in everything an erasure can observe.
FAIL-OPEN, and the asymmetry with RecordMintIntentAsync(string, TenantId, string, CancellationToken) is the design. The intent write fails CLOSED because returning without a durable row would let a key be created that no erasure enumerates. This write fails OPEN because a row stuck at pending is conservative in the direction that matters: it withholds a clean certificate rather than granting one. A caller SHOULD NOT fail a consumer's personal-data write because a confirmation could not be recorded — the key exists, the row exists, and the only consequence is that erasures for this subject report a concurrent write until the row is confirmed by a later mint at the same handle.
Idempotent, and it never moves a confirmation already on file. Confirming a handle already marked minted is a no-op; the first confirmation instant stands. Confirming a handle with NO row is a programming error and is refused — the row is written first, always, so its absence here means the caller skipped the intent step and a key may exist that nothing enumerates.
Exceptions
- ArgumentException
Thrown when
keyHandleis null, empty or whitespace.- InvalidOperationException
Thrown when no row exists for this handle.
RecordMintIntentAsync(string, TenantId, string, CancellationToken)
Records, durably and before any key material is created, that this handle is about to hold personal fields for this data subject.
Task RecordMintIntentAsync(string keyHandle, TenantId tenantId, string dataSubjectIdHash, CancellationToken cancellationToken)
Parameters
keyHandlestringThe handle the key will be minted at, exactly as the value's envelope will name it, at most 81 characters. A row recorded under a different spelling is a row no erasure will match, which is the omission this ledger exists to prevent.
tenantIdTenantIdThe resolved OWNER of the data being protected — the same owner the handle was derived from, resolved by the HOST. It is stored because the handle is an opaque digest: nothing can be recovered from it, so the enumeration key must be carried alongside.
An owner is NOT a storage partition, and the distinction is load-bearing rather than pedantic. This subsystem carries both on one erasure status and uses them four lines apart — the key handle is derived from the owner, while retention declarations are joined on the partition. In the DEFAULT single-tenant deployment the two are UNEQUAL: the owner is the resolved default identity and the partition is the reserved untenanted marker. An implementation that bound the partition here instead would enumerate the empty set, and the erasure would destroy the subject's plain handle and certify. The parameter type is what makes that substitution fail to compile.
dataSubjectIdHashstringThe data subject's pseudonymisation token, as an erasure request records it. With
tenantIdit forms the only key an erasure can enumerate by.cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Remarks
Idempotent by the handle, and a lost race is a SUCCESS. Recording a handle that already has a row is a no-op, not an error: the first write per subject and obligation class races with every other, and the row carries nothing a later call could legitimately change. An implementation inserts if absent and never updates. An implementation MUST NOT surface a duplicate-key error from a lost insert race — that turns a specified no-op into a failed personal-data write on a path deliberately made fail-closed, so an insert-if-absent that is not atomic must catch the duplicate and report success.
A handle re-recorded under a DIFFERENT owner or subject is REFUSED, loudly. Keeping the first spelling silently would leave a row whose enumeration key does not match the data it names: the handle would exist while the correct owner's enumeration returned nothing, which is worse than having no row at all. A handle is derived from the owner and the subject, so a collision between two of them is either a derivation defect or a hash collision, and both must be loud.
A failure to write is thrown, never swallowed. See the fail-closed obligation on the interface.
Exceptions
- ArgumentException
Thrown when
keyHandleordataSubjectIdHashis null, empty or whitespace, or when the handle exceeds 81 characters.- InvalidOperationException
Thrown when a row already exists for this handle under a different owner or a different data subject.