@nervur-org/dock 0.3.0

package/api/route.ts

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+// The api. route: HTTP as the fourth rendering of one describe. It is
+// `Request` in and `Response` out and names no terrain, so the daemon mounts
+// it under `/api` behind the proxy that maps the api. hostname, and the
+// worker at the edge mounts the same route under its own prefix.
+// Beside forms, tools and the CLI, it speaks a being's describe and asks as
+// plain JSON, and it hears every rung a route hears. A request carrying no
+// bearer is the stranger every route knows: the named ward's public being
+// asked as `{}`, which is what a browser fetch, a crawler or a page
+// rendering server side is. A request carrying a bearer the box granted is
+// an occupant: the identity's avatar in the ward the grant names, asked
+// through her one standing at the world's being, so what a script sees
+// with a bearer is what a model sees with the same bearer as tools and a
+// tab sees as forms. A world is a ward, so `/api/<ward>` is the describe
+// for this asker and `/api/<ward>/<ask>` is one ask, args from the query on
+// a GET or a JSON object on a POST. A caller who names no ward is at the
+// device's own, as a tab at the web route's root is: `GET /api` is the
+// describe of that ward, for a stranger and under a bearer alike.
+//
+// A program gets its bearer the way the allow page gives one to a model,
+// without the page: `POST /api` with the identity and the invitation the
+// root minted for it trades the invitation for tokens, the avatar knocks,
+// and the invitation is spent. `POST /api` with a refresh token rotates.
+//
+// What she says crosses as the model side crosses it: an object is 200
+// with that JSON, an error object she answered is 400 with that JSON, and
+// no object at all is 503 `{ error: 'silence' }`. For a stranger, silence,
+// a throw, a wait that ran out and a ward with nobody at the door are one
+// answer here, as they are one answer on the wire: a stranger learns which
+// world exists and nothing else about it. For an occupant the ward's
+// words cross by name, and `removed` is 401 with the grant forgotten, so a
+// script that was removed at the user being starts over with a fresh
+// invitation. A world that is not here, and a path that is not one of the
+// shapes, are the route's own 404 and never a being's.
+import type { Handler } from '../harbor/http.ts';
+import { readText } from '../harbor/http.ts';
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import type { Avatar } from '../beings/avatar.ts';
+import { invitationOf } from '../beings/link.ts';
+import { landed, POLICY } from '../human/door.ts';
+import { CSS } from '../human/style.ts';
+import type { Grants } from '../dock/grants.ts';
+import { isInvitation, isSilence, isWord, wordOf, type Invitation, type JsonObject } from '@nervur-org/nervur';
+
+const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'GET, POST, OPTIONS', 'access-control-allow-headers': 'content-type, authorization' };
+
+// The harbor this route answers for, as the route needs it: the wards it
+// holds, and which of them a caller who names none is at. The second is the
+// terrain's word and never a guess of the route's: a disk reads the mark an
+// operator wrote, a worker holds the one world in its object. A terrain with
+// no answer says the empty string, and the path that named no ward is no
+// such world.
+export type Held = { wards: ReadonlyMap<string, Hosted>; here(): string };
+
+export type Options = {
+  grants: Grants;
+  // Her avatar as she stands in a world, for a bearer: nothing is minted.
+  resolve: (identity: string, ward: string) => Promise<{ avatar?: Avatar; error?: string }>;
+  // Boot or find the avatar for this identity in that world, and knock.
+  join: (identity: string, invitation: Invitation, ward: string) => Promise<{ error?: string }>;
+  // Where the worlds' pages are, for the one arrival here that is a human:
+  // a redirect from somewhere a world sent her. Without it she still gets a
+  // page, with no way back offered on it.
+  web?: string;
+};
+
+const word = (s: unknown) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
+
+export function apiRoute(harbor: Held, o: Options): Handler {
+  return async (req, rest) => {
+    const json = (status: number, body: unknown) => Response.json(body, { status, headers: open });
+    // The one page this road serves, and it wears the one stylesheet every
+    // screen wears. No cross-origin header on it: a page is for the browser
+    // that was sent here and never for a script somewhere else. Its policy
+    // is the allow page's, and for the same reason: a page that runs no
+    // script of its own should be allowed none.
+    const page = (status: number, body: string) =>
+      new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>\n<style>${CSS}</style>\n</head><body>${body}</body></html>`, {
+        status,
+        headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': POLICY, 'referrer-policy': 'no-referrer' },
+      });
+    // Where this world lives, as the daemon was told and not as the request
+    // said: a Host header is the caller's to write, and a page that printed
+    // one would print whatever a caller wanted a human to read. Falling back
+    // to it is for a box configured with no web address at all, where the
+    // request is the only thing that knows.
+    const hostOf = (r: Request) => {
+      try {
+        return o.web === undefined ? (r.headers.get('host') ?? '') : new URL(o.web).host;
+      } catch {
+        return r.headers.get('host') ?? '';
+      }
+    };
+    if (req.method === 'OPTIONS') return new Response(null, { status: 204, headers: open });
+    if (req.method !== 'GET' && req.method !== 'POST') return json(405, { error: 'GET or POST' });
+    const body = async (): Promise<JsonObject | null> => {
+      const raw = await readText(req);
+      if (raw === undefined) return null;
+      let parsed: unknown = {};
+      try {
+        parsed = raw.length === 0 ? {} : JSON.parse(raw);
+      } catch {
+        return null;
+      }
+      return parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) ? null : (parsed as JsonObject);
+    };
+
+    // The trade: an invitation for a grant, or a refresh token for the next.
+    if ((rest === '' || rest === '/') && req.method === 'POST') {
+      const b = await body();
+      if (b === null) return json(400, { error: 'the body is a JSON object' });
+      if (typeof b.refresh === 'string') {
+        const t = await o.grants.refresh(b.refresh);
+        return t ? json(200, t) : json(400, { error: 'invalid_grant' });
+      }
+      const inv = typeof b.invitation === 'string' ? invitationOf(b.invitation) : isInvitation(b.invitation) ? b.invitation : null;
+      if (!inv) return json(400, { error: 'that is not an invitation' });
+      const world = [...harbor.wards].find(([, h]) => h.pk === inv.ward);
+      if (!world) return json(400, { error: 'that invitation is for a world that does not live here' });
+      const [ward, hosted] = world;
+      const identity = word(b.identity);
+      if (identity === null || identity === hosted.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
+      // Nobody at a page vouches for a program, so a trade is a knock that
+      // spends: an identity already in refreshes, or is removed at the user
+      // being and invited again, and never re-enters on a spent invitation.
+      if ((await o.resolve(identity, ward)).avatar) return json(400, { error: 'already in' });
+      const joined = await o.join(identity, inv, ward);
+      if (joined.error) return json(400, { error: joined.error });
+      return json(200, await o.grants.issue(identity, ward, 'api'));
+    }
+
+    // No ward named is the device's own ward, and never a default the route
+    // picks: the harbor points at one of its wards and says that one is the
+    // device's, and its door answers for it.
+    const [, named = '', ask = '', ...more] = rest.split('/');
+    const ward = named === '' ? harbor.here() : named;
+
+    // The delivery: a vendor's webhook to an envoy, `/api/<ward>/<being>/deliver`.
+    // Not a stranger's ask and not an occupant's: the owner asking her
+    // `deliver` with the raw bytes and the headers, and nothing else. The
+    // body is read as a string and never parsed here, since the vendor
+    // signed the bytes and a reparsed body fails her check; no bearer is
+    // read, since the rung is not the caller's to prove. She answers `{ ok }`
+    // or her error object, and the route carries it.
+    // A GET on the same path is the same ask with an empty body: where an
+    // OAuth redirect lands, the code in the query. The query crosses inside
+    // the headers under `:query`, a name no header on the wire can have, so
+    // her one ask in stays one.
+    if (more.length === 1 && more[0] === 'deliver') {
+      if (req.method !== 'POST' && req.method !== 'GET') return json(405, { error: 'POST, or GET for a redirect' });
+      const hosted = harbor.wards.get(ward);
+      if (!hosted || !/^[\w-]+$/.test(ask)) return json(404, { error: 'no such world' });
+      const raw = req.method === 'GET' ? '' : await readText(req);
+      if (raw === undefined) return json(413, { error: 'too big' });
+      const headers: Record<string, string> = {};
+      req.headers.forEach((v, k) => (headers[k] = v));
+      const query = new URL(req.url).search.slice(1);
+      if (query) headers[':query'] = query;
+      const out = await hosted.ask('ask', { being: ask, method: 'deliver', args: { body: raw, headers } });
+      await hosted.save();
+      // A GET here is a browser and a browser is a human: a vendor a world
+      // sent her to has opened this URL in her tab, so what she is looking
+      // at is whatever the envoy answered a machine. She gets a page
+      // instead, and only she does; a vendor asking for JSON is answered in
+      // JSON as it always was, and so is a GET that says nothing about what
+      // it wants.
+      const wants = req.method === 'GET' && (req.headers.get('accept') ?? '').includes('text/html');
+      if (wants) {
+        const ok = out !== null && typeof out === 'object' && !Array.isArray(out) && typeof (out as { error?: unknown }).error !== 'string';
+        return page(ok ? 200 : 400, landed({ world: ward, host: hostOf(req), ...(o.web ? { at: `${o.web.replace(/\/$/, '')}/${encodeURIComponent(ward)}` } : {}), ok }));
+      }
+      if (isSilence(out) || out === null || typeof out !== 'object' || Array.isArray(out)) return json(503, { error: 'silence' });
+      const said = (out as { error?: unknown }).error;
+      if (said === 'no such being' || said === 'unknown ask') return json(404, { error: 'no such envoy' });
+      if (said === 'silence' || said === 'threw' || said === 'late') return json(503, { error: 'silence' });
+      if (typeof said === 'string') return json(400, out);
+      return json(200, out);
+    }
+    if (!/^[\w.-]+$/.test(ward) || more.length > 0 || (ask !== '' && !/^[\w-]+$/.test(ask))) return json(404, { error: 'GET /api for the device’s ward, GET /api/<ward> for the describe, GET or POST /api/<ward>/<ask> for one ask, POST /api/<ward>/<being>/deliver for a delivery' });
+    const hosted = harbor.wards.get(ward);
+    if (!hosted) return json(404, { error: 'no such world' });
+    let args: JsonObject;
+    if (req.method === 'POST') {
+      const b = await body();
+      if (b === null) return json(400, { error: 'the body is a JSON object' });
+      args = b;
+    } else {
+      const url = new URL(req.url);
+      args = Object.fromEntries(url.searchParams.entries());
+    }
+
+    const carried = (req.headers.get('authorization') ?? '') !== '';
+    const grant = o.grants.bearer(req);
+    if (carried && grant === null) return json(401, { error: 'unauthorized' });
+    if (grant === null) {
+      // The owner's `ask` with no being named: the public being, asked as
+      // nobody, bounded and judged by the ward, which is the in-process twin
+      // of the bytes a stranger would send. The route holds none of that. A
+      // world with nobody at the door and a being who said nothing are one
+      // answer here, as they are one answer on the wire.
+      const out = await hosted.ask('ask', ask === '' ? {} : { method: ask, args });
+      if (isSilence(out) || out === null || typeof out !== 'object' || Array.isArray(out)) return json(503, { error: 'silence' });
+      const said = (out as { error?: unknown }).error;
+      if (said === 'silence' || said === 'threw' || said === 'late' || said === 'no such being') return json(503, { error: 'silence' });
+      if (typeof said === 'string') return json(400, out);
+      return json(200, out);
+    }
+
+    // An occupant: the grant names a world, and the path must name the same
+    // one, since an avatar is one relation in one world.
+    if (grant.ward !== ward) return json(403, { error: 'not your world' });
+    const found = await o.resolve(grant.identity, ward);
+    if (found.error === 'removed') {
+      await o.grants.revoke(grant.identity, ward);
+      return json(401, { error: 'removed' });
+    }
+    if (!found.avatar) return json(401, { error: found.error ?? 'not joined' });
+    const out = ask === '' ? await found.avatar.tools() : await found.avatar.call(ask, args);
+    await hosted.save();
+    if (isSilence(out)) return json(503, { error: 'silence' });
+    if (isWord(out)) return json(503, { error: wordOf(out) });
+    if (out === null || typeof out !== 'object' || Array.isArray(out)) return json(200, out);
+    const said = (out as { error?: unknown }).error;
+    if (typeof said === 'string' && !('asks' in out)) return json(400, out);
+    return json(200, out);
+  };
+}

package/beings/GLOSSARY.md

@@ -0,0 +1,118 @@
+# GLOSSARY
+
+Every word the papers above the spec use, in one place. The protocol's own
+words, being, ward, harbor, standing, occupant, invitation, knock and the
+rest, are in the glossary of `quo/SPEC.md`, which assumes nothing and
+is not repeated here; what the library spells for itself is in
+`papers/quo-kit.md`. A word here is a convention of the dock or of an
+estate, and changes no word of the spec. `papers/WORLDS.md` is where the
+first seven are reasoned; `papers/quo-dock.md` and the papers of its sides
+are where the rest are built.
+
+## A person and a world
+
+- **org**: the unit every "you" names: a company, a family, a club, a
+  service, and at the smallest one human alone, an org of one. An org owns
+  wards, holds standings, trusts boxes and is trusted. Never an avatar, an
+  account or a user id; each of those is a thing an org holds.
+- **world**: a ward, as a human sees it: one seed, one partition, one body
+  of code, one owner.
+- **home**: the one ward an org owns on a harbor it trusts; the org's own
+  being is its being. Also that being's standing at the ward's own door as
+  an owner, `home`. One per org, and an org may have none yet.
+- **org being**: home's own being, one per org, running day and night,
+  holding the org's standings and its members as occupants. An estate's
+  own class for an organisation; the user being for an org of one.
+- **presence**: a ward a person owns on a harbor in her hand, one per world
+  reached from that device. The tab, the phone and the desk are presences
+  of the same shape, and nothing in a hand is a home.
+- **presence being**: the being of a world who lives on a device, booted in
+  the presence ward when the world is joined. She lends every faculty the
+  box has at her birth and carries them, so a world reaches the device only
+  by asking her.
+- **app**: a browser of worlds, one harbor and a presence ward per world,
+  the same shell on every terrain. It has no account and no person of its
+  own; which app a person uses is settled at home, and an adopter's app is
+  only the first one its member meets.
+- **membership**: an id in a ward someone else owns. An employee id, a
+  member id, a customer id. Never a ward of hers.
+- **hub**: home, as the one place every relation of hers meets.
+- **rule**: home answering one standing by asking another.
+- **device**: a harbor in her hand, with a ward of its own holding what that
+  box can do. One OS user is one harbor, and the app has no people of its
+  own.
+
+## The dock
+
+- **dock**: what every estate needs and nobody writes twice,
+  `packages/dock/`, published as `@nervur-org/dock`.
+- **dock ward**: the ward a harbor boots and roots for itself, holding the
+  faculties that box lends. Never a home, and never migrated.
+- **estate**: all of one owner's harbors, with what is theirs alone, in a
+  tree of the owner's own and never published.
+- **daemon**: `quo serve`, the one process on a device that holds a harbor.
+- **route**: a hostname a reverse proxy sends to one process: `web.`,
+  `quo.`, `mcp.`, `api.`.
+- **user being**: the org being of an org of one: a human's own, holding
+  all of her standings. The dock's `User` class, which also serves a
+  membership the desk makes in another org's ward.
+- **front desk**: the being every fresh client meets; hands out invitations
+  minted by the ward's being, and is what `quo init` marks public in a
+  fresh ward. Any ward may mark one being of any class public instead.
+- **avatar**: a being that is someone's voice from outside Quo, one per
+  client identity.
+- **side**: the interface an avatar speaks through to someone outside Quo:
+  a screen, an MCP server, a runner, an agent.
+- **client identity**: what a credential exchange establishes; one avatar,
+  for life.
+- **proof**: a vouch the front desk trades once for an invitation: the
+  daemon's nonce for a local side, or the link a world mailed to an address
+  it wants proof of. Everyone else arrives with an invitation.
+- **way in**: a being who says who a proof of one kind is for, and who sends
+  the proof out to an address where the kind has one. The desk holds a
+  standing at each, under `way:<kind>`: the box's, lent by the dock ward,
+  and the world's own, in the world's ward.
+- **carrier**: a being who shows her standings' asks as her own and
+  forwards. The user being and the device are two.
+- **envoy**: a being of the org's standing in for a ward nobody here runs,
+  one being per vendor and one relation per account, on the base
+  `beings/envoy.ts`. Her asks out are the vendor's surface, narrowed; her
+  one ask in, `deliver`, is the owner's, the vendor's bytes reaching her
+  own body through the api route and never a door; her credential is in
+  her cells, placed by the owner and shown to nobody; and a delivery is one
+  ask on the way back her occupant handed her at the knock.
+- **faculty**: a being of the dock ward, standing for one thing the box can
+  do: a timer, a line, a store, a vendor's API. Reached by `lend`, held as
+  an ordinary standing, and she wakes whoever invited her. She holds what
+  the device holds and begins holding it at birth.
+- **ring**: one platform's way of waking a device by its token, held by the
+  push faculty: `web`, `apns`, `fcm`. It carries the banner sealed to that
+  device's banner key, and nothing else.
+- **bell**: a ward that wakes devices, with a public being for a phone
+  nobody knows and one doorbell per device. `papers/quo-app-bells.md`.
+- **doorbell**: one device's being at a bell. Its cells hold that device's
+  platform token, and its occupants are the worlds that device allowed to
+  wake it, one standing each.
+- **porter**: a bell's public being, where a phone nobody knows arrives as
+  `{}` and comes away with a doorbell of its own.
+- **banner key**: the pair a device keeps in the cells of its notifications
+  faculty. A world seals a notification to its public half; the secret half
+  opens banners and nothing else, and never the world.
+- **timer**: the faculty that reads the box's clock, and the only thing on a
+  device that may. She wakes whoever invited her, every minute.
+- **clock**: the being who wakes beings at a time, on standings the root
+  placed. She holds the schedules and invited the timer.
+- **gate**: `for(occupant, asker)`; the whole permission model.
+- **look**: how a being is presented, as values; one optional ask.
+- **page**: a being's page as a tree of values in the screen's grammar; one
+  optional ask, read by a screen alone.
+- **owner pilot**: `quo pilot`, the model side over a ward's owner asks,
+  reaching the daemon's socket; with `--via`, a ward elsewhere through a
+  standing. Under cron, the estate's own agent.
+
+## The model side
+
+- **constitution**: the folder and instructions an autonomous agent runs
+  under; governance, never permission.
+- **runner**: an inline MCP client for a model that speaks function
+  calling; it drives the loop the MCP client would, over one conversation.