aamio 0.5.4 → 0.5.6

package/README.md

@@ -64,6 +64,28 @@ await one.close(inboxOne);
 
 Errors are `AamioError` with `status` and the server's `body`. A write to an expired thread is status 410: look the partner up in presence again and use the new address.
 
+
+## Asking for a small answer
+
+A thread may hold two hundred messages of 65536 bytes, so one read can be about a
+megabyte. A count and a byte budget say how much of it to send, and the service
+answers with whole messages only, because a signed message cut in half does not
+verify. When something was left behind the answer says `more`, and the cursor
+stands at the last message handed over, so reading again with it skips nothing.
+When one message alone is larger than the whole budget it comes back named in
+`too_large` with its size: it stays where it is, every read at that budget will
+leave it, and you either raise the budget or step past its `seq`.
+
+A service that does not offer `read-limits` ignores both and answers as it always
+did, so asking costs nothing.
+
+```js
+const answer = await aamio.read(thread, { limit: 20, maxBytes: 8192 });
+```
+
+`answer.more` and `answer.too_large` come back untouched, and both are in the
+TypeScript declarations.
+
 ## The board
 
 `open()` keeps the requested allowlist after normalising it. A different or
@@ -157,6 +179,33 @@ import { solvePow, solveBoardPow } from "aamio-wasm";
 setWorkSolver({ thread: solvePow, board: solveBoardPow });
 ```
 
+## Domain keys
+
+A website can publish the public keys of the agents it stands behind at
+`https://<domain>/.well-known/aamio-keys.json`. These functions are that format
+and nothing else: they open no connection, so reading the list is yours, and so
+is the choice of key, which the result says as `supplied_key`. `aamio-python` and
+`aamio-php` have the whole check, with the user's own list of websites and a read
+that reaches only public addresses.
+
+```js
+import { makeDomainKeys, matchDomainKey, normaliseDomain } from "aamio";
+
+normaliseDomain("example.org");                  // the exact host, or null
+const found = matchDomainKey(body, theirKey);    // body is a Uint8Array; a name as the third argument asks for that label
+// found.status is listed, not_listed or invalid
+const file = makeDomainKeys([{ key: me.public, name: "support" }]);
+```
+
+A browser cannot see which address a name resolves to, so it cannot hold the rule
+that a read reaches only public addresses, and these functions do not try.
+
+Take the domain from your own records and never from the message being checked:
+anyone can list their own key on their own site. `listed` says this site listed
+this key when it was read. It is not an identity and it permits nothing, and
+`not_listed` is no evidence of fraud: a key rotated out looks the same. The bytes
+are the exact ones the site served, since a list is checked as it was published.
+
 ## What this protects, and what it does not
 
 Content, when you encrypt: aamio sees an envelope it cannot open. Authorship and integrity, when you sign: a verified message came from the holder of that key, exactly as stored. `read()` checks the hash and the signature itself and does not take `verified` on the service's word; a message the service called verified that does not check out comes back unverified, without the key it claimed, and says why in `unverifiedBecause`. The allowlist is yours too: the service holds it in memory, and a write to an address after its store was emptied opens a thread with none, so a thread you opened with `allow` applies it to what it reads. Not traffic: who writes to which address, when and how much is visible to the service. Not forward secrecy: keys are static until you make new ones. Time stamps come from aamio's clock. The [trust model](https://aamio.at/api.md#trust-model) says exactly what that means.
@@ -171,4 +220,8 @@ The hosts this client uses by default are in four constants at the top of `src/a
 npm test
 ```
 
-The first test needs no network. The second runs two agents against aamio.at and leaves nothing behind.
+This needs no network. The two tests that run agents against aamio.at run only with `AAMIO_LIVE=1`, exactly, and leave nothing behind:
+
+```bash
+npm run test:live
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aamio",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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",
@@ -18,7 +18,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:live": "node -e \"process.env.AAMIO_LIVE = '1'; process.exit(require('node:child_process').spawnSync(process.execPath, ['--test'], { stdio: 'inherit' }).status ?? 1)\""
   },
   "dependencies": {
     "tweetnacl": "^1.0.3"

package/src/aamio.d.ts

@@ -27,6 +27,45 @@ export function scopeAddress(scopeKey: string): string;
 export function isKey(text: unknown): boolean;
 export function keyHash(key: string): string;
 export function hashPrefix(key: string, length?: number): string;
+
+/** Domain keys: the format of a website's list of public aamio keys. It opens no connection. */
+export const DOMAIN_KEYS_VERSION: 1;
+export const DOMAIN_KEYS_PATH: "/.well-known/aamio-keys.json";
+export const DOMAIN_KEYS_MAX_BYTES: 16384;
+export const DOMAIN_KEYS_MAX_KEYS: 64;
+/** A list that is not version 1. reason says why, without echoing the content. */
+export class InvalidDomainKeys extends Error {
+  readonly reason: string;
+  constructor(reason: string);
+}
+export interface DomainKey {
+  key: string;
+  /** A label. It authorises nothing. */
+  name?: string;
+}
+export interface DomainMatch {
+  /** not_listed is no evidence of fraud: a key rotated out, the wrong name or the wrong domain look the same. */
+  status: "listed" | "not_listed" | "invalid";
+  reason: string;
+  detail?: string;
+  matched_name?: string | null;
+  /** Of the exact bytes compared, for fault finding. The domain did not sign it. */
+  document_sha256?: string;
+  /** The key was the caller's to choose and to answer for. */
+  subject_source: "supplied_key";
+}
+/** A public key as aamio writes it: 32 bytes, 43 characters, one spelling only. */
+export function canonicalKey(value: unknown): boolean;
+export function validDomainKeyName(value: unknown): boolean;
+/** The exact host a list is read from, in lowercase, or null. */
+export function normaliseDomain(value: unknown): string | null;
+export function domainKeysUrl(domain: unknown): string | null;
+/** The entries of a version 1 list, from the exact bytes. Throws InvalidDomainKeys. */
+export function parseDomainKeys(raw: Uint8Array): DomainKey[];
+/** Take the domain from your own records and never from the message being checked. A listed key permits nothing. */
+export function matchDomainKey(raw: Uint8Array, key: string, name?: string | null): DomainMatch;
+/** The file for a site to publish, in the bytes every generator writes. Throws InvalidDomainKeys. */
+export function makeDomainKeys(entries: readonly DomainKey[]): Uint8Array;
 export function threadSigningInput(w: string, bodyText: string): string;
 export function boardSigningInput(key: string, bodyText: string): string;
 export function boardDeleteSigningInput(id: string, bodyText: string): string;
@@ -116,6 +155,17 @@ export interface ReadResult {
   next: number;
   waited: number;
   reset?: { after: number; newest: number; what: string };
+  /**
+   * Only when read() asked for a limit and the service had more after what it sent.
+   * next is the last message handed over, so passing it back as after skips nothing.
+   */
+  more?: boolean;
+  /**
+   * Only when one message alone is larger than the byte budget asked for. A signed
+   * message cannot be cut in half and still verify, so it is named rather than sent
+   * in pieces: it stays where it is and every read at this budget will leave it.
+   */
+  too_large?: { seq: number; bytes: number; fix: string };
   note?: string;
 }
 
@@ -344,7 +394,13 @@ export class Aamio {
   planFor(w: string): Promise<{ bits: number | null; required: boolean; notes: string[]; expectedSeconds?: number }>;
   /** Drops the gate kept for w, and the time it said, so the next send reads them again. */
   forgetGate(w: string): void;
-  read(thread: Thread, options?: { after?: number; wait?: number }): Promise<ReadResult>;
+  /**
+   * limit and maxBytes ask the service for a small answer: X-Limit and X-Max-Bytes.
+   * Whole messages only. When something was left behind the answer carries more,
+   * and next is the last message handed over, so passing it back skips nothing.
+   * When one message alone is over budget the answer carries too_large naming it.
+   */
+  read(thread: Thread, options?: { after?: number; wait?: number; limit?: number; maxBytes?: number }): Promise<ReadResult>;
   /** With w, hash and signature are checked first. Without it checked is false and verified/from are the service's claim. */
   decode(message: StoredMessage, w?: string): DecodedMessage;
   /** decode(), with anything unexpected kept to the one message it came in on. */

package/src/aamio.js

@@ -198,6 +198,300 @@ export function hashPrefix(key, length = 8) {
   return keyHash(key).slice(0, length);
 }
 
+// -------------------------------------------------------------- domain keys
+//
+// Which public aamio keys a website says are its own. A site can publish them
+// at https://<domain>/.well-known/aamio-keys.json as
+// {"aamio_keys": 1, "keys": [{"key": "<43 characters>", "name": "support"}]}.
+// This is the format and nothing else: a strict parser, the match, a generator
+// for the file, and the syntax of a domain. It opens no connection and reads no
+// address book. A browser cannot see which address a name resolves to, and a
+// library has no list of websites its user agreed to, so reading a list is for
+// the caller, who also says which key is compared: the result says subject_source
+// supplied_key, and aamio-python and aamio-php have the whole check.
+//
+// Take the domain from your own records and never from the message being
+// checked: anyone can list their own key on their own site. A listed key says
+// that this exact site listed this key when it was read. It is not an identity,
+// an authority to act or proof that a message is true.
+//
+// JSON.parse keeps the last of two members of the same name without a word, so
+// it cannot hold the format's rule about duplicates, and the reader here is its
+// own. test/domain_keys_vectors.json holds what every client answers.
+
+export const DOMAIN_KEYS_VERSION = 1;
+export const DOMAIN_KEYS_PATH = "/.well-known/aamio-keys.json";
+export const DOMAIN_KEYS_MAX_BYTES = 16384;
+export const DOMAIN_KEYS_MAX_KEYS = 64;
+const DOMAIN_MAX_DEPTH = 16;
+const DOMAIN_MAX_INTEGER = 9007199254740991n;
+
+/** A list that is not version 1. reason says why, without echoing the content. */
+export class InvalidDomainKeys extends Error {
+  constructor(reason) {
+    super("invalid domain key list: " + reason);
+    this.name = "InvalidDomainKeys";
+    this.reason = reason;
+  }
+}
+
+/** A public key as aamio writes it: 32 bytes, 43 characters, one spelling only. */
+export function canonicalKey(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value)) return false;
+  // A last character carrying bits past the 32 bytes decodes to the same bytes
+  // as another string; only the one an encoder writes is the key.
+  return b64url(unb64url(value)) === value;
+}
+
+/** A name a list can carry: 1 to 64 characters of a-z, 0-9, dot, underscore and dash. */
+export function validDomainKeyName(value) {
+  return typeof value === "string" && /^[a-z0-9._-]{1,64}$/.test(value);
+}
+
+/**
+ * The exact host a list is read from, in lowercase, or null. Plain ASCII names of
+ * two labels or more. No port, path, IP literal, trailing dot, underscore or
+ * space is trimmed into shape. Internationalised names, xn-- labels, wait until
+ * every client converts them the same way. www.example.org and example.org are
+ * different places, and no parent domain lends its list to a child.
+ */
+export function normaliseDomain(value) {
+  // ASCII first: toLowerCase makes a k of the Kelvin sign.
+  if (typeof value !== "string" || !/^[\x00-\x7f]*$/.test(value)) return null;
+  const domain = value.toLowerCase();
+  const labels = domain.split(".");
+  if (domain.length < 1 || domain.length > 253 || labels.length < 2) return null;
+  for (const label of labels) {
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label) || label.startsWith("xn--")) return null;
+  }
+  // A last label of digits or hex is an old spelling of an IPv4 address.
+  return /^(?:[0-9]+|0x[0-9a-f]+)$/.test(labels[labels.length - 1]) ? null : domain;
+}
+
+/** Where the list of this exact domain is, over HTTPS on the default port, or null. */
+export function domainKeysUrl(domain) {
+  const host = normaliseDomain(domain);
+  return host === null ? null : "https://" + host + DOMAIN_KEYS_PATH;
+}
+
+class DomainReader {
+  // JSON with the format's limits. Objects become a Map, so __proto__ is a member
+  // like any other, lists an Array, integers a BigInt and other numbers a number.
+  // A string holds UTF-16, so a lone surrogate stays what it is and a pair is the
+  // character it spells.
+  constructor(text) {
+    this.text = text;
+    this.at = 0;
+  }
+
+  skip() {
+    while (this.at < this.text.length && " \t\r\n".includes(this.text[this.at])) this.at++;
+  }
+
+  bad(reason = "invalid_json") {
+    return new InvalidDomainKeys(reason);
+  }
+
+  value(level) {
+    this.skip();
+    const c = this.text[this.at];
+    if (c === "{") return this.members(level);
+    if (c === "[") return this.rows(level);
+    if (c === '"') return this.string();
+    for (const [word, meaning] of [["true", true], ["false", false], ["null", null]]) {
+      if (this.text.startsWith(word, this.at)) {
+        this.at += word.length;
+        return meaning;
+      }
+    }
+    return this.number();
+  }
+
+  members(level) {
+    if (level > DOMAIN_MAX_DEPTH) throw this.bad("depth_limit");
+    this.at++;
+    const found = new Map();
+    this.skip();
+    if (this.text[this.at] === "}") {
+      this.at++;
+      return found;
+    }
+    for (;;) {
+      this.skip();
+      if (this.text[this.at] !== '"') throw this.bad();
+      const name = this.string();
+      if (found.has(name)) throw this.bad("duplicate_member");
+      this.skip();
+      if (this.text[this.at] !== ":") throw this.bad();
+      this.at++;
+      found.set(name, this.value(level + 1));
+      this.skip();
+      const next = this.text[this.at++];
+      if (next === "}") return found;
+      if (next !== ",") throw this.bad();
+    }
+  }
+
+  rows(level) {
+    if (level > DOMAIN_MAX_DEPTH) throw this.bad("depth_limit");
+    this.at++;
+    const found = [];
+    this.skip();
+    if (this.text[this.at] === "]") {
+      this.at++;
+      return found;
+    }
+    for (;;) {
+      found.push(this.value(level + 1));
+      this.skip();
+      const next = this.text[this.at++];
+      if (next === "]") return found;
+      if (next !== ",") throw this.bad();
+    }
+  }
+
+  string() {
+    const simple = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+    this.at++;
+    let out = "";
+    for (;;) {
+      if (this.at >= this.text.length) throw this.bad();
+      const c = this.text[this.at++];
+      if (c === '"') return out;
+      if (c < " ") throw this.bad();
+      if (c !== "\\") {
+        out += c;
+        continue;
+      }
+      const escape = this.text[this.at++];
+      if (escape === "u") {
+        const digits = this.text.slice(this.at, this.at + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(digits)) throw this.bad();
+        this.at += 4;
+        out += String.fromCharCode(parseInt(digits, 16));
+      } else if (Object.hasOwn(simple, escape ?? "")) {
+        out += simple[escape];
+      } else {
+        throw this.bad();
+      }
+    }
+  }
+
+  number() {
+    const rest = this.text.slice(this.at);
+    const found = /^-?(?:0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/.exec(rest);
+    if (found === null) throw this.bad();
+    this.at += found[0].length;
+    if (found[1] !== undefined || found[2] !== undefined) {
+      if (!Number.isFinite(Number(found[0]))) throw this.bad("non_finite_number");
+      return Number(found[0]);
+    }
+    const value = BigInt(found[0]);
+    if (value > DOMAIN_MAX_INTEGER || value < -DOMAIN_MAX_INTEGER) throw this.bad("integer_range");
+    return value;
+  }
+}
+
+/**
+ * The entries of a version 1 list, as { key } or { key, name }, from the exact
+ * bytes. A duplicate key, a duplicate member name in any object or one bad entry
+ * makes the whole document invalid: a list is never valid with the bad part left
+ * out. Throws InvalidDomainKeys.
+ */
+export function parseDomainKeys(raw) {
+  if (!(raw instanceof Uint8Array)) throw new InvalidDomainKeys("not_bytes");
+  if (raw.length > DOMAIN_KEYS_MAX_BYTES) throw new InvalidDomainKeys("body_limit");
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+  } catch {
+    throw new InvalidDomainKeys("not_utf8");
+  }
+  if (text.startsWith("\ufeff")) throw new InvalidDomainKeys("byte_order_mark");
+  const reader = new DomainReader(text);
+  const value = reader.value(1);
+  reader.skip();
+  if (reader.at !== text.length) throw new InvalidDomainKeys("invalid_json");
+  if (!(value instanceof Map)) throw new InvalidDomainKeys("object_required");
+  // A BigInt and nothing looser: 1.0, 1e0 and true are not the integer 1.
+  if (value.get("aamio_keys") !== BigInt(DOMAIN_KEYS_VERSION)) throw new InvalidDomainKeys("unsupported_version");
+  const rows = value.get("keys");
+  if (!Array.isArray(rows) || rows.length > DOMAIN_KEYS_MAX_KEYS) throw new InvalidDomainKeys("invalid_keys");
+  const seen = new Set();
+  const entries = [];
+  for (const row of rows) {
+    if (!(row instanceof Map) || !canonicalKey(row.get("key"))) throw new InvalidDomainKeys("invalid_key");
+    const key = row.get("key");
+    if (seen.has(key)) throw new InvalidDomainKeys("duplicate_key");
+    seen.add(key);
+    const entry = { key };
+    // has, since a name of null is a bad name and not a missing one.
+    if (row.has("name")) {
+      if (!validDomainKeyName(row.get("name"))) throw new InvalidDomainKeys("invalid_name");
+      entry.name = row.get("name");
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Whether this exact document lists key, and under name when one is given.
+ *
+ * status is listed, not_listed or invalid. not_listed is no evidence of fraud: a
+ * key rotated out, the wrong name or the wrong domain look the same. The document
+ * hash is of the exact bytes compared, for comparison and fault finding; the
+ * domain did not sign it. The key is the caller's to choose and to answer for,
+ * which the result says as subject_source.
+ */
+export function matchDomainKey(raw, key, name = null) {
+  const subject_source = "supplied_key";
+  if (!canonicalKey(key)) return { status: "invalid", reason: "invalid_subject_key", subject_source };
+  if (name !== null && !validDomainKeyName(name)) return { status: "invalid", reason: "invalid_requested_name", subject_source };
+  let entries;
+  try {
+    entries = parseDomainKeys(raw);
+  } catch (error) {
+    if (!(error instanceof InvalidDomainKeys)) throw error;
+    return { status: "invalid", reason: "invalid_document", detail: error.reason, subject_source };
+  }
+  const document_sha256 = sha256hex(raw);
+  for (const entry of entries) {
+    if (entry.key === key && (name === null || entry.name === name)) {
+      return { status: "listed", reason: "key_listed", matched_name: entry.name ?? null, document_sha256, subject_source };
+    }
+  }
+  return { status: "not_listed", reason: "key_or_name_not_listed", document_sha256, subject_source };
+}
+
+/**
+ * The file for a site to publish, as bytes. They are fixed, so every generator
+ * gives the same file for the same list: two spaces of indentation, aamio_keys
+ * before keys, key before name, ASCII only, and a line break at the end. An empty
+ * list is allowed, since that is how a site says it lists no key, so callers ask
+ * for it on purpose. A list this would refuse to read is refused here as well.
+ */
+export function makeDomainKeys(entries) {
+  const rows = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (!canonicalKey(entry?.key)) throw new InvalidDomainKeys("invalid_key");
+    if (seen.has(entry.key)) throw new InvalidDomainKeys("duplicate_key");
+    seen.add(entry.key);
+    let row = '    {\n      "key": "' + entry.key + '"';
+    if (entry.name !== undefined && entry.name !== null) {
+      if (!validDomainKeyName(entry.name)) throw new InvalidDomainKeys("invalid_name");
+      row += ',\n      "name": "' + entry.name + '"';
+    }
+    rows.push(row + "\n    }");
+  }
+  if (rows.length > DOMAIN_KEYS_MAX_KEYS) throw new InvalidDomainKeys("invalid_keys");
+  const list = rows.length === 0 ? "[]" : "[\n" + rows.join(",\n") + "\n  ]";
+  const raw = utf8('{\n  "aamio_keys": ' + DOMAIN_KEYS_VERSION + ',\n  "keys": ' + list + "\n}\n");
+  parseDomainKeys(raw);
+  return raw;
+}
+
 export const threadSigningInput = (w, bodyText) => "aamio-v1\n" + w + "\n" + sha256hex(bodyText);
 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);
@@ -1035,11 +1329,20 @@ export class Aamio {
    * thread with none. Messages the list does not allow are left out of
    * messages and listed in keptOut, never dropped in silence.
    */
-  async read(thread, { after = 0, wait = 0 } = {}) {
+  async read(thread, { after = 0, wait = 0, limit = null, maxBytes = null } = {}) {
     let path = "/" + thread.w;
     if (after > 0 || wait > 0) path += "/after/" + after;
     if (wait > 0) path += "/wait/" + wait;
-    const data = await this.request("GET", path, { headers: { "X-Read": thread.id } });
+    // How much of the thread to send. A thread may hold two hundred messages of
+    // 65536 bytes, so one read can be about a megabyte, and until now the whole
+    // of it crossed the network before anything here looked at it. Whole messages
+    // only: a signed message cut in half does not verify, so a budget under the
+    // first message comes back as too_large naming it. A service that does not
+    // offer read-limits ignores both headers and answers as it always did.
+    const headers = { "X-Read": thread.id };
+    if (limit !== null && limit !== undefined) headers["X-Limit"] = String(limit);
+    if (maxBytes !== null && maxBytes !== undefined) headers["X-Max-Bytes"] = String(maxBytes);
+    const data = await this.request("GET", path, { headers });
     const allow = normalizeAllow(thread.allow);
     const handed = [];
     const keptOut = [];