@narumitw/pi-sync-daemon 0.7.0 → 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.
- package/CHANGELOG.md +11 -0
- package/README.md +16 -2
- package/dist/consent.js +21 -6
- package/dist/engine/backends/git/git-backend.d.ts +1 -1
- package/dist/engine/backends/git/git-backend.js +17 -2
- package/dist/engine/backends/git/git-storage.d.ts +1 -1
- package/dist/engine/backends/git/git-storage.js +30 -9
- package/dist/engine/backends/s3/s3-backend.js +8 -0
- package/dist/engine/backends/sync-backend.d.ts +1 -0
- package/dist/engine/backends/webdav/webdav-backend.js +8 -0
- package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
- package/dist/engine/ignore/effective-ignore-policy.js +33 -0
- package/dist/engine/ignore/ignore-edit.d.ts +13 -0
- package/dist/engine/ignore/ignore-edit.js +102 -0
- package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
- package/dist/engine/ignore/ignore-initialization.js +186 -0
- package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
- package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
- package/dist/engine/ignore/ignore-settings.d.ts +15 -0
- package/dist/engine/ignore/ignore-settings.js +322 -0
- package/dist/engine/ignore/ignore-source.d.ts +27 -0
- package/dist/engine/ignore/ignore-source.js +250 -0
- package/dist/engine/settings/config-file.d.ts +9 -2
- package/dist/engine/settings/config-file.js +124 -28
- package/dist/engine/settings/config.d.ts +3 -0
- package/dist/engine/settings/config.js +93 -7
- package/dist/engine/settings/settings-management.d.ts +2 -2
- package/dist/engine/settings/settings-management.js +16 -8
- package/dist/engine/settings/settings-types.d.ts +23 -2
- package/dist/engine/settings/settings-validation.js +23 -5
- package/dist/engine/snapshot/session-paths.d.ts +1 -1
- package/dist/engine/snapshot/session-paths.js +36 -13
- package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
- package/dist/engine/snapshot/snapshot-apply.js +23 -4
- package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
- package/dist/engine/snapshot/snapshot-codec.js +14 -5
- package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
- package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
- package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
- package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
- package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +24 -1
- package/dist/engine/snapshot/snapshot-transaction-policy.js +106 -2
- package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
- package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
- package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
- package/dist/engine/snapshot/snapshot-transaction.js +86 -108
- package/dist/engine/snapshot/snapshot-types.d.ts +23 -1
- package/dist/engine/snapshot/snapshot-types.js +9 -1
- package/dist/engine/snapshot/snapshot.d.ts +6 -4
- package/dist/engine/snapshot/snapshot.js +91 -34
- package/dist/engine/state/state-types.d.ts +1 -0
- package/dist/engine/sync/continuous-sync.js +18 -3
- package/dist/engine/sync/continuous-watch.js +4 -1
- package/dist/engine/sync/initialization.js +3 -2
- package/dist/engine/sync/local-fields.d.ts +3 -1
- package/dist/engine/sync/local-fields.js +62 -1
- package/dist/engine/sync/merge-apply.js +35 -7
- package/dist/engine/sync/merge-journal.d.ts +18 -4
- package/dist/engine/sync/merge-journal.js +115 -8
- package/dist/engine/sync/merged-sync.d.ts +1 -1
- package/dist/engine/sync/merged-sync.js +103 -50
- package/dist/engine/sync/remote-snapshot.d.ts +9 -2
- package/dist/engine/sync/remote-snapshot.js +56 -17
- package/dist/engine/sync/sync-inspection.js +7 -5
- package/dist/engine/sync/sync-mutations.d.ts +2 -1
- package/dist/engine/sync/sync-mutations.js +110 -47
- package/dist/engine/sync/sync-policy.d.ts +24 -8
- package/dist/engine/sync/sync-policy.js +127 -16
- package/dist/engine/sync/sync-queries.js +8 -1
- package/dist/engine/sync/sync-state.d.ts +2 -2
- package/dist/engine/sync/sync-state.js +20 -2
- package/dist/engine-service.js +24 -2
- package/docs/architecture.md +22 -0
- package/package.json +2 -1
|
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
|
|
|
3
3
|
import path from "node:path";
|
|
4
4
|
import { isPathInside, toPosix } from "../paths.js";
|
|
5
5
|
import { mergePathIdentity } from "../sync/file-merge-planner.js";
|
|
6
|
-
import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, } from "../sync/sync-policy.js";
|
|
6
|
+
import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, isIgnoreControlPath, } from "../sync/sync-policy.js";
|
|
7
7
|
import { sessionStorageRoot } from "./snapshot-paths.js";
|
|
8
8
|
function directoryStat(absolute) {
|
|
9
9
|
try {
|
|
@@ -56,31 +56,75 @@ export function agentDirectoryAnchor(root, boundary) {
|
|
|
56
56
|
}
|
|
57
57
|
return anchor;
|
|
58
58
|
}
|
|
59
|
-
export function agentDirectorySessionRoot(root, sessionDir) {
|
|
59
|
+
export function agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
|
|
60
60
|
const sessionRoot = sessionStorageRoot(root, sessionDir);
|
|
61
61
|
if (physicalRelative(sessionRoot, root) !== undefined)
|
|
62
62
|
throw new Error("Pi session storage overlaps the agent directory root.");
|
|
63
63
|
const relative = physicalRelative(root, sessionRoot);
|
|
64
64
|
if (relative !== undefined) {
|
|
65
|
+
const logical = toPosix(relative);
|
|
65
66
|
const canTraverse = compileSyncPolicyTraversal({ scope: "agent-directory", include: ["sessions"] });
|
|
66
|
-
|
|
67
|
+
const reserved = ignorePolicy || reservedIgnoreNames
|
|
68
|
+
? new Set([
|
|
69
|
+
...(ignorePolicy ? [ignorePolicy.filename, ...ignorePolicy.reservedNames] : []),
|
|
70
|
+
...(reservedIgnoreNames ?? []),
|
|
71
|
+
].map((name) => name.toLowerCase()))
|
|
72
|
+
: undefined;
|
|
73
|
+
if (!canTraverse(logical) || (reserved && isIgnoreControlPath(logical, reserved)))
|
|
67
74
|
throw new Error("Pi session storage overlaps protected agent files.");
|
|
68
75
|
}
|
|
69
76
|
return sessionRoot;
|
|
70
77
|
}
|
|
71
|
-
export function agentDirectoryPhysicalSessionPath(root, sessionDir) {
|
|
72
|
-
const sessionRoot = agentDirectorySessionRoot(root, sessionDir);
|
|
78
|
+
export function agentDirectoryPhysicalSessionPath(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
|
|
79
|
+
const sessionRoot = agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames);
|
|
73
80
|
const nested = physicalRelative(root, sessionRoot) !== undefined;
|
|
74
81
|
return (relativePath) => nested && physicalRelative(sessionRoot, path.resolve(root, relativePath)) !== undefined;
|
|
75
82
|
}
|
|
83
|
+
async function realpathWithMissingTail(target) {
|
|
84
|
+
let ancestor = path.resolve(target);
|
|
85
|
+
for (;;) {
|
|
86
|
+
try {
|
|
87
|
+
const resolved = await fs.realpath(ancestor);
|
|
88
|
+
return path.resolve(resolved, path.relative(ancestor, target));
|
|
89
|
+
}
|
|
90
|
+
catch (error) {
|
|
91
|
+
const code = error.code;
|
|
92
|
+
const parent = path.dirname(ancestor);
|
|
93
|
+
if (parent === ancestor || (code !== "ENOENT" && code !== "ENOTDIR"))
|
|
94
|
+
throw error;
|
|
95
|
+
ancestor = parent;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
export function reservedIgnoreTargetGuard(root, options) {
|
|
100
|
+
if (options.reservedIgnoreNames === undefined)
|
|
101
|
+
return undefined;
|
|
102
|
+
const reserved = new Set(options.reservedIgnoreNames);
|
|
103
|
+
function check(agentRoot, target) {
|
|
104
|
+
const relative = physicalRelative(agentRoot, target);
|
|
105
|
+
if (physicalRelative(target, agentRoot) !== undefined ||
|
|
106
|
+
(relative !== undefined && isIgnoreControlPath(toPosix(relative), reserved)))
|
|
107
|
+
throw new Error("Transfer would access a protected ignore rule path or its ancestor.");
|
|
108
|
+
}
|
|
109
|
+
return async (target) => {
|
|
110
|
+
check(root, target);
|
|
111
|
+
const canonicalRoot = await realpathWithMissingTail(root);
|
|
112
|
+
const canonicalTarget = await realpathWithMissingTail(target);
|
|
113
|
+
check(canonicalRoot, canonicalTarget);
|
|
114
|
+
return canonicalTarget;
|
|
115
|
+
};
|
|
116
|
+
}
|
|
76
117
|
/** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
|
|
77
118
|
export async function assertUnexcludedTargets(root, targets, options, { recursive = true } = {}) {
|
|
78
119
|
const wholeDirectory = options.scope === "agent-directory";
|
|
79
|
-
|
|
120
|
+
const guardReserved = reservedIgnoreTargetGuard(root, options);
|
|
121
|
+
if (!wholeDirectory &&
|
|
122
|
+
!guardReserved &&
|
|
123
|
+
(options.exclude === undefined || (Array.isArray(options.exclude) && !options.exclude.length)))
|
|
80
124
|
return;
|
|
81
125
|
const excluded = compileSyncPolicyExclude(options);
|
|
82
126
|
const sessionRoot = wholeDirectory
|
|
83
|
-
? agentDirectorySessionRoot(root, options.sessionDir)
|
|
127
|
+
? agentDirectorySessionRoot(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames)
|
|
84
128
|
: sessionStorageRoot(root, options.sessionDir);
|
|
85
129
|
const configured = configuredSnapshotPathMatcher(options);
|
|
86
130
|
let visited = 0;
|
|
@@ -93,11 +137,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
|
|
|
93
137
|
if (++visited > 16_384)
|
|
94
138
|
throw new Error("Exclude safety preflight exceeds its path bound; review a smaller transfer.");
|
|
95
139
|
};
|
|
96
|
-
|
|
140
|
+
function refuse() {
|
|
97
141
|
throw new Error("Transfer would replace an excluded path or directory descendant; no replacement is authorized.");
|
|
98
|
-
}
|
|
142
|
+
}
|
|
99
143
|
async function visit(target) {
|
|
100
144
|
validate();
|
|
145
|
+
if (guardReserved) {
|
|
146
|
+
await guardReserved(target);
|
|
147
|
+
validate();
|
|
148
|
+
}
|
|
149
|
+
let logicalPath;
|
|
101
150
|
let sessionPath;
|
|
102
151
|
if (wholeDirectory) {
|
|
103
152
|
if (physicalRelative(target, sessionRoot) !== undefined)
|
|
@@ -105,14 +154,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
|
|
|
105
154
|
const sessionRelative = physicalRelative(sessionRoot, target);
|
|
106
155
|
if (sessionRelative !== undefined) {
|
|
107
156
|
sessionPath = `sessions/${toPosix(sessionRelative)}`;
|
|
108
|
-
|
|
109
|
-
refuse();
|
|
157
|
+
logicalPath = sessionPath;
|
|
110
158
|
}
|
|
111
159
|
else {
|
|
112
160
|
const relative = physicalRelative(root, target);
|
|
113
|
-
if (relative
|
|
161
|
+
if (!relative || /^sessions(?:\/|$)/iu.test(toPosix(relative)))
|
|
114
162
|
refuse();
|
|
163
|
+
logicalPath = toPosix(relative);
|
|
115
164
|
}
|
|
165
|
+
if (!options.ignorePolicy && excluded(logicalPath))
|
|
166
|
+
refuse();
|
|
116
167
|
}
|
|
117
168
|
else {
|
|
118
169
|
const candidates = [];
|
|
@@ -120,22 +171,28 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
|
|
|
120
171
|
candidates.push(toPosix(path.relative(root, target)));
|
|
121
172
|
if (isPathInside(sessionRoot, target))
|
|
122
173
|
candidates.push(`sessions/${toPosix(path.relative(sessionRoot, target))}`);
|
|
123
|
-
if (candidates.some(excluded))
|
|
174
|
+
if (candidates.some((candidate) => excluded(candidate)))
|
|
124
175
|
refuse();
|
|
125
176
|
}
|
|
126
|
-
let
|
|
177
|
+
let observed;
|
|
127
178
|
try {
|
|
128
|
-
|
|
179
|
+
observed = await fs.lstat(target);
|
|
129
180
|
}
|
|
130
181
|
catch (error) {
|
|
131
|
-
validate();
|
|
132
182
|
const code = error.code;
|
|
133
|
-
if (code !== "ENOENT" && code !== "ENOTDIR")
|
|
183
|
+
if (code !== "ENOENT" && code !== "ENOTDIR") {
|
|
184
|
+
validate();
|
|
134
185
|
throw error;
|
|
135
|
-
|
|
186
|
+
}
|
|
136
187
|
}
|
|
137
188
|
validate();
|
|
138
|
-
if (
|
|
189
|
+
if (options.ignorePolicy && logicalPath !== undefined && excluded(logicalPath, observed?.isDirectory()))
|
|
190
|
+
refuse();
|
|
191
|
+
if (!observed)
|
|
192
|
+
return;
|
|
193
|
+
const stat = observed;
|
|
194
|
+
if ((wholeDirectory && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) ||
|
|
195
|
+
(guardReserved && stat.isFile() && stat.nlink !== 1)) {
|
|
139
196
|
throw new Error("Refusing an unsafe symlink, hard link, or special file during snapshot mutation.");
|
|
140
197
|
}
|
|
141
198
|
if (sessionPath && stat.isFile() && !configured(sessionPath))
|
|
@@ -23,13 +23,15 @@ export type ScopedImage = {
|
|
|
23
23
|
} | ScopedNode;
|
|
24
24
|
export declare function scopedPathIdentity(target: string, guards: Guards): Promise<string>;
|
|
25
25
|
export declare function scopedIdentity(stat: BigIntStats): string;
|
|
26
|
+
export declare function installedVacancyIdentityMatches(image: ScopedImage, expected: string): boolean;
|
|
26
27
|
export declare function stableScopedIdentity(target: string, stat: BigIntStats): string;
|
|
27
28
|
export declare function readTransactionJournal(file: string, guards: Guards, maxBytes?: number): Promise<string | undefined>;
|
|
28
29
|
export declare function scopedTransactionImage(target: string, guards: Guards, copyTo?: string, checkPath?: (source: string) => Promise<void>, beforeCopyFile?: (handle: FileHandle) => Promise<void>): Promise<ScopedImage>;
|
|
29
30
|
export declare function ownedScopedSubset(image: ScopedImage, expected: ScopedImage): boolean;
|
|
30
31
|
export declare function matchesScopedFilePrefix(source: string, original: ScopedImage, partial: ScopedImage, guards: Guards): Promise<boolean>;
|
|
31
32
|
export declare function scopedDescendant(image: ScopedImage, relative: string): ScopedImage | undefined;
|
|
32
|
-
export declare function
|
|
33
|
+
export declare function recheckScopedImage(target: string, image: ScopedImage, guards: Guards): Promise<void>;
|
|
34
|
+
export declare function removeScopedImage(target: string, image: ScopedImage, guards: Guards, validateIgnorePolicy?: () => Promise<void>): Promise<void>;
|
|
33
35
|
export declare function legacyImage(target: string, durable?: boolean): Promise<string>;
|
|
34
36
|
type PostFiles = NonNullable<TransactionEntry["postFiles"]>;
|
|
35
37
|
export declare function ownedScopedPostTree(image: ScopedImage, files: PostFiles, requireComplete: boolean): boolean;
|
|
@@ -22,6 +22,16 @@ export function scopedIdentity(stat) {
|
|
|
22
22
|
changedImage();
|
|
23
23
|
return identity;
|
|
24
24
|
}
|
|
25
|
+
export function installedVacancyIdentityMatches(image, expected) {
|
|
26
|
+
if (image.kind === "missing" || !isScopedIdentity(expected))
|
|
27
|
+
return false;
|
|
28
|
+
if (scopedIdentity(image.stat) === expected)
|
|
29
|
+
return true;
|
|
30
|
+
if (process.platform !== "win32" || image.kind !== "file" || image.stat.ino === 0n)
|
|
31
|
+
return false;
|
|
32
|
+
const [device, inode] = expected.split(":");
|
|
33
|
+
return image.stat.dev.toString() === device && image.stat.ino.toString() === inode;
|
|
34
|
+
}
|
|
25
35
|
export function stableScopedIdentity(target, stat) {
|
|
26
36
|
const identity = scopedIdentity(stat);
|
|
27
37
|
if (stat.birthtimeNs > 0n) {
|
|
@@ -180,8 +190,16 @@ export async function scopedTransactionImage(target, guards, copyTo, checkPath,
|
|
|
180
190
|
const hash = createHash("sha256");
|
|
181
191
|
const copy = destination ? await fs.open(destination, "wx", 0o600) : undefined;
|
|
182
192
|
try {
|
|
183
|
-
if (copy)
|
|
184
|
-
|
|
193
|
+
if (copy && beforeCopyFile) {
|
|
194
|
+
if (process.platform === "darwin") {
|
|
195
|
+
validate(guards);
|
|
196
|
+
await copy.utimes(observed.atime, observed.mtime);
|
|
197
|
+
validate(guards);
|
|
198
|
+
await copy.sync();
|
|
199
|
+
validate(guards);
|
|
200
|
+
}
|
|
201
|
+
await beforeCopyFile(copy);
|
|
202
|
+
}
|
|
185
203
|
await readStableFile(source, observed, guards, async (chunk) => {
|
|
186
204
|
hash.update(chunk);
|
|
187
205
|
if (copy)
|
|
@@ -236,7 +254,13 @@ export function scopedDescendant(image, relative) {
|
|
|
236
254
|
}
|
|
237
255
|
return node;
|
|
238
256
|
}
|
|
239
|
-
export async function
|
|
257
|
+
export async function recheckScopedImage(target, image, guards) {
|
|
258
|
+
if (image.kind !== "missing")
|
|
259
|
+
await recheck(target, image.stat, guards);
|
|
260
|
+
else if (await lstat(target, guards))
|
|
261
|
+
changedImage();
|
|
262
|
+
}
|
|
263
|
+
export async function removeScopedImage(target, image, guards, validateIgnorePolicy) {
|
|
240
264
|
if (image.kind === "missing")
|
|
241
265
|
return;
|
|
242
266
|
async function remove(target, node) {
|
|
@@ -245,12 +269,18 @@ export async function removeScopedImage(target, image, guards) {
|
|
|
245
269
|
const observed = await scopedTransactionImage(target, guards);
|
|
246
270
|
if (observed.kind !== "file" || !sameObservation(node.stat, observed.stat) || observed.value !== node.value)
|
|
247
271
|
changedImage();
|
|
272
|
+
if (validateIgnorePolicy) {
|
|
273
|
+
await validateIgnorePolicy();
|
|
274
|
+
await recheck(target, node.stat, guards);
|
|
275
|
+
}
|
|
248
276
|
validate(guards);
|
|
249
277
|
await fs.unlink(target);
|
|
250
278
|
return;
|
|
251
279
|
}
|
|
252
280
|
for (const [name, child] of node.children)
|
|
253
281
|
await remove(path.join(target, name), child);
|
|
282
|
+
if (validateIgnorePolicy)
|
|
283
|
+
await validateIgnorePolicy();
|
|
254
284
|
await recheck(target, node.stat, guards, true);
|
|
255
285
|
validate(guards);
|
|
256
286
|
await fs.rmdir(target);
|
|
@@ -1,17 +1,37 @@
|
|
|
1
1
|
import { type SyncSelectionConfig } from "../sync/sync-policy.js";
|
|
2
2
|
import { type SessionRootTransition } from "./snapshot-root-transition.js";
|
|
3
|
-
import type { SnapshotSelection } from "./snapshot-types.js";
|
|
3
|
+
import type { EffectiveIgnorePolicy, SnapshotOptions, SnapshotSelection } from "./snapshot-types.js";
|
|
4
4
|
export declare const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
|
|
5
5
|
export declare const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
|
|
6
6
|
export declare const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
|
|
7
|
+
export declare const IGNORE_POLICY_JOURNAL_VERSION = 11;
|
|
7
8
|
export declare function isScopedJournal(journal: TransactionJournalPolicy): boolean;
|
|
8
9
|
export declare function isRecoveryStageId(value: unknown): value is string;
|
|
9
10
|
export declare function isScopedIdentity(value: unknown): value is string;
|
|
11
|
+
interface IgnoreSourceBinding {
|
|
12
|
+
version: 1;
|
|
13
|
+
filename: string;
|
|
14
|
+
sourceDigest: string;
|
|
15
|
+
reservedNames: string[];
|
|
16
|
+
}
|
|
10
17
|
export interface TransactionJournalPolicy {
|
|
11
18
|
version: number;
|
|
12
19
|
exclude?: string[];
|
|
13
20
|
selection?: SnapshotSelection;
|
|
21
|
+
ignoreSource?: IgnoreSourceBinding;
|
|
22
|
+
}
|
|
23
|
+
export declare function ignoreSourceBinding(policy: Pick<EffectiveIgnorePolicy, "filename" | "sourceDigest" | "reservedNames">): IgnoreSourceBinding;
|
|
24
|
+
type TransactionGuards = Pick<SnapshotOptions, "validateIgnorePolicy" | "signal" | "validateMutation">;
|
|
25
|
+
export interface TransactionOptions extends SyncSelectionConfig, TransactionGuards {
|
|
26
|
+
sessionDir?: string;
|
|
27
|
+
exclude?: readonly string[];
|
|
28
|
+
protectedTargets?: readonly string[];
|
|
29
|
+
expectedPreimages?: ReadonlyMap<string, string>;
|
|
30
|
+
resolveConfiguredSessionDir?: boolean;
|
|
31
|
+
}
|
|
32
|
+
export declare class StaleIgnorePolicyError extends Error {
|
|
14
33
|
}
|
|
34
|
+
export declare function ignorePolicyValidator(options: SyncSelectionConfig & TransactionGuards): (() => Promise<void>) | undefined;
|
|
15
35
|
export declare function validateJournalPolicy(journal: TransactionJournalPolicy): void;
|
|
16
36
|
export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: SyncSelectionConfig): void;
|
|
17
37
|
export interface TransactionEntry {
|
|
@@ -47,4 +67,7 @@ export interface TransactionJournal extends TransactionJournalPolicy {
|
|
|
47
67
|
export declare function validateJournal(directory: string, journal: TransactionJournal, sessionDir?: string): void;
|
|
48
68
|
export declare function transactionHasSessionTargets(journal: TransactionJournal): boolean;
|
|
49
69
|
export declare function isStrictlyInside(root: string, target: string): boolean;
|
|
70
|
+
export declare function touchesProtectedTarget(target: string, protectedTargets?: readonly string[]): boolean | undefined;
|
|
71
|
+
export declare function assertSafeParents(root: string, sessionRoot: string | undefined, target: string): Promise<void>;
|
|
50
72
|
export declare function assertAllowedTarget(root: string, sessionRoot: string | undefined, target: string): void;
|
|
73
|
+
export {};
|
|
@@ -1,7 +1,10 @@
|
|
|
1
|
+
import fs from "node:fs/promises";
|
|
1
2
|
import path from "node:path";
|
|
3
|
+
import { DEFAULT_IGNORE_FILENAME, validateIgnoreFilename } from "../ignore/ignore-source.js";
|
|
2
4
|
import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
|
|
3
5
|
import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
|
|
4
|
-
import {
|
|
6
|
+
import { mergePathIdentity } from "../sync/file-merge-planner.js";
|
|
7
|
+
import { portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
|
|
5
8
|
import { agentDir } from "./session-paths.js";
|
|
6
9
|
import { isCaseReplacement } from "./snapshot-case-replacement.js";
|
|
7
10
|
import { sessionStorageRoot } from "./snapshot-paths.js";
|
|
@@ -9,22 +12,91 @@ import { validateSessionRootTransition } from "./snapshot-root-transition.js";
|
|
|
9
12
|
export const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
|
|
10
13
|
export const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
|
|
11
14
|
export const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
|
|
15
|
+
export const IGNORE_POLICY_JOURNAL_VERSION = 11;
|
|
12
16
|
export function isScopedJournal(journal) {
|
|
13
17
|
return [
|
|
14
18
|
LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
|
|
15
19
|
FIXED_WORKSPACE_JOURNAL_VERSION,
|
|
16
20
|
AGENT_DIRECTORY_JOURNAL_VERSION,
|
|
21
|
+
IGNORE_POLICY_JOURNAL_VERSION,
|
|
17
22
|
].includes(journal.version);
|
|
18
23
|
}
|
|
24
|
+
function usesSlottedWorkspace(journal) {
|
|
25
|
+
return journal.version === AGENT_DIRECTORY_JOURNAL_VERSION || journal.version === IGNORE_POLICY_JOURNAL_VERSION;
|
|
26
|
+
}
|
|
19
27
|
export function isRecoveryStageId(value) {
|
|
20
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));
|
|
21
29
|
}
|
|
22
30
|
export function isScopedIdentity(value) {
|
|
23
31
|
return typeof value === "string" && /^\d{1,20}:[1-9]\d{0,19}:\d{1,20}$/u.test(value);
|
|
24
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
|
+
}
|
|
25
79
|
export function validateJournalPolicy(journal) {
|
|
26
80
|
if (!journal || (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal)))
|
|
27
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.");
|
|
28
100
|
if (isScopedJournal(journal)) {
|
|
29
101
|
if (journal.exclude !== undefined || portableSnapshotSelection(journal.selection).version !== 3)
|
|
30
102
|
throw new Error("Invalid agent-directory transaction policy; preserve evidence.");
|
|
@@ -37,6 +109,16 @@ export function validateJournalPolicy(journal) {
|
|
|
37
109
|
normalizeSyncExclude(journal.exclude);
|
|
38
110
|
}
|
|
39
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
|
+
}
|
|
40
122
|
const directoryKey = syncDirectoryPolicyKey(journal.selection ?? {});
|
|
41
123
|
const effectiveDirectoryKey = syncDirectoryPolicyKey(options);
|
|
42
124
|
if (directoryKey !== undefined
|
|
@@ -117,7 +199,7 @@ export function validateJournal(directory, journal, sessionDir) {
|
|
|
117
199
|
entry.recoveryStaged ||
|
|
118
200
|
!["file", "directory"].includes(entry.kind))) ||
|
|
119
201
|
(entry.recoveryWorkspaceId !== undefined &&
|
|
120
|
-
(journal
|
|
202
|
+
(!usesSlottedWorkspace(journal) ||
|
|
121
203
|
!entry.recoveryWorkspace ||
|
|
122
204
|
!isRecoveryStageId(entry.recoveryWorkspaceId))) ||
|
|
123
205
|
(entry.scopedRemoval !== undefined &&
|
|
@@ -154,6 +236,28 @@ export function transactionHasSessionTargets(journal) {
|
|
|
154
236
|
export function isStrictlyInside(root, target) {
|
|
155
237
|
return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
|
|
156
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
|
+
}
|
|
157
261
|
export function assertAllowedTarget(root, sessionRoot, target) {
|
|
158
262
|
const resolved = path.resolve(target);
|
|
159
263
|
if (isStrictlyInside(root, resolved)) {
|
|
@@ -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
|
+
}>;
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import fs from "node:fs/promises";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { caseReplacementSpelling } from "./snapshot-case-replacement.js";
|
|
4
|
+
import { installedVacancyIdentityMatches, legacyImage, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, recheckScopedImage, scopedIdentity, scopedTransactionImage, } from "./snapshot-transaction-images.js";
|
|
5
|
+
import { assertSafeParents, isScopedJournal, } from "./snapshot-transaction-policy.js";
|
|
6
|
+
export async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
|
|
7
|
+
await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
|
|
8
|
+
const isScoped = isScopedJournal(journal);
|
|
9
|
+
const backup = isScoped && entry.kind !== "missing"
|
|
10
|
+
? await scopedTransactionImage(path.join(directory, "before", entry.backupName), options)
|
|
11
|
+
: undefined;
|
|
12
|
+
const before = isScoped ? (backup?.value ?? "missing") : await legacyBeforeImage(directory, entry);
|
|
13
|
+
if ((backup && backup.kind !== entry.kind) || (journal.version >= 2 && before !== entry.beforeImage))
|
|
14
|
+
throw new Error("Transaction backup changed; preserve evidence for review.");
|
|
15
|
+
const spelling = entry.afterTarget ? await caseReplacementSpelling(entry.target, entry.afterTarget) : entry.target;
|
|
16
|
+
const scoped = isScoped ? await scopedTransactionImage(entry.target, options) : undefined;
|
|
17
|
+
const value = scoped?.value ?? (await legacyImage(entry.target));
|
|
18
|
+
const result = { value, before, scoped };
|
|
19
|
+
const postFiles = entry.postFiles ?? [];
|
|
20
|
+
if (entry.vacantInstall) {
|
|
21
|
+
if (scoped?.kind === "missing" ||
|
|
22
|
+
(scoped &&
|
|
23
|
+
value === before &&
|
|
24
|
+
spelling === entry.target &&
|
|
25
|
+
(await installedVacancyMatches(entry.target, scoped, entry.vacantInstall, options))))
|
|
26
|
+
return result;
|
|
27
|
+
}
|
|
28
|
+
else if (value === "missing") {
|
|
29
|
+
if (value === before ||
|
|
30
|
+
deletedByThisCall ||
|
|
31
|
+
(journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
|
|
32
|
+
return result;
|
|
33
|
+
}
|
|
34
|
+
else if (scoped && entry.scopedRemoval) {
|
|
35
|
+
const removal = entry.scopedRemoval;
|
|
36
|
+
if ((removal.image === "before"
|
|
37
|
+
? backup && ownedScopedSubset(scoped, backup)
|
|
38
|
+
: value === entry.afterImage || ownedScopedPostTree(scoped, postFiles, false)) &&
|
|
39
|
+
scoped.kind !== "missing" &&
|
|
40
|
+
scopedIdentity(scoped.stat) === removal.identity)
|
|
41
|
+
return result;
|
|
42
|
+
}
|
|
43
|
+
else if (value === before || (journal.version >= 2 && value === entry.afterImage)) {
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
46
|
+
else if (journal.version >= 2) {
|
|
47
|
+
const requireComplete = journal.version < 4 || entry.replacementStarted === true || !entry.removalPending;
|
|
48
|
+
if (scoped
|
|
49
|
+
? ownedScopedPostTree(scoped, postFiles, true)
|
|
50
|
+
: await ownedLegacyPostTree(entry.target, postFiles, requireComplete))
|
|
51
|
+
return result;
|
|
52
|
+
}
|
|
53
|
+
throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
|
|
54
|
+
}
|
|
55
|
+
async function installedVacancyMatches(target, image, expected, options) {
|
|
56
|
+
if (!installedVacancyIdentityMatches(image, expected) || image.kind === "missing")
|
|
57
|
+
return false;
|
|
58
|
+
if (scopedIdentity(image.stat) === expected)
|
|
59
|
+
return true;
|
|
60
|
+
const names = await fs.readdir(path.dirname(target));
|
|
61
|
+
options.validateMutation?.();
|
|
62
|
+
options.signal?.throwIfAborted();
|
|
63
|
+
if (!names.includes(path.basename(target)))
|
|
64
|
+
return false;
|
|
65
|
+
await recheckScopedImage(target, image, options);
|
|
66
|
+
return true;
|
|
67
|
+
}
|
|
68
|
+
async function legacyBeforeImage(directory, entry) {
|
|
69
|
+
if (entry.kind === "missing")
|
|
70
|
+
return "missing";
|
|
71
|
+
const backup = path.join(directory, "before", entry.backupName);
|
|
72
|
+
if (entry.kind === "symlink")
|
|
73
|
+
return `symlink:${entry.linkTarget}`;
|
|
74
|
+
const value = await legacyImage(backup);
|
|
75
|
+
if (value === "missing")
|
|
76
|
+
throw new Error("Transaction backup is missing; preserve evidence for review.");
|
|
77
|
+
return value;
|
|
78
|
+
}
|
|
@@ -1,16 +1,5 @@
|
|
|
1
|
-
import { type
|
|
1
|
+
import { type TransactionOptions } from "./snapshot-transaction-policy.js";
|
|
2
2
|
import type { SnapshotApplyPlan } from "./snapshot-types.js";
|
|
3
|
-
interface TransactionOptions extends SyncSelectionConfig {
|
|
4
|
-
sessionDir?: string;
|
|
5
|
-
exclude?: readonly string[];
|
|
6
|
-
signal?: AbortSignal;
|
|
7
|
-
validateMutation?: () => void;
|
|
8
|
-
protectedTargets?: readonly string[];
|
|
9
|
-
/** Fresh apply authorization only; recovery remains bound to durable journal images. */
|
|
10
|
-
expectedPreimages?: ReadonlyMap<string, string>;
|
|
11
|
-
resolveConfiguredSessionDir?: boolean;
|
|
12
|
-
}
|
|
13
3
|
export declare function applySnapshotTransaction(plan: SnapshotApplyPlan, options?: TransactionOptions): Promise<void>;
|
|
14
4
|
export declare function recoverSnapshotTransactionsOnStartup(options?: TransactionOptions): Promise<void>;
|
|
15
5
|
export declare function recoverPendingSnapshotTransactions(options?: TransactionOptions): Promise<void>;
|
|
16
|
-
export {};
|