@cotal-ai/auth 0.11.6 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/dist/admission-mediator.d.ts +319 -0
  2. package/dist/admission-mediator.d.ts.map +1 -0
  3. package/dist/admission-mediator.js +1033 -0
  4. package/dist/admission-mediator.js.map +1 -0
  5. package/dist/auth-admin.d.ts +29 -0
  6. package/dist/auth-admin.d.ts.map +1 -0
  7. package/dist/auth-admin.js +224 -0
  8. package/dist/auth-admin.js.map +1 -0
  9. package/dist/authority-client.d.ts +215 -0
  10. package/dist/authority-client.d.ts.map +1 -0
  11. package/dist/authority-client.js +346 -0
  12. package/dist/authority-client.js.map +1 -0
  13. package/dist/barrier-evict.d.ts +16 -0
  14. package/dist/barrier-evict.d.ts.map +1 -0
  15. package/dist/barrier-evict.js +100 -0
  16. package/dist/barrier-evict.js.map +1 -0
  17. package/dist/commands.js +16 -12
  18. package/dist/commands.js.map +1 -1
  19. package/dist/connect-reader.d.ts +72 -0
  20. package/dist/connect-reader.d.ts.map +1 -0
  21. package/dist/connect-reader.js +154 -0
  22. package/dist/connect-reader.js.map +1 -0
  23. package/dist/continuity.d.ts +23 -0
  24. package/dist/continuity.d.ts.map +1 -0
  25. package/dist/continuity.js +145 -0
  26. package/dist/continuity.js.map +1 -0
  27. package/dist/credential-ledger.d.ts +343 -0
  28. package/dist/credential-ledger.d.ts.map +1 -0
  29. package/dist/credential-ledger.js +732 -0
  30. package/dist/credential-ledger.js.map +1 -0
  31. package/dist/drain-repair.d.ts +95 -0
  32. package/dist/drain-repair.d.ts.map +1 -0
  33. package/dist/drain-repair.js +305 -0
  34. package/dist/drain-repair.js.map +1 -0
  35. package/dist/idp.d.ts +19 -0
  36. package/dist/idp.d.ts.map +1 -1
  37. package/dist/idp.js +17 -0
  38. package/dist/idp.js.map +1 -1
  39. package/dist/index.d.ts +7 -3
  40. package/dist/index.d.ts.map +1 -1
  41. package/dist/index.js +31 -3
  42. package/dist/index.js.map +1 -1
  43. package/dist/issuer.d.ts +8 -0
  44. package/dist/issuer.d.ts.map +1 -1
  45. package/dist/issuer.js +4 -2
  46. package/dist/issuer.js.map +1 -1
  47. package/dist/ledger-scanner.d.ts +98 -0
  48. package/dist/ledger-scanner.d.ts.map +1 -0
  49. package/dist/ledger-scanner.js +352 -0
  50. package/dist/ledger-scanner.js.map +1 -0
  51. package/dist/ledger.d.ts +12 -0
  52. package/dist/ledger.d.ts.map +1 -1
  53. package/dist/ledger.js +103 -13
  54. package/dist/ledger.js.map +1 -1
  55. package/dist/lifecycle-registry.d.ts +397 -0
  56. package/dist/lifecycle-registry.d.ts.map +1 -0
  57. package/dist/lifecycle-registry.js +819 -0
  58. package/dist/lifecycle-registry.js.map +1 -0
  59. package/dist/permissions.d.ts +5 -1
  60. package/dist/permissions.d.ts.map +1 -1
  61. package/dist/permissions.js +29 -6
  62. package/dist/permissions.js.map +1 -1
  63. package/dist/plane-claim.d.ts +83 -0
  64. package/dist/plane-claim.d.ts.map +1 -0
  65. package/dist/plane-claim.js +290 -0
  66. package/dist/plane-claim.js.map +1 -0
  67. package/dist/provider.d.ts.map +1 -1
  68. package/dist/provider.js +45 -16
  69. package/dist/provider.js.map +1 -1
  70. package/dist/records-scanner.d.ts +78 -0
  71. package/dist/records-scanner.d.ts.map +1 -0
  72. package/dist/records-scanner.js +320 -0
  73. package/dist/records-scanner.js.map +1 -0
  74. package/dist/retirement-barrier.d.ts +217 -0
  75. package/dist/retirement-barrier.d.ts.map +1 -0
  76. package/dist/retirement-barrier.js +624 -0
  77. package/dist/retirement-barrier.js.map +1 -0
  78. package/dist/retirement-cleaner.d.ts +54 -0
  79. package/dist/retirement-cleaner.d.ts.map +1 -0
  80. package/dist/retirement-cleaner.js +158 -0
  81. package/dist/retirement-cleaner.js.map +1 -0
  82. package/dist/root-credential.d.ts +26 -0
  83. package/dist/root-credential.d.ts.map +1 -0
  84. package/dist/root-credential.js +116 -0
  85. package/dist/root-credential.js.map +1 -0
  86. package/dist/service.d.ts +73 -5
  87. package/dist/service.d.ts.map +1 -1
  88. package/dist/service.js +349 -24
  89. package/dist/service.js.map +1 -1
  90. package/dist/session-ledger.d.ts +224 -0
  91. package/dist/session-ledger.d.ts.map +1 -0
  92. package/dist/session-ledger.js +713 -0
  93. package/dist/session-ledger.js.map +1 -0
  94. package/dist/store.d.ts +18 -8
  95. package/dist/store.d.ts.map +1 -1
  96. package/dist/store.js +74 -51
  97. package/dist/store.js.map +1 -1
  98. package/dist/token.d.ts +17 -0
  99. package/dist/token.d.ts.map +1 -1
  100. package/dist/token.js +30 -2
  101. package/dist/token.js.map +1 -1
  102. package/package.json +7 -4
@@ -0,0 +1,343 @@
1
+ /**
2
+ * The D13 NORMATIVE CREDENTIAL LEDGER + the full TAKEOVER ISSUANCE BARRIER, slices (3)+(2b)
3
+ * (SPEC §13.1, as amended). The sibling of `lifecycle-registry.ts`: the SAME minting authority
4
+ * over the SAME two stores, reached only through the sealed registry ({@link registryStores}),
5
+ * so a caller that cannot open the registry can neither write a ledger row nor run a barrier.
6
+ *
7
+ * What is here (all §13.1-normative):
8
+ * - the AGENT-family ledger rows `cred.<lifecycleUid>.<credentialId>` — the closed row schema
9
+ * `{ credentialId, holderPrincipal, lifecycleUid, sourceChain, state: active|revoked, exp }`
10
+ * (monotonic state; revoked rows are never deleted), the per-ancestor lineage index
11
+ * `bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>`, and the shared row codec the
12
+ * ENDPOINT family `epcred.<endpoint>.<instanceId>.<credentialId>` reuses (same schema, same
13
+ * discipline; the session adapter writes that family);
14
+ * - the MINT PROTOCOL (observe gate → write rows → revision-pinned gate touch-CAS → release):
15
+ * {@link stageAgentMint} + {@link finalizeAgentMint}. The touch is the §13.1 fence — a gate
16
+ * (or any presented source gate) that moved since observation makes the pinned write LOSE,
17
+ * the mint marks its OWN rows revoked and never releases. An unledgered mint cannot occur
18
+ * through this module: release is gated on finalize, and finalize is gated on the staged
19
+ * rows existing;
20
+ * - SOURCE GATES `srcgate.<issuerKeyId>.<id>` (`{ state: open | frozen }`, CAS): every handle
21
+ * in a presented chain is observed at stage and touch-CASed at finalize, and
22
+ * {@link revokeHandleSource} is the handle-revocation walk — freeze the source gate FIRST,
23
+ * enumerate `bysrc.`, revoke every descendant row, then VERIFIED cluster-wide eviction of
24
+ * every revoked row's holder principal (fail-closed; the gate stays frozen forever);
25
+ * - the TAKEOVER BARRIER {@link runAgentTakeoverBarrier} in the normative order: durable op
26
+ * intent (`stage.<opId>`, create-only) → gate CAS `open → frozen` carrying the intent →
27
+ * point-in-time enumeration of `cred.<lifecycleUid>.>` (the SEALED auth-ledger scanner's
28
+ * fence-free LastPerSubject read — `ledger-scanner.ts`; the barrier profile holds NO auth-stream
29
+ * `CONSUMER.CREATE`, whose body cannot be subject-confined, so the CREATE lives only in the
30
+ * scanner's own sealed credential) → revoke EVERY row → VERIFIED
31
+ * eviction of every holder principal (the injected `evictPrincipal` seam; `verifiedGone`
32
+ * is the ONLY success — anything else throws and the gate STAYS frozen) → the epoch head
33
+ * CAS LAST ({@link advanceEpochWithinTakeover}) → reopen the gate at generation G+1. Every
34
+ * boundary is crash-resumable from the durable intent ({@link resumeAgentTakeover}), and
35
+ * only the SAME operation resumes it.
36
+ *
37
+ * Deny-new vs kill-live, stated precisely (the two halves of revocation, §13.1):
38
+ * - the ledger row CAS is the deny-new SUBSTRATE (rows live in a replicated, leader-served
39
+ * JetStream KV, `allow_direct=false`, §13.12). The REDEEM arm is wired here: the session
40
+ * release reads the normative row and refuses a `revoked` one, so a burned session
41
+ * credential never re-releases. The CONNECT arm (the auth callout reading `cred.<uid>.<id>`
42
+ * to refuse an OFFLINE credential's reconnect) is NOT wired in this slice: it needs the
43
+ * ROOT credential ledgered (the head's `currentCredentialId`, which the activation saga
44
+ * leaves absent until production issuance) and the presented credential to carry its id, so
45
+ * it lands with production activation wiring. Until then, this barrier's deny-new covers the
46
+ * REDEEM path and the LIVE connections it evicts; an offline root credential whose lifecycle
47
+ * UID is preserved across takeover is NOT denied reconnect by the barrier alone (§13.1
48
+ * requires takeover to FAIL LOUD where it cannot revoke + verified-evict, e.g. static
49
+ * credentials — enforced at that connect-arm wiring, not here);
50
+ * - the injected verified eviction is the cluster-wide kill-live with re-scan (core
51
+ * `evictDeniedPrincipal`: CONNZ scan → per-server KICK → re-scan; partial scans fail
52
+ * closed), which handles the LIVE half regardless of the connect-arm.
53
+ *
54
+ * SURFACE: NOTHING here is exported from the package index. The executor seam is the sealed
55
+ * registry itself (constructed only over the minting authority's authenticated connection);
56
+ * an `opId` is an identifier, never a bearer capability. Implementation staging lives in the
57
+ * `stage.` family only — never under a ledger prefix a barrier enumerates.
58
+ */
59
+ import type { KV } from "@nats-io/kv";
60
+ import { type EvictionResult } from "@cotal-ai/core";
61
+ import { type LifecycleRegistry } from "./lifecycle-registry.js";
62
+ export declare const SOURCE_ROOT = "root";
63
+ /** Validate ONE sourceChain member — `root`, `handle.<issuerKeyId>.<id>`, or
64
+ * `session.<sessionId>` (SPEC 13.1) — and return its parsed shape. */
65
+ export declare function parseSourceMember(member: unknown): {
66
+ kind: "root";
67
+ } | {
68
+ kind: "handle";
69
+ issuerKeyId: string;
70
+ id: string;
71
+ } | {
72
+ kind: "session";
73
+ sessionId: string;
74
+ };
75
+ /** The agent-family ledger key `cred.<lifecycleUid>.<credentialId>`. */
76
+ export declare function credRowKey(lifecycleUid: string, credentialId: string): string;
77
+ /** The endpoint-family ledger key `epcred.<endpoint>.<instanceId>.<credentialId>` (disjoint by
78
+ * explicit prefix, never arity, SPEC 13.1). */
79
+ export declare function epcredRowKey(endpoint: string, instanceId: string, credentialId: string): string;
80
+ /** The per-ancestor lineage index key `bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>`. */
81
+ export declare function bysrcKey(issuerKeyId: string, id: string, lifecycleUid: string, credentialId: string): string;
82
+ /** The per-handle source gate key `srcgate.<issuerKeyId>.<id>`. */
83
+ export declare function srcgateKey(issuerKeyId: string, id: string): string;
84
+ /** A takeover/registration operation's durable intent key `stage.<opId>` (the `stage.<opId>.`
85
+ * staging family root — NEVER under a ledger prefix a barrier enumerates, SPEC 13.1). */
86
+ export declare function stageIntentKey(opId: string): string;
87
+ /** The §13.1 credential-ledger row, closed. `lifecycleUid` is the HOLDER's KEY identity
88
+ * component: the managed agent's lifecycle UID in the `cred.` family, the endpoint instance's
89
+ * `instanceId` in the `epcred.` family (SPEC 13.1: `instanceId` is to an endpoint what
90
+ * `lifecycleUid` is to a managed agent). `endpoint` is present ONLY in the `epcred.` family
91
+ * (it forms the key there and is absent in `cred.`), so the KEY identity is never conflated
92
+ * with the eviction target. `holderPrincipal` is who the barrier KICKs: ALWAYS a CONNZ-
93
+ * attributable `<owner>.<actor>` dot-form (the caller principal in the `cred.` family; the
94
+ * serving instance's own connection principal in the `epcred.` family, recorded from the
95
+ * endpoint gate), NEVER the endpoint name (which CONNZ cannot attribute). */
96
+ export interface CredentialLedgerRow {
97
+ credentialId: string;
98
+ holderPrincipal: string;
99
+ lifecycleUid: string;
100
+ /** The endpoint NAME whose token forms the `epcred.` key; present iff this is an endpoint-
101
+ * family row, absent in the `cred.` family (which the lifecycleUid keys). */
102
+ endpoint?: string;
103
+ /** The FULL verified lineage at mint: `root` | `handle.<issuerKeyId>.<id>`… |
104
+ * `session.<sessionId>` (SPEC 13.1 — for a handle redemption EVERY handle in the presented
105
+ * chain, never only the leaf). */
106
+ sourceChain: string[];
107
+ /** Monotonic: `active → revoked` only; a revoked row is never deleted. */
108
+ state: "active" | "revoked";
109
+ exp: number;
110
+ }
111
+ /** Parse + validate a ledger row at its consuming boundary — closed schema, and the embedded
112
+ * identity MUST rebuild the row's own key, so a key-mismatched or family-swapped poison row
113
+ * never authorizes (SPEC 13.1/13.3). */
114
+ export declare function parseLedgerRow(raw: Uint8Array, key: string): CredentialLedgerRow;
115
+ /** Create-only write of a ledger/index row with the BYTE-IDENTICAL retry (a crashed writer's
116
+ * retry of its OWN deterministic row proceeds; foreign content under a staged name refuses —
117
+ * a name never silently re-binds, SPEC 13.6 discipline). PACKAGE-INTERNAL: the session
118
+ * adapter writes its `epcred.` rows through this. */
119
+ export declare function createRowByteIdempotent(kv: KV, key: string, value: unknown): Promise<void>;
120
+ /** Idempotent monotonic revocation mark on a ledger row (revision-pinned CAS; a lost pin
121
+ * re-reads — terminal-now returns, still-active retries). An ABSENT key refuses: the ledger
122
+ * is never-deleted, so "revoke a row that does not exist" is a caller bug or corruption,
123
+ * never a silent success. PACKAGE-INTERNAL (the session adapter routes through this too). */
124
+ export declare function markLedgerRowRevoked(kv: KV, key: string): Promise<"revoked" | "already-revoked">;
125
+ /** A per-handle source gate: `open` mints, `frozen` is the revocation fence (terminal for a
126
+ * revoked handle — a source gate never reopens; SPEC 13.1). */
127
+ export interface SourceGateRow {
128
+ issuerKeyId: string;
129
+ id: string;
130
+ state: "open" | "frozen";
131
+ }
132
+ /** Observe a source gate (the candidate read feeding a pinned CAS/touch). A DEL/PURGE marker
133
+ * refuses loudly — a gate is never deleted. */
134
+ export declare function observeSourceGate(reg: LifecycleRegistry, args: {
135
+ issuerKeyId: string;
136
+ id: string;
137
+ }): Promise<{
138
+ row: SourceGateRow;
139
+ revision: number;
140
+ } | undefined>;
141
+ /** Create a handle's source gate OPEN (at the handle's own provisioning). Create-only:
142
+ * idempotent for the identical row; anything else (including a deletion marker) conflicts. */
143
+ export declare function createSourceGateOpen(reg: LifecycleRegistry, args: {
144
+ issuerKeyId: string;
145
+ id: string;
146
+ }): Promise<void>;
147
+ /** CAS a source gate `open → frozen` at the observed revision — the handle-revocation fence
148
+ * (SPEC 13.1: freeze BEFORE enumerating `bysrc.`; an in-flight redemption either finished
149
+ * before the freeze, so its rows are in the enumeration, or loses its pinned touch). */
150
+ export declare function freezeSourceGate(reg: LifecycleRegistry, args: {
151
+ issuerKeyId: string;
152
+ id: string;
153
+ revision: number;
154
+ }): Promise<void>;
155
+ /** What {@link stageAgentMint} durably staged, handed to {@link finalizeAgentMint}. BRANDED
156
+ * (WeakMap membership): only {@link stageAgentMint} produces one, so a hand-assembled or
157
+ * mutated object (e.g. an empty `pins` array that would finalize with no gate proof) can never
158
+ * reach the touch-CAS. The finalize NEVER trusts fields read back from this object: the
159
+ * authoritative pins/rowKey snapshot lives in the module-private WeakMap value (a
160
+ * shallow-frozen public array left mutable pin OBJECTS a caller could rewrite to duplicate
161
+ * the source-gate pin and skip the lifecycle gate). The public object is deep-frozen too,
162
+ * but the snapshot is the authority. */
163
+ export interface StagedAgentMint {
164
+ readonly lifecycleUid: string;
165
+ readonly credentialId: string;
166
+ /** The observed lifecycle-gate + source-gate pins the finalize touch-CASes, keyed by KV key. */
167
+ readonly pins: ReadonlyArray<{
168
+ readonly key: string;
169
+ readonly revision: number;
170
+ }>;
171
+ /** The staged row's own key (what a losing finalize revokes). */
172
+ readonly rowKey: string;
173
+ }
174
+ /**
175
+ * Stage an AGENT-family mint (SPEC 13.1 mint protocol, steps observe + write-rows): observe
176
+ * the lifecycle issuance gate (must exist and be `open` — a frozen gate is a barrier in
177
+ * flight, a retired one is terminal) and EVERY presented handle's source gate (must exist and
178
+ * be `open`), recording each revision; then create the ledger row (`state: "active"` — the
179
+ * row is authority only after finalize releases, and the barrier enumerates it either way)
180
+ * and one `bysrc.` index row per handle chain member. Returns the staged coordinates for
181
+ * {@link finalizeAgentMint}. Nothing is released here.
182
+ */
183
+ export declare function stageAgentMint(reg: LifecycleRegistry, args: {
184
+ lifecycleUid: string;
185
+ credentialId: string;
186
+ holderPrincipal: string;
187
+ sourceChain: string[];
188
+ exp: number;
189
+ }): Promise<StagedAgentMint>;
190
+ /**
191
+ * Finalize an AGENT-family mint (SPEC 13.1 mint protocol, step gate-CAS): touch-CAS every
192
+ * observed gate — the lifecycle gate and each presented source gate — at its pinned revision,
193
+ * each DISTINCT key once, in CANONICAL (sorted) order (the same crossed-pair discipline as the
194
+ * session stage). The touch preserves the value and bumps only the revision: a barrier or a
195
+ * handle revocation that moved ANY of them since observation makes the pinned write LOSE, the
196
+ * mint marks its OWN row revoked, and throws `permission-denied` — it never releases. Only a
197
+ * finalize that returns cleanly permits the caller to release the credential bytes.
198
+ */
199
+ export declare function finalizeAgentMint(reg: LifecycleRegistry, staged: StagedAgentMint): Promise<void>;
200
+ /** One enumerated ledger row (its key, parsed value, and store revision). */
201
+ export interface EnumeratedRow {
202
+ key: string;
203
+ row: CredentialLedgerRow;
204
+ revision: number;
205
+ }
206
+ /**
207
+ * Enumerate a lifecycle's FULL descendant family `cred.<lifecycleUid>.>` (SPEC 13.1/13.9) through
208
+ * the SEALED auth-ledger scanner ({@link registryScanner}). The scan is a fence-free LastPerSubject
209
+ * read: under the normative history=1 store a same-subject `active→revoked` overwrite EVICTS the
210
+ * pre-scan revision, so the scanner delivers each subject's CURRENT last (a concurrent revoke is
211
+ * SEEN, never dropped). The scanner holds the ONLY auth-stream `CONSUMER.CREATE` on its own sealed
212
+ * credential; the barrier profile holds none (a consumer-create body is not subject-ACL confinable,
213
+ * nats-server#8274 — ledger-scanner.ts).
214
+ */
215
+ export declare function enumerateAgentFamily(reg: LifecycleRegistry, lifecycleUid: string): Promise<EnumeratedRow[]>;
216
+ /** A durable operation intent under `stage.<opId>` (SINGLE segment: the session release pins
217
+ * live at `stage.session.<sid>.<c|s>` and are not operations). */
218
+ export interface OperationIntentRef {
219
+ opId: string;
220
+ kind: "takeover" | "retirement";
221
+ lifecycleUid: string;
222
+ }
223
+ /**
224
+ * Enumerate every durable OPERATION intent `stage.<opId>` (SPEC 13.1) — the boot-resume
225
+ * discovery: a barrier executor that crashed mid-operation finds what it may owe here (whether
226
+ * an intent is actually OWED is the gate's call: only a gate still frozen by that opId is —
227
+ * completed and lost operations leave their intent behind by design). Multi-segment `stage.`
228
+ * keys (the session release pins) are not operations and are skipped; a single-segment intent
229
+ * that carries a DEL/PURGE marker, fails to parse, or names an unknown kind THROWS — an intent
230
+ * is never deleted while resumable, and garbled trusted-path state never drives a barrier.
231
+ */
232
+ export declare function enumerateOperationIntents(reg: LifecycleRegistry): Promise<OperationIntentRef[]>;
233
+ /** The injected VERIFIED-EVICTION seam (§13.9: the barrier executor holds the deployment's
234
+ * `evictPrincipal` capability for exactly this step). `verifiedGone` is the ONLY success. */
235
+ export type EvictPrincipal = (principal: string) => Promise<EvictionResult>;
236
+ /** The injected SESSION-PAIR reconciler (SPEC 13.1: a lifecycle barrier tears down BOTH halves
237
+ * of a session, not just the caller credential under `cred.<uid>.>`). For each distinct
238
+ * `session.<sessionId>` naming a revoked descendant, the barrier calls this to terminalize the
239
+ * `session.<sessionId>` row and revoke the paired serving `epcred.` row, and it RETURNS the
240
+ * serving row's CONNZ-attributable holder principal(s) so the barrier can UNION them into its
241
+ * verified-eviction set (SPEC 13.6: a takeover on either side revokes BOTH credentials WITH
242
+ * eviction — a row-only revocation would leave an already-connected serving session live).
243
+ * Injected (not imported) so the credential ledger never depends on the session adapter.
244
+ * Idempotent: an already-reconciled session still returns its principals (a resumed barrier
245
+ * must still evict). */
246
+ export type ReconcileSessionPair = (sessionId: string) => Promise<{
247
+ servingPrincipals: readonly string[];
248
+ }>;
249
+ /** The barrier's injected capabilities. `reconcileSessionPair` is optional: a deployment with
250
+ * no sessions omits it, but a lifecycle that HAS session-derived credentials and omits it
251
+ * fails loud (a torn-down half would be left live). */
252
+ export interface TakeoverDeps {
253
+ evictPrincipal: EvictPrincipal;
254
+ reconcileSessionPair?: ReconcileSessionPair;
255
+ }
256
+ /** The durable takeover intent at `stage.<opId>` — captured BEFORE the freeze, so a crashed
257
+ * barrier resumes the SAME operation from the SAME coordinates ({@link resumeAgentTakeover}). */
258
+ export interface TakeoverIntent {
259
+ kind: "takeover";
260
+ lifecycleUid: string;
261
+ owner: string;
262
+ actor: string;
263
+ /** The head epoch the barrier supersedes (the epoch CAS advances fromEpoch → fromEpoch+1). */
264
+ fromEpoch: number;
265
+ /** The gate generation the barrier freezes at (the reopen advances it to fromGeneration+1). */
266
+ fromGeneration: number;
267
+ }
268
+ /** The barrier's outcome (durable facts, re-readable on resume). */
269
+ export interface TakeoverResult {
270
+ opId: string;
271
+ lifecycleUid: string;
272
+ /** The successor's fenced epoch (fromEpoch + 1). */
273
+ toEpoch: number;
274
+ /** The gate's first mintable generation for the successor (fromGeneration + 1). */
275
+ toGeneration: number;
276
+ /** Ledger rows this run transitioned `active → revoked` (0 on a resume that found them done). */
277
+ revokedRows: number;
278
+ /** Every DISTINCT principal the barrier verified evicted (family holders + the alias itself). */
279
+ evictedPrincipals: string[];
280
+ }
281
+ /**
282
+ * The shared CONTAINMENT core of the lifecycle barriers (SPEC 13.1: takeover and terminal
283
+ * retirement run the SAME revoke + verified-evict discipline over the SAME family):
284
+ * point-in-time enumeration of `cred.<lifecycleUid>.>` → revoke EVERY row (idempotent — a
285
+ * resumed barrier finds some already revoked; the row CAS is the deny-new SUBSTRATE, module
286
+ * header) → reconcile BOTH halves of every session-derived credential (the reconciler
287
+ * terminalizes `session.<sessionId>` and revokes the paired serving `epcred.` row, returning
288
+ * the serving holders; a lifecycle that HAS session-derived credentials but no reconciler
289
+ * fails loud — the serving half would be left live) → VERIFIED cluster-wide eviction of every
290
+ * enumerated holder principal (revoked earlier runs included: their connections may still be
291
+ * live), the alias principal itself, and every session-serving principal. Fail-closed per
292
+ * principal: anything but `verifiedGone` throws and the calling barrier's gate stays frozen.
293
+ * PACKAGE-INTERNAL: both barriers reach it through the sealed registry only.
294
+ */
295
+ export declare function containLifecycleFamily(reg: LifecycleRegistry, args: {
296
+ owner: string;
297
+ actor: string;
298
+ lifecycleUid: string;
299
+ barrier: "takeover" | "retirement";
300
+ }, deps: TakeoverDeps): Promise<{
301
+ revokedRows: number;
302
+ evictedPrincipals: string[];
303
+ }>;
304
+ /**
305
+ * Run the FULL takeover issuance barrier for a managed-agent lifecycle (SPEC 13.1, in the
306
+ * normative order — see the module header). Idempotent/crash-resumable: every step re-checks
307
+ * durable state, so calling it again with the SAME `opId` (directly or via
308
+ * {@link resumeAgentTakeover}) finishes the same operation; a DIFFERENT operation's freeze,
309
+ * a foreign epoch/generation movement, or a stranger's opId refuses before any CAS.
310
+ *
311
+ * FAIL-CLOSED CONTRACT: any failure after the freeze leaves the gate FROZEN (nothing mints)
312
+ * and the epoch un-advanced; eviction failure (`verifiedGone !== true` for ANY principal)
313
+ * throws `unavailable` — takeover MUST fail loud rather than proceed over a live predecessor.
314
+ */
315
+ export declare function runAgentTakeoverBarrier(reg: LifecycleRegistry, args: {
316
+ owner: string;
317
+ actor: string;
318
+ lifecycleUid: string;
319
+ opId: string;
320
+ }, deps: TakeoverDeps): Promise<TakeoverResult>;
321
+ /** Resume a crashed takeover from its durable intent alone (`{ opId }` — SPEC 13.1: the intent
322
+ * decides WHICH operation a frozen gate belongs to; `{ opId, kind }` alone resumes
323
+ * deterministically). Re-runs {@link runAgentTakeoverBarrier} with the intent's own
324
+ * coordinates; a stranger's opId (no intent) is `not-found`. */
325
+ export declare function resumeAgentTakeover(reg: LifecycleRegistry, opId: string, deps: TakeoverDeps): Promise<TakeoverResult>;
326
+ /**
327
+ * Revoke a sturdy handle at its SOURCE (SPEC 13.1): CAS the source gate `open → frozen` FIRST
328
+ * (the fence — an in-flight redemption under this handle either finished before the freeze,
329
+ * so its rows are in the enumeration, or loses its pinned finalize touch and never releases),
330
+ * then enumerate `bysrc.<issuerKeyId>.<id>.>`, revoke EVERY descendant ledger row it indexes
331
+ * (credentials minted under this handle OR under any descendant handle that carried it in the
332
+ * chain), and run VERIFIED cluster-wide eviction of every revoked row's holder principal —
333
+ * fail-closed, exactly the takeover discipline. The source gate stays frozen forever (a
334
+ * revoked handle never mints again); an already-frozen gate resumes the walk idempotently.
335
+ */
336
+ export declare function revokeHandleSource(reg: LifecycleRegistry, args: {
337
+ issuerKeyId: string;
338
+ id: string;
339
+ }, deps: TakeoverDeps): Promise<{
340
+ revokedRows: number;
341
+ evictedPrincipals: string[];
342
+ }>;
343
+ //# sourceMappingURL=credential-ledger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"credential-ledger.d.ts","sourceRoot":"","sources":["../src/credential-ledger.ts"],"names":[],"mappings":"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"}