@le-space/orbitdb-storage-bridge 0.10.0

package/lib/backends/aleph.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Aleph Cloud storage backend
+ *
+ * The keyless one. `POST https://ipfs.aleph.cloud/api/v0/add` takes a file with
+ * **no API key at any point** and answers `access-control-allow-origin: *`, so
+ * a browser posts to it directly — no proxy, no bearer token, nothing on the
+ * device that would be an account takeover if it leaked. For an application
+ * that has to store something from wherever it happens to be running, that is
+ * a different category from every other driver here.
+ *
+ * Measured against the live host on 2026-09-09, because a driver written from
+ * a description is a guess:
+ *
+ * - a 4 KB `application/vnd.ipld.car` upload came back **byte-identical**, so
+ *   there is none of the "binary files case by case" hedging other services
+ *   attach to CARs;
+ * - an empty blob is accepted, and answers with the well-known empty-file CID;
+ * - retrieval through Aleph's own gateway is exact.
+ *
+ * ## What it cannot do, and why the shape follows
+ *
+ * **Only `add` exists.** `dag/import`, `block/put`, `dag/put`, `pin/add` and
+ * `cat` all 404 on that host. So there is no CAR import and no way to write a
+ * dag-cbor block under its own CID — which since 0.5.2 costs nothing, because
+ * the CAR goes up as one opaque file anyway and the inner CIDs come back when
+ * we unpack it ourselves.
+ *
+ * **The id is Aleph's, not ours.** `add` wraps the file in UnixFS and returns
+ * *its* CIDv0 for the wrapper. That is not the CID of our bytes, and the handle
+ * says so by carrying an `id` and no `cid`. This is exactly the distinction the
+ * contract exists for: a caller that treated the two as interchangeable would
+ * eventually restore something that was never backed up.
+ *
+ * **`add` is ingest, not persistence.** Retention comes from a wallet-signed
+ * STORE message with the `ipfs` engine, posted to `api2.aleph.im`. That needs a
+ * wallet and an SDK, so it is **injected rather than imported**: pass `pin` and
+ * the driver declares `pinByCid`; leave it out and the driver is honest about
+ * being ingest-only. `relay-button`'s `@le-space/browser` already speaks that
+ * API, which is the implementation this hook is shaped for.
+ *
+ * @author @NiKrause
+ * @requires ./types.js - the backend contract
+ */
+
+/* global FormData */
+
+import { defineBackend, handleId, BackendError } from "./types.js";
+import { fetchFromGateways } from "../gateway-fetch.js";
+
+/** Aleph's own first: it serves what Aleph ingested without waiting for propagation. */
+export const ALEPH_GATEWAYS = Object.freeze([
+  "https://ipfs.aleph.cloud/ipfs",
+  "https://dweb.link/ipfs",
+  "https://ipfs.io/ipfs",
+]);
+
+const ALEPH_INGEST = "https://ipfs.aleph.cloud/api/v0/add";
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Create an Aleph backend.
+ *
+ * @param {object} [options]
+ * @param {string} [options.ingestUrl] - defaults to Aleph's public IPFS host
+ * @param {string[]} [options.gateways] - retrieval, tried in order
+ * @param {number} [options.timeout] - per request, in ms
+ * @param {(cid: string, meta?: object) => Promise<any>} [options.pin] - make it
+ *   stick. Aleph retains what a wallet-signed STORE message names, so this is
+ *   the caller's wallet, not ours. Supplying it is what declares `pinByCid`;
+ *   without it the driver stores and says plainly that it does not retain.
+ * @param {typeof fetch} [options.fetch] - for tests, or a browser with its own
+ * @returns {import("./types.js").StorageBackend}
+ */
+export function createAlephBackend(options = {}) {
+  const ingestUrl = options.ingestUrl || ALEPH_INGEST;
+  const gateways = options.gateways || ALEPH_GATEWAYS;
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  const pin = options.pin;
+  const doFetch = options.fetch || globalThis.fetch;
+
+  if (typeof doFetch !== "function") {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      "The aleph backend needs fetch — pass one in `options.fetch` on a runtime without it",
+    );
+  }
+
+  const backend = {
+    name: "aleph",
+
+    capabilities: {
+      // Follows from `pin`, rather than being claimed: the contract checks that
+      // the flag and the method agree, and this is where they come from.
+      pinByCid: Boolean(pin),
+      carImport: false,
+      // A CAR goes up as one opaque file and comes back byte for byte —
+      // measured, not assumed, and the conformance suite re-checks it on every
+      // run by verifying each block against its own CID.
+      preservesInnerCids: true,
+      // No key exists to leak.
+      browserSafeAuth: true,
+      delegation: false,
+      // The IPFS host offers no listing, and the messages API would need the
+      // wallet address this driver deliberately does not hold.
+      listing: false,
+      // Unpinning is a FORGET message, so it belongs with `pin` rather than
+      // here. Claiming deletion the driver cannot perform would be worse than
+      // saying no.
+      deletion: false,
+      minBlobSize: 0,
+    },
+
+    async putBlob(bytes, meta = {}) {
+      const name = meta.name || "blob";
+      const form = new FormData();
+      form.append(
+        "file",
+        new Blob([bytes], { type: meta.contentType || "application/octet-stream" }),
+        name,
+      );
+
+      let response;
+      try {
+        response = await doFetch(ingestUrl, {
+          method: "POST",
+          body: form,
+          signal: AbortSignal.timeout ? AbortSignal.timeout(timeout) : undefined,
+        });
+      } catch (error) {
+        throw new BackendError("UNSUPPORTED", `Aleph ingest is unreachable: ${error.message}`);
+      }
+
+      if (!response.ok) {
+        throw new BackendError(
+          "UNSUPPORTED",
+          `Aleph ingest answered ${response.status} ${response.statusText}`,
+        );
+      }
+
+      // `add` answers one JSON object per line. A name with a path in it — and
+      // backupDatabase gives every file one — makes the host wrap the file in
+      // directories and add a line for each (measured 2026-09-17). The id we
+      // keep is the file's own, never a wrapper's.
+      let entries;
+      try {
+        entries = (await response.text())
+          .split("\n")
+          .filter((line) => line.trim())
+          .map((line) => JSON.parse(line));
+      } catch {
+        throw new BackendError("UNSUPPORTED", "Aleph ingest answered something that is not JSON");
+      }
+      const body = entries.find((entry) => entry?.Name === name) ?? entries[0];
+      if (!body?.Hash) {
+        throw new BackendError("UNSUPPORTED", "Aleph ingest returned no Hash");
+      }
+
+      return {
+        // Aleph's CIDv0 for the UnixFS wrapper it made. Deliberately not
+        // reported as `cid`: it names their encoding of our bytes, not ours.
+        id: body.Hash,
+        backend: "aleph",
+        size: bytes.length,
+        ...(meta.name ? { name: meta.name } : {}),
+        // Said out loud in the handle, because "stored" and "kept" are not the
+        // same thing here and a caller should not have to read this file.
+        retained: Boolean(pin),
+      };
+    },
+
+    async getBlob(handle) {
+      const id = handleId(handle);
+      try {
+        return await fetchFromGateways(id, { gateways, timeout });
+      } catch (error) {
+        throw new BackendError("NOT_FOUND", `No blob for ${id}: ${error.message}`);
+      }
+    },
+  };
+
+  if (pin) {
+    /**
+     * Ask Aleph to keep something already on IPFS.
+     *
+     * Class 1 for the pin, class 2 for the bytes — the split the evaluation
+     * predicted, and the reason `pinCid` here does not upload anything.
+     */
+    backend.pinCid = async (cid, meta = {}) => {
+      await pin(cid, meta);
+      return { id: cid, cid, backend: "aleph", retained: true, ...(meta.name ? { name: meta.name } : {}) };
+    };
+  }
+
+  return defineBackend(backend);
+}
+
+export default createAlephBackend;

package/lib/backends/lighthouse.js

@@ -0,0 +1,325 @@
+/**
+ * @fileoverview Lighthouse storage backend for OrbitDB Storage Bridge
+ *
+ * Pay once, stored in perpetuity: a one-time payment funds an endowment that renews the
+ * Filecoin deals. That is a different bargain from every other backend here, and it fits a
+ * different job -- a small archive you want to stop thinking about, not a rolling backup
+ * whose old versions you would happily expire, because here you pay for those forever too.
+ *
+ * No SDK dependency. The endpoints and shapes below are the ones `@lighthouse-web3/sdk`
+ * 0.4.7 uses: `POST {node}/api/v0/add?wrap-with-directory=false&cid-version=1` with one
+ * multipart `file`, `POST {node}/api/v0/dag/import` for a CAR, `GET
+ * {api}/api/user/files_uploaded` for the listing and `DELETE {api}/api/user/delete_file`.
+ * Their Node client insists on a path on disk; posting the multipart body ourselves takes
+ * the bytes we already hold, and works unchanged in a browser.
+ *
+ * What the Pinata driver learned against a live account applies here too, so it is built
+ * in rather than rediscovered: a backup's CAR goes up as a plain file unless CAR import is
+ * asked for, because `backupDatabase` restores by fetching the CAR back; a file name
+ * carries no path, because a Kubo-shaped `add` turns a path into folders; and a refusal
+ * says what the service said.
+ *
+ * @author @NiKrause
+ * @requires ./types.js - the backend contract
+ * @see {@link ../../docs/STORAGE-BACKENDS.md} for the cost model and the trade-offs
+ */
+
+/* global FormData, URLSearchParams */
+
+import { defineBackend, handleId, BackendError } from "./types.js";
+
+const DEFAULT_NODE = "https://upload.lighthouse.storage";
+const DEFAULT_API = "https://api.lighthouse.storage";
+const DEFAULT_GATEWAY = "https://gateway.lighthouse.storage";
+
+const CAR_MIME = "application/vnd.ipld.car";
+
+/** How often a gateway 429 is waited out before it counts as a failure. */
+const GATEWAY_RETRIES = 4;
+/** The longest single wait, whatever Retry-After asks for. */
+const MAX_RETRY_WAIT_MS = 30_000;
+
+/**
+ * Lighthouse's words for an account whose plan does not include the call. Measured on
+ * 2026-09-17: an upload with a valid key on an expired trial answered 403 "Trial expired
+ * … Please upgrade to a paid plan", while the listing still answered 200.
+ */
+const PLAN_REFUSAL = /trial (period )?(has )?expired|upgrade to a paid plan/i;
+
+/**
+ * What a refusal means to a caller: a plan without the feature is "cannot", a key the
+ * service rejects is a misconfigured backend, only a 404 is "not there", and anything
+ * else is "cannot".
+ */
+const codeFor = (status, detail = "") => {
+  if (status === 404) return "NOT_FOUND";
+  if (PLAN_REFUSAL.test(detail)) return "UNSUPPORTED";
+  if (status === 401 || status === 403) return "INVALID_BACKEND";
+  return "UNSUPPORTED";
+};
+
+/** The first 240 characters of what the service said, on one line. */
+const reasonOf = async (response) =>
+  (await response.text().catch(() => "")).replace(/\s+/g, " ").trim().slice(0, 240);
+
+/** Retry-After when the gateway sends one, otherwise doubling from a second. */
+const retryWait = (response, attempt) => {
+  const header = response.headers.get("retry-after");
+  const seconds = header === null ? NaN : Number(header);
+  const ms = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : 1000 * 2 ** attempt;
+  return Math.min(ms, MAX_RETRY_WAIT_MS);
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** A base URL as given, or over https when given as a bare domain. */
+const baseUrl = (value) => {
+  const trimmed = String(value).trim().replace(/\/+$/, "");
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+};
+
+/**
+ * An `add` or `dag/import` answer: one JSON object, a JSON array, or one object per
+ * line — Kubo answers the last way whenever more than one entry comes back.
+ */
+const parseEntries = (text) => {
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  }
+};
+
+/**
+ * Create a Lighthouse backend.
+ *
+ * @param {object} options
+ * @param {string} [options.apiKey] - Lighthouse API key; falls back to LIGHTHOUSE_API_KEY
+ * @param {"shared"|"user"} [options.keyOwnership="shared"] - who the key belongs to.
+ *   Lighthouse lets each person mint their own key by signing with their own wallet
+ *   (`POST /api/auth/create_api_key`), and only then is nothing secret being shipped to a
+ *   browser -- so this is what decides `browserSafeAuth`. The key is unscoped and
+ *   long-lived either way: an XSS is a full account takeover, user-minted or not.
+ * @param {boolean} [options.carImport=false] - send CARs to `dag/import`, so Lighthouse
+ *   unpacks them and the blocks inside keep their CIDs. The handle then names the CAR's
+ *   root, which a gateway serves as that block, not as the CAR — so `backupDatabase`,
+ *   which restores by fetching the CAR back, needs this off. Without it a CAR goes up as
+ *   one plain file and comes back byte for byte.
+ * @param {string} [options.gateway] - retrieval gateway; a bare domain is read over https
+ * @param {number} [options.gatewayRetries=4] - how often a gateway 429 is waited out
+ * @param {string} [options.node] - upload node
+ * @param {string} [options.api] - account API
+ * @param {"walrus"} [options.storageType] - Lighthouse can put the bytes on Walrus/Sui instead
+ * @returns {import("./types.js").StorageBackend}
+ */
+export function createLighthouseBackend(options = {}) {
+  const apiKey =
+    options.apiKey ||
+    (typeof process !== "undefined"
+      ? process.env?.LIGHTHOUSE_API_KEY
+      : undefined);
+
+  if (!apiKey) {
+    throw new BackendError(
+      "INVALID_BACKEND",
+      "createLighthouseBackend needs an apiKey (or LIGHTHOUSE_API_KEY)",
+    );
+  }
+
+  const node = baseUrl(options.node || DEFAULT_NODE);
+  const api = baseUrl(options.api || DEFAULT_API);
+  const gateway = baseUrl(options.gateway || DEFAULT_GATEWAY);
+  const storageType = options.storageType;
+  const carImport = options.carImport === true;
+  const gatewayRetries = options.gatewayRetries ?? GATEWAY_RETRIES;
+
+  const authHeaders = (extra = {}) => ({
+    Authorization: `Bearer ${apiKey}`,
+    ...(storageType ? { "X-Storage-Type": storageType } : {}),
+    ...extra,
+  });
+
+  /** Call the account API; a refusal carries the service's reason and a code. */
+  const call = async (url, init = {}) => {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      const path = url.replace(api, "");
+      const reason = await reasonOf(response);
+      throw new BackendError(
+        codeFor(response.status, reason),
+        `Lighthouse ${init.method || "GET"} ${path} failed: HTTP ${response.status} ${reason}`.trim() +
+          (PLAN_REFUSAL.test(reason) ? " (the account's plan does not include this)" : ""),
+      );
+    }
+    return response;
+  };
+
+  /** One page of the account listing, normalised to backend entries. */
+  const listFiles = async (listOptions = {}) => {
+    const query = new URLSearchParams({
+      lastKey: listOptions.cursor ?? "null",
+      fileType: listOptions.fileType || "all",
+    });
+    const response = await call(`${api}/api/user/files_uploaded?${query}`, {
+      headers: authHeaders({ "Content-Type": "application/json" }),
+    });
+    const body = await response.json();
+    const files = body?.data?.fileList || body?.fileList || [];
+    return files.map((file) => ({
+      id: file.cid,
+      cid: file.cid,
+      backend: "lighthouse",
+      size: Number(file.fileSizeInBytes) || undefined,
+      // Deletion addresses Lighthouse's own file id, not the CID.
+      fileId: file.id,
+      insertedAt: file.createdAt,
+      raw: file,
+    }));
+  };
+
+  return defineBackend({
+    name: "lighthouse",
+
+    capabilities: {
+      // No pin-by-CID endpoint: the bytes have to travel.
+      pinByCid: false,
+      // dag/import unpacks a CAR and keeps the CIDs inside — opt-in, see carImport above.
+      carImport,
+      // A plain /api/v0/add is hashed by Lighthouse with its own chunker and always comes
+      // back as UnixFS or raw -- never dag-cbor -- so an OrbitDB block cannot be stored
+      // under its own CID here. Backups go up as a CAR.
+      preservesInnerCids: false,
+      browserSafeAuth: options.keyOwnership === "user",
+      delegation: false,
+      listing: true,
+      deletion: true,
+      minBlobSize: 0,
+    },
+
+    /** @type {import("./types.js").StorageBackend["putBlob"]} */
+    putBlob: async (bytes, meta = {}) => {
+      const name = meta.name || "blob";
+      const type = meta.type || "application/octet-stream";
+      const isCar = carImport && (meta.car ?? type === CAR_MIME);
+
+      // No path in the file's own name: backupDatabase names files `<space>/backup-…`,
+      // and a Kubo-shaped add turns a path into folders and answers for those too. The
+      // SDK sends the base name for the same reason. dag/import wants a .car name.
+      const baseName = name.split("/").filter(Boolean).pop() || "blob";
+      const fileName = isCar && !/\.car$/i.test(baseName) ? `${baseName}.car` : baseName;
+
+      const form = new FormData();
+      form.append("file", new File([bytes], fileName, { type }));
+
+      const url = isCar
+        ? `${node}/api/v0/dag/import`
+        : `${node}/api/v0/add?wrap-with-directory=false&cid-version=1`;
+
+      const response = await fetch(url, {
+        method: "POST",
+        headers: authHeaders(),
+        body: form,
+      });
+      if (!response.ok) {
+        const reason = await reasonOf(response);
+        throw new BackendError(
+          codeFor(response.status, reason),
+          `Lighthouse upload failed: HTTP ${response.status} ${reason}`.trim() +
+            (PLAN_REFUSAL.test(reason) ? " (the account's plan does not include uploads)" : ""),
+        );
+      }
+
+      const entries = parseEntries(await response.text());
+      const data = entries.find((entry) => entry?.Name === fileName) ?? entries[0] ?? {};
+      const cid = data.Hash || data.cid || data.Root?.Cid?.["/"];
+      if (!cid) {
+        throw new BackendError(
+          "UNSUPPORTED",
+          `Lighthouse accepted the upload but returned no CID: ${JSON.stringify(data).slice(0, 200)}`,
+        );
+      }
+
+      return {
+        id: cid,
+        // Only an imported CAR comes back under a CID that is ours — its root. A plain
+        // upload is hashed by Lighthouse, so its CID names their encoding of our bytes.
+        ...(isCar ? { cid } : {}),
+        backend: "lighthouse",
+        size: Number(data.Size ?? bytes.length),
+        raw: data,
+      };
+    },
+
+    /** @type {import("./types.js").StorageBackend["getBlob"]} */
+    getBlob: async (handle) => {
+      const cid = handleId(handle);
+      let response;
+      // A 429 says "not now", not "not there": wait as told, a few times.
+      for (let attempt = 0; ; attempt++) {
+        response = await fetch(`${gateway}/ipfs/${cid}`);
+        if (response.status !== 429 || attempt >= gatewayRetries) break;
+        await response.body?.cancel();
+        await sleep(retryWait(response, attempt));
+      }
+      if (!response.ok) {
+        const reason = await reasonOf(response);
+        throw new BackendError(
+          "NOT_FOUND",
+          `Lighthouse gateway did not serve ${cid}: HTTP ${response.status}` +
+            (reason ? ` "${reason}"` : "") +
+            (response.status === 402
+              ? " (402 is what this gateway answers for content it does not hold)"
+              : "") +
+            (response.status === 429 ? ` (still rate limited after ${gatewayRetries} retries)` : ""),
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+
+    /** @type {import("./types.js").StorageBackend["list"]} */
+    list: listFiles,
+
+    /** @type {import("./types.js").StorageBackend["remove"]} */
+    remove: async (handle) => {
+      let fileId = typeof handle === "object" ? handle?.fileId : undefined;
+
+      if (!fileId) {
+        // putBlob does not learn the file id, so a delete usually has to look it up.
+        // Match on the CID and refuse rather than guess: this account is paid for once
+        // and its files are meant to be permanent.
+        const cid = handleId(handle);
+        const entries = await listFiles();
+        const match = entries.find((entry) => entry.cid === cid);
+        if (!match?.fileId) {
+          throw new BackendError(
+            "NOT_FOUND",
+            `No Lighthouse file found for ${cid} in the first page of the listing; pass the listed entry to delete it`,
+          );
+        }
+        fileId = match.fileId;
+      }
+
+      await call(
+        `${api}/api/user/delete_file?id=${encodeURIComponent(fileId)}`,
+        {
+          method: "DELETE",
+          headers: authHeaders({ "Content-Type": "application/json" }),
+        },
+      );
+    },
+  });
+}
+
+export default createLighthouseBackend;

package/lib/backends/memory.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview In-process storage backend for OrbitDB Storage Bridge
+ *
+ * The reference driver: everything the contract asks for, nothing a network can add.
+ * It exists so the conformance suite has a baseline that cannot fail for reasons of
+ * its own, and so demos and tests can run a full backup/restore cycle with no service,
+ * no credentials and no wallet.
+ *
+ * Ids are real CIDs — raw codec, sha-256 — so a caller that treats the id as content
+ * addressed is not learning a habit that only works here.
+ *
+ * @author @NiKrause
+ * @requires ./types.js - the backend contract
+ */
+
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import * as raw from "multiformats/codecs/raw";
+import { defineBackend, handleId, BackendError } from "./types.js";
+
+/**
+ * Create an in-process backend.
+ *
+ * @param {object} [options]
+ * @param {Map<string, Uint8Array>} [options.store] - bring your own map to inspect it from a test
+ * @param {(cid: string) => Promise<Uint8Array|null>} [options.resolve] - when given, the
+ *   backend can pin by CID: `pinCid()` calls this to fetch the bytes, the way a real
+ *   pinning service fetches from the IPFS network. Declaring `pinByCid` follows from it.
+ * @returns {import("./types.js").StorageBackend}
+ */
+export function createMemoryBackend(options = {}) {
+  const store = options.store || new Map();
+  const resolve = options.resolve;
+
+  const put = async (bytes, meta = {}) => {
+    const digest = await sha256.digest(bytes);
+    const cid = CID.create(1, raw.code, digest).toString();
+    // Copied, not referenced. A real backend serialises the bytes onto a wire,
+    // so a caller can reuse its buffer afterwards without touching what was
+    // stored; holding the caller's array here would make this driver the one
+    // place that behaves differently, and it is the driver every other one is
+    // measured against.
+    store.set(cid, bytes.slice());
+    return {
+      id: cid,
+      cid,
+      backend: "memory",
+      size: bytes.length,
+      ...(meta.name ? { name: meta.name } : {}),
+    };
+  };
+
+  const backend = {
+    name: "memory",
+
+    capabilities: {
+      pinByCid: Boolean(resolve),
+      carImport: false,
+      // the bytes are handed back exactly as they arrived, keyed by their own
+      // hash — and by copy, so "exactly as they arrived" survives a caller that
+      // reuses its buffer
+      preservesInnerCids: true,
+      browserSafeAuth: true,
+      delegation: false,
+      listing: true,
+      deletion: true,
+      minBlobSize: 0,
+    },
+
+    putBlob: put,
+
+    getBlob: async (handle) => {
+      const id = handleId(handle);
+      const bytes = store.get(id);
+      if (!bytes) {
+        throw new BackendError("NOT_FOUND", `No blob for ${id}`);
+      }
+      // Likewise on the way out: what the caller does to this must not reach
+      // back into the store.
+      return bytes.slice();
+    },
+
+    list: async () =>
+      Array.from(store.entries()).map(([cid, bytes]) => ({
+        id: cid,
+        cid,
+        backend: "memory",
+        size: bytes.length,
+      })),
+
+    remove: async (handle) => {
+      store.delete(handleId(handle));
+    },
+  };
+
+  if (resolve) {
+    backend.pinCid = async (cid, meta = {}) => {
+      const key = String(cid);
+      const bytes = await resolve(key);
+      if (!bytes) {
+        throw new BackendError("NOT_FOUND", `Cannot resolve ${cid} to pin it`);
+      }
+
+      // Pinning stores the bytes under the CID it was handed. Re-deriving one here
+      // would silently re-code the block -- a dag-cbor entry pinned as raw keeps its
+      // digest and loses its codec, which reads as success and restores as garbage.
+      const parsed = CID.parse(key);
+      if (parsed.multihash.code !== sha256.code) {
+        throw new BackendError(
+          "UNSUPPORTED",
+          `${cid} is not sha-256 addressed; this backend cannot verify it`,
+        );
+      }
+      const rehashed = CID.create(
+        parsed.version,
+        parsed.code,
+        await sha256.digest(bytes),
+      );
+      if (rehashed.toString() !== key) {
+        throw new BackendError(
+          "NOT_FOUND",
+          `Resolved bytes for ${cid} do not hash to it`,
+        );
+      }
+
+      store.set(key, bytes);
+      return {
+        id: key,
+        cid: key,
+        backend: "memory",
+        size: bytes.length,
+        ...(meta.name ? { name: meta.name } : {}),
+      };
+    };
+  }
+
+  return defineBackend(backend);
+}
+
+export default createMemoryBackend;