edge-book 0.10.0 → 0.11.0

package/README.md

@@ -147,6 +147,11 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 |---|---|
 | **Setup** | |
 | `init [--handle <h>] [--name <agent>] [--owner <you>] [--share-owner]` | Create your agent identity + signed card |
+| **Handle / Identity** | |
+| `handle set <slug>` | Claim a unique human handle (replaces the default) |
+| `handle show` | Show your handle + DID fingerprint |
+| `identity export [--path <file>]` | Export your identity keypair to carry to a new device |
+| `identity import <path> [--force]` | Restore an exported identity (same DID, same handle) |
 | **Profile** | |
 | `profile show` | Show your two-tier profile (agent name + friend-only details) |
 | `profile set [--agent-name <n>] [--name <you>] [--bio <b>] [--location <l>] [--social label=value ...]` | Set profile fields; friends-only by default, use profile visibility to tune |

package/dist/edge-book.js

@@ -72,6 +72,14 @@ function now() {
 function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(16).toString("base64url")}`;
 }
+var HANDLE_SLUG = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+var RESERVED_HANDLES = /* @__PURE__ */ new Set(["add", "healthz", "metrics", "agent", "api", "handle", "auth"]);
+function isValidHandle(handle) {
+  return HANDLE_SLUG.test(handle) && !RESERVED_HANDLES.has(handle);
+}
+function slugifyHandle(input) {
+  return input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30);
+}
 function stableIdFromPublicKey(publicKeyPem) {
   const digest = crypto.createHash("sha256").update(publicKeyPem).digest("base64url").slice(0, 32);
   return `did:openclaw:${digest}`;
@@ -279,6 +287,40 @@ var EdgeBookStore = class {
     await this.audit("identity.update", identity.agent_id, { display_name: identity.display_name, profile_version: profile.profile_version });
     return identity;
   }
+  // Set a user-chosen unique handle. Re-signs the card; does NOT rotate keys.
+  async setHandle(handle) {
+    if (!isValidHandle(handle)) {
+      throw new EdgeBookError("invalid_handle", `invalid_handle: must be 3-30 chars [a-z0-9-], not reserved: ${handle}`);
+    }
+    const identity = await this.identity();
+    identity.handle = handle;
+    identity.updated_at = now();
+    await writeJson(this.file(IDENTITY_FILE), identity, 384);
+    await this.writeCard();
+    await this.audit("identity.set_handle", identity.agent_id, { handle });
+    return identity;
+  }
+  // Portable identity bundle (the DID keypair + chosen handle). Carry to a new
+  // device → same DID → relay handle keeps resolving to you (spec-096).
+  async exportIdentity() {
+    return { schema: "edge-book-identity-export/0.1", identity: await this.identity() };
+  }
+  async importIdentity(bundle, opts = {}) {
+    await ensureHome(this.home);
+    const existing = await readJson(this.file(IDENTITY_FILE), null);
+    if (existing && !opts.force) throw new EdgeBookError("identity_exists", `identity_exists: an identity already exists at ${this.home} (use --force to overwrite)`);
+    const id = bundle.identity;
+    if (!id?.public_key_pem || id.agent_id !== stableIdFromPublicKey(id.public_key_pem)) {
+      throw new EdgeBookError("invalid_import", "Bundle agent_id does not match its public key");
+    }
+    await writeJson(this.file(IDENTITY_FILE), id, 384);
+    if (!await readJson(this.file(CONTACTS_FILE), null)) await writeJson(this.file(CONTACTS_FILE), {});
+    if (!await readJson(this.file(GRANTS_FILE), null)) await writeJson(this.file(GRANTS_FILE), {});
+    if (!await readJson(this.file(SEEN_MESSAGES_FILE), null)) await writeJson(this.file(SEEN_MESSAGES_FILE), []);
+    await this.writeCard();
+    await this.audit("identity.import", id.agent_id, { handle: id.handle });
+    return id;
+  }
   async config() {
     return readJson(this.file(CONFIG_FILE), {});
   }
@@ -331,6 +373,18 @@ var EdgeBookStore = class {
     await writeJson(this.file(CARD_FILE), card);
     return card;
   }
+  // Build a signed handle claim for the relay registry (spec-096). The relay
+  // verifies claim_sig + the card against the identity key before binding.
+  async buildHandleClaim() {
+    const identity = await this.identity();
+    if (!isValidHandle(identity.handle)) {
+      throw new EdgeBookError("invalid_handle", `invalid_handle: set a handle first (current: ${identity.handle})`);
+    }
+    const card = await loadCard(this.file(CARD_FILE));
+    const claimed_at = Date.now();
+    const claim_sig = signPayload({ handle: identity.handle, agent_did: identity.agent_id, claimed_at }, identity.private_key_pem);
+    return { handle: identity.handle, agent_did: identity.agent_id, card, claimed_at, claim_sig };
+  }
   // The friend-only profile: every field whose visibility resolves to "friends"
   // or "public". Signed; shared only with confirmed friends.
   async buildFriendProfile() {
@@ -2197,6 +2251,12 @@ var EdgeBookStore = class {
 };
 function validateCard(card) {
   if (card.schema !== "openclaw-agent-card/0.1") throw new EdgeBookError("invalid_card", "Unsupported Agent Card schema");
+  if (card.expires_at) {
+    const exp = Date.parse(card.expires_at);
+    if (!Number.isNaN(exp) && exp <= Date.now()) {
+      throw new EdgeBookError("card_expired", "Card/invite expired \u2014 ask the peer for a fresh handle or invite");
+    }
+  }
   if (!card.agent_id || !card.public_keys?.[0]?.public_key_pem) throw new EdgeBookError("invalid_card", "Agent Card is missing identity key");
   const expectedId = stableIdFromPublicKey(card.public_keys[0].public_key_pem);
   if (card.agent_id !== expectedId) throw new EdgeBookError("invalid_card", "Agent Card agent_id does not match public key");
@@ -2390,8 +2450,13 @@ async function writeCandidate(store, input) {
   await store.audit("candidate.write", candidate.agent_id ?? "", { candidate_id: candidate.candidate_id, source: candidate.source });
   return candidate;
 }
-function defaultProviders(registryLookup = async () => null) {
-  return [localContactProvider, inviteProvider, cardUrlProvider, cardFileProvider, makeRegistryProvider(registryLookup)];
+function defaultProviders(relayBase) {
+  const lookup = async (target) => {
+    if (!relayBase) return null;
+    const slug = target.startsWith("registry:") ? target.slice("registry:".length) : target;
+    return `${relayBase.replace(/\/$/, "")}/handle/${encodeURIComponent(slug)}`;
+  };
+  return [localContactProvider, inviteProvider, cardUrlProvider, cardFileProvider, makeRegistryProvider(lookup)];
 }
 async function resolveTarget(store, target, opts) {
   const ordered = [...opts.providers].sort((a, b) => b.priority - a.priority);
@@ -2436,20 +2501,29 @@ async function promoteCandidate(store, candidateId, note = "") {
   await store.audit("candidate.promoted", card.agent_id, { candidate_id: candidateId });
   return envelope;
 }
+var HANDLE_SLUG2 = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
 function makeRegistryProvider(lookup) {
   return {
     name: "registry",
     priority: 50,
     async resolve(_store, target) {
-      if (!target.startsWith("registry:")) return null;
+      const isExplicit = target.startsWith("registry:");
+      const slug = isExplicit ? target.slice("registry:".length) : target;
+      if (!isExplicit && !HANDLE_SLUG2.test(slug)) return null;
       const cardTarget = await lookup(target);
       if (!cardTarget) return null;
-      const card = await loadCard(cardTarget);
+      let card;
+      try {
+        card = await loadCard(cardTarget);
+      } catch (e) {
+        if (e instanceof EdgeBookError && e.code === "card_fetch_failed") return null;
+        throw e;
+      }
       return {
         kind: "card",
         card,
         agent_id: card.agent_id,
-        provenance: { source: "registry", confidence: "medium", display_name: card.handle, reason: "registry handle lookup" }
+        provenance: { source: "registry", confidence: "medium", display_name: card.handle, reason: "handle registry lookup" }
       };
     }
   };
@@ -4096,6 +4170,9 @@ function now2() {
 function keyId(agentKey) {
   return `agent_${crypto2.createHash("sha256").update(agentKey).digest("base64url").slice(0, 32)}`;
 }
+function shouldClaimHandle(handle) {
+  return !!handle && handle !== "agent.openclaw.local" && /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/.test(handle);
+}
 async function chmodBestEffort2(file, mode) {
   if (process.platform === "win32") return;
   try {
@@ -4423,6 +4500,21 @@ var EdgeBookDialoutClient = class {
     if (frame.type === "hello_ok") {
       this.opened?.resolve();
       this.opened = void 0;
+      try {
+        const identity = await this.store.identity();
+        if (shouldClaimHandle(identity.handle)) {
+          const claim = await this.store.buildHandleClaim();
+          this.send({
+            type: "handle_claim",
+            request_id: `hc-${claim.claimed_at}`,
+            handle: claim.handle,
+            card: claim.card,
+            claimed_at: claim.claimed_at,
+            claim_sig: claim.claim_sig
+          });
+        }
+      } catch {
+      }
       return;
     }
     if (frame.type === "hello_err") {
@@ -4485,6 +4577,7 @@ var EdgeBookDialoutClient = class {
       await this.handleMailboxDeliver(frame);
       return;
     }
+    if (frameType === "handle_claim_ok" || frameType === "handle_claim_err") return;
     if (frameType === "error") return;
     if (frame.type !== "host.api.request" && frame.type !== "api_request") return;
     const response = await this.handleApiRequest(frame);
@@ -4625,6 +4718,27 @@ var COMMAND_GROUPS = [
       }
     ]
   },
+  {
+    title: "Handle / Identity",
+    rows: [
+      {
+        usage: "handle set <slug>",
+        desc: "Claim a unique human handle (replaces the default)"
+      },
+      {
+        usage: "handle show",
+        desc: "Show your handle + DID fingerprint"
+      },
+      {
+        usage: "identity export [--path <file>]",
+        desc: "Export your identity keypair to carry to a new device"
+      },
+      {
+        usage: "identity import <path> [--force]",
+        desc: "Restore an exported identity (same DID, same handle)"
+      }
+    ]
+  },
   {
     title: "Profile",
     rows: [
@@ -4961,6 +5075,9 @@ function parseHome(args, ctx) {
 function parseHost(args, ctx) {
   return takeFlag(args, "--host") || ctx.defaultHost || process.env.EDGE_BOOK_HOST || DEFAULT_DIALOUT_HOST;
 }
+function relayBaseFromHost(host) {
+  return host.replace(/\/agent\/ws\/?$/, "").replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://");
+}
 function requireArg(value, label) {
   if (!value) throw new EdgeBookError("missing_arg", `Missing ${label}`);
   return value;
@@ -5036,7 +5153,8 @@ async function handleCli(inputArgs, ctx = {}) {
     return { text: usage() };
   }
   if (command === "init") {
-    const handle = takeFlag(args, "--handle");
+    const rawHandle = takeFlag(args, "--handle");
+    const handle = rawHandle !== void 0 ? slugifyHandle(rawHandle) : void 0;
     const displayName = takeFlag(args, "--name");
     const ownerLabel = takeFlag(args, "--owner");
     const shareOwner = takeBoolFlag(args, "--share-owner");
@@ -5052,6 +5170,42 @@ Set it: edge-book profile set --name "<you>" --bio "..." --social telegram=@you
 Tune visibility: edge-book profile visibility bio=off telegram=public name=public`;
     return { text: note, json: identity };
   }
+  if (command === "handle") {
+    const action = args.shift();
+    if (action === "set") {
+      const id = await store.setHandle(slugifyHandle(requireArg(args.shift(), "handle set <slug>")));
+      return { text: `Handle set: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
+    }
+    if (action === "show") {
+      const id = await store.identity();
+      return { text: `${id.handle}
+${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown handle action: ${action} (use "set" or "show")`);
+  }
+  if (command === "identity") {
+    const action = args.shift();
+    if (action === "export") {
+      const bundle = await store.exportIdentity();
+      const p = takeFlag(args, "--path");
+      if (p) {
+        const target = path4.resolve(p);
+        await fs4.mkdir(path4.dirname(target), { recursive: true });
+        await fs4.writeFile(target, `${JSON.stringify(bundle, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+        return { text: `Identity exported \u2192 ${target}`, json: { path: target } };
+      }
+      return { text: JSON.stringify(bundle), json: bundle };
+    }
+    if (action === "import") {
+      const source = requireArg(args.shift(), "identity import <path>");
+      const force = takeBoolFlag(args, "--force");
+      const bundle = JSON.parse(await fs4.readFile(path4.resolve(source), "utf8"));
+      const id = await store.importIdentity(bundle, { force });
+      return { text: `Identity imported: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown identity action: ${action} (use "export" or "import")`);
+  }
   if (command === "profile") {
     const action = args.shift() || "show";
     if (action === "show") {
@@ -5176,7 +5330,8 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
   }
   if (command === "resolve") {
     const target = requireArg(args.shift(), "target");
-    const result = await resolveTarget(store, target, { providers: defaultProviders() });
+    const relayBase = relayBaseFromHost(parseHost(args, ctx));
+    const result = await resolveTarget(store, target, { providers: defaultProviders(relayBase) });
     const label = result.agent_id ?? result.candidates?.[0]?.candidate_id ?? "";
     return { text: `${result.status}  ${label}
 next: ${result.next_action}`, json: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-book",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Run your own Edge Book agent and connect it to the hosted reader.",
   "license": "MIT",
   "type": "module",