@clawkeepers/gatekeeper-fs 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ControlStackAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,206 @@
+OpenClaw OS
+Copyright (c) 2026 ControlStackAI
+Original project contributions are licensed under the MIT License; see LICENSE.
+Third-party and adapted material retains its applicable license terms.
+
+OpenClaw (https://github.com/openclaw/openclaw) provides the separately installed,
+unmodified agent runtime, Gateway and public plugin interfaces. Its pinned
+v2026.9.2 license is MIT, copyright (c) 2026 OpenClaw Foundation; its own
+THIRD_PARTY_NOTICES.md applies to incorporated upstream dependencies.
+
+Cloudflare OS (https://github.com/cloudflare/cloudflare-os), by Cloudflare and
+its contributors, provides architectural foundations and adapted material:
+capability introductions, gatekeepers, approval/simulation contracts, observers,
+and kernel review/authoring guidance. OpenClaw OS contributors modified these
+contracts and documents for a self-hosted, single-process, tool-calling plugin
+runtime. Cloudflare OS Starter (https://github.com/cloudflare/cloudflare-os-starter)
+informed wrapper-owned customization and the upgrade discipline.
+
+Cloudflare OS and Cloudflare OS Starter are Apache-2.0 licensed. Their retained
+material is not relicensed by the project's MIT license. The applicable Apache
+License 2.0 text is reproduced below. The original source distribution includes
+further provenance in docs/acknowledgments.md. Other dependencies retain their
+respective licenses and notices, including generated THIRD-PARTY-NOTICES for
+bundled dependencies.
+
+This is an independent project, not an upstream-endorsed product. No affiliation,
+endorsement or rights to upstream trademarks are implied.
+
+--- Apache License 2.0: retained Cloudflare material ---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,25 @@
+# @clawkeepers/gatekeeper-fs
+
+Phase 3's first driver, currently at the **STOP 2 account/resource checkpoint**.
+No OAuth or external credentials. Explicit `config.roots` is an allowlist; empty roots
+deny all introductions. The kernel, not this package, authenticates the operator and
+activates grants. Accounts are per-operator and revocable; no account lookup auto-grants access.
+
+Implemented: original local-file URL validation, component-aware root containment,
+symlink-component refusal, directory identity capture/revalidation, account revocation,
+constructor-bound `KitGatekeeper` resources, metadata and deployment inputs. Titles omit host
+paths. `resourceKey` is a canonical URL for private kernel storage, not an agent-facing title.
+
+**No list/read/write operation is executable.** Session creation, action application and
+observer verification fail closed. Directory identity checks establish an introduction-time
+binding only; they are not a replacement-race defense for file I/O. The later use/apply
+implementation must prove confinement (including hardlinks and parent replacement) or deny.
+No check-then-open/realpath-only I/O is permitted by the approved contract.
+
+The approved tools remain `gk_fs_dir_list`, `gk_fs_file_read`, `gk_fs_file_write`.
+After STOP 2: kernel authorization, race-confined bounded UTF-8 I/O, pending overlays,
+external-edit refusal on apply, and owner-only audience enforcement. Strategy `low-stakes`
+does not grant sharing; no revert or automatic-write policy is offered.
+
+Focused checkpoint: `scripts/vm/test.sh phase-3 installed fs-boundary` from the disposable
+VM driver. This is explicitly **not full Phase 3 acceptance** and installs no runtime plugin.

package/deploy-inputs.json

@@ -0,0 +1,8 @@
+{
+  "inputs": [],
+  "setupSteps": [
+    "Configure explicit absolute directory roots in plugins.entries.gatekeeper-fs.config.roots; the empty default denies access.",
+    "Only a trusted kernel operator introduction may activate a directory grant.",
+    "File operations remain disabled at the STOP 2 authoring checkpoint. No external credentials are needed."
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import * as openclaw_plugin_sdk_plugin_entry from 'openclaw/plugin-sdk/plugin-entry';
+
+declare const _default: Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["kind"];
+    configSchema?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema | (() => openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema);
+    reload?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema;
+};
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,571 @@
+// src/index.ts
+import { defineGatekeeper } from "@clawkeepers/gatekeeper-kit";
+
+// src/vendor.ts
+import { createHash as createHash3 } from "crypto";
+import { join as join4 } from "path";
+
+// src/account.ts
+import { createHash as createHash2 } from "crypto";
+import { join as join3 } from "path";
+
+// src/directory.ts
+import { join as join2 } from "path";
+import { Value } from "typebox/value";
+import { KitGatekeeper, OverlayStore } from "@clawkeepers/gatekeeper-kit";
+
+// src/paths.ts
+import { lstatSync } from "fs";
+import { pathToFileURL } from "url";
+function denied() {
+  return new Error("Filesystem resource unavailable.");
+}
+function directoryPath(value) {
+  if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//") || /[\\\u0000-\u001f\u007f]/u.test(value) || Buffer.byteLength(value, "utf8") > 4096 || Buffer.from(value, "utf8").toString("utf8") !== value) throw denied();
+  const path = value.length > 1 && value.endsWith("/") ? value.slice(0, -1) : value;
+  if (path !== "/" && path.slice(1).split("/").some((part) => !part || part === "." || part === "..")) throw denied();
+  return path;
+}
+function directoryUrl(value) {
+  if (typeof value !== "string" || value.length > 12300 || !value.startsWith("file:///") || /[?#\\\u0000-\u0020\u007f]/u.test(value) || /%(?:2f|5c)/iu.test(value)) throw denied();
+  try {
+    return directoryPath(decodeURIComponent(value.slice("file://".length)));
+  } catch {
+    throw denied();
+  }
+}
+function contains(root, path) {
+  return root === "/" || path === root || path.startsWith(`${root}/`);
+}
+function configuredRoots(config) {
+  if (Object.keys(config).some((key) => key !== "roots")) throw denied();
+  const roots = config.roots === void 0 ? [] : config.roots;
+  if (!Array.isArray(roots)) throw denied();
+  return [...new Set(roots.map(directoryPath))];
+}
+function identity(path) {
+  const stat = lstatSync(path, { bigint: true });
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw denied();
+  return { path, dev: stat.dev, ino: stat.ino };
+}
+var DirectoryBinding = class _DirectoryBinding {
+  constructor(path) {
+    this.path = path;
+    const paths = ["/"];
+    if (path !== "/") {
+      let current = "";
+      for (const part of path.slice(1).split("/")) {
+        current += `/${part}`;
+        paths.push(current);
+      }
+    }
+    this.chain = paths.map(identity);
+    this.assertCurrent();
+  }
+  chain;
+  /** Capture only existing directories, rejecting symlink components including those above the root. */
+  static capture(path) {
+    try {
+      return new _DirectoryBinding(directoryPath(path));
+    } catch {
+      throw denied();
+    }
+  }
+  /** Reject replacement/removal of the root, target, or any ancestor since introduction. */
+  assertCurrent() {
+    try {
+      for (const before of this.chain) {
+        const now = identity(before.path);
+        if (before.dev !== now.dev || before.ino !== now.ino) throw denied();
+      }
+    } catch {
+      throw denied();
+    }
+  }
+  /** Match a safely opened directory to the captured resource, not merely its current pathname. */
+  assertDescriptor(stat) {
+    const captured = this.chain.at(-1);
+    if (!stat.isDirectory() || stat.dev !== captured.dev || stat.ino !== captured.ino) throw denied();
+  }
+  /** Persistent instance identity includes every ancestor; replacement never inherits old pending actions. */
+  fingerprint() {
+    return JSON.stringify(this.chain.map(({ path, dev, ino }) => [path, String(dev), String(ino)]));
+  }
+  /** Private kernel resource identity, never an agent-facing title or tool result. */
+  key() {
+    return pathToFileURL(this.path).href;
+  }
+};
+
+// src/resources.ts
+var fsResources = [{
+  type: "dir",
+  urlPattern: "file:///:path+",
+  title: "Directory",
+  description: "Read and write text files inside one directory tree.",
+  grantable: true,
+  observerStrategy: "low-stakes",
+  tools: ["gk_fs_dir_list", "gk_fs_file_read", "gk_fs_file_write"]
+}];
+
+// src/tools.ts
+import { Type } from "typebox";
+import { GrantHandle } from "@clawkeepers/shared";
+var closed = { additionalProperties: false };
+var relativePath = Type.String({ minLength: 1, maxLength: 4096 });
+var fsTools = [
+  {
+    name: "gk_fs_dir_list",
+    resourceType: "dir",
+    kind: "observation",
+    description: "List the immediate files and folders in the directory or a relative subdirectory.",
+    parameters: Type.Object({ grant: GrantHandle, subpath: Type.Optional(relativePath) }, closed),
+    outputSchema: Type.Object({ entries: Type.Array(Type.Object({
+      name: Type.String(),
+      kind: Type.Enum(["file", "directory", "unavailable"])
+    }, closed), { maxItems: 1e3 }) }, closed)
+  },
+  {
+    name: "gk_fs_file_read",
+    resourceType: "dir",
+    kind: "observation",
+    description: "Read a UTF-8 text file of up to 1 MiB at a relative path inside the directory.",
+    parameters: Type.Object({ grant: GrantHandle, path: relativePath }, closed),
+    outputSchema: Type.Object({ path: relativePath, content: Type.String({ maxLength: 1048576 }) }, closed)
+  },
+  {
+    name: "gk_fs_file_write",
+    resourceType: "dir",
+    kind: "action",
+    description: "Create or replace a UTF-8 text file of up to 1 MiB at a relative path inside the directory.",
+    parameters: Type.Object({
+      grant: GrantHandle,
+      path: relativePath,
+      content: Type.String({ maxLength: 1048576 })
+    }, closed),
+    outputSchema: Type.Object({ path: relativePath, bytes: Type.Integer({ minimum: 0, maximum: 1048576 }) }, closed)
+  }
+];
+
+// src/io.ts
+import { constants as C, closeSync, fstatSync, lstatSync as lstatSync2, openSync, opendirSync, readSync, readlinkSync } from "fs";
+import { TextDecoder } from "util";
+import { createHash } from "crypto";
+var MAX_BYTES = 1048576;
+function relativePath2(value) {
+  if (typeof value !== "string" || !value || value.startsWith("/") || /[\\\u0000-\u001f\u007f]/u.test(value) || Buffer.byteLength(value) > 4096 || Buffer.from(value).toString("utf8") !== value || value.split("/").some((part) => !part || part === "." || part === "..")) throw denied();
+  return value;
+}
+function textBytes(value) {
+  if (typeof value !== "string") throw denied();
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length > MAX_BYTES || bytes.includes(0) || bytes.toString("utf8") !== value) throw denied();
+  return bytes;
+}
+var stamp = (s) => [s.dev, s.ino, s.nlink, s.size, s.mtimeNs, s.ctimeNs].join(":");
+var regular = (s) => s.isFile() && s.nlink === 1n && s.size <= BigInt(MAX_BYTES);
+var dirFlags = C.O_RDONLY | C.O_DIRECTORY | C.O_NOFOLLOW;
+var fdPath = (fd) => `/proc/self/fd/${fd}`;
+var ConfinedIO = class {
+  constructor(binding) {
+    this.binding = binding;
+  }
+  withDirectory(subpath, fn) {
+    const descriptors = [];
+    try {
+      if (process.platform !== "linux" || !C.O_NOFOLLOW || !C.O_DIRECTORY) throw denied();
+      this.binding.assertCurrent();
+      let fd = openSync("/", dirFlags);
+      descriptors.push(fd);
+      for (const part of this.binding.path.split("/").filter(Boolean)) {
+        fd = openSync(`${fdPath(fd)}/${part}`, dirFlags);
+        descriptors.push(fd);
+      }
+      this.binding.assertDescriptor(fstatSync(fd, { bigint: true }));
+      let expected = this.binding.path;
+      if (subpath !== void 0) for (const part of relativePath2(subpath).split("/")) {
+        fd = openSync(`${fdPath(fd)}/${part}`, dirFlags);
+        descriptors.push(fd);
+        expected = expected === "/" ? `/${part}` : `${expected}/${part}`;
+      }
+      if (readlinkSync(fdPath(fd)) !== expected) throw denied();
+      const value = fn(fd);
+      this.binding.assertCurrent();
+      if (readlinkSync(fdPath(fd)) !== expected) throw denied();
+      return value;
+    } catch {
+      throw denied();
+    } finally {
+      for (const fd of descriptors.reverse()) closeSync(fd);
+    }
+  }
+  withParent(path, fn) {
+    const parts = relativePath2(path).split("/"), name = parts.pop();
+    return this.withDirectory(parts.length ? parts.join("/") : void 0, (fd) => fn(fd, name));
+  }
+  /** Bounded read from a no-follow, single-link regular-file descriptor. Missing alone returns null. */
+  read(path) {
+    return this.withParent(path, (parent, name) => {
+      let fd;
+      try {
+        fd = openSync(`${fdPath(parent)}/${name}`, C.O_RDONLY | C.O_NOFOLLOW | C.O_NONBLOCK);
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw denied();
+      }
+      try {
+        const before = fstatSync(fd, { bigint: true });
+        if (!regular(before)) throw denied();
+        const bytes = Buffer.alloc(MAX_BYTES + 1);
+        let total = 0;
+        while (total < bytes.length) {
+          const n = readSync(fd, bytes, total, bytes.length - total, total);
+          if (n === 0) break;
+          total += n;
+        }
+        const after = fstatSync(fd, { bigint: true });
+        const named = lstatSync2(`${fdPath(parent)}/${name}`, { bigint: true });
+        if (total > MAX_BYTES || !regular(after) || stamp(before) !== stamp(after) || stamp(after) !== stamp(named)) throw denied();
+        const body = bytes.subarray(0, total);
+        if (body.includes(0)) throw denied();
+        const content = new TextDecoder("utf-8", { fatal: true }).decode(body);
+        return { content, stamp: `${stamp(after)}:${createHash("sha256").update(body).digest("hex")}` };
+      } finally {
+        closeSync(fd);
+      }
+    });
+  }
+  /** Never recurse or follow entry symlinks; oversized directories fail, without partial results. */
+  list(subpath) {
+    return this.withDirectory(subpath, (parent) => {
+      const dir = opendirSync(fdPath(parent), { encoding: "utf8", bufferSize: 32 });
+      const entries = [];
+      try {
+        for (let entry = dir.readSync(); entry; entry = dir.readSync()) {
+          relativePath2(entry.name);
+          if (entry.name.includes("/")) throw denied();
+          if (entries.length === 1e3) throw denied();
+          const stat = lstatSync2(`${fdPath(parent)}/${entry.name}`, { bigint: true });
+          entries.push({ name: entry.name, kind: stat.isDirectory() ? "directory" : stat.isFile() && stat.nlink === 1n ? "file" : "unavailable" });
+        }
+      } finally {
+        dir.closeSync();
+      }
+      return entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    });
+  }
+  /** Verify the parent exists through the same anchored walk, without returning file data. */
+  checkParent(path) {
+    this.withParent(path, () => void 0);
+  }
+  /** No supported atomic confined compare-and-publish primitive: all host writes deny. */
+  create(_path, _content, _privateDir) {
+    throw denied();
+  }
+};
+
+// src/state.ts
+import { closeSync as closeSync2, constants as C2, fsyncSync, lstatSync as lstatSync3, mkdirSync, openSync as openSync2, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { randomBytes } from "crypto";
+import { dirname, join } from "path";
+function privateDirectory(path) {
+  try {
+    mkdirSync(path, { recursive: true, mode: 448 });
+    DirectoryBinding.capture(path);
+    const stat = lstatSync3(path);
+    if ((stat.mode & 63) !== 0 || process.getuid && stat.uid !== process.getuid()) throw denied();
+    return path;
+  } catch {
+    throw denied();
+  }
+}
+function readState(path) {
+  let fd;
+  try {
+    fd = openSync2(path, C2.O_RDONLY | C2.O_NOFOLLOW);
+    return JSON.parse(readFileSync(fd, "utf8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return void 0;
+    throw denied();
+  } finally {
+    if (fd !== void 0) closeSync2(fd);
+  }
+}
+function writeState(path, value) {
+  const dir = privateDirectory(dirname(path)), temp = join(dir, `.state-${randomBytes(16).toString("hex")}`);
+  let fd;
+  try {
+    fd = openSync2(temp, C2.O_CREAT | C2.O_EXCL | C2.O_WRONLY | C2.O_NOFOLLOW, 384);
+    writeFileSync(fd, JSON.stringify(value));
+    fsyncSync(fd);
+    closeSync2(fd);
+    fd = void 0;
+    renameSync(temp, path);
+    fd = openSync2(dir, C2.O_RDONLY | C2.O_DIRECTORY | C2.O_NOFOLLOW);
+    fsyncSync(fd);
+  } catch {
+    throw denied();
+  } finally {
+    if (fd !== void 0) closeSync2(fd);
+    try {
+      unlinkSync(temp);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw denied();
+    }
+  }
+}
+
+// src/directory.ts
+var observation = (title) => ({ title, description: "Read within the bound directory.", prohibitAllSharing: true });
+function describeWrite(p) {
+  const path = relativePath2(p.path), bytes = textBytes(p.content).length;
+  return {
+    title: "Write text file",
+    description: "Write text within the bound directory. Host application is currently unavailable because atomic path and external-edit protection cannot be guaranteed.",
+    implementsRevert: false,
+    autoApprovable: false,
+    awaitDecision: false,
+    preview: { path, bytes }
+  };
+}
+var FsDirectory = class extends KitGatekeeper {
+  constructor(binding, accountLive, stateDir) {
+    super(join2(privateDirectory(stateDir), "actions.json"));
+    this.binding = binding;
+    this.accountLive = accountLive;
+    this.stateDir = stateDir;
+    this.overlay = new OverlayStore(join2(stateDir, "overlay.json"));
+    this.io = new ConfinedIO(binding);
+    this.observations = {
+      gk_fs_dir_list: { describe: () => observation("List directory"), read: async (p) => this.list(p.subpath) },
+      gk_fs_file_read: { describe: () => observation("Read text file"), read: async (p) => this.read(relativePath2(p.path)) }
+    };
+    this.actions = { gk_fs_file_write: {
+      describe: describeWrite,
+      simulate: async (p, overlay, id) => {
+        this.live();
+        const path = relativePath2(p.path), content = textBytes(p.content).toString("utf8");
+        const effectPath = join2(this.stateDir, `effect-${id}.json`), recovered = readState(effectPath);
+        if (recovered !== void 0) {
+          if (!recovered || typeof recovered !== "object" || !("path" in recovered) || !("content" in recovered) || recovered.path !== path || recovered.content !== content) throw denied();
+          overlay.add({ actionId: id, kind: "fs.write", payload: recovered });
+          return { path, bytes: Buffer.byteLength(content) };
+        }
+        const original = this.refresh(path);
+        const earlier = this.effects().filter((effect2) => effect2.path === path).at(-1);
+        const effect = { path, content, baseline: earlier?.baseline ?? original?.stamp ?? null };
+        writeState(effectPath, effect);
+        overlay.add({ actionId: id, kind: "fs.write", payload: effect });
+        return { path, bytes: Buffer.byteLength(content) };
+      },
+      apply: async () => {
+        throw denied();
+      }
+    } };
+  }
+  resource = structuredClone(fsResources[0]);
+  overlay;
+  io;
+  live() {
+    this.accountLive();
+    this.binding.assertCurrent();
+  }
+  /** Revalidate bound identity; no contents in metadata. */
+  async describe() {
+    this.live();
+    return { resource: structuredClone(this.resource), title: "Directory", suggestedName: "DIRECTORY" };
+  }
+  effects() {
+    return this.overlay.list().map((entry) => {
+      if (entry.kind !== "fs.write" || !entry.payload || typeof entry.payload !== "object") throw denied();
+      const effect = entry.payload;
+      relativePath2(effect.path);
+      textBytes(effect.content);
+      if (effect.baseline !== null && typeof effect.baseline !== "string") throw denied();
+      return effect;
+    });
+  }
+  refresh(path) {
+    this.live();
+    const current = this.io.read(path);
+    const cachePath = join2(this.stateDir, "cache.json"), stored = readState(cachePath);
+    let cached;
+    if (stored !== void 0) {
+      if (!stored || typeof stored !== "object" || !("path" in stored) || !("value" in stored)) throw denied();
+      cached = stored;
+    }
+    if (cached?.path !== path || JSON.stringify(cached.value) !== JSON.stringify(current)) writeState(cachePath, { path, value: current });
+    return current;
+  }
+  read(path) {
+    this.live();
+    const current = this.refresh(path), pending = this.effects().filter((effect) => effect.path === path).at(-1);
+    if (!pending && !current) throw denied();
+    return { path, content: pending ? pending.content : current.content };
+  }
+  list(raw) {
+    this.live();
+    const subpath = raw === void 0 ? void 0 : relativePath2(raw);
+    const entries = new Map(this.io.list(subpath).map((entry) => [entry.name, entry]));
+    for (const effect of this.effects()) {
+      const parts = effect.path.split("/"), name = parts.pop();
+      if (parts.join("/") !== (subpath ?? "")) continue;
+      if (entries.has(name) && entries.get(name).kind !== "file") throw denied();
+      entries.set(name, { name, kind: "file" });
+    }
+    if (entries.size > 1e3) throw denied();
+    return { entries: [...entries.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0) };
+  }
+  /** No automatic filesystem write policy is offered. */
+  async getAutoApprovableActions() {
+    this.live();
+    return [];
+  }
+  /** Queue authority is supplied only by kernel resolveGrant; sessions recheck liveness and closed schemas on every call. */
+  async startSession(queue) {
+    this.live();
+    const session = await super.startSession(queue);
+    return { close: () => session.close(), call: async (tool, params, ctx) => {
+      this.live();
+      const definition = fsTools.find((def) => def.name === tool);
+      if (!definition || !Value.Check(definition.parameters, params)) throw denied();
+      const value = await session.call(tool, params, ctx);
+      this.live();
+      if (!ctx.dryRun && definition.kind === "observation") {
+        await queue.authorizeObservation(observation(tool === "gk_fs_dir_list" ? "List directory" : "Read text file"));
+        this.live();
+      }
+      return value;
+    } };
+  }
+  /** Deny before touching the journal: rejection remains possible, and no uncertain host write is claimed. */
+  async applyAction(_id) {
+    this.live();
+    throw denied();
+  }
+  /** Retire a pending effect without modifying host files. */
+  async rejectAction(id) {
+    this.live();
+    await super.rejectAction(id);
+    this.live();
+  }
+  /** Revert support is deliberately not advertised. */
+  async revertAction(_id) {
+    throw denied();
+  }
+};
+
+// src/account.ts
+var FsAccount = class {
+  constructor(roots, onRevoke, stateDir, protectedRoot) {
+    this.roots = roots;
+    this.onRevoke = onRevoke;
+    this.stateDir = stateDir;
+    this.protectedRoot = protectedRoot;
+  }
+  active = true;
+  directories = /* @__PURE__ */ new Map();
+  assertLive = () => {
+    if (!this.active) throw denied();
+  };
+  async describe() {
+    this.assertLive();
+    return { displayName: "Local filesystem" };
+  }
+  async getSupportedResources() {
+    this.assertLive();
+    return structuredClone(fsResources);
+  }
+  /** Validate an operator introduction; this produces no grant and never creates a session. */
+  async getGatekeeperFor(url) {
+    this.assertLive();
+    const path = directoryUrl(url);
+    if (contains(path, this.protectedRoot) || contains(this.protectedRoot, path)) throw denied();
+    const root = this.roots.find((candidate) => contains(candidate.path, path));
+    if (!root) throw denied();
+    root.assertCurrent();
+    const binding = DirectoryBinding.capture(path);
+    root.assertCurrent();
+    this.assertLive();
+    const resourceKey = binding.key();
+    const identityPath = join3(privateDirectory(this.stateDir), `binding-${createHash2("sha256").update(resourceKey).digest("hex")}.json`);
+    const fingerprint = binding.fingerprint(), previous = readState(identityPath);
+    if (previous !== void 0 && previous !== fingerprint) throw denied();
+    if (previous === void 0) writeState(identityPath, fingerprint);
+    let gatekeeper = this.directories.get(resourceKey);
+    if (!gatekeeper) {
+      gatekeeper = new FsDirectory(binding, this.assertLive, join3(this.stateDir, createHash2("sha256").update(binding.fingerprint()).digest("hex")));
+      this.directories.set(resourceKey, gatekeeper);
+    }
+    await gatekeeper.describe();
+    this.assertLive();
+    return { gatekeeper, resource: structuredClone(fsResources[0]), resourceKey };
+  }
+  /** Sharing is unavailable; strategy metadata is not evidence of observer access. */
+  async getVerifier() {
+    throw denied();
+  }
+  /** Retained resources keep this account's liveness guard and cannot survive revocation. */
+  async revoke() {
+    if (!this.active) return;
+    this.active = false;
+    this.directories.clear();
+    this.onRevoke();
+  }
+  async reconnect() {
+    throw denied();
+  }
+};
+
+// src/vendor.ts
+var FsVendor = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.roots = configuredRoots(ctx.pluginConfig);
+  }
+  vendor = "fs";
+  apiVersion = 1;
+  roots;
+  accounts = /* @__PURE__ */ new Map();
+  async describe() {
+    return { title: "Filesystem", description: "Scoped host directories.", autoProvisionsAccount: true };
+  }
+  async connectAccount() {
+    throw denied();
+  }
+  async createAccount(operatorId) {
+    if (!operatorId || operatorId.length > 512 || /[\u0000-\u001f\u007f]/u.test(operatorId)) throw denied();
+    const existing = this.accounts.get(operatorId);
+    if (existing) return existing;
+    const account = new FsAccount(this.roots.map((root) => DirectoryBinding.capture(root)), () => {
+      if (this.accounts.get(operatorId) === account) this.accounts.delete(operatorId);
+    }, join4(this.ctx.stateDir, "os", "gatekeepers", "fs", createHash3("sha256").update(operatorId).digest("hex")), this.ctx.stateDir);
+    this.accounts.set(operatorId, account);
+    return account;
+  }
+  async getAccount(operatorId) {
+    return this.accounts.get(operatorId) ?? null;
+  }
+  async getSupportedResources() {
+    return structuredClone(fsResources);
+  }
+  async getTools() {
+    return structuredClone(fsTools);
+  }
+};
+
+// src/index.ts
+var index_default = defineGatekeeper({
+  vendor: "fs",
+  apiVersion: 1,
+  id: "gatekeeper-fs",
+  name: "Filesystem Gatekeeper",
+  description: "Mediates agent access to specific host directories.",
+  createVendor: (ctx) => new FsVendor(ctx),
+  actions: { gk_fs_file_write: { describe: describeWrite } },
+  resources: fsResources,
+  tools: fsTools
+});
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,30 @@
+{
+  "id": "gatekeeper-fs",
+  "name": "Filesystem Gatekeeper",
+  "description": "Mediates agent access to specific host directories.",
+  "contracts": {
+    "tools": []
+  },
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "roots": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "clawos": {
+    "gatekeeper": {
+      "vendor": "fs",
+      "apiVersion": 1
+    }
+  },
+  "version": "0.1.0-beta.1"
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@clawkeepers/gatekeeper-fs",
+  "version": "0.1.0-beta.1",
+  "description": "Scoped host-directory gatekeeper for OpenClaw OS.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "openclaw.plugin.json",
+    "deploy-inputs.json"
+  ],
+  "dependencies": {
+    "typebox": "1.1.39",
+    "@clawkeepers/shared": "0.1.0-beta.1",
+    "@clawkeepers/gatekeeper-kit": "0.1.0-beta.1"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.9.2 <2026.11.0"
+  },
+  "devDependencies": {
+    "tsup": "8.5.0",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4",
+    "@types/node": "22.18.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.9.2 <2026.11.0",
+      "minGatewayVersion": "2026.9.2"
+    },
+    "build": {
+      "openclawVersion": "2026.9.2",
+      "pluginSdkVersion": "2026.9.2"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawkeeper/openclaw-os.git",
+    "directory": "packages/gatekeeper-fs"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "node ../../scripts/check-plugin-metadata.mjs ."
+  }
+}