@run402/sdk 4.94.0 → 4.96.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.
- package/README.md +44 -44
- package/core-dist/keystore.d.ts +1 -1
- package/core-dist/keystore.js +1 -1
- package/dist/actions.d.ts +3 -3
- package/dist/actions.d.ts.map +1 -1
- package/dist/app-up.d.ts +2 -2
- package/dist/app-up.d.ts.map +1 -1
- package/dist/config.d.ts +1 -2
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js.map +1 -1
- package/dist/credentials.d.ts +1 -1
- package/dist/errors.d.ts +6 -6
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +1 -1
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +9 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -9
- package/dist/index.js.map +1 -1
- package/dist/namespaces/admin.d.ts +1 -1
- package/dist/namespaces/admin.d.ts.map +1 -1
- package/dist/namespaces/ai.d.ts +1 -1
- package/dist/namespaces/ai.js +2 -2
- package/dist/namespaces/ai.js.map +1 -1
- package/dist/namespaces/assets.js +1 -1
- package/dist/namespaces/assets.js.map +1 -1
- package/dist/namespaces/ci.js +3 -3
- package/dist/namespaces/ci.js.map +1 -1
- package/dist/namespaces/deploy.d.ts +5 -5
- package/dist/namespaces/deploy.d.ts.map +1 -1
- package/dist/namespaces/deploy.js +45 -46
- package/dist/namespaces/deploy.js.map +1 -1
- package/dist/namespaces/deploy.types.d.ts +19 -19
- package/dist/namespaces/deploy.types.d.ts.map +1 -1
- package/dist/namespaces/domains.d.ts +10 -2
- package/dist/namespaces/domains.d.ts.map +1 -1
- package/dist/namespaces/domains.js +10 -5
- package/dist/namespaces/domains.js.map +1 -1
- package/dist/namespaces/errors.js +1 -1
- package/dist/namespaces/functions.js +1 -1
- package/dist/namespaces/functions.js.map +1 -1
- package/dist/namespaces/org.d.ts +2 -2
- package/dist/namespaces/org.js +2 -2
- package/dist/namespaces/org.types.d.ts +3 -3
- package/dist/namespaces/pay.js +1 -1
- package/dist/namespaces/{gitvault.d.ts → repos.d.ts} +438 -451
- package/dist/namespaces/repos.d.ts.map +1 -0
- package/dist/namespaces/{gitvault.js → repos.js} +454 -462
- package/dist/namespaces/repos.js.map +1 -0
- package/dist/namespaces/rooms.js +2 -2
- package/dist/namespaces/rooms.js.map +1 -1
- package/dist/namespaces/session.d.ts +2 -2
- package/dist/namespaces/session.d.ts.map +1 -1
- package/dist/namespaces/session.js +2 -2
- package/dist/namespaces/session.js.map +1 -1
- package/dist/namespaces/tier.d.ts +4 -4
- package/dist/namespaces/tier.d.ts.map +1 -1
- package/dist/namespaces/transfers.d.ts +46 -15
- package/dist/namespaces/transfers.d.ts.map +1 -1
- package/dist/namespaces/transfers.js.map +1 -1
- package/dist/namespaces/{gitvault.crypto.d.ts → vault.crypto.d.ts} +141 -141
- package/dist/namespaces/vault.crypto.d.ts.map +1 -0
- package/dist/namespaces/{gitvault.crypto.js → vault.crypto.js} +173 -173
- package/dist/namespaces/vault.crypto.js.map +1 -0
- package/dist/namespaces/{gitvault.types.d.ts → vault.types.d.ts} +136 -136
- package/dist/namespaces/vault.types.d.ts.map +1 -0
- package/dist/namespaces/{gitvault.types.js → vault.types.js} +4 -4
- package/dist/namespaces/vault.types.js.map +1 -0
- package/dist/node/actions-node.js +8 -8
- package/dist/node/actions-node.js.map +1 -1
- package/dist/node/assets-node.js +6 -6
- package/dist/node/assets-node.js.map +1 -1
- package/dist/node/bearer-redeem-key.d.ts +1 -1
- package/dist/node/bearer-redeem-key.js +5 -5
- package/dist/node/bearer-redeem-key.js.map +1 -1
- package/dist/node/ci.js +1 -1
- package/dist/node/ci.js.map +1 -1
- package/dist/node/credentials.d.ts +1 -1
- package/dist/node/credentials.js +1 -1
- package/dist/node/deploy-manifest.d.ts +3 -5
- package/dist/node/deploy-manifest.d.ts.map +1 -1
- package/dist/node/deploy-manifest.js +3 -12
- package/dist/node/deploy-manifest.js.map +1 -1
- package/dist/node/http-dispatcher.js +5 -5
- package/dist/node/http-dispatcher.js.map +1 -1
- package/dist/node/index.d.ts +29 -29
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/index.js +39 -39
- package/dist/node/index.js.map +1 -1
- package/dist/node/manifest-export.js +2 -2
- package/dist/node/manifest-export.js.map +1 -1
- package/dist/node/org-adopt.js +1 -1
- package/dist/node/org-adopt.js.map +1 -1
- package/dist/node/sites-node.js +1 -1
- package/dist/node/sites-node.js.map +1 -1
- package/dist/node/{gitvault-address.d.ts → vault-address.d.ts} +42 -42
- package/dist/node/vault-address.d.ts.map +1 -0
- package/dist/node/{gitvault-address.js → vault-address.js} +43 -43
- package/dist/node/vault-address.js.map +1 -0
- package/dist/node/{gitvault-apply.d.ts → vault-apply.d.ts} +27 -27
- package/dist/node/vault-apply.d.ts.map +1 -0
- package/dist/node/{gitvault-apply.js → vault-apply.js} +38 -38
- package/dist/node/vault-apply.js.map +1 -0
- package/dist/node/vault-byo-config.d.ts +29 -0
- package/dist/node/vault-byo-config.d.ts.map +1 -0
- package/dist/node/{gitvault-byo-config.js → vault-byo-config.js} +18 -18
- package/dist/node/vault-byo-config.js.map +1 -0
- package/dist/node/vault-byo-probe.d.ts +20 -0
- package/dist/node/vault-byo-probe.d.ts.map +1 -0
- package/dist/node/vault-byo-probe.js +57 -0
- package/dist/node/vault-byo-probe.js.map +1 -0
- package/dist/node/{gitvault-creation-journal.d.ts → vault-creation-journal.d.ts} +69 -69
- package/dist/node/vault-creation-journal.d.ts.map +1 -0
- package/dist/node/{gitvault-creation-journal.js → vault-creation-journal.js} +54 -54
- package/dist/node/vault-creation-journal.js.map +1 -0
- package/dist/node/{gitvault-degraded-read.d.ts → vault-degraded-read.d.ts} +34 -34
- package/dist/node/vault-degraded-read.d.ts.map +1 -0
- package/dist/node/{gitvault-degraded-read.js → vault-degraded-read.js} +24 -24
- package/dist/node/vault-degraded-read.js.map +1 -0
- package/dist/node/{gitvault-deploy.d.ts → vault-deploy.d.ts} +67 -67
- package/dist/node/vault-deploy.d.ts.map +1 -0
- package/dist/node/{gitvault-deploy.js → vault-deploy.js} +27 -27
- package/dist/node/vault-deploy.js.map +1 -0
- package/dist/node/{gitvault-edge-fetch.d.ts → vault-edge-fetch.d.ts} +9 -9
- package/dist/node/vault-edge-fetch.d.ts.map +1 -0
- package/dist/node/{gitvault-edge-fetch.js → vault-edge-fetch.js} +11 -11
- package/dist/node/vault-edge-fetch.js.map +1 -0
- package/dist/node/{gitvault-handoff.d.ts → vault-handoff.d.ts} +9 -9
- package/dist/node/vault-handoff.d.ts.map +1 -0
- package/dist/node/{gitvault-handoff.js → vault-handoff.js} +24 -24
- package/dist/node/vault-handoff.js.map +1 -0
- package/dist/node/{gitvault-keystore.d.ts → vault-keystore.d.ts} +87 -77
- package/dist/node/vault-keystore.d.ts.map +1 -0
- package/dist/node/{gitvault-keystore.js → vault-keystore.js} +105 -68
- package/dist/node/vault-keystore.js.map +1 -0
- package/dist/node/{gitvault-member-bundle.d.ts → vault-member-bundle.d.ts} +17 -17
- package/dist/node/vault-member-bundle.d.ts.map +1 -0
- package/dist/node/{gitvault-member-bundle.js → vault-member-bundle.js} +11 -11
- package/dist/node/vault-member-bundle.js.map +1 -0
- package/dist/node/{gitvault-mirror-backend.d.ts → vault-mirror-backend.d.ts} +26 -26
- package/dist/node/vault-mirror-backend.d.ts.map +1 -0
- package/dist/node/{gitvault-mirror-backend.js → vault-mirror-backend.js} +25 -25
- package/dist/node/vault-mirror-backend.js.map +1 -0
- package/dist/node/{gitvault-mirror-config.d.ts → vault-mirror-config.d.ts} +23 -23
- package/dist/node/vault-mirror-config.d.ts.map +1 -0
- package/dist/node/{gitvault-mirror-config.js → vault-mirror-config.js} +16 -16
- package/dist/node/vault-mirror-config.js.map +1 -0
- package/dist/node/{gitvault-mirror.d.ts → vault-mirror.d.ts} +36 -36
- package/dist/node/vault-mirror.d.ts.map +1 -0
- package/dist/node/{gitvault-mirror.js → vault-mirror.js} +75 -75
- package/dist/node/vault-mirror.js.map +1 -0
- package/dist/node/{gitvault-native-crypto.d.ts → vault-native-crypto.d.ts} +10 -10
- package/dist/node/vault-native-crypto.d.ts.map +1 -0
- package/dist/node/{gitvault-native-crypto.js → vault-native-crypto.js} +16 -16
- package/dist/node/vault-native-crypto.js.map +1 -0
- package/dist/node/{gitvault-open-or-create.d.ts → vault-open-or-create.d.ts} +16 -16
- package/dist/node/vault-open-or-create.d.ts.map +1 -0
- package/dist/node/{gitvault-open-or-create.js → vault-open-or-create.js} +10 -10
- package/dist/node/vault-open-or-create.js.map +1 -0
- package/dist/node/{gitvault-prewarm.d.ts → vault-prewarm.d.ts} +13 -13
- package/dist/node/vault-prewarm.d.ts.map +1 -0
- package/dist/node/{gitvault-prewarm.js → vault-prewarm.js} +25 -25
- package/dist/node/vault-prewarm.js.map +1 -0
- package/dist/node/{gitvault-profile-scan.d.ts → vault-profile-scan.d.ts} +3 -3
- package/dist/node/vault-profile-scan.d.ts.map +1 -0
- package/dist/node/{gitvault-profile-scan.js → vault-profile-scan.js} +12 -12
- package/dist/node/vault-profile-scan.js.map +1 -0
- package/dist/node/{gitvault-prune.d.ts → vault-prune.d.ts} +61 -61
- package/dist/node/vault-prune.d.ts.map +1 -0
- package/dist/node/{gitvault-prune.js → vault-prune.js} +34 -34
- package/dist/node/vault-prune.js.map +1 -0
- package/dist/node/{gitvault-publication.d.ts → vault-publication.d.ts} +399 -399
- package/dist/node/vault-publication.d.ts.map +1 -0
- package/dist/node/{gitvault-publication.js → vault-publication.js} +584 -584
- package/dist/node/vault-publication.js.map +1 -0
- package/dist/node/{gitvault-push-to-create.d.ts → vault-push-to-create.d.ts} +16 -16
- package/dist/node/vault-push-to-create.d.ts.map +1 -0
- package/dist/node/{gitvault-push-to-create.js → vault-push-to-create.js} +9 -9
- package/dist/node/vault-push-to-create.js.map +1 -0
- package/dist/node/{gitvault-recover.d.ts → vault-recover.d.ts} +50 -50
- package/dist/node/vault-recover.d.ts.map +1 -0
- package/dist/node/{gitvault-recover.js → vault-recover.js} +84 -84
- package/dist/node/vault-recover.js.map +1 -0
- package/dist/node/{gitvault-restore.d.ts → vault-restore.d.ts} +8 -8
- package/dist/node/vault-restore.d.ts.map +1 -0
- package/dist/node/{gitvault-restore.js → vault-restore.js} +11 -11
- package/dist/node/vault-restore.js.map +1 -0
- package/dist/node/{gitvault-snapshot.d.ts → vault-snapshot.d.ts} +48 -48
- package/dist/node/vault-snapshot.d.ts.map +1 -0
- package/dist/node/{gitvault-snapshot.js → vault-snapshot.js} +61 -61
- package/dist/node/vault-snapshot.js.map +1 -0
- package/dist/node/{gitvault-writer-state.d.ts → vault-writer-state.d.ts} +8 -8
- package/dist/node/vault-writer-state.d.ts.map +1 -0
- package/dist/node/{gitvault-writer-state.js → vault-writer-state.js} +15 -15
- package/dist/node/vault-writer-state.js.map +1 -0
- package/dist/node/workflow-output.js +4 -4
- package/dist/node/workflow-output.js.map +1 -1
- package/dist/scoped.d.ts +8 -8
- package/dist/scoped.d.ts.map +1 -1
- package/dist/scoped.js +3 -3
- package/dist/scoped.js.map +1 -1
- package/package.json +1 -1
- package/dist/namespaces/gitvault.crypto.d.ts.map +0 -1
- package/dist/namespaces/gitvault.crypto.js.map +0 -1
- package/dist/namespaces/gitvault.d.ts.map +0 -1
- package/dist/namespaces/gitvault.js.map +0 -1
- package/dist/namespaces/gitvault.types.d.ts.map +0 -1
- package/dist/namespaces/gitvault.types.js.map +0 -1
- package/dist/node/gitvault-address.d.ts.map +0 -1
- package/dist/node/gitvault-address.js.map +0 -1
- package/dist/node/gitvault-apply.d.ts.map +0 -1
- package/dist/node/gitvault-apply.js.map +0 -1
- package/dist/node/gitvault-byo-config.d.ts +0 -29
- package/dist/node/gitvault-byo-config.d.ts.map +0 -1
- package/dist/node/gitvault-byo-config.js.map +0 -1
- package/dist/node/gitvault-byo-probe.d.ts +0 -20
- package/dist/node/gitvault-byo-probe.d.ts.map +0 -1
- package/dist/node/gitvault-byo-probe.js +0 -57
- package/dist/node/gitvault-byo-probe.js.map +0 -1
- package/dist/node/gitvault-creation-journal.d.ts.map +0 -1
- package/dist/node/gitvault-creation-journal.js.map +0 -1
- package/dist/node/gitvault-degraded-read.d.ts.map +0 -1
- package/dist/node/gitvault-degraded-read.js.map +0 -1
- package/dist/node/gitvault-deploy.d.ts.map +0 -1
- package/dist/node/gitvault-deploy.js.map +0 -1
- package/dist/node/gitvault-edge-fetch.d.ts.map +0 -1
- package/dist/node/gitvault-edge-fetch.js.map +0 -1
- package/dist/node/gitvault-handoff.d.ts.map +0 -1
- package/dist/node/gitvault-handoff.js.map +0 -1
- package/dist/node/gitvault-keystore.d.ts.map +0 -1
- package/dist/node/gitvault-keystore.js.map +0 -1
- package/dist/node/gitvault-member-bundle.d.ts.map +0 -1
- package/dist/node/gitvault-member-bundle.js.map +0 -1
- package/dist/node/gitvault-mirror-backend.d.ts.map +0 -1
- package/dist/node/gitvault-mirror-backend.js.map +0 -1
- package/dist/node/gitvault-mirror-config.d.ts.map +0 -1
- package/dist/node/gitvault-mirror-config.js.map +0 -1
- package/dist/node/gitvault-mirror.d.ts.map +0 -1
- package/dist/node/gitvault-mirror.js.map +0 -1
- package/dist/node/gitvault-native-crypto.d.ts.map +0 -1
- package/dist/node/gitvault-native-crypto.js.map +0 -1
- package/dist/node/gitvault-open-or-create.d.ts.map +0 -1
- package/dist/node/gitvault-open-or-create.js.map +0 -1
- package/dist/node/gitvault-prewarm.d.ts.map +0 -1
- package/dist/node/gitvault-prewarm.js.map +0 -1
- package/dist/node/gitvault-profile-scan.d.ts.map +0 -1
- package/dist/node/gitvault-profile-scan.js.map +0 -1
- package/dist/node/gitvault-prune.d.ts.map +0 -1
- package/dist/node/gitvault-prune.js.map +0 -1
- package/dist/node/gitvault-publication.d.ts.map +0 -1
- package/dist/node/gitvault-publication.js.map +0 -1
- package/dist/node/gitvault-push-to-create.d.ts.map +0 -1
- package/dist/node/gitvault-push-to-create.js.map +0 -1
- package/dist/node/gitvault-recover.d.ts.map +0 -1
- package/dist/node/gitvault-recover.js.map +0 -1
- package/dist/node/gitvault-restore.d.ts.map +0 -1
- package/dist/node/gitvault-restore.js.map +0 -1
- package/dist/node/gitvault-snapshot.d.ts.map +0 -1
- package/dist/node/gitvault-snapshot.js.map +0 -1
- package/dist/node/gitvault-writer-state.d.ts.map +0 -1
- package/dist/node/gitvault-writer-state.js.map +0 -1
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* vault — publication (protocol rev 41 §6 + §4.4–4.7 + §5A client side;
|
|
3
3
|
* task 5.4).
|
|
4
4
|
*
|
|
5
5
|
* What lives here:
|
|
@@ -13,12 +13,12 @@
|
|
|
13
13
|
* next_cursor coupling, strictly-above-anchor, gapless across pages,
|
|
14
14
|
* truthful total), chain linkage (`CHAIN_BROKEN`), and the transition
|
|
15
15
|
* fail-closed rule (`UPGRADE_REQUIRED`);
|
|
16
|
-
* - {@link
|
|
16
|
+
* - {@link VaultTransport} — the control-plane + bucket operations the
|
|
17
17
|
* vault needs (extends task 5.3's creation transport) — and
|
|
18
|
-
* {@link
|
|
18
|
+
* {@link createVaultHttpTransport}, the `fetch`-backed implementation
|
|
19
19
|
* over the SDK kernel (upload sessions → presigned PUT with
|
|
20
20
|
* `If-None-Match: *` → finalize);
|
|
21
|
-
* - {@link
|
|
21
|
+
* - {@link Vault} — discover/verify to newest with the RESUMABLE
|
|
22
22
|
* verification budget, materialize (decrypt ref_state + retention_roots →
|
|
23
23
|
* the materialized pin), push (pack_set or a checkpoint-bearing head when
|
|
24
24
|
* the delta exceeds the 64-receipt budget, upload with receipt-compare,
|
|
@@ -34,27 +34,27 @@
|
|
|
34
34
|
* transition is `UPGRADE_REQUIRED` (read-only past it, no publish).
|
|
35
35
|
*/
|
|
36
36
|
import type { Client } from "../kernel.js";
|
|
37
|
-
import { type
|
|
38
|
-
import type {
|
|
39
|
-
import { type
|
|
40
|
-
import type {
|
|
41
|
-
import type {
|
|
42
|
-
import {
|
|
43
|
-
import type {
|
|
44
|
-
export declare const
|
|
45
|
-
export declare const
|
|
46
|
-
export declare const
|
|
47
|
-
export declare const
|
|
48
|
-
export declare const
|
|
49
|
-
export declare const
|
|
50
|
-
export declare const
|
|
51
|
-
export declare const
|
|
52
|
-
export declare const
|
|
53
|
-
export declare const
|
|
54
|
-
export declare const
|
|
55
|
-
export declare const
|
|
37
|
+
import { type VaultMirrorBackend } from "./vault-mirror-backend.js";
|
|
38
|
+
import type { VaultMirrorCredential, VaultMirrorDestination } from "./vault-mirror-config.js";
|
|
39
|
+
import { type VaultCheckpointStaleness } from "../namespaces/repos.js";
|
|
40
|
+
import type { VaultActivationToken, VaultCaptureBinding, VaultCaptureReceipt, VaultCheckpointBlock, VaultCheckpointClaimSet, VaultCheckpointManifest, VaultDigestLabel, VaultHead, VaultHeadTarget, VaultHeadsListingPage, VaultHeadsListingRequest, VaultOpenReceipt, VaultRecipientConfirmationReceipt, VaultRefState, VaultRefTransaction, VaultRefUpdate, VaultRepairDescriptor, VaultRetentionCutoff, VaultRetentionCutoffReceipt, VaultRetentionRoot, VaultRetentionRoots, VaultRetentionRootsReceipt, VaultRotateEpochPayload, VaultRotationAttemptDescriptor, VaultRotationReason, VaultGenesis } from "../namespaces/vault.types.js";
|
|
41
|
+
import type { VaultCreationTransport } from "./vault-creation-journal.js";
|
|
42
|
+
import { VaultKeystore, type VaultRepoFile } from "./vault-keystore.js";
|
|
43
|
+
import type { VaultPruneIntentRecord } from "./vault-prune.js";
|
|
44
|
+
export declare const VAULT_MAX_CANONICAL_REFS = 10000;
|
|
45
|
+
export declare const VAULT_MAX_REF_UPDATES_PER_TRANSACTION = 1000;
|
|
46
|
+
export declare const VAULT_MAX_RETENTION_ROOT_ENTRIES = 50000;
|
|
47
|
+
export declare const VAULT_MAX_REPAIR_ADDED_ROOTS = 10000;
|
|
48
|
+
export declare const VAULT_MAX_WAL_RECEIPTS_PER_HEAD = 64;
|
|
49
|
+
export declare const VAULT_MAX_CHECKPOINT_PACKS = 4096;
|
|
50
|
+
export declare const VAULT_MAX_CHECKPOINT_TOTAL_STORED_BYTES = 858993459200n;
|
|
51
|
+
export declare const VAULT_MULTI_OBJECT_PACK_TARGET_BYTES = 201326592;
|
|
52
|
+
export declare const VAULT_MAX_REF_STATE_OBJECT_BYTES = 33554432;
|
|
53
|
+
export declare const VAULT_MAX_HEADS_PER_LISTING_PAGE = 1000;
|
|
54
|
+
export declare const VAULT_VERIFICATION_BUDGET_HEADS = 100000;
|
|
55
|
+
export declare const VAULT_RETENTION_MIN_DAYS = 90;
|
|
56
56
|
/** Default admission-conflict retries before the push gives up (each retry re-verifies + re-applies to the winner). */
|
|
57
|
-
export declare const
|
|
57
|
+
export declare const VAULT_PUSH_CONFLICT_RETRIES = 5;
|
|
58
58
|
/**
|
|
59
59
|
* `run402@<version>/<entrypoint>` — the audit-provenance string named on
|
|
60
60
|
* `self_open_attestation.reader_entrypoint` (D209) and
|
|
@@ -63,29 +63,29 @@ export declare const GITVAULT_PUSH_CONFLICT_RETRIES = 5;
|
|
|
63
63
|
* authorization input; no wire grammar is promised for it (protocol-v0.md
|
|
64
64
|
* §4.14, `rotate_epoch_payload.json`'s own field `$comment`).
|
|
65
65
|
*/
|
|
66
|
-
export declare function
|
|
66
|
+
export declare function vaultReaderEntrypoint(entrypoint: string): string;
|
|
67
67
|
export declare function generationToBigInt(generation: string): bigint;
|
|
68
68
|
export declare function bigIntToGeneration(value: bigint): string;
|
|
69
69
|
export declare function nextGeneration(generation: string): string;
|
|
70
|
-
export type
|
|
70
|
+
export type VaultRefMap = Record<string, string>;
|
|
71
71
|
/** A tip that left the canonical map in this transaction — it enters `retention_roots` in the same generation. */
|
|
72
|
-
export interface
|
|
72
|
+
export interface VaultDroppedTip {
|
|
73
73
|
ref: string;
|
|
74
74
|
oid: string;
|
|
75
75
|
reason: "deleted" | "force_displaced";
|
|
76
76
|
}
|
|
77
|
-
export interface
|
|
78
|
-
refs:
|
|
79
|
-
dropped:
|
|
77
|
+
export interface VaultRefTransactionEvaluation {
|
|
78
|
+
refs: VaultRefMap;
|
|
79
|
+
dropped: VaultDroppedTip[];
|
|
80
80
|
}
|
|
81
|
-
export interface
|
|
81
|
+
export interface VaultEvaluateRefTransactionOptions {
|
|
82
82
|
/** Ancestry oracle: true iff `ancestor` is reachable from `descendant`. */
|
|
83
83
|
isAncestor: (ancestor: string, descendant: string) => Promise<boolean> | boolean;
|
|
84
84
|
/** `refuse` (default — user pushes): any `refs/run402/*` update is refused; `allow`: the protocol's own deploy-ref move. */
|
|
85
85
|
protocol_refs?: "refuse" | "allow";
|
|
86
86
|
}
|
|
87
87
|
/** One failing update of a refused transaction (never a silent revert). */
|
|
88
|
-
export interface
|
|
88
|
+
export interface VaultRefUpdateFailure {
|
|
89
89
|
ref: string;
|
|
90
90
|
reason: "expected_old_mismatch" | "non_fast_forward" | "tag_immutable" | "delete_requires_expected_old" | "noop";
|
|
91
91
|
expected_old_oid: string | null;
|
|
@@ -97,16 +97,16 @@ export interface GitvaultRefUpdateFailure {
|
|
|
97
97
|
* then per-update semantics collected into ONE `REF_EXPECTED_OLD_MISMATCH`
|
|
98
98
|
* (every failing update listed), then the resulting-state cardinality.
|
|
99
99
|
*/
|
|
100
|
-
export declare function evaluateRefTransaction(current:
|
|
100
|
+
export declare function evaluateRefTransaction(current: VaultRefMap, transaction: VaultRefTransaction, options: VaultEvaluateRefTransactionOptions): Promise<VaultRefTransactionEvaluation>;
|
|
101
101
|
/** §6.5 bound: ≤ 10 000 canonical refs and the serialized map ≤ 32 MiB. */
|
|
102
|
-
export declare function assertRefMapCardinality(refs:
|
|
102
|
+
export declare function assertRefMapCardinality(refs: VaultRefMap): void;
|
|
103
103
|
/** The §4.4 deploy-ref move: force-with-lease `refs/run402/deploys/latest` → `oid` (creation when absent). */
|
|
104
|
-
export declare function deployRefTransaction(current:
|
|
104
|
+
export declare function deployRefTransaction(current: VaultRefMap, oid: string): VaultRefTransaction;
|
|
105
105
|
/** `effective_admitted_at = max(prepared_at, storage creation time of the winning admission record)` (§4.10). */
|
|
106
106
|
export declare function effectiveAdmittedAt(preparedAt: string, recordStorageCreatedAt: string): string;
|
|
107
107
|
/** A root may be removed iff `effective_admitted_at + 90 days < cutoff_at` (STRICT; §4.5a). */
|
|
108
108
|
export declare function isRootEligibleForRemoval(effectiveAdmittedAtIso: string, cutoffAtIso: string, retentionDays?: number): boolean;
|
|
109
|
-
export interface
|
|
109
|
+
export interface VaultEvolveRootsOptions {
|
|
110
110
|
/** The generation being built (`g+1`) — stamped as `dropped_at_generation` on new/renewed keys. */
|
|
111
111
|
generation: string;
|
|
112
112
|
/** Tips dropped or force-displaced by this generation's transaction. */
|
|
@@ -125,12 +125,12 @@ export interface GitvaultEvolveRootsOptions {
|
|
|
125
125
|
effectiveAdmittedAt: (droppedAtGeneration: string) => string | null;
|
|
126
126
|
};
|
|
127
127
|
}
|
|
128
|
-
export declare function compareRoots(a:
|
|
128
|
+
export declare function compareRoots(a: VaultRetentionRoot, b: VaultRetentionRoot): number;
|
|
129
129
|
/** roots(g+1) = roots(g) ∪ dropped (RENEWING an existing `(ref, oid)` key) ∖ {expired, only at a checkpoint with a ticket}. */
|
|
130
|
-
export declare function evolveRetentionRoots(previous:
|
|
130
|
+
export declare function evolveRetentionRoots(previous: VaultRetentionRoot[], options: VaultEvolveRootsOptions): VaultRetentionRoot[];
|
|
131
131
|
/**
|
|
132
132
|
* The client-local, protocol-owned namespace (design D4). Distinct from the
|
|
133
|
-
* VAULT-side `refs/run402/*` (e.g. `
|
|
133
|
+
* VAULT-side `refs/run402/*` (e.g. `VAULT_DEPLOY_REF`) that rides the wire
|
|
134
134
|
* as part of `ref_state` — `refs/r402/*` never rides the wire at all; it is
|
|
135
135
|
* written directly into the local `.git` by the materializer and reconciled
|
|
136
136
|
* on every later fetch/fsck. A push naming any ref under it is refused by the
|
|
@@ -138,14 +138,14 @@ export declare function evolveRetentionRoots(previous: GitvaultRetentionRoot[],
|
|
|
138
138
|
* `git-remote-run402.mjs`'s `partitionProtectedRefPushes`) — this constant is
|
|
139
139
|
* the ONE place the namespace string is spelled, shared by both sides.
|
|
140
140
|
*/
|
|
141
|
-
export declare const
|
|
141
|
+
export declare const VAULT_R402_REF_NAMESPACE = "refs/r402/";
|
|
142
142
|
/** Where a retained (branch-unreachable) deploy-capture tip gets its local ref (design D1/D2). */
|
|
143
|
-
export declare const
|
|
143
|
+
export declare const VAULT_RETAIN_REF_PREFIX = "refs/r402/retain/";
|
|
144
144
|
/**
|
|
145
145
|
* D1's ref-identity choice, recorded here because the design doc's own
|
|
146
|
-
* assumption did not hold: `
|
|
146
|
+
* assumption did not hold: `VaultRetentionRoot` carries no per-capture
|
|
147
147
|
* stable id (only `{ref, oid, dropped_at_generation}`) — the capture id that
|
|
148
|
-
* DOES exist (`
|
|
148
|
+
* DOES exist (`VaultHead.capture_binding.capture_id`) lives on the head
|
|
149
149
|
* that INTRODUCED a tip onto a canonical ref, not on the retention-root entry
|
|
150
150
|
* recording its later displacement, and correlating the two would require
|
|
151
151
|
* walking the chain further back than materialization already reads (D2
|
|
@@ -154,8 +154,8 @@ export declare const GITVAULT_RETAIN_REF_PREFIX = "refs/r402/retain/";
|
|
|
154
154
|
* ever changes for the same history), and needs no correlation at all — the
|
|
155
155
|
* ref name IS the tip's own identity.
|
|
156
156
|
*/
|
|
157
|
-
export declare function
|
|
158
|
-
export interface
|
|
157
|
+
export declare function vaultRetainedRefName(oid: string): string;
|
|
158
|
+
export interface VaultRetainedRefsReconcileResult {
|
|
159
159
|
/** `refs/r402/retain/<oid>` refs created or moved this call. */
|
|
160
160
|
written: string[];
|
|
161
161
|
/** `refs/r402/retain/*` refs removed this call — a root the vault no longer retains. */
|
|
@@ -194,14 +194,14 @@ export interface GitvaultRetainedRefsReconcileResult {
|
|
|
194
194
|
* never a warning.
|
|
195
195
|
*/
|
|
196
196
|
/**
|
|
197
|
-
* Name prefix of the scratch directory {@link
|
|
197
|
+
* Name prefix of the scratch directory {@link Vault.buildPacks}
|
|
198
198
|
* allocates INSIDE the repository's git common dir. Dotted and clearly named
|
|
199
199
|
* so it can never be mistaken for `objects/`, `refs/`, or a pack directory.
|
|
200
200
|
*/
|
|
201
|
-
export declare const
|
|
201
|
+
export declare const VAULT_PACK_SCRATCH_PREFIX = ".run402-vault-packs-";
|
|
202
202
|
/**
|
|
203
203
|
* Allocate the pack-objects scratch directory on the OBJECT STORE's own
|
|
204
|
-
* filesystem: `<git-common-dir>/.run402-
|
|
204
|
+
* filesystem: `<git-common-dir>/.run402-vault-packs-XXXXXX`, never under
|
|
205
205
|
* `os.tmpdir()`.
|
|
206
206
|
*
|
|
207
207
|
* `git pack-objects <base>` writes its temporary pack under
|
|
@@ -216,11 +216,11 @@ export declare const GITVAULT_PACK_SCRATCH_PREFIX = ".run402-gitvault-packs-";
|
|
|
216
216
|
*/
|
|
217
217
|
export declare function allocatePackScratchDir(repoDir: string): Promise<string>;
|
|
218
218
|
export declare function reconcileRetainedTipRefs(repoDir: string, state: {
|
|
219
|
-
refs:
|
|
220
|
-
roots: readonly
|
|
221
|
-
head_target:
|
|
222
|
-
}): Promise<
|
|
223
|
-
export interface
|
|
219
|
+
refs: VaultRefMap;
|
|
220
|
+
roots: readonly VaultRetentionRoot[];
|
|
221
|
+
head_target: VaultHeadTarget;
|
|
222
|
+
}): Promise<VaultRetainedRefsReconcileResult>;
|
|
223
|
+
export interface VaultListingProgress {
|
|
224
224
|
/** The anchor (constant across the sequence). */
|
|
225
225
|
after_generation: string;
|
|
226
226
|
/** The highest generation delivered so far (== anchor before page 1). */
|
|
@@ -229,22 +229,22 @@ export interface GitvaultListingProgress {
|
|
|
229
229
|
delivered: number;
|
|
230
230
|
}
|
|
231
231
|
/** Validate a listing request before it is sent (the request schema, D186). */
|
|
232
|
-
export declare function validateHeadsListingRequest(request:
|
|
232
|
+
export declare function validateHeadsListingRequest(request: VaultHeadsListingRequest): void;
|
|
233
233
|
/**
|
|
234
234
|
* Validate one page against the request and the sequence so far. Returns the
|
|
235
235
|
* advanced progress. Refusals: anchor not echoed / wrong vault / coupling
|
|
236
|
-
* violation / retired member → `
|
|
236
|
+
* violation / retired member → `VAULT_LISTING_PAGE_INVALID`; an entry at or
|
|
237
237
|
* below the anchor → `GENERATION_REGRESSION`; a gap within or across pages →
|
|
238
238
|
* `CHAIN_BROKEN`; an untruthful final `total` → `CHAIN_BROKEN`.
|
|
239
239
|
*/
|
|
240
|
-
export declare function verifyHeadsListingPage(page:
|
|
240
|
+
export declare function verifyHeadsListingPage(page: VaultHeadsListingPage, request: VaultHeadsListingRequest, progress: VaultListingProgress, expectedRepoId?: string): VaultListingProgress;
|
|
241
241
|
/**
|
|
242
242
|
* The continuation request for `page`, or `null` when the sequence is complete.
|
|
243
243
|
* The anchor stays CONSTANT and `next_cursor` is echoed UNCHANGED — the cursor
|
|
244
244
|
* is stored and echoed, never parsed or edited (a client that re-anchors or
|
|
245
245
|
* edits a byte earns `INVALID_CURSOR` from the platform, D186).
|
|
246
246
|
*/
|
|
247
|
-
export declare function nextListingRequest(request:
|
|
247
|
+
export declare function nextListingRequest(request: VaultHeadsListingRequest, page: VaultHeadsListingPage): VaultHeadsListingRequest | null;
|
|
248
248
|
/**
|
|
249
249
|
* §6.4: the vault's newest generation may never fall BELOW the authenticated
|
|
250
250
|
* pin. A listing (or a storage read) that says otherwise is a rollback, not a
|
|
@@ -252,25 +252,25 @@ export declare function nextListingRequest(request: GitvaultHeadsListingRequest,
|
|
|
252
252
|
*/
|
|
253
253
|
export declare function checkGenerationRegression(listedNewestGeneration: string, pinnedGeneration: string): void;
|
|
254
254
|
/** The parameters a maintenance open requests, and that the C1 record must echo. */
|
|
255
|
-
export interface
|
|
255
|
+
export interface VaultOpenBindingRecord {
|
|
256
256
|
base_head_sha256: string;
|
|
257
257
|
prior_checkpoint_claim_set_sha256: string | null;
|
|
258
258
|
r2_cap_size_bytes: string;
|
|
259
259
|
}
|
|
260
260
|
/** `SHA-256("r402s/v0/open-binding" ‖ lp(client_open_id) ‖ lp(base_head) ‖ lp_opt(prior) ‖ lp(cap))`. */
|
|
261
|
-
export declare function openBindingDigest(clientOpenId: string, record:
|
|
261
|
+
export declare function openBindingDigest(clientOpenId: string, record: VaultOpenBindingRecord): string;
|
|
262
262
|
/**
|
|
263
263
|
* Recompute the binding from the record's OWN fields and compare it bytewise
|
|
264
264
|
* with the signed issuance digest. The error registry has no dedicated code for
|
|
265
265
|
* the fence inequality (D145), so the client surfaces
|
|
266
|
-
* `
|
|
266
|
+
* `VAULT_OPEN_BINDING_MISMATCH`; a same-`client_open_id` retry that carries a
|
|
267
267
|
* DIFFERENT binding is the registry's `CLIENT_OPEN_ID_CONFLICT`.
|
|
268
268
|
*/
|
|
269
|
-
export declare function checkOpenBinding(clientOpenId: string, record:
|
|
269
|
+
export declare function checkOpenBinding(clientOpenId: string, record: VaultOpenBindingRecord, issuanceOpenBindingSha256: string, options?: {
|
|
270
270
|
retry?: boolean;
|
|
271
271
|
}): void;
|
|
272
|
-
export interface
|
|
273
|
-
head:
|
|
272
|
+
export interface VaultChainLinkInput {
|
|
273
|
+
head: VaultHead;
|
|
274
274
|
stored_bytes: Uint8Array;
|
|
275
275
|
/** The listing's hash for this generation. */
|
|
276
276
|
listed_sha256: string;
|
|
@@ -281,7 +281,7 @@ export interface GitvaultChainLinkInput {
|
|
|
281
281
|
writer_public_key: Uint8Array | string;
|
|
282
282
|
writer_key_id: string;
|
|
283
283
|
/**
|
|
284
|
-
* The predecessor's own `epoch` (D194, rev 42) — `
|
|
284
|
+
* The predecessor's own `epoch` (D194, rev 42) — `VAULT_GENESIS_EPOCH`
|
|
285
285
|
* for generation 1's predecessor (genesis). Drives the D193 epoch-
|
|
286
286
|
* continuity check below; pure and keyless (no envelope is ever opened
|
|
287
287
|
* here — only the head's own `epoch` FIELD is checked).
|
|
@@ -289,7 +289,7 @@ export interface GitvaultChainLinkInput {
|
|
|
289
289
|
prev_epoch: string;
|
|
290
290
|
}
|
|
291
291
|
/** Verify one link: bytes hash to the listing, strict parse, generation, prev linkage, epoch pin, repo, writer signature. */
|
|
292
|
-
export declare function checkChainLink(input:
|
|
292
|
+
export declare function checkChainLink(input: VaultChainLinkInput): void;
|
|
293
293
|
/**
|
|
294
294
|
* The transition fail-closed rule: a V0 client that encounters an ADMITTED
|
|
295
295
|
* transition kind it cannot validate stops advancing — read-only at the
|
|
@@ -300,19 +300,19 @@ export declare function checkChainLink(input: GitvaultChainLinkInput): void;
|
|
|
300
300
|
* rotation is ACTIVATED") — `checkChainLink`'s own D194 epoch-continuity
|
|
301
301
|
* check already validates its structural admissibility, and
|
|
302
302
|
* {@link parseRotateEpochPayload} / the caller's own envelope-open step
|
|
303
|
-
* (`
|
|
304
|
-
* EXEMPT as of rev 47 (
|
|
303
|
+
* (`Vault.verifyToNewest`) handle it fully. `add_writer_key` is
|
|
304
|
+
* EXEMPT as of rev 47 (vault-multi-writer) the same way — {@link
|
|
305
305
|
* parseAddWriterKeyPayload} + `validateAddWriterKeyPayload`
|
|
306
|
-
* (`
|
|
306
|
+
* (`vault-writer-state.js`) handle it fully, INSIDE `verifyToNewest`'s
|
|
307
307
|
* own loop, BEFORE this function ever runs on that head (so a transition
|
|
308
308
|
* that fails writer validation never reaches here at all — this function
|
|
309
309
|
* only ever sees ones that already passed). The other two kinds
|
|
310
310
|
* (`add_envelope`, `transfer_binding`) remain genuinely unactivated and stay
|
|
311
311
|
* fail-closed exactly as before.
|
|
312
312
|
*/
|
|
313
|
-
export declare function assertNoTransition(head:
|
|
313
|
+
export declare function assertNoTransition(head: VaultHead): void;
|
|
314
314
|
/** One object to upload — identity fixed BEFORE the PUT; the receipt is compared against it. */
|
|
315
|
-
export interface
|
|
315
|
+
export interface VaultUploadObject {
|
|
316
316
|
/**
|
|
317
317
|
* Storage path relative to the vault root (§3). CLIENT-LOCAL addressing only:
|
|
318
318
|
* the control plane derives the bucket key from `object_kind` + the ledger
|
|
@@ -330,7 +330,7 @@ export interface GitvaultUploadObject {
|
|
|
330
330
|
/** `wal_pack` only — §4.1: the ONLY receipt kind carrying `base_generation`. */
|
|
331
331
|
base_generation?: string;
|
|
332
332
|
}
|
|
333
|
-
export interface
|
|
333
|
+
export interface VaultUploadReceipt {
|
|
334
334
|
path: string;
|
|
335
335
|
object_id: string | null;
|
|
336
336
|
sha256: string;
|
|
@@ -341,10 +341,10 @@ export interface GitvaultUploadReceipt {
|
|
|
341
341
|
* bucket path: heads and admission records have their own generation-addressed
|
|
342
342
|
* routes, and every uploadable kind is named by `object_kind` + `object_id`
|
|
343
343
|
* (or, for envelopes, `epoch` + `recipient_fingerprint`). This resolver maps
|
|
344
|
-
* the SDK's internal `
|
|
344
|
+
* the SDK's internal `vaultPaths` strings onto that identity so the rest of
|
|
345
345
|
* the vault can keep addressing objects the way §3 describes them.
|
|
346
346
|
*/
|
|
347
|
-
export type
|
|
347
|
+
export type VaultWireRef = {
|
|
348
348
|
kind: "head";
|
|
349
349
|
generation: string;
|
|
350
350
|
} | {
|
|
@@ -352,10 +352,10 @@ export type GitvaultWireRef = {
|
|
|
352
352
|
generation: string;
|
|
353
353
|
} | {
|
|
354
354
|
kind: "object";
|
|
355
|
-
read:
|
|
355
|
+
read: VaultObjectReadRequest;
|
|
356
356
|
};
|
|
357
357
|
/** One entry of a `POST …/object-reads` batch. */
|
|
358
|
-
export interface
|
|
358
|
+
export interface VaultObjectReadRequest {
|
|
359
359
|
object_kind: string;
|
|
360
360
|
object_id?: string;
|
|
361
361
|
epoch?: string;
|
|
@@ -366,17 +366,17 @@ export interface GitvaultObjectReadRequest {
|
|
|
366
366
|
pin_manifest_version?: string;
|
|
367
367
|
}
|
|
368
368
|
/** `null` for a path with no wire identity (e.g. a locally-held cutoff ticket). */
|
|
369
|
-
export declare function
|
|
369
|
+
export declare function vaultWireRefForPath(path: string): VaultWireRef | null;
|
|
370
370
|
/** The manifest entry for one upload — closed-key, exactly what the control plane validates. */
|
|
371
|
-
export declare function
|
|
371
|
+
export declare function vaultManifestEntry(object: VaultUploadObject): VaultObjectReadRequest & {
|
|
372
372
|
sha256: string;
|
|
373
373
|
size_bytes: string;
|
|
374
374
|
base_generation?: string;
|
|
375
375
|
};
|
|
376
|
-
/** Mirrors the gateway's `
|
|
377
|
-
export declare const
|
|
378
|
-
/** Mirrors the gateway's `
|
|
379
|
-
export declare const
|
|
376
|
+
/** Mirrors the gateway's `VAULT_INLINE_UPLOAD_MAX_OBJECT_BYTES` (`services/vault/upload-sessions.ts`). */
|
|
377
|
+
export declare const VAULT_INLINE_UPLOAD_MAX_OBJECT_BYTES = 262144;
|
|
378
|
+
/** Mirrors the gateway's `VAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES`. */
|
|
379
|
+
export declare const VAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES = 1048576;
|
|
380
380
|
/**
|
|
381
381
|
* The client-side mirror of the gateway's `isInlineUploadRequest` + per-object/
|
|
382
382
|
* per-request cap check: every object must fit under the PER-OBJECT cap AND
|
|
@@ -387,32 +387,32 @@ export declare const GITVAULT_INLINE_UPLOAD_MAX_REQUEST_BYTES = 1048576;
|
|
|
387
387
|
* already short-circuits before this is consulted, and `putObject` always
|
|
388
388
|
* wraps exactly one object so it never hits this branch).
|
|
389
389
|
*
|
|
390
|
-
* Takes the narrowest shape that satisfies every call site (`
|
|
390
|
+
* Takes the narrowest shape that satisfies every call site (`VaultUploadObject[]`
|
|
391
391
|
* for `uploadObjects`, a single `{bytes}`-shaped array for `putObject`) so
|
|
392
392
|
* neither caller needs to fabricate unrelated fields just to ask the
|
|
393
393
|
* question.
|
|
394
394
|
*/
|
|
395
|
-
export declare function
|
|
395
|
+
export declare function vaultInlineUploadEligible(objects: readonly {
|
|
396
396
|
bytes: Uint8Array;
|
|
397
397
|
}[]): boolean;
|
|
398
398
|
/**
|
|
399
399
|
* The stable key both sides agree on, used to pair receipts back to
|
|
400
400
|
* requests — MIRRORS the gateway's `keyEnvelopeLedgerId`/`pinManifestLedgerId`
|
|
401
|
-
* (services/
|
|
401
|
+
* (services/vault/epoch-rotation.ts) exactly; drift here breaks receipt
|
|
402
402
|
* pairing at upload finalize for a rotation-attempt envelope or a pin
|
|
403
403
|
* manifest.
|
|
404
404
|
*/
|
|
405
|
-
export declare function
|
|
406
|
-
export interface
|
|
405
|
+
export declare function vaultLedgerId(read: VaultObjectReadRequest): string;
|
|
406
|
+
export interface VaultAdmitHeadRequest {
|
|
407
407
|
repo_id: string;
|
|
408
408
|
generation: string;
|
|
409
409
|
stored_bytes: Uint8Array;
|
|
410
410
|
stored_bytes_sha256: string;
|
|
411
411
|
}
|
|
412
|
-
export type
|
|
412
|
+
export type VaultAdmitHeadResult = {
|
|
413
413
|
outcome: "admitted";
|
|
414
414
|
admission_record_sha256: string;
|
|
415
|
-
capture_receipt:
|
|
415
|
+
capture_receipt: VaultCaptureReceipt | null;
|
|
416
416
|
} | {
|
|
417
417
|
outcome: "conflict";
|
|
418
418
|
winner: {
|
|
@@ -420,9 +420,9 @@ export type GitvaultAdmitHeadResult = {
|
|
|
420
420
|
stored_bytes_sha256: string;
|
|
421
421
|
};
|
|
422
422
|
};
|
|
423
|
-
export interface
|
|
424
|
-
ticket:
|
|
425
|
-
receipt:
|
|
423
|
+
export interface VaultRetentionCutoffIssued {
|
|
424
|
+
ticket: VaultRetentionCutoff;
|
|
425
|
+
receipt: VaultRetentionCutoffReceipt;
|
|
426
426
|
}
|
|
427
427
|
/**
|
|
428
428
|
* Everything the vault needs from the control plane + bucket. Extends the
|
|
@@ -430,7 +430,7 @@ export interface GitvaultRetentionCutoffIssued {
|
|
|
430
430
|
* idempotent from the state machines' point of view.
|
|
431
431
|
*/
|
|
432
432
|
/** The `resource_binding` an upload session is charged against (§7.2 / §9.3). */
|
|
433
|
-
export type
|
|
433
|
+
export type VaultResourceBinding = {
|
|
434
434
|
kind: "ordinary_push";
|
|
435
435
|
} | {
|
|
436
436
|
kind: "maintenance_cycle";
|
|
@@ -440,7 +440,7 @@ export type GitvaultResourceBinding = {
|
|
|
440
440
|
repair_attempt_id: string;
|
|
441
441
|
};
|
|
442
442
|
/** `POST …/maintenance-leases` — the owner's compact/prune reservation (§7.2). */
|
|
443
|
-
export interface
|
|
443
|
+
export interface VaultMaintenanceLeaseRequest {
|
|
444
444
|
repo_id: string;
|
|
445
445
|
base_head_sha256: string;
|
|
446
446
|
current_checkpoint_hash?: string | null;
|
|
@@ -449,7 +449,7 @@ export interface GitvaultMaintenanceLeaseRequest {
|
|
|
449
449
|
p_before_c1_size_bytes?: string;
|
|
450
450
|
p_before_c2_size_bytes?: string;
|
|
451
451
|
}
|
|
452
|
-
export interface
|
|
452
|
+
export interface VaultMaintenanceLease {
|
|
453
453
|
maintenance_lease_id: string;
|
|
454
454
|
repo_id: string;
|
|
455
455
|
base_head_sha256: string;
|
|
@@ -461,8 +461,8 @@ export interface GitvaultMaintenanceLease {
|
|
|
461
461
|
expires_at: string | null;
|
|
462
462
|
hard_deadline_at: string | null;
|
|
463
463
|
}
|
|
464
|
-
/** `POST …/compaction-grant`'s result (
|
|
465
|
-
export interface
|
|
464
|
+
/** `POST …/compaction-grant`'s result (vault-checkpoint-cadence design D3). */
|
|
465
|
+
export interface VaultCompactionGrant {
|
|
466
466
|
/**
|
|
467
467
|
* The vault's server-measured `source_bytes` at grant time, capped — never
|
|
468
468
|
* client-declared. NOTE the byte fields arrive as STRINGS on the wire (the
|
|
@@ -479,20 +479,20 @@ export interface GitvaultCompactionGrant {
|
|
|
479
479
|
/** `pool_limit_bytes` + this grant's `granted_bytes` — the limit the preflight arithmetic should use while this grant is active. */
|
|
480
480
|
effective_pool_limit_bytes: number | string;
|
|
481
481
|
}
|
|
482
|
-
export interface
|
|
482
|
+
export interface VaultTransport extends VaultCreationTransport {
|
|
483
483
|
/**
|
|
484
484
|
* Read N independent carrier objects (ref_state, retention_roots, WAL/
|
|
485
485
|
* checkpoint packs — anything `object-reads`-addressed, never a
|
|
486
|
-
* generation-addressed head/admission) in ONE presigned batch (
|
|
486
|
+
* generation-addressed head/admission) in ONE presigned batch (vault-
|
|
487
487
|
* client-round-trips design D2): one `object-reads` POST naming every
|
|
488
488
|
* path, then the resulting GETs issued with bounded concurrency. Order in
|
|
489
489
|
* the result array matches `paths`; a missing object is `null` at its
|
|
490
|
-
* index, the same "absent" reading {@link
|
|
490
|
+
* index, the same "absent" reading {@link VaultCreationTransport.getObject}
|
|
491
491
|
* gives for one object. Callers that need exactly one object still use
|
|
492
|
-
* {@link
|
|
492
|
+
* {@link VaultCreationTransport.getObject} — this is for the plural
|
|
493
493
|
* case only, so a single-object caller never pays a batch's overhead.
|
|
494
494
|
*
|
|
495
|
-
* `expected` (
|
|
495
|
+
* `expected` (vault-small-object-inline design D3), when supplied, is
|
|
496
496
|
* INDEX-ALIGNED with `paths`: `expected[i]`, if present, is the sha256 hex
|
|
497
497
|
* the caller will itself check `paths[i]`'s bytes against. An
|
|
498
498
|
* `object-reads`-backed implementation MAY use it to verify a
|
|
@@ -510,13 +510,13 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
510
510
|
}): Promise<Array<Uint8Array | null>>;
|
|
511
511
|
/**
|
|
512
512
|
* OPTIONAL per-object settlement over the SAME batch shape as
|
|
513
|
-
* {@link getObjects} (
|
|
513
|
+
* {@link getObjects} (vault-pipelined-restore D2): one presign POST,
|
|
514
514
|
* the same bounded-concurrency GETs — counted ops identical — but the
|
|
515
515
|
* result is one promise PER path, each settling when its own object's
|
|
516
516
|
* bytes land, so a consumer can decrypt/verify/apply object i while later
|
|
517
517
|
* objects are still downloading. Order and absence semantics match
|
|
518
518
|
* `getObjects` (index-aligned; `null` for absent), including `expected`
|
|
519
|
-
* (
|
|
519
|
+
* (vault-small-object-inline design D3 — see {@link getObjects}'s doc
|
|
520
520
|
* comment). Every returned promise is pre-marked handled, so an abandoned
|
|
521
521
|
* tail after a mid-batch failure never surfaces as an unhandled
|
|
522
522
|
* rejection. A transport without this method degrades to the
|
|
@@ -530,7 +530,7 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
530
530
|
}): Promise<Array<Promise<Uint8Array | null>>>;
|
|
531
531
|
/**
|
|
532
532
|
* Read the EXACT stored bytes of many generation-addressed heads in ONE
|
|
533
|
-
* POST (`…/head-reads`,
|
|
533
|
+
* POST (`…/head-reads`, vault-batched-head-reads).
|
|
534
534
|
*
|
|
535
535
|
* Heads are the one hot read that cannot ride {@link getObjects}: that
|
|
536
536
|
* batch is carrier-only by wire design and fails closed on a
|
|
@@ -550,14 +550,14 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
550
550
|
repo_id: string;
|
|
551
551
|
generations: string[];
|
|
552
552
|
}): Promise<Uint8Array[] | null>;
|
|
553
|
-
listHeads(request:
|
|
553
|
+
listHeads(request: VaultHeadsListingRequest & {
|
|
554
554
|
repo_id: string;
|
|
555
|
-
}): Promise<
|
|
555
|
+
}): Promise<VaultHeadsListingPage>;
|
|
556
556
|
/**
|
|
557
557
|
* Session → create-only presigned PUTs (`If-None-Match: *`) → finalize;
|
|
558
558
|
* receipts in request order.
|
|
559
559
|
*
|
|
560
|
-
*
|
|
560
|
+
* vault-byo-primary-bucket task 3.2 — `byo`, when present, marks this
|
|
561
561
|
* vault as `storage_profile: "byo"` and names where the CLIENT itself
|
|
562
562
|
* writes payload-kind objects directly (never through run402's own
|
|
563
563
|
* bucket): the inline-upload fast path is skipped entirely (a BYO vault
|
|
@@ -570,36 +570,36 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
570
570
|
*/
|
|
571
571
|
uploadObjects(request: {
|
|
572
572
|
repo_id: string;
|
|
573
|
-
objects:
|
|
574
|
-
resource_binding?:
|
|
573
|
+
objects: VaultUploadObject[];
|
|
574
|
+
resource_binding?: VaultResourceBinding;
|
|
575
575
|
byo?: {
|
|
576
|
-
destination:
|
|
577
|
-
credential?:
|
|
576
|
+
destination: VaultMirrorDestination;
|
|
577
|
+
credential?: VaultMirrorCredential;
|
|
578
578
|
};
|
|
579
|
-
}): Promise<
|
|
580
|
-
admitHead(request:
|
|
579
|
+
}): Promise<VaultUploadReceipt[]>;
|
|
580
|
+
admitHead(request: VaultAdmitHeadRequest): Promise<VaultAdmitHeadResult>;
|
|
581
581
|
requestRetentionCutoff(request: {
|
|
582
582
|
repo_id: string;
|
|
583
583
|
base_head_sha256: string;
|
|
584
|
-
}): Promise<
|
|
584
|
+
}): Promise<VaultRetentionCutoffIssued>;
|
|
585
585
|
exchangeActivationToken(request: {
|
|
586
586
|
repo_id: string;
|
|
587
587
|
operation_id: string;
|
|
588
|
-
capture_receipt:
|
|
589
|
-
}): Promise<
|
|
588
|
+
capture_receipt: VaultCaptureReceipt;
|
|
589
|
+
}): Promise<VaultActivationToken>;
|
|
590
590
|
submitOverrideCompletion(request: {
|
|
591
591
|
repo_id: string;
|
|
592
592
|
operation_id: string;
|
|
593
|
-
capture_receipt:
|
|
593
|
+
capture_receipt: VaultCaptureReceipt;
|
|
594
594
|
}): Promise<{
|
|
595
595
|
cleared: boolean;
|
|
596
596
|
}>;
|
|
597
597
|
/** The vault record — policy, allocation generation, storage + maintenance state (§9.2). */
|
|
598
598
|
getVaultRecord(request: {
|
|
599
599
|
repo_id: string;
|
|
600
|
-
}): Promise<
|
|
600
|
+
}): Promise<VaultRecord>;
|
|
601
601
|
/**
|
|
602
|
-
* `GET …/state` (
|
|
602
|
+
* `GET …/state` (vault-composite-state-read design D1) — the pin-current
|
|
603
603
|
* fast path: the vault record, the newest generation, its head's exact
|
|
604
604
|
* stored bytes, and both carriers (`ref_state`/`retention_roots`) resolved
|
|
605
605
|
* to raw bytes here (inline decoded, or fetched from the presigned URL —
|
|
@@ -608,10 +608,10 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
608
608
|
* for a freshly allocated vault with no admitted generation yet (mirrors
|
|
609
609
|
* `newest_generation: null`); a carrier can independently be `null` when
|
|
610
610
|
* its stored bytes are absent (the same "absent" reading {@link
|
|
611
|
-
*
|
|
611
|
+
* VaultCreationTransport.getObject} gives for one object — the caller
|
|
612
612
|
* treats it identically, never a route-level distinction).
|
|
613
613
|
*
|
|
614
|
-
* {@link
|
|
614
|
+
* {@link Vault} verifies every field here EXACTLY as it does
|
|
615
615
|
* walking the paginated listing — chain link from the caller's own pin,
|
|
616
616
|
* carrier hashes against the head's own embedded receipts, and the writer
|
|
617
617
|
* signature. This route bundles bytes; it never becomes the verifier. A
|
|
@@ -619,7 +619,7 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
619
619
|
* `carriers` and falls back to {@link listHeads} — that decision lives in
|
|
620
620
|
* the vault, never here.
|
|
621
621
|
*
|
|
622
|
-
* `since` (
|
|
622
|
+
* `since` (vault-delta-fetch): the caller's materialized generation.
|
|
623
623
|
* A gateway that recognizes it MAY answer with a bounded `delta`
|
|
624
624
|
* (intermediate heads + their WAL packs, inline under caps) — and MAY
|
|
625
625
|
* ignore it entirely (older gateway, disqualified span); absence of
|
|
@@ -627,14 +627,14 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
627
627
|
* other stored byte: consumers hash-check before use, and a failed check
|
|
628
628
|
* is a plain miss that the ordinary reads absorb.
|
|
629
629
|
*
|
|
630
|
-
* `restore` (
|
|
630
|
+
* `restore` (vault-restore-recipe design D2), ORTHOGONAL to `since` —
|
|
631
631
|
* declares restore intent. A gateway that recognizes it AND can locate a
|
|
632
632
|
* checkpoint boundary within its own bound MAY answer with `restore_plan`
|
|
633
633
|
* (the heads from that boundary to newest, the boundary checkpoint's
|
|
634
634
|
* claim set + manifest, and every pack the span references) — and MAY
|
|
635
635
|
* ignore it entirely (older gateway, no locatable boundary, a transition
|
|
636
636
|
* inside the span); absence of `restore_plan` is never an error. Plan
|
|
637
|
-
* bytes are UNTRUSTED exactly like `delta`'s: {@link
|
|
637
|
+
* bytes are UNTRUSTED exactly like `delta`'s: {@link Vault}
|
|
638
638
|
* re-derives the full backward chain-link, claim-set signature,
|
|
639
639
|
* cross-equality, per-pack receipt-hash, and AEAD-open obligations before
|
|
640
640
|
* using anything here, and falls back to the ordinary backward walk on
|
|
@@ -644,14 +644,14 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
644
644
|
repo_id: string;
|
|
645
645
|
since?: string;
|
|
646
646
|
restore?: boolean;
|
|
647
|
-
}): Promise<
|
|
647
|
+
}): Promise<VaultState>;
|
|
648
648
|
/** Resolve a project's vault without local state (the cold-restart entry point). */
|
|
649
649
|
findVaultByProject(request: {
|
|
650
650
|
project_id: string;
|
|
651
|
-
}): Promise<
|
|
651
|
+
}): Promise<VaultRecord>;
|
|
652
652
|
/**
|
|
653
653
|
* Resolve a vault by its address-form `org-slug/name` (repo-first-onramp
|
|
654
|
-
* task 4.3, design D6) — `GET /
|
|
654
|
+
* task 4.3, design D6) — `GET /vaults/v1?repo=<org-slug>/<name>`.
|
|
655
655
|
* `RESOURCE_NOT_FOUND` for no such org OR no such name within it (the two
|
|
656
656
|
* collapse deliberately, so slug-namespace probing learns nothing extra);
|
|
657
657
|
* `SLUG_RELEASED` (with `successor_slug`/`released_at`/`cooldown_until` on
|
|
@@ -661,8 +661,8 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
661
661
|
findVaultByRepo(request: {
|
|
662
662
|
org_slug: string;
|
|
663
663
|
repo_name: string;
|
|
664
|
-
}): Promise<
|
|
665
|
-
acquireMaintenanceLease(request:
|
|
664
|
+
}): Promise<VaultRecord>;
|
|
665
|
+
acquireMaintenanceLease(request: VaultMaintenanceLeaseRequest): Promise<VaultMaintenanceLease>;
|
|
666
666
|
heartbeatMaintenanceLease(request: {
|
|
667
667
|
repo_id: string;
|
|
668
668
|
maintenance_lease_id: string;
|
|
@@ -680,13 +680,13 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
680
680
|
status: string;
|
|
681
681
|
}>;
|
|
682
682
|
/**
|
|
683
|
-
* `POST …/compaction-grant` (
|
|
683
|
+
* `POST …/compaction-grant` (vault-checkpoint-cadence design D3) — a
|
|
684
684
|
* short-lived, TTL'd, at-most-one-per-project headroom grant that raises
|
|
685
685
|
* the org's EFFECTIVE pooled storage limit by at most this vault's
|
|
686
686
|
* server-measured `source_bytes`, so compaction's own transient ~2x
|
|
687
687
|
* overshoot (the new checkpoint coexisting with the not-yet-pruned
|
|
688
688
|
* history) can land without the routine manual override
|
|
689
|
-
* (`--force-headroom`). Rejects `
|
|
689
|
+
* (`--force-headroom`). Rejects `VAULT_COMPACTION_GRANT_ACTIVE` (409)
|
|
690
690
|
* when this project already holds an active grant — the caller reads
|
|
691
691
|
* that as "another compaction is already in flight for this vault" and
|
|
692
692
|
* skips its own cycle rather than racing it. An older gateway 404s/
|
|
@@ -695,7 +695,7 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
695
695
|
*/
|
|
696
696
|
openCompactionGrant(request: {
|
|
697
697
|
repo_id: string;
|
|
698
|
-
}): Promise<
|
|
698
|
+
}): Promise<VaultCompactionGrant>;
|
|
699
699
|
/**
|
|
700
700
|
* `DELETE …/compaction-grant` — idempotent; `{closed: false}` when
|
|
701
701
|
* nothing was active (already closed, already expired, or never
|
|
@@ -719,33 +719,33 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
719
719
|
submitPruneIntent(request: {
|
|
720
720
|
repo_id: string;
|
|
721
721
|
intent_bytes: Uint8Array;
|
|
722
|
-
}): Promise<
|
|
722
|
+
}): Promise<VaultPruneIntentRecord & {
|
|
723
723
|
stored: boolean;
|
|
724
724
|
}>;
|
|
725
725
|
/** `GET …/prune-intents/:id` — the intent's state and, once signed, its completion. */
|
|
726
726
|
getPruneIntent(request: {
|
|
727
727
|
repo_id: string;
|
|
728
728
|
prune_intent_object_id: string;
|
|
729
|
-
}): Promise<
|
|
729
|
+
}): Promise<VaultPruneIntentRecord | null>;
|
|
730
730
|
/**
|
|
731
|
-
* The org's directory of envelope-capable principals (
|
|
731
|
+
* The org's directory of envelope-capable principals (vault-human-
|
|
732
732
|
* envelopes design D7, `GET /orgs/v1/:org_id/encryption-keys`) — every
|
|
733
733
|
* active human member who has published an encryption key. Read by
|
|
734
|
-
* {@link
|
|
734
|
+
* {@link Vault.reconcileEnvelopeRecipients} to diff against a
|
|
735
735
|
* vault's current recipient set.
|
|
736
736
|
*/
|
|
737
737
|
listOrgEncryptionKeys(request: {
|
|
738
738
|
org_id: string;
|
|
739
|
-
}): Promise<
|
|
739
|
+
}): Promise<VaultOrgEncryptionKeyDirectory>;
|
|
740
740
|
/**
|
|
741
741
|
* The `ek_` fingerprints already covering this vault, at any epoch
|
|
742
|
-
* (`GET /
|
|
742
|
+
* (`GET /vaults/v1/:vault_id/envelope-recipients`, task 2.2) —
|
|
743
743
|
* fingerprints only, never envelope bytes; the recipient-only rule on
|
|
744
744
|
* envelope BYTES elsewhere is unaffected.
|
|
745
745
|
*/
|
|
746
746
|
listEnvelopeRecipients(request: {
|
|
747
747
|
repo_id: string;
|
|
748
|
-
}): Promise<
|
|
748
|
+
}): Promise<VaultEnvelopeRecipientsResponse>;
|
|
749
749
|
/**
|
|
750
750
|
* `POST …/rotation-attempts` (D195) — the FIRST write of any rotation
|
|
751
751
|
* attempt, BEFORE any `key_envelope` upload for it. `descriptor` is the
|
|
@@ -755,10 +755,10 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
755
755
|
*/
|
|
756
756
|
createRotationAttempt(request: {
|
|
757
757
|
repo_id: string;
|
|
758
|
-
descriptor:
|
|
758
|
+
descriptor: VaultRotationAttemptDescriptor;
|
|
759
759
|
}): Promise<{
|
|
760
760
|
rotation_id: string;
|
|
761
|
-
descriptor:
|
|
761
|
+
descriptor: VaultRotationAttemptDescriptor;
|
|
762
762
|
deduplicated: boolean;
|
|
763
763
|
}>;
|
|
764
764
|
/** `POST …/recipients/:principal_id/confirm` (D197) — first-seen pin confirmation; owner + step-up. */
|
|
@@ -766,14 +766,14 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
766
766
|
repo_id: string;
|
|
767
767
|
principal_id: string;
|
|
768
768
|
new_fingerprint: string;
|
|
769
|
-
}): Promise<
|
|
769
|
+
}): Promise<VaultRecipientConfirmationReceipt>;
|
|
770
770
|
/** `POST …/recipients/:principal_id/repin` (D197) — re-pin ceremony; owner + step-up. */
|
|
771
771
|
repinRecipient(request: {
|
|
772
772
|
repo_id: string;
|
|
773
773
|
principal_id: string;
|
|
774
774
|
old_ek_fingerprint: string;
|
|
775
775
|
new_fingerprint: string;
|
|
776
|
-
}): Promise<
|
|
776
|
+
}): Promise<VaultRecipientConfirmationReceipt>;
|
|
777
777
|
/** `POST …/recipients/:principal_id/key-revocation` (D199) — declares `reason:"recipient_key_revoked"` admissible; owner + step-up. Returns the D194 counters this rotation must be fenced against — the ONE reason value with a client-visible counter read. */
|
|
778
778
|
declareRecipientKeyRevoked(request: {
|
|
779
779
|
repo_id: string;
|
|
@@ -802,7 +802,7 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
802
802
|
* of the envelope this identity actually opened. Self-match only: the
|
|
803
803
|
* gateway requires `principal_id` to equal the AUTHENTICATED caller,
|
|
804
804
|
* never overridable — a mismatch is the ordinary 403
|
|
805
|
-
* `
|
|
805
|
+
* `VAULT_ACCESS_DENIED`, not a `proof-of-open`-specific error.
|
|
806
806
|
* Idempotent on `(repo_id, principal_id, ek_fingerprint,
|
|
807
807
|
* decryptable_to_generation)`: `deduplicated: true` means the gateway
|
|
808
808
|
* returned the tuple's EXISTING receipt (HTTP `200`) rather than minting
|
|
@@ -817,25 +817,25 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
|
|
|
817
817
|
decryptable_to_generation: string;
|
|
818
818
|
reader_entrypoint: string;
|
|
819
819
|
}): Promise<{
|
|
820
|
-
receipt:
|
|
820
|
+
receipt: VaultOpenReceipt;
|
|
821
821
|
deduplicated: boolean;
|
|
822
822
|
}>;
|
|
823
823
|
}
|
|
824
824
|
/**
|
|
825
825
|
* One row of the org's envelope-capable-principal directory
|
|
826
|
-
* ({@link
|
|
826
|
+
* ({@link VaultTransport.listOrgEncryptionKeys}).
|
|
827
827
|
*
|
|
828
828
|
* The gateway route (`GET /orgs/v1/:org_id/encryption-keys`, `routes/org.ts`
|
|
829
829
|
* in run402-private) returns `public_key` on every row — the raw key
|
|
830
830
|
* material is what makes the directory usable for wrapping at all.
|
|
831
831
|
* The field stays OPTIONAL in this wire type the
|
|
832
|
-
* same way `desired[]` does on {@link
|
|
832
|
+
* same way `desired[]` does on {@link VaultEnvelopeRecipientsResponse}:
|
|
833
833
|
* a response is network data, and an older/rolling-deploy gateway that
|
|
834
834
|
* omits the field must degrade to a per-entry `skipped` report
|
|
835
|
-
* (`missing_public_key`) from {@link
|
|
835
|
+
* (`missing_public_key`) from {@link Vault.reconcileEnvelopeRecipients},
|
|
836
836
|
* never a hardcoded assumption or a thrown error.
|
|
837
837
|
*/
|
|
838
|
-
export interface
|
|
838
|
+
export interface VaultOrgEncryptionKeyEntry {
|
|
839
839
|
principal_id: string;
|
|
840
840
|
display_name: string | null;
|
|
841
841
|
ek_fingerprint: string;
|
|
@@ -844,7 +844,7 @@ export interface GitvaultOrgEncryptionKeyEntry {
|
|
|
844
844
|
/** Raw base64url X25519 public key. Present on every current-gateway row; tolerated as absent (per-entry `missing_public_key` skip) for wire robustness only. */
|
|
845
845
|
public_key?: string;
|
|
846
846
|
/**
|
|
847
|
-
*
|
|
847
|
+
* vault-multi-writer (rev 47) D9 — the SAME row's vault-WRITER signing
|
|
848
848
|
* half (`routes/org.ts` in run402-private, deployed alongside `public_key`
|
|
849
849
|
* D9). Raw base64url Ed25519 public key; `null` when this principal has
|
|
850
850
|
* never published a signing half (a pre-rev47 or encryption-only
|
|
@@ -855,21 +855,21 @@ export interface GitvaultOrgEncryptionKeyEntry {
|
|
|
855
855
|
signing_possession_verified_at?: string | null;
|
|
856
856
|
[key: string]: unknown;
|
|
857
857
|
}
|
|
858
|
-
/** `GET /orgs/v1/:org_id/encryption-keys` — {@link
|
|
859
|
-
export interface
|
|
858
|
+
/** `GET /orgs/v1/:org_id/encryption-keys` — {@link VaultTransport.listOrgEncryptionKeys}'s result. */
|
|
859
|
+
export interface VaultOrgEncryptionKeyDirectory {
|
|
860
860
|
org_id: string;
|
|
861
|
-
keys:
|
|
861
|
+
keys: VaultOrgEncryptionKeyEntry[];
|
|
862
862
|
}
|
|
863
863
|
/**
|
|
864
864
|
* One row of the vault's org-level, membership-driven DESIRED-recipient
|
|
865
865
|
* state. `status` is the server's own honest accounting of what membership
|
|
866
866
|
* currently wants, NOT a claim about whether access was actually revoked:
|
|
867
|
-
* `"pending_removal"` means membership removed this principal but
|
|
867
|
+
* `"pending_removal"` means membership removed this principal but vault
|
|
868
868
|
* protocol v0 has no epoch-rotation mechanism yet to un-wrap their existing
|
|
869
869
|
* `key_envelope`, so `covered: true` on a `pending_removal` row is a REAL
|
|
870
870
|
* continuing-access fact, not stale data.
|
|
871
871
|
*/
|
|
872
|
-
export interface
|
|
872
|
+
export interface VaultDesiredRecipientEntry {
|
|
873
873
|
principal_id: string;
|
|
874
874
|
display_name: string | null;
|
|
875
875
|
status: "active" | "pending_removal";
|
|
@@ -880,39 +880,39 @@ export interface GitvaultDesiredRecipientEntry {
|
|
|
880
880
|
/** `true` when `ek_fingerprint` currently has a `key_envelope` on this vault. */
|
|
881
881
|
covered: boolean;
|
|
882
882
|
}
|
|
883
|
-
/** `GET /
|
|
884
|
-
export interface
|
|
883
|
+
/** `GET /vaults/v1/:vault_id/envelope-recipients` — {@link VaultTransport.listEnvelopeRecipients}'s result. */
|
|
884
|
+
export interface VaultEnvelopeRecipientsResponse {
|
|
885
885
|
vault_id: string;
|
|
886
886
|
recipient_fingerprints: string[];
|
|
887
887
|
/**
|
|
888
888
|
* The org's desired-recipient state, cross-referenced against this
|
|
889
|
-
* vault's coverage — see {@link
|
|
889
|
+
* vault's coverage — see {@link VaultDesiredRecipientEntry}. OPTIONAL:
|
|
890
890
|
* absent (not empty) on an older gateway that predates this field —
|
|
891
891
|
* callers MUST distinguish "field absent" (older gateway, state genuinely
|
|
892
892
|
* unknown) from "field present and empty" (org has no desired recipients)
|
|
893
893
|
* rather than treating both as "no data."
|
|
894
894
|
*/
|
|
895
|
-
desired?:
|
|
895
|
+
desired?: VaultDesiredRecipientEntry[];
|
|
896
896
|
/** The desired-recipient substrate's own monotonic version, for cheap client-side diffing. Present iff `desired` is present. */
|
|
897
897
|
desired_state_version?: number;
|
|
898
898
|
/**
|
|
899
899
|
* D194's two org-level rotation counters, read (never locked) alongside
|
|
900
900
|
* `desired` so a writer can drive the writer-capable
|
|
901
901
|
* `reason:"member_removed"` rotation from the same read it partitions H
|
|
902
|
-
* from ({@link
|
|
902
|
+
* from ({@link Vault.rotateEpochForMemberRemoval}). OPTIONAL:
|
|
903
903
|
* absent on a gateway that predates them.
|
|
904
904
|
*/
|
|
905
905
|
recipient_state_version?: string;
|
|
906
906
|
recipient_revocation_version?: string;
|
|
907
907
|
}
|
|
908
|
-
/** `GET /
|
|
909
|
-
export interface
|
|
908
|
+
/** `GET /vaults/v1/:vault_id` — the shape `reads.ts:getVaultRecord` returns. */
|
|
909
|
+
export interface VaultRecord {
|
|
910
910
|
repo_id: string;
|
|
911
911
|
project_id: string;
|
|
912
912
|
org_id: string;
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
913
|
+
vault_policy: "required" | "grandfathered" | null;
|
|
914
|
+
vault_policy_version: string;
|
|
915
|
+
vault_policy_changed_at: string | null;
|
|
916
916
|
allocation_generation: string;
|
|
917
917
|
allocation_sha256: string | null;
|
|
918
918
|
newest_generation: string | null;
|
|
@@ -923,7 +923,7 @@ export interface GitvaultVaultRecord {
|
|
|
923
923
|
repair_version: string;
|
|
924
924
|
repair_fence_state: string;
|
|
925
925
|
/**
|
|
926
|
-
*
|
|
926
|
+
* vault-byo-primary-bucket task 3.1/3.5 (protocol-v0.md rev 46 §9.2,
|
|
927
927
|
* D220). Absent-or-`"managed"` is BYTE-IDENTICAL to every vault allocated
|
|
928
928
|
* before this fold. `byo_destination` is the destination's ADDRESS ONLY
|
|
929
929
|
* (never credential material) and is non-null iff `storage_profile ===
|
|
@@ -953,9 +953,9 @@ export interface GitvaultVaultRecord {
|
|
|
953
953
|
pending_repair_attempt_id: string | null;
|
|
954
954
|
};
|
|
955
955
|
/**
|
|
956
|
-
*
|
|
956
|
+
* vault-multi-writer (rev 47) task 3.7 — the writer chain state's read
|
|
957
957
|
* surface, mirrored client-side from the gateway's `VaultRecord` (see
|
|
958
|
-
* `services/
|
|
958
|
+
* `services/vault/reads.ts` in run402-private for the authoritative doc
|
|
959
959
|
* comment). `writer_set` is the on-chain-recognized set exactly as the
|
|
960
960
|
* chain itself would verify (regardless of any gateway-only block — that's
|
|
961
961
|
* `ineligible_members`). `pending_writers` is the reverse direction:
|
|
@@ -969,14 +969,14 @@ export interface GitvaultVaultRecord {
|
|
|
969
969
|
writer_set?: {
|
|
970
970
|
version: string;
|
|
971
971
|
sha256: string | null;
|
|
972
|
-
writers:
|
|
972
|
+
writers: VaultWriterSetEntry[];
|
|
973
973
|
};
|
|
974
|
-
pending_writers?:
|
|
975
|
-
ineligible_members?:
|
|
976
|
-
/** `
|
|
974
|
+
pending_writers?: VaultPendingWriter[];
|
|
975
|
+
ineligible_members?: VaultIneligibleMember[];
|
|
976
|
+
/** `vault_vaults.read_only_terminal_at IS NOT NULL` — the D228 forced sole-writer-removal terminal state: no further writer-authenticated push is admissible. Absent (never `undefined`-checked as `true`) on an older gateway — treat as `false`. */
|
|
977
977
|
read_only_terminal?: boolean;
|
|
978
978
|
/**
|
|
979
|
-
*
|
|
979
|
+
* vault-multi-writer (rev 47) D6/D227, task 5.9 — decimal-string
|
|
980
980
|
* uint64 counter, bumped by the gateway every time a membership/role/key
|
|
981
981
|
* change gateway-blocks one or more writer keys. A client building a
|
|
982
982
|
* `writer_set_update` freezes THIS value into `rotation_attempt_
|
|
@@ -994,7 +994,7 @@ export interface GitvaultVaultRecord {
|
|
|
994
994
|
/**
|
|
995
995
|
* The control plane's SIGNED allocation record for the vault (present on
|
|
996
996
|
* gateways that wrap it into the vault read; `null`/absent otherwise).
|
|
997
|
-
*
|
|
997
|
+
* vault-agent-envelopes D4: a cold open compares genesis's creator
|
|
998
998
|
* fingerprints against these — platform-attested consistency, never
|
|
999
999
|
* independent authentication (the platform serves both sides).
|
|
1000
1000
|
*/
|
|
@@ -1006,36 +1006,36 @@ export interface GitvaultVaultRecord {
|
|
|
1006
1006
|
[key: string]: unknown;
|
|
1007
1007
|
} | null;
|
|
1008
1008
|
}
|
|
1009
|
-
/** One chain-recognized active writer on {@link
|
|
1010
|
-
export interface
|
|
1009
|
+
/** One chain-recognized active writer on {@link VaultRecord.writer_set} — the on-chain shape only; `gateway_blocked_at` (gateway-only) rides {@link VaultIneligibleMember} instead. */
|
|
1010
|
+
export interface VaultWriterSetEntry {
|
|
1011
1011
|
writer_key_id: string;
|
|
1012
1012
|
principal_id: string;
|
|
1013
1013
|
authorization_kind: "writer" | "handoff";
|
|
1014
1014
|
admitted_generation: string;
|
|
1015
1015
|
admitted_head_sha256: string;
|
|
1016
1016
|
}
|
|
1017
|
-
/** An org member eligible to become a writer (active membership at role developer+, a published possession-verified signing key) who is NOT yet in {@link
|
|
1018
|
-
export interface
|
|
1017
|
+
/** An org member eligible to become a writer (active membership at role developer+, a published possession-verified signing key) who is NOT yet in {@link VaultRecord.writer_set}'s `writers` — a candidate for the "writer"-door `add_writer_key` ({@link Vault.reconcileWriterAdmissions}). */
|
|
1018
|
+
export interface VaultPendingWriter {
|
|
1019
1019
|
principal_id: string;
|
|
1020
1020
|
writer_key_id: string;
|
|
1021
1021
|
}
|
|
1022
1022
|
/** A chain-recognized active writer the gateway has flagged for removal — still active on-chain, pending the next `rotate_epoch{writer_set_update}`. */
|
|
1023
|
-
export interface
|
|
1023
|
+
export interface VaultIneligibleMember {
|
|
1024
1024
|
principal_id: string;
|
|
1025
1025
|
writer_key_id: string;
|
|
1026
1026
|
gateway_blocked_at: string | null;
|
|
1027
1027
|
reason: "membership_revoked" | "role_below_developer" | "encryption_key_revoked" | "gateway_blocked_pending_removal";
|
|
1028
1028
|
}
|
|
1029
1029
|
/**
|
|
1030
|
-
* {@link
|
|
1030
|
+
* {@link VaultTransport.getState}'s result — the SAME bytes the per-object
|
|
1031
1031
|
* routes serve, resolved to raw `Uint8Array` here (never verified here; see
|
|
1032
1032
|
* that method's own doc comment). `head`/`carriers` are `null` together for
|
|
1033
1033
|
* a freshly allocated vault (mirrors `newest_generation: null`); a `carriers`
|
|
1034
1034
|
* field can independently be `null` when that carrier's stored bytes are
|
|
1035
1035
|
* absent from the backing store.
|
|
1036
1036
|
*/
|
|
1037
|
-
export interface
|
|
1038
|
-
vault:
|
|
1037
|
+
export interface VaultState {
|
|
1038
|
+
vault: VaultRecord;
|
|
1039
1039
|
newest_generation: string | null;
|
|
1040
1040
|
head: {
|
|
1041
1041
|
stored_bytes: Uint8Array;
|
|
@@ -1045,13 +1045,13 @@ export interface GitvaultVaultState {
|
|
|
1045
1045
|
ref_state: Uint8Array | null;
|
|
1046
1046
|
retention_roots: Uint8Array | null;
|
|
1047
1047
|
} | null;
|
|
1048
|
-
/** Present only when the gateway answered a `since` request with a qualifying span (
|
|
1049
|
-
delta?:
|
|
1050
|
-
/** Present only when the caller declared `restore: true` AND the gateway located a qualifying checkpoint boundary (
|
|
1051
|
-
restore_plan?:
|
|
1048
|
+
/** Present only when the gateway answered a `since` request with a qualifying span (vault-delta-fetch); absent otherwise, including on every older gateway. */
|
|
1049
|
+
delta?: VaultStateDelta | null;
|
|
1050
|
+
/** Present only when the caller declared `restore: true` AND the gateway located a qualifying checkpoint boundary (vault-restore-recipe); absent otherwise, including on every older gateway. */
|
|
1051
|
+
restore_plan?: VaultRestorePlan | null;
|
|
1052
1052
|
}
|
|
1053
1053
|
/**
|
|
1054
|
-
* The state read's restore recipe (
|
|
1054
|
+
* The state read's restore recipe (vault-restore-recipe design D1-D5):
|
|
1055
1055
|
* the heads from the newest checkpoint boundary through the caller's own
|
|
1056
1056
|
* newest generation (ascending, boundary-first — ONE entry when the
|
|
1057
1057
|
* boundary IS the newest head), that boundary's checkpoint claim set +
|
|
@@ -1065,12 +1065,12 @@ export interface GitvaultVaultState {
|
|
|
1065
1065
|
* `url`/`edge_url` on a lying, absent, or over-cap `inline`), `null` when
|
|
1066
1066
|
* neither arm produced bytes (an absent object, a failed GET). UNTRUSTED
|
|
1067
1067
|
* THROUGHOUT: nothing here is verified by this decode — {@link
|
|
1068
|
-
*
|
|
1068
|
+
* Vault} re-derives the full chain-link/signature/cross-equality/
|
|
1069
1069
|
* receipt-hash/AEAD-open obligations before consuming anything, matching
|
|
1070
1070
|
* one for one by `(object_kind, object_id)`, and falls back to the ordinary
|
|
1071
1071
|
* backward walk byte-identically on any failure.
|
|
1072
1072
|
*/
|
|
1073
|
-
export interface
|
|
1073
|
+
export interface VaultRestorePlan {
|
|
1074
1074
|
boundary_generation: string;
|
|
1075
1075
|
heads: Array<{
|
|
1076
1076
|
generation: string;
|
|
@@ -1094,14 +1094,14 @@ export interface GitvaultVaultRestorePlan {
|
|
|
1094
1094
|
}>;
|
|
1095
1095
|
}
|
|
1096
1096
|
/**
|
|
1097
|
-
* The state read's bounded delta (
|
|
1097
|
+
* The state read's bounded delta (vault-delta-fetch): the span's heads in
|
|
1098
1098
|
* chain order plus their WAL packs' INLINE bytes. Over-cap packs arrive as
|
|
1099
1099
|
* presigned references on the wire and are DROPPED here (v1 consumes inline
|
|
1100
1100
|
* only — an uncovered pack simply rides the ordinary batched fetch, so the
|
|
1101
1101
|
* reference arm costs nothing to ignore). Untrusted throughout: every
|
|
1102
1102
|
* consumer hash-checks before use.
|
|
1103
1103
|
*/
|
|
1104
|
-
export interface
|
|
1104
|
+
export interface VaultStateDelta {
|
|
1105
1105
|
heads: Array<{
|
|
1106
1106
|
generation: string;
|
|
1107
1107
|
stored_bytes: Uint8Array;
|
|
@@ -1112,11 +1112,11 @@ export interface GitvaultVaultStateDelta {
|
|
|
1112
1112
|
bytes: Uint8Array;
|
|
1113
1113
|
}>;
|
|
1114
1114
|
}
|
|
1115
|
-
export interface
|
|
1116
|
-
/** Wire shape: every vault-scoped route is `/
|
|
1115
|
+
export interface VaultHttpTransportOptions {
|
|
1116
|
+
/** Wire shape: every vault-scoped route is `/vaults/v1/:vault_id/...`; `vault_id` is the `repo_id` unless a mapping is supplied (D185). */
|
|
1117
1117
|
vaultIdFor?: (repoId: string) => string;
|
|
1118
1118
|
/**
|
|
1119
|
-
*
|
|
1119
|
+
* vault-byo-primary-bucket: where THIS machine reads a BYO vault's
|
|
1120
1120
|
* payload from. The gateway holds no payload copy of a `storage_profile:
|
|
1121
1121
|
* "byo"` vault, so its `object-reads` entries and `GET …/state` carriers
|
|
1122
1122
|
* for the payload kinds carry `byo_key` (the object's relative key under
|
|
@@ -1125,22 +1125,22 @@ export interface GitvaultHttpTransportOptions {
|
|
|
1125
1125
|
* backend (`byo/<repo_id>.json` in the keystore — destination + credential
|
|
1126
1126
|
* NAME, never material) and reads the key from it. `null` means this
|
|
1127
1127
|
* machine has no such config, and the read fails
|
|
1128
|
-
* `
|
|
1128
|
+
* `VAULT_BYO_NOT_CONFIGURED` by name — never a silent "absent". Absent
|
|
1129
1129
|
* option: same as `null`. Managed vaults never consult it.
|
|
1130
1130
|
*/
|
|
1131
|
-
byoBackend?: (repoId: string) =>
|
|
1131
|
+
byoBackend?: (repoId: string) => VaultMirrorBackend | null;
|
|
1132
1132
|
/**
|
|
1133
|
-
*
|
|
1133
|
+
* vault-object-host-predial (design D1, task 1.2): called with the
|
|
1134
1134
|
* ORIGIN(s) (`scheme://host`) of an object-store URL this transport just
|
|
1135
1135
|
* completed a round trip against — the presigned `url`'s origin, and the
|
|
1136
1136
|
* `edge_url`'s origin too when the target carried one, regardless of
|
|
1137
1137
|
* which one actually served the bytes (both are worth a future predial;
|
|
1138
|
-
* see `
|
|
1138
|
+
* see `vault-prewarm.ts`). Fired ONLY after a completed fetch (any
|
|
1139
1139
|
* status, including 404 — a real "absent" response still proves the
|
|
1140
1140
|
* origin is reachable); NEVER fired for an `inline`-satisfied read
|
|
1141
1141
|
* (nothing was dialed) or a fetch that threw. This is the ONE place the
|
|
1142
1142
|
* transport observes origins — the caller (who holds the keystore) is
|
|
1143
|
-
* expected to persist them via `
|
|
1143
|
+
* expected to persist them via `VaultKeystore.recordObjectStoreOrigins`;
|
|
1144
1144
|
* the transport itself has no keystore and does no persistence. Called
|
|
1145
1145
|
* synchronously and never awaited — a throwing callback must never
|
|
1146
1146
|
* surface into the read it rode along with, so callers wrap their own
|
|
@@ -1149,13 +1149,13 @@ export interface GitvaultHttpTransportOptions {
|
|
|
1149
1149
|
onObjectStoreOriginObserved?: (repoId: string, origins: string[]) => void;
|
|
1150
1150
|
}
|
|
1151
1151
|
/**
|
|
1152
|
-
* Independent reads/PUTs within one
|
|
1152
|
+
* Independent reads/PUTs within one vault step run at this concurrency
|
|
1153
1153
|
* (design D2) — "browser-era origin etiquette", well within what S3/the
|
|
1154
1154
|
* gateway tolerate, and it keeps in-flight memory bounded by ~6×frame size.
|
|
1155
1155
|
* Chain-ordered steps (the head-chain walk, admission, readback) never call
|
|
1156
1156
|
* this — they stay strictly sequential.
|
|
1157
1157
|
*/
|
|
1158
|
-
export declare const
|
|
1158
|
+
export declare const VAULT_TRANSPORT_CONCURRENCY = 6;
|
|
1159
1159
|
/**
|
|
1160
1160
|
* Run `fn` over `items` with at most `limit` in flight at once, preserving
|
|
1161
1161
|
* result order regardless of completion order. A plain worker-pool: `limit`
|
|
@@ -1167,8 +1167,8 @@ export declare function mapBounded<T, R>(items: readonly T[], limit: number, fn:
|
|
|
1167
1167
|
* `If-None-Match: *` (create-only — the bucket policy demands it) and the
|
|
1168
1168
|
* FULL_OBJECT SHA-256 checksum header.
|
|
1169
1169
|
*/
|
|
1170
|
-
export declare function
|
|
1171
|
-
export declare const
|
|
1170
|
+
export declare function createVaultHttpTransport(client: Client, options?: VaultHttpTransportOptions): VaultTransport;
|
|
1171
|
+
export declare const vaultPaths: {
|
|
1172
1172
|
readonly head: (generation: string) => string;
|
|
1173
1173
|
readonly admission: (generation: string) => string;
|
|
1174
1174
|
readonly wal: (id: string) => string;
|
|
@@ -1182,7 +1182,7 @@ export declare const gitvaultPaths: {
|
|
|
1182
1182
|
readonly verifierReceipt: (id: string) => string;
|
|
1183
1183
|
/**
|
|
1184
1184
|
* `envelopes/<epoch>/<recipient_fingerprint>` — mirrors
|
|
1185
|
-
* `
|
|
1185
|
+
* `vault-creation-journal.ts`'s private `envelopePath` (the genesis
|
|
1186
1186
|
* creator's envelope); this is the same addressing for every OTHER
|
|
1187
1187
|
* recipient's `key_envelope`. `rotationId` present (D195, rev 42) widens
|
|
1188
1188
|
* this to `envelopes/<epoch>/<rotation_id>/<recipient_fingerprint>` — a
|
|
@@ -1193,25 +1193,25 @@ export declare const gitvaultPaths: {
|
|
|
1193
1193
|
/** `recipient-pins/<pin_manifest_version>.json` (D197, rev 42) — version-addressed, plaintext-structured, writer-signed. */
|
|
1194
1194
|
readonly pinManifest: (pinManifestVersion: string) => string;
|
|
1195
1195
|
};
|
|
1196
|
-
export interface
|
|
1196
|
+
export interface VaultRestoreMarker {
|
|
1197
1197
|
generation: string;
|
|
1198
1198
|
head_sha256: string;
|
|
1199
1199
|
}
|
|
1200
1200
|
/** Read this target directory's `restored_through` marker, or `null` when nothing was ever restored into it. */
|
|
1201
|
-
export declare function
|
|
1201
|
+
export declare function readVaultRestoreMarker(targetRepoDir: string): Promise<VaultRestoreMarker | null>;
|
|
1202
1202
|
/** Default `auto_gc_generations` — see the change proposal's rationale (≈2-3s over the fresh-checkpoint floor at this backlog, a busy repo compacts roughly once per few dozen pushes). */
|
|
1203
|
-
export declare const
|
|
1203
|
+
export declare const VAULT_AUTO_GC_GENERATIONS_DEFAULT = 32;
|
|
1204
1204
|
/**
|
|
1205
1205
|
* Read this checkout's auto-gc threshold, or the default when unset or
|
|
1206
1206
|
* unparseable. Never throws — a corrupt local config value degrades to the
|
|
1207
1207
|
* default rather than blocking a push's own auto-gc check.
|
|
1208
1208
|
*/
|
|
1209
|
-
export declare function
|
|
1209
|
+
export declare function readVaultAutoGcThreshold(targetRepoDir: string): Promise<number>;
|
|
1210
1210
|
/** Set this checkout's auto-gc threshold. `0` disables auto-gc entirely. */
|
|
1211
|
-
export declare function
|
|
1211
|
+
export declare function writeVaultAutoGcThreshold(targetRepoDir: string, generations: number): Promise<void>;
|
|
1212
1212
|
/**
|
|
1213
|
-
* {@link
|
|
1214
|
-
* restored from its own envelope (
|
|
1213
|
+
* {@link Vault.ensureRepoState}'s report when a cold keystore was
|
|
1214
|
+
* restored from its own envelope (vault-agent-envelopes D4). `trust` is
|
|
1215
1215
|
* `receipt` only when a creator-held recovery receipt pinned genesis;
|
|
1216
1216
|
* `platform_attested` means the control plane's signed allocation matched —
|
|
1217
1217
|
* consistency the platform itself vouches for, so `independently_verified`
|
|
@@ -1219,7 +1219,7 @@ export declare function writeGitvaultAutoGcThreshold(targetRepoDir: string, gene
|
|
|
1219
1219
|
* authentication. `continuity` is `pinned` when this keystore had already
|
|
1220
1220
|
* seen this genesis (a later open), `first_seen` on the first.
|
|
1221
1221
|
*/
|
|
1222
|
-
export interface
|
|
1222
|
+
export interface VaultColdOpenResult {
|
|
1223
1223
|
repo_id: string;
|
|
1224
1224
|
org_id: string;
|
|
1225
1225
|
provenance: "restored_from_envelope";
|
|
@@ -1229,9 +1229,9 @@ export interface GitvaultColdOpenResult {
|
|
|
1229
1229
|
epoch: string;
|
|
1230
1230
|
recipient_fingerprint: string;
|
|
1231
1231
|
}
|
|
1232
|
-
export interface
|
|
1233
|
-
keystore:
|
|
1234
|
-
transport:
|
|
1232
|
+
export interface VaultOptions {
|
|
1233
|
+
keystore: VaultKeystore;
|
|
1234
|
+
transport: VaultTransport;
|
|
1235
1235
|
repo_id: string;
|
|
1236
1236
|
/** The local git repository (objects for pack building / ancestry); optional for read-only use. */
|
|
1237
1237
|
repo_dir?: string;
|
|
@@ -1252,7 +1252,7 @@ export interface GitvaultVaultOptions {
|
|
|
1252
1252
|
allow_unauthenticated_salvage?: boolean;
|
|
1253
1253
|
}
|
|
1254
1254
|
/** How a checkpoint-bearing head binds a `retention_cutoff` ticket and expires roots (§4.5a / §4.5). */
|
|
1255
|
-
export interface
|
|
1255
|
+
export interface VaultCutoffOptions {
|
|
1256
1256
|
/**
|
|
1257
1257
|
* `effective_admitted_at` for a root's drop generation, or `null` when this
|
|
1258
1258
|
* client cannot resolve it — a `null` RETAINS the root (expiry is permissive).
|
|
@@ -1261,15 +1261,15 @@ export interface GitvaultCutoffOptions {
|
|
|
1261
1261
|
*/
|
|
1262
1262
|
effectiveAdmittedAt?: (droppedAtGeneration: string) => string | null;
|
|
1263
1263
|
}
|
|
1264
|
-
/** One admitted `rotate_epoch` transition {@link
|
|
1265
|
-
export interface
|
|
1264
|
+
/** One admitted `rotate_epoch` transition {@link Vault.verifyToNewest} walked over, KEYLESS (structural only — no envelope opened yet). */
|
|
1265
|
+
export interface VaultEncounteredRotation {
|
|
1266
1266
|
/** The rotate_epoch head's own generation. */
|
|
1267
1267
|
generation: string;
|
|
1268
1268
|
/** == `payload.new_epoch` == the head's own `epoch`. */
|
|
1269
1269
|
epoch: string;
|
|
1270
|
-
payload:
|
|
1270
|
+
payload: VaultRotateEpochPayload;
|
|
1271
1271
|
/**
|
|
1272
|
-
*
|
|
1272
|
+
* vault-multi-writer rev 47 — the writer who actually signed THIS
|
|
1273
1273
|
* rotation head (already resolved + signature-verified by the forward
|
|
1274
1274
|
* chain walk at the point this was collected — never the vault's fixed
|
|
1275
1275
|
* genesis creator in a multi-writer vault). Optional: the BACKWARD
|
|
@@ -1282,8 +1282,8 @@ export interface GitvaultEncounteredRotation {
|
|
|
1282
1282
|
*/
|
|
1283
1283
|
signing_pubkey?: string;
|
|
1284
1284
|
}
|
|
1285
|
-
/** Named detail for a reader's own `
|
|
1286
|
-
export interface
|
|
1285
|
+
/** Named detail for a reader's own `VAULT_EPOCH_NOT_OPENABLE` / decrypt stop point (Part C: `repos fsck`'s honest `chain_verified_to` vs `decryptable_to` split). */
|
|
1286
|
+
export interface VaultEpochDecryptFailure {
|
|
1287
1287
|
generation: string;
|
|
1288
1288
|
epoch: string;
|
|
1289
1289
|
rotation_id: string | null;
|
|
@@ -1300,79 +1300,79 @@ export interface GitvaultEpochDecryptFailure {
|
|
|
1300
1300
|
* `strict: false` (tolerant) mode, in which case `failure` names exactly
|
|
1301
1301
|
* where and why (never a bare, undifferentiated AEAD failure).
|
|
1302
1302
|
*/
|
|
1303
|
-
export interface
|
|
1303
|
+
export interface VaultDecryptValidationResult {
|
|
1304
1304
|
decryptable_to_generation: string;
|
|
1305
1305
|
/** The newest successfully-decrypted `ref_state`/`retention_roots`, or `null` if none this call reached (generation zero, or the very first head failed). */
|
|
1306
|
-
ref_state:
|
|
1307
|
-
retention_roots:
|
|
1306
|
+
ref_state: VaultRefState | null;
|
|
1307
|
+
retention_roots: VaultRetentionRoots | null;
|
|
1308
1308
|
/** Every locally-known epoch key at the end of this call, hex-encoded — seeded from the keystore's persisted `epoch_keys` plus every rotation this call itself opened. */
|
|
1309
1309
|
epoch_keys_hex: Record<string, string>;
|
|
1310
|
-
failure:
|
|
1310
|
+
failure: VaultEpochDecryptFailure | null;
|
|
1311
1311
|
}
|
|
1312
|
-
export interface
|
|
1312
|
+
export interface VaultVerifiedState {
|
|
1313
1313
|
generation: string;
|
|
1314
1314
|
head_sha256: string;
|
|
1315
1315
|
/** `null` at generation zero. */
|
|
1316
|
-
head:
|
|
1317
|
-
genesis:
|
|
1316
|
+
head: VaultHead | null;
|
|
1317
|
+
genesis: VaultGenesis;
|
|
1318
1318
|
/** Every admitted `rotate_epoch` transition walked THIS call, oldest first — keyless (Part A's structural half; D202's join predicate needs only this). */
|
|
1319
|
-
rotations:
|
|
1319
|
+
rotations: VaultEncounteredRotation[];
|
|
1320
1320
|
/** Present iff `decryptValidate` was requested. */
|
|
1321
|
-
decrypt:
|
|
1321
|
+
decrypt: VaultDecryptValidationResult | null;
|
|
1322
1322
|
}
|
|
1323
|
-
export interface
|
|
1324
|
-
ref_state:
|
|
1325
|
-
retention_roots:
|
|
1326
|
-
refs:
|
|
1327
|
-
roots:
|
|
1328
|
-
head_target:
|
|
1323
|
+
export interface VaultMaterializedState extends VaultVerifiedState {
|
|
1324
|
+
ref_state: VaultRefState | null;
|
|
1325
|
+
retention_roots: VaultRetentionRoots | null;
|
|
1326
|
+
refs: VaultRefMap;
|
|
1327
|
+
roots: VaultRetentionRoot[];
|
|
1328
|
+
head_target: VaultHeadTarget;
|
|
1329
1329
|
/** Every locally-known epoch key after this call, hex-encoded, keyed by epoch — `restoreObjectsInto` needs every epoch spanned by the covered generations, not just the newest. */
|
|
1330
1330
|
epoch_keys_hex: Record<string, string>;
|
|
1331
1331
|
}
|
|
1332
|
-
/** One directory entry {@link
|
|
1333
|
-
export interface
|
|
1332
|
+
/** One directory entry {@link Vault.reconcileEnvelopeRecipients} wrapped a fresh `key_envelope` for. */
|
|
1333
|
+
export interface VaultReconcileEnvelopeRecipientsWrapped {
|
|
1334
1334
|
principal_id: string;
|
|
1335
1335
|
ek_fingerprint: string;
|
|
1336
1336
|
}
|
|
1337
|
-
/** Why {@link
|
|
1338
|
-
export type
|
|
1339
|
-
export interface
|
|
1337
|
+
/** Why {@link Vault.reconcileEnvelopeRecipients} did NOT wrap a directory entry it otherwise would have. */
|
|
1338
|
+
export type VaultReconcileEnvelopeRecipientsSkipReason = "missing_public_key" | "invalid_public_key" | "pinned_key_mismatch";
|
|
1339
|
+
export interface VaultReconcileEnvelopeRecipientsSkipped {
|
|
1340
1340
|
principal_id: string;
|
|
1341
1341
|
ek_fingerprint: string;
|
|
1342
|
-
reason:
|
|
1342
|
+
reason: VaultReconcileEnvelopeRecipientsSkipReason;
|
|
1343
1343
|
/** `pinned_key_mismatch`: `{pinned_fingerprint, directory_fingerprint}`. `invalid_public_key` (derivation mismatch): `{derived_fingerprint}`. Absent for `missing_public_key` and a bad-encoding `invalid_public_key`. */
|
|
1344
1344
|
details?: Record<string, unknown>;
|
|
1345
1345
|
}
|
|
1346
|
-
/** {@link
|
|
1347
|
-
export interface
|
|
1346
|
+
/** {@link Vault.reconcileEnvelopeRecipients}'s full per-recipient breakdown. */
|
|
1347
|
+
export interface VaultReconcileEnvelopeRecipientsResult {
|
|
1348
1348
|
repo_id: string;
|
|
1349
1349
|
org_id: string;
|
|
1350
|
-
/** The epoch every wrap in this call used (V0: always {@link
|
|
1350
|
+
/** The epoch every wrap in this call used (V0: always {@link VAULT_GENESIS_EPOCH}). */
|
|
1351
1351
|
epoch: string;
|
|
1352
1352
|
/** Directory entries this call itself wrapped a NEW `key_envelope` for. */
|
|
1353
|
-
wrapped:
|
|
1353
|
+
wrapped: VaultReconcileEnvelopeRecipientsWrapped[];
|
|
1354
1354
|
/** `ek_` fingerprints already covering the vault before (or, for a raced wrap, as of) this call — no action taken. */
|
|
1355
1355
|
already_covered: string[];
|
|
1356
1356
|
/** Directory entries this call could not (or, for `pinned_key_mismatch`, would not) wrap. */
|
|
1357
|
-
skipped:
|
|
1357
|
+
skipped: VaultReconcileEnvelopeRecipientsSkipped[];
|
|
1358
1358
|
}
|
|
1359
|
-
/** One `pending_writers[]` entry {@link
|
|
1360
|
-
export interface
|
|
1359
|
+
/** One `pending_writers[]` entry {@link Vault.reconcileWriterAdmissions} admitted via a fresh `add_writer_key{"writer"}` head. */
|
|
1360
|
+
export interface VaultReconcileWriterAdmissionsAdmitted {
|
|
1361
1361
|
principal_id: string;
|
|
1362
1362
|
writer_key_id: string;
|
|
1363
1363
|
generation: string;
|
|
1364
1364
|
}
|
|
1365
|
-
/** Why {@link
|
|
1366
|
-
export type
|
|
1367
|
-
export interface
|
|
1365
|
+
/** Why {@link Vault.reconcileWriterAdmissions} did NOT admit a `pending_writers[]` entry it otherwise would have. */
|
|
1366
|
+
export type VaultReconcileWriterAdmissionsSkipReason = "missing_signing_pubkey" | "invalid_signing_pubkey";
|
|
1367
|
+
export interface VaultReconcileWriterAdmissionsSkipped {
|
|
1368
1368
|
principal_id: string;
|
|
1369
1369
|
writer_key_id: string;
|
|
1370
|
-
reason:
|
|
1370
|
+
reason: VaultReconcileWriterAdmissionsSkipReason;
|
|
1371
1371
|
}
|
|
1372
1372
|
/**
|
|
1373
|
-
* {@link
|
|
1373
|
+
* {@link Vault.reconcileWriterAdmissions}'s full per-candidate
|
|
1374
1374
|
* breakdown (task 5.7). Structurally parallel to
|
|
1375
|
-
* {@link
|
|
1375
|
+
* {@link VaultReconcileEnvelopeRecipientsResult} (same repo/wrapped-or-
|
|
1376
1376
|
* admitted/already-covered/skipped shape), but this reconcile submits a REAL
|
|
1377
1377
|
* chain head per admission (one `add_writer_key{"writer"}` transition per
|
|
1378
1378
|
* candidate — the protocol allows only one added writer per head) rather
|
|
@@ -1380,7 +1380,7 @@ export interface GitvaultReconcileWriterAdmissionsSkipped {
|
|
|
1380
1380
|
* admission materializes fresh against the PRIOR admission's own updated
|
|
1381
1381
|
* writer set.
|
|
1382
1382
|
*/
|
|
1383
|
-
export interface
|
|
1383
|
+
export interface VaultReconcileWriterAdmissionsResult {
|
|
1384
1384
|
repo_id: string;
|
|
1385
1385
|
org_id: string;
|
|
1386
1386
|
/**
|
|
@@ -1395,26 +1395,26 @@ export interface GitvaultReconcileWriterAdmissionsResult {
|
|
|
1395
1395
|
*/
|
|
1396
1396
|
eligible: boolean;
|
|
1397
1397
|
/** `pending_writers[]` entries this call admitted this call, each via its own head. */
|
|
1398
|
-
admitted:
|
|
1398
|
+
admitted: VaultReconcileWriterAdmissionsAdmitted[];
|
|
1399
1399
|
/** `writer_key_id`s already active before (or, for a raced admission, as of) this call — no action taken. */
|
|
1400
1400
|
already_covered: string[];
|
|
1401
1401
|
/** `pending_writers[]` entries this call could not admit. */
|
|
1402
|
-
skipped:
|
|
1402
|
+
skipped: VaultReconcileWriterAdmissionsSkipped[];
|
|
1403
1403
|
}
|
|
1404
|
-
export interface
|
|
1405
|
-
transaction:
|
|
1404
|
+
export interface VaultPushOptions {
|
|
1405
|
+
transaction: VaultRefTransaction;
|
|
1406
1406
|
/** New `HEAD` target for the published ref_state; carried forward when omitted. */
|
|
1407
|
-
head_target?:
|
|
1407
|
+
head_target?: VaultHeadTarget;
|
|
1408
1408
|
protocol_refs?: "refuse" | "allow";
|
|
1409
1409
|
/** Force the checkpoint-bearing form (purpose `ordinary_push`) regardless of delta size. */
|
|
1410
1410
|
checkpoint?: boolean;
|
|
1411
1411
|
/** Bind a fresh `retention_cutoff` ticket so expired roots may leave the map (checkpoint-bearing heads only). */
|
|
1412
|
-
cutoff?:
|
|
1412
|
+
cutoff?: VaultCutoffOptions;
|
|
1413
1413
|
/** Built lazily at head-sign time — the deploy lane may still be computing the plan digest. */
|
|
1414
|
-
capture_binding?:
|
|
1414
|
+
capture_binding?: VaultCaptureBinding | (() => Promise<VaultCaptureBinding | null> | VaultCaptureBinding | null);
|
|
1415
1415
|
/**
|
|
1416
|
-
* A caller-supplied base (
|
|
1417
|
-
* VERBATIM for the first attempt instead of calling {@link
|
|
1416
|
+
* A caller-supplied base (vault-client-round-trips design D1) — used
|
|
1417
|
+
* VERBATIM for the first attempt instead of calling {@link Vault.materialize}
|
|
1418
1418
|
* again. Only meaningful for a base the caller JUST materialized from this
|
|
1419
1419
|
* same vault instance (e.g. one `list → push` protocol exchange sharing
|
|
1420
1420
|
* one snapshot for both `expected_old` derivation and the push itself) —
|
|
@@ -1423,34 +1423,34 @@ export interface GitvaultPushOptions {
|
|
|
1423
1423
|
* admission), just not the round-trip win. A conflict retry re-materializes
|
|
1424
1424
|
* from storage exactly as when no base is supplied at all.
|
|
1425
1425
|
*/
|
|
1426
|
-
base?:
|
|
1426
|
+
base?: VaultMaterializedState;
|
|
1427
1427
|
}
|
|
1428
|
-
export interface
|
|
1428
|
+
export interface VaultPublishResult {
|
|
1429
1429
|
generation: string;
|
|
1430
1430
|
head_sha256: string;
|
|
1431
|
-
head:
|
|
1431
|
+
head: VaultHead;
|
|
1432
1432
|
admission_record_sha256: string;
|
|
1433
|
-
capture_receipt:
|
|
1433
|
+
capture_receipt: VaultCaptureReceipt | null;
|
|
1434
1434
|
/** `wal` = direct WAL receipts; `checkpoint` = the delta shipped as a checkpoint set. */
|
|
1435
1435
|
form: "wal" | "checkpoint";
|
|
1436
1436
|
conflicts_retried: number;
|
|
1437
|
-
refs:
|
|
1437
|
+
refs: VaultRefMap;
|
|
1438
1438
|
/**
|
|
1439
|
-
*
|
|
1439
|
+
* vault-clone-scaling (P3): generations-since-checkpoint against the
|
|
1440
1440
|
* coverage this checkout has locally learned (`{0, false}` when unknown
|
|
1441
1441
|
* — see the keystore field's doc). Advisory data only; consumers echo,
|
|
1442
1442
|
* never gate.
|
|
1443
1443
|
*/
|
|
1444
|
-
checkpoint_staleness:
|
|
1444
|
+
checkpoint_staleness: VaultCheckpointStaleness;
|
|
1445
1445
|
}
|
|
1446
|
-
/** {@link
|
|
1447
|
-
export interface
|
|
1446
|
+
/** {@link Vault.rotateEpoch}'s result (D193-D203, rev 42). */
|
|
1447
|
+
export interface VaultRotationResult {
|
|
1448
1448
|
outcome: "admitted";
|
|
1449
1449
|
generation: string;
|
|
1450
1450
|
head_sha256: string;
|
|
1451
1451
|
new_epoch: string;
|
|
1452
1452
|
rotation_id: string;
|
|
1453
|
-
reason:
|
|
1453
|
+
reason: VaultRotationReason;
|
|
1454
1454
|
included: {
|
|
1455
1455
|
principal_id: string;
|
|
1456
1456
|
ek_fingerprint: string;
|
|
@@ -1458,10 +1458,10 @@ export interface GitvaultRotationResult {
|
|
|
1458
1458
|
excluded_keyless_principal_ids: string[];
|
|
1459
1459
|
excluded_unconfirmed_principal_ids: string[];
|
|
1460
1460
|
admission_record_sha256: string;
|
|
1461
|
-
capture_receipt:
|
|
1461
|
+
capture_receipt: VaultCaptureReceipt | null;
|
|
1462
1462
|
/**
|
|
1463
1463
|
* `"passed"` — this principal is itself an included recipient and its own
|
|
1464
|
-
* new-epoch envelope opened (via {@link import("../namespaces/
|
|
1464
|
+
* new-epoch envelope opened (via {@link import("../namespaces/vault.crypto.js").openEpochRotationForRecipient},
|
|
1465
1465
|
* the real reader entry point) to reproduce the sealed `K_e` +
|
|
1466
1466
|
* `epoch_key_commitment` — the SAME round-trip that fed
|
|
1467
1467
|
* `payload.self_open_attestation` (D209), run BEFORE this head was ever
|
|
@@ -1476,7 +1476,7 @@ export interface GitvaultRotationResult {
|
|
|
1476
1476
|
* `keystore.recordEpochRotation` below advances the LOCAL pointer
|
|
1477
1477
|
* unconditionally once admission succeeds, regardless of `self_check` —
|
|
1478
1478
|
* an agent/CI writer that is deliberately never a directory envelope
|
|
1479
|
-
* recipient (design D1 of `services/
|
|
1479
|
+
* recipient (design D1 of `services/vault/desired-recipients.ts`:
|
|
1480
1480
|
* "agents hold their own vault keys in their CLI keystore") keeps
|
|
1481
1481
|
* read/write access to its own vault through every rotation it itself
|
|
1482
1482
|
* drives, with or without an envelope.
|
|
@@ -1511,7 +1511,7 @@ export interface GitvaultRotationResult {
|
|
|
1511
1511
|
principal_ids: string[];
|
|
1512
1512
|
} | null;
|
|
1513
1513
|
/**
|
|
1514
|
-
*
|
|
1514
|
+
* vault-multi-writer (task 5.9, D6/D227) — writer keys this SAME head
|
|
1515
1515
|
* removed via a folded `writer_set_update`, each with the reason it was
|
|
1516
1516
|
* removed for. Empty (never omitted) when nothing needed removing — the
|
|
1517
1517
|
* common case, matching `excluded_keyless_principal_ids`' own
|
|
@@ -1525,7 +1525,7 @@ export interface GitvaultRotationResult {
|
|
|
1525
1525
|
}[];
|
|
1526
1526
|
}
|
|
1527
1527
|
/**
|
|
1528
|
-
* What {@link
|
|
1528
|
+
* What {@link Vault.planPush} reports — a REAL
|
|
1529
1529
|
* local computation, not an estimate: every number here comes from actually
|
|
1530
1530
|
* building the packs (or checkpoint set) and actually sealing/encrypting
|
|
1531
1531
|
* them, exactly as a real `push` would. `would_admit_generation` is what this
|
|
@@ -1533,7 +1533,7 @@ export interface GitvaultRotationResult {
|
|
|
1533
1533
|
* win the race before a real push runs (see the method doc for why that is
|
|
1534
1534
|
* not a defect: `git push --dry-run` carries the identical caveat).
|
|
1535
1535
|
*/
|
|
1536
|
-
export interface
|
|
1536
|
+
export interface VaultPushPlan {
|
|
1537
1537
|
/** The base this plan was computed against — `materialize()`'s generation at call time. */
|
|
1538
1538
|
base_generation: string;
|
|
1539
1539
|
/** The generation a real push would claim, computed the same way a real push computes it (`nextGeneration(base_generation)`). */
|
|
@@ -1543,11 +1543,11 @@ export interface GitvaultPushPlan {
|
|
|
1543
1543
|
/** `wal` = direct WAL receipts; `checkpoint` = the delta would ship as a checkpoint set — the SAME threshold real `push` uses. */
|
|
1544
1544
|
form: "wal" | "checkpoint";
|
|
1545
1545
|
/** The ref map this push would publish (after evaluating the transaction against the base). */
|
|
1546
|
-
refs:
|
|
1547
|
-
head_target:
|
|
1546
|
+
refs: VaultRefMap;
|
|
1547
|
+
head_target: VaultHeadTarget;
|
|
1548
1548
|
/** Every object that would be uploaded — `ref_state`, `retention_roots`, and the WAL/checkpoint pack(s) — with their REAL sealed (encrypted) sizes. */
|
|
1549
1549
|
objects: Array<{
|
|
1550
|
-
object_kind:
|
|
1550
|
+
object_kind: VaultUploadObject["object_kind"];
|
|
1551
1551
|
size_bytes: string;
|
|
1552
1552
|
}>;
|
|
1553
1553
|
object_count: number;
|
|
@@ -1557,11 +1557,11 @@ export interface GitvaultPushPlan {
|
|
|
1557
1557
|
raw_bytes: string;
|
|
1558
1558
|
}
|
|
1559
1559
|
/**
|
|
1560
|
-
* What {@link
|
|
1560
|
+
* What {@link Vault.verifyStoredCheckpoint} observed. Every boolean is
|
|
1561
1561
|
* a FINDING, not a promise: a `false` here is what makes a truthful negative
|
|
1562
1562
|
* `verifier_receipt` possible.
|
|
1563
1563
|
*/
|
|
1564
|
-
export interface
|
|
1564
|
+
export interface VaultStoredCheckpointAttestation {
|
|
1565
1565
|
checkpoint_head_sha256: string;
|
|
1566
1566
|
checkpoint_generation: string;
|
|
1567
1567
|
claim_set_sha256: string;
|
|
@@ -1578,26 +1578,26 @@ export interface GitvaultStoredCheckpointAttestation {
|
|
|
1578
1578
|
/** The `rootset` commitment over this generation's roots carrier — the intent core's `retention_state_hmac`. */
|
|
1579
1579
|
retention_state_hmac: string;
|
|
1580
1580
|
}
|
|
1581
|
-
export interface
|
|
1582
|
-
manifest:
|
|
1583
|
-
claim_set:
|
|
1584
|
-
claim_set_receipt:
|
|
1585
|
-
objects:
|
|
1581
|
+
export interface VaultBuiltCheckpoint {
|
|
1582
|
+
manifest: VaultCheckpointManifest;
|
|
1583
|
+
claim_set: VaultCheckpointClaimSet;
|
|
1584
|
+
claim_set_receipt: VaultCheckpointBlock["claim_set"];
|
|
1585
|
+
objects: VaultUploadObject[];
|
|
1586
1586
|
/** Plaintext packs in order (for the acceptance self-check). */
|
|
1587
1587
|
packs: Uint8Array[];
|
|
1588
1588
|
covered_tips: string[];
|
|
1589
1589
|
}
|
|
1590
1590
|
/** A transport-agnostic view of git ops the publication needs (the local repository). */
|
|
1591
|
-
export declare class
|
|
1591
|
+
export declare class Vault {
|
|
1592
1592
|
#private;
|
|
1593
|
-
readonly keystore:
|
|
1594
|
-
readonly transport:
|
|
1593
|
+
readonly keystore: VaultKeystore;
|
|
1594
|
+
readonly transport: VaultTransport;
|
|
1595
1595
|
readonly repoId: string;
|
|
1596
1596
|
readonly repoDir: string | null;
|
|
1597
1597
|
private readonly now;
|
|
1598
1598
|
private readonly budget;
|
|
1599
1599
|
/**
|
|
1600
|
-
*
|
|
1600
|
+
* vault-clone-scaling (bench P2): the CURRENT walk window's prefetched
|
|
1601
1601
|
* bytes — head bytes (bounded-concurrent direct reads) and carrier frames
|
|
1602
1602
|
* (one batched getObjects), keyed by storage path — filled by
|
|
1603
1603
|
* `verifyToNewest`'s per-page prefetch and `restoreObjectsInto`'s
|
|
@@ -1614,7 +1614,7 @@ export declare class GitvaultVault {
|
|
|
1614
1614
|
*/
|
|
1615
1615
|
private walkPrefetch;
|
|
1616
1616
|
/**
|
|
1617
|
-
* WAL pack bytes carried by the state read's delta (
|
|
1617
|
+
* WAL pack bytes carried by the state read's delta (vault-delta-fetch),
|
|
1618
1618
|
* keyed by object_id — the walkPrefetch discipline exactly: UNTRUSTED
|
|
1619
1619
|
* until a consumer's own hash check passes, a mismatch is a plain miss,
|
|
1620
1620
|
* and the buffer is transient (stashed by {@link tryStateFastPath},
|
|
@@ -1622,7 +1622,7 @@ export declare class GitvaultVault {
|
|
|
1622
1622
|
*/
|
|
1623
1623
|
private stateDeltaPacks;
|
|
1624
1624
|
/**
|
|
1625
|
-
* The state read's restore plan (
|
|
1625
|
+
* The state read's restore plan (vault-restore-recipe design D1-D5),
|
|
1626
1626
|
* stashed RAW — never verified at stash time, unlike `stateDeltaPacks`
|
|
1627
1627
|
* (whose heads self-check before entering the shared keystore cache): a
|
|
1628
1628
|
* plan's heads/checkpoint/packs are only ever verified by {@link
|
|
@@ -1638,7 +1638,7 @@ export declare class GitvaultVault {
|
|
|
1638
1638
|
private readonly allowUnauthenticatedSalvage;
|
|
1639
1639
|
private genesisCache;
|
|
1640
1640
|
/**
|
|
1641
|
-
*
|
|
1641
|
+
* vault-byo-primary-bucket task 3.2 — this vault's resolved BYO write
|
|
1642
1642
|
* target, cached after the first resolution (storage_profile/
|
|
1643
1643
|
* byo_destination are immutable-at-allocation in v1, so a single
|
|
1644
1644
|
* read-once-per-instance is safe). `undefined` = not yet resolved;
|
|
@@ -1647,14 +1647,14 @@ export declare class GitvaultVault {
|
|
|
1647
1647
|
* been configured to write — see {@link resolveByoWriteTarget}).
|
|
1648
1648
|
*/
|
|
1649
1649
|
private byoResolution;
|
|
1650
|
-
constructor(options:
|
|
1651
|
-
static open(options:
|
|
1652
|
-
repoFile():
|
|
1650
|
+
constructor(options: VaultOptions);
|
|
1651
|
+
static open(options: VaultOptions): Vault;
|
|
1652
|
+
repoFile(): VaultRepoFile;
|
|
1653
1653
|
/**
|
|
1654
|
-
*
|
|
1654
|
+
* vault-agent-envelopes D4 — the COLD OPEN. A keystore that holds an
|
|
1655
1655
|
* identity but no repo file for this vault (a member joining from a fresh
|
|
1656
1656
|
* machine, or a creator whose repo file was lost) restores `K_repo` from
|
|
1657
|
-
* its OWN `key_envelope` instead of dying `
|
|
1657
|
+
* its OWN `key_envelope` instead of dying `VAULT_REPO_STATE_MISSING`:
|
|
1658
1658
|
*
|
|
1659
1659
|
* 1. genesis (the writer-key source) is fetched and signature-verified;
|
|
1660
1660
|
* 2. its creator fingerprints are compared against the control plane's
|
|
@@ -1663,10 +1663,10 @@ export declare class GitvaultVault {
|
|
|
1663
1663
|
* genesis needs a substituted allocation, which the org's owners can
|
|
1664
1664
|
* see — TOFU + audit, human-envelopes D4's tier);
|
|
1665
1665
|
* 3. the envelope-recipients read says whether THIS fingerprint is
|
|
1666
|
-
* covered — if not, `
|
|
1666
|
+
* covered — if not, `VAULT_ENVELOPE_PENDING` names the key-holders
|
|
1667
1667
|
* who can fulfil and the exact next actions (never a terminal error:
|
|
1668
1668
|
* the desired state already records this member; any key-holder's
|
|
1669
|
-
* next
|
|
1669
|
+
* next vault operation wraps);
|
|
1670
1670
|
* 4. the base envelope is fetched, opened, and the repo file written
|
|
1671
1671
|
* `restored_from_envelope` with the genesis hash PINNED (a later open
|
|
1672
1672
|
* seeing a different genesis for this repo_id refuses
|
|
@@ -1679,7 +1679,7 @@ export declare class GitvaultVault {
|
|
|
1679
1679
|
* Returns `null` when the repo file already existed (nothing restored).
|
|
1680
1680
|
*/
|
|
1681
1681
|
/**
|
|
1682
|
-
*
|
|
1682
|
+
* vault-multi-writer (rev 47) — the vault's CURRENT admitted writer set
|
|
1683
1683
|
* for a cold open, computed from the chain itself: every admitted head is
|
|
1684
1684
|
* hash-checked against the listing, signature-verified under the writer
|
|
1685
1685
|
* the chain admits at that point, and its `add_writer_key` /
|
|
@@ -1689,16 +1689,16 @@ export declare class GitvaultVault {
|
|
|
1689
1689
|
* trusted when the chain vouches for it.
|
|
1690
1690
|
*/
|
|
1691
1691
|
private resolveAdmittedWritersForColdOpen;
|
|
1692
|
-
ensureRepoState(): Promise<
|
|
1692
|
+
ensureRepoState(): Promise<VaultColdOpenResult | null>;
|
|
1693
1693
|
/** {@link open}, but a missing repo file triggers {@link ensureRepoState} first. */
|
|
1694
|
-
static openOrRestore(options:
|
|
1695
|
-
vault:
|
|
1696
|
-
restored:
|
|
1694
|
+
static openOrRestore(options: VaultOptions): Promise<{
|
|
1695
|
+
vault: Vault;
|
|
1696
|
+
restored: VaultColdOpenResult | null;
|
|
1697
1697
|
}>;
|
|
1698
1698
|
private kRepo;
|
|
1699
1699
|
private epoch;
|
|
1700
1700
|
/**
|
|
1701
|
-
*
|
|
1701
|
+
* vault-clone-scaling (P3): staleness of the newest checkpoint coverage
|
|
1702
1702
|
* this checkout has locally learned, measured at `newestGeneration`. Reads
|
|
1703
1703
|
* the keystore AFTER the caller's own persist (a checkpoint-form push has
|
|
1704
1704
|
* already recorded its fresh coverage by the time its result is built), so
|
|
@@ -1710,7 +1710,7 @@ export declare class GitvaultVault {
|
|
|
1710
1710
|
* Fetch many generation-addressed heads' bytes ahead of the ordered walk,
|
|
1711
1711
|
* keyed by head path.
|
|
1712
1712
|
*
|
|
1713
|
-
* BATCH-FIRST (
|
|
1713
|
+
* BATCH-FIRST (vault-batched-head-reads task 4.2): one
|
|
1714
1714
|
* `POST …/head-reads` carries a whole page's bytes. Heads deliberately do
|
|
1715
1715
|
* NOT ride `getObjects` — the `object-reads` presign batch is CARRIER-ONLY
|
|
1716
1716
|
* by wire design (see `getObjectsBytes`'s fail-closed doc comment; the live
|
|
@@ -1718,10 +1718,10 @@ export declare class GitvaultVault {
|
|
|
1718
1718
|
* by 25 serial singles), which is exactly why the batch route had to be its
|
|
1719
1719
|
* own thing.
|
|
1720
1720
|
*
|
|
1721
|
-
* FALLBACK (the shipped
|
|
1721
|
+
* FALLBACK (the shipped vault-clone-scaling P2 shape): on ANY
|
|
1722
1722
|
* unsupported answer — an older gateway, a refusal, a fault — head bytes
|
|
1723
1723
|
* parallelize as the SAME direct GETs the ordered walk itself would issue,
|
|
1724
|
-
* just early and overlapped at {@link
|
|
1724
|
+
* just early and overlapped at {@link VAULT_TRANSPORT_CONCURRENCY}. The
|
|
1725
1725
|
* transport remembers a route-absent verdict, so the probe is paid once per
|
|
1726
1726
|
* client, not once per window.
|
|
1727
1727
|
*
|
|
@@ -1734,11 +1734,11 @@ export declare class GitvaultVault {
|
|
|
1734
1734
|
private git;
|
|
1735
1735
|
/** Fetch + pin-check the genesis (the writer key source). */
|
|
1736
1736
|
genesis(): Promise<{
|
|
1737
|
-
genesis:
|
|
1737
|
+
genesis: VaultGenesis;
|
|
1738
1738
|
sha256: string;
|
|
1739
1739
|
}>;
|
|
1740
1740
|
/**
|
|
1741
|
-
*
|
|
1741
|
+
* vault-composite-state-read design D1 — the pin-current fast path
|
|
1742
1742
|
* `verifyToNewest` tries FIRST: one `GET …/state` in place of BOTH the
|
|
1743
1743
|
* live "server still holds the pin" read {@link readHead} would otherwise
|
|
1744
1744
|
* perform AND, when eligible, the `listHeads` walk that would follow it.
|
|
@@ -1776,13 +1776,13 @@ export declare class GitvaultVault {
|
|
|
1776
1776
|
* {@link openCarrier} already key their own writes) but NEVER trusted
|
|
1777
1777
|
* here — every reader downstream re-verifies a cache hit against the hash
|
|
1778
1778
|
* it would check network bytes against before using it (this file's own
|
|
1779
|
-
* established cache discipline; see `
|
|
1779
|
+
* established cache discipline; see `VaultKeystore`'s class doc
|
|
1780
1780
|
* comment). A wrong or absent byte this method wrote is therefore just a
|
|
1781
1781
|
* cache MISS on the next read, never a verification bypass.
|
|
1782
1782
|
*/
|
|
1783
1783
|
private tryStateFastPath;
|
|
1784
1784
|
/**
|
|
1785
|
-
* Absorb a state read's delta (
|
|
1785
|
+
* Absorb a state read's delta (vault-delta-fetch): heads blind-warm the
|
|
1786
1786
|
* SAME keystore head cache every walk already re-verifies on read (the
|
|
1787
1787
|
* established cache discipline — a wrong byte is a miss, never a bypass),
|
|
1788
1788
|
* gated only on each entry's self-consistency; packs stash into the
|
|
@@ -1830,7 +1830,7 @@ export declare class GitvaultVault {
|
|
|
1830
1830
|
* producer/consumer would, and counting each decrypt attempt as an EXTRA
|
|
1831
1831
|
* unit against the same `this.budget` (decryption is the expensive step).
|
|
1832
1832
|
* `options.strict` (default `true`) throws immediately, fail-closed, on the
|
|
1833
|
-
* first `
|
|
1833
|
+
* first `VAULT_EPOCH_NOT_OPENABLE` / AEAD failure it hits — the ordinary
|
|
1834
1834
|
* `materialize()` read path's behavior. `strict: false` (fsck's tolerant
|
|
1835
1835
|
* mode) instead records `decrypt.failure` and stops attempting further
|
|
1836
1836
|
* decrypts while the pure chain walk keeps going — this is exactly what
|
|
@@ -1843,7 +1843,7 @@ export declare class GitvaultVault {
|
|
|
1843
1843
|
strict?: boolean;
|
|
1844
1844
|
deltaSince?: string;
|
|
1845
1845
|
restore?: boolean;
|
|
1846
|
-
}): Promise<
|
|
1846
|
+
}): Promise<VaultVerifiedState>;
|
|
1847
1847
|
/**
|
|
1848
1848
|
* Read one NEWLY-LISTED head's raw bytes, trying the local cache first
|
|
1849
1849
|
* (design D3), re-verified against `expectedSha256` — the SAME check
|
|
@@ -1920,7 +1920,7 @@ export declare class GitvaultVault {
|
|
|
1920
1920
|
* transition now opens the rotation's own envelope and decrypts under the
|
|
1921
1921
|
* NEW epoch, chaining through multiple sequential rotations; a keystore
|
|
1922
1922
|
* with no envelope for a new epoch fails CLOSED with
|
|
1923
|
-
* `
|
|
1923
|
+
* `VAULT_EPOCH_NOT_OPENABLE`, never a bare `VAULT_AEAD_AUTH_FAILURE`)
|
|
1924
1924
|
* — `strict: true` means this call throws exactly where the OLD
|
|
1925
1925
|
* (pre-fix) `materialize()` silently produced a wrong `k_obj` instead.
|
|
1926
1926
|
*/
|
|
@@ -1928,7 +1928,7 @@ export declare class GitvaultVault {
|
|
|
1928
1928
|
persist?: boolean;
|
|
1929
1929
|
deltaSince?: string;
|
|
1930
1930
|
restore?: boolean;
|
|
1931
|
-
}): Promise<
|
|
1931
|
+
}): Promise<VaultMaterializedState>;
|
|
1932
1932
|
/**
|
|
1933
1933
|
* Wrap the vault's CURRENT epoch key to every org member the directory
|
|
1934
1934
|
* lists but the vault does not yet have a `key_envelope` for.
|
|
@@ -1937,7 +1937,7 @@ export declare class GitvaultVault {
|
|
|
1937
1937
|
* describes a recipient-set change as an epoch rotation — "history epochs
|
|
1938
1938
|
* stay wrapped as they were; a new member reads from their first covered
|
|
1939
1939
|
* epoch forward" — which needs a protocol revision: V0 pins `epoch` to
|
|
1940
|
-
* the single constant `
|
|
1940
|
+
* the single constant `VAULT_GENESIS_EPOCH` on every head, so there
|
|
1941
1941
|
* is no "forward" to speak of. What this method actually does, legally, without any
|
|
1942
1942
|
* protocol change: `key_envelope` objects are never head-referenced (not
|
|
1943
1943
|
* even genesis's own envelope is), so uploading an ADDITIONAL one at
|
|
@@ -1962,7 +1962,7 @@ export declare class GitvaultVault {
|
|
|
1962
1962
|
*
|
|
1963
1963
|
* **The gateway directory route carries `public_key` on every row**
|
|
1964
1964
|
* (`GET /orgs/v1/:org_id/encryption-keys` — see the
|
|
1965
|
-
* doc comment on {@link
|
|
1965
|
+
* doc comment on {@link VaultOrgEncryptionKeyEntry}), so against a
|
|
1966
1966
|
* current gateway entries actually wrap. A directory entry that arrives
|
|
1967
1967
|
* WITHOUT the field (an older/rolling-deploy gateway) is still tolerated
|
|
1968
1968
|
* per-entry — reported under `skipped` with reason `missing_public_key`,
|
|
@@ -1970,11 +1970,11 @@ export declare class GitvaultVault {
|
|
|
1970
1970
|
*
|
|
1971
1971
|
* Best-effort by design at the call site, not here: this method itself
|
|
1972
1972
|
* either completes (returning a full per-recipient breakdown) or throws
|
|
1973
|
-
* (e.g. `
|
|
1973
|
+
* (e.g. `VAULT_READ_ONLY` when this principal holds no signing key).
|
|
1974
1974
|
* Callers that want "never block on this" (the deploy hook) wrap the call
|
|
1975
|
-
* themselves — see `
|
|
1975
|
+
* themselves — see `Repos.capture`'s `#tryReconcileEnvelopeRecipients`.
|
|
1976
1976
|
*/
|
|
1977
|
-
reconcileEnvelopeRecipients(): Promise<
|
|
1977
|
+
reconcileEnvelopeRecipients(): Promise<VaultReconcileEnvelopeRecipientsResult>;
|
|
1978
1978
|
/**
|
|
1979
1979
|
* `keyOverride` (D194, rev 42): a `rotate_epoch` head's OWN `ref_state`/
|
|
1980
1980
|
* `retention_roots` must be sealed under the NEWLY-sampled `K_e` at the
|
|
@@ -1984,7 +1984,7 @@ export declare class GitvaultVault {
|
|
|
1984
1984
|
*/
|
|
1985
1985
|
private seal;
|
|
1986
1986
|
/**
|
|
1987
|
-
* The owner signing seed, or `
|
|
1987
|
+
* The owner signing seed, or `VAULT_READ_ONLY`.
|
|
1988
1988
|
*
|
|
1989
1989
|
* Public so the prune lane signs its intent core, wrapper, and verifier
|
|
1990
1990
|
* receipt through the SAME refusal path every other signed object uses — a
|
|
@@ -1995,7 +1995,7 @@ export declare class GitvaultVault {
|
|
|
1995
1995
|
signer(): Uint8Array;
|
|
1996
1996
|
private writerKeyId;
|
|
1997
1997
|
/**
|
|
1998
|
-
*
|
|
1998
|
+
* vault-multi-writer (task 5.8) — the push pre-check: before signing an
|
|
1999
1999
|
* ORDINARY head (any operation that expects this session to already be an
|
|
2000
2000
|
* active writer), refuse EARLY and LOCALLY when this session's own key is
|
|
2001
2001
|
* not (or is no longer) an active writer, rather than let real
|
|
@@ -2009,13 +2009,13 @@ export declare class GitvaultVault {
|
|
|
2009
2009
|
* `removedMidRace` (design D8/D10) distinguishes the two shapes this
|
|
2010
2010
|
* refusal takes: `false` (the default) is the ORDINARY pre-check — this
|
|
2011
2011
|
* session was never (or is not currently) an admitted writer, thrown as
|
|
2012
|
-
* `
|
|
2012
|
+
* `VAULT_WRITER_NOT_ADMITTED`. `true` is the CAS-LOSER path
|
|
2013
2013
|
* specifically: a retry, after re-materializing from the winner, that
|
|
2014
2014
|
* discovers THIS session's own key was removed by whatever won the race —
|
|
2015
2015
|
* "stop if removed" in D8's loser-rule sequence (fetch winner → verify →
|
|
2016
2016
|
* apply writer transition → stop if removed → rebase → rebuild → bounded
|
|
2017
2017
|
* backoff) — thrown as the more specific, client-local
|
|
2018
|
-
* `
|
|
2018
|
+
* `VAULT_WRITER_REMOVED` (D10) instead: a real prior attempt just lost
|
|
2019
2019
|
* to a removal, not a caller who was never eligible.
|
|
2020
2020
|
*
|
|
2021
2021
|
* Deliberately NOT called for a "handoff"-door `add_writer_key` head
|
|
@@ -2023,7 +2023,7 @@ export declare class GitvaultVault {
|
|
|
2023
2023
|
* yet a writer — becoming one is what that exact head does.
|
|
2024
2024
|
*/
|
|
2025
2025
|
private assertCallerIsWriter;
|
|
2026
|
-
/** The owner's full signing keypair, or `
|
|
2026
|
+
/** The owner's full signing keypair, or `VAULT_READ_ONLY` — same refusal path as {@link signer}, which returns only the seed; {@link sealKeyEnvelope} needs both halves. */
|
|
2027
2027
|
private signingKeypair;
|
|
2028
2028
|
private buildRefState;
|
|
2029
2029
|
private buildRetentionRoots;
|
|
@@ -2048,7 +2048,7 @@ export declare class GitvaultVault {
|
|
|
2048
2048
|
* generation's. Same `openCarrier` path, same `CHAIN_UNUSABLE` semantics — a
|
|
2049
2049
|
* carrier that cannot be opened is never silently treated as empty.
|
|
2050
2050
|
*/
|
|
2051
|
-
openRetentionRootsAt(receipt:
|
|
2051
|
+
openRetentionRootsAt(receipt: VaultRetentionRootsReceipt): Promise<VaultRetentionRoots>;
|
|
2052
2052
|
private digest;
|
|
2053
2053
|
/**
|
|
2054
2054
|
* The §1 keyed commitment under one of the five `K_digest` labels.
|
|
@@ -2060,14 +2060,14 @@ export declare class GitvaultVault {
|
|
|
2060
2060
|
* agreeing. Keyed by design (§7.3): a server-comparable plaintext digest
|
|
2061
2061
|
* would be a confirmation oracle.
|
|
2062
2062
|
*/
|
|
2063
|
-
keyedDigest(label:
|
|
2063
|
+
keyedDigest(label: VaultDigestLabel, content: unknown): string;
|
|
2064
2064
|
/** Strip the single top-level signature — the commitment preimage shape carriers use. */
|
|
2065
2065
|
digestPreimage<T extends {
|
|
2066
2066
|
signature: string;
|
|
2067
2067
|
}>(o: T): Omit<T, "signature">;
|
|
2068
2068
|
private withoutSignature;
|
|
2069
2069
|
/** Coverage tips (§4.7): canonical refs ∪ unexpired roots ∪ the HEAD target (detached commit; an unborn symref contributes nothing). */
|
|
2070
|
-
static coverageTips(refs:
|
|
2070
|
+
static coverageTips(refs: VaultRefMap, roots: VaultRetentionRoot[], headTarget: VaultHeadTarget): string[];
|
|
2071
2071
|
/**
|
|
2072
2072
|
* Build a checkpoint set (§4.7): manifest + packs + the owner-signed claim
|
|
2073
2073
|
* set, with the acceptance self-check (restore into an empty scratch, every
|
|
@@ -2076,11 +2076,11 @@ export declare class GitvaultVault {
|
|
|
2076
2076
|
*/
|
|
2077
2077
|
buildCheckpoint(input: {
|
|
2078
2078
|
generation: string;
|
|
2079
|
-
ref_state:
|
|
2080
|
-
retention_roots:
|
|
2081
|
-
}): Promise<
|
|
2079
|
+
ref_state: VaultRefState;
|
|
2080
|
+
retention_roots: VaultRetentionRoots;
|
|
2081
|
+
}): Promise<VaultBuiltCheckpoint>;
|
|
2082
2082
|
/** §4.7 acceptance: restore from the set ALONE into an empty scratch; every covered ref resolves; fsck connectivity; recompute the three commitments. */
|
|
2083
|
-
acceptCheckpoint(built:
|
|
2083
|
+
acceptCheckpoint(built: VaultBuiltCheckpoint, refState: VaultRefState, roots: VaultRetentionRoots): Promise<void>;
|
|
2084
2084
|
/**
|
|
2085
2085
|
* The §4.7 acceptance run against a checkpoint ALREADY IN STORAGE — the
|
|
2086
2086
|
* restore-and-verify pass a `verifier_receipt` attests (§7.3).
|
|
@@ -2092,7 +2092,7 @@ export declare class GitvaultVault {
|
|
|
2092
2092
|
* must be able to carry as `false` — turning it into an exception would make
|
|
2093
2093
|
* an honest negative attestation impossible to produce.
|
|
2094
2094
|
*/
|
|
2095
|
-
verifyStoredCheckpoint(head:
|
|
2095
|
+
verifyStoredCheckpoint(head: VaultHead, headSha256: string): Promise<VaultStoredCheckpointAttestation>;
|
|
2096
2096
|
/**
|
|
2097
2097
|
* The whole verified chain, newest-first walk returned oldest-first, each
|
|
2098
2098
|
* head paired with its checkpoint claim set (`null` when it bears none).
|
|
@@ -2104,18 +2104,18 @@ export declare class GitvaultVault {
|
|
|
2104
2104
|
* trusted from a listing.
|
|
2105
2105
|
*/
|
|
2106
2106
|
chainEntries(): Promise<Array<{
|
|
2107
|
-
head:
|
|
2107
|
+
head: VaultHead;
|
|
2108
2108
|
head_sha256: string;
|
|
2109
|
-
claim_set:
|
|
2109
|
+
claim_set: VaultCheckpointClaimSet | null;
|
|
2110
2110
|
}>>;
|
|
2111
2111
|
/**
|
|
2112
|
-
*
|
|
2112
|
+
* vault-byo-primary-bucket task 3.2 — resolve (once, cached) this
|
|
2113
2113
|
* machine's local BYO write config for THIS vault. `null` when none is
|
|
2114
2114
|
* configured locally — either because this is an ordinary managed vault
|
|
2115
2115
|
* (the common case; deliberately never confirmed with a network call, so
|
|
2116
2116
|
* a managed vault's push pays zero extra round trips), or because this
|
|
2117
2117
|
* machine has not been configured to write a BYO vault it nonetheless
|
|
2118
|
-
* belongs to (surfaced downstream as `
|
|
2118
|
+
* belongs to (surfaced downstream as `VAULT_BYO_BUCKET_WRITE_REFUSED`
|
|
2119
2119
|
* when the session actually names a `put: null` object with no target).
|
|
2120
2120
|
*/
|
|
2121
2121
|
private resolveByoWriteTarget;
|
|
@@ -2135,7 +2135,7 @@ export declare class GitvaultVault {
|
|
|
2135
2135
|
* retry always re-materializes from storage, exactly as when no base is
|
|
2136
2136
|
* supplied.
|
|
2137
2137
|
*/
|
|
2138
|
-
push(options:
|
|
2138
|
+
push(options: VaultPushOptions): Promise<VaultPublishResult>;
|
|
2139
2139
|
/**
|
|
2140
2140
|
* A REAL preview of what {@link push} would publish
|
|
2141
2141
|
* — runs the SAME local pipeline `push` runs (materialize → evaluate →
|
|
@@ -2151,11 +2151,11 @@ export declare class GitvaultVault {
|
|
|
2151
2151
|
*
|
|
2152
2152
|
* Never retries and never allocates: an unallocated vault has no `repo_id`
|
|
2153
2153
|
* (hence no encryption key) to preview a push against at all — callers
|
|
2154
|
-
* resolve the vault READ-ONLY first (see `
|
|
2155
|
-
* `../namespaces/
|
|
2154
|
+
* resolve the vault READ-ONLY first (see `Repos.planCapture` in
|
|
2155
|
+
* `../namespaces/repos.js`, which reports `allocation_needed: true` in
|
|
2156
2156
|
* that case instead of calling this method).
|
|
2157
2157
|
*/
|
|
2158
|
-
planPush(options:
|
|
2158
|
+
planPush(options: VaultPushOptions): Promise<VaultPushPlan>;
|
|
2159
2159
|
/**
|
|
2160
2160
|
* Publish an `ordinary_push` checkpoint-bearing head that changes NO ref (the
|
|
2161
2161
|
* canonical map and HEAD target are carried forward). With a cutoff the head
|
|
@@ -2170,14 +2170,14 @@ export declare class GitvaultVault {
|
|
|
2170
2170
|
* `prepared_at` alone would shorten the lane, which the protocol's own
|
|
2171
2171
|
* delayed-PUT vector calls out as the naive implementation.
|
|
2172
2172
|
*
|
|
2173
|
-
* This is NOT `run402
|
|
2173
|
+
* This is NOT `run402 repos gc`: the §7.2 maintenance CYCLE (purpose
|
|
2174
2174
|
* `maintenance_cycle`, C1/C2 roles, stage claim sets, prune intents, `R2_cap`
|
|
2175
2175
|
* accounting) is a separate protocol under compact authority, and gets its own
|
|
2176
2176
|
* method when it ships.
|
|
2177
2177
|
*/
|
|
2178
2178
|
publishCheckpoint(options?: {
|
|
2179
|
-
cutoff?:
|
|
2180
|
-
}): Promise<
|
|
2179
|
+
cutoff?: VaultCutoffOptions | false;
|
|
2180
|
+
}): Promise<VaultPublishResult>;
|
|
2181
2181
|
/** Request a `retention_cutoff` ticket and check it binds THIS base head (and the service key, when one is pinned). */
|
|
2182
2182
|
private issueRetentionCutoff;
|
|
2183
2183
|
/**
|
|
@@ -2216,7 +2216,7 @@ export declare class GitvaultVault {
|
|
|
2216
2216
|
*/
|
|
2217
2217
|
private loadEffectivePinManifest;
|
|
2218
2218
|
/**
|
|
2219
|
-
* Local-cache short-circuit (see {@link
|
|
2219
|
+
* Local-cache short-circuit (see {@link VaultRepoFile.known_pin_manifest}'s
|
|
2220
2220
|
* own doc comment for why this is safe): a manifest THIS keystore itself
|
|
2221
2221
|
* just built, signed, and admitted is resolved from the on-disk cache
|
|
2222
2222
|
* instead of a network `object-reads` round trip — same return shape,
|
|
@@ -2265,7 +2265,7 @@ export declare class GitvaultVault {
|
|
|
2265
2265
|
* **This is an ORDINARY admission (`transition: null`) and is therefore
|
|
2266
2266
|
* itself refused `EPOCH_ROTATION_REQUIRED` while a migration/revocation/
|
|
2267
2267
|
* exposure condition is outstanding on this vault (D193) — the exact
|
|
2268
|
-
* deadlock the incident behind {@link
|
|
2268
|
+
* deadlock the incident behind {@link Vault.rotateEpoch}'s
|
|
2269
2269
|
* `pending_confirmations` parameter closes.** When this vault is in that
|
|
2270
2270
|
* state, fold the receipt into `rotateEpoch({..., pending_confirmations:
|
|
2271
2271
|
* [{principal_id, ek_fingerprint, receipt}]})` instead of calling this
|
|
@@ -2276,8 +2276,8 @@ export declare class GitvaultVault {
|
|
|
2276
2276
|
principal_id: string;
|
|
2277
2277
|
ek_fingerprint: string;
|
|
2278
2278
|
confirmed_by: "operator_confirmation";
|
|
2279
|
-
receipt:
|
|
2280
|
-
}): Promise<
|
|
2279
|
+
receipt: VaultRecipientConfirmationReceipt;
|
|
2280
|
+
}): Promise<VaultPublishResult>;
|
|
2281
2281
|
/**
|
|
2282
2282
|
* Drive one epoch rotation to a committed head (D193-D203). This is the
|
|
2283
2283
|
* producer's obligations in full: sample a FRESH `K_e` independent of
|
|
@@ -2296,17 +2296,17 @@ export declare class GitvaultVault {
|
|
|
2296
2296
|
*
|
|
2297
2297
|
* **`recipient_state_version`/`recipient_revocation_version` are REQUIRED
|
|
2298
2298
|
* inputs, not discovered here.** The gateway exposes NO general read route
|
|
2299
|
-
* for `internal.
|
|
2299
|
+
* for `internal.vault_recipient_state_counters` (D194) — the ONLY
|
|
2300
2300
|
* client-visible read of these two org-scoped counters today is the
|
|
2301
2301
|
* response of `POST …/recipients/:principal_id/key-revocation`
|
|
2302
|
-
* ({@link
|
|
2302
|
+
* ({@link VaultTransport.declareRecipientKeyRevoked}), which is why
|
|
2303
2303
|
* {@link rotateEpochForKeyRevocation} (below) is the one fully
|
|
2304
2304
|
* self-contained entry point. For `member_removed` / `elective_rekey` /
|
|
2305
2305
|
* `epoch_secret_exposed`, a caller that does not already know the current
|
|
2306
2306
|
* counter pair cannot discover it from any shipped gateway route — this
|
|
2307
2307
|
* is a confirmed gap in the live gateway (verified against
|
|
2308
|
-
* `packages/gateway/src/services/
|
|
2309
|
-
* every `routes/
|
|
2308
|
+
* `packages/gateway/src/services/vault/reads.ts:getVaultRecord` and
|
|
2309
|
+
* every `routes/vault*.ts` handler, not inferred), not a client
|
|
2310
2310
|
* limitation this SDK can work around. Passing a stale/guessed pair fails
|
|
2311
2311
|
* safely: the admission fence's D194 frozen-counter comparison refuses
|
|
2312
2312
|
* `RECIPIENT_SET_MISMATCH` rather than silently canonizing against wrong
|
|
@@ -2329,7 +2329,7 @@ export declare class GitvaultVault {
|
|
|
2329
2329
|
* PREDECESSOR manifest, unchanged. They land in
|
|
2330
2330
|
* `excluded_unconfirmed_principal_ids` here (same as without folding) and
|
|
2331
2331
|
* become eligible starting at the NEXT rotation, once this manifest is
|
|
2332
|
-
* the admitted predecessor. See {@link
|
|
2332
|
+
* the admitted predecessor. See {@link VaultRotationResult.pin_manifest_published}.
|
|
2333
2333
|
*
|
|
2334
2334
|
* **Honest residual — this does not rescue a vault with ZERO ever-
|
|
2335
2335
|
* confirmed principals.** If `included` would be empty even with the
|
|
@@ -2344,7 +2344,7 @@ export declare class GitvaultVault {
|
|
|
2344
2344
|
* over) and needs an operator-side decision, not a client workaround.
|
|
2345
2345
|
*/
|
|
2346
2346
|
rotateEpoch(options: {
|
|
2347
|
-
reason:
|
|
2347
|
+
reason: VaultRotationReason;
|
|
2348
2348
|
recipient_state_version: string;
|
|
2349
2349
|
recipient_revocation_version: string;
|
|
2350
2350
|
client_idempotency_key?: string;
|
|
@@ -2352,10 +2352,10 @@ export declare class GitvaultVault {
|
|
|
2352
2352
|
pending_confirmations?: {
|
|
2353
2353
|
principal_id: string;
|
|
2354
2354
|
ek_fingerprint: string;
|
|
2355
|
-
receipt:
|
|
2355
|
+
receipt: VaultRecipientConfirmationReceipt;
|
|
2356
2356
|
}[];
|
|
2357
2357
|
/**
|
|
2358
|
-
*
|
|
2358
|
+
* vault-multi-writer (task 5.9, D7/D228) — an outstanding
|
|
2359
2359
|
* gateway-blocked writer set (`ineligible_members`, checked fresh on
|
|
2360
2360
|
* every call — see the `writer_set_update` fold-in below) is ALWAYS
|
|
2361
2361
|
* folded into this rotation automatically; this flag is the EXPLICIT
|
|
@@ -2367,22 +2367,22 @@ export declare class GitvaultVault {
|
|
|
2367
2367
|
* it widens nothing beyond that one specific, named exception.
|
|
2368
2368
|
*/
|
|
2369
2369
|
force_empty_writer_set?: boolean;
|
|
2370
|
-
}): Promise<
|
|
2370
|
+
}): Promise<VaultRotationResult>;
|
|
2371
2371
|
/**
|
|
2372
2372
|
* The writer-capable rotation that completes an org membership removal
|
|
2373
|
-
* (
|
|
2373
|
+
* (vault-multi-writer D6: "`member_removed` keeps its automatic
|
|
2374
2374
|
* writer-capable path"). The removal itself already advanced the org's
|
|
2375
2375
|
* D194 counters and flipped the member to `pending_removal`, so there is
|
|
2376
2376
|
* nothing to declare: read the counters off the envelope-recipients read
|
|
2377
2377
|
* (the same read the H-partition uses) and rotate under
|
|
2378
2378
|
* `reason:"member_removed"`, which needs `gitvault.writer` only — any
|
|
2379
2379
|
* surviving writer can run it, no owner step-up. Refuses
|
|
2380
|
-
* `
|
|
2380
|
+
* `VAULT_ROTATION_COUNTERS_UNAVAILABLE` on a gateway that does not yet
|
|
2381
2381
|
* carry the counters on that read.
|
|
2382
2382
|
*/
|
|
2383
2383
|
rotateEpochForMemberRemoval(options?: {
|
|
2384
2384
|
client_idempotency_key?: string;
|
|
2385
|
-
}): Promise<
|
|
2385
|
+
}): Promise<VaultRotationResult>;
|
|
2386
2386
|
/**
|
|
2387
2387
|
* The ONE fully self-contained rotation entry point: declares
|
|
2388
2388
|
* `reason:"recipient_key_revoked"` (owner + step-up) for `principal_id`,
|
|
@@ -2391,7 +2391,7 @@ export declare class GitvaultVault {
|
|
|
2391
2391
|
*/
|
|
2392
2392
|
rotateEpochForKeyRevocation(principalId: string, options?: {
|
|
2393
2393
|
client_idempotency_key?: string;
|
|
2394
|
-
}): Promise<
|
|
2394
|
+
}): Promise<VaultRotationResult>;
|
|
2395
2395
|
/**
|
|
2396
2396
|
* Submit a REF-NEUTRAL `add_writer_key{authorization.kind:"handoff"}`
|
|
2397
2397
|
* activation head — no ref/checkpoint/repair changes ride it (protocol
|
|
@@ -2428,13 +2428,13 @@ export declare class GitvaultVault {
|
|
|
2428
2428
|
acceptance: Record<string, unknown>;
|
|
2429
2429
|
}): Promise<{
|
|
2430
2430
|
outcome: "activated";
|
|
2431
|
-
result:
|
|
2431
|
+
result: VaultPublishResult;
|
|
2432
2432
|
} | {
|
|
2433
2433
|
outcome: "already_admitted";
|
|
2434
2434
|
generation: string;
|
|
2435
2435
|
}>;
|
|
2436
2436
|
/**
|
|
2437
|
-
*
|
|
2437
|
+
* vault-multi-writer (task 5.7) — the "writer"-door twin of {@link
|
|
2438
2438
|
* submitWriterActivationHead}: an ALREADY-ACTIVE writer (this vault
|
|
2439
2439
|
* session's own key) admits `input`, an eligible org member with a
|
|
2440
2440
|
* published signing key but no writer standing yet, via a fresh
|
|
@@ -2444,8 +2444,8 @@ export declare class GitvaultVault {
|
|
|
2444
2444
|
* branch), re-verified admission-side by `checkTransitionAdmissible`.
|
|
2445
2445
|
* Task 5.8 adds the SAME local pre-check every other head-signing path
|
|
2446
2446
|
* gets: if THIS session's own key is not (or is no longer) an active
|
|
2447
|
-
* writer, refuse EARLY and LOCALLY (`
|
|
2448
|
-
* `
|
|
2447
|
+
* writer, refuse EARLY and LOCALLY (`VAULT_WRITER_NOT_ADMITTED` /
|
|
2448
|
+
* `VAULT_WRITER_REMOVED`) rather than let the head reach the gateway
|
|
2449
2449
|
* only to be refused there — redundant with `reconcileWriterAdmissions`'s
|
|
2450
2450
|
* own upfront gate for that caller, but this method is public and a
|
|
2451
2451
|
* direct caller should get the same fast, specific refusal.
|
|
@@ -2456,13 +2456,13 @@ export declare class GitvaultVault {
|
|
|
2456
2456
|
addedPrincipalId: string;
|
|
2457
2457
|
}): Promise<{
|
|
2458
2458
|
outcome: "activated";
|
|
2459
|
-
result:
|
|
2459
|
+
result: VaultPublishResult;
|
|
2460
2460
|
} | {
|
|
2461
2461
|
outcome: "already_admitted";
|
|
2462
2462
|
generation: string;
|
|
2463
2463
|
}>;
|
|
2464
2464
|
/**
|
|
2465
|
-
*
|
|
2465
|
+
* vault-multi-writer (task 5.7) — the vault's OWN writer-admission
|
|
2466
2466
|
* reconcile: reads `pending_writers[]` off the vault record (eligible org
|
|
2467
2467
|
* members with no writer standing yet), resolves each candidate's
|
|
2468
2468
|
* published signing key off the org's encryption-key directory (the SAME
|
|
@@ -2480,7 +2480,7 @@ export declare class GitvaultVault {
|
|
|
2480
2480
|
* a session that reached this call already pushed successfully as an
|
|
2481
2481
|
* active writer in every wired call site (push/snapshot/deploy) OR is a
|
|
2482
2482
|
* member that simply is not one yet (session-start/read) — the SAME
|
|
2483
|
-
* "not yet admitted" case {@link
|
|
2483
|
+
* "not yet admitted" case {@link Repos.capture}'s own pre-push check
|
|
2484
2484
|
* (task 5.8) names, not a new refusal shape. Returns `{eligible: false}`
|
|
2485
2485
|
* with every other field empty (never throws) for that case: every OTHER
|
|
2486
2486
|
* `pending_writers[]` entry would fail identically, so there is nothing
|
|
@@ -2489,7 +2489,7 @@ export declare class GitvaultVault {
|
|
|
2489
2489
|
* (`eligible: true`, still all empty), which matters to a caller trying
|
|
2490
2490
|
* to explain an all-empty result to a human.
|
|
2491
2491
|
*/
|
|
2492
|
-
reconcileWriterAdmissions(): Promise<
|
|
2492
|
+
reconcileWriterAdmissions(): Promise<VaultReconcileWriterAdmissionsResult>;
|
|
2493
2493
|
/**
|
|
2494
2494
|
* Publish a repair head over `base_generation` (§4.3): superseded tips that
|
|
2495
2495
|
* the repaired state no longer reaches enter the retention-root map with
|
|
@@ -2499,8 +2499,8 @@ export declare class GitvaultVault {
|
|
|
2499
2499
|
*/
|
|
2500
2500
|
repair(input: {
|
|
2501
2501
|
base_generation: string;
|
|
2502
|
-
reason:
|
|
2503
|
-
}): Promise<
|
|
2502
|
+
reason: VaultRepairDescriptor["reason"];
|
|
2503
|
+
}): Promise<VaultPublishResult>;
|
|
2504
2504
|
/** Heads `base..newest` (already chain-verified by `verifyToNewest`) re-read + hash-checked from storage. */
|
|
2505
2505
|
/**
|
|
2506
2506
|
* Re-read heads `baseGeneration..newest` and hash-check each against the
|
|
@@ -2518,10 +2518,10 @@ export declare class GitvaultVault {
|
|
|
2518
2518
|
* `targetRepoDir` (an initialized repository), then verify every canonical
|
|
2519
2519
|
* ref + the HEAD target resolves. Returns the materialized refs.
|
|
2520
2520
|
*
|
|
2521
|
-
* Design D5 (
|
|
2521
|
+
* Design D5 (vault-client-round-trips): incremental above the local
|
|
2522
2522
|
* `restored_through` marker (this target directory's own local git
|
|
2523
|
-
* config, read/written by {@link
|
|
2524
|
-
*
|
|
2523
|
+
* config, read/written by {@link readVaultRestoreMarker}/{@link
|
|
2524
|
+
* writeVaultRestoreMarker}) — replaying only the WAL packs of
|
|
2525
2525
|
* generations above it — WHEN the walk from newest back to the marker is
|
|
2526
2526
|
* plain WAL the entire way. The moment that walk crosses a
|
|
2527
2527
|
* checkpoint-bearing, repair, or transition head (checked BEFORE
|
|
@@ -2533,16 +2533,16 @@ export declare class GitvaultVault {
|
|
|
2533
2533
|
* paths; the marker only advances after they both succeed.
|
|
2534
2534
|
*/
|
|
2535
2535
|
restoreObjectsInto(targetRepoDir: string, reuse?: {
|
|
2536
|
-
marker:
|
|
2537
|
-
state:
|
|
2536
|
+
marker: VaultRestoreMarker | null;
|
|
2537
|
+
state: VaultMaterializedState;
|
|
2538
2538
|
}): Promise<{
|
|
2539
|
-
refs:
|
|
2540
|
-
head_target:
|
|
2539
|
+
refs: VaultRefMap;
|
|
2540
|
+
head_target: VaultHeadTarget;
|
|
2541
2541
|
generation: string;
|
|
2542
|
-
retained_refs:
|
|
2542
|
+
retained_refs: VaultRetainedRefsReconcileResult;
|
|
2543
2543
|
}>;
|
|
2544
2544
|
/**
|
|
2545
|
-
* The shared restore tail (
|
|
2545
|
+
* The shared restore tail (vault-restore-recipe): apply `heads`'
|
|
2546
2546
|
* checkpoint (if any) + WAL packs into `targetRepoDir`, verify §4.7
|
|
2547
2547
|
* coverage, reconcile retained refs, and advance the marker — IDENTICALLY
|
|
2548
2548
|
* whether `heads` came from {@link restoreObjectsInto}'s own backward walk
|
|
@@ -2562,10 +2562,10 @@ export declare class GitvaultVault {
|
|
|
2562
2562
|
* packs (`stateDeltaPacks` never carries checkpoint packs — a delta span
|
|
2563
2563
|
* never crosses a checkpoint boundary). Both are `null` on the ordinary
|
|
2564
2564
|
* walk path, in which case every line below is byte-identical to the
|
|
2565
|
-
* pre-
|
|
2565
|
+
* pre-vault-restore-recipe shape.
|
|
2566
2566
|
*/
|
|
2567
2567
|
/**
|
|
2568
|
-
*
|
|
2568
|
+
* vault-multi-writer (rev 47): the key a head's own checkpoint claim set
|
|
2569
2569
|
* and carriers were signed under — the head's writer, resolved against the
|
|
2570
2570
|
* keystore's persisted `writer_set_pin` (maintained by the chain walk that
|
|
2571
2571
|
* always precedes a restore), falling back to `fallback` (the genesis
|
|
@@ -2580,7 +2580,7 @@ export declare class GitvaultVault {
|
|
|
2580
2580
|
* `newest.epoch_keys_hex[epoch]`, decoded — the D194 per-carrying-head key
|
|
2581
2581
|
* lookup shared by {@link applyRestoreHeads} and {@link verifyRestorePlan}.
|
|
2582
2582
|
* `newest.epoch_keys_hex` is the FULL map `materialize()` resolved
|
|
2583
|
-
* (throwing `
|
|
2583
|
+
* (throwing `VAULT_EPOCH_NOT_OPENABLE` fail-closed if any needed epoch
|
|
2584
2584
|
* could not be opened), so every lookup through this helper is guaranteed
|
|
2585
2585
|
* present.
|
|
2586
2586
|
*/
|
|
@@ -2607,7 +2607,7 @@ export declare class GitvaultVault {
|
|
|
2607
2607
|
*/
|
|
2608
2608
|
private verifyRestorePlan;
|
|
2609
2609
|
/**
|
|
2610
|
-
* Consume a stashed restore plan (
|
|
2610
|
+
* Consume a stashed restore plan (vault-restore-recipe design D1-D6):
|
|
2611
2611
|
* verify it ({@link verifyRestorePlan}) and, on success, apply it via the
|
|
2612
2612
|
* SAME shared tail the backward walk uses ({@link applyRestoreHeads}) —
|
|
2613
2613
|
* `null` on absence or ANY verification failure, the caller's cue to run
|
|
@@ -2617,16 +2617,16 @@ export declare class GitvaultVault {
|
|
|
2617
2617
|
* `verifyRestorePlan` itself).
|
|
2618
2618
|
*/
|
|
2619
2619
|
private tryConsumeRestorePlan;
|
|
2620
|
-
/** Thin passthrough to the transport — see {@link
|
|
2621
|
-
openCompactionGrant(): Promise<
|
|
2622
|
-
/** Thin passthrough to the transport — see {@link
|
|
2620
|
+
/** Thin passthrough to the transport — see {@link VaultTransport.openCompactionGrant}. */
|
|
2621
|
+
openCompactionGrant(): Promise<VaultCompactionGrant>;
|
|
2622
|
+
/** Thin passthrough to the transport — see {@link VaultTransport.closeCompactionGrant}. Always safe best-effort; never throws by construction of the route (idempotent). */
|
|
2623
2623
|
closeCompactionGrant(): Promise<{
|
|
2624
2624
|
closed: boolean;
|
|
2625
2625
|
}>;
|
|
2626
2626
|
}
|
|
2627
2627
|
/** §4.7 cross-field equality: covers_through agree; the claim set's ordered pack ids/hashes/sizes/total equal the manifest's (shared stored fields only). */
|
|
2628
|
-
export declare function checkClaimSetEquality(claimSet:
|
|
2628
|
+
export declare function checkClaimSetEquality(claimSet: VaultCheckpointClaimSet, manifest: VaultCheckpointManifest, headCoversThrough: string): void;
|
|
2629
2629
|
/** Convenience for the deploy lane: the §6.5 capture binding. */
|
|
2630
|
-
export declare function captureBinding(captureId: string, applyPlanSha256: string | null, snapshotOidHmac: string):
|
|
2631
|
-
export type {
|
|
2632
|
-
//# sourceMappingURL=
|
|
2630
|
+
export declare function captureBinding(captureId: string, applyPlanSha256: string | null, snapshotOidHmac: string): VaultCaptureBinding;
|
|
2631
|
+
export type { VaultRefUpdate };
|
|
2632
|
+
//# sourceMappingURL=vault-publication.d.ts.map
|