@quo-systems/dock 0.2.2 → 0.2.4

package/mcp/quo-mcp.md

@@ -39,10 +39,11 @@ connected to the same user being see two different tool lists, and neither
 can call what it cannot see: the gate is one decision for describe and for
 dispatch.
 
-A being who answers `look`, the trunk's one optional ask, is listed with
+A being who answers `look`, the trunk's presentation ask, is listed with
 what it says: `asks.NAME.title` is the tool's title, and `readOnly`,
 `destructive` and `idempotent` are the annotations of the same names with
-`Hint` after them. The `look` ask itself is not a tool. A carried standing's
+`Hint` after them. Neither `look` nor `page`, the screen's presentation
+ask, is a tool: a model reads no page. A carried standing's
 asks, `acme-book` on the user being for a model the human let reach, carry
 the far being's hints the same way, read from the notes the carrier writes.
 The side asks `look` once per digest of the describe. Nothing else changes:
@@ -67,26 +68,32 @@ the two words give it what it needs to decide.
 
 ### A remote MCP client connects
 
-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: `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.
+The client speaks OAuth and lands the human on the allow page of the web
+route, where nothing is typed but an invitation: the one the root minted
+for this client on the user being with `quo invite`, and the identity it
+will be. The invitation names its ward, so the world the client is let
+into is the invitation's, and the grant remembers it: a bearer is an
+identity in a world and a session is that identity's there. A session
+opening under a grant finds the avatar as she stands and mints nothing; an
+identity the user being removed hears `removed` there, which is 401.
+`/mcp` stays one endpoint per 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
-  |-- OAuth ------->|                     |                  |                |
-  |                 |-- device(proof) --->|                  |                |
-  |                 |                     |-- invite ------->|                |
-  |                 |                     |<-- invitation ---|                |
-  |                 |<-- invitation ------|                  |                |
-  |                 |-- boot or find avatar for (human, client) ------------>|
-  |                 |-- knock(invitation) --------------------------------->|
-  |                 |                     |                  |<-- knock ------|
-  |                 |                     |                  |--- answer ---->|
-  |                 |                                                  take   |
-  |<-- initialize --|                                                          |
+root              user being         client            mcp. route          avatar
+  |-- invite ------->|                  |                  |                  |
+  |<-- invitation ---|                  |                  |                  |
+  |   ... the link reaches the human by any channel ...    |                  |
+  |                  |                  |-- OAuth -------->|                  |
+  |                  |                  |   the allow page: identity, invitation
+  |                  |                  |                  |-- boot or find avatar for the identity -->|
+  |                  |                  |                  |-- knock(invitation) -------------------->|
+  |                  |<-- knock -------------------------------------------------------------------|
+  |                  |--- answer ----------------------------------------------------------------->|
+  |                  |                  |                  |                            take   |
+  |                  |                  |<-- initialize ---|                                   |
   |-- tools/list -->|-- ask() ------------------------------------------------>|--> user being
   |<-- tool list ---|<-- describe for this asker --------------------------------|
   |-- tools/call -->|-- ask(name, args, { time }) ---------------------------->|--> user being

package/mcp/route.ts

@@ -24,7 +24,7 @@ export async function mcpRoute(dir: string, routes: Routes, mcp: McpHttp | null)
       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 oauth = new OAuth({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/allow?request=${id}`, store, persist });
   const handler: Handler = async (req, res, rest) => {
     if (await oauth.handle(req, res, rest)) return;
     if (rest === '/mcp') {

package/mcp/runner.ts

@@ -32,13 +32,16 @@ type Completion = { choices: { message: { role: 'assistant'; content: string | n
 // Her describe, spoken as a tools array. Name, description and input are
 // verbatim, with the one narrowing an endpoint has asked for: an ask that
 // declares no properties is sent with an empty `properties`, because
-// LM Studio refuses a parameters schema without one.
+// LM Studio refuses a parameters schema without one. `look` and `page` are
+// presentation, for a screen, and are not functions.
 export function tools(bp: Blueprint): Tool[] {
-  return bp.asks.map((a) => {
-    const t: Tool = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
-    if (a.description !== undefined) t.function.description = a.description;
-    return t;
-  });
+  return bp.asks
+    .filter((a) => a.name !== 'look' && a.name !== 'page')
+    .map((a) => {
+      const t: Tool = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
+      if (a.description !== undefined) t.function.description = a.description;
+      return t;
+    });
 }
 
 // One tool call, one ask, one tool message: the three words cross as the

package/mcp/server.ts

@@ -31,7 +31,7 @@ export const DESCRIBE: Tool = { name: 'describe', description: 'the empty ask: h
 // reads. The `look` ask itself is presentation, and is not a tool.
 export function tools(bp: Blueprint, look: Look = {}): Tool[] {
   const asks = bp.asks
-    .filter((a) => a.name !== 'look')
+    .filter((a) => a.name !== 'look' && a.name !== 'page') // presentation, for a screen, and not a tool
     .map((a) => {
       const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
       if (a.description !== undefined) t.description = a.description;

package/mcp/web/exchange.ts

@@ -1,32 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
-// The exchange pages on the web route. Two static pages, hand-written, and
-// explicitly not the human side: they render no blueprint. They end the
-// credential exchange the way the trunk says every route does: a proof is
-// made, the front desk trades it for an invitation, the avatar knocks, and
-// the OAuth request completes with the client identity the human chose.
+// The exchange page on the web route. One static page, hand-written, and
+// explicitly not the human side: it renders no blueprint. It ends the
+// credential exchange the way every way in ends: with a knock. Nothing is
+// typed to get in but an invitation, the one the root minted for this
+// client on the user being with `quo invite` and sent as a link or a line;
+// the avatar the identity boots knocks with it, and the OAuth request
+// completes with the identity the human chose. No password, no cookie, no
+// session: the invitation is the credential, it is used once, and from the
+// knock on there is no token anywhere but the route's own grant.
 //
-//   GET  /login?request=ID     the owner password, from QUO_OWNER_PASSWORD
-//   POST /login                sets a short session cookie, goes to /allow
-//   GET  /allow?request=ID     who is asking, and the identity they will be
-//   POST /allow                allow as that identity, or deny
+//   GET  /allow?request=ID     who is asking, the identity it will be, and
+//                              the field for the invitation
+//   POST /allow                allow as that identity with that invitation,
+//                              or deny
 //
-// The password is the device's, read from the environment the way an envoy
-// reads a secret, never through cells. With none set, the exchange is closed.
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+// The invitation names its ward, so the world the client lands in is the
+// one the invitation was minted on, and there is nothing to choose.
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Invitation } from '@quo-systems/quo';
 import type { OAuth } from '../oauth.ts';
 import { readForm } from '../oauth.ts';
+import { parse } from '../../beings/link.ts';
 
-export const SESSION_TTL = 10 * 60 * 1000; // a login lives as long as a request: ten minutes
-const COOKIE = 'quo_exchange';
-
-export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{ error?: string }>;
+export type Join = (identity: string, invitation: Invitation, ward: string) => Promise<{ error?: string }>;
 export type Options = {
   oauth: OAuth;
-  password: () => string | undefined; // QUO_OWNER_PASSWORD, read at every login
-  admit: Admit; // the daemon: boot or find the avatar for this identity in that world, and enter her
-  worlds: () => { ward: string; user: string }[]; // the worlds of this harbor, the first the default: a ward with a public being, and its user being's name
-  now?: () => number;
+  join: Join; // the daemon: boot or find the avatar for this identity in that world, and knock
+  worlds: () => { ward: string; pk: string; user: string }[]; // the worlds of this harbor, by name and pk
 };
 
 const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
@@ -39,122 +39,88 @@ export const suggest = (name: string) =>
     .replace(/^-|-$/g, '')
     .slice(0, 40) || 'client';
 
+// The invitation as typed: the link's compact form, `ward.heir.secret`, or
+// the whole link it came in, or the JSON value `quo invite` printed.
+export function invitationOf(text: string): Invitation | null {
+  const t = text.trim();
+  const hash = t.indexOf('#');
+  const linked = parse(hash === -1 ? `#quo=${t}` : t.slice(hash));
+  if (linked?.heir) return linked;
+  try {
+    const v = JSON.parse(t) as Record<string, unknown>;
+    if (v && typeof v === 'object' && typeof v.ward === 'string' && typeof v.heir === 'string' && typeof v.secret === 'string') return { ward: v.ward, heir: v.heir, secret: v.secret };
+  } catch {
+    /* not JSON either */
+  }
+  return null;
+}
+
 export class Exchange {
   readonly o: Options;
-  readonly secret = randomBytes(32); // sessions die with the daemon, and that is fine: they live ten minutes
   constructor(o: Options) {
     this.o = o;
   }
-  now() {
-    return this.o.now?.() ?? Date.now();
-  }
-
-  // ---- the session cookie: an expiry, signed
-
-  mint(): string {
-    const exp = String(this.now() + SESSION_TTL);
-    return `${exp}.${createHmac('sha256', this.secret).update(exp).digest('base64url')}`;
-  }
-  valid(req: IncomingMessage): boolean {
-    const m = /(?:^|;\s*)quo_exchange=([^;]+)/.exec(req.headers.cookie ?? '');
-    const [exp, sig] = (m?.[1] ?? '').split('.');
-    if (!exp || !sig) return false;
-    const want = createHmac('sha256', this.secret).update(exp).digest('base64url');
-    return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)) && Number(exp) > this.now();
-  }
 
   async handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean> {
     const url = new URL(req.url ?? '/', 'http://localhost');
-    const page = (status: number, body: string, headers: Record<string, string> = {}) => {
-      res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...headers });
+    const page = (status: number, body: string): true => {
+      res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
       res.end(shell(body));
+      return true;
     };
-    const go = (to: string, headers: Record<string, string> = {}) => {
-      res.writeHead(302, { location: to, 'cache-control': 'no-store', ...headers });
+    const go = (to: string): true => {
+      res.writeHead(302, { location: to, 'cache-control': 'no-store' });
       res.end();
+      return true;
     };
 
-    if (rest === '/login' && req.method === 'GET') {
-      const request = url.searchParams.get('request') ?? '';
-      const p = this.o.oauth.pending(request);
-      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`), true;
-      if (this.o.password() === undefined) return page(503, `<h1>Closed</h1><p>This world takes no logins: no owner password is set.</p>`), true;
-      if (this.valid(req)) return go(`/allow?request=${encodeURIComponent(request)}`), true;
-      return page(200, loginForm(request, p.client.client_name)), true;
-    }
-    if (rest === '/login' && req.method === 'POST') {
-      const f = await readForm(req);
-      const request = f.get('request') ?? '';
-      const p = this.o.oauth.pending(request);
-      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-      const want = this.o.password();
-      const got = f.get('password') ?? '';
-      if (want === undefined) return page(503, `<h1>Closed</h1>`), true;
-      if (got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
-        await new Promise((ok) => setTimeout(ok, 300));
-        return page(401, loginForm(request, p.client.client_name, 'That is not the password.')), true;
-      }
-      return go(`/allow?request=${encodeURIComponent(request)}`, { 'set-cookie': `${COOKIE}=${this.mint()}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${SESSION_TTL / 1000}` }), true;
-    }
     if (rest === '/allow' && req.method === 'GET') {
       const request = url.searchParams.get('request') ?? '';
       const p = this.o.oauth.pending(request);
-      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-      if (!this.valid(req)) return go(`/login?request=${encodeURIComponent(request)}`), true;
-      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`);
+      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds()));
     }
     if (rest === '/allow' && req.method === 'POST') {
       const f = await readForm(req);
       const request = f.get('request') ?? '';
       const p = this.o.oauth.pending(request);
-      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
-      if (!this.valid(req)) return go(`/login?request=${encodeURIComponent(request)}`), true;
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`);
       if (f.get('decision') !== 'allow') {
         const out = await this.o.oauth.deny(request);
-        return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
+        return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
       }
       const worlds = this.o.worlds();
-      const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
-      if (!world) return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
+      const again = (err: string) => page(400, allowForm(request, p.client.client_name, p.redirect_uri, word(f.get('identity')) ?? suggest(p.client.client_name), worlds, err));
+      const inv = invitationOf(f.get('invitation') ?? '');
+      if (!inv) return again('That is not an invitation.');
+      const world = worlds.find((w) => w.pk === inv.ward);
+      if (!world) return again('That invitation is for a world that does not live here.');
       const identity = word(f.get('identity'));
-      if (identity === null || identity === world.user || identity === 'desk') return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
-      const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
-      if (admitted.error) return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
+      if (identity === null || identity === world.user || identity === 'desk') return again('An identity is one word, and not the user or the desk.');
+      const joined = await this.o.join(identity, inv, world.ward);
+      if (joined.error) return again(`Not in: ${joined.error}.`);
       const out = await this.o.oauth.complete(request, identity, world.ward);
-      return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
+      return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`);
     }
     return false;
   }
 }
 
 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>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input,textarea{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}textarea{font-family:ui-monospace,monospace;min-height:5rem}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
 </head><body>${body}</body></html>`;
 
-const loginForm = (request: string, client: string, err = '') => `<h1>${esc(client)} wants in</h1>
-<p>Log in as the owner of this world to decide.</p>
-${err ? `<p class="err">${esc(err)}</p>` : ''}
-<form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
-<label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
-<button type="submit">Log in</button></form>`;
-
-// The world is a choice when the harbor has more than one; the user named
-// is the first world's, and the page says which world each identity lands in.
+// The one page. The world is the invitation's, so the page only says which
+// worlds live here and whose they are.
 const allowForm = (request: string, client: string, redirect: string, identity: string, worlds: { ward: string; user: string }[], err = '') => {
-  const user = worlds[0]?.user ?? '';
-  const pick =
-    worlds.length > 1
-      ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
-      : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+  const whose = worlds.map((w) => `<strong>${esc(w.user)}</strong> in ${esc(w.ward)}`).join(', ');
   return `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
-<p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of ${whose || 'a world here'}.</p>
+<p>It will see exactly what the user being shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
-${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
-<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
-<label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
+<label for="v">Invitation</label><textarea id="v" name="invitation" autofocus required placeholder="the invitation the owner minted for this client, as the link or as printed"></textarea>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/dock",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -31,6 +31,10 @@
       "types": "./dist/harbor/browser.d.ts",
       "default": "./dist/harbor/browser.js"
     },
+    "./harbor/capacitor": {
+      "types": "./dist/harbor/capacitor.d.ts",
+      "default": "./dist/harbor/capacitor.js"
+    },
     "./cli/daemon": {
       "types": "./dist/cli/daemon.d.ts",
       "default": "./dist/cli/daemon.js"
@@ -55,6 +59,10 @@
       "types": "./dist/human/html.d.ts",
       "default": "./dist/human/html.js"
     },
+    "./human/local": {
+      "types": "./dist/human/local.d.ts",
+      "default": "./dist/human/local.js"
+    },
     "./harbor/edge/worker": {
       "types": "./dist/harbor/edge/worker.d.ts",
       "default": "./dist/harbor/edge/worker.js"
@@ -67,8 +75,11 @@
     "prepublishOnly": "cd ../.. && npm run check && npm run check:terrain"
   },
   "dependencies": {
+    "@aparajita/capacitor-secure-storage": "^8.0.0",
+    "@capacitor/core": "^8.5.1",
+    "@capacitor/filesystem": "^8.1.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@quo-systems/quo": "^0.2.2",
+    "@quo-systems/quo": "^0.2.4",
     "esbuild": "^0.28.2",
     "ws": "^8.21.3"
   },