@kuznai/inception-engine 0.23.0 → 0.24.0

package/README.md

@@ -171,6 +171,8 @@ Create an `inception.json` file at the root of your skills directory:
 }
 ```
 
+`files` and `configs` are intentionally narrower than the raw target-template syntax might suggest. Arbitrary project-local targets under `{repo}` and `{workspace}` are allowed, but user-profile targets under `{home}`, `{appdata}`, and `{xdg_config}` must resolve to documented agent-owned global surfaces such as `~/.claude/settings.json` or `~/.codex/AGENTS.md`. Manifests cannot target inception-engine's own `~/.inception-engine/` state directory.
+
 Each **skill** entry has:
 
 - **name** - Unique identifier using letters, digits, dots, underscores, or hyphens; must not start with a dot
@@ -542,9 +544,11 @@ inception-engine maintains a centralized deployment registry at `~/.inception-en
 
 - **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind. For `skill-dir` and `file-write`, ownership checks also require the recorded `source` to match before an existing target is treated as managed. For `config-patch` and `frontmatter-emit`, overwrite protection is keyed by target path, kind, skill, and agent; the stored `patch` and `undoPatch` are used for patch-level revert bookkeeping rather than deploy-time identity checks.
 
+- **Reserved state**: Manifest-driven deploy and revert actions are not allowed to touch `~/.inception-engine/`, and the registry loader refuses symlinked registry files or directories.
+
 - **Atomic redeploy**: When overwriting an existing managed `skill-dir` target, the engine renames the old target to a backup, creates the new deployment, and only removes the backup on success. If the new deployment fails, the backup is restored. `file-write` and `config-patch` deployments write directly to the target without this backup/rollback model.
 
-- **Cross-platform**: The registry uses the same resolved home directory as the rest of the tool, including sudo scenarios on POSIX and elevated PowerShell on Windows.
+- **Cross-platform**: The registry uses the same resolved home directory as the rest of the tool, including sudo scenarios on POSIX and elevated PowerShell on Windows. On POSIX, inception-engine keeps the state directory at `0700` and the registry file at `0600`.
 
 ## Running with Privilege Escalation
 

package/dist/src/core/deploy.js

@@ -9,7 +9,7 @@ import { compileAdapterActions } from "./adapters/index.js";
 import { applyTomlMcpPatch } from "./adapters/toml.js";
 import { planCapabilityForDeploy } from "./capabilities.js";
 import { applyMergePatch, computeUndoPatch, isPlainObject, } from "./merge-patch.js";
-import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
+import { lookupDeployment, registryDirPath, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
@@ -153,6 +153,62 @@ function detectAmbiguities(detectedAgents, manifest) {
     }
     return warnings;
 }
+function normalizeTemplatePath(template) {
+    return template.replaceAll("\\", "/");
+}
+function isRepoScopedTemplate(template) {
+    return template.startsWith("{repo}") || template.startsWith("{workspace}");
+}
+function normalizePathForComparison(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const normalizedCandidate = normalizePathForComparison(candidate);
+    const normalizedRoot = normalizePathForComparison(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+function collectApprovedGlobalSurfaceTemplates(agentId) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent)
+        return new Set();
+    const supports = [
+        agent.mcpSupport,
+        agent.agentRulesSupport,
+        agent.permissionsSupport,
+        agent.hooksSupport,
+        agent.executionConfigSupport,
+    ];
+    const approved = new Set();
+    for (const support of supports) {
+        if (!support || support.status !== "supported")
+            continue;
+        approved.add(normalizeTemplatePath(support.path.posix.join("/")));
+        approved.add(normalizeTemplatePath(support.path.windows.join("/")));
+    }
+    return approved;
+}
+function assertApprovedManagedTargetTemplate(template, targetAgents, kind) {
+    if (isRepoScopedTemplate(template))
+        return;
+    const normalizedTemplate = normalizeTemplatePath(template);
+    for (const agentId of targetAgents) {
+        const approvedTemplates = collectApprovedGlobalSurfaceTemplates(agentId);
+        if (approvedTemplates.has(normalizedTemplate)) {
+            return;
+        }
+    }
+    throw new UserError("DEPLOY_FAILED", `${kind} target "${template}" is not an approved managed surface. ` +
+        `Use {repo}/... or {workspace}/... for arbitrary project-local paths, ` +
+        `or target a documented agent-owned global config surface.`);
+}
+function assertTargetOutsideReservedEngineState(targetPath, home) {
+    const reservedDir = registryDirPath(home);
+    if (isSameOrDescendantPath(targetPath, reservedDir)) {
+        throw new UserError("DEPLOY_FAILED", `Target "${targetPath}" is inside inception-engine state directory "${reservedDir}" and cannot be managed by manifests`);
+    }
+}
 function checkAntigravityPathCollisions(manifest) {
     const warnings = [];
     const defNames = new Set((manifest.agentDefinitions ?? [])
@@ -223,6 +279,7 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
         const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
         if (targetAgents.length === 0)
             return;
+        assertApprovedManagedTargetTemplate(fileEntry.target, targetAgents, "files");
         const source = path.resolve(sourceDir, fileEntry.path);
         await validateSourcePath(source, fileEntry.path, resolvedSourceDir, realRoot);
         await validateSourceFile(source, fileEntry.path);
@@ -245,6 +302,10 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
 function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace) {
     const actions = [];
     for (const configEntry of manifest.configs ?? []) {
+        const targetAgents = configEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
+        if (targetAgents.length === 0)
+            continue;
+        assertApprovedManagedTargetTemplate(configEntry.target, targetAgents, "configs");
         for (const agentId of configEntry.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
@@ -289,6 +350,9 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
         ...detectCollisions(actions),
         ...adapterResult.warnings,
     ];
+    for (const action of actions) {
+        assertTargetOutsideReservedEngineState(action.target, home);
+    }
     return { actions, warnings };
 }
 export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {

package/dist/src/core/ownership.d.ts

@@ -21,6 +21,7 @@ export type VerifyExpected = {
     agent: AgentId;
 };
 export declare function registryPath(home: string): string;
+export declare function registryDirPath(home: string): string;
 export declare const defaultRegistryPersistence: RegistryPersistence;
 export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed"> | Omit<FrontmatterEmitRegistryEntry, "deployed">;
 export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;

package/dist/src/core/ownership.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { RegistrySchema, } from "../schemas/registry.js";
 const REGISTRY_DIR = ".inception-engine";
@@ -6,8 +6,26 @@ const REGISTRY_FILE = "registry.json";
 export function registryPath(home) {
     return path.join(home, REGISTRY_DIR, REGISTRY_FILE);
 }
+export function registryDirPath(home) {
+    return path.join(home, REGISTRY_DIR);
+}
+async function assertSafeRegistryStoragePath(targetPath, label) {
+    try {
+        const stat = await lstat(targetPath);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Refusing to use ${label} symlink: ${targetPath}`);
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
 async function loadRegistry(home) {
     try {
+        await assertSafeRegistryStoragePath(registryDirPath(home), "registry directory");
+        await assertSafeRegistryStoragePath(registryPath(home), "registry file");
         const content = await readFile(registryPath(home), "utf-8");
         const parsed = JSON.parse(content);
         const result = RegistrySchema.safeParse(parsed);
@@ -18,9 +36,12 @@ async function loadRegistry(home) {
     }
 }
 async function saveRegistry(home, registry) {
-    const dir = path.join(home, REGISTRY_DIR);
+    const dir = registryDirPath(home);
+    await assertSafeRegistryStoragePath(dir, "registry directory");
     await mkdir(dir, { recursive: true });
+    await setDirectoryPermissions(dir);
     const filePath = registryPath(home);
+    await assertSafeRegistryStoragePath(filePath, "registry file");
     await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
     await setFilePermissions(filePath);
 }
@@ -29,12 +50,21 @@ export const defaultRegistryPersistence = {
     save: saveRegistry,
 };
 /**
- * Ensure the file is not world-writable regardless of umask.
+ * Restrict access to the state directory regardless of umask.
+ * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
+ */
+async function setDirectoryPermissions(dirPath) {
+    if (process.platform !== "win32") {
+        await chmod(dirPath, 0o700);
+    }
+}
+/**
+ * Restrict the registry file to the current user regardless of umask.
  * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
  */
 async function setFilePermissions(filePath) {
     if (process.platform !== "win32") {
-        await chmod(filePath, 0o644);
+        await chmod(filePath, 0o600);
     }
 }
 function emptyRegistry() {

package/dist/src/core/revert.js

@@ -1,11 +1,12 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
 import * as frontmatterAdapter from "./adapters/frontmatter.js";
 import { compileAgentDefinitionReverts, compileAgentRuleReverts, compileExecutionConfigReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
 import { revertTomlMcpPatch } from "./adapters/toml.js";
 import { applyUndoPatch } from "./merge-patch.js";
-import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
+import { lookupDeployment, registryDirPath, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
 function buildSkillDirReverts(manifest, home, agentFilter) {
@@ -125,6 +126,54 @@ function lstatOutcome(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { outcome: "fail", error: msg };
 }
+function normalizePathForComparison(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const normalizedCandidate = normalizePathForComparison(candidate);
+    const normalizedRoot = normalizePathForComparison(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+function failReservedStateTarget(action, home) {
+    const reservedDir = registryDirPath(home);
+    if (!isSameOrDescendantPath(action.target, reservedDir)) {
+        return null;
+    }
+    return {
+        outcome: "fail",
+        error: `Refusing to modify inception-engine state directory "${reservedDir}" ` +
+            `via manifest-managed revert target "${action.target}"`,
+    };
+}
+async function preflightManagedSkillDirRevert(action, label, home, deps) {
+    const reservedTargetFailure = failReservedStateTarget(action, home);
+    if (reservedTargetFailure) {
+        if (reservedTargetFailure.outcome === "fail") {
+            logger.fail(label, reservedTargetFailure.error);
+        }
+        return reservedTargetFailure;
+    }
+    try {
+        await lstat(action.target);
+    }
+    catch (err) {
+        const result = lstatOutcome(err);
+        if (result.outcome === "skip") {
+            logger.skip(label, "(not found, skipping)");
+            return result;
+        }
+        logger.fail(label, result.error);
+        return result;
+    }
+    const entry = await lookupDeployment(home, action.target, deps.registry);
+    if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
+        logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
+        return { outcome: "skip" };
+    }
+    return null;
+}
 export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
     const failed = [];
     const planned = [];
@@ -198,6 +247,13 @@ async function applyFrontmatterRevert(action, frontmatterEntry) {
 }
 async function revertFrontmatterEmit(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
+    const reservedTargetFailure = failReservedStateTarget(action, home);
+    if (reservedTargetFailure) {
+        if (reservedTargetFailure.outcome === "fail") {
+            logger.fail(label, reservedTargetFailure.error);
+        }
+        return reservedTargetFailure;
+    }
     try {
         await lstat(action.target);
     }
@@ -245,22 +301,9 @@ async function revertFrontmatterEmit(action, dryRun, verbose, home, planned, dep
 }
 async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
-    try {
-        await lstat(action.target);
-    }
-    catch (err) {
-        const result = lstatOutcome(err);
-        if (result.outcome === "skip") {
-            logger.skip(label, "(not found, skipping)");
-            return result;
-        }
-        logger.fail(label, result.error);
-        return result;
-    }
-    const entry = await lookupDeployment(home, action.target, deps.registry);
-    if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
-        logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
-        return { outcome: "skip" };
+    const preflight = await preflightManagedSkillDirRevert(action, label, home, deps);
+    if (preflight) {
+        return preflight;
     }
     if (dryRun) {
         planned.push({
@@ -302,6 +345,13 @@ async function executeRevertAction(action, dryRun, verbose, home, planned, deps)
 }
 async function revertFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
+    const reservedTargetFailure = failReservedStateTarget(action, home);
+    if (reservedTargetFailure) {
+        if (reservedTargetFailure.outcome === "fail") {
+            logger.fail(label, reservedTargetFailure.error);
+        }
+        return reservedTargetFailure;
+    }
     try {
         await lstat(action.target);
     }
@@ -353,6 +403,13 @@ async function revertFileWrite(action, dryRun, verbose, home, planned, deps) {
 }
 async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
+    const reservedTargetFailure = failReservedStateTarget(action, home);
+    if (reservedTargetFailure) {
+        if (reservedTargetFailure.outcome === "fail") {
+            logger.fail(label, reservedTargetFailure.error);
+        }
+        return reservedTargetFailure;
+    }
     try {
         await lstat(action.target);
     }
@@ -404,6 +461,13 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
 }
 async function revertTomlPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
+    const reservedTargetFailure = failReservedStateTarget(action, home);
+    if (reservedTargetFailure) {
+        if (reservedTargetFailure.outcome === "fail") {
+            logger.fail(label, reservedTargetFailure.error);
+        }
+        return reservedTargetFailure;
+    }
     try {
         await lstat(action.target);
     }

package/dist/test/helpers/path.d.ts

@@ -4,7 +4,7 @@
  */
 export declare function normalizeSlashes(value: string): string;
 /**
- * Assert that a path ends with the given POSIX-style suffix, normalizing separators.
- * Use instead of: assert.ok(normalizeSlashes(p).endsWith("some/suffix"))
+ * Assert that a path ends with the given suffix, normalizing separators on both
+ * sides so callers can safely use either literals or path.join(...).
  */
 export declare function assertPathEndsWith(actual: string, suffix: string, msg?: string): void;

package/dist/test/helpers/path.js

@@ -7,9 +7,9 @@ export function normalizeSlashes(value) {
     return value.replaceAll("\\", "/");
 }
 /**
- * Assert that a path ends with the given POSIX-style suffix, normalizing separators.
- * Use instead of: assert.ok(normalizeSlashes(p).endsWith("some/suffix"))
+ * Assert that a path ends with the given suffix, normalizing separators on both
+ * sides so callers can safely use either literals or path.join(...).
  */
 export function assertPathEndsWith(actual, suffix, msg) {
-    assert.ok(normalizeSlashes(actual).endsWith(suffix), msg ?? `Expected path "${actual}" to end with "${suffix}"`);
+    assert.ok(normalizeSlashes(actual).endsWith(normalizeSlashes(suffix)), msg ?? `Expected path "${actual}" to end with "${suffix}"`);
 }