@nervur-org/dock 0.4.0 → 0.5.0

package/quo-api.md

@@ -1,196 +0,0 @@
-# The api route
-
-This is the fourth rendering of one describe. The screen speaks a being's
-describe as forms, the model side speaks it as tools, the CLI speaks it as
-lines, and this route speaks it as plain HTTP and JSON. It is one route of
-the daemon described in `papers/quo-dock.md`, which owns the routes, the
-grants, the avatar and the shared invariants; this document assumes all of
-that and adds only what the route does. `papers/WORLDS.md` decides what
-every route is held to: a route says the grammar a caller speaks and never
-who the caller is, and the same credential is honoured on every route.
-
-## What it is for
-
-A route hears every rung. A request carrying nothing is the stranger every
-route knows: an ask at the named ward's public being as `{}`, which is what
-every stranger is at every door, and what a browser fetch, a page
-rendering server side, a crawler and a tab on another origin are. A
-request carrying a bearer the box granted is an occupant: the identity's
-avatar in the world the grant names, asked through her one standing at the
-world's being. What a script sees with a bearer is what a model sees with
-the same bearer as tools and a tab sees as forms, because all three are
-one avatar's describe for one identity, and the gate is one decision for
-describe and for dispatch. The route judges nothing and names nobody: the
-public being answers a stranger by her own gate, the world's being answers
-an occupant by hers, and the route carries the answer.
-
-A grant is the box's and may die at any moment: a box wiped, an occupant
-removed at the world's being, thirty days without a refresh. Nothing of
-the world dies with it, since the avatar and her standing are the ward's;
-only the box's memory of which token names her is gone, and the holder
-trades again on a fresh invitation and lands on the same avatar. So a
-bearer is held by something with a human near it: a model client whose
-human clicks the allow page again, a script whose root mints again, a
-SaaS whose operator signs up again as at any vendor. A program of the
-org's that must run without a human is not a caller of this route. It is
-a harbor of the org with a ward and a standing, or an agent the daemon
-boots on the box, and either speaks Quo on keys that do not expire.
-
-A world is a ward, so the route names one. Every ward `init` made holds a
-desk, who is public for the first hello and answers a stranger nothing
-else, so a world's public reads live in a ward of their own, and the route is what
-makes a second ward reachable by name from outside: the corpus of a court
-watcher, a catalogue, a board. An occupant's world is the one her
-invitation named, and a bearer on any other world is refused.
-
-## The mapping
-
-`packages/dock/api/route.ts` is the route, `Request` in and `Response` out
-and naming no terrain: the daemon mounts it under `/api` and the proxy maps
-it from the api. hostname, and the worker at the edge mounts the same file
-under its harbor's prefix. It asks its harbor for the wards it holds and for
-which of them a caller who names none is at, and for nothing else.
-
-| request                              | Quo                                                                  |
-| ------------------------------------ | -------------------------------------------------------------------- |
-| `POST /api` `{identity, invitation}` | the trade: her avatar knocks with it, and a grant is issued          |
-| `POST /api` `{refresh}`              | the next grant; the old refresh token dies                           |
-| `GET /api`                           | the describe of the default ward, as `GET /api/<that ward>`          |
-| `GET /api/<ward>`                    | the describe: the public being for nobody, the avatar under a bearer |
-| `GET /api/<ward>/<ask>?k=v`          | that ask, the query as args, every value a string                    |
-| `POST /api/<ward>/<ask>` JSON body   | that ask, the object as args                                         |
-| `POST /api/<ward>/<being>/deliver`   | a vendor's delivery, the raw body and the headers to that envoy      |
-| `GET /api/<ward>/<being>/deliver`    | the same with an empty body: a redirect lands here, query in headers |
-| `OPTIONS`                            | the preflight, any origin, `authorization` allowed                   |
-
-What a caller leaves unsaid follows `papers/WORLDS.md`, and none of it is
-a default the route picks. A credential names an identity in a world, so an
-occupant's ward is her grant's and a bearer on any other ward is refused.
-A stranger carries nothing that names a world, so a stranger who names no
-ward is at the ward the terrain says it is at, the one the box hosts or the
-one it marks, and `GET /api` is what a tab at the web
-route's root sees and a model's first tool list. A being is never named,
-because a caller
-does not choose who answers: naming a ward is naming a door, and behind it
-the ward decides, the public being as nobody for a stranger and the
-identity's avatar for an occupant. The one path that names a being is the
-delivery, and there it is not a choice either: the envoy claimed that path
-at her birth, and a delivery with no envoy named has nowhere to land and
-is 404, never the public being.
-
-The trade is the allow page of the model side without the page. Nobody at
-a page vouches for a program, so a trade is a knock that spends: the
-invitation is the one the root minted for that identity on the world's
-being with `nervur invite`, sent as a line, and the avatar knocks with it
-inside the trade. An identity already in is refused with `already in` and
-refreshes instead, or is removed at the world's being and invited again,
-and never re-enters on a spent invitation. What comes back is the box's
-grant, `dock/grants.ts`: an access token for an hour, a refresh token for
-thirty days, the same grant the OAuth dance issues, honoured on the model
-route too.
-
-What she says crosses as the model side crosses it:
-
-| she answered                   | the client gets                                        |
-| ------------------------------ | ------------------------------------------------------ |
-| an object                      | 200 with that JSON                                     |
-| `{ error }`                    | 400 with that JSON                                     |
-| silence, a throw, a wait spent | 503 `{ error: 'silence' }`: the work may have happened |
-| an ask not hers for this asker | 400 `{ error: 'unknown ask' }`, her own answer         |
-
-For a stranger, a ward with nobody at the door is 503 beside them, and
-not a 404 of its own: on the wire a stranger who asks a ward that has no
-public being hears one silence, and a device speaking for strangers says
-what the door would. A stranger learns which world exists here and nothing
-else about it. For an occupant the ward's words cross by name, `unreached`
-as 503 `{ error: 'unreached' }`, and `removed` is 401 `{ error: 'removed'
-}` with the grant forgotten at the box, so a script the world's being
-removed starts over with a fresh invitation, exactly as a model client
-does.
-
-And what the route says on its own: 404 for a ward not here and for a path
-that is not one of the shapes, 400 for a body that is not a JSON object,
-400 `{ error: 'already in' }` for a trade on an identity that holds a live
-standing, 401 `{ error: 'unauthorized' }` for a bearer nobody issued or one
-that died, 403 `{ error: 'not your world' }` for a bearer on a world the
-grant does not name, 413 for a body past a megabyte, 405 for any other
-method. Every answer is JSON and open to any origin: the route carries
-nothing a stranger can use that she did not choose to say, and a bearer is
-the caller's to keep.
-
-The route holds none of the judgement. For a stranger it asks the ward the
-owner's `ask` with no being named, which is the public being asked as
-nobody, and the ward bounds the wait, names the three choices and saves
-before the pointer returns: a public being may write while answering, a
-tally, a board, and what she wrote is hers to keep. For an occupant it
-asks her avatar, `tools` for the describe and `call` for an ask, the two
-things every side asks of her, and saves the ward after.
-
-## The delivery
-
-A vendor's webhook is not a stranger's ask and does not land as `{}`, and
-it is not an occupant's ask either: it is the owner asking the envoy
-`deliver`, as `papers/quo-dock.md` says of envoys, and the route carries
-the bytes and nothing of the judgement. `POST /api/<ward>/<being>/deliver`
-is its own row and not an ask: the body is read as a string and never
-parsed here, since the vendor signed the bytes and a reparsed body fails
-her check, and the rule that a body is a JSON object does not apply. The
-route asks the ward's owner pointer for that being's `deliver` with `{
-body, headers }`, and answers what she answers: `{ ok }` as 200, her error
-object as 400, silence as 503. No bearer is read on this path, because the
-rung is not the caller's to prove: the signature is hers to check, and
-what fails it is refused by her and never by the route.
-
-A `GET` on the same path is the same ask with an empty body, and is where
-an OAuth redirect lands when an envoy begins an account, the code in the
-query. The query crosses inside the headers object under the name
-`:query`, which no header on the wire can carry, so her one ask in stays
-one and an author writes no second door for redirects. What she answers
-crosses as JSON like any delivery.
-
-**And a browser gets a page.** This is a road for programs with exactly one
-human arrival, and it is somebody who has just paid for something: a vendor
-returns her by opening this URL in her tab, so without a page she ends a
-payment reading what an envoy says to a machine. A `GET` whose `accept`
-names HTML is answered with the human side's landing page, saying which of
-the two happened and offering the world's own page, since a tab a vendor
-opened has no history to go back through. What the envoy answered is never
-on it. Everything else is unchanged: a vendor asking for JSON is answered
-in JSON, a `GET` that says nothing about what it wants is answered in JSON,
-and the page carries no cross-origin header, since a page is for the
-browser that was sent here and never for a script somewhere else.
-
-On its own the route says 404 for a ward not here, for a being not hers
-and for a third segment that is not `deliver`, 413 past a megabyte and 405
-for any method but `POST` and `GET`. A vendor that retries on anything but a quick
-200 lands once, because she keeps the delivery id and answers `{ ok }` for
-one she has seen before she wakes anyone.
-
-## What is not here
-
-A ward's delivery reaching more than one envoy, and a vendor that cannot
-sign what it sends. Both stand when a first user does.
-
-## The proof
-
-`packages/dock/test/api.test.ts`, over a real daemon on loopback. A
-stranger: a world with a public board described and asked by anyone, args
-by query and by body, what she wrote kept across a reboot, no ward named
-being the device's own, and every refusal. An occupant: an invitation
-traded for a grant, the describe under the bearer being the avatar's own
-with no ward named and with hers, an ask through her, another world
-refused, refresh rotating, removal at the world's being ending the grant,
-and the identity let in again on a fresh invitation. One identity, two
-grammars: a bearer the OAuth dance issued honoured here and its refresh
-rotating at the trade, a bearer the trade issued opening an MCP session,
-and the tool list being this route's describe with her look and page
-left out. The delivery: signed bytes landing on an envoy's `deliver` as
-the owner, a good signature kept and woken once, a retry landing once, a
-bad one her refusal as 400, no bearer read, what she kept outliving the
-daemon, and the route's own 404, 405 and 413.
-
-The same route on a second terrain is
-`packages/dock/test/terrain/edge.test.ts`, behind `npm run deep:dock`: the
-trade at a worker's `/api`, the ask through her avatar, and the answer
-compared against a Node daemon doing the same thing, because a rendering of
-one describe must not differ by terrain.

package/quo-app-bells.md

@@ -1,280 +0,0 @@
-# The bells of a Quo app
-
-A ward on a dialer is reachable only while it holds a line. A closed tab, a
-phone asleep, an app in the background: the world has something to say and
-nobody is listening. The bell is how such a device is reached, the one way
-its platform allows, by waking it.
-
-Everything here is four pieces, and none of them is any publisher's. An
-adopter who ships their own Quo app under their own name runs the same four
-with their own keys, changes nothing in the library and nothing in the dock,
-and is not asking anyone's permission.
-
-## Why a service exists at all
-
-Apple and Google accept a push only when it is signed with the key of the
-team that published the app. A world's box holds no such key and never
-will, because the key belongs to whoever publishes the app and to nobody
-else. So a world hands the ring on to a service that publisher runs.
-
-This is the one place in Quo where a world does not reach a person
-directly, and it is not a design choice. It is the platform's rule, and the
-whole of this paper is about making that hop carry as little as it possibly
-can.
-
-Web Push needs no service. A world mints its own keypair and speaks to the
-browser's push service itself, so tabs and desks are free of this entirely.
-
-## The porter
-
-A bell is a ward, and its public being is the porter. A phone nobody knows
-arrives at her as `{}`, which is the one place in Quo a stranger is
-answered by design.
-
-She does one thing. A device says hello, she brings a doorbell into being
-for it, and hands back the way in. The device knocks, and from then on it is
-a named occupant with a heir and a count, which is where anything that must
-happen once belongs. Her own answer is safe to repeat, as a public being's
-must be: saying hello twice is two doorbells and no harm.
-
-A stranger who keeps knocking is the harbor's, never hers and never the
-door's. A bell needs no attestation, no account and no door of its own
-invention, and it should have none.
-
-## The doorbell
-
-One being per device. Two things live in it.
-
-**The platform token**, in her cells, written by the device and read by
-nobody. It leaves for nowhere. No world ever sees it, so no world can copy
-it, hand it on, or keep ringing after it is told to stop. When the platform
-hands the phone a new token, the phone writes it here once and not one world
-is told anything.
-
-**One occupant per allowed world.** The device asks the doorbell for a way
-in, hands it to a world it has joined, and that world knocks and holds an
-ordinary standing. That row is the whole of the permission, and it is held
-at the bell, by neither the world that rings nor the publisher who holds the
-key.
-
-So the pair is recorded independently: this device, that world. A device
-with presence in many worlds has many rows here, and every one of them
-stands or falls on its own.
-
-## Allowing and disallowing
-
-**Allowing is an invitation the device mints.** A world can only ring a
-phone that chose it. There is no list of approved worlds anywhere, and there
-must not be: gating it would make the publisher the gatekeeper of every
-world's relation with its own member, which is the thing Quo exists to
-abolish, and it buys nothing, because the consent is already there in the
-act of handing over the invitation.
-
-**Disallowing is `remove`.** One occupant goes. The heir is forgotten and
-its last keys are kept apart, bounded, so that world hears `removed` once at
-the door and nobody else hears a thing. Her other worlds are untouched. It
-takes effect at the bell, so it does not depend on the removed world being
-honest about it, and there is nothing it could have kept that would still
-work.
-
-## What a ring carries
-
-A world rings its standing. It names no device, no token and no world,
-because the doorbell reads both ends from the standing the ask arrived on.
-There is nothing in a ring to forge.
-
-It carries one thing: a payload sealed to the device's own key. Not to the
-bell's, not to the world's, not to anyone else's. The bell passes ciphertext
-it could not read if it tried, the platform carries ciphertext, and on the
-device a notification service extension unseals it before the banner is
-drawn. What the person sees is an ordinary, immediate notification.
-
-So the claim is not that the doorbell carries nothing. It is that the
-doorbell carries nothing anyone but her device can read, which is the
-stronger promise, because the weaker one bought its purity with the banner
-itself: a notification composed after the app wakes is one the platform may
-delay at its own discretion and one a person who force quit the app never
-sees at all.
-
-The payload is bounded by what the platform will carry, four kilobytes on
-APNs, and the doorbell refuses a seal that will not fit rather than letting
-a platform nobody is reading refuse it two hops later.
-
-Web Push carries the same line and seals it once rather than twice. The
-standard encrypts a body to keys only that browser holds, so the only party
-a banner key would hide it from is the push service, which that encryption
-already excludes. A second seal would buy nothing and would make every tab
-keep a banner key for it. So a world encrypts the line itself, the browser
-opens it, and the worker shows what it was handed.
-
-## Where a bell runs
-
-Anywhere a harbor runs, and it is the same bell. A bell is a ward: the
-porter, a doorbell per device, and the push faculty of the ward it stands
-on. Nothing in it knows a platform.
-
-What differs is one thing, and it is the thing a faculty is for. The
-faculty's rings are built by the terrain out of what that terrain has: a
-worker's `fetch` speaks HTTP/2 and an edge bell rings APNs with it, a
-droplet speaks it with `node:http2` and rings the same service, and a
-terrain with neither holds no `apns` ring and says so. A publisher who
-starts on a worker and moves to a box moves the ward, keeps its pk, and
-neither a device's standing nor a world's is disturbed.
-
-So the edge is a convenience and never a requirement. It is a good first
-home because a bell keeps almost nothing and must answer whenever any world
-rings, and that is all it is.
-
-## Nothing is configured
-
-A bell has no configuration file and wants none. What it holds, it holds the
-way every being holds anything.
-
-- **Who may ring** is an occupant, invited by the device.
-- **What is rung** is a token in a doorbell's cells, written by the device.
-- **Which service a world hands a ring to** is a cell on the push faculty,
-  set by the root, because whose service it is belongs to an estate and not
-  to a world.
-- **The platform keys** are the terrain's secrets and reach the faculty as
-  its rings are built, never a file in a tree and never a cell.
-
-Rotation is the same answer twice. A heir rotates as it speaks, which is
-Quo's and needs nobody. A platform token rotates by the device writing it
-once, and because no world was ever given one, no world is told.
-
-## The banner key
-
-A world seals to a key that opens banners and nothing else.
-
-It is the device's, one pair, and it lives in the cells of the box's
-notifications faculty, which is the being that shows a human a line. That is
-the source of truth and the only place the pair is kept. The public half
-goes to a world when the device admits it, beside the invitation to the
-doorbell. The secret half never leaves the device.
-
-Where a platform's own notification process can read it is the faculty's
-business, and this is the whole reason the key sits there rather than in a
-being of the library's. On a phone the extension that draws the banner is a
-second process, so the faculty puts the secret in the keychain group it
-shares with it. On a desk and in a tab the terrain has its own answer. A
-faculty is the terrain's hand, and a key that must be reachable by the
-platform belongs in the hand and not in the library.
-
-A tab keeps none. Web Push is encrypted to the subscription's own keys and
-a browser draws its own banners in its own worker, so there is neither a
-second process to reach nor a second seal to open.
-
-Minting the key is where the person is asked. A device that has just minted
-one is a device about to be rung, and the ring that carries a banner is an
-alert the platform draws for nobody who has not allowed it. Registering for
-the doorbell asked for nothing, deliberately, because a doorbell displays
-nothing; so the phone asks in the same act as it plants the key, and a
-refusal costs the line and not the wake. The key stays where it is, the
-world is admitted, and what arrives is a push the person reads when she
-opens the app.
-
-It is not the ward's own key, and that is deliberate. The ward's seed opens
-everything the person sees and is kept so that it never leaves the device at
-all. A banner key opens banners. If the process that draws notifications
-were ever turned against her, the second loses her a line of text and the
-first would lose her the world.
-
-## What a bell knows, and what it cannot
-
-It knows which device, which world, and when. It cannot know what was said.
-
-That is the honest accounting, and the design holds it to the minimum: keep
-counters and no log of rings, name a doorbell by nothing that identifies a
-person, and hold occupants as keys with no world's name beside them. A bell
-that kept more would be a registry of worlds, and the app exists not to have
-one.
-
-The publisher cannot add a world to a device's doorbell. Only the device
-can, because only the device holds the standing that mints a way in. The
-list is held at the bell and it is not the bell's to write.
-
-## The three kinds
-
-**Web.** A world mints its own keypair and rings the browser's push service
-itself. The line rides in the ring, encrypted end to end by the standard to
-the two keys of that subscription, no bell is involved, and no banner key is
-wanted.
-
-**iOS.** APNs, signed under the publisher's key, spoken over HTTP/2. The
-service extension is what makes a sealed payload into a banner, and it needs
-the device's key reachable from a second process.
-
-**Android.** The same shape under FCM, with a data message the app composes
-from.
-
-A bell that holds no key for a kind says so to whoever rings that kind,
-which is what a publisher who rings no Android phones says to an Android
-phone. It does not pretend it rang.
-
-## What this refuses
-
-- **An account at the bell.** The standing is the identity. An account would
-  be the registry of worlds, and there is no third thing it would buy.
-- **Approving worlds.** The device approves. Nobody else is asked.
-- **A token that travels.** The moment a world holds one, disallowing is a
-  request rather than a fact.
-- **A payload the bell can read.** Including one it merely promises not to.
-- **A configuration file.** A bell is occupants, standings and cells. A
-  second place to say who may ring would be a second answer to a question
-  that already has one.
-- **A terrain in the design.** Edge or droplet is where the ward sleeps, and
-  a bell that worked one way on one and another way on the other would be
-  two bells.
-- **Anything publisher-specific in the packages.** Team ids, bundle ids, a
-  bell's address and a push key are an estate's, carried in by its
-  environment. What is published is the porter, the doorbell, the faculty
-  and the service, and they name nobody.
-
-## Where the tree stands
-
-The one place under this paper where a gap between it and the code is named.
-
-Each of the three grounds has drawn a line on a screen, and each in the
-shape this paper gives it. On an iPhone the app minted its banner key,
-planted the secret half where the extension reads it, took a device token
-from Apple, and a ring under the team's own key carried a hundred and
-thirty bytes of ciphertext that the extension opened. On Android the ring
-carried an empty data map and the device composed the line itself. In a
-real Chrome the world found the tab unreachable, rang its subscription, and
-the worker drew what it was handed.
-
-- **A simulator draws no sealed banner**, because it runs no notification
-  service extension at all. It proves everything on either side of that
-  move: the pair minted and kept across a reinstall, the secret half
-  planted, and the seal opened by the extension's own code against a
-  payload a world sealed to that device. The move itself is an iPhone's.
-- **A browser wants a real one.** The Chromium a bench drives answers
-  `showNotification` neither way, so the line that draws it is the one line
-  no test here runs. A browser also asks the human with a button and never
-  on load, so the permission is a click and no suite can spring it.
-- **Android is pointed at a Firebase project by a file a build carries**
-  and the tree ignores, since the file holds a key. The project is the
-  publisher's own and holds the one app it ships. Its id is minted once and
-  never moves, so a project opened for something else keeps that name for
-  as long as it lives, which is a thing to know before opening one.
-- **The ring on real hardware holds past the first.** A phone with the app
-  backgrounded draws the banner, and so does one locked with the screen
-  off. Five rings two seconds apart all arrived, in order, none coalesced
-  and none dropped, so the platform throttles nothing at that rate. And a
-  ring lands after a full power cycle on an app that has not run since the
-  device booted, which is custody at its strongest: the doorbell standing
-  and the banner key are both kept, and nothing has to be launched to
-  receive. A background push reaches no app the human force quit, by
-  Apple's rule, so a phone under test is backgrounded and not closed.
-- **An Android device reaches its bell over `wss` and never `ws`.** The
-  shell is served from `https://localhost` there, and that ground's WebView
-  refuses a cleartext socket from an HTTPS page as mixed content, so a bell
-  on a bare address on the same network cannot be dialled at all and the
-  device comes away with no doorbell. A phone's WebView on the other ground
-  allows it. So a bell under test wants a real name and a certificate,
-  where the other ground is content with an address on the wire.
-- **A ring costs about 290ms on the box side**, measured from the ask to
-  the answer that comes back only once the bell has handed it to Apple and
-  Apple has taken it. It is steady under a burst: five rings measured 291,
-  294, 291, 295 and 295. What the platform then does with it before a
-  screen lights is the platform's and is not ours to measure.