npm - @quo-systems/dock - Versions diffs - 0.2.1 → 0.2.2 - Mend

@quo-systems/dock 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

package/human/web.ts ADDED Viewed

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// The web route: the worlds' pages, served by the daemon under `/web` and
+// mapped by the proxy from the web. hostname. A world is a ward with a
+// public being, and its address is `/web/<ward>`: the tab page, `tab.ts`,
+// told which ward this is, and every ward on the harbor by name, pk and
+// whether a public being is at its door, so that its guest is that ward's
+// public being rendered by the screen, whatever class she is. Every ward
+// has a page, since a link may point into one with nobody at the door;
+// `/web/` lists the worlds and carries the tab too, so a link at the root
+// lands in the ward its invitation names, and with no world to list it is
+// the door page, `door.ts`. The bundle is built once from the source
+// beside this file, `.ts` in the tree, `.js` once emitted into the
+// package's dist. Nothing here authenticates and nothing is admitted on
+// this side: the way into a world is an invitation, carried by a link, and
+// the knock is the tab's. Paths this route does not take fall through to
+// the exchange pages, which share the prefix.
+//
+// The page carries a content security policy: scripts from this origin
+// only and never inline, connections to this origin and the quo. route the
+// tab dials, images from data URIs and this origin, and nothing else. So
+// even a bug in a renderer cannot become a script, and no look can reach a
+// server. The config crosses in a JSON script, which the policy allows.
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import type { DiskHarbor, Hosted } from '../harbor/disk.ts';
+import { door } from './door.ts';
+export type WebOptions = {
+  // where the routes are, as a tab sees them: what it dials and where it is
+  at: { quo: string; web: string };
+};
+// The paths under `/web` that are the exchange's, never a ward's name.
+const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+export function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
+  const tabEntry = () => {
+    const js = fileURLToPath(new URL('./tab.js', import.meta.url));
+    return existsSync(js) ? js : fileURLToPath(new URL('./tab.ts', import.meta.url));
+  };
+  let bundle: Promise<string> | undefined;
+  const built = () =>
+    (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((out) => out.outputFiles[0]!.text));
+  const quoOrigin = (() => {
+    try {
+      const u = new URL(o.at.quo);
+      return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+    } catch {
+      return '';
+    }
+  })();
+  const host = (() => {
+    try {
+      return new URL(o.at.web).host;
+    } catch {
+      return o.at.web;
+    }
+  })();
+  const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+  const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body>${body}</body></html>`;
+  const esc = (v: string) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+  const publicOf = (h: Hosted) => (h.partition as { public?: string | null }).public ?? null;
+  const html = (status: number, res: ServerResponse, body: string) => {
+    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
+    res.end(shell(body));
+    return true;
+  };
+  const wards = () => Object.fromEntries([...harbor.wards].map(([n, h]) => [n, { pk: h.pk, public: publicOf(h) !== null }]));
+  const tab = (ward?: string) => {
+    const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), ...(ward ? { ward } : {}) };
+    return `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
+  };
+  return async (req, res, rest) => {
+    const parts = rest.split('/').filter(Boolean);
+    if (req.method === 'GET' && (rest === '' || rest === '/')) {
+      const list = [...harbor.wards]
+        .filter(([, h]) => publicOf(h) !== null)
+        .map(([n, h]) => `<li><a href="${o.at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
+        .join('');
+      return html(200, res, `${list ? `<h1>worlds</h1><ul>${list}</ul>` : door({ host })}${tab()}`);
+    }
+    if (rest === '/tab.js' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(await built());
+      return true;
+    }
+    const wardName = parts[0] ?? '';
+    if (!wardName || RESERVED_PATHS.has(wardName)) return false;
+    const hosted = harbor.wards.get(wardName);
+    if (!hosted) return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+    if (parts.length === 1 && req.method === 'GET') return html(200, res, tab(wardName));
+    return false;
+  };
+}
+// The tab's stylesheet: one, light and dark, honouring the variables a look
+// sets on a section. The page owns layout; a far being paints inside her
+// section and nowhere else. The door page is the one designed thing in it.
+const CSS = [
+  ':root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px;--ink:#1c1b22;--paper:#fbfaf7;--mute:#6b6a73}',
+  '@media(prefers-color-scheme:dark){:root{--ink:#ecebe6;--paper:#141318;--mute:#9a99a2}}',
+  'html{background:var(--paper);color:var(--ink)}',
+  'body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}',
+  'nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}',
+  'nav.relations{display:flex;flex-wrap:wrap;gap:.25rem;margin:.5rem 0}nav.relations button{background:transparent;color:inherit;border:1px solid color-mix(in srgb,currentColor 30%,transparent)}nav.relations button[aria-current]{border-color:var(--accent);font-weight:600}',
+  'header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}',
+  'input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}',
+  'fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}',
+  'section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}',
+  'table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}',
+  // the door page: one column, generous air, the mark, a word, a sentence
+  'main.door{min-height:70vh;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;max-width:32rem;margin:0 auto;padding:3rem 0;font-family:ui-serif,Georgia,"Times New Roman",serif}',
+  'main.door .mark{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
+  'main.door h1{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
+  'main.door .where{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .where span{text-transform:none;letter-spacing:0}',
+  'main.door .lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
+  'main.door p{font-size:1.05rem;line-height:1.6;margin:0 0 1rem;max-width:30rem}',
+  'main.door .quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
+].join('');

package/human/worlds.ts ADDED Viewed

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worlds in a tab, and the relations in each. A tab is a device with a
+// harbor of its own, and it keeps one local ward per far world, named by
+// the far ward's pk; inside it, one avatar per relation, since an avatar is
+// one standing and nothing more. An invitation names its ward by pk, so an
+// invitation is self-addressing: the local ward is chosen by the invitation
+// and never by the page it was opened on, and a fresh invitation is always a
+// fresh avatar, never a join on one that already holds her standing. Two
+// humans on one family tablet are two relations in one world; a shop and a
+// friend in one far ward are two as well. Nothing here touches a document:
+// `tab.ts` is the shell over this, and this is what the memory harbor proves.
+import type { Harbor, Hosted } from '@quo-systems/quo/harbor';
+import { Avatar, USER } from '../beings/avatar.ts';
+// The local ward for a far world, by its pk: created on first sight, on
+// the tab's own seed, empty.
+export const localName = (pk: string): string => `w-${pk.slice(0, 16)}`;
+export async function world(harbor: Harbor, pk: string): Promise<Hosted> {
+  const name = localName(pk);
+  return harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+}
+// The relations held in a local ward: every avatar there who holds her
+// standing, by key, in the order they were born.
+export type Relation = { key: string; avatar: Avatar };
+export function relations(ward: Hosted): Relation[] {
+  const beings = (ward.partition as { beings?: Record<string, { class?: string }> }).beings ?? {};
+  const out: Relation[] = [];
+  for (const key of Object.keys(beings)) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && a.standings[USER]) out.push({ key, avatar: a });
+  }
+  return out;
+}
+// An avatar for a relation not yet made: one who holds no standing, whether
+// left by a guest who never came in or booted now under the next free key.
+// She is the one who knocks, as a guest or with an invitation, and she
+// becomes a relation the moment she takes her standing.
+export async function fresh(ward: Hosted): Promise<Relation> {
+  const beings = (ward.partition as { beings?: Record<string, { class?: string }> }).beings ?? {};
+  for (const key of Object.keys(beings)) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && !a.standings[USER]) return { key, avatar: a };
+  }
+  let n = 1;
+  while (beings[`r${n}`]) n++;
+  const key = `r${n}`;
+  const out = (await ward.ask('boot', { key, class: 'Avatar' })) as { error?: string };
+  if (out.error) throw new Error(`the tab could not boot an avatar: ${out.error}`);
+  return { key, avatar: ward.being(key) as Avatar };
+}

package/mcp/quo-mcp.md CHANGED Viewed

@@ -70,7 +70,9 @@ the two words give it what it needs to decide.
 One harbor holds many worlds, and the allow page names the one the client
 is let into; the grant remembers it, so a bearer is an identity in a world
 and a session is that identity's there. `/mcp` stays one endpoint per
-harbor.
+harbor: `mcp/route.ts` is the route the daemon mounts, the exchange in
+`oauth.ts` in front and the endpoint in `http.ts` behind it, with the
+route's store, `<dir>/oauth.json`, the route's own and never a ward's.
 ```
 client            mcp. route          front desk         user being        avatar

package/mcp/route.ts ADDED Viewed

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// The mcp. route: the credential exchange and the MCP endpoint, served by
+// the daemon under `/mcp` and mapped by the proxy from the mcp. hostname.
+// The OAuth store is `<dir>/oauth.json`, the route's own and never a
+// ward's: clients, pending requests, codes and tokens, each mapping to a
+// client identity at most. A bearer names an identity in a world; the
+// endpoint hands both to the model side, which runs beside her avatar.
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { OAuth, emptyStore, type Store } from './oauth.ts';
+import type { McpHttp } from './http.ts';
+import type { Handler } from '../cli/http.ts';
+// The routes' public faces, as the exchange and the metadata name them.
+export type Routes = { mcp: string; web: string; quo?: string };
+export async function mcpRoute(dir: string, routes: Routes, mcp: McpHttp | null): Promise<{ oauth: OAuth; handler: Handler }> {
+  const file = join(dir, 'oauth.json');
+  const store: Store = existsSync(file) ? { ...emptyStore(), ...(JSON.parse(await readFile(file, 'utf8')) as Partial<Store>) } : emptyStore();
+  let queue = Promise.resolve();
+  const persist = (s: Store) =>
+    (queue = queue.then(async () => {
+      await writeFile(file + '.tmp', JSON.stringify(s), { mode: 0o600 });
+      await rename(file + '.tmp', file);
+    }));
+  const oauth = new OAuth({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/login?request=${id}`, store, persist });
+  const handler: Handler = async (req, res, rest) => {
+    if (await oauth.handle(req, res, rest)) return;
+    if (rest === '/mcp') {
+      const grant = oauth.bearer(req);
+      if (grant === null || !mcp) return oauth.challenge(res);
+      return mcp.handle(req, res, grant.identity, grant.ward);
+    }
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'no such route' }));
+  };
+  return { oauth, handler };
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/dock",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "The dock: what every estate on Quo needs and nobody writes twice. A daemon and the quo command, the front desk, the user being and the avatar, harbors on disk, in a tab and on the edge, the model sides and the screen.",
   "keywords": [
     "quo",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@quo-systems/quo": "^0.2.1",
+    "@quo-systems/quo": "^0.2.2",
     "esbuild": "^0.28.2",
     "ws": "^8.21.3"
   },