Single-use redemption
A capability is a single-use authorization ticket. Redemption consumes it just before the effect, after re-checking that the authority behind it still holds. It decides about authority, never about the effect.
Status: Experimental · V1 under construction. Not independently reviewed or audited. Written against the authority-graph commit 397ba8c; the source remains authoritative.
The cycle: issue, redeem, perform
- Issue.
issue()takes the authenticated requester, a client idempotency key, a command naming anaction_idand anenforcement_point_id, and an explicitauthorityTime. If the engine’s validators accept, it records aCAPABILITY_ISSUEDevent: the capability, the action and its fingerprint, the decision sequence, the granted chain, the enforcement point and the expiry. It can refuse, for example withREQUESTER_MISMATCH,STALE_AUTHORITY_TIMEorCAPACITY_EXCEEDED. - Redeem. Just before the effect, the enforcement point calls
redeem()with the authenticated principal, a command and an explicitauthorityTime. The command carries the capability id, the enforcement point id, and the capability and parameters it is about to execute. - Perform. Only if
redeem()returnsok: truemay the caller perform the effect, once. Authority never performs the action: the caller’s own system does.
What redemption re-checks
- The ticket exists and is still a coherent grant of the journal (
CAPABILITY_NOT_FOUND,CAPABILITY_NOT_VALID). - The authenticated requester equals the requester recorded on the action request, never a value taken from the command (
REQUESTER_MISMATCH). - The enforcement point equals the ticket’s (
WRONG_ENFORCEMENT_POINT). - The ticket has not been redeemed (
ALREADY_REDEEMED) and has not expired:authorityTimestrictly beforeexpires_atis valid, otherwiseEXPIRED. - What the enforcement point is about to execute has the same fingerprint as the ticket (
ARGUMENTS_MISMATCH). Tool arguments are bound only when the action’s parameters carry anarguments_digest(fingerprint scheme V2); with scheme V1 only the capability, the amount, the currency and the recipient are bound. - The delegation is re-resolved over the whole journal at the command’s own instant. If it is no longer authorized (revoked, expired, a link lost), the result is
AUTHORITY_NO_LONGER_VALID. authorityTimeis not older than an instant already in the journal (STALE_AUTHORITY_TIME).
The order of refusals is fixed: not found, not valid, requester, stale instant, enforcement point, already redeemed, expired, arguments, authority.
One successful redemption
At most one CAPABILITY_REDEEMED event exists per capability. The decision kernel refuses a second one (ALREADY_REDEEMED), and ingestion independently refuses it as a business-identifier collision. In memory, redemptions over one store are serialized by a per-store mutex.
On PostgreSQL, one SQL transaction takes the writer advisory lock shared with every other writer of authority_events, reads the whole journal afresh, decides, inserts and reads back before committing. A partial unique index, authority_events_redeemed_capability_id_uidx, makes a second redemption row impossible even for a writer that ignores the lock. REDEEMED is returned only if this very transaction inserted the row and the read-back shows exactly one redemption row for the capability; a unique violation is reported as REDEMPTION_COLLISION. This is tested with concurrent connections and with separate operating-system processes, including a process holding the lock that is killed.
Redemption changes no earlier decision and releases no capacity: a redeemed capability stays engaged.
What this does not guarantee
What is bounded is authorization: at most one successful redemption per ticket. Nothing here guarantees that an external effect happens, happens once, or is undone. REDEEMED authorizes the effect; only the target system can deduplicate or verify it. A legitimate effect may even be lost, for instance after an unknown outcome, because Authority never produces a second ok: true.
Results
| Result | Event written | Ticket consumed | Effect may run | The caller should |
|---|---|---|---|---|
REDEEMED | yes, right after the decision | yes | yes | perform the effect, once |
CAPABILITY_NOT_FOUND, CAPABILITY_NOT_VALID, REQUESTER_MISMATCH, WRONG_ENFORCEMENT_POINT, EXPIRED, ARGUMENTS_MISMATCH, AUTHORITY_NO_LONGER_VALID, STALE_AUTHORITY_TIME | no | no | no | fix the cause, or authorize again |
ALREADY_REDEEMED, REDEMPTION_COLLISION | no, not by this call | yes, by another call | no | not retry: this call never authorized the effect |
CONCURRENT_WRITE_DETECTED, in memory | yes, but not right after the decision | yes | no | authorize again; this may meet CAPACITY_EXCEEDED |
CONCURRENT_WRITE_DETECTED, on PostgreSQL | no, rolled back | no | no | retry: the decision is made again on the new journal |
RedemptionSchemaError, on PostgreSQL | no, thrown before anything is written | no | no | fix the migration, then retry the same ticket |
| any other exception, on PostgreSQL | unknown | unknown | no | retry the same ticket when the database is reachable again |
Unknown outcomes on PostgreSQL
On PostgreSQL, three situations must be kept apart. They are not equivalent.
- A business refusal.
redeem()returnsok: falsewith a reason. This is a known outcome, not an exception: the results table says whether the ticket is consumed, and the effect must not run. - A known configuration error.
RedemptionSchemaErroris thrown before anything is written, because the redemption index is missing, invalid, not unique or mis-defined. It is not an unknown outcome. The effect must not run; fix the migration, then retry the same ticket (the failure is not cached). - Any other exception, for example a lost connection or a server error. From outside, you cannot tell whether it happened before the commit, around it, or after a commit whose acknowledgement was lost. Most such failures leave nothing written, but the call cannot say so: treat the outcome as unknown.
On an exception, the effect must never run on that call: this stays fail-closed, whatever the exception. Only the third case needs the recovery protocol, and only when the database is reachable again:
- Retry the same ticket.
REDEEMEDmeans the first attempt had not committed: run the effect once.ALREADY_REDEEMEDmeans the ticket is consumed, by the lost attempt or by another caller, and Authority cannot tell which: do not run the effect, and authorize again with a new capability.
A per-attempt recovery token that would tell the two cases apart is not provided. In memory, a concurrent write consumes the ticket without authorizing anything, and the capacity it engaged stays engaged: re-authorizing the same action against a total budget may then be refused with CAPACITY_EXCEEDED. This availability cost was accepted for V1; safety is not affected.
PostgreSQL setup
schema.sql is the migration and is idempotent. Building the unique index blocks writes while it runs; on a large journal, build it by hand first with CREATE UNIQUE INDEX CONCURRENTLY. A failed concurrent build leaves an invalid index that enforces nothing. Each PostgresCapabilityRedemptionTransaction therefore checks the index before its first redemption and throws RedemptionSchemaError, writing nothing, if it is not in force.
The pool you pass in must have an error listener, pool.on("error", ...), for idle clients whose connection is lost. The transaction guards the client it has checked out, not the pool: without your listener, an error on an idle client is not handled by Authority.
Examples that match the current code
These are teaching excerpts, not a library and not an SDK (the SDK is planned and not started). The variables and functions they use are supplied by your application. runEffectOnce is an illustrative function: Authority does not run it, and does not guarantee that an external effect runs once. Only the target system can do that. The examples are also not a complete production configuration: they leave out credentials and TLS, the application database role, pool sizing and timeouts, retries with backoff, logging and monitoring.
In memory. store is an InMemoryEventStore that already holds the issued ticket, and command is a RedeemCapabilityCommand with capability_id, enforcement_point_id, observed_capability and observed_parameters. runEffectOnce and refuseEffect stand for your own code.
import { InMemoryCapabilityRedemptionTransaction } from "./src/storage/capabilityRedemptionTransaction.js";
import { iso8601, principalId } from "./src/domain/types.js";
const redemption = new InMemoryCapabilityRedemptionTransaction(store);
const result = await redemption.redeem(
{ principalId: principalId("agent-a") },
command,
iso8601("2024-01-01T00:05:00.000Z"),
);
if (result.ok) {
runEffectOnce(result.redemption);
} else {
refuseEffect(result.reason);
}PostgreSQL, where pool is a pg pool, requester an authenticated principal and authorityTime a trusted instant you supply. The pool.on("error", ...) listener is required. In the catch branch, RedemptionSchemaError is the known configuration error and anything else is the potentially unknown outcome described above. reportIdleClientError, fixTheMigration and retryTheSameTicket stand for your own code; neither branch runs the effect.
import { PostgresCapabilityRedemptionTransaction, RedemptionSchemaError } from "./src/storage/postgresCapabilityRedemptionTransaction.js";
pool.on("error", (error) => {
reportIdleClientError(error);
});
const redemption = new PostgresCapabilityRedemptionTransaction(pool);
try {
const result = await redemption.redeem(requester, command, authorityTime);
if (result.ok) runEffectOnce(result.redemption);
else refuseEffect(result.reason);
} catch (error) {
if (error instanceof RedemptionSchemaError) fixTheMigration(error);
else retryTheSameTicket();
}A redemption can then be attested: see Authority Proof. The SDK that would wrap these calls is planned and not started; today they are used as shown.
Trust boundaries
| Boundary | What is trusted | What follows |
|---|---|---|
| Identity | The authenticated principal is asserted by the caller. | Only a mismatch with the action’s requester is detected. A caller that asserts the right identity is believed. |
| Clock | authorityTime is supplied by the caller. | A stale clock can redeem a ticket long after real time. A far-future instant written to the journal raises its high-water mark for good and makes later calls with a sane clock STALE_AUTHORITY_TIME. Authority has no source of real time. |
| Application role | The PostgreSQL application role can read and insert, not update or delete. | A writer with insert rights can append a coherent forged redemption: it validates, because validation checks coherence and not provenance, and it takes the ticket from its holder. It cannot alter or delete it. |
| Database owner, superuser, infrastructure | Out of scope. | They can alter or drop the journal. |
| Writers that bypass the lock | Detected, not prevented. | The primary key and the unique index refuse collisions, and a taken or missing sequence makes redemption fail closed. |
| External effect | Not covered. | REDEEMED authorizes; it does not make the effect happen, happen once, or be undone. |
Review status
Redemption has not been independently reviewed. These statements follow the repository at the pinned commit; the specification (invariants I26 to I31) remains the reference.