@tinycloud/replica 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,897 @@
+// src/engine.ts
+import { blake3 } from "@noble/hashes/blake3";
+import { bytesToHex } from "@noble/hashes/utils";
+
+// src/errors.ts
+var ReplicaErrorCode = {
+  /** Another process holds the sync lease. */
+  BUSY: "REPLICA_BUSY",
+  /** No replica with this name exists. */
+  NOT_FOUND: "REPLICA_NOT_FOUND",
+  /** The replica exists but its stored configuration differs from the request. */
+  CONFIG_MISMATCH: "REPLICA_CONFIG_MISMATCH",
+  /** The runtime has no supported durable store (e.g. Node < 22.13). */
+  RUNTIME_UNSUPPORTED: "RUNTIME_UNSUPPORTED",
+  /** The local store failed (I/O, corruption, schema). */
+  STORAGE_ERROR: "STORAGE_ERROR",
+  /** The local disk is full. */
+  STORAGE_FULL: "STORAGE_FULL",
+  /** The key is outside the replica's prefix. */
+  NOT_COVERED: "NOT_COVERED",
+  /** Syncing the secrets space or the vault namespace needs an explicit opt-in. */
+  SECRETS_OPT_IN_REQUIRED: "SECRETS_OPT_IN_REQUIRED",
+  /** No grant is installed, or none covers the requested scope. */
+  GRANT_MISSING: "GRANT_MISSING",
+  /** The grant bytes are not a verifiable UCAN, or its signature is wrong. */
+  GRANT_INVALID: "GRANT_INVALID",
+  /** SIWE/CACAO and other non-UCAN grants cannot be used for a replica. */
+  GRANT_FORMAT_UNSUPPORTED: "GRANT_FORMAT_UNSUPPORTED",
+  /** The grant was issued to a different device. */
+  GRANT_AUDIENCE_MISMATCH: "GRANT_AUDIENCE_MISMATCH",
+  /** The grant lacks `tinycloud.kv/sync` or `tinycloud.kv/get` on the prefix. */
+  GRANT_NOT_COVERING: "GRANT_NOT_COVERING",
+  GRANT_NOT_YET_VALID: "GRANT_NOT_YET_VALID",
+  GRANT_EXPIRED: "GRANT_EXPIRED",
+  GRANT_REVOKED: "GRANT_REVOKED",
+  /** The node refused the invocation for a reason other than revocation. */
+  GRANT_UNAUTHORIZED: "GRANT_UNAUTHORIZED",
+  /** The node refused the retention grant. */
+  RETENTION_GRANT_REFUSED: "RETENTION_GRANT_REFUSED",
+  /** The node could not be reached. */
+  NETWORK_ERROR: "NETWORK_ERROR",
+  /** The node answered with an unexpected status. */
+  NODE_ERROR: "NODE_ERROR",
+  /** The node's answer violates the wire contract. */
+  PROTOCOL_ERROR: "PROTOCOL_ERROR",
+  /** The node asked for a fresh bootstrap (410). Handled inside sync. */
+  RESET_REQUIRED: "RESET_REQUIRED",
+  /** The feed now comes from a different node than the one pinned. */
+  SOURCE_CHANGED: "SOURCE_CHANGED",
+  /** The feed delivered a key outside the replica's prefix. */
+  SCOPE_VIOLATION: "SCOPE_VIOLATION",
+  /** Fetched bytes do not hash to the ETag the node attested for them. */
+  CONTENT_MISMATCH: "CONTENT_MISMATCH",
+  /** A stored blob no longer hashes to its name. */
+  INTEGRITY_ERROR: "INTEGRITY_ERROR"
+};
+var REPLICA_ERROR = /* @__PURE__ */ Symbol.for("tinycloud.replica.error");
+var ReplicaError = class extends Error {
+  [REPLICA_ERROR] = true;
+  code;
+  detail;
+  constructor(code, message, detail, options) {
+    super(message, options);
+    this.name = "ReplicaError";
+    this.code = code;
+    if (detail !== void 0) this.detail = detail;
+  }
+};
+function isReplicaError(error, code) {
+  return typeof error === "object" && error !== null && error[REPLICA_ERROR] === true && (code === void 0 || error.code === code);
+}
+
+// src/scope.ts
+function kvPrefixCovers(prefix, key) {
+  if (prefix === "") return true;
+  if (prefix.endsWith("/")) return key.startsWith(prefix);
+  return key === prefix || key.startsWith(`${prefix}/`);
+}
+function requiresSecretsOptIn(space, prefix) {
+  if (space === "secrets" || space.endsWith(":secrets")) return true;
+  const firstSegment = prefix.split("/", 1)[0];
+  return firstSegment === "vault";
+}
+function hashFromEtag(etag) {
+  const match = /^"?blake3-([0-9a-f]{64})"?$/.exec(etag);
+  return match?.[1];
+}
+var RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+function isInstant(value) {
+  return RFC3339.test(value) && Number.isFinite(Date.parse(value));
+}
+function minIso(a, bSeconds) {
+  if (bSeconds === null) return a;
+  const b = new Date(bSeconds * 1e3).toISOString();
+  if (a === null) return b;
+  return Date.parse(a) <= Date.parse(b) ? a : b;
+}
+function maxIso(a, bSeconds) {
+  if (bSeconds === null) return a;
+  const b = new Date(bSeconds * 1e3).toISOString();
+  if (a === null) return b;
+  return Date.parse(a) >= Date.parse(b) ? a : b;
+}
+function effectiveAuthority(input) {
+  const notBefore = maxIso(input.window?.notBefore ?? null, input.grant?.notBefore ?? null);
+  const expiresAt = minIso(input.window?.expiresAt ?? null, input.grant?.expiresAt ?? null);
+  const retainUntil = input.policy === "retainAfterExpiry" ? input.window?.retainUntil ?? null : null;
+  let state = "valid";
+  if (input.revoked !== null) state = "revoked";
+  else if (notBefore !== null && input.now < Date.parse(notBefore)) state = "not-yet-valid";
+  else if (expiresAt !== null && input.now >= Date.parse(expiresAt)) state = "expired";
+  return { state, notBefore, expiresAt, retainUntil, retentionRevoked: (input.retentionRevoked ?? null) !== null };
+}
+function assertReadable(authority, now) {
+  switch (authority.state) {
+    case "valid":
+      return "valid";
+    case "revoked":
+      throw new ReplicaError(ReplicaErrorCode.GRANT_REVOKED, "The replica's grant was revoked; local reads are blocked.");
+    case "not-yet-valid":
+      throw new ReplicaError(
+        ReplicaErrorCode.GRANT_NOT_YET_VALID,
+        `The replica's grant is not valid before ${authority.notBefore}.`
+      );
+    case "expired":
+      if (authority.retentionRevoked) {
+        throw new ReplicaError(
+          ReplicaErrorCode.GRANT_REVOKED,
+          `The replica's grant expired at ${authority.expiresAt} and its retention grant was revoked; local reads are blocked.`
+        );
+      }
+      if (authority.retainUntil !== null && now < Date.parse(authority.retainUntil)) return "expired";
+      throw new ReplicaError(
+        ReplicaErrorCode.GRANT_EXPIRED,
+        authority.retainUntil === null ? `The replica's grant expired at ${authority.expiresAt}; local reads are blocked.` : `The replica's retention ended at ${authority.retainUntil}; local reads are blocked.`
+      );
+  }
+}
+
+// src/engine.ts
+var DEFAULT_PAGE_LIMIT = 500;
+var DEFAULT_LEASE_TTL_MS = 12e4;
+var FETCH_CHUNK = 100;
+var REPAIR_BATCH = 100;
+var RETENTION_REVOKED = /* @__PURE__ */ new Set(["retention-grant-revoked", "retention-grant-ancestor-revoked"]);
+var PENDING_REFUSALS = /* @__PURE__ */ new Set([
+  ReplicaErrorCode.GRANT_UNAUTHORIZED,
+  ReplicaErrorCode.GRANT_EXPIRED,
+  ReplicaErrorCode.GRANT_NOT_YET_VALID
+]);
+function contentHash(bytes) {
+  return bytesToHex(blake3(bytes));
+}
+function sameEtag(a, b) {
+  return a.replace(/^"|"$/g, "") === b.replace(/^"|"$/g, "");
+}
+function lastErrorOf(error, at) {
+  return {
+    at: new Date(at).toISOString(),
+    code: isReplicaError(error) ? error.code : "ERROR",
+    message: error instanceof Error ? error.message : String(error)
+  };
+}
+var Replica = class {
+  #store;
+  #transportFor;
+  #now;
+  #leaseTtlMs;
+  constructor(options) {
+    this.#store = options.store;
+    const transport = options.transport;
+    this.#transportFor = options.transportFor ?? (transport === void 0 ? void 0 : () => transport);
+    this.#now = options.now ?? Date.now;
+    this.#leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+  }
+  async #state() {
+    const state = await this.#store.open();
+    if (state === null) throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, "The replica has not been created.");
+    return state;
+  }
+  /** Throws unless local reads are allowed now; returns the meta every read reports. */
+  #readMeta(state) {
+    const now = this.#now();
+    const authority = assertReadable(
+      effectiveAuthority({
+        window: state.authority,
+        grant: state.grant,
+        revoked: state.revoked,
+        retentionRevoked: state.retentionRevoked,
+        policy: state.config.localReadPolicy,
+        now
+      }),
+      now
+    );
+    return {
+      consistency: "observed",
+      source: { host: state.config.host, nodeDid: state.nodeDid, space: state.config.space, prefix: state.config.prefix },
+      asOf: state.lastSyncAt,
+      coverage: state.coverage,
+      authority
+    };
+  }
+  /**
+   * Authority again, from the store's current state and the clock, once the
+   * read has its data: a revocation (and its purge) or an expiry that landed
+   * while the read ran wins, and the caller gets the error, not the data.
+   */
+  async #confirmedMeta() {
+    return this.#readMeta(await this.#state());
+  }
+  async get(key, options = {}) {
+    const state = await this.#state();
+    this.#readMeta(state);
+    if (!kvPrefixCovers(state.config.prefix, key)) return { status: "not_covered", key, meta: await this.#confirmedMeta() };
+    for (let attempt = 0; ; attempt += 1) {
+      const entry = await this.#store.get(key);
+      if (entry === void 0) {
+        const status = state.coverage === "complete" ? "absent" : "coverage_incomplete";
+        return { status, key, meta: await this.#confirmedMeta() };
+      }
+      if (entry.deleted) return { status: "deleted", key, meta: await this.#confirmedMeta() };
+      if (!entry.content) {
+        return { status: "content_missing", key, etag: entry.etag, metadata: entry.metadata, meta: await this.#confirmedMeta() };
+      }
+      const value = await this.#store.readContent(entry.hash);
+      const intact = value !== void 0 && (options.verify === false || contentHash(value) === entry.hash);
+      if (intact) {
+        return { status: "present", key, value, etag: entry.etag, metadata: entry.metadata, meta: await this.#confirmedMeta() };
+      }
+      if (attempt === 0) continue;
+      await this.#confirmedMeta();
+      throw new ReplicaError(
+        ReplicaErrorCode.INTEGRITY_ERROR,
+        value === void 0 ? `The stored content for ${JSON.stringify(key)} is missing.` : `The stored content for ${JSON.stringify(key)} does not match its hash.`,
+        { key }
+      );
+    }
+  }
+  /** Live keys under `prefix` (a plain string prefix within the replica's scope). */
+  async list(options = {}) {
+    const state = await this.#state();
+    this.#readMeta(state);
+    const scope = state.config.prefix;
+    const prefix = options.prefix ?? "";
+    if (prefix !== "" && !scope.startsWith(prefix) && !kvPrefixCovers(scope, prefix)) {
+      throw new ReplicaError(
+        ReplicaErrorCode.NOT_COVERED,
+        `${JSON.stringify(prefix)} is outside the replica's prefix ${JSON.stringify(scope)}.`
+      );
+    }
+    const rows = await this.#store.list(options);
+    const entries = [];
+    for (const row of rows) {
+      if (row.deleted) continue;
+      entries.push({ key: row.key, etag: row.etag, metadata: row.metadata, content: row.content });
+    }
+    return { entries, meta: await this.#confirmedMeta() };
+  }
+  async status() {
+    await this.#state();
+    return this.#store.status(this.#now());
+  }
+  /** Clear entries, blobs, cursor and the source pin; keep the configuration and grant. */
+  async reset(reason) {
+    await this.#state();
+    const lease = await this.#store.acquireSyncLease(this.#leaseTtlMs);
+    if (lease === null) throw new ReplicaError(ReplicaErrorCode.BUSY, "Another process is syncing this replica.");
+    try {
+      await this.#store.reset(lease, reason);
+    } finally {
+      await this.#store.releaseLease(lease);
+    }
+  }
+  /**
+   * Sync under the pending grant if there is one, else the active grant. If
+   * the node refuses a pending grant before anything committed under it, the
+   * active grant serves: a revoked pending grant is discarded, any other
+   * refusal is recorded on it. A revocation of the grant serving the replica,
+   * learned anywhere in the sync, purges the replica before this returns.
+   */
+  async sync(options = {}) {
+    const transportFor = this.#transportFor;
+    if (transportFor === void 0) throw new Error("Replica.sync needs a transport");
+    const initial = await this.#state();
+    if (initial.revoked !== null) {
+      throw new ReplicaError(ReplicaErrorCode.GRANT_REVOKED, `The replica's grant was revoked: ${initial.revoked}`);
+    }
+    const candidates = [initial.pendingGrant, initial.grant].filter((grant) => grant !== null);
+    if (candidates.length === 0) throw new ReplicaError(ReplicaErrorCode.GRANT_MISSING, "No grant is installed for this replica.");
+    const lease = await this.#store.acquireSyncLease(this.#leaseTtlMs);
+    if (lease === null) throw new ReplicaError(ReplicaErrorCode.BUSY, "Another process is syncing this replica.");
+    try {
+      for (const [index, grant] of candidates.entries()) {
+        const pending = grant.cid === initial.pendingGrant?.cid;
+        const attempt = {
+          lease,
+          grant,
+          transport: transportFor(grant),
+          promote: pending ? grant : null,
+          signal: options.signal
+        };
+        try {
+          return await this.#syncUnder(attempt, options.limit ?? DEFAULT_PAGE_LIMIT);
+        } catch (error) {
+          const canFallBack = pending && attempt.promote !== null && index < candidates.length - 1;
+          if (canFallBack && isReplicaError(error, ReplicaErrorCode.GRANT_REVOKED)) {
+            await this.#store.discardPendingGrant(grant.cid, error.message);
+            continue;
+          }
+          if (canFallBack && isReplicaError(error) && PENDING_REFUSALS.has(error.code)) {
+            await this.#store.recordPendingGrantError(grant.cid, lastErrorOf(error, this.#now()));
+            continue;
+          }
+          throw error;
+        }
+      }
+      throw new Error("unreachable: the last candidate either returns or throws");
+    } catch (error) {
+      await this.#learn(error);
+      throw error;
+    } finally {
+      await this.#store.releaseLease(lease).catch(() => void 0);
+    }
+  }
+  /** Persist what a failed sync taught us before the error reaches the caller. */
+  async #learn(error) {
+    if (isReplicaError(error, ReplicaErrorCode.GRANT_REVOKED)) {
+      if ((await this.#store.open())?.revoked != null) return;
+      await this.#store.markRevoked(error.message);
+      return;
+    }
+    if (isReplicaError(error, ReplicaErrorCode.RETENTION_GRANT_REFUSED)) {
+      const cid = error.detail?.retentionGrantCid;
+      const reason = error.detail?.reason;
+      if (typeof cid === "string" && typeof reason === "string" && RETENTION_REVOKED.has(reason)) {
+        await this.#store.markRetentionRevoked(cid, error.message);
+        return;
+      }
+    }
+    await this.#store.recordError(lastErrorOf(error, this.#now())).catch(() => void 0);
+  }
+  /** The effective window for `grant` under `window`; throws unless it holds now (no retention for syncing). */
+  #syncWindow(window, grant) {
+    const now = this.#now();
+    const authority = effectiveAuthority({ window, grant, revoked: null, policy: "whileGrantValid", now });
+    if (authority.state !== "valid") assertReadable({ ...authority, retainUntil: null }, now);
+    return { notBefore: authority.notBefore, expiresAt: authority.expiresAt };
+  }
+  async #syncUnder(attempt, limit) {
+    const state = await this.#state();
+    const { config } = state;
+    this.#syncWindow(attempt.promote === null ? state.authority : null, attempt.grant);
+    const report = {
+      pages: 0,
+      changes: 0,
+      deleted: 0,
+      fetched: 0,
+      contentMissing: 0,
+      repaired: 0,
+      resets: 0,
+      coverage: state.coverage,
+      cursorAdvanced: false,
+      promotedGrant: false,
+      blobsCollected: 0
+    };
+    let cursor = state.cursor;
+    let pinned = state.nodeDid;
+    let coverage = state.coverage;
+    for (; ; ) {
+      let page;
+      const retentionGrant = config.retentionGrantCid;
+      try {
+        page = await attempt.transport.syncPage({
+          prefix: config.prefix,
+          ...cursor === null ? {} : { cursor },
+          limit,
+          ...retentionGrant === null ? {} : { retentionGrant },
+          ...attempt.signal === void 0 ? {} : { signal: attempt.signal }
+        });
+      } catch (error) {
+        if (isReplicaError(error, ReplicaErrorCode.RESET_REQUIRED) && report.resets === 0) {
+          const reason = typeof error.detail?.reason === "string" ? error.detail.reason : "reset-required";
+          await this.#store.reset(attempt.lease, `node: ${reason}`, { keepSource: true });
+          report.resets += 1;
+          cursor = null;
+          coverage = "empty";
+          continue;
+        }
+        if (isReplicaError(error, ReplicaErrorCode.RETENTION_GRANT_REFUSED) && retentionGrant !== null) {
+          throw new ReplicaError(error.code, error.message, { ...error.detail, retentionGrantCid: retentionGrant }, { cause: error });
+        }
+        throw error;
+      }
+      this.#checkPage(page, config.space, config.prefix, pinned);
+      const window = this.#syncWindow(page.authority, attempt.grant);
+      const verified = await this.#verify(page, attempt);
+      coverage = page.more ? coverage === "complete" ? "complete" : "bootstrapping" : "complete";
+      const at = new Date(this.#now()).toISOString();
+      await this.#store.applyPage(attempt.lease, {
+        changes: verified.changes,
+        blobs: verified.blobs,
+        cursor: page.cursor,
+        source: page.source,
+        authority: page.authority,
+        coverage,
+        at,
+        window,
+        complete: !page.more,
+        promoteGrant: attempt.promote
+      });
+      if (attempt.promote !== null) {
+        report.promotedGrant = true;
+        attempt.promote = null;
+      }
+      report.pages += 1;
+      report.changes += page.changes.length;
+      report.deleted += page.changes.filter((change) => change.deleted).length;
+      report.fetched += verified.fetched;
+      if (page.cursor !== cursor) report.cursorAdvanced = true;
+      cursor = page.cursor;
+      pinned = page.source.nodeDid;
+      await this.#store.renewLease(attempt.lease, this.#leaseTtlMs);
+      if (!page.more) break;
+    }
+    report.repaired = await this.#repair(attempt, cursor, pinned, coverage);
+    report.blobsCollected = await this.#store.collectGarbage(attempt.lease);
+    report.coverage = coverage;
+    report.contentMissing = (await this.#store.pendingRepairs(Number.MAX_SAFE_INTEGER)).length;
+    return report;
+  }
+  #checkPage(page, space, prefix, pinnedNodeDid) {
+    if (page.source.space !== space || page.source.prefix !== prefix) {
+      throw new ReplicaError(
+        ReplicaErrorCode.PROTOCOL_ERROR,
+        `The node answered for ${page.source.space}/${page.source.prefix}, not ${space}/${prefix}.`
+      );
+    }
+    for (const [name, value] of Object.entries(page.authority)) {
+      if (value !== null && (typeof value !== "string" || !isInstant(value))) {
+        throw new ReplicaError(
+          ReplicaErrorCode.PROTOCOL_ERROR,
+          `The node attested authority.${name} = ${JSON.stringify(value)}, which is not a timestamp; nothing was committed.`
+        );
+      }
+    }
+    if (pinnedNodeDid !== null && page.source.nodeDid !== pinnedNodeDid) {
+      throw new ReplicaError(
+        ReplicaErrorCode.SOURCE_CHANGED,
+        `The feed now comes from ${page.source.nodeDid}, not the pinned source ${pinnedNodeDid}. Reset the replica to follow a new source.`,
+        { pinned: pinnedNodeDid, received: page.source.nodeDid }
+      );
+    }
+    for (const change of page.changes) {
+      if (!kvPrefixCovers(prefix, change.key)) {
+        throw new ReplicaError(
+          ReplicaErrorCode.SCOPE_VIOLATION,
+          `The feed delivered ${JSON.stringify(change.key)}, outside the prefix ${JSON.stringify(prefix)}.`,
+          { key: change.key }
+        );
+      }
+    }
+  }
+  async #verify(page, attempt) {
+    const blobs = /* @__PURE__ */ new Map();
+    const changes = [];
+    const candidates = [];
+    for (const change of page.changes) {
+      if (change.deleted) {
+        changes.push({ key: change.key, deleted: true });
+        continue;
+      }
+      const hash = hashFromEtag(change.etag);
+      if (hash === void 0) {
+        throw new ReplicaError(ReplicaErrorCode.PROTOCOL_ERROR, `The feed sent an ETag that is not blake3: ${change.etag}`, {
+          key: change.key
+        });
+      }
+      const previous = await this.#store.get(change.key);
+      const unchanged = previous !== void 0 && !previous.deleted && previous.etag === change.etag && previous.content;
+      changes.push({ key: change.key, deleted: false, etag: change.etag, hash, metadata: change.metadata, content: unchanged });
+      if (!unchanged) candidates.push({ index: changes.length - 1, key: change.key, etag: change.etag, hash });
+    }
+    const held = await this.#store.hasContent([...new Set(candidates.map((candidate) => candidate.hash))]);
+    const needed = candidates.filter((candidate) => {
+      if (!held.has(candidate.hash)) return true;
+      changes[candidate.index].content = true;
+      return false;
+    });
+    let fetched2 = 0;
+    for (let start = 0; start < needed.length; start += FETCH_CHUNK) {
+      const chunk = needed.slice(start, start + FETCH_CHUNK);
+      const contents = await attempt.transport.fetchContent(
+        chunk.map((candidate) => candidate.key),
+        attempt.signal === void 0 ? void 0 : { signal: attempt.signal }
+      );
+      for (const candidate of chunk) {
+        const ok = acceptContent(candidate, contents.get(candidate.key));
+        if (ok === void 0) continue;
+        blobs.set(candidate.hash, ok);
+        changes[candidate.index].content = true;
+        fetched2 += 1;
+      }
+      await this.#store.renewLease(attempt.lease, this.#leaseTtlMs);
+    }
+    return { changes, blobs, fetched: fetched2 };
+  }
+  async #repair(attempt, cursor, nodeDid, coverage) {
+    const pending = await this.#store.pendingRepairs(Number.MAX_SAFE_INTEGER);
+    let repaired = 0;
+    for (let start = 0; start < pending.length; start += REPAIR_BATCH) {
+      const chunk = pending.slice(start, start + REPAIR_BATCH);
+      const contents = await attempt.transport.fetchContent(
+        chunk.map((entry) => entry.key),
+        attempt.signal === void 0 ? void 0 : { signal: attempt.signal }
+      );
+      const blobs = /* @__PURE__ */ new Map();
+      const changes = [];
+      for (const entry of chunk) {
+        const bytes = acceptContent(entry, contents.get(entry.key));
+        if (bytes === void 0) continue;
+        blobs.set(entry.hash, bytes);
+        changes.push({ ...entry, content: true });
+      }
+      await this.#store.renewLease(attempt.lease, this.#leaseTtlMs);
+      if (changes.length === 0) continue;
+      const state = await this.#state();
+      await this.#store.applyPage(attempt.lease, {
+        changes,
+        blobs,
+        cursor,
+        source: { nodeDid: nodeDid ?? "", space: state.config.space, prefix: state.config.prefix },
+        authority: null,
+        coverage,
+        at: new Date(this.#now()).toISOString(),
+        window: this.#syncWindow(state.authority, attempt.grant),
+        complete: false,
+        promoteGrant: null
+      });
+      repaired += changes.length;
+    }
+    return repaired;
+  }
+};
+function acceptContent(expected, fetched2) {
+  if (fetched2 === void 0 || "missing" in fetched2) return void 0;
+  if (contentHash(fetched2.bytes) === expected.hash) return fetched2.bytes;
+  if (sameEtag(fetched2.etag, expected.etag)) {
+    throw new ReplicaError(
+      ReplicaErrorCode.CONTENT_MISMATCH,
+      `The content of ${JSON.stringify(expected.key)} does not hash to its ETag ${expected.etag}.`,
+      { key: expected.key }
+    );
+  }
+  return void 0;
+}
+
+// src/grant.ts
+import { ed25519 } from "@noble/curves/ed25519";
+import { blake3 as blake32 } from "@noble/hashes/blake3";
+var BASE58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+function base58Decode(text) {
+  let value = 0n;
+  for (const char of text) {
+    const digit = BASE58.indexOf(char);
+    if (digit < 0) throw new Error("invalid base58");
+    value = value * 58n + BigInt(digit);
+  }
+  const bytes = [];
+  while (value > 0n) {
+    bytes.unshift(Number(value & 0xffn));
+    value >>= 8n;
+  }
+  for (const char of text) {
+    if (char !== "1") break;
+    bytes.unshift(0);
+  }
+  return Uint8Array.from(bytes);
+}
+function base32Encode(bytes) {
+  let out = "";
+  let buffer = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    buffer = buffer << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += BASE32[buffer >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += BASE32[buffer << 5 - bits & 31];
+  return out;
+}
+function base64UrlDecode(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) throw new Error("invalid base64url");
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  const binary = globalThis.atob(padded);
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+function ucanCid(jwt) {
+  const digest = blake32(new TextEncoder().encode(jwt));
+  const bytes = new Uint8Array(4 + digest.length);
+  bytes.set([1, 85, 30, 32]);
+  bytes.set(digest, 4);
+  return `b${base32Encode(bytes)}`;
+}
+function ed25519KeyOfDid(did) {
+  const bare = did.split("#", 1)[0];
+  if (!bare.startsWith("did:key:z")) return void 0;
+  let decoded;
+  try {
+    decoded = base58Decode(bare.slice("did:key:z".length));
+  } catch {
+    return void 0;
+  }
+  if (decoded.length !== 34 || decoded[0] !== 237 || decoded[1] !== 1) return void 0;
+  return decoded.subarray(2);
+}
+function invalid(message) {
+  return new ReplicaError(ReplicaErrorCode.GRANT_INVALID, message);
+}
+function parseUcanGrant(input) {
+  const raw = typeof input === "string" ? input : new TextDecoder().decode(input);
+  const jwt = raw.trim().replace(/^Bearer\s+/i, "");
+  const parts = jwt.split(".");
+  if (parts.length !== 3) {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_FORMAT_UNSUPPORTED,
+      "The grant is not a compact UCAN. SIWE/CACAO grants cannot back a replica; ask the owner for a device grant (tc auth grant)."
+    );
+  }
+  const [headerPart, payloadPart, signaturePart] = parts;
+  let header;
+  let payload;
+  let signature;
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64UrlDecode(headerPart)));
+    payload = JSON.parse(new TextDecoder().decode(base64UrlDecode(payloadPart)));
+    signature = base64UrlDecode(signaturePart);
+  } catch {
+    throw invalid("The grant is not well-formed base64url JSON.");
+  }
+  if (header?.alg !== "EdDSA") {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_FORMAT_UNSUPPORTED,
+      `The grant is signed with ${String(header?.alg)}; a replica needs an Ed25519 (EdDSA) device grant.`
+    );
+  }
+  const issuer = payload?.iss;
+  const audience = payload?.aud;
+  if (typeof issuer !== "string" || typeof audience !== "string" || audience.length === 0) {
+    throw invalid("The grant has no signed issuer or audience.");
+  }
+  const key = ed25519KeyOfDid(issuer);
+  if (key === void 0) {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_FORMAT_UNSUPPORTED,
+      `The grant issuer ${issuer} is not an Ed25519 did:key.`
+    );
+  }
+  let verified = false;
+  try {
+    verified = ed25519.verify(signature, new TextEncoder().encode(`${headerPart}.${payloadPart}`), key);
+  } catch {
+    verified = false;
+  }
+  if (!verified) throw invalid("The grant's signature does not verify against its issuer.");
+  const att = payload.att;
+  if (att === null || typeof att !== "object" || Array.isArray(att)) throw invalid("The grant has no signed attenuation.");
+  for (const abilities of Object.values(att)) {
+    if (abilities === null || typeof abilities !== "object" || Array.isArray(abilities)) {
+      throw invalid("The grant has a malformed signed attenuation.");
+    }
+  }
+  const prf = payload.prf ?? [];
+  if (!Array.isArray(prf) || prf.some((proof) => typeof proof !== "string")) throw invalid("The grant has malformed signed proofs.");
+  const window = (name) => {
+    const value = payload[name];
+    if (value === void 0 || value === null) return null;
+    if (typeof value !== "number" || !Number.isFinite(value)) throw invalid(`The grant's signed ${name} is not a number.`);
+    return value;
+  };
+  return {
+    cid: ucanCid(jwt),
+    bytes: new TextEncoder().encode(jwt),
+    jwt,
+    issuer,
+    audience,
+    notBefore: window("nbf"),
+    expiresAt: window("exp"),
+    att,
+    prf
+  };
+}
+function kvPathIn(resource, space) {
+  for (const base of [`${space}/kv/`, `tinycloud://${space}/kv/`]) {
+    if (resource.startsWith(base)) return resource.slice(base.length);
+  }
+  return void 0;
+}
+function grantCovers(grant, space, prefix, ability) {
+  for (const [resource, abilities] of Object.entries(grant.att)) {
+    const path = kvPathIn(resource, space);
+    if (path === void 0 || !kvPrefixCovers(path, prefix)) continue;
+    if (ability in abilities) return true;
+    if (ability !== "tinycloud.kv/sync" && ability !== "tinycloud.kv/retain" && "tinycloud.kv/*" in abilities) return true;
+  }
+  return false;
+}
+function syncGrantSpaces(grant) {
+  const spaces = /* @__PURE__ */ new Set();
+  for (const [resource, abilities] of Object.entries(grant.att)) {
+    if (!("tinycloud.kv/sync" in abilities)) continue;
+    const match = /^(?:tinycloud:\/\/)?(tinycloud:[^/]+)\/kv\//.exec(resource);
+    if (match) spaces.add(match[1]);
+  }
+  return [...spaces];
+}
+function assertGrantInstallable(grant, input) {
+  if (grant.audience.split("#", 1)[0] !== input.deviceDid.split("#", 1)[0]) {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_AUDIENCE_MISMATCH,
+      `The grant was issued to ${grant.audience}, not this device (${input.deviceDid}).`
+    );
+  }
+  for (const ability of ["tinycloud.kv/sync", "tinycloud.kv/get"]) {
+    if (!grantCovers(grant, input.space, input.prefix, ability)) {
+      throw new ReplicaError(
+        ReplicaErrorCode.GRANT_NOT_COVERING,
+        `The grant does not carry ${ability} on ${input.space}/kv/${input.prefix}.`,
+        { ability }
+      );
+    }
+  }
+  const nowSeconds = input.now / 1e3;
+  if (grant.notBefore !== null && nowSeconds < grant.notBefore) {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_NOT_YET_VALID,
+      `The grant is not valid before ${new Date(grant.notBefore * 1e3).toISOString()}.`
+    );
+  }
+  if (grant.expiresAt !== null && nowSeconds >= grant.expiresAt) {
+    throw new ReplicaError(
+      ReplicaErrorCode.GRANT_EXPIRED,
+      `The grant expired at ${new Date(grant.expiresAt * 1e3).toISOString()}.`
+    );
+  }
+}
+
+// src/transport.ts
+var REVOKED_CODES = /* @__PURE__ */ new Set(["AUTH_DELEGATION_REVOKED", "AUTH_DELEGATION_ANCESTOR_REVOKED"]);
+var REVOKED_BODY = /^(?:Invalid invocation: )?(?:delegation-revoked: [A-Za-z0-9]+|delegation-ancestor-revoked: ancestor=[A-Za-z0-9]+ (?:invoked|parent)=[A-Za-z0-9]+)$/;
+function isRevocation(error, status, request) {
+  if (REVOKED_CODES.has(error.code)) return true;
+  if (status !== 401 || request === void 0) return false;
+  const lead = `${request}: 401 - `;
+  return error.message.startsWith(lead) && REVOKED_BODY.test(error.message.slice(lead.length));
+}
+function replicaErrorFromService(error, context, request) {
+  const meta = error.meta ?? {};
+  const status = typeof meta.status === "number" ? meta.status : void 0;
+  const detail = { serviceCode: error.code, ...status === void 0 ? {} : { status } };
+  const reason = typeof meta.reason === "string" ? meta.reason : void 0;
+  if (error.code === "KV_SYNC_RESET_REQUIRED" || status === 410) {
+    return new ReplicaError(
+      ReplicaErrorCode.RESET_REQUIRED,
+      `${context}: the node requires a fresh bootstrap (${reason ?? "reason not given"}).`,
+      { ...detail, reason: reason ?? "reset-required" }
+    );
+  }
+  if (isRevocation(error, status, request)) {
+    return new ReplicaError(ReplicaErrorCode.GRANT_REVOKED, `${context}: ${error.message}`, detail);
+  }
+  if (error.code === "KV_RETENTION_GRANT_REFUSED") {
+    return new ReplicaError(ReplicaErrorCode.RETENTION_GRANT_REFUSED, `${context}: ${error.message}`, {
+      ...detail,
+      ...reason === void 0 ? {} : { reason }
+    });
+  }
+  if (status === 401 || status === 403 || /^AUTH_/.test(error.code)) {
+    if (/expired/i.test(error.message)) {
+      return new ReplicaError(ReplicaErrorCode.GRANT_EXPIRED, `${context}: ${error.message}`, detail);
+    }
+    return new ReplicaError(ReplicaErrorCode.GRANT_UNAUTHORIZED, `${context}: ${error.message}`, detail);
+  }
+  if (status !== void 0) {
+    return new ReplicaError(ReplicaErrorCode.NODE_ERROR, `${context}: ${error.message}`, detail);
+  }
+  if (error.code === "NETWORK_ERROR" || /TIMEOUT|ABORT/.test(error.code)) {
+    return new ReplicaError(ReplicaErrorCode.NETWORK_ERROR, `${context}: ${error.message}`, detail);
+  }
+  return new ReplicaError(ReplicaErrorCode.NODE_ERROR, `${context}: ${error.message}`, detail);
+}
+var encoder = new TextEncoder();
+function compareKeyBytes(a, b) {
+  const x = encoder.encode(a);
+  const y = encoder.encode(b);
+  for (let index = 0; index < Math.min(x.length, y.length); index += 1) {
+    if (x[index] !== y[index]) return x[index] - y[index];
+  }
+  return x.length - y.length;
+}
+function isNotFound(error) {
+  return error.code === "KV_NOT_FOUND" || error.code === "NOT_FOUND";
+}
+function instant(value) {
+  if (value === null) return null;
+  if (typeof value === "string" && isInstant(value)) return value;
+  throw new ReplicaError(ReplicaErrorCode.PROTOCOL_ERROR, `The kv/sync authority holds a bound that is not a timestamp: ${JSON.stringify(value)}.`);
+}
+function checkPage(data) {
+  const ok = data !== null && typeof data === "object" && Array.isArray(data.changes) && typeof data.more === "boolean" && typeof data.cursor === "string" && typeof data.source?.nodeDid === "string" && typeof data.source?.space === "string" && typeof data.source?.prefix === "string" && data.authority !== null && typeof data.authority === "object" && data.changes.every(
+    (change) => typeof change?.key === "string" && (change.deleted === true || change.deleted === false && typeof change.etag === "string" && change.metadata !== null && typeof change.metadata === "object" && Object.values(change.metadata).every((value) => typeof value === "string"))
+  );
+  if (!ok) throw new ReplicaError(ReplicaErrorCode.PROTOCOL_ERROR, "The kv/sync response does not match the wire contract.");
+  return {
+    changes: data.changes.map(
+      (change) => change.deleted ? { key: change.key, deleted: true } : { key: change.key, deleted: false, etag: change.etag, metadata: { ...change.metadata } }
+    ),
+    more: data.more,
+    cursor: data.cursor,
+    source: { nodeDid: data.source.nodeDid, space: data.source.space, prefix: data.source.prefix },
+    authority: {
+      notBefore: instant(data.authority.notBefore),
+      expiresAt: instant(data.authority.expiresAt),
+      retainUntil: instant(data.authority.retainUntil)
+    }
+  };
+}
+function fetched(key, result, request) {
+  if (!result.ok) {
+    if (isNotFound(result.error)) return { missing: true };
+    throw replicaErrorFromService(result.error, `Fetching ${JSON.stringify(key)}`, request);
+  }
+  if (!(result.data.data instanceof Uint8Array)) {
+    throw new ReplicaError(ReplicaErrorCode.PROTOCOL_ERROR, `The value of ${JSON.stringify(key)} did not arrive as bytes.`);
+  }
+  return { bytes: result.data.data, etag: result.data.headers.etag ?? "" };
+}
+function kvSyncTransport(kv) {
+  return {
+    async syncPage({ prefix, cursor, limit, retentionGrant, signal }) {
+      const result = await kv.changes({
+        prefix,
+        limit,
+        ...cursor === void 0 ? {} : { cursor },
+        ...retentionGrant === void 0 ? {} : { retentionGrant },
+        ...signal === void 0 ? {} : { signal }
+      });
+      if (!result.ok) throw replicaErrorFromService(result.error, "Syncing");
+      return checkPage(result.data);
+    },
+    async fetchContent(keys, options) {
+      const contents = /* @__PURE__ */ new Map();
+      if (keys.length === 0) return contents;
+      const signal = options?.signal;
+      const ordered = [...keys].sort(compareKeyBytes);
+      const batch = await kv.batchGet(ordered, { binary: true, ...signal === void 0 ? {} : { signal } });
+      if (batch.ok) {
+        for (const item of batch.data.results) {
+          const result = item.result;
+          if (!result.ok && result.error.code === "KV_RESPONSE_TOO_LARGE") continue;
+          contents.set(item.key, fetched(item.key, result, `Failed to get key ${JSON.stringify(item.key)}`));
+        }
+      } else if (batch.error.code !== "KV_RESPONSE_TOO_LARGE") {
+        throw replicaErrorFromService(batch.error, `Fetching ${keys.length} value(s)`, `Failed to batch read ${ordered.length} key(s)`);
+      }
+      for (const key of keys) {
+        if (contents.has(key)) continue;
+        const request = `Failed to get key ${JSON.stringify(key)}`;
+        contents.set(key, fetched(key, await kv.get(key, { binary: true, ...signal === void 0 ? {} : { signal } }), request));
+      }
+      return contents;
+    }
+  };
+}
+export {
+  Replica,
+  ReplicaError,
+  ReplicaErrorCode,
+  assertGrantInstallable,
+  assertReadable,
+  contentHash,
+  effectiveAuthority,
+  grantCovers,
+  hashFromEtag,
+  isReplicaError,
+  kvPrefixCovers,
+  kvSyncTransport,
+  parseUcanGrant,
+  replicaErrorFromService,
+  requiresSecretsOptIn,
+  syncGrantSpaces,
+  ucanCid
+};
+//# sourceMappingURL=index.js.map