edge-book 0.3.0 → 0.5.0

package/dist/edge-book.js

@@ -17,6 +17,12 @@ import crypto from "crypto";
 import fs from "fs/promises";
 import os from "os";
 import path from "path";
+var EPHEMERAL_TTL_POLICY = {
+  query: { hard: true },
+  delegation_request: { hard: true },
+  share: { hard: false },
+  coordinate: { hard: false }
+};
 var EdgeBookError = class extends Error {
   code;
   constructor(code, message) {
@@ -46,7 +52,10 @@ var ATTESTATIONS_FILE = "attestations.json";
 var ENDORSEMENTS_FILE = "endorsements.json";
 var SIGNALS_FILE = "signals.json";
 var CAPABILITIES_FILE = "capabilities.json";
+var EPHEMERAL_FILE = "ephemeral-posts.json";
+var ANSWERS_FILE = "answers.json";
 var DEFAULT_SIGNAL_TTL_MS = 6 * 60 * 60 * 1e3;
+var DEFAULT_EPHEMERAL_TTL_MS = 24 * 60 * 60 * 1e3;
 function resolveHome(home) {
   if (home?.trim()) return path.resolve(home.trim());
   if (process.env.EDGE_BOOK_HOME?.trim()) return path.resolve(process.env.EDGE_BOOK_HOME.trim());
@@ -145,6 +154,13 @@ async function readJsonl(file) {
 function relationshipId(a, b) {
   return `rel_${crypto.createHash("sha256").update([a, b].sort().join("|")).digest("base64url").slice(0, 24)}`;
 }
+function computeLifecycle(expiresAt, hard, current) {
+  if (current === "expired" || current === "cancelled" || current === "tombstoned") {
+    return current;
+  }
+  if (Date.parse(expiresAt) <= Date.now()) return hard ? "expired" : "stale";
+  return "active";
+}
 var EdgeBookStore = class {
   home;
   constructor(options = {}) {
@@ -218,6 +234,7 @@ var EdgeBookStore = class {
     const transports = [{ mode: "local", endpoint: this.home }];
     if (config.direct_url) transports.push({ mode: "direct", endpoint: config.direct_url });
     if (config.relay_url) transports.push({ mode: "relay", endpoint: config.relay_url });
+    const caps = Object.values(await this.capabilities()).map((c) => ({ name: c.name, version: c.version, summary: c.summary, status: c.status }));
     const unsigned = {
       schema: "openclaw-agent-card/0.1",
       agent_id: identity.agent_id,
@@ -229,6 +246,7 @@ var EdgeBookStore = class {
       card_version: 1,
       public_keys: [{ id: `${identity.agent_id}#main`, type: "ed25519", public_key_pem: identity.public_key_pem }],
       capabilities: ["friend_request", "friend_gated_message", "feed_read_friends"],
+      ...caps.length ? { advertised_capabilities: caps } : {},
       transports,
       refresh_after: new Date(Date.now() + 24 * 60 * 60 * 1e3).toISOString(),
       expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1e3).toISOString()
@@ -310,6 +328,7 @@ var EdgeBookStore = class {
       // Carry the peer's shared human name (undefined if they didn't opt in, or
       // dropped on refresh if they turned sharing off).
       owner_label: card.owner_label,
+      advertised_capabilities: card.advertised_capabilities,
       card_url: card.card_url,
       known_endpoints: card.transports,
       public_keys: card.public_keys,
@@ -470,6 +489,7 @@ var EdgeBookStore = class {
     }
     const grant = await this.findUsableGrant(peerAgentId, scope);
     if (!grant) throw new EdgeBookError("missing_grant", `No active grant for ${scope}`);
+    await this.assertGrantSignature(grant);
     const envelope = await this.signEnvelope({
       type: "privileged_message",
       to_agent_id: peerAgentId,
@@ -497,6 +517,7 @@ var EdgeBookStore = class {
     if (!grant || grant.status !== "active" || grant.subject_agent_id !== envelope.from_agent_id || !grant.scopes.includes("message.friend")) {
       throw new EdgeBookError("missing_grant", "Message does not carry an active grant issued to sender");
     }
+    await this.assertGrantSignature(grant);
     await appendJsonl(this.file(INBOX_FILE), envelope);
     await this.audit("message.receive", envelope.from_agent_id, { message_id: envelope.message_id });
   }
@@ -614,6 +635,43 @@ var EdgeBookStore = class {
     const { signature, ...rest } = cap;
     return verifyPayload(rest, signature, pub);
   }
+  // Verify an EphemeralPost signature. lifecycle is NOT part of the signed payload
+  // (it is mutable local metadata), so strip both signature and lifecycle before verify.
+  async verifyEphemeral(post) {
+    const identity = await this.identity();
+    let pub = identity.agent_id === post.from_agent ? identity.public_key_pem : void 0;
+    if (!pub) {
+      const c = (await this.contacts())[post.from_agent];
+      pub = c?.public_keys?.[0]?.public_key_pem;
+    }
+    if (!pub) return false;
+    const { signature, lifecycle: _lc, ...signedPayload } = post;
+    return verifyPayload(signedPayload, signature, pub);
+  }
+  // Verify an Answer signature. lifecycle is NOT part of the signed payload.
+  async verifyAnswer(ans) {
+    const identity = await this.identity();
+    let pub = identity.agent_id === ans.answerer_agent_id ? identity.public_key_pem : void 0;
+    if (!pub) {
+      const c = (await this.contacts())[ans.answerer_agent_id];
+      pub = c?.public_keys?.[0]?.public_key_pem;
+    }
+    if (!pub) return false;
+    const { signature, lifecycle: _lc, ...signedPayload } = ans;
+    return verifyPayload(signedPayload, signature, pub);
+  }
+  // Verify a Signal signature. lifecycle is NOT part of the signed payload.
+  async verifySignal(sig) {
+    const identity = await this.identity();
+    let pub = identity.agent_id === sig.from_agent ? identity.public_key_pem : void 0;
+    if (!pub) {
+      const c = (await this.contacts())[sig.from_agent];
+      pub = c?.public_keys?.[0]?.public_key_pem;
+    }
+    if (!pub) return false;
+    const { signature, lifecycle: _lc, ...signedPayload } = sig;
+    return verifyPayload(signedPayload, signature, pub);
+  }
   // Class 3: Endorse — actor-owned reified edge, strongRef parent, evidence link (R5, R8)
   async endorsements() {
     return readJson(this.file(ENDORSEMENTS_FILE), {});
@@ -650,8 +708,7 @@ var EdgeBookStore = class {
   }
   // Class 2: Signal — ephemeral, lifecycle + TTL (R4)
   signalLifecycle(sig) {
-    if (sig.lifecycle === "expired") return "expired";
-    return Date.parse(sig.expires_at) <= Date.now() ? "stale" : "active";
+    return computeLifecycle(sig.expires_at, false, sig.lifecycle);
   }
   async signals() {
     const raw = await readJson(this.file(SIGNALS_FILE), {});
@@ -669,11 +726,10 @@ var EdgeBookStore = class {
       schema: "edge-book/signal/0.1",
       from_agent: identity.agent_id,
       body: input.body,
-      lifecycle: "active",
       created_at: created,
       expires_at
     };
-    const signal = { ...unsigned, signature: signPayload(unsigned, identity.private_key_pem) };
+    const signal = { ...unsigned, lifecycle: "active", signature: signPayload(unsigned, identity.private_key_pem) };
     const all = await this.signals();
     all[signal_id] = signal;
     await this.saveSignals(all);
@@ -691,6 +747,111 @@ var EdgeBookStore = class {
     }
     if (changed) await this.saveSignals(all);
   }
+  // Generic Class-2 ephemeral store (query/share/coordinate/delegation_request, R2/R4)
+  async saveEphemeral(posts) {
+    await writeJson(this.file(EPHEMERAL_FILE), posts);
+  }
+  async ephemeralPosts() {
+    const raw = await readJson(this.file(EPHEMERAL_FILE), {});
+    for (const id of Object.keys(raw)) {
+      raw[id].lifecycle = computeLifecycle(raw[id].expires_at, EPHEMERAL_TTL_POLICY[raw[id].post_type].hard, raw[id].lifecycle);
+    }
+    return raw;
+  }
+  async createEphemeral(type, input) {
+    if (!EPHEMERAL_TTL_POLICY[type]) throw new EdgeBookError("unknown_post_type", `Not an ephemeral Class-2 type: ${type}`);
+    const identity = await this.identity();
+    const post_id = randomId("eph");
+    const created = now();
+    const expires_at = new Date(Date.now() + (input.ttlMs ?? DEFAULT_EPHEMERAL_TTL_MS)).toISOString();
+    const unsigned = {
+      post_id,
+      post_type: type,
+      schema: "edge-book/ephemeral/0.1",
+      from_agent: identity.agent_id,
+      body: input.body,
+      ...input.subject_agent_id ? { subject_agent_id: input.subject_agent_id } : {},
+      ...input.ref ? { ref: input.ref } : {},
+      created_at: created,
+      expires_at
+    };
+    const post = { ...unsigned, lifecycle: "active", signature: signPayload(unsigned, identity.private_key_pem) };
+    const all = await this.ephemeralPosts();
+    all[post_id] = post;
+    await this.saveEphemeral(all);
+    await this.audit(type + ".create", identity.agent_id, { post_id, ...input.subject_agent_id ? { subject_agent_id: input.subject_agent_id } : {} });
+    return post;
+  }
+  async expireEphemeral() {
+    const all = await readJson(this.file(EPHEMERAL_FILE), {});
+    let changed = false;
+    for (const id of Object.keys(all)) {
+      const next = computeLifecycle(all[id].expires_at, EPHEMERAL_TTL_POLICY[all[id].post_type].hard, all[id].lifecycle);
+      if (next !== all[id].lifecycle) {
+        all[id].lifecycle = next;
+        changed = true;
+      }
+    }
+    if (changed) await this.saveEphemeral(all);
+  }
+  async cancelEphemeral(postId) {
+    const all = await readJson(this.file(EPHEMERAL_FILE), {});
+    const post = all[postId];
+    if (!post) throw new EdgeBookError("not_found", `No ephemeral post ${postId}`);
+    post.lifecycle = "cancelled";
+    await this.saveEphemeral(all);
+    await this.audit("ephemeral.cancel", post.from_agent, { post_id: postId });
+    return post;
+  }
+  // Class 3: Answer — actor-owned, strongRef to a Query (R5)
+  async saveAnswers(answers) {
+    await writeJson(this.file(ANSWERS_FILE), answers);
+  }
+  async answers() {
+    return readJson(this.file(ANSWERS_FILE), {});
+  }
+  async createAnswer(input) {
+    if (!input.parent?.uri || !input.parent?.hash) {
+      throw new EdgeBookError("missing_parent", "Answer requires a strongRef parent (uri + hash) \u2014 R5");
+    }
+    const identity = await this.identity();
+    const answer_id = randomId("ans");
+    const unsigned = {
+      answer_id,
+      post_type: "answer",
+      schema: "edge-book/answer/0.1",
+      answerer_agent_id: identity.agent_id,
+      // actor-owned (R5)
+      parent: input.parent,
+      body: input.body,
+      created_at: now()
+    };
+    const answer = { ...unsigned, lifecycle: "active", signature: signPayload(unsigned, identity.private_key_pem) };
+    const all = await this.answers();
+    all[answer_id] = answer;
+    await this.saveAnswers(all);
+    await this.audit("answer.create", identity.agent_id, { answer_id, parent: input.parent.uri });
+    return answer;
+  }
+  // R7: deleting a Query tombstones (archives) it AND its Answers — never hard-drops.
+  async deleteQuery(queryId) {
+    const eph = await readJson(this.file(EPHEMERAL_FILE), {});
+    const q = eph[queryId];
+    if (!q || q.post_type !== "query") throw new EdgeBookError("not_found", `No query ${queryId}`);
+    q.lifecycle = "tombstoned";
+    await this.saveEphemeral(eph);
+    const parentUri = "edgebook:query:" + queryId;
+    const ans = await this.answers();
+    let changed = false;
+    for (const id of Object.keys(ans)) {
+      if (ans[id].parent.uri === parentUri && ans[id].lifecycle !== "tombstoned") {
+        ans[id].lifecycle = "tombstoned";
+        changed = true;
+      }
+    }
+    if (changed) await this.saveAnswers(ans);
+    await this.audit("query.delete", q.from_agent, { query_id: queryId });
+  }
   // Class 1: Capability Advertisement — versioned, deprecate-not-delete (R3)
   async capabilities() {
     return readJson(this.file(CAPABILITIES_FILE), {});
@@ -745,8 +906,21 @@ var EdgeBookStore = class {
     }
     await this.saveCapabilities(caps);
     const sigs = await readJson(this.file(SIGNALS_FILE), {});
-    for (const id of Object.keys(sigs)) sigs[id].lifecycle = "expired";
+    for (const id of Object.keys(sigs)) {
+      if (sigs[id].lifecycle !== "expired") sigs[id].lifecycle = "expired";
+    }
     await this.saveSignals(sigs);
+    const eph = await readJson(this.file(EPHEMERAL_FILE), {});
+    for (const id of Object.keys(eph)) {
+      const lc = eph[id].lifecycle;
+      if (lc === "expired" || lc === "cancelled" || lc === "tombstoned") continue;
+      const t = eph[id].post_type;
+      eph[id].lifecycle = t === "query" || t === "delegation_request" ? "cancelled" : "expired";
+    }
+    await this.saveEphemeral(eph);
+    const ans = await readJson(this.file(ANSWERS_FILE), {});
+    for (const id of Object.keys(ans)) if (ans[id].lifecycle !== "tombstoned") ans[id].lifecycle = "tombstoned";
+    await this.saveAnswers(ans);
     await this.audit("agent.deregister", (await this.identity()).agent_id, {});
   }
   // Issue an `object.read` grant binding ONE object to ONE subject (revocable).
@@ -917,6 +1091,34 @@ var EdgeBookStore = class {
       (grant) => grant.issuer_agent_id === peerAgentId && grant.subject_agent_id === identity.agent_id && grant.status === "active" && grant.scopes.includes(scope) && (!grant.expires_at || Date.parse(grant.expires_at) > Date.now())
     );
   }
+  // ea-openclaw-030 access check #6: a grant authorizes access only if its
+  // issuer signature verifies against the issuer's accepted public key. Grants
+  // are signed on issue (signPayload) but must be re-verified on use so that a
+  // grant tampered after signing, or presented independently of its issuing
+  // envelope, fails closed. Resolves the issuer key from local identity when
+  // self-issued, else from the issuer's contact record.
+  async verifyGrantSignature(grant) {
+    if (!grant.signature) return false;
+    const identity = await this.identity();
+    let publicKey;
+    if (grant.issuer_agent_id === identity.agent_id) {
+      publicKey = identity.public_key_pem;
+    } else {
+      const contacts = await this.contacts();
+      publicKey = contacts[grant.issuer_agent_id]?.public_keys?.[0]?.public_key_pem;
+    }
+    if (!publicKey) return false;
+    return verifyPayload(withoutSignature(grant), grant.signature, publicKey);
+  }
+  // Throwing guard used by every friend-gated access path so the signature
+  // check lives in exactly one place (ea-openclaw-031: build the grant-check
+  // primitive once, have all sites consume it).
+  async assertGrantSignature(grant) {
+    if (!await this.verifyGrantSignature(grant)) {
+      await this.audit("grant.denied", grant.issuer_agent_id, { grant_id: grant.grant_id, reason: "invalid_grant_signature" });
+      throw new EdgeBookError("invalid_grant_signature", "Grant signature does not verify against the issuer key");
+    }
+  }
   async signEnvelope(input) {
     const identity = await this.identity();
     const unsigned = {
@@ -1227,6 +1429,7 @@ var EdgeBookStore = class {
       (candidate) => candidate.issuer_agent_id === identity.agent_id && candidate.subject_agent_id === peerAgentId && candidate.status === "active" && candidate.scopes.includes("feed.read.friends") && (!candidate.expires_at || Date.parse(candidate.expires_at) > Date.now())
     );
     if (!grant) throw new EdgeBookError("missing_grant", "No active feed.read.friends grant for peer");
+    await this.assertGrantSignature(grant);
     const posts = Object.values(await this.posts());
     return posts.filter((post) => post.visibility === "friends" && ["published", "edited"].includes(post.status)).filter((post) => !post.expires_at || Date.parse(post.expires_at) > Date.now()).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
   }
@@ -1567,6 +1770,14 @@ async function handleOwnerApi(req, res, url, adapters) {
     sendJson(res, 200, { capabilities: await store.capabilities() });
     return true;
   }
+  if (req.method === "GET" && url.pathname === "/api/ephemeral") {
+    sendJson(res, 200, { ephemeral: await store.ephemeralPosts() });
+    return true;
+  }
+  if (req.method === "GET" && url.pathname === "/api/answers") {
+    sendJson(res, 200, { answers: await store.answers() });
+    return true;
+  }
   if (req.method === "GET" && url.pathname === "/api/shared-objects") {
     const objects = await store.sharedObjectsFor();
     sendJson(res, 200, { objects: objects.map((object) => ({ ...object, grant_scope: "object.read" })) });
@@ -3434,7 +3645,15 @@ Post taxonomy (spec-0021):
   edge-book signal --body <s> [--ttl-ms <ms>]
   edge-book capability advertise --name <n> --version <v> --summary <s>
   edge-book capability deprecate <capability-id>
-  edge-book capability list`;
+  edge-book capability list
+  edge-book query --body <s> [--ttl-ms <ms>]
+  edge-book share --body <s> [--ref <r>] [--ttl-ms <ms>]
+  edge-book coordinate --body <s> [--with <agent>] [--ttl-ms <ms>]
+  edge-book delegate --to <agent> --body <s> [--ttl-ms <ms>]
+  edge-book answer <query-id> --body <s>
+  edge-book query-delete <query-id>
+  edge-book ephemeral            # list Class-2 ephemeral posts
+  edge-book answers              # list answers`;
 }
 function takeFlag(args, name) {
   const idx = args.indexOf(name);
@@ -3825,6 +4044,40 @@ ${JSON.stringify(result, null, 2)}`, json: result };
     }
     throw new EdgeBookError("unknown_action", `Unknown capability action: ${action}`);
   }
+  if (command === "query" || command === "share" || command === "coordinate" || command === "delegate") {
+    const type = command === "delegate" ? "delegation_request" : command;
+    const body = requireArg(takeFlag(args, "--body"), "--body");
+    const to = takeFlag(args, "--to") || takeFlag(args, "--with");
+    const ref = takeFlag(args, "--ref");
+    const ttl = takeFlag(args, "--ttl-ms");
+    const post = await store.createEphemeral(type, { body, subject_agent_id: to, ref, ttlMs: ttl ? Number(ttl) : void 0 });
+    return { text: `${post.post_type} ${post.post_id}`, json: post };
+  }
+  if (command === "answer") {
+    const queryId = requireArg(args.shift(), "<query-id>");
+    const ephemeral = await store.ephemeralPosts();
+    const query = ephemeral[queryId];
+    if (!query) throw new EdgeBookError("not_found", `No local query ${queryId} to answer`);
+    const { signature: _sig, lifecycle: _lc, ...queryUnsigned } = query;
+    const ans = await store.createAnswer({
+      parent: { uri: "edgebook:query:" + queryId, hash: contentHash(queryUnsigned) },
+      body: requireArg(takeFlag(args, "--body"), "--body")
+    });
+    return { text: `answer ${ans.answer_id}`, json: ans };
+  }
+  if (command === "query-delete") {
+    const queryId = requireArg(args.shift(), "<query-id>");
+    await store.deleteQuery(queryId);
+    return { text: `Tombstoned query ${queryId} and its answers`, json: { query_id: queryId } };
+  }
+  if (command === "ephemeral") {
+    const all = await store.ephemeralPosts();
+    return { text: JSON.stringify(all, null, 2), json: all };
+  }
+  if (command === "answers") {
+    const all = await store.answers();
+    return { text: JSON.stringify(all, null, 2), json: all };
+  }
   throw new EdgeBookError("unknown_command", usage());
 }
 async function runCli(args) {

package/package.json

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