@airctrl/cli 0.0.0-stage → 0.4.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.
@@ -0,0 +1,554 @@
1
+ /**
2
+ * U9b-2 · Strict, versioned runtime schemas for SA profiles + handoffs (§10.b #1).
3
+ *
4
+ * State machines (ratified — implemented literally):
5
+ * STANDARD: capability_prepared → claimed → activation_prepared → active → terminal
6
+ * LEGACY: legacy_source → capability_prepared → migration_prepared → activation_prepared → active → terminal
7
+ *
8
+ * Each stage enumerates its EXACT allowed key set (no `+` inheritance): a key not in the
9
+ * set — whether an extra field or material that belongs to another stage — is rejected.
10
+ * `credentialId` is NOT part of the common envelope; it is required/forbidden per stage.
11
+ * The SA identity private raw is never a field in any stage. All failures use the stable
12
+ * code `sa_profile_schema_invalid` and never echo the offending value.
13
+ */
14
+ import { isSaClaimTicketPlaintext } from '@airctrl/sdk';
15
+ import { StoreError } from './errors.js';
16
+ import { isCanonicalB64 } from './canonical.js';
17
+ import { normalizeBaseUrl } from './base-url.js';
18
+ export const PROFILE_SCHEMA_VERSION = 1;
19
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
20
+ const X25519_BYTES = 32;
21
+ const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
22
+ const neStr = (v) => typeof v === 'string' && v.length > 0;
23
+ const uuid = (v) => typeof v === 'string' && UUID_RE.test(v);
24
+ const b64_32 = (v) => isCanonicalB64(v, X25519_BYTES);
25
+ const b64 = (v) => isCanonicalB64(v);
26
+ const baseUrlOk = (v) => {
27
+ if (typeof v !== 'string')
28
+ return false;
29
+ try {
30
+ normalizeBaseUrl(v);
31
+ return true;
32
+ }
33
+ catch {
34
+ return false;
35
+ }
36
+ };
37
+ const eqNum = (n) => (v) => v === n;
38
+ const eqStr = (s) => (v) => v === s;
39
+ const oneOf = (...opts) => (v) => typeof v === 'string' && opts.includes(v);
40
+ const termStatus = oneOf('expired', 'cancelled', 'revoked');
41
+ // U9b-3a: `expiresAt` (ISO-canonical). `isCanonicalIso` is a hoisted function declaration below.
42
+ const isoCanonical = (v) => typeof v === 'string' && isCanonicalIso(v);
43
+ const activationBody = (kind) => (v) => {
44
+ if (!isPlainObject(v))
45
+ return false;
46
+ const keys = kind === 'standard'
47
+ ? ['sealedActivationPayloadB64', 'bearerCommitmentB64', 'popResponseB64']
48
+ : ['sealedActivationPayloadB64', 'bearerCommitmentB64', 'identityResponseB64', 'capResponseB64'];
49
+ const own = Object.keys(v);
50
+ if (own.length !== keys.length)
51
+ return false;
52
+ return keys.every((k) => Object.prototype.hasOwnProperty.call(v, k) && isCanonicalB64(v[k]));
53
+ };
54
+ /** U4 Capa 3 · a durable claim-attempt budget: an integer in 0..2 (F4). */
55
+ const claimAttempts = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 2;
56
+ /** U4 Capa 3 · a non-negative integer (durable commit-result counters). */
57
+ const intNonNeg = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;
58
+ /** U4 Capa 3 · the EXACT 5-field commit body (all canonical base64), persisted at `claimed` (F2). */
59
+ const identityRotationCommitBody = (v) => {
60
+ if (!isPlainObject(v))
61
+ return false;
62
+ const keys = [
63
+ 'sealedActivationPayloadB64',
64
+ 'bearerCommitmentB64',
65
+ 'oldIdentityResponseB64',
66
+ 'newIdentityResponseB64',
67
+ 'successorCapResponseB64',
68
+ ];
69
+ const own = Object.keys(v);
70
+ if (own.length !== keys.length)
71
+ return false;
72
+ return keys.every((k) => Object.prototype.hasOwnProperty.call(v, k) && isCanonicalB64(v[k]));
73
+ };
74
+ /** Validate `obj` against `spec`: exact key set (all required present, nothing extra) + per-field checks. */
75
+ function validateAgainst(obj, spec) {
76
+ const allowed = new Set(Object.keys(spec));
77
+ for (const key of Object.keys(obj)) {
78
+ if (!allowed.has(key))
79
+ throw new StoreError('sa_profile_schema_invalid');
80
+ }
81
+ for (const [key, field] of Object.entries(spec)) {
82
+ const present = Object.prototype.hasOwnProperty.call(obj, key);
83
+ if (!present) {
84
+ if (!field.optional)
85
+ throw new StoreError('sa_profile_schema_invalid');
86
+ continue;
87
+ }
88
+ if (!field.check(obj[key]))
89
+ throw new StoreError('sa_profile_schema_invalid');
90
+ }
91
+ }
92
+ function standardSpec(stage, mode) {
93
+ const s = {
94
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
95
+ flow: { check: eqStr('standard') },
96
+ stage: { check: eqStr(stage) },
97
+ serviceAccountId: { check: neStr },
98
+ baseUrl: { check: baseUrlOk },
99
+ principalType: { check: eqStr('service_account') },
100
+ mode: { check: eqStr(mode) },
101
+ };
102
+ const rotationResume = () => {
103
+ s.holderProfileName = { check: neStr };
104
+ s.holderCredentialId = { check: neStr };
105
+ };
106
+ switch (stage) {
107
+ case 'capability_prepared':
108
+ s.expiresAt = { check: isoCanonical }; // U9b-3a: REQUIRED in STANDARD pending
109
+ s.credentialId = { check: neStr };
110
+ s.capPublicKeyB64 = { check: b64_32 };
111
+ s.capPrivateKeyB64 = { check: b64_32 };
112
+ s.claimIdempotencyKey = { check: uuid };
113
+ if (mode === 'bootstrap')
114
+ s.handoffId = { check: neStr };
115
+ else
116
+ rotationResume();
117
+ return s;
118
+ case 'claimed':
119
+ s.expiresAt = { check: isoCanonical }; // U9b-3a: REQUIRED in STANDARD pending
120
+ s.credentialId = { check: neStr };
121
+ s.capPublicKeyB64 = { check: b64_32 };
122
+ s.capPrivateKeyB64 = { check: b64_32 };
123
+ s.bearer = { check: neStr };
124
+ s.patId = { check: neStr };
125
+ s.popChallengeSealedB64 = { check: b64 };
126
+ if (mode === 'rotation') {
127
+ rotationResume();
128
+ // U9b-3e-4 · D4: the successor's advertised STABLE SA identity public — persisted at `claimed` so a
129
+ // post-crash resume can reconstruct the FULL `SaClaimResult` and run the REAL H4 (assertIdentityMatches)
130
+ // in `buildSuccessorActivation` without synthesizing it from A. Public material (32B), never a secret;
131
+ // REQUIRED only here (rotation `claimed`), FORBIDDEN elsewhere/bootstrap, DROPPED on `activation_prepared`.
132
+ s.saIdentityPublicKeyB64 = { check: b64_32 };
133
+ }
134
+ return s;
135
+ case 'activation_prepared':
136
+ s.expiresAt = { check: isoCanonical }; // U9b-3a: REQUIRED in STANDARD pending
137
+ s.credentialId = { check: neStr };
138
+ s.capPublicKeyB64 = { check: b64_32 };
139
+ s.capPrivateKeyB64 = { check: b64_32 };
140
+ s.bearer = { check: neStr };
141
+ s.patId = { check: neStr };
142
+ s.activationBody = { check: activationBody('standard') };
143
+ s.activateIdempotencyKey = { check: uuid };
144
+ if (mode === 'rotation')
145
+ rotationResume();
146
+ return s;
147
+ case 'active':
148
+ s.credentialId = { check: neStr };
149
+ s.patId = { check: neStr };
150
+ s.bearer = { check: neStr };
151
+ s.capPublicKeyB64 = { check: b64_32 };
152
+ s.capPrivateKeyB64 = { check: b64_32 };
153
+ // U9b-3e-4 · D6: a rotation's `active` profile carries the durable, non-secret `operationId` completion binding
154
+ // so a crash AFTER the artifact was durably unlinked but BEFORE stdout/lease-release is recoverable and can NEVER
155
+ // be adopted by a different operation. REQUIRED only for rotation; FORBIDDEN for bootstrap (the shape is exact).
156
+ if (mode === 'rotation')
157
+ s.operationId = { check: uuid };
158
+ return s;
159
+ case 'terminal':
160
+ s.credentialId = { check: neStr };
161
+ s.terminalStatus = { check: termStatus };
162
+ s.terminalReason = { check: neStr };
163
+ s.patId = { check: neStr, optional: true };
164
+ return s;
165
+ default:
166
+ throw new StoreError('sa_profile_schema_invalid');
167
+ }
168
+ }
169
+ /**
170
+ * U4 Capa 3 · identity-rotation successor profile spec (`flow:'standard'`, `mode:'identity_rotation'`). Exact
171
+ * key set per stage; ZERO raw identity private in any stage (the new identity private lives ONLY inside the
172
+ * SEALED `seedSealedB64`, openable by the persisted successor cap private). The successor cap keypair uses the
173
+ * common `capPublicKeyB64`/`capPrivateKeyB64` names so the terminal `active` profile is a normal usable SA
174
+ * credential. Holder binding (F3) and the durable claim budget (F4) live only in `identity_prepared`; the exact
175
+ * commit body + `commitIdempotencyKey` (F2) appear from `claimed`. Per-batch stage keys live in the journal, NOT here.
176
+ */
177
+ function identityRotationSpec(stage) {
178
+ const s = {
179
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
180
+ flow: { check: eqStr('standard') },
181
+ stage: { check: eqStr(stage) },
182
+ serviceAccountId: { check: neStr },
183
+ baseUrl: { check: baseUrlOk },
184
+ principalType: { check: eqStr('service_account') },
185
+ mode: { check: eqStr('identity_rotation') },
186
+ };
187
+ const holderBinding = () => {
188
+ s.holderProfileName = { check: neStr };
189
+ s.holderCredentialId = { check: neStr };
190
+ s.holderPatId = { check: neStr };
191
+ s.holderIdentityPublicKeyB64 = { check: b64_32 };
192
+ };
193
+ // Identity material WITHOUT the sealed seed — the seed lives ONLY in `identity_prepared` (F1); from `claimed`
194
+ // onward the new identity private is recovered from `commitBody.sealedActivationPayloadB64` (cap-sealed), never
195
+ // from a persisted seed.
196
+ const identityMaterialNoSeed = () => {
197
+ s.operationId = { check: uuid };
198
+ s.newIdentityPublicKeyB64 = { check: b64_32 };
199
+ s.capPublicKeyB64 = { check: b64_32 };
200
+ s.capPrivateKeyB64 = { check: b64_32 };
201
+ };
202
+ const claimedShape = () => {
203
+ identityMaterialNoSeed(); // NO seedSealedB64 here (F1) — dropped on the durable transition to `claimed`
204
+ s.credentialId = { check: neStr };
205
+ s.bearer = { check: neStr };
206
+ s.patId = { check: neStr };
207
+ s.commitBody = { check: identityRotationCommitBody }; // carries the sealedActivationPayloadB64 for recovery
208
+ s.commitIdempotencyKey = { check: uuid };
209
+ holderBinding();
210
+ };
211
+ switch (stage) {
212
+ case 'identity_prepared':
213
+ identityMaterialNoSeed();
214
+ s.seedSealedB64 = { check: b64 }; // F1: the sealed new-identity seed exists ONLY in identity_prepared
215
+ s.claimIdempotencyKey = { check: uuid }; // F1: UUID, never base64url
216
+ s.claimAttempts = { check: claimAttempts }; // F4: durable budget 0..2
217
+ holderBinding(); // F3: exact holder binding
218
+ return s;
219
+ case 'claimed':
220
+ case 'staging':
221
+ case 'commit_prepared':
222
+ claimedShape();
223
+ return s;
224
+ case 'active_pending_cleanup':
225
+ // Post-commit, pre-cleanup: the successor is usable AND carries the non-secret holder binding + durable commit
226
+ // result so a crash reruns cleanup (holder terminalize + journal delete) WITHOUT re-unlocking the revoked holder,
227
+ // then strips this aux on the validated transition to the clean `active`.
228
+ s.operationId = { check: uuid };
229
+ s.credentialId = { check: neStr };
230
+ s.patId = { check: neStr };
231
+ s.bearer = { check: neStr };
232
+ s.capPublicKeyB64 = { check: b64_32 };
233
+ s.capPrivateKeyB64 = { check: b64_32 };
234
+ s.holderProfileName = { check: neStr };
235
+ s.holderCredentialId = { check: neStr };
236
+ s.holderPatId = { check: neStr };
237
+ s.resultResealedRecord = { check: intNonNeg };
238
+ s.resultResealedProject = { check: intNonNeg };
239
+ s.resultRevoked = { check: intNonNeg };
240
+ return s;
241
+ case 'active':
242
+ // The successor is now the active credential — a normal usable SA active profile (D6 keeps operationId).
243
+ s.operationId = { check: uuid };
244
+ s.credentialId = { check: neStr };
245
+ s.patId = { check: neStr };
246
+ s.bearer = { check: neStr };
247
+ s.capPublicKeyB64 = { check: b64_32 };
248
+ s.capPrivateKeyB64 = { check: b64_32 };
249
+ return s;
250
+ case 'terminal':
251
+ s.credentialId = { check: neStr };
252
+ s.terminalStatus = { check: termStatus };
253
+ s.terminalReason = { check: neStr };
254
+ s.patId = { check: neStr, optional: true };
255
+ return s;
256
+ default:
257
+ throw new StoreError('sa_profile_schema_invalid');
258
+ }
259
+ }
260
+ function legacySpec(stage) {
261
+ const s = {
262
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
263
+ flow: { check: eqStr('legacy_migration') },
264
+ stage: { check: eqStr(stage) },
265
+ serviceAccountId: { check: neStr },
266
+ baseUrl: { check: baseUrlOk },
267
+ principalType: {
268
+ check: stage === 'active'
269
+ ? eqStr('service_account')
270
+ : stage === 'terminal'
271
+ ? oneOf('service_account', 'service_account_legacy')
272
+ : eqStr('service_account_legacy'),
273
+ },
274
+ };
275
+ switch (stage) {
276
+ case 'legacy_source':
277
+ s.bearer = { check: neStr };
278
+ return s;
279
+ case 'capability_prepared':
280
+ s.bearer = { check: neStr };
281
+ s.capPublicKeyB64 = { check: b64_32 };
282
+ s.capPrivateKeyB64 = { check: b64_32 };
283
+ s.prepareIdempotencyKey = { check: uuid };
284
+ return s;
285
+ case 'migration_prepared':
286
+ s.expiresAt = { check: isoCanonical }; // U9b-3a: REQUIRED in LEGACY pending
287
+ s.credentialId = { check: neStr };
288
+ s.bearer = { check: neStr };
289
+ s.capPublicKeyB64 = { check: b64_32 };
290
+ s.capPrivateKeyB64 = { check: b64_32 };
291
+ s.identityChallengeSealedB64 = { check: b64 };
292
+ s.capChallengeSealedB64 = { check: b64 };
293
+ return s;
294
+ case 'activation_prepared':
295
+ s.expiresAt = { check: isoCanonical }; // U9b-3a: REQUIRED in LEGACY pending
296
+ s.credentialId = { check: neStr };
297
+ s.bearer = { check: neStr };
298
+ s.capPublicKeyB64 = { check: b64_32 };
299
+ s.capPrivateKeyB64 = { check: b64_32 };
300
+ s.activationBody = { check: activationBody('legacy') };
301
+ s.completeIdempotencyKey = { check: uuid };
302
+ return s;
303
+ case 'active':
304
+ s.credentialId = { check: neStr };
305
+ s.patId = { check: neStr };
306
+ s.bearer = { check: neStr };
307
+ s.capPublicKeyB64 = { check: b64_32 };
308
+ s.capPrivateKeyB64 = { check: b64_32 };
309
+ return s;
310
+ case 'terminal':
311
+ s.credentialId = { check: neStr };
312
+ s.terminalStatus = { check: termStatus };
313
+ s.terminalReason = { check: neStr };
314
+ s.patId = { check: neStr, optional: true };
315
+ return s;
316
+ default:
317
+ throw new StoreError('sa_profile_schema_invalid');
318
+ }
319
+ }
320
+ /** Validate a decoded object as a versioned profile; returns it typed, or throws. */
321
+ export function validateProfile(raw) {
322
+ if (!isPlainObject(raw))
323
+ throw new StoreError('sa_profile_schema_invalid');
324
+ if (raw.schemaVersion !== PROFILE_SCHEMA_VERSION)
325
+ throw new StoreError('sa_profile_schema_invalid');
326
+ const flow = raw.flow;
327
+ if (flow === 'standard') {
328
+ const mode = raw.mode;
329
+ if (mode === 'identity_rotation') {
330
+ validateAgainst(raw, identityRotationSpec(typeof raw.stage === 'string' ? raw.stage : ''));
331
+ }
332
+ else if (mode === 'bootstrap' || mode === 'rotation') {
333
+ validateAgainst(raw, standardSpec(typeof raw.stage === 'string' ? raw.stage : '', mode));
334
+ }
335
+ else {
336
+ throw new StoreError('sa_profile_schema_invalid');
337
+ }
338
+ }
339
+ else if (flow === 'legacy_migration') {
340
+ validateAgainst(raw, legacySpec(typeof raw.stage === 'string' ? raw.stage : ''));
341
+ }
342
+ else {
343
+ throw new StoreError('sa_profile_schema_invalid');
344
+ }
345
+ return raw;
346
+ }
347
+ // `claimTicket` uses the SHARED SSOT acceptor (`@airctrl/crypto` via SDK) — the exact format the client
348
+ // generator targets and the backend accepts — NOT a loose non-empty check.
349
+ const PROVISIONAL_HANDOFF_SPEC = {
350
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
351
+ operationId: { check: uuid },
352
+ claimTicket: { check: (v) => isSaClaimTicketPlaintext(v) },
353
+ serviceAccountId: { check: neStr },
354
+ baseUrl: { check: baseUrlOk },
355
+ };
356
+ const FINALIZED_HANDOFF_SPEC = {
357
+ ...PROVISIONAL_HANDOFF_SPEC,
358
+ credentialId: { check: neStr },
359
+ expiresAt: { check: isoCanonical },
360
+ };
361
+ function isCanonicalIso(s) {
362
+ const d = new Date(s);
363
+ return !Number.isNaN(d.getTime()) && d.toISOString() === s;
364
+ }
365
+ /** Structural validation of a PROVISIONAL handoff (no `credentialId`/`expiresAt`). */
366
+ export function validateProvisionalHandoff(raw) {
367
+ if (!isPlainObject(raw))
368
+ throw new StoreError('sa_handoff_schema_invalid');
369
+ try {
370
+ validateAgainst(raw, PROVISIONAL_HANDOFF_SPEC);
371
+ }
372
+ catch {
373
+ throw new StoreError('sa_handoff_schema_invalid');
374
+ }
375
+ return raw;
376
+ }
377
+ /** Structural validation of a FINALIZED handoff (does NOT check expiry — see {@link assertHandoffNotExpired}). */
378
+ export function validateFinalizedHandoff(raw) {
379
+ if (!isPlainObject(raw))
380
+ throw new StoreError('sa_handoff_schema_invalid');
381
+ try {
382
+ validateAgainst(raw, FINALIZED_HANDOFF_SPEC);
383
+ }
384
+ catch {
385
+ throw new StoreError('sa_handoff_schema_invalid');
386
+ }
387
+ return raw;
388
+ }
389
+ /** Throw `sa_handoff_expired` if the FINALIZED handoff's `expiresAt` is at or before `nowMs`. */
390
+ export function assertHandoffNotExpired(handoff, nowMs) {
391
+ if (new Date(handoff.expiresAt).getTime() <= nowMs)
392
+ throw new StoreError('sa_handoff_expired');
393
+ }
394
+ const ROTATION_ARTIFACT_SPEC = {
395
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
396
+ operationId: { check: uuid },
397
+ credentialId: { check: neStr },
398
+ expiresAt: { check: isoCanonical },
399
+ serviceAccountId: { check: neStr },
400
+ baseUrl: { check: baseUrlOk },
401
+ };
402
+ /**
403
+ * Validate a rotation artifact — exact key set. ANY extra field (especially a secret: claimTicket, bearer,
404
+ * capPrivate, SA-private, sealed payload, PoP, activationBody) → `sa_rotation_artifact_schema_invalid`.
405
+ */
406
+ export function validateRotationArtifact(raw) {
407
+ if (!isPlainObject(raw))
408
+ throw new StoreError('sa_rotation_artifact_schema_invalid');
409
+ try {
410
+ validateAgainst(raw, ROTATION_ARTIFACT_SPEC);
411
+ }
412
+ catch {
413
+ throw new StoreError('sa_rotation_artifact_schema_invalid');
414
+ }
415
+ return raw;
416
+ }
417
+ const isBool = (v) => typeof v === 'boolean';
418
+ const CANCEL_RECEIPT_SPEC = {
419
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
420
+ serviceAccountId: { check: neStr },
421
+ terminalStatus: { check: eqStr('cancelled') },
422
+ credentialId: { check: neStr },
423
+ terminalReason: { check: neStr },
424
+ baseUrl: { check: baseUrlOk },
425
+ createdAt: { check: isoCanonical },
426
+ };
427
+ const REVOKE_RECEIPT_SPEC = {
428
+ schemaVersion: { check: eqNum(PROFILE_SCHEMA_VERSION) },
429
+ serviceAccountId: { check: neStr },
430
+ terminalStatus: { check: eqStr('revoked') },
431
+ patId: { check: neStr },
432
+ cryptoLocked: { check: isBool },
433
+ terminalReason: { check: neStr },
434
+ baseUrl: { check: baseUrlOk },
435
+ createdAt: { check: isoCanonical },
436
+ };
437
+ /** Validate a receipt as EXACTLY one of the two ratified variants; any mix → `sa_receipt_schema_invalid`. */
438
+ export function validateReceipt(raw) {
439
+ if (!isPlainObject(raw))
440
+ throw new StoreError('sa_receipt_schema_invalid');
441
+ const spec = raw.terminalStatus === 'cancelled'
442
+ ? CANCEL_RECEIPT_SPEC
443
+ : raw.terminalStatus === 'revoked'
444
+ ? REVOKE_RECEIPT_SPEC
445
+ : null;
446
+ if (!spec)
447
+ throw new StoreError('sa_receipt_schema_invalid');
448
+ try {
449
+ validateAgainst(raw, spec);
450
+ }
451
+ catch {
452
+ throw new StoreError('sa_receipt_schema_invalid');
453
+ }
454
+ return raw;
455
+ }
456
+ // Ratified legal edges (§10.b state machines). Terminal is reachable only from stages that hold a
457
+ // remote credential; LEGACY legacy_source/capability_prepared have NO terminal edge — aborting them
458
+ // is a direct unlink (see profile-store.abortUnprovisionedLegacyProfile), never a `terminal` replace.
459
+ const EDGES = {
460
+ standard: {
461
+ capability_prepared: ['claimed', 'terminal'],
462
+ claimed: ['activation_prepared', 'terminal'],
463
+ activation_prepared: ['active', 'terminal'],
464
+ active: ['terminal'],
465
+ },
466
+ legacy_migration: {
467
+ legacy_source: ['capability_prepared'],
468
+ capability_prepared: ['migration_prepared'],
469
+ migration_prepared: ['activation_prepared', 'terminal'],
470
+ activation_prepared: ['active', 'terminal'],
471
+ active: ['terminal'],
472
+ },
473
+ };
474
+ // U4 Capa 3 · identity-rotation edges (mode:'identity_rotation'). `identity_prepared` has NO terminal edge —
475
+ // pre-claim there is no local successor credentialId to record, so aborting it is a direct unlink (mirrors the
476
+ // legacy legacy_source pattern) + an ADMIN cancel of the remote op.
477
+ const IDENTITY_ROTATION_EDGES = {
478
+ identity_prepared: ['claimed'],
479
+ claimed: ['staging', 'terminal'],
480
+ staging: ['commit_prepared', 'terminal'],
481
+ commit_prepared: ['active_pending_cleanup', 'terminal'],
482
+ active_pending_cleanup: ['active', 'terminal'], // strips the aux (holder binding + result) → clean active
483
+ active: ['terminal'],
484
+ };
485
+ function eqIfBoth(a, b, key) {
486
+ if (a[key] !== undefined && b[key] !== undefined)
487
+ return a[key] === b[key];
488
+ return true;
489
+ }
490
+ /**
491
+ * Enforce a ratified `current → next` transition (§10.b) BEFORE writing. Rejects illegal stage jumps
492
+ * and any change to identity/binding invariants (flow, mode, serviceAccountId, baseUrl, credentialId,
493
+ * cap keypair, bearer, patId, rotation holder refs). The ONLY principalType change allowed is the
494
+ * ratified LEGACY promotion to `service_account` on reaching `active`. Throws `sa_profile_transition_invalid`.
495
+ */
496
+ export function assertTransition(current, next) {
497
+ const cur = current;
498
+ const nxt = next;
499
+ const invalid = () => {
500
+ throw new StoreError('sa_profile_transition_invalid');
501
+ };
502
+ if (cur.schemaVersion !== nxt.schemaVersion)
503
+ invalid();
504
+ if (current.flow !== next.flow)
505
+ invalid();
506
+ // Identity rotation (mode:'identity_rotation') has its OWN edge set (distinct stages); every other standard
507
+ // profile keeps the ratified bootstrap/rotation edges. Mode is immutable across every transition.
508
+ const identityRotation = current.flow === 'standard' && cur.mode === 'identity_rotation';
509
+ const legal = identityRotation ? IDENTITY_ROTATION_EDGES[current.stage] : EDGES[current.flow]?.[current.stage];
510
+ if (!legal || !legal.includes(next.stage))
511
+ invalid();
512
+ if (current.flow === 'standard' && cur.mode !== nxt.mode)
513
+ invalid();
514
+ if (current.serviceAccountId !== next.serviceAccountId)
515
+ invalid();
516
+ try {
517
+ if (normalizeBaseUrl(current.baseUrl) !== normalizeBaseUrl(next.baseUrl))
518
+ invalid();
519
+ }
520
+ catch {
521
+ invalid();
522
+ }
523
+ // credentialId, once present, is immutable (introduction on legacy capability_prepared→migration_prepared is allowed).
524
+ if (cur.credentialId !== undefined && cur.credentialId !== nxt.credentialId)
525
+ invalid();
526
+ // `expiresAt` (U9b-3a) is immutable across the pending stages where it appears; its ratified removal on
527
+ // reaching `active`/`terminal` (one side undefined) is allowed by `eqIfBoth` and required by those specs.
528
+ for (const key of [
529
+ 'capPublicKeyB64',
530
+ 'capPrivateKeyB64',
531
+ 'bearer',
532
+ 'patId',
533
+ 'holderProfileName',
534
+ 'holderCredentialId',
535
+ 'expiresAt',
536
+ // U4 Capa 3 · identity-rotation binding invariants: the new identity, its sealed seed, the operation, the
537
+ // holder pat/identity, and the exact commit key are immutable once present (each side undefined = allowed drop).
538
+ 'operationId',
539
+ 'newIdentityPublicKeyB64',
540
+ 'seedSealedB64',
541
+ 'holderPatId',
542
+ 'holderIdentityPublicKeyB64',
543
+ 'commitIdempotencyKey',
544
+ ]) {
545
+ if (!eqIfBoth(cur, nxt, key))
546
+ invalid();
547
+ }
548
+ const promotesLegacy = current.flow === 'legacy_migration' && next.stage === 'active';
549
+ if (current.principalType !== next.principalType) {
550
+ if (!(promotesLegacy && current.principalType === 'service_account_legacy' && next.principalType === 'service_account')) {
551
+ invalid();
552
+ }
553
+ }
554
+ }
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "@airctrl/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.0",
4
+ "type": "module",
5
+ "description": "AIRCTRL CLI for encrypted records, process injection, projects, gateways and Service Accounts.",
6
+ "license": "UNLICENSED",
7
+ "homepage": "https://docs.airctrl.dev/cli/overview",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://gitlab.com/theovex/theo/airctrl.git",
11
+ "directory": "packages/cli"
12
+ },
13
+ "bin": {
14
+ "airctrl": "dist/index.js"
15
+ },
16
+ "main": "dist/index.js",
17
+ "exports": {
18
+ ".": "./dist/index.js"
19
+ },
20
+ "files": [
21
+ "dist",
22
+ "!dist/.freshbuild-stamp"
23
+ ],
24
+ "engines": {
25
+ "node": "22.x"
26
+ },
27
+ "keywords": [
28
+ "airctrl",
29
+ "secrets",
30
+ "zero-knowledge",
31
+ "cli",
32
+ "devops"
33
+ ],
34
+ "publishConfig": {
35
+ "access": "public"
36
+ },
37
+ "scripts": {
38
+ "build": "tsc",
39
+ "dev": "tsx src/index.ts"
40
+ },
41
+ "dependencies": {
42
+ "@airctrl/sdk": "0.4.0"
43
+ }
44
+ }