@multileaf/ai-workflow 0.1.0 → 0.1.2

package/dist/files.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, openSync, closeSync, lstatSync, realpathSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, openSync, closeSync, lstatSync, realpathSync, rmdirSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 export const nodeFileSystem = {
     exists: existsSync,
     read: (path) => readFileSync(path, "utf8"),
@@ -10,14 +10,41 @@ export const nodeFileSystem = {
     },
     createExclusive: (path, content) => {
         mkdirSync(dirname(path), { recursive: true });
+        let descriptor;
+        let created = false;
         try {
-            const descriptor = openSync(path, "wx");
-            try {
-                writeFileSync(descriptor, content);
+            descriptor = openSync(path, "wx");
+            created = true;
+            writeFileSync(descriptor, content);
+            closeSync(descriptor);
+            descriptor = undefined;
+            return true;
+        }
+        catch (error) {
+            if (descriptor !== undefined) {
+                try {
+                    closeSync(descriptor);
+                }
+                catch {
+                    // Keep the original creation/write error as the primary failure.
+                }
             }
-            finally {
-                closeSync(descriptor);
+            if (created) {
+                try {
+                    unlinkSync(path);
+                }
+                catch {
+                    // Keep the original creation/write error as the primary failure.
+                }
             }
+            if (!created && error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    },
+    mkdirExclusive: (path) => {
+        try {
+            mkdirSync(path);
             return true;
         }
         catch (error) {
@@ -37,6 +64,7 @@ export const nodeFileSystem = {
         .map((entry) => join(entry.parentPath.slice(path.length + 1), entry.name))
         .sort(),
     remove: unlinkSync,
+    removeDirectory: rmdirSync,
     pathType: (path) => {
         try {
             const entry = lstatSync(path);
@@ -56,3 +84,184 @@ export const nodeFileSystem = {
     },
     realpath: realpathSync,
 };
+/** Apply project containment and symlink checks to every workflow filesystem mutation. */
+export function withSafeProjectWrites(fs, projectRoot) {
+    const safeMutation = (path) => assertSafeProjectPath(fs, projectRoot, path);
+    return {
+        ...fs,
+        write: (path, content) => {
+            safeMutation(path);
+            fs.write(path, content);
+        },
+        mkdir: (path) => {
+            safeMutation(path);
+            fs.mkdir(path);
+        },
+        ...(fs.writeBytes
+            ? {
+                writeBytes: (path, content) => {
+                    safeMutation(path);
+                    fs.writeBytes?.(path, content);
+                },
+            }
+            : {}),
+        ...(fs.mkdirExclusive
+            ? {
+                mkdirExclusive: (path) => {
+                    safeMutation(path);
+                    return fs.mkdirExclusive?.(path) ?? false;
+                },
+            }
+            : {}),
+        ...(fs.createExclusive
+            ? {
+                createExclusive: (path, content) => {
+                    safeMutation(path);
+                    return fs.createExclusive?.(path, content) ?? false;
+                },
+            }
+            : {}),
+        ...(fs.remove
+            ? {
+                remove: (path) => {
+                    safeMutation(path);
+                    fs.remove?.(path);
+                },
+            }
+            : {}),
+        ...(fs.removeDirectory
+            ? {
+                removeDirectory: (path) => {
+                    safeMutation(path);
+                    fs.removeDirectory?.(path);
+                },
+            }
+            : {}),
+    };
+}
+/** Reject writes that escape the project or cross any existing/dangling symbolic link. */
+export function assertSafeProjectPath(fs, projectRoot, destination) {
+    const root = resolve(projectRoot);
+    const path = resolve(destination);
+    if (!isInside(root, path))
+        throw new Error(`Path must stay inside the project: ${destination}`);
+    if (!fs.pathType)
+        throw new Error("Filesystem cannot safely verify symbolic links for project writes.");
+    const rootType = fs.pathType(root);
+    if (rootType !== "directory")
+        throw new Error(`Project root is not a safe directory: ${root}`);
+    const canonicalRoot = fs.realpath?.(root) ?? root;
+    let current = path;
+    while (isInside(root, current)) {
+        const type = fs.pathType(current);
+        if (type === "symlink")
+            throw new Error(`Project path cannot traverse a symbolic link: ${current}`);
+        if (type !== "missing") {
+            const canonicalPath = fs.realpath?.(current) ?? current;
+            if (!isInside(canonicalRoot, canonicalPath))
+                throw new Error(`Project path resolves outside the project: ${current}`);
+        }
+        if (current === root)
+            return;
+        current = dirname(current);
+    }
+    throw new Error(`Path must stay inside the project: ${destination}`);
+}
+/** Create a set of new project files as one rollback-capable transaction. */
+export function writeProjectFilesAtomically(fs, projectRoot, writes, requiredDirectories = []) {
+    if (!fs.pathType ||
+        !fs.mkdirExclusive ||
+        !fs.createExclusive ||
+        !fs.remove ||
+        !fs.removeDirectory)
+        throw new Error("Filesystem does not support safe atomic project installation.");
+    const root = resolve(projectRoot);
+    const uniquePaths = new Set();
+    const directories = new Set();
+    for (const directoryPath of requiredDirectories) {
+        const directory = resolve(directoryPath);
+        assertSafeProjectPath(fs, root, directory);
+        if (fs.pathType(directory) !== "directory" && fs.pathType(directory) !== "missing")
+            throw new Error(`Installation directory is obstructed: ${directory}`);
+        let current = directory;
+        while (current !== root) {
+            directories.add(current);
+            const parent = dirname(current);
+            if (parent === current || !isInside(root, parent))
+                throw new Error(`Installation directory must stay inside the project: ${current}`);
+            current = parent;
+        }
+    }
+    for (const { path } of writes) {
+        const destination = resolve(path);
+        assertSafeProjectPath(fs, root, destination);
+        if (uniquePaths.has(destination))
+            throw new Error(`Duplicate installation path: ${destination}`);
+        uniquePaths.add(destination);
+        let directory = dirname(destination);
+        while (directory !== root) {
+            assertSafeProjectPath(fs, root, directory);
+            directories.add(directory);
+            const parent = dirname(directory);
+            if (parent === directory || !isInside(root, parent))
+                throw new Error(`Installation directory must stay inside the project: ${directory}`);
+            directory = parent;
+        }
+        if (fs.pathType(destination) !== "missing")
+            throw new Error(`Installation path appeared or already exists: ${destination}`);
+    }
+    const orderedDirectories = [...directories].sort((a, b) => relative(root, a).split(sep).length - relative(root, b).split(sep).length);
+    const createdDirectories = [];
+    const createdFiles = [];
+    try {
+        for (const directory of orderedDirectories) {
+            const type = fs.pathType(directory);
+            if (type === "directory")
+                continue;
+            if (type !== "missing")
+                throw new Error(`Installation directory is obstructed: ${directory}`);
+            assertSafeProjectPath(fs, root, directory);
+            if (!fs.mkdirExclusive(directory))
+                throw new Error(`Installation directory appeared during install: ${directory}`);
+            createdDirectories.push(directory);
+        }
+        for (const { path, content } of writes) {
+            const destination = resolve(path);
+            assertSafeProjectPath(fs, root, destination);
+            if (fs.pathType(destination) !== "missing")
+                throw new Error(`Installation path appeared during install: ${destination}`);
+            if (!fs.createExclusive(destination, content))
+                throw new Error(`Installation file appeared during install: ${destination}`);
+            createdFiles.push(destination);
+        }
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        for (const path of createdFiles.reverse()) {
+            try {
+                if (fs.pathType(path) === "file")
+                    fs.remove(path);
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        for (const path of createdDirectories.reverse()) {
+            try {
+                if (fs.pathType(path) === "directory")
+                    fs.removeDirectory(path);
+            }
+            catch (cleanupError) {
+                if (!["ENOTEMPTY", "EEXIST"].includes(cleanupError.code ?? ""))
+                    cleanupErrors.push(cleanupError);
+            }
+        }
+        if (cleanupErrors.length)
+            throw new AggregateError([error, ...cleanupErrors], "Install failed and rollback was incomplete.", { cause: error });
+        throw error;
+    }
+}
+function isInside(root, destination) {
+    const path = relative(root, destination);
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}

package/dist/generator.js

@@ -1,8 +1,8 @@
 import { resolveGeneratedPath } from "./drift.js";
 export function generateProjectResources(profile, selected, write) {
-    const linterCommand = profile.quality.linter?.command;
-    const formatterCommand = profile.quality.formatter?.command;
-    const testCommand = profile.testing?.command;
+    const linterCommand = safeInlineValue(profile.quality.linter?.command);
+    const formatterCommand = safeInlineValue(profile.quality.formatter?.command);
+    const testCommand = safeInlineValue(profile.testing?.command);
     if (selected.includes("typescript-quality"))
         write(resolveGeneratedPath("rules/project-quality.md"), `# Project Quality Rules\n\n- Use ${profile.runtime.languages.map((language) => (language === "typescript" ? "TypeScript" : language)).join(", ")} with strict typing.\n${linterCommand ? `- Run \`${linterCommand}\` before completion.\n` : ""}${formatterCommand ? `- Run \`${formatterCommand}\` before review.\n` : ""}- Keep all generated AI Workflow artifacts in English.\n`);
     if (selected.includes("tdd-development"))
@@ -14,3 +14,13 @@ export function generateProjectResources(profile, selected, write) {
         write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${testCommand ? `\n- Tests: \`${testCommand}\`` : ""}\n`);
     }
 }
+function safeInlineValue(value) {
+    return value
+        ?.split("")
+        .map((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127 || character === "`"
+        ? " "
+        : character)
+        .join("")
+        .replace(/\s+/g, " ")
+        .slice(0, 180);
+}

package/dist/interpreter.js

@@ -16,9 +16,37 @@ function safeFile(file) {
 }
 function redactSecrets(content) {
     return content
-        .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, "[REDACTED]")
+        .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g, "[REDACTED]")
         .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]")
-        .replace(/\b(api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|password)\b(\s*[=:]\s*)["']?[^\s,"'}]+/gi, "$1$2[REDACTED]");
+        .replace(/(^|[,{;\s])(["']?)([A-Za-z_][A-Za-z0-9_.-]*)(["']?)(\s*[:=]\s*)(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s,;}\]#]+))/gm, (match, boundary, opening, key, closing, operator, doubleQuoted, singleQuoted) => {
+        if (!isSensitiveKey(key))
+            return match;
+        if (doubleQuoted !== undefined)
+            return `${boundary}${opening}${key}${closing}${operator}"[REDACTED]"`;
+        if (singleQuoted !== undefined)
+            return `${boundary}${opening}${key}${closing}${operator}'[REDACTED]'`;
+        return `${boundary}${opening}${key}${closing}${operator}[REDACTED]`;
+    })
+        .replace(/\b(?:github_pat_|gh[pousr]_)[A-Za-z0-9_]{20,}\b/gi, "[REDACTED]")
+        .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gi, "[REDACTED]")
+        .replace(/\bAIza[0-9A-Za-z_-]{20,}\b/g, "[REDACTED]")
+        .replace(/\bsk-[A-Za-z0-9_-]{20,}\b/g, "[REDACTED]")
+        .replace(/\bAKIA[A-Z0-9]{16}\b/g, "[REDACTED]");
+}
+function isSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/[.-]/g, "_");
+    const parts = normalized.split("_");
+    return (parts.some((part) => [
+        "secret",
+        "token",
+        "password",
+        "passwd",
+        "credential",
+        "credentials",
+        "authorization",
+    ].includes(part)) ||
+        /(^|_)(api|access|private|client)_?key(_|$)/.test(normalized) ||
+        /^(aws|azure|gcp|google|cloud|openai|anthropic|stripe|github|gitlab|slack|npm|docker|twilio|sendgrid)(?:_.*)?_(?:key|id)$/.test(normalized));
 }
 function isBinary(content) {
     return [...content].some((character) => {
@@ -81,7 +109,7 @@ function parseFacts(output, allowedFiles) {
         };
     });
 }
-export function createProjectInterpreter(root, provider, contextReader = (path) => readFile(path, "utf8")) {
+export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path))) {
     const projectRoot = resolve(root);
     return {
         async interpret(request) {
@@ -98,16 +126,29 @@ export function createProjectInterpreter(root, provider, contextReader = (path)
                 catch {
                     // Injected context readers may provide virtual files in tests or adapters.
                 }
-                const content = await contextReader(absolute);
+                let content;
+                try {
+                    content = await contextReader(absolute);
+                }
+                catch {
+                    // Do not send content when decoding or reading it failed.
+                    continue;
+                }
                 if (isBinary(content))
                     continue;
-                sections.push(`## ${file}\n${redactSecrets(content)}`);
+                try {
+                    sections.push(`## ${file}\n${redactSecrets(content)}`);
+                }
+                catch {
+                    // Secret filtering is fail-closed: a failing filter excludes the whole file.
+                }
             }
             if (sections.length === 0)
                 return [];
+            const safeProfile = redactSecrets(JSON.stringify(scoped.profile));
             const output = await provider.generate({
                 system: "Interpret project conventions from only the supplied context. Return JSON with a facts array. Each fact must have key, string value, confidence from 0 to 1, and evidence entries with source and reason. Do not infer secrets or repeat credentials.",
-                prompt: `Detected profile:\n${JSON.stringify(scoped.profile)}\n\nScoped project context:\n${sections.join("\n\n")}`,
+                prompt: `Detected profile:\n${safeProfile}\n\nScoped project context:\n${sections.join("\n\n")}`,
                 maxTokens: scoped.maxTokens,
                 responseFormat: "json",
             });

package/dist/lockfile.d.ts

@@ -7,6 +7,6 @@ export type LockedPackage = {
     integrity: string;
     permissions?: string[];
 };
-export declare function resolvePackage(pkg: PackageContract): LockedPackage;
+export declare function resolvePackage(pkg: PackageContract, integrity: string): LockedPackage;
 export declare function serializeLock(packages: LockedPackage[]): string;
 export declare function parseLock(content: string): LockedPackage[];

package/dist/lockfile.js

@@ -1,10 +1,12 @@
-export function resolvePackage(pkg) {
+export function resolvePackage(pkg, integrity) {
+    if (!/^sha256-[a-f0-9]{64}$/.test(integrity))
+        throw new Error("Resolved package integrity must be a SHA-256 snapshot digest.");
     return {
         id: pkg.id,
         version: pkg.version,
         provider: pkg.provider,
         source: pkg.source,
-        integrity: `sha256-${pkg.id}@${pkg.version}`,
+        integrity,
         permissions: [...pkg.permissions].sort(),
     };
 }
@@ -27,6 +29,8 @@ export function parseLock(content) {
         const provider = requiredLockValue(lines[index + 2], /^ {4}provider: (.+)$/, "provider");
         const source = requiredLockValue(lines[index + 3], /^ {4}source: (.+)$/, "source");
         const integrity = requiredLockValue(lines[index + 4], /^ {4}integrity: (.+)$/, "integrity");
+        if ((provider === "local" || provider === "git") && !/^sha256-[a-f0-9]{64}$/.test(integrity))
+            throw new Error(`Lockfile package integrity is invalid: ${id}`);
         index += 5;
         let permissions;
         if (lines[index]?.startsWith("    permissions:")) {

package/dist/migration.d.ts

@@ -1,17 +1,36 @@
+import { type ResourceType } from "./package-contract.js";
 import type { Target } from "./types.js";
 export type ResourceMigration = {
     source: string;
     destination: string;
+    type: ResourceType;
+    id: string;
+    neutralSource: boolean;
+};
+export type MigrationDiagnostic = {
+    path: string;
+    reason: string;
+};
+export type ResourceMigrationPlan = {
+    migrations: ResourceMigration[];
+    diagnostics: MigrationDiagnostic[];
 };
 export type MigrationSnapshot = {
     path: string;
     existed: boolean;
     contentBase64: string;
 };
-export declare function planNeutralResourceMigration(neutralRoot: string, relativeFiles: string[], target: Target): ResourceMigration[];
-export declare function serializeMigrationPreview(target: Target, migrations: ResourceMigration[], existingDestinations: string[]): string;
+export type MigrationCheckpoint = {
+    snapshots: MigrationSnapshot[];
+    postMigrationSnapshots?: MigrationSnapshot[];
+};
+export declare function planNeutralResourceMigration(neutralRoot: string, relativeFiles: string[], target: Target): ResourceMigrationPlan;
+export declare function validateNeutralResourceDocument(relativePath: string, bytes: Uint8Array): string | undefined;
+export declare function serializeMigrationPreview(target: Target, migrations: ResourceMigration[], existingDestinations: string[], removals?: string[], diagnostics?: MigrationDiagnostic[], conflicts?: string[], additionalChanges?: string[]): string;
 export declare function serializeMigrationSnapshots(snapshots: MigrationSnapshot[]): string;
 export declare function parseMigrationSnapshots(encoded: string): MigrationSnapshot[];
+export declare function serializeMigrationCheckpoint(snapshots: MigrationSnapshot[], postMigrationSnapshots?: MigrationSnapshot[]): string;
+export declare function parseMigrationCheckpoint(content: string): MigrationCheckpoint;
 export declare function readResourceBytes(fs: {
     read(path: string): string;
     readBytes?(path: string): Uint8Array;

package/dist/migration.js

@@ -1,43 +1,184 @@
-import { join } from "node:path";
+import { parseDocument } from "yaml";
+import { isAbsolute, join } from "node:path";
 import { renderResourcePath } from "./adapter.js";
 import { RESOURCE_TYPES } from "./package-contract.js";
 export function planNeutralResourceMigration(neutralRoot, relativeFiles, target) {
-    return relativeFiles
-        .flatMap((relative) => {
-        const [candidateType, id, filename, extra] = relative.split("/");
-        if (extra || !RESOURCE_TYPES.includes(candidateType) || !id || !filename)
-            return [];
+    const migrations = [];
+    const diagnostics = [];
+    for (const relative of relativeFiles) {
+        const parts = relative.split("/");
+        const [candidateType, id, filename, extra] = parts;
+        if (isAbsolute(relative) ||
+            relative.includes("\\") ||
+            parts.some((part) => !part || part === "." || part === "..")) {
+            diagnostics.push({ path: relative, reason: "path is not normalized and project-relative" });
+            continue;
+        }
+        if (extra ||
+            parts.length !== 3 ||
+            !RESOURCE_TYPES.includes(candidateType)) {
+            diagnostics.push({ path: relative, reason: "unsupported neutral resource path" });
+            continue;
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+            diagnostics.push({ path: relative, reason: "resource identifier is invalid" });
+            continue;
+        }
         const type = candidateType;
-        const expected = type === "skills" ? "SKILL.md" : `${id}.md`;
-        if (filename !== expected)
-            return [];
-        return [
-            { source: join(neutralRoot, relative), destination: renderResourcePath(target, type, id) },
-        ];
-    })
-        .sort((left, right) => left.destination.localeCompare(right.destination));
-}
-export function serializeMigrationPreview(target, migrations, existingDestinations) {
+        if (type === "skills" && id === "ai-init") {
+            diagnostics.push({
+                path: relative,
+                reason: "skill id ai-init is reserved for the bootstrap skill",
+            });
+            continue;
+        }
+        const expectedFilename = type === "skills" ? "SKILL.md" : `${id}.md`;
+        if (filename !== expectedFilename) {
+            diagnostics.push({ path: relative, reason: `expected filename ${expectedFilename}` });
+            continue;
+        }
+        migrations.push({
+            source: join(neutralRoot, relative),
+            destination: renderResourcePath(target, type, id),
+            type,
+            id,
+            neutralSource: target === "universal",
+        });
+    }
+    migrations.sort((left, right) => left.destination < right.destination ? -1 : left.destination > right.destination ? 1 : 0);
+    diagnostics.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+    return { migrations, diagnostics };
+}
+export function validateNeutralResourceDocument(relativePath, bytes) {
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return "resource is not valid UTF-8";
+    }
+    if ([...content].some((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return (code <= 0x08 || (code >= 0x0e && code <= 0x1f)) && code !== 0x09;
+    }))
+        return "resource contains unsupported control characters";
+    let body = content.replace(/^\uFEFF/, "");
+    if (body.startsWith("---\n") || body.startsWith("---\r\n")) {
+        const frontmatter = body.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+        if (!frontmatter)
+            return "resource frontmatter is not closed";
+        const document = parseDocument(frontmatter[1], { uniqueKeys: true, strict: true });
+        if (document.errors.length)
+            return "resource frontmatter is malformed";
+        const value = document.toJS();
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return "resource frontmatter must be a mapping";
+        const metadata = value;
+        if (typeof metadata.name !== "string" || !metadata.name.trim())
+            return "resource frontmatter requires a non-empty name";
+        if (typeof metadata.description !== "string" || !metadata.description.trim())
+            return "resource frontmatter requires a non-empty description";
+        body = body.slice(frontmatter[0].length);
+    }
+    if (!/^#{1,6}\s+\S/m.test(body))
+        return "resource must contain a Markdown heading";
+    if (!relativePath.endsWith(".md"))
+        return "resource must use the .md format";
+    return undefined;
+}
+export function serializeMigrationPreview(target, migrations, existingDestinations, removals = [], diagnostics = [], conflicts = [], additionalChanges = []) {
     const existing = new Set(existingDestinations);
-    const changes = migrations.map(({ destination }) => existing.has(destination) ? `update: ${destination}` : `add: ${destination}`);
-    return `Migration preview for ${target}:\n${changes.join("\n")}${changes.length ? "\n" : ""}remove: previous target ai-init\n`;
+    const changes = migrations.map(({ destination, neutralSource }) => neutralSource
+        ? `keep: ${destination} (neutral source)`
+        : existing.has(destination)
+            ? `update: ${destination}`
+            : `add: ${destination}`);
+    changes.push(...removals.map((path) => `remove: ${path}`));
+    changes.push(...conflicts.map((path) => `conflict: ${path}`));
+    changes.push(...diagnostics.map(({ path, reason }) => `invalid: ${path} (${reason})`));
+    changes.push(...additionalChanges);
+    return `Migration preview for ${target}:\n${changes.join("\n")}${changes.length ? "\n" : ""}`;
 }
 export function serializeMigrationSnapshots(snapshots) {
+    snapshots.forEach(validateSnapshot);
+    if (new Set(snapshots.map(({ path }) => path)).size !== snapshots.length)
+        throw new Error("Migration resource snapshots contain duplicate paths.");
     return Buffer.from(JSON.stringify(snapshots), "utf8").toString("base64");
 }
 export function parseMigrationSnapshots(encoded) {
-    const value = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+    }
+    catch {
+        throw new Error("Migration resource snapshots are invalid.");
+    }
     if (!Array.isArray(value))
         throw new Error("Migration resource snapshots are invalid.");
-    return value.map((snapshot) => {
+    const snapshots = value.map((snapshot) => {
         if (typeof snapshot !== "object" ||
             snapshot === null ||
             typeof snapshot.path !== "string" ||
             typeof snapshot.existed !== "boolean" ||
             typeof snapshot.contentBase64 !== "string")
             throw new Error("Migration resource snapshots are invalid.");
-        return snapshot;
+        const candidate = snapshot;
+        if (Object.keys(snapshot).some((key) => !["path", "existed", "contentBase64"].includes(key)))
+            throw new Error("Migration resource snapshots contain unsupported fields.");
+        validateSnapshot(candidate);
+        return candidate;
     });
+    if (new Set(snapshots.map(({ path }) => path)).size !== snapshots.length)
+        throw new Error("Migration resource snapshots contain duplicate paths.");
+    return snapshots;
+}
+export function serializeMigrationCheckpoint(snapshots, postMigrationSnapshots) {
+    if (!postMigrationSnapshots)
+        return `schema: 2\nsnapshots_base64: ${serializeMigrationSnapshots(snapshots)}\n`;
+    return `schema: 3\nsnapshots_base64: ${serializeMigrationSnapshots(snapshots)}\npost_migration_snapshots_base64: ${serializeMigrationSnapshots(postMigrationSnapshots)}\n`;
+}
+export function parseMigrationCheckpoint(content) {
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error("Migration backup is invalid.");
+    const value = document.toJS();
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Migration backup is invalid.");
+    const checkpoint = value;
+    if (checkpoint.schema === 2 &&
+        Object.keys(checkpoint).length === 2 &&
+        typeof checkpoint.snapshots_base64 === "string")
+        return { snapshots: parseMigrationSnapshots(checkpoint.snapshots_base64) };
+    if (checkpoint.schema === 3 &&
+        Object.keys(checkpoint).length === 3 &&
+        typeof checkpoint.snapshots_base64 === "string" &&
+        typeof checkpoint.post_migration_snapshots_base64 === "string")
+        return {
+            snapshots: parseMigrationSnapshots(checkpoint.snapshots_base64),
+            postMigrationSnapshots: parseMigrationSnapshots(checkpoint.post_migration_snapshots_base64),
+        };
+    throw new Error("Migration backup is invalid.");
+}
+function validateSnapshotPath(path) {
+    if (!path ||
+        isAbsolute(path) ||
+        path.includes("\\") ||
+        path.includes(":") ||
+        [...path].some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code <= 0x1f || code === 0x7f;
+        }) ||
+        path.split("/").some((part) => !part || part === "." || part === ".."))
+        throw new Error("Migration snapshot path must be project-relative.");
+}
+function validateSnapshot(snapshot) {
+    validateSnapshotPath(snapshot.path);
+    if (typeof snapshot.existed !== "boolean")
+        throw new Error("Migration resource snapshots are invalid.");
+    if (!snapshot.existed && snapshot.contentBase64 !== "")
+        throw new Error("Migration resource snapshots are invalid.");
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(snapshot.contentBase64))
+        throw new Error("Migration resource snapshots are invalid.");
 }
 export function readResourceBytes(fs, path) {
     return fs.readBytes?.(path) ?? Buffer.from(fs.read(path), "utf8");

package/dist/ownership.d.ts

@@ -0,0 +1,14 @@
+import { type ResourceType } from "./package-contract.js";
+import { type Target } from "./types.js";
+export type OwnedFile = {
+    path: string;
+    checksum: string;
+    kind?: "neutral-resource" | "target-resource" | "ai-init" | "supporting-file";
+    target?: Target;
+    resourceType?: ResourceType;
+    resourceId?: string;
+};
+export type OwnershipMetadata = Omit<OwnedFile, "path" | "checksum">;
+export declare function createOwnedFile(path: string, content: string | Uint8Array, metadata?: OwnershipMetadata): OwnedFile;
+export declare function serializeOwnership(files: OwnedFile[]): string;
+export declare function parseOwnership(content: string): OwnedFile[];