@narumitw/pi-sync-daemon 0.6.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +17 -3
  3. package/dist/consent.js +26 -1
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +39 -13
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/paths.js +1 -1
  24. package/dist/engine/settings/config-file.d.ts +9 -2
  25. package/dist/engine/settings/config-file.js +126 -28
  26. package/dist/engine/settings/config.d.ts +5 -4
  27. package/dist/engine/settings/config.js +114 -13
  28. package/dist/engine/settings/settings-management.js +34 -32
  29. package/dist/engine/settings/settings-types.d.ts +40 -5
  30. package/dist/engine/settings/settings-validation.js +52 -24
  31. package/dist/engine/snapshot/session-paths.d.ts +6 -4
  32. package/dist/engine/snapshot/session-paths.js +84 -15
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +7 -8
  34. package/dist/engine/snapshot/snapshot-apply.js +107 -21
  35. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  36. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  37. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  38. package/dist/engine/snapshot/snapshot-codec.js +15 -7
  39. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  40. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +9 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +239 -24
  43. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  45. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  46. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  47. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  48. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  49. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +39 -0
  50. package/dist/engine/snapshot/snapshot-transaction-images.js +387 -0
  51. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +73 -0
  52. package/dist/engine/snapshot/snapshot-transaction-policy.js +276 -0
  53. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  54. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  55. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  56. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  57. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -11
  58. package/dist/engine/snapshot/snapshot-transaction.js +390 -364
  59. package/dist/engine/snapshot/snapshot-types.d.ts +47 -2
  60. package/dist/engine/snapshot/snapshot-types.js +9 -1
  61. package/dist/engine/snapshot/snapshot.d.ts +22 -3
  62. package/dist/engine/snapshot/snapshot.js +357 -43
  63. package/dist/engine/state/merge-baseline-store.js +20 -9
  64. package/dist/engine/state/state-types.d.ts +3 -0
  65. package/dist/engine/sync/apply-review.d.ts +3 -3
  66. package/dist/engine/sync/apply-review.js +5 -4
  67. package/dist/engine/sync/continuous-sync.js +37 -12
  68. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  69. package/dist/engine/sync/continuous-watch.js +90 -15
  70. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  71. package/dist/engine/sync/exclude-policy.js +8 -1
  72. package/dist/engine/sync/initialization.js +9 -4
  73. package/dist/engine/sync/local-fields.d.ts +3 -1
  74. package/dist/engine/sync/local-fields.js +88 -8
  75. package/dist/engine/sync/merge-apply.js +190 -47
  76. package/dist/engine/sync/merge-journal.d.ts +18 -4
  77. package/dist/engine/sync/merge-journal.js +126 -10
  78. package/dist/engine/sync/merged-sync.d.ts +1 -1
  79. package/dist/engine/sync/merged-sync.js +124 -68
  80. package/dist/engine/sync/partial-progress.js +5 -3
  81. package/dist/engine/sync/remote-snapshot.d.ts +10 -2
  82. package/dist/engine/sync/remote-snapshot.js +59 -17
  83. package/dist/engine/sync/session-push.js +7 -6
  84. package/dist/engine/sync/sync-decision.d.ts +4 -0
  85. package/dist/engine/sync/sync-decision.js +17 -2
  86. package/dist/engine/sync/sync-inspection.js +8 -6
  87. package/dist/engine/sync/sync-mutations.d.ts +10 -2
  88. package/dist/engine/sync/sync-mutations.js +245 -101
  89. package/dist/engine/sync/sync-policy.d.ts +36 -10
  90. package/dist/engine/sync/sync-policy.js +285 -20
  91. package/dist/engine/sync/sync-queries.js +49 -32
  92. package/dist/engine/sync/sync-state.d.ts +11 -0
  93. package/dist/engine/sync/sync-state.js +42 -5
  94. package/dist/engine/ui/sync-format.js +22 -7
  95. package/dist/engine-service.js +24 -2
  96. package/docs/architecture.md +28 -0
  97. package/package.json +2 -1
@@ -0,0 +1,276 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { DEFAULT_IGNORE_FILENAME, validateIgnoreFilename } from "../ignore/ignore-source.js";
4
+ import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
5
+ import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
6
+ import { mergePathIdentity } from "../sync/file-merge-planner.js";
7
+ import { portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
8
+ import { agentDir } from "./session-paths.js";
9
+ import { isCaseReplacement } from "./snapshot-case-replacement.js";
10
+ import { sessionStorageRoot } from "./snapshot-paths.js";
11
+ import { validateSessionRootTransition } from "./snapshot-root-transition.js";
12
+ export const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
13
+ export const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
14
+ export const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
15
+ export const IGNORE_POLICY_JOURNAL_VERSION = 11;
16
+ export function isScopedJournal(journal) {
17
+ return [
18
+ LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
19
+ FIXED_WORKSPACE_JOURNAL_VERSION,
20
+ AGENT_DIRECTORY_JOURNAL_VERSION,
21
+ IGNORE_POLICY_JOURNAL_VERSION,
22
+ ].includes(journal.version);
23
+ }
24
+ function usesSlottedWorkspace(journal) {
25
+ return journal.version === AGENT_DIRECTORY_JOURNAL_VERSION || journal.version === IGNORE_POLICY_JOURNAL_VERSION;
26
+ }
27
+ export function isRecoveryStageId(value) {
28
+ return (typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value));
29
+ }
30
+ export function isScopedIdentity(value) {
31
+ return typeof value === "string" && /^\d{1,20}:[1-9]\d{0,19}:\d{1,20}$/u.test(value);
32
+ }
33
+ export function ignoreSourceBinding(policy) {
34
+ const filename = validateIgnoreFilename(policy.filename);
35
+ if (typeof policy.sourceDigest !== "string" ||
36
+ policy.sourceDigest.length !== 64 ||
37
+ !/^[0-9a-f]{64}$/u.test(policy.sourceDigest))
38
+ throw new Error("Invalid ignore policy source digest.");
39
+ return {
40
+ version: 1,
41
+ filename,
42
+ sourceDigest: policy.sourceDigest,
43
+ reservedNames: [
44
+ ...new Set([DEFAULT_IGNORE_FILENAME, filename, ...policy.reservedNames].map((name) => validateIgnoreFilename(name).toLowerCase())),
45
+ ].sort(),
46
+ };
47
+ }
48
+ function sameIgnoreSource(left, right) {
49
+ return (left.version === right.version &&
50
+ left.filename === right.filename &&
51
+ left.sourceDigest === right.sourceDigest &&
52
+ left.reservedNames.length === right.reservedNames.length &&
53
+ left.reservedNames.every((name, index) => name === right.reservedNames[index]));
54
+ }
55
+ export class StaleIgnorePolicyError extends Error {
56
+ }
57
+ export function ignorePolicyValidator(options) {
58
+ if (!options.ignorePolicy && options.version !== 4)
59
+ return;
60
+ const validateIgnorePolicy = options.validateIgnorePolicy;
61
+ if (!options.ignorePolicy || options.scope !== "agent-directory" || typeof validateIgnorePolicy !== "function")
62
+ throw new Error("Ignore-file mutation requires an explicit local policy and a freshness check.");
63
+ return async () => {
64
+ options.validateMutation?.();
65
+ options.signal?.throwIfAborted();
66
+ try {
67
+ const pending = validateIgnorePolicy();
68
+ if (typeof pending?.then !== "function")
69
+ throw new Error("The ignore policy freshness check must be async.");
70
+ await pending;
71
+ }
72
+ catch (cause) {
73
+ throw new StaleIgnorePolicyError("Pi Sync ignore policy changed or could not be verified; preserve any transaction evidence and reopen the review.", { cause });
74
+ }
75
+ options.validateMutation?.();
76
+ options.signal?.throwIfAborted();
77
+ };
78
+ }
79
+ export function validateJournalPolicy(journal) {
80
+ if (!journal || (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal)))
81
+ throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
82
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION) {
83
+ const binding = journal.ignoreSource;
84
+ try {
85
+ if (journal.exclude === undefined &&
86
+ portableSnapshotSelection(journal.selection).version === 4 &&
87
+ binding &&
88
+ Array.isArray(binding.reservedNames) &&
89
+ Object.keys(binding).length === 4 &&
90
+ sameIgnoreSource(binding, ignoreSourceBinding(binding)))
91
+ return;
92
+ }
93
+ catch (cause) {
94
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.", { cause });
95
+ }
96
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.");
97
+ }
98
+ if (journal.ignoreSource !== undefined)
99
+ throw new Error("Unsupported transaction ignore source binding; preserve evidence for review.");
100
+ if (isScopedJournal(journal)) {
101
+ if (journal.exclude !== undefined || portableSnapshotSelection(journal.selection).version !== 3)
102
+ throw new Error("Invalid agent-directory transaction policy; preserve evidence.");
103
+ }
104
+ else if (journal.selection !== undefined) {
105
+ throw new Error("Unsupported pi-sync transaction journal policy; preserve evidence for review.");
106
+ }
107
+ if (journal.exclude !== undefined && !Array.isArray(journal.exclude))
108
+ throw new Error("Invalid transaction exclude policy; preserve evidence.");
109
+ normalizeSyncExclude(journal.exclude);
110
+ }
111
+ export function assertRecoveryPolicy(journal, options) {
112
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION || options.ignorePolicy || options.version === 4) {
113
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION &&
114
+ journal.ignoreSource &&
115
+ options.scope === "agent-directory" &&
116
+ options.ignorePolicy &&
117
+ sameIgnoreSource(journal.ignoreSource, ignoreSourceBinding(options.ignorePolicy)) &&
118
+ sameSnapshotSelection(journal.selection, selectionForSnapshot(undefined, undefined, options)))
119
+ return;
120
+ throw new Error("Pending transaction has a different ignore-file policy; preserve its backup for reviewed recovery.");
121
+ }
122
+ const directoryKey = syncDirectoryPolicyKey(journal.selection ?? {});
123
+ const effectiveDirectoryKey = syncDirectoryPolicyKey(options);
124
+ if (directoryKey !== undefined
125
+ ? directoryKey === effectiveDirectoryKey
126
+ : effectiveDirectoryKey === undefined && sameSyncExclude(journal.exclude, options.exclude))
127
+ return;
128
+ throw new Error("Pending transaction has a different exclude policy or directory scope; preserve its backup for reviewed recovery.");
129
+ }
130
+ export function validateJournal(directory, journal, sessionDir) {
131
+ validateJournalPolicy(journal);
132
+ const wholeDirectory = isScopedJournal(journal);
133
+ if (!Array.isArray(journal.entries) || journal.entries.length > 16_384)
134
+ throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
135
+ if (journal.completed !== undefined &&
136
+ ((!wholeDirectory && ![6, 7].includes(journal.version)) || journal.completed !== true))
137
+ throw new Error("Invalid transaction completion evidence.");
138
+ const root = path.resolve(agentDir());
139
+ if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
140
+ throw new Error("Transaction root no longer matches the Pi agent directory.");
141
+ if (journal.sessionRootTransition !== undefined) {
142
+ if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
143
+ throw new Error("Invalid session root-transition version.");
144
+ validateSessionRootTransition(journal.sessionRootTransition);
145
+ }
146
+ else if (journal.version === 7)
147
+ throw new Error("Missing session root-transition evidence.");
148
+ const trustedSessionRoot = sessionDir
149
+ ? path.resolve(sessionStorageRoot(root, sessionDir))
150
+ : path.join(root, "sessions");
151
+ if (wholeDirectory && journal.sessionRoot === undefined)
152
+ throw new Error("Missing agent-directory transaction session root evidence.");
153
+ if (journal.sessionRoot !== undefined &&
154
+ (typeof journal.sessionRoot !== "string" ||
155
+ !path.isAbsolute(journal.sessionRoot) ||
156
+ path.resolve(journal.sessionRoot) !== journal.sessionRoot ||
157
+ (!journal.completed &&
158
+ (wholeDirectory || transactionHasSessionTargets(journal)) &&
159
+ journal.sessionRoot !== trustedSessionRoot)))
160
+ throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
161
+ for (const entry of journal.entries) {
162
+ if (!entry ||
163
+ typeof entry.target !== "string" ||
164
+ !path.isAbsolute(entry.target) ||
165
+ path.resolve(entry.target) !== entry.target ||
166
+ typeof entry.backupName !== "string" ||
167
+ !/^\d+$/u.test(entry.backupName) ||
168
+ !["missing", "file", "directory", "symlink"].includes(entry.kind))
169
+ throw new Error("Invalid pi-sync transaction entry.");
170
+ assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
171
+ assertAllowedTarget(root, journal.sessionRoot, entry.target);
172
+ if (entry.afterTarget !== undefined &&
173
+ ((!wholeDirectory && ![5, 6, 7].includes(journal.version)) ||
174
+ typeof entry.afterTarget !== "string" ||
175
+ !isCaseReplacement(root, entry.target, entry.afterTarget) ||
176
+ path.resolve(entry.afterTarget) !== entry.afterTarget ||
177
+ entry.kind !== "file"))
178
+ throw new Error("Invalid transaction case replacement evidence.");
179
+ if (entry.afterTarget)
180
+ assertAllowedTarget(root, journal.sessionRoot, entry.afterTarget);
181
+ if (journal.version >= 2 &&
182
+ ((entry.beforeImage === undefined ? !journal.completed : typeof entry.beforeImage !== "string") ||
183
+ (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
184
+ (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
185
+ throw new Error("Invalid transaction postimage evidence.");
186
+ if (entry.recoveryStaged !== undefined &&
187
+ (typeof entry.recoveryStaged !== "boolean" || journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION))
188
+ throw new Error("Invalid recovery staging evidence.");
189
+ if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
190
+ throw new Error("Invalid transaction removal evidence.");
191
+ if (entry.replacementStarted !== undefined &&
192
+ (journal.version < 4 || typeof entry.replacementStarted !== "boolean"))
193
+ throw new Error("Invalid transaction replacement evidence.");
194
+ if (entry.removalPending && entry.replacementStarted)
195
+ throw new Error("Conflicting transaction replacement evidence.");
196
+ if ((entry.recoveryWorkspace !== undefined &&
197
+ (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
198
+ !isScopedIdentity(entry.recoveryWorkspace) ||
199
+ entry.recoveryStaged ||
200
+ !["file", "directory"].includes(entry.kind))) ||
201
+ (entry.recoveryWorkspaceId !== undefined &&
202
+ (!usesSlottedWorkspace(journal) ||
203
+ !entry.recoveryWorkspace ||
204
+ !isRecoveryStageId(entry.recoveryWorkspaceId))) ||
205
+ (entry.scopedRemoval !== undefined &&
206
+ (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
207
+ !entry.removalPending ||
208
+ !["before", "after"].includes(entry.scopedRemoval?.image) ||
209
+ !isScopedIdentity(entry.scopedRemoval?.identity) ||
210
+ (entry.scopedRemoval.image === "before"
211
+ ? !["file", "directory"].includes(entry.kind)
212
+ : entry.afterImage === "missing" && !entry.postFiles?.length))) ||
213
+ (entry.vacantInstall !== undefined &&
214
+ (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
215
+ !entry.recoveryWorkspace ||
216
+ !isScopedIdentity(entry.vacantInstall) ||
217
+ entry.removalPending ||
218
+ entry.replacementStarted)))
219
+ throw new Error("Invalid scoped transaction progress evidence.");
220
+ for (const file of entry.postFiles ?? []) {
221
+ if (typeof file.relative !== "string" ||
222
+ typeof file.image !== "string" ||
223
+ !isStrictlyInside(entry.target, path.resolve(entry.target, file.relative)))
224
+ throw new Error("Invalid transaction subtree evidence.");
225
+ }
226
+ }
227
+ }
228
+ export function transactionHasSessionTargets(journal) {
229
+ const root = path.resolve(agentDir());
230
+ return (Array.isArray(journal.entries) &&
231
+ journal.entries.some((entry) => typeof entry?.target === "string" &&
232
+ (!isPathInside(root, entry.target) ||
233
+ isPathInside(path.join(root, "sessions"), entry.target) ||
234
+ (typeof journal.sessionRoot === "string" && isPathInside(journal.sessionRoot, entry.target)))));
235
+ }
236
+ export function isStrictlyInside(root, target) {
237
+ return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
238
+ }
239
+ export function touchesProtectedTarget(target, protectedTargets) {
240
+ return protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
241
+ isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)));
242
+ }
243
+ export async function assertSafeParents(root, sessionRoot, target) {
244
+ assertAllowedTarget(root, sessionRoot, target);
245
+ const boundary = isPathInside(root, target) ? root : sessionRoot;
246
+ for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
247
+ if (path.dirname(parent) === parent)
248
+ throw new Error("Transaction parent did not reach its owned boundary.");
249
+ try {
250
+ const stat = await fs.lstat(parent);
251
+ if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
252
+ throw new Error("Unsafe transaction parent.");
253
+ }
254
+ catch (error) {
255
+ const code = error.code;
256
+ if (code !== "ENOENT" && code !== "ENOTDIR")
257
+ throw error;
258
+ }
259
+ }
260
+ }
261
+ export function assertAllowedTarget(root, sessionRoot, target) {
262
+ const resolved = path.resolve(target);
263
+ if (isStrictlyInside(root, resolved)) {
264
+ if (isDeniedPath(path.relative(root, resolved)))
265
+ throw new Error("Transaction targets denied private storage.");
266
+ assertWithinRoot(root, resolved);
267
+ return;
268
+ }
269
+ if (sessionRoot && isStrictlyInside(sessionRoot, resolved)) {
270
+ if (isDeniedPath(`sessions/${path.relative(sessionRoot, resolved)}`))
271
+ throw new Error("Transaction targets denied session storage.");
272
+ assertWithinRoot(sessionRoot, resolved);
273
+ return;
274
+ }
275
+ throw new Error("Transaction target is outside configured roots.");
276
+ }
@@ -0,0 +1,32 @@
1
+ import { type ScopedImage } from "./snapshot-transaction-images.js";
2
+ import { type TransactionEntry } from "./snapshot-transaction-policy.js";
3
+ interface Guards {
4
+ signal?: AbortSignal;
5
+ validateMutation?: () => void;
6
+ }
7
+ export declare function recoveryStagePath(directory: string, entry: TransactionEntry): string;
8
+ export declare function prepareLegacyRecoveryStage(directory: string, entry: TransactionEntry, options: Guards, persist: () => Promise<void>): Promise<string>;
9
+ export declare function assertNoUnclaimedLegacyStage(directory: string, entry: TransactionEntry, options: Guards): Promise<void>;
10
+ export declare function cleanScopedLegacyStage(directory: string, entry: TransactionEntry, options: Guards): Promise<void>;
11
+ export declare function inspectScopedRecoveryStage(directory: string, entry: TransactionEntry, options: Guards, requireStableWorkspace?: boolean): Promise<{
12
+ workspace: string;
13
+ backup: string;
14
+ source: ScopedImage;
15
+ payload: string;
16
+ image: ScopedImage;
17
+ scratch: string;
18
+ partial: {
19
+ kind: "file";
20
+ value: string;
21
+ stat: import("node:fs").BigIntStats;
22
+ } | {
23
+ kind: "missing";
24
+ value: "missing";
25
+ };
26
+ evidence: string;
27
+ container: string | undefined;
28
+ containerIdentity: string | undefined;
29
+ } | undefined>;
30
+ export declare function buildScopedRecoveryStage(directory: string, entry: TransactionEntry, options: Guards, persist: () => Promise<void>): Promise<void>;
31
+ export declare function cleanScopedWorkspace(directory: string, entry: TransactionEntry, options: Guards): Promise<void>;
32
+ export {};
@@ -0,0 +1,303 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { syncDirectory, writeJson } from "../state/json-file.js";
5
+ import { matchesScopedFilePrefix, ownedScopedSubset, readTransactionJournal, removeScopedImage, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
6
+ import { isRecoveryStageId, isScopedIdentity } from "./snapshot-transaction-policy.js";
7
+ function validate(options) {
8
+ options.validateMutation?.();
9
+ options.signal?.throwIfAborted();
10
+ }
11
+ function unrecognizedStage() {
12
+ throw new Error("Unrecognized recovery staging image; preserve evidence for review.");
13
+ }
14
+ export function recoveryStagePath(directory, entry) {
15
+ const token = createHash("sha256").update(directory).update("\\0").update(entry.backupName).digest("hex");
16
+ return path.join(path.dirname(entry.target), `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`);
17
+ }
18
+ export async function prepareLegacyRecoveryStage(directory, entry, options, persist) {
19
+ const temporary = recoveryStagePath(directory, entry);
20
+ if (!entry.recoveryStaged) {
21
+ try {
22
+ await fs.lstat(temporary);
23
+ throw new Error("Unowned recovery staging path; preserve evidence for review.");
24
+ }
25
+ catch (error) {
26
+ if (error.code !== "ENOENT")
27
+ throw error;
28
+ }
29
+ validate(options);
30
+ entry.recoveryStaged = true;
31
+ await persist();
32
+ validate(options);
33
+ }
34
+ return temporary;
35
+ }
36
+ export async function assertNoUnclaimedLegacyStage(directory, entry, options) {
37
+ if (entry.recoveryStaged)
38
+ return;
39
+ validate(options);
40
+ try {
41
+ await fs.lstat(recoveryStagePath(directory, entry));
42
+ }
43
+ catch (error) {
44
+ validate(options);
45
+ const code = error.code;
46
+ if (code === "ENOENT" || code === "ENOTDIR")
47
+ return;
48
+ throw error;
49
+ }
50
+ unrecognizedStage();
51
+ }
52
+ export async function cleanScopedLegacyStage(directory, entry, options) {
53
+ const temporary = recoveryStagePath(directory, entry);
54
+ const staged = await scopedTransactionImage(temporary, options);
55
+ if (staged.kind === "missing")
56
+ return;
57
+ if (staged.kind !== entry.kind || staged.value !== entry.beforeImage)
58
+ unrecognizedStage();
59
+ await removeScopedImage(temporary, staged, options);
60
+ await syncDirectory(path.dirname(temporary));
61
+ }
62
+ function workspacePath(directory, entry, slot = entry.recoveryWorkspaceId) {
63
+ const base = `${recoveryStagePath(directory, entry)}.workspace`;
64
+ return slot ? `${base}.${slot}` : base;
65
+ }
66
+ function scratchPath(workspace, slot) {
67
+ return `${workspace}.scratch.${slot}`;
68
+ }
69
+ async function existingDirectory(workspace, identity, options, requireStable = false) {
70
+ validate(options);
71
+ try {
72
+ const stat = await fs.lstat(workspace, { bigint: true });
73
+ validate(options);
74
+ if (!stat.isDirectory() || scopedIdentity(stat) !== identity)
75
+ unrecognizedStage();
76
+ if (requireStable)
77
+ stableScopedIdentity(workspace, stat);
78
+ return true;
79
+ }
80
+ catch (error) {
81
+ validate(options);
82
+ const code = error.code;
83
+ if (code === "ENOENT" || code === "ENOTDIR")
84
+ return false;
85
+ throw error;
86
+ }
87
+ }
88
+ function fileKey(relative) {
89
+ return createHash("sha256").update(relative).digest("hex");
90
+ }
91
+ function findFile(node, key, relative = "") {
92
+ if (node.kind === "file" && fileKey(relative) === key)
93
+ return [relative, node];
94
+ if (node.kind !== "directory")
95
+ return;
96
+ for (const [name, child] of node.children) {
97
+ const found = findFile(child, key, path.join(relative, name));
98
+ if (found)
99
+ return found;
100
+ }
101
+ }
102
+ const SCRATCH_EVIDENCE_BYTES = 1024;
103
+ function parseScratchEvidence(content) {
104
+ if (content === undefined)
105
+ return;
106
+ const saved = JSON.parse(content);
107
+ if (!saved ||
108
+ !isScopedIdentity(saved.identity) ||
109
+ typeof saved.file !== "string" ||
110
+ !/^[0-9a-f]{64}$/u.test(saved.file))
111
+ unrecognizedStage();
112
+ const { identity, file, slot, container } = saved;
113
+ if (slot === undefined && container === undefined)
114
+ return { identity, file };
115
+ if (!isRecoveryStageId(slot) || !isScopedIdentity(container))
116
+ unrecognizedStage();
117
+ return { identity, file, slot, container };
118
+ }
119
+ async function createPrivateStageDirectory(directory, options) {
120
+ validate(options);
121
+ await fs.mkdir(directory, { mode: 0o700 });
122
+ validate(options);
123
+ const stat = await fs.lstat(directory, { bigint: true });
124
+ validate(options);
125
+ if (!stat.isDirectory())
126
+ unrecognizedStage();
127
+ return stableScopedIdentity(directory, stat);
128
+ }
129
+ async function removeScratchContainer(container, identity, options) {
130
+ if (!(await existingDirectory(container, identity, options)))
131
+ return;
132
+ validate(options);
133
+ await fs.rmdir(container);
134
+ await syncDirectory(path.dirname(container));
135
+ }
136
+ export async function inspectScopedRecoveryStage(directory, entry, options, requireStableWorkspace = false) {
137
+ if (!entry.recoveryWorkspace)
138
+ return;
139
+ const workspace = workspacePath(directory, entry);
140
+ if (!(await existingDirectory(workspace, entry.recoveryWorkspace, options)))
141
+ return;
142
+ const backup = path.join(directory, "before", entry.backupName);
143
+ const source = await scopedTransactionImage(backup, options);
144
+ if (source.kind !== entry.kind || source.value !== entry.beforeImage)
145
+ unrecognizedStage();
146
+ const payload = path.join(workspace, "image");
147
+ const evidence = path.join(directory, `scratch-${entry.backupName}.json`);
148
+ const saved = parseScratchEvidence(await readTransactionJournal(evidence, options, SCRATCH_EVIDENCE_BYTES));
149
+ const container = saved?.slot ? scratchPath(workspace, saved.slot) : undefined;
150
+ const hasContainer = container && saved?.container && (await existingDirectory(container, saved.container, options));
151
+ if (hasContainer) {
152
+ for await (const child of await fs.opendir(container)) {
153
+ validate(options);
154
+ if (child.name !== "bytes")
155
+ unrecognizedStage();
156
+ }
157
+ }
158
+ const scratch = container ? path.join(container, "bytes") : path.join(workspace, "scratch");
159
+ for await (const child of await fs.opendir(workspace)) {
160
+ validate(options);
161
+ if (child.name !== "image" && (child.name !== "scratch" || saved?.slot))
162
+ unrecognizedStage();
163
+ }
164
+ const image = await scopedTransactionImage(payload, options);
165
+ if (image.kind !== "missing" && !ownedScopedSubset(image, source))
166
+ unrecognizedStage();
167
+ const partial = !container || hasContainer ? await scopedTransactionImage(scratch, options) : { kind: "missing", value: "missing" };
168
+ if (partial.kind !== "missing") {
169
+ if (partial.kind !== "file" ||
170
+ !saved ||
171
+ scopedIdentity(partial.stat) !== saved.identity ||
172
+ findFile(image, saved.file))
173
+ unrecognizedStage();
174
+ const expected = findFile(source, saved.file);
175
+ if (!expected || !(await matchesScopedFilePrefix(path.join(backup, expected[0]), expected[1], partial, options)))
176
+ unrecognizedStage();
177
+ }
178
+ if (!(await existingDirectory(workspace, entry.recoveryWorkspace, options, requireStableWorkspace)))
179
+ unrecognizedStage();
180
+ return {
181
+ workspace,
182
+ backup,
183
+ source,
184
+ payload,
185
+ image,
186
+ scratch,
187
+ partial,
188
+ evidence,
189
+ container,
190
+ containerIdentity: saved?.container,
191
+ };
192
+ }
193
+ async function clearScratch(stage, options) {
194
+ if (stage.container && stage.containerIdentity) {
195
+ if (!(await existingDirectory(stage.container, stage.containerIdentity, options))) {
196
+ if (stage.partial.kind !== "missing")
197
+ unrecognizedStage();
198
+ return;
199
+ }
200
+ await removeScopedImage(stage.scratch, stage.partial, options);
201
+ await removeScratchContainer(stage.container, stage.containerIdentity, options);
202
+ }
203
+ else {
204
+ await removeScopedImage(stage.scratch, stage.partial, options);
205
+ }
206
+ }
207
+ export async function buildScopedRecoveryStage(directory, entry, options, persist) {
208
+ if (!entry.recoveryWorkspace) {
209
+ const slot = randomUUID();
210
+ const workspace = workspacePath(directory, entry, slot);
211
+ const identity = await createPrivateStageDirectory(workspace, options);
212
+ await syncDirectory(path.dirname(workspace));
213
+ validate(options);
214
+ entry.recoveryWorkspace = identity;
215
+ entry.recoveryWorkspaceId = slot;
216
+ await persist();
217
+ }
218
+ const stage = (await inspectScopedRecoveryStage(directory, entry, options, true)) ?? unrecognizedStage();
219
+ const { workspace } = stage;
220
+ const workspaceIdentity = entry.recoveryWorkspace;
221
+ await clearScratch(stage, options);
222
+ async function copy(source, existing, relative) {
223
+ if (!workspaceIdentity || !(await existingDirectory(workspace, workspaceIdentity, options)))
224
+ unrecognizedStage();
225
+ const destination = path.join(stage.payload, relative);
226
+ if (source.kind === "file") {
227
+ if (existing && existing.kind !== "missing")
228
+ return;
229
+ let identity;
230
+ const slot = randomUUID();
231
+ const container = scratchPath(workspace, slot);
232
+ const containerIdentity = await createPrivateStageDirectory(container, options);
233
+ const scratch = path.join(container, "bytes");
234
+ const copied = await scopedTransactionImage(path.join(stage.backup, relative), options, scratch, undefined, async (handle) => {
235
+ const stat = await handle.stat({ bigint: true });
236
+ validate(options);
237
+ if (!stat.isFile() || stat.nlink !== 1n || stat.size !== 0n)
238
+ unrecognizedStage();
239
+ identity = stableScopedIdentity(scratch, stat);
240
+ if ((await scopedPathIdentity(scratch, options)) !== identity)
241
+ unrecognizedStage();
242
+ if (!(await existingDirectory(container, containerIdentity, options)))
243
+ unrecognizedStage();
244
+ await syncDirectory(container);
245
+ await syncDirectory(path.dirname(container));
246
+ if (!(await existingDirectory(workspace, workspaceIdentity, options)))
247
+ unrecognizedStage();
248
+ validate(options);
249
+ await writeJson(stage.evidence, { identity, file: fileKey(relative), slot, container: containerIdentity }, { maxBytes: SCRATCH_EVIDENCE_BYTES });
250
+ });
251
+ if (copied.value !== source.value)
252
+ unrecognizedStage();
253
+ const ready = await scopedTransactionImage(scratch, options);
254
+ if (ready.kind !== "file" ||
255
+ ready.value !== source.value ||
256
+ scopedIdentity(ready.stat) !== identity ||
257
+ (await scopedTransactionImage(destination, options)).kind !== "missing" ||
258
+ !(await existingDirectory(workspace, workspaceIdentity, options)) ||
259
+ !(await existingDirectory(container, containerIdentity, options)))
260
+ unrecognizedStage();
261
+ if ((await scopedPathIdentity(scratch, options)) !== identity)
262
+ unrecognizedStage();
263
+ validate(options);
264
+ await fs.rename(scratch, destination);
265
+ await syncDirectory(path.dirname(destination));
266
+ await removeScratchContainer(container, containerIdentity, options);
267
+ }
268
+ else if (source.kind === "directory") {
269
+ if (!existing || existing.kind === "missing") {
270
+ await fs.mkdir(destination, { mode: 0o700 });
271
+ await syncDirectory(path.dirname(destination));
272
+ }
273
+ const children = new Map(existing?.kind === "directory" ? existing.children : []);
274
+ for (const [name, child] of source.children)
275
+ await copy(child, children.get(name), path.join(relative, name));
276
+ validate(options);
277
+ await fs.chmod(destination, Number(source.stat.mode & 511n));
278
+ validate(options);
279
+ await fs.utimes(destination, source.stat.atime, source.stat.mtime);
280
+ await syncDirectory(destination);
281
+ }
282
+ }
283
+ await copy(stage.source, stage.image, "");
284
+ }
285
+ export async function cleanScopedWorkspace(directory, entry, options) {
286
+ const stage = await inspectScopedRecoveryStage(directory, entry, options);
287
+ if (!stage)
288
+ return;
289
+ const identity = entry.recoveryWorkspace;
290
+ if (!identity)
291
+ unrecognizedStage();
292
+ if ((stage.image.kind !== "missing" ||
293
+ (stage.partial.kind !== "missing" && path.dirname(stage.scratch) === stage.workspace)) &&
294
+ !(await existingDirectory(stage.workspace, identity, options, true)))
295
+ unrecognizedStage();
296
+ await clearScratch(stage, options);
297
+ await removeScopedImage(stage.payload, stage.image, options);
298
+ if (!(await existingDirectory(stage.workspace, identity, options)))
299
+ unrecognizedStage();
300
+ validate(options);
301
+ await fs.rmdir(stage.workspace);
302
+ await syncDirectory(path.dirname(stage.workspace));
303
+ }
@@ -0,0 +1,7 @@
1
+ import { type ScopedImage } from "./snapshot-transaction-images.js";
2
+ import { type TransactionEntry, type TransactionJournal, type TransactionOptions } from "./snapshot-transaction-policy.js";
3
+ export declare function verifyTarget(directory: string, entry: TransactionEntry, journal: TransactionJournal, options: TransactionOptions, deletedByThisCall?: boolean): Promise<{
4
+ value: string;
5
+ before: string;
6
+ scoped: ScopedImage | undefined;
7
+ }>;