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

package/dist/scope-migration.mjs

@@ -0,0 +1,154 @@
+import { SCOPE_META_FILE_COUNT_BACKFILL_SQL } from "./changelog-schema.mjs";
+import { deriveScope, isPlainDidScope } from "./scope-id.mjs";
+
+//#region src/scope-migration.ts
+/**
+* scope-migration — offline D1 scope de-identification migration (README §4.5).
+*
+* Migrates the existing PLAINTEXT DID scopes in a CF D1 database to derived
+* HMAC scopes, in place. This is an OFFLINE ops tool (not a DDL migration, not
+* on the request path): a local Node process holds the deployment secret,
+* derives scopes with the SAME `deriveScope` the runtime uses, and rewrites the
+* scope columns.
+*
+* Strict / fail-closed classification: only scopes for which
+* `isPlainDidScope` (= `@arcblock/did#isValid`) is true are migrated. Versioned
+* content scopes (`schema:pkg:1.2.3`), already-derived base32 hashes, bare names
+* (`persona`) and junk are SKIPPED and logged — never silently HMAC'd. Because
+* an already-derived hash is not a valid DID, a re-run sees it as non-DID and
+* skips it: the migration is idempotent with no external "done" set.
+*
+* The thin CLI wrapper (runtimes/cloudflare/scripts/migrate-scope.mjs) handles
+* argv + the D1 connection + the STOP GATE print; this module holds the
+* testable logic so `test/migration.test.ts` can drive it against a mock D1.
+*/
+/**
+* Tables with a `scope` column that hold per-user DID-scoped data. `scope_meta`
+* is intentionally absent — it is a derived count and is REBUILT after the
+* scope columns move (UPDATE does not fire the file_count triggers, so a stale
+* plaintext row would remain). `versioned_scopes` / `resolve_entries` /
+* `gc_queue` are exempt by design (README §4.5 matrix).
+*/
+const SCOPE_TABLES = [
+	"ds_entries",
+	"ds_changelog",
+	"ds_prefix_watermark",
+	"ds_device_sync_state",
+	"ds_dirty_path"
+];
+async function tableExists(db, name) {
+	return await db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").bind(name).first() != null;
+}
+async function distinctColumn(db, table, column) {
+	return ((await db.prepare(`SELECT DISTINCT ${column} AS v FROM ${table}`).all()).results ?? []).map((r) => r.v).filter((v) => v != null);
+}
+/**
+* Migrate (or, with `dryRun`, classify) all plaintext DID scopes in `db`.
+*
+* @param db   the D1 database (or a compatible mock) — the bound runtime D1
+* @param key  the deployment HMAC secret bytes (from `decodeScopeHmacSecret`)
+* @param opts `{ dryRun }` to classify without writing
+*/
+async function migrateD1Scopes(db, key, opts = {}) {
+	const tablesPresent = [];
+	for (const t of SCOPE_TABLES) if (await tableExists(db, t)) tablesPresent.push(t);
+	const hasShares = await tableExists(db, "ds_shares");
+	const hasScopeMeta = await tableExists(db, "ds_scope_meta");
+	const candidateSet = /* @__PURE__ */ new Set();
+	for (const t of tablesPresent) for (const s of await distinctColumn(db, t, "scope")) candidateSet.add(s);
+	if (hasShares) for (const s of await distinctColumn(db, "ds_shares", "owner_did")) candidateSet.add(s);
+	const migrate = [];
+	const skip = [];
+	for (const s of candidateSet) (isPlainDidScope(s) ? migrate : skip).push(s);
+	migrate.sort();
+	skip.sort();
+	const base = {
+		tablesPresent,
+		hasShares,
+		hasScopeMeta,
+		candidates: candidateSet.size,
+		migrate,
+		skip,
+		migrated: 0,
+		scopeMetaRebuilt: false
+	};
+	if (opts.dryRun) return base;
+	for (const s of migrate) {
+		const h = deriveScope(s, key);
+		const stmts = tablesPresent.map((t) => db.prepare(`UPDATE ${t} SET scope = ? WHERE scope = ?`).bind(h, s));
+		if (hasShares) stmts.push(db.prepare("UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?").bind(h, s));
+		await db.batch(stmts);
+	}
+	let scopeMetaRebuilt = false;
+	if (hasScopeMeta && migrate.length > 0) {
+		const placeholders = migrate.map(() => "?").join(", ");
+		await db.prepare(`DELETE FROM ds_scope_meta WHERE scope IN (${placeholders})`).bind(...migrate).run();
+		await db.prepare(SCOPE_META_FILE_COUNT_BACKFILL_SQL).run();
+		scopeMetaRebuilt = true;
+	}
+	return {
+		...base,
+		migrated: migrate.length,
+		scopeMetaRebuilt
+	};
+}
+/** Classify distinct scope strings into migrate (plaintext DID) vs skip. */
+function classifyScopes(scopes) {
+	const migrate = [];
+	const skip = [];
+	for (const s of [...new Set(scopes)]) (isPlainDidScope(s) ? migrate : skip).push(s);
+	migrate.sort();
+	skip.sort();
+	return {
+		migrate,
+		skip
+	};
+}
+const SQL_SCOPE_COLUMN_TABLES = [
+	"ds_entries",
+	"ds_changelog",
+	"ds_prefix_watermark",
+	"ds_dirty_path"
+];
+/**
+* Generate the migration `.sql` for a REMOTE CF D1 (README §4.5 离线脚本形态).
+*
+* The HMAC is computed HERE (D1 SQL can't); the operator dumps the distinct
+* scopes with `wrangler d1 execute --remote --json` and applies the emitted file
+* with `wrangler d1 execute --remote --file`. Only plaintext DID scopes are
+* rewritten — versioned `schema:…` / already-derived / junk are left out, so a
+* re-apply is idempotent (their `WHERE scope = '<old DID>'` matches nothing).
+*
+* Statement order matters: all scope UPDATEs first, then the scope_meta rebuild
+* (DELETE stale plaintext rows + BACKFILL derived counts from the now-moved
+* entries). `entries` / `changelog` / `prefix_watermark` are CF's standard
+* scope-bearing tables (migrations 0100–0107); `device_sync_state` is absent.
+*/
+function buildD1MigrationSql(scopes, key, opts = {}) {
+	const { includeShares = true, includeScopeMeta = true } = opts;
+	const { migrate, skip } = classifyScopes(scopes);
+	const q = (v) => `'${v.replace(/'/g, "''")}'`;
+	const lines = [
+		"-- DID Space scope de-identification migration (generated).",
+		"-- Apply with: wrangler d1 execute <DB> --remote --file <this-file>",
+		`-- migrate ${migrate.length} DID scope(s); skip ${skip.length} non-DID scope(s).`
+	];
+	for (const s of migrate) {
+		const h = deriveScope(s, key);
+		for (const t of SQL_SCOPE_COLUMN_TABLES) lines.push(`UPDATE ${t} SET scope = ${q(h)} WHERE scope = ${q(s)};`);
+		if (includeShares) lines.push(`UPDATE ds_shares SET owner_did = ${q(h)} WHERE owner_did = ${q(s)};`);
+	}
+	if (includeScopeMeta && migrate.length > 0) {
+		lines.push(`DELETE FROM ds_scope_meta WHERE scope IN (${migrate.map(q).join(", ")});`);
+		lines.push(`${SCOPE_META_FILE_COUNT_BACKFILL_SQL};`);
+	}
+	return {
+		sql: `${lines.join("\n")}\n`,
+		migrate,
+		skip
+	};
+}
+
+//#endregion
+export { buildD1MigrationSql, classifyScopes, migrateD1Scopes };
+//# sourceMappingURL=scope-migration.mjs.map

package/dist/scope-migration.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration.mjs","names":[],"sources":["../src/scope-migration.ts"],"sourcesContent":["/**\n * scope-migration — offline D1 scope de-identification migration (README §4.5).\n *\n * Migrates the existing PLAINTEXT DID scopes in a CF D1 database to derived\n * HMAC scopes, in place. This is an OFFLINE ops tool (not a DDL migration, not\n * on the request path): a local Node process holds the deployment secret,\n * derives scopes with the SAME `deriveScope` the runtime uses, and rewrites the\n * scope columns.\n *\n * Strict / fail-closed classification: only scopes for which\n * `isPlainDidScope` (= `@arcblock/did#isValid`) is true are migrated. Versioned\n * content scopes (`schema:pkg:1.2.3`), already-derived base32 hashes, bare names\n * (`persona`) and junk are SKIPPED and logged — never silently HMAC'd. Because\n * an already-derived hash is not a valid DID, a re-run sees it as non-DID and\n * skips it: the migration is idempotent with no external \"done\" set.\n *\n * The thin CLI wrapper (runtimes/cloudflare/scripts/migrate-scope.mjs) handles\n * argv + the D1 connection + the STOP GATE print; this module holds the\n * testable logic so `test/migration.test.ts` can drive it against a mock D1.\n */\nimport { SCOPE_META_FILE_COUNT_BACKFILL_SQL } from \"./changelog-schema.js\";\nimport { deriveScope, isPlainDidScope } from \"./scope-id.js\";\n\n/**\n * Tables with a `scope` column that hold per-user DID-scoped data. `scope_meta`\n * is intentionally absent — it is a derived count and is REBUILT after the\n * scope columns move (UPDATE does not fire the file_count triggers, so a stale\n * plaintext row would remain). `versioned_scopes` / `resolve_entries` /\n * `gc_queue` are exempt by design (README §4.5 matrix).\n */\nconst SCOPE_TABLES = [\n  \"ds_entries\",\n  \"ds_changelog\",\n  \"ds_prefix_watermark\",\n  \"ds_device_sync_state\",\n  // index-follower-dirty-path §10.2: the dirty queue's PK includes `scope`, so a\n  // de-id migration MUST rewrite it too — else a migrated user's dirty rows stay\n  // on the old plaintext scope, the follower queries the new HMAC scope, finds\n  // nothing, and silently stops indexing. (The trigger re-derives NEW rows on the\n  // new scope going forward; this moves the pre-migration backlog.)\n  \"ds_dirty_path\",\n] as const;\n\nexport interface ScopeMigrationOptions {\n  /** Classify only — collect + classify candidates, write nothing (STOP GATE). */\n  dryRun?: boolean;\n}\n\nexport interface ScopeMigrationReport {\n  /** Which `SCOPE_TABLES` actually exist in this DB (CF lacks device_sync_state). */\n  tablesPresent: string[];\n  /** Whether the `shares` / `scope_meta` tables exist. */\n  hasShares: boolean;\n  hasScopeMeta: boolean;\n  /** Distinct candidate scopes seen across all sources. */\n  candidates: number;\n  /** Plaintext DID scopes that WILL be / WERE migrated (sorted). */\n  migrate: string[];\n  /** Non-DID scopes skipped: versioned / already-derived hash / bare / junk (sorted). */\n  skip: string[];\n  /** Count actually migrated (0 when dryRun). */\n  migrated: number;\n  /** Whether scope_meta was rebuilt (only when something migrated + table present). */\n  scopeMetaRebuilt: boolean;\n}\n\nasync function tableExists(db: D1Database, name: string): Promise<boolean> {\n  const row = await db\n    .prepare(\"SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?\")\n    .bind(name)\n    .first<{ name: string }>();\n  return row != null;\n}\n\nasync function distinctColumn(db: D1Database, table: string, column: string): Promise<string[]> {\n  const res = await db.prepare(`SELECT DISTINCT ${column} AS v FROM ${table}`).all<{ v: string }>();\n  return (res.results ?? []).map((r) => r.v).filter((v): v is string => v != null);\n}\n\n/**\n * Migrate (or, with `dryRun`, classify) all plaintext DID scopes in `db`.\n *\n * @param db   the D1 database (or a compatible mock) — the bound runtime D1\n * @param key  the deployment HMAC secret bytes (from `decodeScopeHmacSecret`)\n * @param opts `{ dryRun }` to classify without writing\n */\nexport async function migrateD1Scopes(\n  db: D1Database,\n  key: Uint8Array,\n  opts: ScopeMigrationOptions = {},\n): Promise<ScopeMigrationReport> {\n  // 1. Probe which tables exist (CF has no device_sync_state; fresh DBs vary).\n  const tablesPresent: string[] = [];\n  for (const t of SCOPE_TABLES) {\n    if (await tableExists(db, t)) tablesPresent.push(t);\n  }\n  const hasShares = await tableExists(db, \"ds_shares\");\n  const hasScopeMeta = await tableExists(db, \"ds_scope_meta\");\n\n  // 2. Collect distinct candidate scopes across every existing source.\n  const candidateSet = new Set<string>();\n  for (const t of tablesPresent) {\n    for (const s of await distinctColumn(db, t, \"scope\")) candidateSet.add(s);\n  }\n  if (hasShares) {\n    for (const s of await distinctColumn(db, \"ds_shares\", \"owner_did\")) candidateSet.add(s);\n  }\n\n  // 3. Classify: only true DIDs migrate; everything else is skipped + reported.\n  const migrate: string[] = [];\n  const skip: string[] = [];\n  for (const s of candidateSet) (isPlainDidScope(s) ? migrate : skip).push(s);\n  migrate.sort();\n  skip.sort();\n\n  const base: ScopeMigrationReport = {\n    tablesPresent,\n    hasShares,\n    hasScopeMeta,\n    candidates: candidateSet.size,\n    migrate,\n    skip,\n    migrated: 0,\n    scopeMetaRebuilt: false,\n  };\n\n  if (opts.dryRun) return base;\n\n  // 4. Rewrite scopes — one ATOMIC batch per scope (all tables for a scope move\n  //    together). Per-scope batching is also the crash-safety boundary: an\n  //    interrupted run leaves untouched scopes plaintext, so a re-run completes\n  //    them; already-moved hashes are skipped (idempotent).\n  for (const s of migrate) {\n    const h = deriveScope(s, key);\n    const stmts: D1PreparedStatement[] = tablesPresent.map((t) =>\n      db.prepare(`UPDATE ${t} SET scope = ? WHERE scope = ?`).bind(h, s),\n    );\n    if (hasShares) {\n      stmts.push(db.prepare(\"UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?\").bind(h, s));\n    }\n    await db.batch(stmts);\n  }\n\n  // 5. Rebuild scope_meta from the (now-derived) entries. The triggers fire on\n  //    INSERT/DELETE, NOT the scope UPDATE above — so the old plaintext rows are\n  //    stale (entries moved away) and the new derived scopes have no row yet.\n  //    DELETE the stale plaintext rows, then BACKFILL re-seeds derived counts.\n  let scopeMetaRebuilt = false;\n  if (hasScopeMeta && migrate.length > 0) {\n    const placeholders = migrate.map(() => \"?\").join(\", \");\n    await db\n      .prepare(`DELETE FROM ds_scope_meta WHERE scope IN (${placeholders})`)\n      .bind(...migrate)\n      .run();\n    await db.prepare(SCOPE_META_FILE_COUNT_BACKFILL_SQL).run();\n    scopeMetaRebuilt = true;\n  }\n\n  return { ...base, migrated: migrate.length, scopeMetaRebuilt };\n}\n\n/** Classify distinct scope strings into migrate (plaintext DID) vs skip. */\nexport function classifyScopes(scopes: string[]): { migrate: string[]; skip: string[] } {\n  const migrate: string[] = [];\n  const skip: string[] = [];\n  for (const s of [...new Set(scopes)]) (isPlainDidScope(s) ? migrate : skip).push(s);\n  migrate.sort();\n  skip.sort();\n  return { migrate, skip };\n}\n\nexport interface BuildD1MigrationSqlOptions {\n  /** Emit `UPDATE shares SET owner_did = …` (CF has a shares table). Default true. */\n  includeShares?: boolean;\n  /** Emit the scope_meta DELETE-stale + BACKFILL rebuild. Default true. */\n  includeScopeMeta?: boolean;\n}\n\nexport interface D1MigrationSql {\n  /** The `.sql` text to apply via `wrangler d1 execute --remote --file`. */\n  sql: string;\n  migrate: string[];\n  skip: string[];\n}\n\nconst SQL_SCOPE_COLUMN_TABLES = [\n  \"ds_entries\",\n  \"ds_changelog\",\n  \"ds_prefix_watermark\",\n  // index-follower-dirty-path §10.2 — same reason as SCOPE_TABLES above.\n  \"ds_dirty_path\",\n] as const;\n\n/**\n * Generate the migration `.sql` for a REMOTE CF D1 (README §4.5 离线脚本形态).\n *\n * The HMAC is computed HERE (D1 SQL can't); the operator dumps the distinct\n * scopes with `wrangler d1 execute --remote --json` and applies the emitted file\n * with `wrangler d1 execute --remote --file`. Only plaintext DID scopes are\n * rewritten — versioned `schema:…` / already-derived / junk are left out, so a\n * re-apply is idempotent (their `WHERE scope = '<old DID>'` matches nothing).\n *\n * Statement order matters: all scope UPDATEs first, then the scope_meta rebuild\n * (DELETE stale plaintext rows + BACKFILL derived counts from the now-moved\n * entries). `entries` / `changelog` / `prefix_watermark` are CF's standard\n * scope-bearing tables (migrations 0100–0107); `device_sync_state` is absent.\n */\nexport function buildD1MigrationSql(\n  scopes: string[],\n  key: Uint8Array,\n  opts: BuildD1MigrationSqlOptions = {},\n): D1MigrationSql {\n  const { includeShares = true, includeScopeMeta = true } = opts;\n  const { migrate, skip } = classifyScopes(scopes);\n  // scope values are DIDs (base58) / hashes (base32) — no quotes; escape defensively.\n  const q = (v: string) => `'${v.replace(/'/g, \"''\")}'`;\n\n  const lines: string[] = [\n    \"-- DID Space scope de-identification migration (generated).\",\n    \"-- Apply with: wrangler d1 execute <DB> --remote --file <this-file>\",\n    `-- migrate ${migrate.length} DID scope(s); skip ${skip.length} non-DID scope(s).`,\n  ];\n  for (const s of migrate) {\n    const h = deriveScope(s, key);\n    for (const t of SQL_SCOPE_COLUMN_TABLES) {\n      lines.push(`UPDATE ${t} SET scope = ${q(h)} WHERE scope = ${q(s)};`);\n    }\n    if (includeShares) {\n      lines.push(`UPDATE ds_shares SET owner_did = ${q(h)} WHERE owner_did = ${q(s)};`);\n    }\n  }\n  if (includeScopeMeta && migrate.length > 0) {\n    // DELETE the stale plaintext rows (UPDATE of entries.scope does NOT fire the\n    // file_count triggers), then BACKFILL derived counts from the moved entries.\n    lines.push(`DELETE FROM ds_scope_meta WHERE scope IN (${migrate.map(q).join(\", \")});`);\n    lines.push(`${SCOPE_META_FILE_COUNT_BACKFILL_SQL};`);\n  }\n  return { sql: `${lines.join(\"\\n\")}\\n`, migrate, skip };\n}\n"],"mappings":"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"}

package/dist/share-declaration.cjs

@@ -0,0 +1,225 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _aigne_afs = require("@aigne/afs");
+let js_yaml = require("js-yaml");
+
+//#region src/share-declaration.ts
+/**
+* Phase 0.2 — ShareDeclaration: YAML schema parsing + path helpers.
+*
+* Exported functions used by Phase 0.3 (ShareResolver) and Phase 0.4 (writeHandler hook):
+*   - parseShareDeclaration
+*   - isShareDeclarationPath
+*   - isShareReservedPath
+*   - deriveSourcePath
+*   - mapShareErrorToAFSError
+*/
+const KNOWN_FIELDS = new Set([
+	"slug",
+	"kind",
+	"status",
+	"expires_at",
+	"password",
+	"visibility",
+	"description",
+	"domain"
+]);
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
+const MAX_CONTENT_BYTES = 4096;
+const MAX_DESCRIPTION_LENGTH = 200;
+/**
+* Parse and validate a `.share` file's content.
+*
+* Validation order (strict, per spec):
+*  1. Size check (> 4096 bytes) — before YAML parse
+*  2. Empty content (0 bytes) → { ok: true, data: {} }
+*  3. UTF-8 decode (fatal mode)
+*  4. YAML parse with maxAliasCount: 0
+*  5. Unknown field detection
+*  6. slug format
+*  7. kind enum
+*  8. status enum
+*  9. description length
+* 10. expires_at format
+* 11. password structure
+*/
+function parseShareDeclaration(content) {
+	if (content.byteLength > MAX_CONTENT_BYTES) return {
+		ok: false,
+		code: "share-content-too-large",
+		message: `Content size ${content.byteLength} bytes exceeds ${MAX_CONTENT_BYTES} byte limit`,
+		detail: {
+			sizeBytes: content.byteLength,
+			limit: MAX_CONTENT_BYTES
+		}
+	};
+	if (content.byteLength === 0) return {
+		ok: true,
+		data: {}
+	};
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+	} catch {
+		return {
+			ok: false,
+			code: "share-yaml-parse-error",
+			message: "Content is not valid UTF-8"
+		};
+	}
+	let parsed;
+	try {
+		parsed = (0, js_yaml.load)(text);
+	} catch (err) {
+		return {
+			ok: false,
+			code: "share-yaml-parse-error",
+			message: err instanceof Error ? err.message : String(err),
+			detail: err
+		};
+	}
+	if (parsed == null) return {
+		ok: true,
+		data: {}
+	};
+	if (typeof parsed !== "object" || Array.isArray(parsed)) return {
+		ok: false,
+		code: "share-yaml-parse-error",
+		message: "Expected a YAML mapping (object), got a different type"
+	};
+	const obj = parsed;
+	for (const key of Object.keys(obj)) if (!KNOWN_FIELDS.has(key)) return {
+		ok: false,
+		code: "share-field-unknown",
+		message: `Unknown field: ${key}`,
+		detail: { field: key }
+	};
+	if (obj.slug !== void 0) {
+		if (typeof obj.slug !== "string" || !SLUG_REGEX.test(obj.slug)) return {
+			ok: false,
+			code: "share-slug-invalid",
+			message: `slug must match /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/, got: ${JSON.stringify(obj.slug)}`,
+			detail: { slug: obj.slug }
+		};
+	}
+	if (obj.kind !== void 0) {
+		if (obj.kind !== "raw" && obj.kind !== "web") return {
+			ok: false,
+			code: "share-kind-invalid",
+			message: `kind must be "raw" or "web", got: ${JSON.stringify(obj.kind)}`,
+			detail: { kind: obj.kind }
+		};
+	}
+	if (obj.status !== void 0) {
+		if (obj.status !== "active" && obj.status !== "revoked") return {
+			ok: false,
+			code: "share-status-invalid",
+			message: `status must be "active" or "revoked", got: ${JSON.stringify(obj.status)}`,
+			detail: { status: obj.status }
+		};
+	}
+	if (obj.description !== void 0) {
+		if (typeof obj.description !== "string" || obj.description.length > MAX_DESCRIPTION_LENGTH) return {
+			ok: false,
+			code: "share-field-invalid",
+			message: `description must be a string with at most ${MAX_DESCRIPTION_LENGTH} characters`,
+			detail: { field: "description" }
+		};
+	}
+	if (obj.expires_at !== void 0) {
+		if (typeof obj.expires_at !== "string" || !isValidExpiresAt(obj.expires_at)) return {
+			ok: false,
+			code: "share-field-invalid",
+			message: `expires_at must be a valid ISO 8601 datetime or Unix milliseconds string`,
+			detail: { field: "expires_at" }
+		};
+	}
+	if (obj.password !== void 0) {
+		const pwd = obj.password;
+		if (typeof pwd !== "object" || pwd === null || Array.isArray(pwd) || pwd.algorithm !== "argon2id" || typeof pwd.hash !== "string") return {
+			ok: false,
+			code: "share-field-invalid",
+			message: "password must be {algorithm: \"argon2id\", hash: string}",
+			detail: { field: "password" }
+		};
+	}
+	return {
+		ok: true,
+		data: obj
+	};
+}
+function isValidExpiresAt(value) {
+	if (/^\d+$/.test(value)) return true;
+	const d = new Date(value);
+	return !Number.isNaN(d.getTime());
+}
+/**
+* Returns true if `path` is a `.share` declaration file (in-tree or sidecar).
+*
+* Examples:
+*   `.share`          → true  (root in-tree)
+*   `/.share`         → true  (root in-tree with leading slash)
+*   `docs/.share`     → true  (subdirectory in-tree)
+*   `file.pdf.share`  → true  (sidecar)
+*   `.shares/foo`     → false (reserved virtual view)
+*   `README.md`       → false
+*/
+function isShareDeclarationPath(path) {
+	return (path.startsWith("/") ? path.slice(1) : path).endsWith(".share");
+}
+/**
+* Derives the source path from a declaration path.
+*
+* Examples:
+*   `.share`          → `""`        (root in-tree → source is root directory)
+*   `docs/.share`     → `"docs"`
+*   `file.pdf.share`  → `"file.pdf"`
+*/
+function deriveSourcePath(declPath) {
+	const p = declPath.startsWith("/") ? declPath.slice(1) : declPath;
+	if (p.endsWith("/.share")) return p.slice(0, -7);
+	return p.slice(0, -6);
+}
+/**
+* Returns true if `path` is a reserved share virtual path (read-only view, not writable).
+*
+* Reserved paths:
+*   `.shares`                      → the root virtual share listing
+*   `.shares/<anything>`           → entries under the root listing
+*   `instances/<iid>/.shares`      → per-instance listing
+*   `instances/<iid>/.shares/<…>`  → per-instance listing entries
+*/
+function isShareReservedPath(path) {
+	const norm = path.replace(/^\/+/, "");
+	if (norm === ".shares" || norm.startsWith(".shares/")) return true;
+	if (/^instances\/[^/]+\/\.shares(\/|$)/.test(norm)) return true;
+	return false;
+}
+/**
+* Maps a ShareResolver / parser error code to the appropriate AFS error type
+* so that writeHandler can throw with the correct HTTP status code.
+*/
+function mapShareErrorToAFSError(code, message, path) {
+	switch (code) {
+		case "share-yaml-parse-error":
+		case "share-content-too-large":
+		case "share-field-unknown":
+		case "share-field-invalid":
+		case "share-slug-invalid":
+		case "share-kind-invalid":
+		case "share-status-invalid":
+		case "share-web-no-decl":
+		case "share-sidecar-target-missing":
+		case "share-nested": return new _aigne_afs.AFSValidationError(`[${path}] ${code}: ${message}`);
+		case "share-path-forbidden":
+		case "share-path-reserved": return new _aigne_afs.AFSForbiddenError(path, code);
+		case "share-slug-conflict": return new _aigne_afs.AFSAlreadyExistsError(path, message);
+		default: return new _aigne_afs.AFSError(`${code}: ${message}`, code);
+	}
+}
+
+//#endregion
+exports.deriveSourcePath = deriveSourcePath;
+exports.isShareDeclarationPath = isShareDeclarationPath;
+exports.isShareReservedPath = isShareReservedPath;
+exports.mapShareErrorToAFSError = mapShareErrorToAFSError;
+exports.parseShareDeclaration = parseShareDeclaration;

package/dist/share-declaration.d.cts

@@ -0,0 +1,30 @@
+//#region src/share-declaration.d.ts
+/** All fields are optional; an empty file is equivalent to `{}`. */
+interface ShareDeclaration {
+  slug?: string;
+  kind?: "raw" | "web";
+  status?: "active" | "revoked";
+  expires_at?: string;
+  password?: {
+    algorithm: "argon2id";
+    hash: string;
+  };
+  visibility?: "public" | "unlisted";
+  description?: string;
+  domain?: string;
+}
+/**
+ * Returns true if `path` is a `.share` declaration file (in-tree or sidecar).
+ *
+ * Examples:
+ *   `.share`          → true  (root in-tree)
+ *   `/.share`         → true  (root in-tree with leading slash)
+ *   `docs/.share`     → true  (subdirectory in-tree)
+ *   `file.pdf.share`  → true  (sidecar)
+ *   `.shares/foo`     → false (reserved virtual view)
+ *   `README.md`       → false
+ */
+declare function isShareDeclarationPath(path: string): boolean;
+//#endregion
+export { ShareDeclaration, isShareDeclarationPath };
+//# sourceMappingURL=share-declaration.d.cts.map

package/dist/share-declaration.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-declaration.d.cts","names":[],"sources":["../src/share-declaration.ts"],"mappings":";;UAiBiB,gBAAA;EACf,IAAA;EACA,IAAA;EACA,MAAA;EACA,UAAA;EACA,QAAA;IAAa,SAAA;IAAuB,IAAA;EAAA;EACpC,UAAA;EACA,WAAA;EACA,MAAA;AAAA;;;;;;;;;;;;iBAwNc,sBAAA,CAAuB,IAAA"}

package/dist/share-declaration.d.mts

@@ -0,0 +1,32 @@
+import { AFSAlreadyExistsError, AFSError, AFSForbiddenError, AFSValidationError } from "@aigne/afs";
+
+//#region src/share-declaration.d.ts
+/** All fields are optional; an empty file is equivalent to `{}`. */
+interface ShareDeclaration {
+  slug?: string;
+  kind?: "raw" | "web";
+  status?: "active" | "revoked";
+  expires_at?: string;
+  password?: {
+    algorithm: "argon2id";
+    hash: string;
+  };
+  visibility?: "public" | "unlisted";
+  description?: string;
+  domain?: string;
+}
+/**
+ * Returns true if `path` is a `.share` declaration file (in-tree or sidecar).
+ *
+ * Examples:
+ *   `.share`          → true  (root in-tree)
+ *   `/.share`         → true  (root in-tree with leading slash)
+ *   `docs/.share`     → true  (subdirectory in-tree)
+ *   `file.pdf.share`  → true  (sidecar)
+ *   `.shares/foo`     → false (reserved virtual view)
+ *   `README.md`       → false
+ */
+declare function isShareDeclarationPath(path: string): boolean;
+//#endregion
+export { ShareDeclaration, isShareDeclarationPath };
+//# sourceMappingURL=share-declaration.d.mts.map

package/dist/share-declaration.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-declaration.d.mts","names":[],"sources":["../src/share-declaration.ts"],"mappings":";;;;UAiBiB,gBAAA;EACf,IAAA;EACA,IAAA;EACA,MAAA;EACA,UAAA;EACA,QAAA;IAAa,SAAA;IAAuB,IAAA;EAAA;EACpC,UAAA;EACA,WAAA;EACA,MAAA;AAAA;;;;;;;;;;;;iBAwNc,sBAAA,CAAuB,IAAA"}