@agoric/pola-io 0.1.1-dev-fab25c1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# @agoric/pola-io
+
+A least-authority I/O library for JavaScript.
+
+## Getting Started
+
+```
+npm install @agoric/pola-io
+```
+
+**WIP WIP WIP - EXAMPLES BELOW ARE BROKEN**
+
+### Example: `agoric run` as `npx` subcommand
+
+```js
+import { makeCmdRunner } from '@agoric/pola-io';
+import { execFile as execFileNode } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const main = async ({ execFile = promisify(execFileNode) }) => {
+  const npx = makeCmdRunner('npx', { execFile }); // TODO --no-install
+  return miscTask(npx);
+};
+
+const miscTask = async npx => {
+  const agoric = npx.subCommand('agoric');
+  const { stdout } = await agoric.subCommand('run').exec(['builder.js']);
+  return stdout.split('\n');
+};
+```
+
+### Example: Read-Only File Wrapper
+
+```js
+import { makeFileRW } from '@agoric/pola-io';
+import * as fsp from 'node:fs/promises';
+
+const file = makeFileRW('/', { fsp });
+const readonly = file.readOnly();
+await readonly.readText(); // Allowed
+// @ts-expect-error static error
+await readonly.writeText();
+```
+
+## What This Package Offers
+
+The `@agoric/pola-io` package facilitates using the [Principle of Least Authority (POLA)](https://capnproto.org/capabilities.html#least-authority) for I/O, applying object-capability (ocap) principles to common file, network, and shell operations:
+
+- **Scoped Authority**: Interfaces are built to represent the smallest usable unit of authority—e.g., read-only file handles, command runners with fixed executable paths, or network dialers scoped to specific hosts.
+- **Composable Wrappers**: Inspired by Stiegler's PictureBook of Secure Cooperation, components like revocable forwarders, logging wrappers, and facets are encouraged as default patterns.
+- **Minimize Ambient Authority**: Core interfaces require explicit authority objects. Convenience layers (e.g., `ambient/cmd.js`) exist, but are clearly labeled and should be used with care.
+
+## Background
+
+### Why Minimal Trust Enables Maximal Cooperation
+
+Traditional I/O libraries often assume broad access: open any file, connect to any host, run any command. But this creates fragile systems—where one misused reference or library can do serious harm.
+
+`@agoric/pola-io` takes a different approach. Every I/O action starts from a **scoped authority**—an object that grants only a narrow, intended power. For example, a command runner that can execute *only* a given binary, or a file handle that supports *only* reading.
+
+By making these boundaries explicit, we reduce how much code needs to be trusted—while still making it easy to delegate, revoke, and wrap access. This is what lets us cooperate safely: code can use what it’s been given, but nothing more.
+
+## Related Work
+
+This package builds on a long tradition of work in object-capability security and least-authority design:
+
+- 2023: [**cap-std**](https://crates.io/crates/cap-std) — A Rust library for capability-based I/O that eliminates ambient authority from `std`, providing a least-authority alternative to conventional file and network APIs.
+- 2021: [**Genode's VFS**](https://genodians.org/m-stein/2021-06-21-vfs-1) — Constructs a process's file namespace from explicitly delegated capabilities: "a component can’t just open an arbitrary file. It can only use what the system integrator explicitly handed to it."
+- 2013: [**Distributed Electronic Rights in JavaScript**](https://papers.agoric.com/papers/distributed-electronic-rights-in-javascript/abstract/) — Shows how object-capability techniques in JavaScript support POLA not just for local I/O, but also across distributed systems. Introduces SES (Secure EcmaScript), eventual messaging (!), and authority-constraining wrappers as practical tools for secure cooperation.
+- 2006: [**Emily**](http://www.hpl.hp.com/techreports/2006/HPL-2006-116.html) — A POLA-enforcing subset of OCaml, which uses a verifier to constrain authority and introduces `readable` and `editable` file interfaces that map closely to our approach:
+  ```ocaml
+  type readable = {
+    isDir : unit -> bool;
+    exists : unit -> bool;
+    subRdFiles : unit -> readable list;
+    subRdFile : string -> readable;
+    inChannel : unit -> in_channel;
+    getBytes : unit -> string;
+    fullPath : unit -> string;
+  }
+  type editable = {
+    ro : readable;
+    subEdFiles : unit -> editable list;
+    subEdFile : string -> editable;
+    outChannel : unit -> out_channel;
+    setBytes : string -> unit;
+    mkDir : unit -> unit;
+    createNewFile : unit -> unit;
+    delete : unit -> unit;
+  }
+  ```
+- 2002: [**DarpaBrowser Report**](http://www.combex.com/papers/darpa-report/html/index.html) — Critiques the ambient authority embedded in interfaces like Java's `java.io.File`.
+- 2004: [**A PictureBook of Secure Cooperation**](http://erights.org/talks/efun/SecurityPictureBook.pdf) — A visual introduction to object-capability patterns like revocable forwarders, facets, and sealers, showing how authority can be safely delegated and composed.
+
+These systems share the goal of enabling secure cooperation through modular, delegatable authority. `@agoric/pola-io` brings these patterns to JavaScript I/O.
+
+
+
+## Philosophy: Secure Cooperation
+
+Just like the PictureBook describes, this package is about **delegating only what is necessary**, and composing secure patterns like revocation, logging, and least authority by default. Think:
+
+- Giving a friend temporary read access to a file.
+- Running a single binary with a fixed command.
+- Logging access without breaking encapsulation.
+
+Applying these techniques uniformly leads to systems where cooperation is safer, authority is easier to reason about, and trust boundaries are clear.
+
+## Contributing
+
+Please do! See [CONTRIBUTING](./CONTRIBUTING.md).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agoric/pola-io",
+  "version": "0.1.1-dev-fab25c1.0+fab25c1",
+  "description": "Least Authority I/O utilities",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/types.ts",
+  "scripts": {
+    "build": "exit 0",
+    "test": "ava",
+    "test:xs": "exit 0",
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:eslint": "eslint .",
+    "lint:types": "yarn run -T tsc",
+    "lint-fix": "eslint --fix ."
+  },
+  "devDependencies": {
+    "ava": "^5.3.0"
+  },
+  "files": [
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "eslintConfig": {
+    "extends": [
+      "@agoric"
+    ]
+  },
+  "ava": {
+    "files": [
+      "test/**/*.test.*"
+    ],
+    "timeout": "2m"
+  },
+  "typeCoverage": {
+    "atLeast": 80
+  },
+  "gitHead": "fab25c1d7df5590379b9d71d12d4b72500652932"
+}

package/src/ambient/cmd.js

@@ -0,0 +1,21 @@
+import { execFile as execFileAmbient } from 'child_process';
+import { promisify } from 'node:util';
+import * as cmd from '../cmd.js';
+
+/**
+ * Access to run a command with flags appended.
+ *
+ * @example
+ * const lsPlain = makeCmdRunner('ls', { execFile });
+ * const ls = ls.withFlags('-F')
+ * await ls.exec('/tmp') // runs: ls /tmp -F
+ *
+ * TODO? .withPath('/opt') or .withEnv({PATH: `${env.PATH}:/opt`})
+ *
+ * @param {string} file
+ * @param {{ execFile: any }} io
+ */
+export const makeCmdRunner = (
+  file,
+  { execFile = promisify(execFileAmbient) },
+) => cmd.makeCmdRunner(file, { execFile });

package/src/ambient.js

@@ -0,0 +1 @@
+export * from './ambient/cmd.js';

package/src/cmd.js

@@ -0,0 +1,65 @@
+// freeze() rather than harden() to stay with ZERO dependencies.
+// expected to be compatible with HardenedJS / ses.
+// XXX what hazards does this expose us to?
+const { freeze } = Object;
+
+/**
+ * Access to run a command with flags appended.
+ *
+ * @example
+ * const execP = promisify(childProcess.execFile);
+ * const lsPlain = makeCmdRunner('ls', { execFile: execP });
+ * const ls = ls.withFlags('-F')
+ * await ls.exec('/tmp') // runs: ls /tmp -F
+ *
+ * TODO? .withPath('/opt') or .withEnv({PATH: `${env.PATH}:/opt`})
+ *
+ * XXX use a different name from execFile since the meaning is different
+ * @param {string} file
+ * @param {{ execFile: any }} io XXX expects promisify
+ */
+export const makeCmdRunner = (file, { execFile }) => {
+  /** @param {{ preArgs?: string[], postArgs?: string[] }} [opts] */
+  const make = ({ preArgs = [], postArgs = [] } = {}) => {
+    return freeze({
+      /**
+       * @param {string[]} args
+       * @param {*} [opts]
+       */
+      exec: (
+        args,
+        opts = { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] },
+      ) => execFile(file, [...preArgs, ...args, ...postArgs], opts),
+      /**
+       * @param {string} name
+        @param {string[]} [opts] */
+      subCommand: (name, opts = []) =>
+        make({ preArgs: [...preArgs, name, ...opts], postArgs }),
+      /** @param {string[]} tailFlags */
+      withFlags: (...tailFlags) =>
+        make({ preArgs, postArgs: [...postArgs, ...tailFlags] }),
+    });
+  };
+  return make();
+};
+freeze(makeCmdRunner);
+/** @typedef {ReturnType<makeCmdRunner>} CmdRunner */
+
+/**
+ * @param {Record<string, string | string[] | undefined>} record - e.g. { color: 'blue' }
+ * @returns {string[]} - e.g. ['--color', 'blue']
+ */
+export const flags = record => {
+  // TODO? support --yes with boolean?
+
+  /** @type {[string, string][]} */
+  // @ts-expect-error undefined is filtered out
+  const skipUndef = Object.entries(record).filter(([_k, v]) => v !== undefined);
+  return skipUndef.flatMap(([key, value]) => {
+    if (Array.isArray(value)) {
+      return value.flatMap(v => [`--${key}`, v]);
+    }
+    return [`--${key}`, value];
+  });
+};
+freeze(flags);

package/src/file.js

@@ -0,0 +1,118 @@
+// @ts-check
+
+const { freeze } = Object;
+
+// XXX: what hazards may not using endo assert.fail expose us to?
+export const fail = reason => {
+  throw Error(reason);
+};
+freeze(fail);
+
+/**
+ * Dynamic access
+ *
+ * @template {Record<string, any>} T
+ * @param {Partial<T>} io
+ * @returns {T}
+ */
+const dyn = io => {
+  const it = new Proxy(io, {
+    get(_t, p) {
+      if (!(p in io)) {
+        return () => fail(`no access to ${String(p)}`);
+      }
+      // @ts-expect-error tsc doesn't refine per p in o
+      return io[p];
+    },
+  });
+  return /** @type {T} */ (it);
+};
+
+/**
+ * @template [T=any]
+ * @typedef {{
+ *   join(...segments: string[]): T;
+ *   toString: () => string;
+ *   basename: () => string;
+ *   relative(to: string): string;
+ * }} PathNode
+ *
+ * XXX how to test / assert / declare that FileRd and FileWR extend PathNode?
+ * interfaces?
+ */
+
+/**
+ * @typedef {ReturnType<typeof makeFileRd>} FileRd
+ */
+
+/**
+ * Reify file read access as an object.
+ *
+ * @param {string} root
+ * @param {object} [io]
+ * @param {Partial<typeof import('fs')>} [io.fs]
+ * @param {Partial<typeof import('fs/promises')>} [io.fsp]
+ * @param {Partial<typeof import('path')>} [io.path]
+ */
+export const makeFileRd = (root, { fs = {}, fsp = {}, path = {} } = {}) => {
+  const [fsio, fspio, pathio] = [dyn(fs), dyn(fsp), dyn(path)];
+
+  /** @param {string} there */
+  const make = there => {
+    const self = {
+      toString: () => there,
+      /** @param {string[]} segments */
+      join: (...segments) => make(pathio.join(there, ...segments)),
+      /** @param {string} to */
+      relative: to => pathio.relative(there, to),
+      stat: () => fspio.stat(there),
+      readText: () => fspio.readFile(there, 'utf8'),
+      readJSON: () => self.readText().then(txt => JSON.parse(txt)),
+      /** @param {string} [suffix] */
+      basename: suffix => pathio.basename(there, suffix),
+      existsSync: () => fsio.existsSync(there),
+      /** @returns {Promise<FileRd[]>} */
+      readdir: () =>
+        fspio
+          .readdir(there)
+          .then(files => files.map(segment => self.join(segment))),
+    };
+    return freeze(self);
+  };
+  return make(root);
+};
+freeze(makeFileRd);
+
+/**
+ * Reify file read/write access as an object.
+ *
+ * @param {string} root
+ * @param {object} [io]
+ * @param {Partial<typeof import('fs')>} [io.fs]
+ * @param {Partial<typeof import('fs/promises')>} [io.fsp]
+ * @param {Partial<typeof import('path')>} [io.path]
+ *
+ * @typedef {ReturnType<typeof makeFileRW>} FileRW
+ */
+export const makeFileRW = (root, { fs = {}, fsp = {}, path = {} } = {}) => {
+  // XXX share dyn with makeFileRd?
+  const [fspio, pathio] = [dyn(fsp), dyn(path)];
+
+  /** @param {string} there */
+  const make = there => {
+    const ro = makeFileRd(there, { fs, fsp, path });
+    const self = {
+      toString: () => there,
+      readOnly: () => ro,
+      /** @param {string[]} segments */
+      join: (...segments) => make(pathio.join(there, ...segments)),
+      writeText: text => fspio.writeFile(there, text, 'utf8'),
+      unlink: () => fspio.unlink(there),
+      mkdir: () => fspio.mkdir(there, { recursive: true }),
+      rmdir: () => fspio.rmdir(there),
+    };
+    return freeze(self);
+  };
+  return make(root);
+};
+freeze(makeFileRW);

package/src/index.js

@@ -0,0 +1,3 @@
+export * from './file.js';
+export * from './cmd.js';
+export * from './net.js';

package/src/net.js

@@ -0,0 +1,119 @@
+// @ts-check
+
+const { freeze } = Object;
+
+/**
+ * @import {PathNode, FileRd, FileRW} from './file';
+ *
+ * XXX TODO: basename, relative
+ * @typedef {Omit<PathNode, 'basename' | 'relative'> & Pick<FileRd, 'readText' | 'readJSON'>} TextRd
+ */
+
+const dbg = label => x => {
+  label;
+  // console.log(label, x);
+  return x;
+};
+
+/**
+ *
+ * @param {string} root
+ * @param {object} io
+ * @param {typeof fetch} io.fetch
+ * @param {(...msgs: any[]) => void} [io.log]
+ * @returns {TextRd}
+ */
+export const makeWebRd = (root, { fetch, log = console.log }) => {
+  /** @param {string} there */
+  const make = there => {
+    /** @param {string[]} segments */
+    const join = (...segments) => {
+      dbg('web.join')({ there, segments });
+      let out = there;
+      for (const segment of segments) {
+        out = `${new URL(segment, out)}`;
+      }
+      return out;
+    };
+
+    const checkedFetch = async () => {
+      log('WebRd fetch:', there);
+      const res = await fetch(there);
+      if (!res.ok) {
+        throw Error(`${res.statusText} @ ${there}`);
+      }
+      return res;
+    };
+    /** @type {TextRd} */
+    const self = {
+      toString: () => there,
+      /** @param {string[]} segments */
+      join: (...segments) => make(join(...segments)),
+      readText: () => checkedFetch().then(res => res.text()),
+      readJSON: () => checkedFetch().then(res => res.json()),
+    };
+    return freeze(self);
+  };
+  return make(root);
+};
+freeze(makeWebRd);
+
+/**
+ * @param {TextRd} src
+ * @param {FileRW} dest
+ *
+ * @typedef {ReturnType<typeof makeWebCache>} WebCache
+ */
+export const makeWebCache = (src, dest) => {
+  /** @type {Map<string, Promise<FileRd>>} */
+  const saved = new Map();
+
+  /** @param {string} segment */
+  const getFileP = segment => {
+    const target = src.join(segment);
+    const addr = `${target}`;
+    const cached = saved.get(addr);
+    if (cached) return cached;
+
+    const f = dest.join(segment);
+    /** @type {Promise<FileRd>} */
+    const p = new Promise((resolve, reject) =>
+      target
+        .readText()
+        .then(txt =>
+          dest
+            .mkdir()
+            .then(() => f.writeText(txt).then(_ => resolve(f.readOnly()))),
+        )
+        .catch(reject),
+    );
+    saved.set(addr, p);
+    return p;
+  };
+
+  const remove = async () => {
+    throw Error('TODO');
+    // await Promise.all([...saved.values()].map(p => p.then(f => f.unlink())));
+    // await dest.rmdir();
+  };
+
+  const self = {
+    toString: () => `${src} -> ${dest}`,
+    /** @param {string} segment */
+    getText: async segment => {
+      const fr = await getFileP(segment);
+      return fr.readText();
+    },
+    /** @param {string} segment */
+    storedPath: segment => getFileP(segment).then(f => f.toString()),
+    /** @param {string} segment */
+    size: async segment => {
+      const fr = await getFileP(segment);
+      const info = await fr.stat();
+      return info.size;
+    },
+    remove,
+  };
+  return freeze(self);
+};
+freeze(makeWebCache);