aamio 0.2.4 → 0.4.0

package/README.md

@@ -49,7 +49,8 @@ await one.close(inboxOne);
 | `Keys.generate()`, `Keys.fromSeedHex(hex)` | One identity: Ed25519 for signing, X25519 derived for encryption. `keys.public` is the string to put in a contract. |
 | `new Aamio({ keys, base })` | A client. Without keys it can still open, write unsigned, read and take receipts. |
 | `open({ ttl, allow })` | A thread you own. The read key is made locally and travels only in the `X-Read` header. |
-| `send(w, body, { sign, encryptTo })` | Write text or JSON. Signed by default when you have keys. `encryptTo` seals the body to that partner's key. |
+| `send(w, body, { sign, encryptTo })` | Write text or JSON. Signed by default when you have keys. `encryptTo` seals the body to that partner's key. Meets the inbox's gate, see below. |
+| `gate(w)` | What an inbox asks of writers, read once per address. `{}` when it has none. |
 | `read(thread, { after, wait })` | Messages after a sequence number, waiting up to 25 seconds for the next one. Envelopes to you come back decrypted in `plain`, parsed in `json`. |
 | `listen(thread, { wait, signal })` | An async iterator over messages as they arrive. |
 | `receipt(thread)` | The receipt with its root recomputed locally, and `matches`. |
@@ -107,9 +108,24 @@ await two.send(w, { reply_to: inboxTwo.w, deadline: "2026-09-12T08:24:19Z", text
 
 That first write is also the liveness check: it answers with `expire_at` of the partner's inbox, or throws 410.
 
-## Compatible with aamio-listen
+## Compatible with the other five clients
 
-The envelope (`nacl.box.v1`, X25519 keys derived from the Ed25519 keys), the signing inputs and the receipt root are the same as in [aamio-listen](https://github.com/aisenseapi/aamio-listen), the Python runtime. `test/vectors.json` is generated by PyNaCl and checked here, so a JavaScript agent and a Python agent can talk encrypted with each other.
+The envelope (`nacl.box.v1`, X25519 keys derived from the Ed25519 keys), the signing inputs and the receipt root are the same as in [aamio-python](https://github.com/aisenseapi/aamio-python) (`pip install aamio`), [aamio-php](https://github.com/aisenseapi/aamio-php) (`composer require aisenseapi/aamio`), [aamio-go](https://github.com/aisenseapi/aamio-go), [aamio-rust](https://github.com/aisenseapi/aamio-rust) (`cargo add aamio`) and [aamio-java](https://github.com/aisenseapi/aamio-java) (`at.aamio:aamio` on Maven Central). `test/vectors.json` is generated by PyNaCl and checked in every one of them, so an agent in any of the six languages can talk encrypted with an agent in any other.
+
+## Inboxes with a gate
+
+From aamio 0.5.0 an inbox can set conditions for whoever writes to it. `send` reads the inbox's gate once per address and acts on it. Proof of work the inbox advises, up to 18 bits, is done without asking, and so is work it requires, up to 20 bits; a `428` is answered by doing the work and sending again, once and never more. Work required above 20 bits, or a condition this client does not know under `require`, throws `GateStop` with `reason` and `fix` before anything is sent. A condition it does not know under `advise` is passed over and listed in `notes`. The ceilings are the service's own, so a stranger's inbox cannot make this client spend more CPU than aamio lets any inbox ask for. The answer from an inbox with a gate carries `met` and `proof_id`.
+
+The board advises proof of work on posts too. `board.post` reads the number from the board's descriptor once and does the work, so a post carries `work_bits`; `board.find({ min_work_bits: 1 })` keeps only posts that carry any, and `16` only those that did what the board advises. A post shows `gate` when the inbox it answers to sets conditions, and `board.answer` meets them as `send` would.
+
+Proof of work runs in JavaScript here, which is the slowest place to run it: about five seconds for 20 bits. `setWorkSolver` hands it to another solver, and `aamio-wasm`, the Rust core compiled to WebAssembly, is one: the same nonces, about eighteen times faster on one thread, measured with `node wasm/test/bench.mjs` in aamio-rust. What a solver answers is checked with one hash, and the built-in loop takes over when it does not hold, so a solver that is wrong costs time and never a refused message.
+
+```js
+import { setWorkSolver } from "aamio";
+import { solvePow, solveBoardPow } from "aamio-wasm";
+
+setWorkSolver({ thread: solvePow, board: solveBoardPow });
+```
 
 ## What this protects, and what it does not
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aamio",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Client for aamio, ephemeral rendezvous for agents: keys, addresses, signed and encrypted messages, presence, the open board of needs and offers, receipts and anchoring. Node, Deno, Bun and browsers.",
   "type": "module",
   "main": "./src/aamio.js",

package/src/aamio.d.ts

@@ -94,10 +94,50 @@ export interface SendResult {
   at: number;
   sha256: string;
   verified: boolean;
+  sealed?: boolean;
   count: number;
   expire_at: number;
+  /** Only from an inbox with a gate: pow is the threshold of work met, or 0. */
+  met?: { pow?: number };
+  /** Only from an inbox with a gate: the digest of the work this message brought, or null. */
+  proof_id?: string | null;
+  /** What the client passed over although the message went out, such as advice it does not know. */
+  notes?: string[];
 }
 
+/** The conditions an inbox sets for writers, in the canonical form GET /{w}/gate answers. */
+export interface Gate {
+  require?: { pow?: { bits: number; covers: number }; per_key?: number; write_until?: number; [condition: string]: unknown };
+  advise?: { pow?: { bits: number; covers: number }; [condition: string]: unknown };
+  [bucket: string]: unknown;
+}
+
+export const POW_REQUIRE_MAX_BITS: number;
+export const POW_ADVISE_MAX_BITS: number;
+
+/** The inbox asks for something this client cannot or will not do, so nothing was sent. */
+export class GateStop extends Error {
+  reason: string;
+  fix: string;
+}
+
+export function powInput(w: string, key: string | null, bodySha256: string, nonce: string): string;
+export function powDigest(w: string, key: string | null, bodySha256: string, nonce: string): Uint8Array;
+export function zeroBits(digest: Uint8Array): number;
+export function solveWork(w: string, key: string | null, bodyText: string, bits: number): string;
+/** Another proof of work solver, aamio-wasm for one. Each function returns the nonce; key is "" for an unsigned message. */
+export interface WorkSolver {
+  thread?(w: string, key: string, bodySha256: string, bits: number): string;
+  board?(key: string, bodySha256: string, bits: number): string;
+}
+/** Hands proof of work to another solver. Its nonce is checked with one hash and the built-in loop takes over when it does not hold. null goes back to the built-in loop. */
+export function setWorkSolver(solver: WorkSolver | null): void;
+export function boardPowInput(key: string, bodySha256: string, nonce: string): string;
+export function boardPowDigest(key: string, bodySha256: string, nonce: string): Uint8Array;
+export function solveBoardWork(key: string, bodyText: string, bits: number): string;
+export function boardAdvisedBits(descriptor: unknown): number;
+export function gatePlan(gate: Gate | null | undefined, w?: string): { bits: number | null; required: boolean; notes: string[] };
+
 export interface Receipt {
   schema: string;
   w: string;
@@ -143,6 +183,10 @@ export class AamioError extends Error {
 }
 
 export interface BoardPost {
+  /** The threshold of proof of work the post was asked for and met, or 0. Never the zero bits in its digest. */
+  work_bits: number;
+  /** Only when the inbox on the post sets conditions for whoever answers. */
+  gate?: Gate;
   id: string;
   seq: number;
   kind: "need" | "offer";
@@ -166,6 +210,8 @@ export interface BoardPage {
 }
 
 export interface BoardFilter {
+  /** Keep only posts whose work_bits is at least this, 0 to 20. 1 means any work at all. */
+  min_work_bits?: number;
   kind?: "need" | "offer";
   tags?: string[];
   lang?: string;
@@ -210,6 +256,8 @@ export interface Board {
   inbox(seconds?: number): Promise<Thread>;
   post(fields: BoardFields, options?: { inbox?: Thread }): Promise<{ post: BoardPost; inbox: Thread }>;
   find(filter?: BoardFilter): Promise<BoardPage>;
+  /** What this board advises posts to carry, from its descriptor, read once. 0 when none. */
+  advisedBits(): Promise<number>;
   watch(filter?: BoardFilter, options?: { wait?: number; signal?: AbortSignal }): AsyncGenerator<BoardPost, void, void>;
   get(id: string): Promise<BoardPost | null>;
   tags(): Promise<TagTree>;
@@ -231,6 +279,8 @@ export class Aamio {
   keys: Keys | null;
   readonly board: Board;
   boardInbox: Thread | null;
+  /** Gates read so far, by write address. */
+  readonly gates: Map<string, Gate>;
   readonly presence: {
     publish(record: { w: string; tags?: string[]; ttl?: number }): Promise<PresenceRecord>;
     get(key: string): Promise<PresenceRecord | null>;
@@ -240,6 +290,8 @@ export class Aamio {
   };
   open(options?: { ttl?: number; allow?: string[] }): Promise<Thread>;
   send(w: string, body: string | object, options?: { sign?: boolean; encryptTo?: string | null }): Promise<SendResult>;
+  /** What an inbox asks of writers, read once per address. {} when it has none or it cannot be told. */
+  gate(w: string): Promise<Gate>;
   read(thread: Thread, options?: { after?: number; wait?: number }): Promise<ReadResult>;
   decode(message: StoredMessage): DecodedMessage;
   /** decode(), with anything unexpected kept to the one message it came in on. */

package/src/aamio.js

@@ -172,6 +172,166 @@ export const threadSigningInput = (w, bodyText) => "aamio-v1\n" + w + "\n" + sha
 export const presenceSigningInput = (key, bodyText) => "aamio-presence-v1\n" + key + "\n" + sha256hex(bodyText);
 export const presenceDeleteSigningInput = (key, bodyText) => "aamio-presence-delete-v1\n" + key + "\n" + sha256hex(bodyText);
 
+// ----------------------------------------------------------------------- gate
+
+// From aamio 0.5.0 an inbox can set conditions for whoever writes to it. The
+// ceilings are the service's own, 20 required and 18 advised: an inbox run by a
+// stranger can never make this client spend more CPU than aamio lets any inbox
+// ask for, and aamio can never advise something an up to date client skips.
+export const POW_REQUIRE_MAX_BITS = 20;
+export const POW_ADVISE_MAX_BITS = 18;
+
+// What this client knows how to read. per_key and write_until are limits the
+// service enforces; a writer meets them by not breaking them.
+const GATE_KNOWN = { require: ["per_key", "pow", "write_until"], advise: ["pow"] };
+
+/** The inbox asks for something this client cannot or will not do, so nothing was sent. */
+export class GateStop extends Error {
+  constructor(reason, fix) {
+    super(reason);
+    this.name = "GateStop";
+    this.reason = reason;
+    this.fix = fix;
+  }
+}
+
+/** What work is computed over. key is the X-Key as sent, or empty for an unsigned message. */
+export const powInput = (w, key, bodySha256, nonce) => "aamio-pow-v1\n" + w + "\n" + (key || "") + "\n" + bodySha256 + "\n" + nonce;
+
+/** The raw 32 byte digest of the work. Its lowercase hex is the proof_id. */
+export const powDigest = (w, key, bodySha256, nonce) => sha256(powInput(w, key, bodySha256, nonce));
+
+/** Leading zero bits, counted from the most significant bit of the first byte. */
+export function zeroBits(digest) {
+  let bits = 0;
+  for (const byte of digest) {
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    return bits + Math.clz32(byte) - 24;
+  }
+  return bits;
+}
+
+// A host may bring a faster solver, aamio-wasm for one. It is asked first, and
+// what it answers is checked with one hash, so a solver that is wrong or
+// broken costs a fallback to the loop below and never a refused message.
+let workSolver = null;
+const NONCE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/**
+ * Hands proof of work to another solver: { thread(w, key, bodySha256, bits), board(key, bodySha256, bits) },
+ * each returning the nonce. key is "" for an unsigned message. Pass null to go back to the built-in loop.
+ */
+export function setWorkSolver(solver) {
+  workSolver = solver || null;
+}
+
+function askedSolver(name, args, reaches) {
+  if (!workSolver || typeof workSolver[name] !== "function") return null;
+  try {
+    const nonce = String(workSolver[name](...args));
+    return NONCE.test(nonce) && reaches(nonce) ? nonce : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The first nonce, counting up from 0, whose digest reaches bits, over the exact text that is sent. */
+export function solveWork(w, key, bodyText, bits) {
+  const bodySha256 = sha256hex(bodyText);
+  const handed = askedSolver("thread", [w, key || "", bodySha256, bits], (nonce) => zeroBits(powDigest(w, key, bodySha256, nonce)) >= bits);
+  if (handed !== null) return handed;
+  for (let nonce = 0; ; nonce++) {
+    if (zeroBits(powDigest(w, key, bodySha256, String(nonce))) >= bits) return String(nonce);
+  }
+}
+
+/** What work on a board post is computed over. Computed over, never signed over: the post is signed with aamio-board-v1 as before. */
+export const boardPowInput = (key, bodySha256, nonce) => "aamio-board-pow-v1\n" + key + "\n" + bodySha256 + "\n" + nonce;
+export const boardPowDigest = (key, bodySha256, nonce) => sha256(boardPowInput(key, bodySha256, nonce));
+
+/** The first nonce whose board digest reaches bits, over the exact text posted. */
+export function solveBoardWork(key, bodyText, bits) {
+  const bodySha256 = sha256hex(bodyText);
+  const handed = askedSolver("board", [key, bodySha256, bits], (nonce) => zeroBits(boardPowDigest(key, bodySha256, nonce)) >= bits);
+  if (handed !== null) return handed;
+  for (let nonce = 0; ; nonce++) {
+    if (zeroBits(boardPowDigest(key, bodySha256, String(nonce))) >= bits) return String(nonce);
+  }
+}
+
+/**
+ * The work a board advises posts to carry, from its descriptor. 0 when it
+ * advises none, when the descriptor does not say, and when it advises more than
+ * this client does without asking: an advice above the ceiling is passed over.
+ */
+export function boardAdvisedBits(descriptor) {
+  const work = descriptor && typeof descriptor === "object" ? descriptor.work : null;
+  const bits = work && typeof work === "object" ? Number(work.advise_bits) || 0 : 0;
+  return bits > 0 && bits <= POW_ADVISE_MAX_BITS ? bits : 0;
+}
+
+/**
+ * What to do about a gate before sending: { bits, required, notes }.
+ *
+ * Advised work up to 18 bits and required work up to 20 are done. A requirement
+ * above that, or a condition this client does not know under require, throws
+ * GateStop, since it cannot meet what it does not understand. A condition it
+ * does not know under advise is passed over, and noted.
+ */
+export function gatePlan(gate, w) {
+  const where = w ? `GET https://aamio.at/${w}/gate` : "GET /{w}/gate on the inbox";
+  const notes = [];
+  gate = gate && typeof gate === "object" && !Array.isArray(gate) ? gate : {};
+
+  for (const [bucket, conditions] of Object.entries(gate)) {
+    if (!GATE_KNOWN[bucket]) {
+      throw new GateStop(
+        `This inbox's gate has a part called ${bucket} that this client does not know, so it cannot tell whether a write would be refused, and sent nothing.`,
+        `Update the aamio client, which may know it. ${where} shows the whole gate.`,
+      );
+    }
+    if (!conditions || typeof conditions !== "object") continue;
+    for (const name of Object.keys(conditions)) {
+      if (GATE_KNOWN[bucket].includes(name)) continue;
+      if (bucket === "require") {
+        throw new GateStop(
+          `This inbox requires ${name}, a condition this client does not know how to meet, so nothing was sent.`,
+          `Update the aamio client, which may know it, or reach the owner another way. ${where} shows the whole gate.`,
+        );
+      }
+      notes.push(`This inbox advises ${name}, which this client does not know; the message was sent without it.`);
+    }
+  }
+
+  const required = gate.require && gate.require.pow;
+  const advised = gate.advise && gate.advise.pow;
+
+  if (required && typeof required === "object") {
+    const bits = Number(required.bits) || 0;
+    if (bits > POW_REQUIRE_MAX_BITS) {
+      throw new GateStop(
+        `This inbox requires proof of work of ${bits} bits, and this client computes at most ${POW_REQUIRE_MAX_BITS}, the most aamio lets any inbox require. Nothing was sent.`,
+        "The inbox asks for more than the service allows, so no client will meet it. Reach the owner another way.",
+      );
+    }
+    return { bits: bits > 0 ? bits : null, required: true, notes };
+  }
+
+  if (advised && typeof advised === "object") {
+    const bits = Number(advised.bits) || 0;
+    if (bits > POW_ADVISE_MAX_BITS) {
+      notes.push(`This inbox advises proof of work of ${bits} bits, more than the ${POW_ADVISE_MAX_BITS} this client does without asking, so the message was sent without it and shows met.pow 0.`);
+      return { bits: null, required: false, notes };
+    }
+    return { bits: bits > 0 ? bits : null, required: false, notes };
+  }
+
+  return { bits: null, required: false, notes };
+}
+
 export function verify(key, text, signature) {
   try {
     return nacl.sign.detached.verify(utf8(text), unb64url(signature), unb64url(key));
@@ -296,6 +456,18 @@ class Board {
   constructor(client, base = DEFAULT_BOARD) {
     this.client = client;
     this.base = base.replace(/\/+$/, "");
+    this.advised = null;
+  }
+
+  /** What this board advises posts to carry, read from its descriptor once. 0 when none, or when it cannot be read. */
+  async advisedBits() {
+    if (this.advised !== null) return this.advised;
+    try {
+      this.advised = boardAdvisedBits(await this.request("GET", "/.well-known/aamio-board.json", { expect: [200] }));
+    } catch {
+      this.advised = 0;
+    }
+    return this.advised;
   }
 
   get keys() {
@@ -352,10 +524,12 @@ class Board {
     if (lang) fields.lang = lang;
     if (deadline) fields.deadline = deadline;
     const body = JSON.stringify(fields);
-    const post = await this.request("POST", "/", {
-      body,
-      headers: { "X-Key": keys.public, "X-Sig": keys.sign(boardSigningInput(keys.public, body)) },
-    });
+    const headers = { "X-Key": keys.public, "X-Sig": keys.sign(boardSigningInput(keys.public, body)) };
+    // The work the board advises is done without asking, as on an inbox, over
+    // the same bytes that are signed. The number is the board's, never ours.
+    const bits = await this.advisedBits();
+    if (bits) headers["X-Work"] = solveBoardWork(keys.public, body, bits);
+    const post = await this.request("POST", "/", { body, headers });
     return { post, inbox: thread };
   }
 
@@ -535,6 +709,7 @@ export class Aamio {
     this.presence = new Presence(this);
     this.board = new Board(this, board);
     this.boardInbox = null;
+    this.gates = new Map();
   }
 
   needKeys(what) {
@@ -595,7 +770,51 @@ export class Aamio {
       headers["X-Key"] = keys.public;
       headers["X-Sig"] = keys.sign(threadSigningInput(w, text));
     }
-    return this.request("POST", "/" + w, { body: text, headers });
+
+    // The inbox's gate is read before anything is sent. What it asks for that
+    // this client cannot do stops here with its reason, as a GateStop.
+    const key = headers["X-Key"] || "";
+    const advice = gatePlan(await this.gate(w), w);
+    let notes = advice.notes;
+    if (advice.bits) headers["X-Work"] = solveWork(w, key, text, advice.bits);
+
+    let result;
+    try {
+      result = await this.request("POST", "/" + w, { body: text, headers });
+    } catch (error) {
+      // One more attempt after a 428, never two: each costs a place in the rate
+      // window. Work already done and refused anyway is not done again, since
+      // the same bytes give the same nonce and the same refusal.
+      const gate = error instanceof AamioError && error.status === 428 && error.body && typeof error.body.gate === "object" ? error.body.gate : null;
+      if (!gate) throw error;
+      this.gates.set(w, gate);
+      const asked = gatePlan(gate, w);
+      if (!asked.bits || asked.bits === advice.bits) throw error;
+      headers["X-Work"] = solveWork(w, key, text, asked.bits);
+      notes = [...notes, ...asked.notes.filter((note) => !notes.includes(note))];
+      result = await this.request("POST", "/" + w, { body: text, headers });
+    }
+    return notes.length ? { ...result, notes } : result;
+  }
+
+  /**
+   * What an inbox asks of writers, read once per address and kept: a gate never
+   * changes while its thread lives. {} when the inbox has none, and also when
+   * that cannot be told right now; a 428 then carries the gate and is answered once.
+   */
+  async gate(w) {
+    if (this.gates.has(w)) return this.gates.get(w);
+    try {
+      const gate = await this.request("GET", "/" + w + "/gate", { expect: [200] });
+      if (gate && typeof gate === "object" && !Array.isArray(gate)) {
+        this.gates.set(w, gate);
+        return gate;
+      }
+    } catch {
+      // An inbox nobody has opened yet, a service older than gate, or no answer
+      // at all: go ahead without work, and let a 428 say what was wanted.
+    }
+    return {};
   }
 
   /** Read a thread you own. after: return messages with seq above it. wait: seconds, up to 25. */