@aigne/afs-did-space 1.12.0-beta.5

package/dist/run-gc.cjs

@@ -0,0 +1,57 @@
+const require_object_key = require('./object-key.cjs');
+
+//#region src/run-gc.ts
+/** 7 days — the sole protection for behind/offline devices (design §0.2, §7). */
+const DEFAULT_GC_GRACE_MS = 10080 * 60 * 1e3;
+const DEFAULT_GC_LIMIT = 500;
+async function runGc(o) {
+	const limit = o.limit ?? DEFAULT_GC_LIMIT;
+	const graceMs = o.graceMs ?? DEFAULT_GC_GRACE_MS;
+	const nowMs = Date.now();
+	const candidates = await o.queue.fetchCandidates(limit, graceMs);
+	const stats = {
+		candidates: candidates.length,
+		deleted: [],
+		skipped: [],
+		errors: []
+	};
+	for (const { cid } of candidates) {
+		try {
+			require_object_key.assertValidCid(cid);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			stats.errors.push({
+				cid,
+				error: msg
+			});
+			o.log?.(`[gc] skip invalid cid: ${msg}`);
+			try {
+				await o.queue.remove(cid);
+			} catch {}
+			continue;
+		}
+		try {
+			if (await o.referencedAnywhere(cid, nowMs)) {
+				await o.queue.remove(cid);
+				stats.skipped.push(cid);
+			} else {
+				await o.objectStore.delete(require_object_key.objectKeyForCid(cid));
+				await o.queue.remove(cid);
+				stats.deleted.push(cid);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			stats.errors.push({
+				cid,
+				error: msg
+			});
+			o.log?.(`[gc] error on cid ${cid}: ${msg}`);
+		}
+	}
+	o.log?.(JSON.stringify(stats));
+	return stats;
+}
+
+//#endregion
+exports.DEFAULT_GC_GRACE_MS = DEFAULT_GC_GRACE_MS;
+exports.runGc = runGc;

package/dist/run-gc.d.cts

@@ -0,0 +1,40 @@
+import { ObjectStore } from "./platform/r2/dist/types.cjs";
+import { GcQueue } from "./gc-queue.cjs";
+
+//#region src/run-gc.d.ts
+/** 7 days — the sole protection for behind/offline devices (design §0.2, §7). */
+declare const DEFAULT_GC_GRACE_MS: number;
+interface RunGcOptions {
+  queue: GcQueue;
+  /**
+   * scope-blind liveness — entries ∪ non-expired prepared upload sessions
+   * (reference-check.ts). `nowMs` is the sweep-start time, passed so the whole
+   * sweep judges prepared-session expiry against ONE consistent clock (design
+   * §9). Ad-hoc callers may omit it (the impls default to Date.now()).
+   */
+  referencedAnywhere(cid: string, nowMs: number): Promise<boolean>;
+  objectStore: ObjectStore;
+  /** max candidates per sweep (default 500). */
+  limit?: number;
+  /** grace window (default 7d). `runGc` owns the canonical value and passes it
+   * explicitly to `fetchCandidates`, so a queue impl's own default is never relied upon. */
+  graceMs?: number;
+  log?: (line: string) => void;
+}
+interface GcStats {
+  /** number of candidates fetched this sweep. */
+  candidates: number;
+  /** cids whose object was deleted. */
+  deleted: string[];
+  /** cids kept because still referenced (object NOT deleted). */
+  skipped: string[];
+  /** cids that errored (invalid cid, or delete/remove threw). */
+  errors: Array<{
+    cid: string;
+    error: string;
+  }>;
+}
+declare function runGc(o: RunGcOptions): Promise<GcStats>;
+//#endregion
+export { DEFAULT_GC_GRACE_MS, GcStats, RunGcOptions, runGc };
+//# sourceMappingURL=run-gc.d.cts.map

package/dist/run-gc.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gc.d.cts","names":[],"sources":["../src/run-gc.ts"],"mappings":";;;;;cA+Ba,mBAAA;AAAA,UAGI,YAAA;EACf,KAAA,EAAO,OAAA;EAiBQ;;;;;;EAVf,kBAAA,CAAmB,GAAA,UAAa,KAAA,WAAgB,OAAA;EAChD,WAAA,EAAa,WAAA;EAiBL;EAfR,KAAA;EAe6B;;EAZ7B,OAAA;EACA,GAAA,IAAO,IAAA;AAAA;AAAA,UAGQ,OAAA;EAWc;EAT7B,UAAA;EAS4C;EAP5C,OAAA;EAOmD;EALnD,OAAA;EAK0B;EAH1B,MAAA,EAAQ,KAAA;IAAQ,GAAA;IAAa,KAAA;EAAA;AAAA;AAAA,iBAGT,KAAA,CAAM,CAAA,EAAG,YAAA,GAAe,OAAA,CAAQ,OAAA"}

package/dist/run-gc.d.mts

@@ -0,0 +1,41 @@
+import { ObjectStore } from "./providers/platform/r2/dist/types.mjs";
+import "./providers/platform/r2/dist/index.mjs";
+import { GcQueue } from "./gc-queue.mjs";
+
+//#region src/run-gc.d.ts
+/** 7 days — the sole protection for behind/offline devices (design §0.2, §7). */
+declare const DEFAULT_GC_GRACE_MS: number;
+interface RunGcOptions {
+  queue: GcQueue;
+  /**
+   * scope-blind liveness — entries ∪ non-expired prepared upload sessions
+   * (reference-check.ts). `nowMs` is the sweep-start time, passed so the whole
+   * sweep judges prepared-session expiry against ONE consistent clock (design
+   * §9). Ad-hoc callers may omit it (the impls default to Date.now()).
+   */
+  referencedAnywhere(cid: string, nowMs: number): Promise<boolean>;
+  objectStore: ObjectStore;
+  /** max candidates per sweep (default 500). */
+  limit?: number;
+  /** grace window (default 7d). `runGc` owns the canonical value and passes it
+   * explicitly to `fetchCandidates`, so a queue impl's own default is never relied upon. */
+  graceMs?: number;
+  log?: (line: string) => void;
+}
+interface GcStats {
+  /** number of candidates fetched this sweep. */
+  candidates: number;
+  /** cids whose object was deleted. */
+  deleted: string[];
+  /** cids kept because still referenced (object NOT deleted). */
+  skipped: string[];
+  /** cids that errored (invalid cid, or delete/remove threw). */
+  errors: Array<{
+    cid: string;
+    error: string;
+  }>;
+}
+declare function runGc(o: RunGcOptions): Promise<GcStats>;
+//#endregion
+export { DEFAULT_GC_GRACE_MS, GcStats, RunGcOptions, runGc };
+//# sourceMappingURL=run-gc.d.mts.map

package/dist/run-gc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gc.d.mts","names":[],"sources":["../src/run-gc.ts"],"mappings":";;;;;;cA+Ba,mBAAA;AAAA,UAGI,YAAA;EACf,KAAA,EAAO,OAAA;EAcY;AAGrB;;;;;EAVE,kBAAA,CAAmB,GAAA,UAAa,KAAA,WAAgB,OAAA;EAChD,WAAA,EAAa,WAAA;EAiBb;EAfA,KAAA;EAegB;;EAZhB,OAAA;EACA,GAAA,IAAO,IAAA;AAAA;AAAA,UAGQ,OAAA;;EAEf,UAAA;EASoD;EAPpD,OAAA;EAOmD;EALnD,OAAA;EAK6B;EAH7B,MAAA,EAAQ,KAAA;IAAQ,GAAA;IAAa,KAAA;EAAA;AAAA;AAAA,iBAGT,KAAA,CAAM,CAAA,EAAG,YAAA,GAAe,OAAA,CAAQ,OAAA"}

package/dist/run-gc.mjs

@@ -0,0 +1,57 @@
+import { assertValidCid, objectKeyForCid } from "./object-key.mjs";
+
+//#region src/run-gc.ts
+/** 7 days — the sole protection for behind/offline devices (design §0.2, §7). */
+const DEFAULT_GC_GRACE_MS = 10080 * 60 * 1e3;
+const DEFAULT_GC_LIMIT = 500;
+async function runGc(o) {
+	const limit = o.limit ?? DEFAULT_GC_LIMIT;
+	const graceMs = o.graceMs ?? DEFAULT_GC_GRACE_MS;
+	const nowMs = Date.now();
+	const candidates = await o.queue.fetchCandidates(limit, graceMs);
+	const stats = {
+		candidates: candidates.length,
+		deleted: [],
+		skipped: [],
+		errors: []
+	};
+	for (const { cid } of candidates) {
+		try {
+			assertValidCid(cid);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			stats.errors.push({
+				cid,
+				error: msg
+			});
+			o.log?.(`[gc] skip invalid cid: ${msg}`);
+			try {
+				await o.queue.remove(cid);
+			} catch {}
+			continue;
+		}
+		try {
+			if (await o.referencedAnywhere(cid, nowMs)) {
+				await o.queue.remove(cid);
+				stats.skipped.push(cid);
+			} else {
+				await o.objectStore.delete(objectKeyForCid(cid));
+				await o.queue.remove(cid);
+				stats.deleted.push(cid);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			stats.errors.push({
+				cid,
+				error: msg
+			});
+			o.log?.(`[gc] error on cid ${cid}: ${msg}`);
+		}
+	}
+	o.log?.(JSON.stringify(stats));
+	return stats;
+}
+
+//#endregion
+export { DEFAULT_GC_GRACE_MS, runGc };
+//# sourceMappingURL=run-gc.mjs.map

package/dist/run-gc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gc.mjs","names":[],"sources":["../src/run-gc.ts"],"sourcesContent":["/**\n * runGc — the shared, runtime-agnostic object-GC sweeper (design §4.5).\n *\n * Storage-agnostic: it takes a `GcQueue` (where candidates live), a\n * `referencedAnywhere` callback (scope-blind, entries-only liveness — §4.4b),\n * and an `ObjectStore`. Node passes `SqliteGcQueue` + `referencedAnywhereLibsql`\n * + `FsObjectStore`; Cloudflare passes `D1GCQueue` + `referencedAnywhereD1` +\n * raw R2. Both call the SAME sweeper.\n *\n * Per candidate:\n *   1. `assertValidCid(cid)` — a poisoned queue row (`\"../_metadata.db\"`) is\n *      logged + recorded as an error and the row is dropped; the object store is\n *      NEVER asked to delete a traversal key (§4.5 P0-safety).\n *   2. re-check `referencedAnywhere(cid)` FRESH, immediately before delete (never\n *      snapshotted at fetch) — together with the §4.7 write-dequeue this shrinks\n *      the re-reference race window to sub-ms.\n *   3. referenced ⇒ keep the object, drop the queue row (`skipped`).\n *      unreferenced ⇒ `objectStore.delete(objectKeyForCid(cid))` then drop the\n *      row (`deleted`).\n *\n * Per-item try/catch: one bad cid never aborts the batch. On an operational\n * error (delete/remove threw) the row is LEFT for the next run — delete is\n * idempotent, so a crash between delete and remove is retried safely and never\n * loses a live object.\n */\n\nimport type { ObjectStore } from \"@aigne/afs-r2\";\nimport type { GcQueue } from \"./gc-queue.js\";\nimport { assertValidCid, objectKeyForCid } from \"./object-key.js\";\n\n/** 7 days — the sole protection for behind/offline devices (design §0.2, §7). */\nexport const DEFAULT_GC_GRACE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_GC_LIMIT = 500;\n\nexport interface RunGcOptions {\n  queue: GcQueue;\n  /**\n   * scope-blind liveness — entries ∪ non-expired prepared upload sessions\n   * (reference-check.ts). `nowMs` is the sweep-start time, passed so the whole\n   * sweep judges prepared-session expiry against ONE consistent clock (design\n   * §9). Ad-hoc callers may omit it (the impls default to Date.now()).\n   */\n  referencedAnywhere(cid: string, nowMs: number): Promise<boolean>;\n  objectStore: ObjectStore;\n  /** max candidates per sweep (default 500). */\n  limit?: number;\n  /** grace window (default 7d). `runGc` owns the canonical value and passes it\n   * explicitly to `fetchCandidates`, so a queue impl's own default is never relied upon. */\n  graceMs?: number;\n  log?: (line: string) => void;\n}\n\nexport interface GcStats {\n  /** number of candidates fetched this sweep. */\n  candidates: number;\n  /** cids whose object was deleted. */\n  deleted: string[];\n  /** cids kept because still referenced (object NOT deleted). */\n  skipped: string[];\n  /** cids that errored (invalid cid, or delete/remove threw). */\n  errors: Array<{ cid: string; error: string }>;\n}\n\nexport async function runGc(o: RunGcOptions): Promise<GcStats> {\n  const limit = o.limit ?? DEFAULT_GC_LIMIT;\n  const graceMs = o.graceMs ?? DEFAULT_GC_GRACE_MS;\n  // ONE sweep-start clock, threaded into every liveness check so prepared-session\n  // expiry is judged uniformly across the whole sweep (design §9).\n  const nowMs = Date.now();\n  const candidates = await o.queue.fetchCandidates(limit, graceMs);\n\n  const stats: GcStats = { candidates: candidates.length, deleted: [], skipped: [], errors: [] };\n\n  for (const { cid } of candidates) {\n    // (1) Validate FIRST — a poisoned row must never reach objectStore.delete\n    // with a traversal key. Drop the garbage row (it can never be a valid object\n    // or reference) and record it; keep sweeping.\n    try {\n      assertValidCid(cid);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      stats.errors.push({ cid, error: msg });\n      o.log?.(`[gc] skip invalid cid: ${msg}`);\n      try {\n        await o.queue.remove(cid);\n      } catch {\n        // leave the poison row if even removal fails; it stays visible next run.\n      }\n      continue;\n    }\n\n    try {\n      // (2) FRESH liveness re-check at delete time (never snapshotted).\n      if (await o.referencedAnywhere(cid, nowMs)) {\n        // (3a) still referenced — keep the object, drop the queue row.\n        await o.queue.remove(cid);\n        stats.skipped.push(cid);\n      } else {\n        // (3b) orphan — delete the object, then drop the row. Idempotent: a\n        // crash before `remove` is retried and the already-gone delete no-ops.\n        await o.objectStore.delete(objectKeyForCid(cid));\n        await o.queue.remove(cid);\n        stats.deleted.push(cid);\n      }\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      stats.errors.push({ cid, error: msg });\n      o.log?.(`[gc] error on cid ${cid}: ${msg}`);\n      // leave the row for the next run (delete is idempotent; no live object lost).\n    }\n  }\n\n  o.log?.(JSON.stringify(stats));\n  return stats;\n}\n"],"mappings":";;;;AA+BA,MAAa,sBAAsB,QAAc,KAAK;AACtD,MAAM,mBAAmB;AA+BzB,eAAsB,MAAM,GAAmC;CAC7D,MAAM,QAAQ,EAAE,SAAS;CACzB,MAAM,UAAU,EAAE,WAAW;CAG7B,MAAM,QAAQ,KAAK,KAAK;CACxB,MAAM,aAAa,MAAM,EAAE,MAAM,gBAAgB,OAAO,QAAQ;CAEhE,MAAM,QAAiB;EAAE,YAAY,WAAW;EAAQ,SAAS,EAAE;EAAE,SAAS,EAAE;EAAE,QAAQ,EAAE;EAAE;AAE9F,MAAK,MAAM,EAAE,SAAS,YAAY;AAIhC,MAAI;AACF,kBAAe,IAAI;WACZ,KAAK;GACZ,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAC5D,SAAM,OAAO,KAAK;IAAE;IAAK,OAAO;IAAK,CAAC;AACtC,KAAE,MAAM,0BAA0B,MAAM;AACxC,OAAI;AACF,UAAM,EAAE,MAAM,OAAO,IAAI;WACnB;AAGR;;AAGF,MAAI;AAEF,OAAI,MAAM,EAAE,mBAAmB,KAAK,MAAM,EAAE;AAE1C,UAAM,EAAE,MAAM,OAAO,IAAI;AACzB,UAAM,QAAQ,KAAK,IAAI;UAClB;AAGL,UAAM,EAAE,YAAY,OAAO,gBAAgB,IAAI,CAAC;AAChD,UAAM,EAAE,MAAM,OAAO,IAAI;AACzB,UAAM,QAAQ,KAAK,IAAI;;WAElB,KAAK;GACZ,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAC5D,SAAM,OAAO,KAAK;IAAE;IAAK,OAAO;IAAK,CAAC;AACtC,KAAE,MAAM,qBAAqB,IAAI,IAAI,MAAM;;;AAK/C,GAAE,MAAM,KAAK,UAAU,MAAM,CAAC;AAC9B,QAAO"}

package/dist/scope-id.cjs

@@ -0,0 +1,70 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _arcblock_did = require("@arcblock/did");
+let _noble_hashes_hmac_js = require("@noble/hashes/hmac.js");
+let _noble_hashes_sha2_js = require("@noble/hashes/sha2.js");
+let _noble_hashes_utils_js = require("@noble/hashes/utils.js");
+let multiformats_bases_base32 = require("multiformats/bases/base32");
+
+//#region src/scope-id.ts
+/**
+* scope-id — scope de-identification primitives (README §4.2 / §4.4 / §4.5).
+*
+* The DID Space "storage scope" is normally the plaintext `normalizeId(DID)`.
+* When a deployment opts into de-identification (by providing a per-deployment
+* HMAC secret), the storage scope becomes an opaque HMAC of the DID, so a D1
+* dump / R2 replica leak cannot be attributed back to a specific user.
+*
+* These are PURE functions, shared verbatim by CF + Node runtimes AND by the
+* offline migration scripts. The runtime and the migration script MUST derive
+* scopes with the SAME `decodeScopeHmacSecret` + `deriveScope` to stay
+* addressable — see README §4.4 "编码定死".
+*
+* - HMAC must be SYNCHRONOUS (tree-index constructors run synchronously in the
+*   request path). WebCrypto `subtle.sign` is async; `node:crypto` is absent on
+*   CF Workers. `@noble/hashes` is the only synchronous, cross-runtime option.
+* - base32 reuses did-space's existing `multiformats` dependency.
+*/
+/**
+* Derive an opaque storage scope from a normalized DID + HMAC secret.
+*
+* HMAC-SHA256(key, utf8(normalizedDid)) → first 20 bytes → base32 lower, no pad,
+* no prefix → 32 chars (20 × 8 / 5 = 32, naturally unpadded). The result is the
+* final scope; nothing is prefixed. 32 chars fits `entries.scope CHECK(LENGTH<=128)`.
+*
+* Empty key throws (fail-closed): a de-id-disabled caller must not reach here.
+*/
+function deriveScope(normalizedDid, key) {
+	if (!key?.length) throw new Error("scopeHmacSecret missing — refusing to derive (fail-closed)");
+	const mac = (0, _noble_hashes_hmac_js.hmac)(_noble_hashes_sha2_js.sha256, key, (0, _noble_hashes_utils_js.utf8ToBytes)(normalizedDid));
+	return multiformats_bases_base32.base32.baseEncode(mac.subarray(0, 20));
+}
+/**
+* Decode the deployment HMAC secret from its env/config string.
+*
+* Encoding is fixed (README §4.4): hex(32 bytes) → 64 hex chars. Any other
+* decoded length throws — runtime and migration MUST agree byte-for-byte.
+*/
+function decodeScopeHmacSecret(envStr) {
+	const bytes = (0, _noble_hashes_utils_js.hexToBytes)(envStr);
+	if (bytes.length !== 32) throw new Error(`scopeHmacSecret must decode to 32 bytes, got ${bytes.length}`);
+	return bytes;
+}
+/**
+* Is this scope a plaintext DID (i.e. still pending de-id migration)?
+*
+* Uses the authoritative DID validator (`@arcblock/did#isValid`) — never a
+* hand-rolled regex, never the lenient `validateId`. `isValid` accepts the bare
+* normalizeId form (it strips any prefix internally via `toAddress`), so the
+* normalized scope can be checked directly without re-prefixing.
+*
+* Returns false for: versioned content scopes (`schema:pkg:1.2.3`), already
+* derived base32 hashes, bare names (`persona`), `did:web:*`, random strings.
+* This is what makes migration idempotent: a re-run sees derived hashes as
+* non-DID and skips them (README §4.5).
+*/
+const isPlainDidScope = (scope) => (0, _arcblock_did.isValid)(scope);
+
+//#endregion
+exports.decodeScopeHmacSecret = decodeScopeHmacSecret;
+exports.deriveScope = deriveScope;
+exports.isPlainDidScope = isPlainDidScope;

package/dist/scope-id.d.cts

@@ -0,0 +1,35 @@
+//#region src/scope-id.d.ts
+/**
+ * Derive an opaque storage scope from a normalized DID + HMAC secret.
+ *
+ * HMAC-SHA256(key, utf8(normalizedDid)) → first 20 bytes → base32 lower, no pad,
+ * no prefix → 32 chars (20 × 8 / 5 = 32, naturally unpadded). The result is the
+ * final scope; nothing is prefixed. 32 chars fits `entries.scope CHECK(LENGTH<=128)`.
+ *
+ * Empty key throws (fail-closed): a de-id-disabled caller must not reach here.
+ */
+declare function deriveScope(normalizedDid: string, key: Uint8Array): string;
+/**
+ * Decode the deployment HMAC secret from its env/config string.
+ *
+ * Encoding is fixed (README §4.4): hex(32 bytes) → 64 hex chars. Any other
+ * decoded length throws — runtime and migration MUST agree byte-for-byte.
+ */
+declare function decodeScopeHmacSecret(envStr: string): Uint8Array;
+/**
+ * Is this scope a plaintext DID (i.e. still pending de-id migration)?
+ *
+ * Uses the authoritative DID validator (`@arcblock/did#isValid`) — never a
+ * hand-rolled regex, never the lenient `validateId`. `isValid` accepts the bare
+ * normalizeId form (it strips any prefix internally via `toAddress`), so the
+ * normalized scope can be checked directly without re-prefixing.
+ *
+ * Returns false for: versioned content scopes (`schema:pkg:1.2.3`), already
+ * derived base32 hashes, bare names (`persona`), `did:web:*`, random strings.
+ * This is what makes migration idempotent: a re-run sees derived hashes as
+ * non-DID and skips them (README §4.5).
+ */
+declare const isPlainDidScope: (scope: string) => boolean;
+//#endregion
+export { decodeScopeHmacSecret, deriveScope, isPlainDidScope };
+//# sourceMappingURL=scope-id.d.cts.map

package/dist/scope-id.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.d.cts","names":[],"sources":["../src/scope-id.ts"],"mappings":";;AAiCA;;;;;;;;iBAAgB,WAAA,CAAY,aAAA,UAAuB,GAAA,EAAK,UAAA;AAexD;;;;;AAqBA;AArBA,iBAAgB,qBAAA,CAAsB,MAAA,WAAiB,UAAA;;;;;;;;;;;;;;cAqB1C,eAAA,GAAmB,KAAA"}

package/dist/scope-id.d.mts

@@ -0,0 +1,35 @@
+//#region src/scope-id.d.ts
+/**
+ * Derive an opaque storage scope from a normalized DID + HMAC secret.
+ *
+ * HMAC-SHA256(key, utf8(normalizedDid)) → first 20 bytes → base32 lower, no pad,
+ * no prefix → 32 chars (20 × 8 / 5 = 32, naturally unpadded). The result is the
+ * final scope; nothing is prefixed. 32 chars fits `entries.scope CHECK(LENGTH<=128)`.
+ *
+ * Empty key throws (fail-closed): a de-id-disabled caller must not reach here.
+ */
+declare function deriveScope(normalizedDid: string, key: Uint8Array): string;
+/**
+ * Decode the deployment HMAC secret from its env/config string.
+ *
+ * Encoding is fixed (README §4.4): hex(32 bytes) → 64 hex chars. Any other
+ * decoded length throws — runtime and migration MUST agree byte-for-byte.
+ */
+declare function decodeScopeHmacSecret(envStr: string): Uint8Array;
+/**
+ * Is this scope a plaintext DID (i.e. still pending de-id migration)?
+ *
+ * Uses the authoritative DID validator (`@arcblock/did#isValid`) — never a
+ * hand-rolled regex, never the lenient `validateId`. `isValid` accepts the bare
+ * normalizeId form (it strips any prefix internally via `toAddress`), so the
+ * normalized scope can be checked directly without re-prefixing.
+ *
+ * Returns false for: versioned content scopes (`schema:pkg:1.2.3`), already
+ * derived base32 hashes, bare names (`persona`), `did:web:*`, random strings.
+ * This is what makes migration idempotent: a re-run sees derived hashes as
+ * non-DID and skips them (README §4.5).
+ */
+declare const isPlainDidScope: (scope: string) => boolean;
+//#endregion
+export { decodeScopeHmacSecret, deriveScope, isPlainDidScope };
+//# sourceMappingURL=scope-id.d.mts.map

package/dist/scope-id.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.d.mts","names":[],"sources":["../src/scope-id.ts"],"mappings":";;AAiCA;;;;;;;;iBAAgB,WAAA,CAAY,aAAA,UAAuB,GAAA,EAAK,UAAA;AAexD;;;;;AAqBA;AArBA,iBAAgB,qBAAA,CAAsB,MAAA,WAAiB,UAAA;;;;;;;;;;;;;;cAqB1C,eAAA,GAAmB,KAAA"}

package/dist/scope-id.mjs

@@ -0,0 +1,68 @@
+import { isValid } from "@arcblock/did";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { base32 } from "multiformats/bases/base32";
+
+//#region src/scope-id.ts
+/**
+* scope-id — scope de-identification primitives (README §4.2 / §4.4 / §4.5).
+*
+* The DID Space "storage scope" is normally the plaintext `normalizeId(DID)`.
+* When a deployment opts into de-identification (by providing a per-deployment
+* HMAC secret), the storage scope becomes an opaque HMAC of the DID, so a D1
+* dump / R2 replica leak cannot be attributed back to a specific user.
+*
+* These are PURE functions, shared verbatim by CF + Node runtimes AND by the
+* offline migration scripts. The runtime and the migration script MUST derive
+* scopes with the SAME `decodeScopeHmacSecret` + `deriveScope` to stay
+* addressable — see README §4.4 "编码定死".
+*
+* - HMAC must be SYNCHRONOUS (tree-index constructors run synchronously in the
+*   request path). WebCrypto `subtle.sign` is async; `node:crypto` is absent on
+*   CF Workers. `@noble/hashes` is the only synchronous, cross-runtime option.
+* - base32 reuses did-space's existing `multiformats` dependency.
+*/
+/**
+* Derive an opaque storage scope from a normalized DID + HMAC secret.
+*
+* HMAC-SHA256(key, utf8(normalizedDid)) → first 20 bytes → base32 lower, no pad,
+* no prefix → 32 chars (20 × 8 / 5 = 32, naturally unpadded). The result is the
+* final scope; nothing is prefixed. 32 chars fits `entries.scope CHECK(LENGTH<=128)`.
+*
+* Empty key throws (fail-closed): a de-id-disabled caller must not reach here.
+*/
+function deriveScope(normalizedDid, key) {
+	if (!key?.length) throw new Error("scopeHmacSecret missing — refusing to derive (fail-closed)");
+	const mac = hmac(sha256, key, utf8ToBytes(normalizedDid));
+	return base32.baseEncode(mac.subarray(0, 20));
+}
+/**
+* Decode the deployment HMAC secret from its env/config string.
+*
+* Encoding is fixed (README §4.4): hex(32 bytes) → 64 hex chars. Any other
+* decoded length throws — runtime and migration MUST agree byte-for-byte.
+*/
+function decodeScopeHmacSecret(envStr) {
+	const bytes = hexToBytes(envStr);
+	if (bytes.length !== 32) throw new Error(`scopeHmacSecret must decode to 32 bytes, got ${bytes.length}`);
+	return bytes;
+}
+/**
+* Is this scope a plaintext DID (i.e. still pending de-id migration)?
+*
+* Uses the authoritative DID validator (`@arcblock/did#isValid`) — never a
+* hand-rolled regex, never the lenient `validateId`. `isValid` accepts the bare
+* normalizeId form (it strips any prefix internally via `toAddress`), so the
+* normalized scope can be checked directly without re-prefixing.
+*
+* Returns false for: versioned content scopes (`schema:pkg:1.2.3`), already
+* derived base32 hashes, bare names (`persona`), `did:web:*`, random strings.
+* This is what makes migration idempotent: a re-run sees derived hashes as
+* non-DID and skips them (README §4.5).
+*/
+const isPlainDidScope = (scope) => isValid(scope);
+
+//#endregion
+export { decodeScopeHmacSecret, deriveScope, isPlainDidScope };
+//# sourceMappingURL=scope-id.mjs.map

package/dist/scope-id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.mjs","names":[],"sources":["../src/scope-id.ts"],"sourcesContent":["/**\n * scope-id — scope de-identification primitives (README §4.2 / §4.4 / §4.5).\n *\n * The DID Space \"storage scope\" is normally the plaintext `normalizeId(DID)`.\n * When a deployment opts into de-identification (by providing a per-deployment\n * HMAC secret), the storage scope becomes an opaque HMAC of the DID, so a D1\n * dump / R2 replica leak cannot be attributed back to a specific user.\n *\n * These are PURE functions, shared verbatim by CF + Node runtimes AND by the\n * offline migration scripts. The runtime and the migration script MUST derive\n * scopes with the SAME `decodeScopeHmacSecret` + `deriveScope` to stay\n * addressable — see README §4.4 \"编码定死\".\n *\n * - HMAC must be SYNCHRONOUS (tree-index constructors run synchronously in the\n *   request path). WebCrypto `subtle.sign` is async; `node:crypto` is absent on\n *   CF Workers. `@noble/hashes` is the only synchronous, cross-runtime option.\n * - base32 reuses did-space's existing `multiformats` dependency.\n */\nimport { isValid } from \"@arcblock/did\";\nimport { hmac } from \"@noble/hashes/hmac.js\";\nimport { sha256 } from \"@noble/hashes/sha2.js\";\nimport { hexToBytes, utf8ToBytes } from \"@noble/hashes/utils.js\";\nimport { base32 } from \"multiformats/bases/base32\";\n\n/**\n * Derive an opaque storage scope from a normalized DID + HMAC secret.\n *\n * HMAC-SHA256(key, utf8(normalizedDid)) → first 20 bytes → base32 lower, no pad,\n * no prefix → 32 chars (20 × 8 / 5 = 32, naturally unpadded). The result is the\n * final scope; nothing is prefixed. 32 chars fits `entries.scope CHECK(LENGTH<=128)`.\n *\n * Empty key throws (fail-closed): a de-id-disabled caller must not reach here.\n */\nexport function deriveScope(normalizedDid: string, key: Uint8Array): string {\n  if (!key?.length) {\n    throw new Error(\"scopeHmacSecret missing — refusing to derive (fail-closed)\");\n  }\n  const mac = hmac(sha256, key, utf8ToBytes(normalizedDid)); // 32 bytes\n  // `baseEncode` yields the raw base32 alphabet with no multibase prefix.\n  return base32.baseEncode(mac.subarray(0, 20)); // 32 chars\n}\n\n/**\n * Decode the deployment HMAC secret from its env/config string.\n *\n * Encoding is fixed (README §4.4): hex(32 bytes) → 64 hex chars. Any other\n * decoded length throws — runtime and migration MUST agree byte-for-byte.\n */\nexport function decodeScopeHmacSecret(envStr: string): Uint8Array {\n  const bytes = hexToBytes(envStr);\n  if (bytes.length !== 32) {\n    throw new Error(`scopeHmacSecret must decode to 32 bytes, got ${bytes.length}`);\n  }\n  return bytes;\n}\n\n/**\n * Is this scope a plaintext DID (i.e. still pending de-id migration)?\n *\n * Uses the authoritative DID validator (`@arcblock/did#isValid`) — never a\n * hand-rolled regex, never the lenient `validateId`. `isValid` accepts the bare\n * normalizeId form (it strips any prefix internally via `toAddress`), so the\n * normalized scope can be checked directly without re-prefixing.\n *\n * Returns false for: versioned content scopes (`schema:pkg:1.2.3`), already\n * derived base32 hashes, bare names (`persona`), `did:web:*`, random strings.\n * This is what makes migration idempotent: a re-run sees derived hashes as\n * non-DID and skips them (README §4.5).\n */\nexport const isPlainDidScope = (scope: string): boolean => isValid(scope);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,YAAY,eAAuB,KAAyB;AAC1E,KAAI,CAAC,KAAK,OACR,OAAM,IAAI,MAAM,6DAA6D;CAE/E,MAAM,MAAM,KAAK,QAAQ,KAAK,YAAY,cAAc,CAAC;AAEzD,QAAO,OAAO,WAAW,IAAI,SAAS,GAAG,GAAG,CAAC;;;;;;;;AAS/C,SAAgB,sBAAsB,QAA4B;CAChE,MAAM,QAAQ,WAAW,OAAO;AAChC,KAAI,MAAM,WAAW,GACnB,OAAM,IAAI,MAAM,gDAAgD,MAAM,SAAS;AAEjF,QAAO;;;;;;;;;;;;;;;AAgBT,MAAa,mBAAmB,UAA2B,QAAQ,MAAM"}

package/dist/scope-migration-node.cjs

@@ -0,0 +1,172 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_scope_id = require('./scope-id.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let _libsql_client = require("@libsql/client");
+
+//#region src/scope-migration-node.ts
+/**
+* scope-migration-node — offline Node scope de-identification migration (README §5.4).
+*
+* Migrates the existing PLAINTEXT DID-scoped per-user spaces on a local disk to
+* derived HMAC scopes. Unlike the CF migration (one shared D1), Node stores each
+* user under `{rootPath}/{scope}/_metadata.db` + a daemon-global
+* `{rootPath}/_shares.db`, so this is a per-DIRECTORY rename plus a per-db
+* rewrite. OFFLINE tool: the daemon MUST be stopped first (README §5.4).
+*
+* Per directory `{rootPath}/{s}` whose basename `s` is a plaintext DID:
+*   1. Rewrite `_metadata.db` scope columns (entries / changelog /
+*      prefix_watermark) where `scope = s` → `deriveScope(s)`, rewrite the
+*      `sync_state` `{s}:` key prefix (INSERT+DELETE — can't UPDATE a PK; the
+*      bare `device_id` key has no `{s}:` prefix so it is preserved), and clear
+*      `cid_cache` (no scope column, rebuildable). `sync_checkpoint` (transient)
+*      and `gc_queue` (cid-keyed) are untouched. ALL in one atomic batch.
+*   2. `fs.rename` the directory to `{rootPath}/{deriveScope(s)}` — done LAST so
+*      the directory name is the idempotency marker: an interrupted run leaves a
+*      plaintext dir (re-run completes it), and a finished dir is a hash
+*      (`isPlainDidScope` false → skipped). The per-db batch is itself
+*      idempotent (keyed on the old plaintext `s`, a no-op once moved).
+*
+* Then the daemon-global `_shares.db.owner_did` is migrated once (same DID
+* classification). Strict: only true DIDs migrate; versioned / already-derived /
+* junk are skipped + reported, never silently HMAC'd.
+*/
+/** Which of `names` exist as tables in this db. */
+async function existingTables(client, names) {
+	const placeholders = names.map(() => "?").join(", ");
+	const res = await client.execute({
+		sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`,
+		args: names
+	});
+	return new Set((res.rows ?? []).map((r) => r.name));
+}
+/**
+* Rewrite a single per-user `_metadata.db` for the DID scope `s` → derived.
+* Atomic (one write batch). The caller MUST close the client before renaming
+* the directory.
+*
+* Probes table existence first: older `_metadata.db` files predate
+* `prefix_watermark` / `sync_state` / `cid_cache` (added by later phases), so
+* each statement is included ONLY when its table exists — otherwise libsql
+* throws "no such table" and the whole batch aborts. `entries` / `changelog`
+* are the core tables (always present in a real space db).
+*/
+async function migrateNodeMetadataDb(client, s, key) {
+	const h = require_scope_id.deriveScope(s, key);
+	const scopedPrefix = `${s}:`;
+	const derivedPrefix = `${h}:`;
+	const likeOld = `${s}:%`;
+	const present = await existingTables(client, [
+		"ds_entries",
+		"ds_changelog",
+		"ds_prefix_watermark",
+		"ds_dirty_path",
+		"ds_sync_state",
+		"cid_cache"
+	]);
+	const stmts = [];
+	if (present.has("ds_entries")) stmts.push({
+		sql: "UPDATE ds_entries SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_changelog")) stmts.push({
+		sql: "UPDATE ds_changelog SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_prefix_watermark")) stmts.push({
+		sql: "UPDATE ds_prefix_watermark SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_dirty_path")) stmts.push({
+		sql: "UPDATE ds_dirty_path SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_sync_state")) {
+		stmts.push({
+			sql: "INSERT OR IGNORE INTO ds_sync_state(key, value) SELECT replace(key, ?, ?), value FROM ds_sync_state WHERE key LIKE ?",
+			args: [
+				scopedPrefix,
+				derivedPrefix,
+				likeOld
+			]
+		});
+		stmts.push({
+			sql: "DELETE FROM ds_sync_state WHERE key LIKE ?",
+			args: [likeOld]
+		});
+	}
+	if (present.has("cid_cache")) stmts.push({
+		sql: "DELETE FROM cid_cache",
+		args: []
+	});
+	if (stmts.length > 0) await client.batch(stmts, "write");
+}
+/** Migrate `_shares.db.owner_did` for every plaintext-DID owner (one batch). */
+async function migrateNodeShares(sharesPath, key, dryRun) {
+	const client = (0, _libsql_client.createClient)({ url: `file:${sharesPath}` });
+	try {
+		const owners = ((await client.execute("SELECT DISTINCT owner_did AS v FROM ds_shares")).rows ?? []).map((r) => r.v).filter((v) => v != null);
+		const migrate = owners.filter((o) => require_scope_id.isPlainDidScope(o));
+		const skipped = owners.length - migrate.length;
+		if (dryRun || migrate.length === 0) return {
+			migrated: 0,
+			skipped
+		};
+		await client.batch(migrate.map((o) => ({
+			sql: "UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?",
+			args: [require_scope_id.deriveScope(o, key), o]
+		})), "write");
+		return {
+			migrated: migrate.length,
+			skipped
+		};
+	} finally {
+		client.close();
+	}
+}
+/**
+* Migrate (or, with `dryRun`, classify) every plaintext-DID space under
+* `rootPath`, plus the daemon-global `_shares.db`.
+*/
+async function migrateNodeSpaces(opts) {
+	const { rootPath, key, dryRun = false } = opts;
+	const migrate = [];
+	const skip = [];
+	const entries = (0, node_fs.existsSync)(rootPath) ? (0, node_fs.readdirSync)(rootPath, { withFileTypes: true }) : [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		(require_scope_id.isPlainDidScope(entry.name) ? migrate : skip).push(entry.name);
+	}
+	migrate.sort();
+	skip.sort();
+	let renamed = 0;
+	if (!dryRun) for (const s of migrate) {
+		const dir = (0, node_path.join)(rootPath, s);
+		const dbPath = (0, node_path.join)(dir, "_metadata.db");
+		if ((0, node_fs.existsSync)(dbPath)) {
+			const client = (0, _libsql_client.createClient)({ url: `file:${dbPath}` });
+			try {
+				await migrateNodeMetadataDb(client, s, key);
+			} finally {
+				client.close();
+			}
+		}
+		(0, node_fs.renameSync)(dir, (0, node_path.join)(rootPath, require_scope_id.deriveScope(s, key)));
+		renamed++;
+	}
+	const sharesPath = (0, node_path.join)(rootPath, "_shares.db");
+	const shares = (0, node_fs.existsSync)(sharesPath) ? await migrateNodeShares(sharesPath, key, dryRun) : {
+		migrated: 0,
+		skipped: 0
+	};
+	return {
+		migrate,
+		skip,
+		renamed,
+		shares
+	};
+}
+
+//#endregion
+exports.migrateNodeMetadataDb = migrateNodeMetadataDb;
+exports.migrateNodeSpaces = migrateNodeSpaces;

package/dist/scope-migration-node.d.cts

@@ -0,0 +1,44 @@
+import { Client } from "@libsql/client";
+
+//#region src/scope-migration-node.d.ts
+interface NodeScopeMigrationOptions {
+  /** Classify only — list migrate/skip, rewrite + rename nothing. */
+  dryRun?: boolean;
+}
+interface NodeScopeMigrationReport {
+  /** Plaintext DID directory names that WILL be / WERE migrated (sorted). */
+  migrate: string[];
+  /** Non-DID directory names skipped: already-derived hash / versioned / junk (sorted). */
+  skip: string[];
+  /** Count of directories actually renamed (0 when dryRun). */
+  renamed: number;
+  /** `_shares.db` owner_did migration outcome. */
+  shares: {
+    migrated: number;
+    skipped: number;
+  };
+}
+/**
+ * Rewrite a single per-user `_metadata.db` for the DID scope `s` → derived.
+ * Atomic (one write batch). The caller MUST close the client before renaming
+ * the directory.
+ *
+ * Probes table existence first: older `_metadata.db` files predate
+ * `prefix_watermark` / `sync_state` / `cid_cache` (added by later phases), so
+ * each statement is included ONLY when its table exists — otherwise libsql
+ * throws "no such table" and the whole batch aborts. `entries` / `changelog`
+ * are the core tables (always present in a real space db).
+ */
+declare function migrateNodeMetadataDb(client: Client, s: string, key: Uint8Array): Promise<void>;
+/**
+ * Migrate (or, with `dryRun`, classify) every plaintext-DID space under
+ * `rootPath`, plus the daemon-global `_shares.db`.
+ */
+declare function migrateNodeSpaces(opts: {
+  rootPath: string;
+  key: Uint8Array;
+  dryRun?: boolean;
+}): Promise<NodeScopeMigrationReport>;
+//#endregion
+export { NodeScopeMigrationOptions, NodeScopeMigrationReport, migrateNodeMetadataDb, migrateNodeSpaces };
+//# sourceMappingURL=scope-migration-node.d.cts.map