@weaveprotocol/core 0.1.0

package/dist/schemas/screens.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @module schemas/screens
+ * Screens: an app's own UI, kept on a collection definition and run sealed.
+ *
+ * A definition may carry a `screen` — one HTML document, scripts and styles
+ * inline. An app that wants to show it runs it in a frame that has no network,
+ * no storage and no way to reach the page around it, and hands it one thing:
+ * a message port to a {@link createScreenBridge bridge}. Through that port the
+ * screen reads and writes the records of the collections its app named, in
+ * one space, as whoever is looking — so every rule still holds, and a screen
+ * can do nothing its viewer couldn't.
+ *
+ * Inside the frame, the screen finds `window.weave` (see {@link SCREEN_GUIDE}).
+ * The port is handed over once, when the document is written; a frame that
+ * navigates somewhere else leaves it behind, so a page it navigates to hears
+ * nothing.
+ */
+import type { P2PNode } from '../node/types.js';
+import type { Link } from '../types.js';
+/** What a screen sees of a record */
+export interface ScreenRecord {
+    readonly key: string;
+    /** The same as `key` — what a screen written by guessing tends to reach for */
+    readonly id: string;
+    readonly collection: string;
+    readonly body: unknown;
+    /** The same as `body` */
+    readonly data: unknown;
+    readonly links: ReadonlyArray<Link>;
+    /** The account that created it */
+    readonly createdBy: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Whether the person looking created it */
+    readonly mine: boolean;
+    /** Written by an agent for `createdBy`'s account */
+    readonly viaAgent: boolean;
+}
+/** Who is looking */
+export interface ScreenViewer {
+    readonly did: string;
+    readonly name: string;
+}
+/** How to write a screen — for an agent, in `apps_screen_guide`, and for people */
+export declare const SCREEN_GUIDE = "A screen is one HTML document (scripts and styles inline, at most 48 KB) put on a collection definition as \"screen\".\nWhen the app is added, apps in the space can show it instead of plain lists. It runs sealed: no network (no fetch, no\nimages from URLs, no fonts from URLs), no storage, no popups, no forms that submit. Keep state in records, never in the page.\n\nInside it, window.weave is:\n  weave.me                          { did, name } \u2014 who is looking\n  weave.collections                 the collection names this screen may use (its app's)\n  await weave.list(collection, { where? })   records, oldest first: { key, collection, body, links, createdBy, createdAt, updatedAt, mine, viaAgent }\n                                    where: { \"link:<rel>\": \"<record key>\" } for records linking there, { field: value } for a field's value\n  await weave.get(key)              one record, or null\n  await weave.put(collection, body, { links?, key? })   \u2192 the record written, as the person looking\n  await weave.update(key, body, { links? })             \u2192 the next version\n  await weave.remove(key)\n  await weave.people()              [{ did, name }] \u2014 everyone in the space who said their name\n  weave.onChange(callback)          called whenever records in the space change, here or on another device; returns a function to stop\n\nCalls may also take one object instead: weave.list({ collection, where }), weave.put({ collection, body, links, key }),\nweave.update({ key, body, links }), weave.remove({ key }). Records answer to id / data as well as key / body.\nEvery write is checked against the collection's rules, as the person looking: a refused write rejects with the reason.\nAn error the screen doesn't catch is shown to the person, so they can tell you about it.\nLinks look like { rel: \"game\", to: \"<record key>\" }, with the roles the definition declares.\nDraw everything from weave.list(...) and redraw on weave.onChange \u2014 other people's moves arrive that way.\nTwo people can write at once: design collections so that clashes resolve by the rules (onePer, creator-only edits), not by the screen.\nUse plain DOM; no libraries can be loaded. Prefer system fonts and simple, readable styling that works in light and dark.";
+/** The script put in front of a screen's document: `window.weave`, over the port the host page kept for it */
+export declare const SCREEN_CLIENT = "(() => {\n  const given = window.__weave;\n  delete window.__weave;\n  if (!given) return;\n  const port = given.port;\n  const pending = new Map();\n  const listeners = new Set();\n  let next = 0;\n  const call = (method, ...args) =>\n    new Promise((resolve, reject) => {\n      const id = ++next;\n      pending.set(id, { resolve, reject });\n      port.postMessage({ id, method, args });\n    });\n  port.onmessage = (event) => {\n    const message = event.data || {};\n    if (message.change) {\n      for (const listener of listeners) {\n        try { listener(); } catch (error) { console.error(error); }\n      }\n      return;\n    }\n    const waiting = pending.get(message.id);\n    if (!waiting) return;\n    pending.delete(message.id);\n    if (message.ok) waiting.resolve(message.value);\n    else waiting.reject(new Error(message.error));\n  };\n  // Shown to the person, so a screen that fails says why instead of sitting blank.\n  const report = (message) => {\n    let bar = document.getElementById('__weave-error');\n    if (!bar) {\n      bar = document.createElement('div');\n      bar.id = '__weave-error';\n      bar.setAttribute('role', 'alert');\n      bar.style.cssText = 'position:fixed;left:8px;right:8px;bottom:8px;z-index:2147483647;padding:8px 10px;border-radius:8px;background:#fff0f0;color:#b00020;border:1px solid #f3c2c2;font:12px/1.4 system-ui,sans-serif;white-space:pre-wrap';\n      (document.body || document.documentElement).appendChild(bar);\n    }\n    bar.textContent = 'This screen hit an error: ' + message;\n  };\n  addEventListener('error', (event) => report(event.message || String(event.error)));\n  addEventListener('unhandledrejection', (event) => report(event.reason && event.reason.message ? event.reason.message : String(event.reason)));\n  // weave.me is who is looking; calling it \u2014 weave.me() \u2014 gives the same.\n  // (defineProperty, because a function's own \"name\" can't be assigned)\n  const me = () => ({ did: given.me.did, name: given.me.name });\n  Object.defineProperty(me, 'did', { value: given.me.did, enumerable: true });\n  Object.defineProperty(me, 'name', { value: given.me.name, enumerable: true });\n  window.weave = Object.freeze({\n    me: Object.freeze(me),\n    collections: Object.freeze(given.collections.slice()),\n    list: (collection) => call('list', collection),\n    get: (key) => call('get', key),\n    put: (collection, body, options) => call('put', collection, body, options || {}),\n    update: (key, body, options) => call('update', key, body, options || {}),\n    remove: (key) => call('remove', key),\n    people: () => call('people'),\n    onChange: (listener) => {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n  });\n})();";
+/** The document a host page writes into its frame: the client, then the screen */
+export declare function screenDocument(screen: string): string;
+export interface ScreenBridge {
+    /** Tell the screen that records changed */
+    changed(): void;
+    /** Stop answering, and stop listening to the node */
+    close(): void;
+}
+/**
+ * Answers a screen's calls over `port`, for one space and these collections,
+ * as the node's account. Every write goes through the node like any other,
+ * so the collection's rules decide.
+ */
+export declare function createScreenBridge(params: {
+    readonly node: P2PNode;
+    readonly spaceId: string;
+    readonly collections: ReadonlyArray<string>;
+    readonly port: MessagePort;
+}): ScreenBridge;
+//# sourceMappingURL=screens.d.ts.map

package/dist/schemas/screens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screens.d.ts","sourceRoot":"","sources":["../../src/schemas/screens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAc,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,mFAAmF;AACnF,eAAO,MAAM,YAAY,yuEAuBiG,CAAC;AAE3H,8GAA8G;AAC9G,eAAO,MAAM,aAAa,wtFA6DpB,CAAC;AAEP,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAgCD,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;IAChB,qDAAqD;IACrD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B,GAAG,YAAY,CAiHf"}

package/dist/schemas/screens.js

@@ -0,0 +1,242 @@
+/** How to write a screen — for an agent, in `apps_screen_guide`, and for people */
+export const SCREEN_GUIDE = `A screen is one HTML document (scripts and styles inline, at most 48 KB) put on a collection definition as "screen".
+When the app is added, apps in the space can show it instead of plain lists. It runs sealed: no network (no fetch, no
+images from URLs, no fonts from URLs), no storage, no popups, no forms that submit. Keep state in records, never in the page.
+
+Inside it, window.weave is:
+  weave.me                          { did, name } — who is looking
+  weave.collections                 the collection names this screen may use (its app's)
+  await weave.list(collection, { where? })   records, oldest first: { key, collection, body, links, createdBy, createdAt, updatedAt, mine, viaAgent }
+                                    where: { "link:<rel>": "<record key>" } for records linking there, { field: value } for a field's value
+  await weave.get(key)              one record, or null
+  await weave.put(collection, body, { links?, key? })   → the record written, as the person looking
+  await weave.update(key, body, { links? })             → the next version
+  await weave.remove(key)
+  await weave.people()              [{ did, name }] — everyone in the space who said their name
+  weave.onChange(callback)          called whenever records in the space change, here or on another device; returns a function to stop
+
+Calls may also take one object instead: weave.list({ collection, where }), weave.put({ collection, body, links, key }),
+weave.update({ key, body, links }), weave.remove({ key }). Records answer to id / data as well as key / body.
+Every write is checked against the collection's rules, as the person looking: a refused write rejects with the reason.
+An error the screen doesn't catch is shown to the person, so they can tell you about it.
+Links look like { rel: "game", to: "<record key>" }, with the roles the definition declares.
+Draw everything from weave.list(...) and redraw on weave.onChange — other people's moves arrive that way.
+Two people can write at once: design collections so that clashes resolve by the rules (onePer, creator-only edits), not by the screen.
+Use plain DOM; no libraries can be loaded. Prefer system fonts and simple, readable styling that works in light and dark.`;
+/** The script put in front of a screen's document: `window.weave`, over the port the host page kept for it */
+export const SCREEN_CLIENT = `(() => {
+  const given = window.__weave;
+  delete window.__weave;
+  if (!given) return;
+  const port = given.port;
+  const pending = new Map();
+  const listeners = new Set();
+  let next = 0;
+  const call = (method, ...args) =>
+    new Promise((resolve, reject) => {
+      const id = ++next;
+      pending.set(id, { resolve, reject });
+      port.postMessage({ id, method, args });
+    });
+  port.onmessage = (event) => {
+    const message = event.data || {};
+    if (message.change) {
+      for (const listener of listeners) {
+        try { listener(); } catch (error) { console.error(error); }
+      }
+      return;
+    }
+    const waiting = pending.get(message.id);
+    if (!waiting) return;
+    pending.delete(message.id);
+    if (message.ok) waiting.resolve(message.value);
+    else waiting.reject(new Error(message.error));
+  };
+  // Shown to the person, so a screen that fails says why instead of sitting blank.
+  const report = (message) => {
+    let bar = document.getElementById('__weave-error');
+    if (!bar) {
+      bar = document.createElement('div');
+      bar.id = '__weave-error';
+      bar.setAttribute('role', 'alert');
+      bar.style.cssText = 'position:fixed;left:8px;right:8px;bottom:8px;z-index:2147483647;padding:8px 10px;border-radius:8px;background:#fff0f0;color:#b00020;border:1px solid #f3c2c2;font:12px/1.4 system-ui,sans-serif;white-space:pre-wrap';
+      (document.body || document.documentElement).appendChild(bar);
+    }
+    bar.textContent = 'This screen hit an error: ' + message;
+  };
+  addEventListener('error', (event) => report(event.message || String(event.error)));
+  addEventListener('unhandledrejection', (event) => report(event.reason && event.reason.message ? event.reason.message : String(event.reason)));
+  // weave.me is who is looking; calling it — weave.me() — gives the same.
+  // (defineProperty, because a function's own "name" can't be assigned)
+  const me = () => ({ did: given.me.did, name: given.me.name });
+  Object.defineProperty(me, 'did', { value: given.me.did, enumerable: true });
+  Object.defineProperty(me, 'name', { value: given.me.name, enumerable: true });
+  window.weave = Object.freeze({
+    me: Object.freeze(me),
+    collections: Object.freeze(given.collections.slice()),
+    list: (collection) => call('list', collection),
+    get: (key) => call('get', key),
+    put: (collection, body, options) => call('put', collection, body, options || {}),
+    update: (key, body, options) => call('update', key, body, options || {}),
+    remove: (key) => call('remove', key),
+    people: () => call('people'),
+    onChange: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  });
+})();`;
+/** The document a host page writes into its frame: the client, then the screen */
+export function screenDocument(screen) {
+    // Before anything the screen says, so `weave` is there when its scripts run.
+    return `<script>${SCREEN_CLIENT}</script>\n${screen}`;
+}
+const toScreen = (record, viewer) => ({
+    key: record.key,
+    id: record.key,
+    collection: record.collection,
+    body: record.body,
+    data: record.body,
+    links: record.links,
+    createdBy: record.createdBy,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    mine: record.createdBy === viewer,
+    viaAgent: record.viaAgent === true,
+});
+/** Only plain data crosses into a screen, and only this much of it */
+function plain(value, what) {
+    const text = JSON.stringify(value ?? null);
+    if (text.length > 256 * 1024)
+        throw new Error(`${what} is too large`);
+    return JSON.parse(text);
+}
+function linksOf(options) {
+    const links = options?.links;
+    if (links === undefined)
+        return {};
+    if (!Array.isArray(links) || !links.every((l) => typeof l?.rel === 'string' && typeof l?.to === 'string')) {
+        throw new Error('links must be a list of { rel, to }');
+    }
+    return { links: links.map((l) => ({ rel: l.rel, to: l.to })) };
+}
+/**
+ * Answers a screen's calls over `port`, for one space and these collections,
+ * as the node's account. Every write goes through the node like any other,
+ * so the collection's rules decide.
+ */
+export function createScreenBridge(params) {
+    const { node, spaceId, port } = params;
+    const allowed = new Set(params.collections);
+    let closed = false;
+    const names = [...allowed].map((name) => `"${name}"`).join(', ');
+    const collectionOf = (name) => {
+        if (typeof name !== 'string')
+            throw new Error(`Name the collection as text, like weave.list("${[...allowed][0] ?? 'app.example.thing'}"). This screen may use ${names}.`);
+        if (!allowed.has(name))
+            throw new Error(`This screen can't use "${name}". It may use ${names}.`);
+        return name;
+    };
+    const ownRecord = async (key) => {
+        if (typeof key !== 'string')
+            throw new Error('Name the record by its key, as text: weave.update(record.key, body)');
+        const record = await node.records.get(spaceId, key);
+        if (!record || !allowed.has(record.collection))
+            throw new Error(`No record ${key} this screen can use`);
+        return record;
+    };
+    /** `f(a, b)` or `f({ a, b })`: a screen written by guessing may use either */
+    const spread = (args, keys) => {
+        const first = args[0];
+        if (first && typeof first === 'object' && !Array.isArray(first) && keys.some((k) => k in first)) {
+            return Object.fromEntries(keys.map((k) => [k, first[k]]));
+        }
+        return Object.fromEntries(keys.map((k, i) => [k, args[i]]));
+    };
+    /** `{ "link:game": key }` for records linking there, `{ field: value }` for a field's value */
+    const matches = (record, where) => {
+        if (!where || typeof where !== 'object')
+            return true;
+        return Object.entries(where).every(([field, value]) => field.startsWith('link:')
+            ? record.links.some((link) => link.rel === field.slice(5) && link.to === value)
+            : record.body?.[field] === value);
+    };
+    const methods = {
+        list: async (...args) => {
+            const first = args[0];
+            const { collection, where } = first && typeof first === 'object' ? { collection: first.collection, where: first.where } : { collection: first, where: args[1]?.where };
+            const records = await node.records.list(spaceId, { collection: collectionOf(collection) });
+            return records.filter((record) => matches(record, where)).map((record) => toScreen(record, node.did));
+        },
+        get: async (...args) => {
+            const { key } = spread(args, ['key']);
+            try {
+                return toScreen(await ownRecord(key), node.did);
+            }
+            catch {
+                return null;
+            }
+        },
+        put: async (...args) => {
+            const first = args[0];
+            const [collection, body, options] = first && typeof first === 'object' && 'collection' in first ? [first.collection, first.body, { links: first.links, key: first.key }] : args;
+            const key = options?.key;
+            if (key !== undefined && typeof key !== 'string')
+                throw new Error('key must be text');
+            const record = await node.records.put(spaceId, collectionOf(collection), plain(body, 'The record'), {
+                ...linksOf(options === null || typeof options !== 'object' || options.links === undefined ? {} : options),
+                ...(key !== undefined ? { key } : {}),
+            });
+            return toScreen(record, node.did);
+        },
+        update: async (...args) => {
+            const first = args[0];
+            const [key, body, options] = first && typeof first === 'object' && 'key' in first ? [first.key, first.body, { links: first.links }] : args;
+            const record = await ownRecord(key);
+            const links = options?.links === undefined ? {} : linksOf(options);
+            return toScreen(await node.records.update(spaceId, record.key, plain(body, 'The record'), links), node.did);
+        },
+        remove: async (...args) => {
+            const { key } = spread(args, ['key']);
+            const record = await ownRecord(key);
+            await node.records.delete(spaceId, record.key);
+            return null;
+        },
+        people: async () => (await node.spaces.profiles(spaceId)).map((profile) => ({ did: profile.did, name: profile.name })),
+    };
+    port.onmessage = (event) => {
+        if (closed)
+            return;
+        const message = event.data;
+        if (typeof message?.id !== 'number' || typeof message.method !== 'string' || !Object.hasOwn(methods, message.method))
+            return;
+        const args = Array.isArray(message.args) ? message.args : [];
+        methods[message.method](...args).then((value) => !closed && port.postMessage({ id: message.id, ok: true, value: plain(value, 'The answer') }), (error) => !closed && port.postMessage({ id: message.id, ok: false, error: error instanceof Error ? error.message : String(error) }));
+    };
+    // Changes arrive in bursts while syncing; one nudge per burst is enough.
+    let soon = null;
+    const changed = () => {
+        if (closed || soon)
+            return;
+        soon = setTimeout(() => {
+            soon = null;
+            if (!closed)
+                port.postMessage({ change: true });
+        }, 50);
+    };
+    const stop = node.subscribe((event) => {
+        if (event.type === 'records' && event.space === spaceId)
+            changed();
+    });
+    return {
+        changed,
+        close() {
+            closed = true;
+            if (soon)
+                clearTimeout(soon);
+            stop();
+            port.close();
+        },
+    };
+}
+//# sourceMappingURL=screens.js.map

package/dist/schemas/screens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screens.js","sourceRoot":"","sources":["../../src/schemas/screens.ts"],"names":[],"mappings":"AA8CA,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;0HAuB8F,CAAC;AAE3H,8GAA8G;AAC9G,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA6DvB,CAAC;AAEP,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,6EAA6E;IAC7E,OAAO,WAAW,aAAa,cAAc,MAAM,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,MAAkB,EAAE,MAAc,EAAgB,EAAE,CAAC,CAAC;IACtE,GAAG,EAAE,MAAM,CAAC,GAAG;IACf,EAAE,EAAE,MAAM,CAAC,GAAG;IACd,UAAU,EAAE,MAAM,CAAC,UAAU;IAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;IACjB,IAAI,EAAE,MAAM,CAAC,IAAI;IACjB,KAAK,EAAE,MAAM,CAAC,KAAK;IACnB,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,IAAI,EAAE,MAAM,CAAC,SAAS,KAAK,MAAM;IACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,IAAI;CACnC,CAAC,CAAC;AAEH,sEAAsE;AACtE,SAAS,KAAK,CAAC,KAAc,EAAE,IAAY;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAC3C,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,eAAe,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,OAAO,CAAC,OAAgB;IAC/B,MAAM,KAAK,GAAI,OAAsC,EAAE,KAAK,CAAC;IAC7D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,EAAE,EAAE,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC1G,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;AACjE,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAKlC;IACC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,YAAY,GAAG,CAAC,IAAa,EAAE,EAAE;QACrC,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,mBAAmB,2BAA2B,KAAK,GAAG,CAAC,CAAC;QAC1K,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,iBAAiB,KAAK,GAAG,CAAC,CAAC;QACjG,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,KAAK,EAAE,GAAY,EAAE,EAAE;QACvC,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACpH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,sBAAsB,CAAC,CAAC;QACxG,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,8EAA8E;IAC9E,MAAM,MAAM,GAAG,CAAmB,IAAe,EAAE,IAAsB,EAAsB,EAAE;QAC/F,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAChG,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAG,KAAiC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAuB,CAAC;QAC/G,CAAC;QACD,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAuB,CAAC;IACpF,CAAC,CAAC;IACF,+FAA+F;IAC/F,MAAM,OAAO,GAAG,CAAC,MAAkB,EAAE,KAAc,EAAE,EAAE;QACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACrD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAC/E,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;YACvB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC;YAC/E,CAAC,CAAE,MAAM,CAAC,IAAuC,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,CACvE,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,OAAO,GAA6D;QACxE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACtB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAA0D,CAAC;YAC/E,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GACzB,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAG,IAAI,CAAC,CAAC,CAAqC,EAAE,KAAK,EAAE,CAAC;YAChL,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC3F,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACxG,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACrB,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAyF,CAAC;YAC9G,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,GAC/B,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC9I,MAAM,GAAG,GAAI,OAAoC,EAAE,GAAG,CAAC;YACvD,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;YACtF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE;gBAClG,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAK,OAA+B,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;gBAClI,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtC,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACxB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAmE,CAAC;YACxF,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3I,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,KAAK,GAAI,OAAsC,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACnG,OAAO,QAAQ,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9G,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;YACxB,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;KACvH,CAAC;IAEF,IAAI,CAAC,SAAS,GAAG,CAAC,KAAmB,EAAE,EAAE;QACvC,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAiE,CAAC;QACxF,IAAI,OAAO,OAAO,EAAE,EAAE,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO;QAC7H,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,OAAO,CAAC,OAAO,CAAC,MAAM,CAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CACpC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC,EACvG,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAC9I,CAAC;IACJ,CAAC,CAAC;IAEF,yEAAyE;IACzE,IAAI,IAAI,GAAyC,IAAI,CAAC;IACtD,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,MAAM,IAAI,IAAI;YAAE,OAAO;QAC3B,IAAI,GAAG,UAAU,CAAC,GAAG,EAAE;YACrB,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO;YAAE,OAAO,EAAE,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,KAAK;YACH,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,IAAI;gBAAE,YAAY,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,EAAE,CAAC;YACP,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/session/agent-link.d.ts

@@ -0,0 +1,79 @@
+import type { PeerTransport } from '../network/transport.js';
+import type { Grant } from './connect.js';
+/** Who is asking, as the terminal said */
+export interface AgentAsking {
+    /** The agent's key — the note is made out to it */
+    readonly did: string;
+    /** What the terminal calls itself, e.g. "Agent on leifs-macbook". Shown, not trusted. */
+    readonly name: string;
+}
+/** A new code: `wv_` and 128 random bits */
+export declare function newAgentCode(): string;
+/**
+ * The secret in a code, for anything a person might paste — surrounding
+ * spaces, quotes, the whole command.
+ * @throws When there is no code in it
+ */
+export declare function readAgentCode(input: string): Uint8Array;
+interface LinkNetwork {
+    /** Relays to meet on. The app's and the terminal's must share one. */
+    readonly relays: ReadonlyArray<string>;
+    /** A transport instead of WebRTC — for tests */
+    readonly transport?: (did: string) => PeerTransport;
+}
+export type AgentLinkStage = {
+    readonly kind: 'waiting';
+}
+/** The terminal is there. Call `allow` from a click (it opens the home), or `deny`. */
+ | {
+    readonly kind: 'asking';
+    readonly agent: AgentAsking;
+    allow(grant: Grant): Promise<void>;
+    deny(reason?: string): void;
+} | {
+    readonly kind: 'connected';
+    readonly agent: AgentAsking;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+export interface AgentLinkOffer {
+    /** What the person pastes: `wv_…` */
+    readonly code: string;
+    /** Stops listening. The code stops working. */
+    stop(): void;
+}
+/**
+ * Starts offering a connection to an agent on a computer. Keep it running
+ * while the code is on screen; the first terminal that shows up with the code
+ * is the one asked about, and nobody after it.
+ */
+export declare function offerAgentLink(network: LinkNetwork, onStage: (stage: AgentLinkStage) => void): Promise<AgentLinkOffer>;
+/**
+ * Checks a grant the way the terminal must: a valid agent's note, from the
+ * account it names, made out to this key.
+ * @throws When it does not check out
+ */
+export declare function checkAgentGrant(grant: Grant, audience: string): Promise<void>;
+/**
+ * Connects this terminal as an agent, with the code from the app.
+ *
+ * @param params.did This agent's key — the note will be made out to it
+ * @param params.name What the person sees, e.g. "Agent on leifs-macbook"
+ * @param params.onWaiting Told once the app has heard, and the person is deciding
+ * @returns The grant, checked
+ * @throws When the code is wrong or stale, the person says no, or nothing answers in time
+ */
+export declare function acceptAgentLink(params: {
+    readonly code: string;
+    readonly did: string;
+    readonly name: string;
+    readonly network: LinkNetwork;
+    readonly onWaiting?: () => void;
+    /** How long to wait for the app to answer at all. Default 60 s. */
+    readonly findTimeoutMs?: number;
+    /** How long the person has to decide. Default 10 minutes. */
+    readonly decideTimeoutMs?: number;
+}): Promise<Grant>;
+export {};
+//# sourceMappingURL=agent-link.d.ts.map

package/dist/session/agent-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-link.d.ts","sourceRoot":"","sources":["../../src/session/agent-link.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAS7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAgB1C,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAOD,4CAA4C;AAC5C,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAOvD;AA+BD,UAAU,WAAW;IACnB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;CACrD;AASD,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,uFAAuF;GACrF;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CA4D5H;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnF;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC,GAAG,OAAO,CAAC,KAAK,CAAC,CA6DjB"}