@arcblock/did 1.29.18 → 1.29.19

package/esm/short-form.d.mts

@@ -0,0 +1,30 @@
+//#region src/short-form.d.ts
+/**
+ * Short-form DID Resolution
+ *
+ * Deterministic expansion of short-form identifiers to full DIDs.
+ * Based on base58 checksum validation (not heuristic guessing).
+ *
+ * Rules:
+ * - Already a full DID (starts with "did:") → return as-is
+ * - Valid cryptographic address (passes isValid checksum) → did:abt:{address}
+ * - Everything else → did:name:{input}
+ */
+/**
+ * Expand a short-form identifier to a full DID.
+ *
+ * @param input - Short-form identifier (address, name, or full DID)
+ * @returns Full DID string
+ * @throws If input is not a non-empty string
+ */
+declare function expandShortForm(input: unknown): string;
+/**
+ * Convert a full DID to its short form (strip the did:{method}: prefix).
+ *
+ * @param did - Full DID string
+ * @returns Short-form identifier
+ * @throws If input is not a non-empty string
+ */
+declare function toShortForm(did: unknown): string;
+//#endregion
+export { expandShortForm, toShortForm };

package/esm/short-form.mjs

@@ -0,0 +1,46 @@
+import { formatDid } from "./parse.mjs";
+import { isValid } from "./index.mjs";
+
+//#region src/short-form.ts
+/**
+* Short-form DID Resolution
+*
+* Deterministic expansion of short-form identifiers to full DIDs.
+* Based on base58 checksum validation (not heuristic guessing).
+*
+* Rules:
+* - Already a full DID (starts with "did:") → return as-is
+* - Valid cryptographic address (passes isValid checksum) → did:abt:{address}
+* - Everything else → did:name:{input}
+*/
+/**
+* Expand a short-form identifier to a full DID.
+*
+* @param input - Short-form identifier (address, name, or full DID)
+* @returns Full DID string
+* @throws If input is not a non-empty string
+*/
+function expandShortForm(input) {
+	if (typeof input !== "string") throw new Error("Input must be a string");
+	if (!input) throw new Error("Input cannot be empty");
+	if (input.startsWith("did:")) return input;
+	if (isValid(input)) return formatDid(input, "abt");
+	return formatDid(input, "name");
+}
+/**
+* Convert a full DID to its short form (strip the did:{method}: prefix).
+*
+* @param did - Full DID string
+* @returns Short-form identifier
+* @throws If input is not a non-empty string
+*/
+function toShortForm(did) {
+	if (typeof did !== "string") throw new Error("Input must be a string");
+	if (!did) throw new Error("Input cannot be empty");
+	const match = did.match(/^did:[a-z0-9]+:(.+)$/);
+	if (match) return match[1];
+	return did;
+}
+
+//#endregion
+export { expandShortForm, toShortForm };

package/esm/util.mjs

@@ -12,7 +12,7 @@ const DID_PREFIX = "did:abt:";
 const toBytes = (did) => {
 	try {
 		if (isHexStrict(did)) return Buffer.from(stripHexPrefix(did), "hex");
-		let bytes = fromBase58(did.replace(DID_PREFIX, ""));
+		let bytes = fromBase58(did.replace(/^did:[a-z0-9]+:/, ""));
 		while (bytes.length < 26) bytes = Buffer.concat([Uint8Array.from([0]), Uint8Array.from(bytes)]);
 		return bytes;
 	} catch (err) {

package/esm/validate.d.mts

@@ -0,0 +1,23 @@
+//#region src/validate.d.ts
+/**
+ * DID Validation Functions
+ *
+ * isValid and isFromPublicKey remain in index.ts (too many dependencies to move).
+ * This file provides isKnownDid which covers all methods including did:name.
+ */
+/**
+ * Check if a DID string is a known valid DID.
+ *
+ * Unlike `isValid` (which only validates cryptographic addresses),
+ * `isKnownDid` covers all known methods:
+ * - Crypto methods (abt/afs/aos/spaces): delegates to `isValid` for checksum validation
+ * - Alias methods (name): checks for non-empty identifier
+ * - Unknown methods: returns false
+ * - Bare cryptographic addresses: delegates to `isValid`
+ *
+ * @param did - DID string to validate
+ * @returns true if the DID is valid for its method
+ */
+declare function isKnownDid(did: unknown): boolean;
+//#endregion
+export { isKnownDid };

package/esm/validate.mjs

@@ -0,0 +1,36 @@
+import { isAliasMethod, isCryptoMethod } from "./method.mjs";
+import { isValid } from "./index.mjs";
+
+//#region src/validate.ts
+/**
+* DID Validation Functions
+*
+* isValid and isFromPublicKey remain in index.ts (too many dependencies to move).
+* This file provides isKnownDid which covers all methods including did:name.
+*/
+/**
+* Check if a DID string is a known valid DID.
+*
+* Unlike `isValid` (which only validates cryptographic addresses),
+* `isKnownDid` covers all known methods:
+* - Crypto methods (abt/afs/aos/spaces): delegates to `isValid` for checksum validation
+* - Alias methods (name): checks for non-empty identifier
+* - Unknown methods: returns false
+* - Bare cryptographic addresses: delegates to `isValid`
+*
+* @param did - DID string to validate
+* @returns true if the DID is valid for its method
+*/
+function isKnownDid(did) {
+	if (typeof did !== "string" || !did) return false;
+	const match = did.match(/^did:([a-z0-9]+):(.*)$/);
+	if (!match) return isValid(did);
+	const [, method, identifier] = match;
+	if (!identifier) return false;
+	if (isCryptoMethod(method)) return isValid(did);
+	if (isAliasMethod(method)) return true;
+	return false;
+}
+
+//#endregion
+export { isKnownDid };

package/lib/entity.cjs

@@ -0,0 +1,40 @@
+const require_parse = require('./parse.cjs');
+
+//#region src/entity.ts
+/**
+* Cross-Method Entity Association
+*
+* Functions for comparing DID identity across different methods.
+* Two DIDs with different methods but the same identifier represent the same entity.
+*/
+/**
+* Get the entity identifier from a DID (strips method prefix).
+* This is the canonical identity across methods.
+*
+* @param did - A full DID or bare address
+* @returns The entity identifier
+*/
+function getEntityId(did) {
+	return require_parse.extractIdentifier(did);
+}
+/**
+* Check if two DIDs represent the same entity.
+* Compares the identifier portion (case-insensitive), ignoring the method prefix.
+*
+* For did:name DIDs, performs exact string comparison (names are case-insensitive).
+*
+* @param a - First DID or address
+* @param b - Second DID or address
+* @returns true if both DIDs refer to the same entity
+*/
+function isSameEntity(a, b) {
+	if (typeof a !== "string" || typeof b !== "string" || !a || !b) return false;
+	const idA = require_parse.extractIdentifier(a);
+	const idB = require_parse.extractIdentifier(b);
+	if (!idA || !idB) return false;
+	return idA.toLowerCase() === idB.toLowerCase();
+}
+
+//#endregion
+exports.getEntityId = getEntityId;
+exports.isSameEntity = isSameEntity;

package/lib/entity.d.cts

@@ -0,0 +1,28 @@
+//#region src/entity.d.ts
+/**
+ * Cross-Method Entity Association
+ *
+ * Functions for comparing DID identity across different methods.
+ * Two DIDs with different methods but the same identifier represent the same entity.
+ */
+/**
+ * Get the entity identifier from a DID (strips method prefix).
+ * This is the canonical identity across methods.
+ *
+ * @param did - A full DID or bare address
+ * @returns The entity identifier
+ */
+declare function getEntityId(did: string): string;
+/**
+ * Check if two DIDs represent the same entity.
+ * Compares the identifier portion (case-insensitive), ignoring the method prefix.
+ *
+ * For did:name DIDs, performs exact string comparison (names are case-insensitive).
+ *
+ * @param a - First DID or address
+ * @param b - Second DID or address
+ * @returns true if both DIDs refer to the same entity
+ */
+declare function isSameEntity(a: unknown, b: unknown): boolean;
+//#endregion
+export { getEntityId, isSameEntity };

package/lib/index.cjs

@@ -1,6 +1,14 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_method = require('./method.cjs');
+const require_parse = require('./parse.cjs');
+const require_entity = require('./entity.cjs');
 const require_util = require('./util.cjs');
 const require_type = require('./type.cjs');
+const require_validate = require('./validate.cjs');
+const require_short_form = require('./short-form.cjs');
+const require_name = require('./name.cjs');
+const require_name_registry = require('./name-registry.cjs');
+const require_name_resolver = require('./name-resolver.cjs');
 let _ocap_mcrypto = require("@ocap/mcrypto");
 let _ocap_util = require("@ocap/util");
 
@@ -70,7 +78,7 @@ const fromHash = (hash, role = _ocap_mcrypto.types.RoleType.ROLE_ACCOUNT) => {
 */
 const isFromPublicKey = (did, pk) => {
 	if (isValid(did) === false) return false;
-	return fromPublicKey(pk, require_type.toTypeInfo(did)) === did.replace(require_util.DID_PREFIX, "");
+	return fromPublicKey(pk, require_type.toTypeInfo(did)) === (0, _ocap_util.toAddress)(did);
 };
 /**
 * Check if a DID string is valid
@@ -93,22 +101,44 @@ const isValid = (did) => {
 };
 
 //#endregion
+exports.ALIAS_METHODS = require_method.ALIAS_METHODS;
+exports.ALL_METHODS = require_method.ALL_METHODS;
+exports.CRYPTO_METHODS = require_method.CRYPTO_METHODS;
+exports.DEFAULT_METHOD = require_method.DEFAULT_METHOD;
+exports.DIDNameResolver = require_name_resolver.DIDNameResolver;
 exports.DID_PREFIX = require_util.DID_PREFIX;
 exports.DID_TYPE_ARCBLOCK = require_type.DID_TYPE_ARCBLOCK;
 exports.DID_TYPE_ETHEREUM = require_type.DID_TYPE_ETHEREUM;
 exports.DID_TYPE_PASSKEY = require_type.DID_TYPE_PASSKEY;
 exports.DidType = require_type.DidType;
+exports.InMemoryNameRegistry = require_name_registry.InMemoryNameRegistry;
+exports.expandShortForm = require_short_form.expandShortForm;
+exports.extractIdentifier = require_parse.extractIdentifier;
+exports.extractMethod = require_parse.extractMethod;
+exports.formatDid = require_parse.formatDid;
 exports.fromHash = fromHash;
 exports.fromPublicKey = fromPublicKey;
 exports.fromPublicKeyHash = fromPublicKeyHash;
 exports.fromSecretKey = fromSecretKey;
 exports.fromTypeInfo = require_type.fromTypeInfo;
+exports.getEntityId = require_entity.getEntityId;
+exports.getResolveRoute = require_name.getResolveRoute;
+exports.isAliasMethod = require_method.isAliasMethod;
+exports.isCryptoMethod = require_method.isCryptoMethod;
 exports.isEthereumDid = require_type.isEthereumDid;
 exports.isEthereumType = require_type.isEthereumType;
 exports.isFromPublicKey = isFromPublicKey;
+exports.isGlobalName = require_name.isGlobalName;
+exports.isKnownDid = require_validate.isKnownDid;
+exports.isKnownMethod = require_method.isKnownMethod;
+exports.isLocalName = require_name.isLocalName;
+exports.isSameEntity = require_entity.isSameEntity;
 exports.isValid = isValid;
+exports.parse = require_parse.parse;
+exports.parseNameHierarchy = require_name.parseNameHierarchy;
 exports.toAddress = _ocap_util.toAddress;
 exports.toDid = _ocap_util.toDid;
+exports.toShortForm = require_short_form.toShortForm;
 exports.toStrictHex = require_util.toStrictHex;
 exports.toTypeInfo = require_type.toTypeInfo;
 exports.toTypeInfoStr = require_type.toTypeInfoStr;

package/lib/index.d.cts

@@ -1,5 +1,13 @@
+import { getEntityId, isSameEntity } from "./entity.cjs";
 import { DIDType, DIDTypeArg, DIDTypeShortcut, DIDTypeStr, DID_TYPE_ARCBLOCK, DID_TYPE_ETHEREUM, DID_TYPE_PASSKEY, DidType, RequiredDIDType, fromTypeInfo, isEthereumDid, isEthereumType, toTypeInfo, toTypeInfoStr } from "./type.cjs";
 import { DID_PREFIX, toStrictHex } from "./util.cjs";
+import { ALIAS_METHODS, ALL_METHODS, AliasMethod, CRYPTO_METHODS, CryptoMethod, DEFAULT_METHOD, DIDMethod, isAliasMethod, isCryptoMethod, isKnownMethod } from "./method.cjs";
+import { ParsedDID, extractIdentifier, extractMethod, formatDid, parse } from "./parse.cjs";
+import { isKnownDid } from "./validate.cjs";
+import { expandShortForm, toShortForm } from "./short-form.cjs";
+import { NameHierarchy, ResolveRoute, getResolveRoute, isGlobalName, isLocalName, parseNameHierarchy } from "./name.cjs";
+import { InMemoryNameRegistry, NameRegistry } from "./name-registry.cjs";
+import { DIDNameResolver, DIDNameResolverOptions, ResolveTraceResult } from "./name-resolver.cjs";
 import { types } from "@ocap/mcrypto";
 import { BytesType, toAddress, toDid } from "@ocap/util";
 
@@ -58,4 +66,4 @@ declare const isFromPublicKey: (did: string, pk: BytesType) => boolean;
  */
 declare const isValid: (did: string) => boolean;
 //#endregion
-export { type DIDType, type DIDTypeArg, type DIDTypeShortcut, type DIDTypeStr, DID_PREFIX, DID_TYPE_ARCBLOCK, DID_TYPE_ETHEREUM, DID_TYPE_PASSKEY, DidType, type RequiredDIDType, fromHash, fromPublicKey, fromPublicKeyHash, fromSecretKey, fromTypeInfo, isEthereumDid, isEthereumType, isFromPublicKey, isValid, toAddress, toDid, toStrictHex, toTypeInfo, toTypeInfoStr, types };
+export { ALIAS_METHODS, ALL_METHODS, type AliasMethod, CRYPTO_METHODS, type CryptoMethod, DEFAULT_METHOD, type DIDMethod, DIDNameResolver, type DIDNameResolverOptions, type DIDType, type DIDTypeArg, type DIDTypeShortcut, type DIDTypeStr, DID_PREFIX, DID_TYPE_ARCBLOCK, DID_TYPE_ETHEREUM, DID_TYPE_PASSKEY, DidType, InMemoryNameRegistry, type NameHierarchy, type NameRegistry, type ParsedDID, type RequiredDIDType, type ResolveRoute, type ResolveTraceResult, expandShortForm, extractIdentifier, extractMethod, formatDid, fromHash, fromPublicKey, fromPublicKeyHash, fromSecretKey, fromTypeInfo, getEntityId, getResolveRoute, isAliasMethod, isCryptoMethod, isEthereumDid, isEthereumType, isFromPublicKey, isGlobalName, isKnownDid, isKnownMethod, isLocalName, isSameEntity, isValid, parse, parseNameHierarchy, toAddress, toDid, toShortForm, toStrictHex, toTypeInfo, toTypeInfoStr, types };

package/lib/method.cjs

@@ -0,0 +1,39 @@
+
+//#region src/method.ts
+/** Crypto methods: share unified identifier encoding (base58 checksum / ethereum / base16) */
+const CRYPTO_METHODS = Object.freeze([
+	"abt",
+	"afs",
+	"aos",
+	"spaces"
+]);
+/** Alias methods: human-readable identifiers */
+const ALIAS_METHODS = Object.freeze(["name"]);
+/** All supported methods */
+const ALL_METHODS = Object.freeze([...CRYPTO_METHODS, ...ALIAS_METHODS]);
+/** Default method when none is specified */
+const DEFAULT_METHOD = "abt";
+/** Check if a value is a known crypto method */
+function isCryptoMethod(method) {
+	if (typeof method !== "string") return false;
+	return CRYPTO_METHODS.includes(method);
+}
+/** Check if a value is a known alias method */
+function isAliasMethod(method) {
+	if (typeof method !== "string") return false;
+	return ALIAS_METHODS.includes(method);
+}
+/** Check if a value is any known method */
+function isKnownMethod(method) {
+	if (typeof method !== "string") return false;
+	return ALL_METHODS.includes(method);
+}
+
+//#endregion
+exports.ALIAS_METHODS = ALIAS_METHODS;
+exports.ALL_METHODS = ALL_METHODS;
+exports.CRYPTO_METHODS = CRYPTO_METHODS;
+exports.DEFAULT_METHOD = DEFAULT_METHOD;
+exports.isAliasMethod = isAliasMethod;
+exports.isCryptoMethod = isCryptoMethod;
+exports.isKnownMethod = isKnownMethod;

package/lib/method.d.cts

@@ -0,0 +1,30 @@
+//#region src/method.d.ts
+/**
+ * DID Method Registry
+ *
+ * Defines supported DID methods, their categories, and helper functions.
+ * Crypto methods (abt, afs, aos, spaces) share a unified identifier encoding.
+ * Alias methods (name) use human-readable identifiers with DNS-style hierarchy.
+ */
+/** Crypto methods share unified identifier encoding */
+type CryptoMethod = 'abt' | 'afs' | 'aos' | 'spaces';
+/** Alias methods use human-readable identifiers */
+type AliasMethod = 'name';
+/** All supported DID methods */
+type DIDMethod = CryptoMethod | AliasMethod;
+/** Crypto methods: share unified identifier encoding (base58 checksum / ethereum / base16) */
+declare const CRYPTO_METHODS: readonly CryptoMethod[];
+/** Alias methods: human-readable identifiers */
+declare const ALIAS_METHODS: readonly AliasMethod[];
+/** All supported methods */
+declare const ALL_METHODS: readonly DIDMethod[];
+/** Default method when none is specified */
+declare const DEFAULT_METHOD: CryptoMethod;
+/** Check if a value is a known crypto method */
+declare function isCryptoMethod(method: unknown): method is CryptoMethod;
+/** Check if a value is a known alias method */
+declare function isAliasMethod(method: unknown): method is AliasMethod;
+/** Check if a value is any known method */
+declare function isKnownMethod(method: unknown): method is DIDMethod;
+//#endregion
+export { ALIAS_METHODS, ALL_METHODS, AliasMethod, CRYPTO_METHODS, CryptoMethod, DEFAULT_METHOD, DIDMethod, isAliasMethod, isCryptoMethod, isKnownMethod };

package/lib/name-registry.cjs

@@ -0,0 +1,38 @@
+
+//#region src/name-registry.ts
+const MAX_NAME_LENGTH = 1024;
+/**
+* In-memory name registry implementation.
+* Uses upsert semantics: re-registering a name overwrites the previous value.
+*/
+var InMemoryNameRegistry = class {
+	constructor() {
+		this.store = /* @__PURE__ */ new Map();
+	}
+	resolve(name) {
+		return this.store.get(name) ?? null;
+	}
+	register(name, did) {
+		if (!name || typeof name !== "string") throw new Error("Name must be a non-empty string");
+		if (name.length > MAX_NAME_LENGTH) throw new Error("Name exceeds maximum length");
+		if (name.startsWith(".") || name.endsWith(".")) throw new Error("Name cannot start or end with a dot");
+		if (!did || typeof did !== "string") throw new Error("DID must be a non-empty string");
+		if (!did.startsWith("did:")) throw new Error("DID must have a valid did: prefix");
+		this.store.set(name, did);
+	}
+	unregister(name) {
+		this.store.delete(name);
+	}
+	has(name) {
+		return this.store.has(name);
+	}
+	list() {
+		return [...this.store.keys()];
+	}
+	clear() {
+		this.store.clear();
+	}
+};
+
+//#endregion
+exports.InMemoryNameRegistry = InMemoryNameRegistry;

package/lib/name-registry.d.cts

@@ -0,0 +1,31 @@
+//#region src/name-registry.d.ts
+/**
+ * NameRegistry Interface and InMemoryNameRegistry Implementation
+ *
+ * Provides a synchronous interface for name→DID registration and lookup.
+ * InMemoryNameRegistry is a Map-based implementation for testing.
+ */
+/** Name registry interface (synchronous) */
+interface NameRegistry {
+  resolve(name: string): string | null;
+  register(name: string, did: string): void;
+  unregister(name: string): void;
+  has(name: string): boolean;
+  list(): string[];
+  clear(): void;
+}
+/**
+ * In-memory name registry implementation.
+ * Uses upsert semantics: re-registering a name overwrites the previous value.
+ */
+declare class InMemoryNameRegistry implements NameRegistry {
+  private store;
+  resolve(name: string): string | null;
+  register(name: string, did: string): void;
+  unregister(name: string): void;
+  has(name: string): boolean;
+  list(): string[];
+  clear(): void;
+}
+//#endregion
+export { InMemoryNameRegistry, NameRegistry };

package/lib/name-resolver.cjs

@@ -0,0 +1,97 @@
+const require_name = require('./name.cjs');
+
+//#region src/name-resolver.ts
+/**
+* DID Name Resolver
+*
+* Orchestrates name resolution across different registries (global, local).
+* Supports delegation chains with cycle detection and depth limiting.
+*/
+const DEFAULT_MAX_DEPTH = 10;
+/**
+* DID Name Resolver.
+*
+* Routes name resolution to the appropriate registry based on the name structure:
+* - Global names (single segment) → global registry
+* - .local names → local registry
+* - Delegated names (multi-segment) → resolve TLD first, then delegate
+*/
+var DIDNameResolver = class {
+	constructor(opts = {}) {
+		this.global = opts.global;
+		this.local = opts.local;
+		this.maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+	}
+	/**
+	* Resolve a name to a DID.
+	*
+	* @param name - The name to resolve (can be prefixed with 'did:name:')
+	* @returns The resolved DID, or null if not found
+	*/
+	async resolve(name) {
+		return (await this.resolveWithTrace(name)).result;
+	}
+	/**
+	* Resolve a name with full trace for debugging.
+	*/
+	async resolveWithTrace(name) {
+		if (!name || typeof name !== "string") throw new Error("Name must be a non-empty string");
+		const cleanName = name.replace(/^did:name:/, "");
+		if (!cleanName) throw new Error("Name cannot be empty after stripping prefix");
+		const visited = /* @__PURE__ */ new Set();
+		return this._resolve(cleanName, visited, [], 0);
+	}
+	async _resolve(name, visited, trace, depth) {
+		if (visited.has(name)) {
+			trace.push(`cycle_detected:${name}`);
+			return {
+				result: null,
+				trace
+			};
+		}
+		if (depth >= this.maxDepth) {
+			trace.push(`max_depth:${name}`);
+			return {
+				result: null,
+				trace
+			};
+		}
+		visited.add(name);
+		const route = require_name.getResolveRoute(name);
+		let resolved = null;
+		if (route.type === "local") {
+			trace.push(`local:${name}`);
+			if (this.local) resolved = this.local.resolve(route.name);
+		} else if (route.type === "global") {
+			trace.push(`global:${name}`);
+			if (this.global) resolved = this.global.resolve(route.name);
+		} else {
+			trace.push(`delegated:${name}`);
+			if (this.global) {
+				resolved = this.global.resolve(name);
+				if (!resolved) {
+					const tldResult = this.global.resolve(route.tld);
+					if (tldResult) resolved = tldResult;
+				}
+			}
+		}
+		if (!resolved) {
+			trace.push(`not_found:${name}`);
+			return {
+				result: null,
+				trace
+			};
+		}
+		if (resolved.startsWith("did:name:")) {
+			const nextName = resolved.replace(/^did:name:/, "");
+			return this._resolve(nextName, visited, trace, depth + 1);
+		}
+		return {
+			result: resolved,
+			trace
+		};
+	}
+};
+
+//#endregion
+exports.DIDNameResolver = DIDNameResolver;

package/lib/name-resolver.d.cts

@@ -0,0 +1,41 @@
+import { NameRegistry } from "./name-registry.cjs";
+
+//#region src/name-resolver.d.ts
+
+interface DIDNameResolverOptions {
+  global?: NameRegistry;
+  local?: NameRegistry;
+  maxDepth?: number;
+}
+interface ResolveTraceResult {
+  result: string | null;
+  trace: string[];
+}
+/**
+ * DID Name Resolver.
+ *
+ * Routes name resolution to the appropriate registry based on the name structure:
+ * - Global names (single segment) → global registry
+ * - .local names → local registry
+ * - Delegated names (multi-segment) → resolve TLD first, then delegate
+ */
+declare class DIDNameResolver {
+  private global?;
+  private local?;
+  private maxDepth;
+  constructor(opts?: DIDNameResolverOptions);
+  /**
+   * Resolve a name to a DID.
+   *
+   * @param name - The name to resolve (can be prefixed with 'did:name:')
+   * @returns The resolved DID, or null if not found
+   */
+  resolve(name: string): Promise<string | null>;
+  /**
+   * Resolve a name with full trace for debugging.
+   */
+  resolveWithTrace(name: string): Promise<ResolveTraceResult>;
+  private _resolve;
+}
+//#endregion
+export { DIDNameResolver, DIDNameResolverOptions, ResolveTraceResult };

package/lib/name.cjs

@@ -0,0 +1,77 @@
+
+//#region src/name.ts
+/**
+* Parse a name identifier into its hierarchy components.
+*
+* @param name - The name to parse (e.g. 'robertmao', 'bob.myorg', 'anything.local')
+* @returns Parsed hierarchy
+* @throws If name is invalid
+*/
+function parseNameHierarchy(name) {
+	if (typeof name !== "string") throw new Error("Name must be a string");
+	if (!name) throw new Error("Name cannot be empty");
+	if (name.startsWith(".")) throw new Error("Name cannot start with a dot");
+	if (name.endsWith(".")) throw new Error("Name cannot end with a dot");
+	if (name.includes("..")) throw new Error("Name cannot contain consecutive dots");
+	const segments = name.split(".");
+	if (segments.some((s) => !s)) throw new Error("Name contains empty segments");
+	const tld = segments[segments.length - 1];
+	const isLocal = tld === "local";
+	const isGlobal = segments.length === 1 && !isLocal;
+	const depth = segments.length;
+	return {
+		segments: [...segments],
+		tld,
+		isLocal,
+		isGlobal,
+		depth
+	};
+}
+/**
+* Determine the resolve route for a name.
+*
+* - Single segment (e.g. 'robertmao') → global route
+* - Ends with '.local' → local route
+* - Multi-segment (e.g. 'bob.myorg') → delegated route
+*
+* @param name - The name to route
+* @returns The resolve route
+* @throws If name is invalid
+*/
+function getResolveRoute(name) {
+	const hierarchy = parseNameHierarchy(name);
+	if (hierarchy.isLocal) return {
+		type: "local",
+		name: hierarchy.segments.slice(0, -1).join(".")
+	};
+	if (hierarchy.isGlobal) return {
+		type: "global",
+		name
+	};
+	const subName = hierarchy.segments.slice(0, -1).join(".");
+	return {
+		type: "delegated",
+		tld: hierarchy.tld,
+		subName
+	};
+}
+/**
+* Check if a name is a .local name.
+*/
+function isLocalName(name) {
+	if (!name || !name.includes(".")) return false;
+	return name.endsWith(".local");
+}
+/**
+* Check if a name is a global name (single segment, not .local).
+*/
+function isGlobalName(name) {
+	if (!name) return false;
+	return !name.includes(".");
+}
+
+//#endregion
+exports.getResolveRoute = getResolveRoute;
+exports.isGlobalName = isGlobalName;
+exports.isLocalName = isLocalName;
+exports.parseNameHierarchy = parseNameHierarchy;