aamio 0.6.3 → 0.7.0

package/src/node-scopes.js

@@ -0,0 +1,208 @@
+import { isScopeKey, keyHash, scopeAddress } from "./aamio.js";
+
+/*
+ * The scopes of the local runtime. A scope keeps board posts unlisted for a
+ * group. Here each one has a name, and the name is all a caller passes or
+ * sees. The key is the read capability: it stays in scopes.json, and a share
+ * hands it to a partner sealed, so no model has to hold it. The address is the
+ * write capability and is no secret. Unlisted is not private.
+ *
+ * scopes.json is the file aamio-python and aamio-php keep, in the same shape:
+ * a list of {name, key, address}, with taken_from on a scope that came by
+ * invitation, and {removed_share} for an invitation whose scope was removed.
+ * A home reads the same in all three.
+ *
+ * Everything here is a function of what it is given. The runtime holds the
+ * list and writes the file.
+ */
+
+export const SCOPE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ADDRESS = /^[a-z2-7]{20}$/;
+// One invitation as a channel records a message it handed over, seen_from in
+// node-runtime.js: the hash of its bytes, and who signed them.
+const RECORD = /^[0-9a-f]{64}:(?:[0-9a-f]{16}|-|\?)$/;
+// What a scope share says when scopes.json could not be written, and attention
+// says why. Shorter than the form a kept share takes, which a share is weighed
+// at when that is the longer.
+export const SCOPE_NOT_SAVED = "not kept: could not be saved";
+// How many invitations whose scope was removed scopes.json remembers. One is
+// only read again while its thread lives, and the oldest go first.
+export const SCOPE_REMOVED_KEEP = 256;
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function scopeError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/** The write capability of a scope as it goes on a post: 20 characters of a-z and 2-7. */
+export function isScopeAddress(text) {
+  return typeof text === "string" && ADDRESS.test(text);
+}
+
+/** What an invitation is known by, when it is known: the record a channel keeps of the message. */
+export function isShareRecord(text) {
+  return typeof text === "string" && RECORD.test(text);
+}
+
+/** A scope's name as every runtime takes it. Throws invalid_scope. */
+export function checkScopeName(name) {
+  if (typeof name !== "string" || !SCOPE_NAME.test(name)) {
+    throw scopeError("invalid_scope", "a scope name is 1 to 64 letters, digits, dots, dashes and underscores, starting with a letter or a digit");
+  }
+}
+
+/**
+ * What a scope made elsewhere is given by, checked where nothing has been
+ * opened yet: the key, to read and post, or the address, to post only. Gives
+ * the address the scope has. Throws invalid_scope.
+ */
+export function checkScopeAdd(name, key = null, address = null) {
+  checkScopeName(name);
+  if (key === null && address === null) throw scopeError("invalid_scope", "give the key, to read and post, or the address, to post only");
+  if (key !== null && !isScopeKey(key)) throw scopeError("invalid_scope", "a scope key is 26 to 64 characters of a-z and 0-9. The 20 character address goes in address");
+  if (address !== null && !isScopeAddress(address)) throw scopeError("invalid_scope", "a scope address is the 20 characters of a-z and 2-7 that go on a post");
+  const derived = key !== null ? scopeAddress(key) : address;
+  if (address !== null && derived !== address) throw scopeError("invalid_scope", "that key does not give that address, so one of the two is wrong");
+  return derived;
+}
+
+/** What a share gives: read, the key, or write, the address alone. Throws invalid_access. */
+export function checkAccess(access) {
+  if (access !== "read" && access !== "write") {
+    throw scopeError("invalid_access", "access is read, which gives the key to read and post, or write, which gives the address to post only");
+  }
+}
+
+/** An entry of scopes.json that remembers an invitation whose scope was removed, as aamio-python and aamio-php write it. */
+export function isRemovedShare(entry) {
+  return isObject(entry) && Object.keys(entry).length === 1 && isShareRecord(entry.removed_share);
+}
+
+/** The invitations whose scope was removed, among the entries kept aside. */
+export function removedShares(aside) {
+  return new Set(aside.filter(isRemovedShare).map((entry) => entry.removed_share));
+}
+
+/**
+ * The entries of scopes.json this runtime can use, and the rest. The rest are
+ * never dropped: they go back into the file on every save as they were, so a
+ * hand edit with a typo is there to be corrected rather than gone with the
+ * key in it. unusable counts the ones that are not a removed invitation, which
+ * is remembered among the rest and is no typo to report.
+ */
+export function usableScopes(entries) {
+  const usable = [];
+  const aside = [];
+  const names = new Set();
+  for (const entry of entries) {
+    const key = isObject(entry) ? entry.key ?? null : null;
+    const fine = isObject(entry) && typeof entry.name === "string" && SCOPE_NAME.test(entry.name) && !names.has(entry.name.toLowerCase())
+      && isScopeAddress(entry.address) && (key === null || (isScopeKey(key) && scopeAddress(key) === entry.address));
+    if (fine) {
+      usable.push(entry);
+      names.add(entry.name.toLowerCase());
+    } else {
+      aside.push(entry);
+    }
+  }
+  return { usable, aside, unusable: aside.filter((entry) => !isRemovedShare(entry)).length };
+}
+
+/** The scope with this name, apart from upper and lower case, or null. */
+export function scopeCalled(scopes, name) {
+  const wanted = String(name).toLowerCase();
+  return scopes.find((entry) => entry.name.toLowerCase() === wanted) ?? null;
+}
+
+/** A scope as a caller sees it: never with its key. */
+export function scopeView(entry) {
+  return { name: entry.name, address: entry.address, can_read: Boolean(entry.key) };
+}
+
+/**
+ * What adding a scope would hold, and the list it would keep, or null for the
+ * list when nothing changes. Nothing is kept here. A name already taken by
+ * another address is refused, an address held under another name stays under
+ * that name, and a key for a scope held to post only adds reading to it.
+ */
+export function scopeAddPlan(scopes, name, key = null, address = null) {
+  const derived = checkScopeAdd(name, key, address);
+  const named = scopeCalled(scopes, name);
+  if (named !== null && named.address !== derived) {
+    throw scopeError("scope_exists", `there is a scope called ${name} already, with another address. Remove it or choose another name`);
+  }
+  const before = named ?? scopes.find((entry) => entry.address === derived) ?? null;
+  if (before === null) {
+    const held = { name, key, address: derived };
+    return [held, [...scopes, held]];
+  }
+  if (key !== null && !before.key) {
+    // Held to post only until now. The key adds reading.
+    const held = { ...before, key };
+    return [held, scopes.map((entry) => (entry === before ? held : entry))];
+  }
+  return [before, null];
+}
+
+/**
+ * The name a scope from a partner is kept under: the partner's name, a dot
+ * and the scope's. A partner names its own scopes, and a name is where posts
+ * go. Kept under the bare name, a partner could take review before review was
+ * made here, and the posts meant for it would go where that partner reads.
+ * The partner's part is made of what a name may hold, cut to 24 characters,
+ * and is the start of the key's hash when nothing of the name is left.
+ */
+export function sharedScopeName(partner, name) {
+  checkScopeName(name);
+  const prefix = String(partner.name).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "").slice(0, 24) || keyHash(partner.key).slice(0, 8);
+  return `${prefix}.${name}`.slice(0, 64);
+}
+
+/** The invitations a scope was taken from, as the file holds them. */
+export function takenFrom(entry) {
+  return Array.isArray(entry.taken_from) ? entry.taken_from : [];
+}
+
+/**
+ * The list without one scope, and the rest with the invitations it came from
+ * remembered, in one write: the same invitation read again then keeps
+ * nothing. The newest SCOPE_REMOVED_KEEP are remembered, and the oldest go.
+ */
+export function scopeRemovePlan(scopes, aside, entry) {
+  let rest = [...aside];
+  const removed = removedShares(rest);
+  for (const share of takenFrom(entry)) {
+    if (!isShareRecord(share) || removed.has(share)) continue;
+    rest.push({ removed_share: share });
+    removed.add(share);
+  }
+  const held = rest.filter(isRemovedShare);
+  if (held.length > SCOPE_REMOVED_KEEP) {
+    const dropped = new Set(held.slice(0, held.length - SCOPE_REMOVED_KEEP));
+    rest = rest.filter((item) => !dropped.has(item));
+  }
+  return [scopes.filter((item) => item !== entry), rest];
+}
+
+/** How many bytes a form of a share takes in a message as it is handed over. */
+const formBytes = (form) => Buffer.byteLength(JSON.stringify(form), "utf8");
+
+/** The longer of the two forms a share that may be kept can end in: what a message is weighed at before it is known which. */
+export function longerForm(shown, unsaved) {
+  return formBytes(unsaved) > formBytes(shown) ? unsaved : shown;
+}
+
+/**
+ * value with the scope's key taken out of every string in it. The key goes to
+ * the board in the body of a find and reads the whole scope. Nothing the board
+ * answers has to carry it, and what a runtime shows is read by a model: a
+ * board that sent it back, or a post that quotes it, is shown without it.
+ */
+export function withoutScopeKey(value, key) {
+  if (typeof value === "string") return value.split(key).join("[scope key]");
+  const text = JSON.stringify(value);
+  return text.includes(key) ? JSON.parse(text.split(key).join("[scope key]")) : value;
+}

package/src/node-trace.js

@@ -0,0 +1,170 @@
+import { isKey } from "./aamio.js";
+
+/*
+ * The conversation trace of the local runtime: what was sent to each
+ * counterpart and what came back, as hashes and shapes, never content.
+ * trace.json is the file aamio-python and aamio-php keep too, in the same
+ * shape, so a home reads the same in all three: a book per public key, with
+ * the last fifty sends, the last fifty arrivals, and the last message from
+ * them that was read and opened here, which the next message to them names as
+ * seen.
+ *
+ * Everything here is a function of what it is given. The runtime holds the
+ * books and writes the file.
+ */
+
+export const TRACE_KEEP = 50;
+export const TRACE_KEYS = 100;
+// How many field names a row keeps, and how long a name may be, in characters,
+// as aamio-python and aamio-php count them. The names of a
+// message that arrived are its sender's to choose: one message of the largest
+// size can carry thousands of them, fifty such from one key were megabytes in a
+// file that is written again at every read, and a board inbox takes any signed
+// key. The fields this runtime and the other two write are a handful of short
+// names, so what is cut is only what was made to be long.
+export const TRACE_FIELDS = 32;
+export const TRACE_FIELD_CHARS = 64;
+
+const HASH = /^[0-9a-f]{64}$/;
+
+/** The sha256 of a message as the service gives it: 64 lowercase hex characters. */
+export function isMessageHash(value) {
+  return typeof value === "string" && HASH.test(value);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// What a row of the trace may hold, and of what kind. trace.json is this
+// runtime's own file and is still read as if anyone could have written it: a
+// nested field of the wrong type once reached the code that records a send,
+// after the message had gone, and the caller heard an error about a message
+// that was delivered (aamio-python, 25 September 2026).
+export const TRACE_SENT_FIELDS = {
+  message_id: "string", at: "int", w: "string", status: "int", outcome: "string", seq: "int", sha256: "hash",
+  sealed: "bool", bytes: "int", fields: "list", text_chars: "int", re: "hash", seen: "hash",
+};
+export const TRACE_RECEIVED_FIELDS = {
+  at: "int", channel: "string", w: "string", seq: "int", sha256: "hash", encrypted: "bool", format: "string",
+  error: "string", fields: "list", text_chars: "int", re: "hash", seen: "hash",
+};
+export const TRACE_READ_FIELDS = { sha256: "hash", seq: "int", w: "string", at: "int" };
+
+function traceValue(kind, value) {
+  if (kind === "hash") return isMessageHash(value) ? value : null;
+  if (kind === "list") {
+    if (!Array.isArray(value)) return null;
+    // length counts UTF-16 units, never fewer than the characters: only a name longer than that is counted again.
+    const short = (item) => typeof item === "string" && (item.length <= TRACE_FIELD_CHARS || [...item].length <= TRACE_FIELD_CHARS);
+    return value.filter(short).sort().slice(0, TRACE_FIELDS);
+  }
+  if (kind === "int") return Number.isInteger(value) ? value : null;
+  if (kind === "bool") return typeof value === "boolean" ? value : null;
+  return typeof value === "string" ? value : null;
+}
+
+/** One row of a trace as the runtimes write it: the fields they know, each of the kind they write or null. */
+export function traceRow(row, fields) {
+  if (!isObject(row)) return null;
+  const out = {};
+  for (const [name, kind] of Object.entries(fields)) if (name in row) out[name] = traceValue(kind, row[name]);
+  return out;
+}
+
+/** Rows as the file held them. A row without what names it, the message id of a send or the hash of what arrived, says nothing and is left out. */
+function traceRows(found, fields, keep, required) {
+  const rows = Array.isArray(found) ? found.map((item) => traceRow(item, fields)) : [];
+  return rows.filter((row) => row !== null && row[required] !== null && row[required] !== undefined).slice(-keep);
+}
+
+/** trace.json as the runtimes write it, whatever the file held: a book per key, rows of a known shape, within the bounds. */
+export function normalizeTraces(traces, keep = TRACE_KEEP, keys = TRACE_KEYS) {
+  const books = {};
+  for (const [key, book] of isObject(traces) ? Object.entries(traces) : []) {
+    if (!isKey(key) || !isObject(book)) continue;
+    const last = traceRow(book.last_read, TRACE_READ_FIELDS);
+    books[key] = {
+      sent: traceRows(book.sent, TRACE_SENT_FIELDS, keep, "message_id"),
+      received: traceRows(book.received, TRACE_RECEIVED_FIELDS, keep, "sha256"),
+      last_read: last && last.sha256 ? last : null,
+      active: Number.isInteger(book.active) ? book.active : 0,
+    };
+  }
+  const names = Object.keys(books);
+  for (const stale of names.sort((a, b) => books[a].active - books[b].active).slice(0, Math.max(0, names.length - keys))) delete books[stale];
+  return books;
+}
+
+/**
+ * One counterpart's record, with each message sent next to what came back
+ * about it. A claim is exact. A verified message from them whose seen names a
+ * sha256 says their runtime read and opened that message, and nothing more: not
+ * the ones sent before it, not another channel's. A message nothing names is
+ * unknown, never unread.
+ */
+export function traceView(book, limit) {
+  const sentRows = (Array.isArray(book?.sent) ? book.sent : []).filter(isObject);
+  const receivedRows = (Array.isArray(book?.received) ? book.received : []).filter(isObject);
+  const claimed = new Set(receivedRows.filter((row) => isMessageHash(row.seen)).map((row) => row.seen));
+  const answered = new Set(receivedRows.filter((row) => isMessageHash(row.re)).map((row) => row.re));
+  const mine = new Map(sentRows.filter((row) => isMessageHash(row.sha256)).map((row) => [row.sha256, row]));
+  const delivered = sentRows.filter((row) => row.status === 201 && isMessageHash(row.sha256));
+  const noClaim = delivered.filter((row) => !claimed.has(row.sha256)).map((row) => row.message_id ?? null);
+  const sent = sentRows.slice(-limit).map((record) => {
+    const stored = record.status === 201 && isMessageHash(record.sha256) ? record.sha256 : null;
+    return { ...record, seen_by_them: stored !== null && claimed.has(stored) ? true : null, answered_by_them: stored !== null && answered.has(stored) ? true : null };
+  });
+  const received = receivedRows.slice(-limit).map((record) => {
+    const row = { ...record };
+    for (const [field, as] of [["re", "answers"], ["seen", "acknowledges"]]) {
+      if (!isMessageHash(record[field])) continue;
+      const ours = mine.get(record[field]);
+      row[as] = ours ? { seq: ours.seq ?? null, sha256: ours.sha256, at: ours.at ?? null } : { sha256: record[field], note: "no confirmed send in this record has this sha256" };
+    }
+    return row;
+  });
+  const elsewhere = [...claimed].filter((hash) => !mine.has(hash));
+  return { sent, received, no_read_claim: noClaim, note: traceNote(sentRows, receivedRows, delivered, noClaim, elsewhere) };
+}
+
+/**
+ * What the record says, in words, and no more than it says. A send the service
+ * did not confirm is not a send it did not store: the answer can be lost after
+ * the message was stored, and whoever is told it was not stored sends the text
+ * again as new bytes, which is a second message. The words are aamio-python's.
+ */
+export function traceNote(sent, received, delivered, noClaim, elsewhere) {
+  if (!sent.length) return "Nothing sent to them is recorded here.";
+  const named = received.some((row) => isMessageHash(row.seen));
+  const turnedAway = sent.filter((row) => row.outcome === "refused" && row.status !== 201).length;
+  const unsettled = sent.length - delivered.length - turnedAway;
+  let note;
+  if (!delivered.length) {
+    note = "No message here has an answer from the service that confirms it was stored.";
+  } else if (!named) {
+    const said = received.length ? "Nothing from them has named a message of yours as read" : "Nothing has come back from them";
+    note = said + ", so each is unknown, not unread. A client that does not send seen says nothing, and neither does one "
+      + "that cannot open what it gets: every message here is sealed to their key, so a reader without it sees an "
+      + "envelope and no text. The sha256 of each message is what the service stored, byte for byte; ask them for "
+      + "the sha256 they read.";
+  } else {
+    note = `${delivered.length} delivered, and their runtime says it read and opened ${delivered.length - noClaim.length} of them.`;
+    if (noClaim.length) {
+      note += ` For ${noClaim.length} there is no claim kept here: that is unknown, not unread, since each message from them names only `
+        + "the last of yours it had read when it was written, and this record keeps fifty each way.";
+    }
+  }
+  if (elsewhere.length) {
+    note += ` They named ${elsewhere.length} message(s) this record cannot match to a send the service confirmed: older than this record, `
+      + "sent from elsewhere, or sent from here without an answer that confirmed it.";
+  }
+  if (unsettled) {
+    note += ` For ${unsettled} no answer settled whether the service stored it, so it may be stored already. Check each one's status `
+      + "and outcome first, and if it must go again, retry it from the outbox: the same bytes are marked a replay "
+      + "where the first arrived, and new bytes would be a second message.";
+  }
+  if (turnedAway) note += ` The service turned away ${turnedAway}; the status of each says why.`;
+  if (named) note += " A claim covers the one message it names. It says their runtime opened it, not that anyone understood it or acted on it.";
+  return note;
+}