@niscorp/moss 0.3.0 → 0.3.3

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 (48) hide show
  1. package/CHANGELOG.md +160 -0
  2. package/DESIGN.md +92 -21
  3. package/DOCS.md +190 -40
  4. package/README.md +7 -2
  5. package/dist/{chunk-J72N3EMJ.js → chunk-4T6KAXBP.js} +45 -27
  6. package/dist/chunk-4T6KAXBP.js.map +1 -0
  7. package/dist/{chunk-3CJCJKKY.js → chunk-AUZMT3GL.js} +742 -654
  8. package/dist/chunk-AUZMT3GL.js.map +1 -0
  9. package/dist/{chunk-ZOEUEMDX.js → chunk-HOZID4EM.js} +131 -16
  10. package/dist/chunk-HOZID4EM.js.map +1 -0
  11. package/dist/chunk-NE2EXMTO.js +103 -0
  12. package/dist/chunk-NE2EXMTO.js.map +1 -0
  13. package/dist/client/node.cjs +1 -1
  14. package/dist/client/node.cjs.map +1 -1
  15. package/dist/client/node.js +1 -1
  16. package/dist/client/node.js.map +1 -1
  17. package/dist/client.cjs +60 -26
  18. package/dist/client.cjs.map +1 -1
  19. package/dist/client.d.cts +6 -1
  20. package/dist/client.d.ts +6 -1
  21. package/dist/client.js +2 -2
  22. package/dist/{document-Jhfii6kd.d.cts → document-DhWxieUc.d.cts} +24 -4
  23. package/dist/{document-Jhfii6kd.d.ts → document-DhWxieUc.d.ts} +24 -4
  24. package/dist/index.cjs +780 -572
  25. package/dist/index.cjs.map +1 -1
  26. package/dist/index.d.cts +19 -3
  27. package/dist/index.d.ts +19 -3
  28. package/dist/index.js +2 -2
  29. package/dist/node.cjs +373 -219
  30. package/dist/node.cjs.map +1 -1
  31. package/dist/node.d.cts +2 -1
  32. package/dist/node.d.ts +2 -1
  33. package/dist/node.js +3 -3
  34. package/dist/terminal/index.cjs +60 -26
  35. package/dist/terminal/index.cjs.map +1 -1
  36. package/dist/terminal/index.js +2 -2
  37. package/dist/vite.cjs +103 -28
  38. package/dist/vite.cjs.map +1 -1
  39. package/dist/vite.d.cts +1 -1
  40. package/dist/vite.d.ts +1 -1
  41. package/dist/vite.js +14 -9
  42. package/dist/vite.js.map +1 -1
  43. package/package.json +15 -14
  44. package/dist/chunk-3CJCJKKY.js.map +0 -1
  45. package/dist/chunk-DPFWL7BS.js +0 -64
  46. package/dist/chunk-DPFWL7BS.js.map +0 -1
  47. package/dist/chunk-J72N3EMJ.js.map +0 -1
  48. package/dist/chunk-ZOEUEMDX.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,165 @@
1
1
  # @niscorp/moss
2
2
 
3
+ ## 0.3.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 78a563f: A page served by its app no longer holds its session: the browser does, in a cookie no script can read.
8
+
9
+ A session token in a page — in `localStorage`, or in the script-readable cookie copy `browserEnv({ cookie: true })` kept — is there for anything else that runs in that page to take. Now the server writes the session into a cookie the page cannot read (`HttpOnly`, `SameSite=Lax`; `__Host-` prefixed and `Secure` over https) in its answer to the socket's upgrade, and the browser sends it by itself with the two requests that need to know who is asking: the page, and the upgrade. After a reload the page holds nothing.
10
+
11
+ **The setup this stops working for:** code that read the session token out of the page. `localStorage['nisc.token']` is empty once the browser holds the session, and the cookie copy is no longer written, so anything that took the token from there — to call a route with `Authorization: Bearer`, say — finds nothing. No route answers to the new cookie, on purpose: a browser sends a cookie with requests another site makes it send. And `renderDocument` no longer answers a cookie that does not resolve with a `Set-Cookie` that takes it back; the upgrade is the one place the cookie is written.
12
+
13
+ What happens, and to whom:
14
+ - **Only the app's own page.** The cookie is read and written when the upgrade's `Origin` is the host it was addressed to, or one listed in the new `runtime.origins` (for a proxy that rewrites `Host`). A page on another origin — which a browser sends the cookie with all the same — is nobody. A terminal that is not a page of its app (a process on `nodeEnv`, a page served from somewhere else, a browser that refuses cookies) holds its own token and offers it, exactly as before.
15
+ - **Nobody is signed out by the update.** A token an earlier build left in storage is offered once, moved into the cookie by the answer, and removed from storage along with the old copy.
16
+ - **Seats.** The cookie is named by the terminal's `tokenKey`, so several people can be signed in on one origin as before; the terminal names its key in the socket's address (`?key=`), and `renderDocument`'s `tokenKey` reads the same one. The name ends with the port when the page is on one — a browser keeps cookies by host, not port, and two apps on localhost would otherwise sign each other out — so `renderDocument` takes `request.host`; `mountSite` and the vite plugin pass it.
17
+ - **Signing out.** A cookie that no longer resolves is taken back on the next upgrade. Under an app's own identity provider the token may go on resolving, so a terminal that was signed out says so (`?leave=1`) and the cookie is taken back whatever it holds.
18
+ - **A sign-in the app answers over HTTP** (a link redeemed, a provider's callback) sets the cookie itself: `sessionCookies(request, token, { key?, lastsMs? })`, exported from the package root, returns the `Set-Cookie` values. The page that follows is signed in and was never handed the token. The vite plugin's `/dev/as/<who>` does this now.
19
+ - **A transport of your own** passes what the request carried — `connection.upgrade = { offered, origin, host, cookie }` — and, to let the cookie be written, leaves the request unanswered until the connection is first used, answering then with the cookies moss named through `upgrade.answer(cookies)` (moss names them before it uses the connection, and names none when there are none to write). One that has already answered reads the cookie and writes none. `attachSocket` does both.
20
+ - **A `WireEnv` of your own** is unchanged: without `tokens.held` a terminal stores its token as it always did.
21
+
22
+ **What to change:** nothing in an app that uses `createWire` with `browserEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. `browserEnv({ cookie: true })` still compiles and the option now does nothing; drop it when convenient. A sign-in page that writes the token to `localStorage` keeps working (the token is moved on the next upgrade), and is better replaced by `sessionCookies` on the response. Behind a proxy that rewrites `Host`, list the app's origin in `runtime.origins` — until then every page looks like one served from somewhere else, so the app works as it did before this change, each terminal holding its own token, and moss says so once in the log. An app that draws its own pages passes `request.host` to `renderDocument`; behind a proxy that rewrites `Host` to an upstream on another port, `site` is where the port is taken from.
23
+
24
+ - 51dc5ce: DESIGN says what a rebuilt shell holds. "Durability" named a projection as the durable thing, and moss has built none ("Deliberately unbuilt" lists it). It now says the database is the durable thing: a shell is rebuilt on the next connection from definitions and whatever the app reads from rows as it builds, and evicting an idle shell, restarting the process and `reset` each cost what was only in the shell — the screens someone had opened, and what they had typed. Two source comments now say the same. No code changed.
25
+
26
+ **What to change:** nothing.
27
+
28
+ - da42472: With `shellFrameDelta` on, a canvas whose frame is over 64 KB is sent whole, and no longer compared.
29
+
30
+ Encoding a delta costs the server in proportion to the size of the two frames, not of the change, and it does the work on the thread every session shares. Nothing bounded it. Measured on the encoder alone: a 0.3 MB frame held the thread 65 ms for one changed letter, a 2.7 MB frame over a second, and at 20 MB it ran for eight seconds, took a gigabyte and failed — after which the frame was sent whole anyway. Every session on the process waited each time. A large frame needs nothing unusual: a long table, or one long value in a bound field, which any terminal can send. Now a change is sent whole, with no encode, when the frame the terminals hold or the frame replacing it is longer than 64 KB — where an in-place change measured about 7 ms.
31
+
32
+ Nothing moves with `shellFrameDelta` off (the default), for a terminal that did not ask for deltas, or on a canvas whose frames are at most 64 KB: those are byte for byte what they were. The rendered tree is the same in every case.
33
+
34
+ **What to change:** nothing. With deltas on, a change to a canvas over 64 KB now costs that canvas's whole frame on the wire — what a terminal that never asked for deltas is sent — where it had cost a delta, after the encode.
35
+
36
+ - a91b5db: `migrateTables`: the step that changes the tables, and checks the app's entries against what it leaves before it commits. `runtime.tables` hands it the app's own.
37
+
38
+ A deployment whose runtime says `migrations: 'verify'` refuses to start with anything pending, and moss had nothing to run first. An app's own tables were outside that run, so `'verify'` did not cover them.
39
+
40
+ `runtime.tables` takes the app's own table sequences (and another owner's the app keeps — tide's `TIDE_SEQUENCE`). They join moss's one ledgered run, after moss's own. A runtime that hands tables over does not also migrate them itself.
41
+
42
+ `migrateTables(runtime, app, { dryRun? })` applies everything pending in that run and, before it may commit, checks every entry of the manifest against the schema as it would stand: a read is resolved, a write is put to the gates it passes before it runs (vex's `mutationMisfits`). An entry that does not fit refuses the run — strata's `DOES_NOT_FIT`, each reason as `fingerprint: why` — and nothing is applied. It checks when nothing was pending too, so a release that changes an entry and no table is checked.
43
+
44
+ One kind of entry is listed and not refused: one that already did not fit before the run and that the database already holds seeded exactly as it is. A new or changed entry gets no such pass. The report also says which tables and columns a run removed and which column types it changed.
45
+
46
+ It sees entries and nothing else: not SQL written by hand, not a column a scope rule stamps, not what a value means.
47
+
48
+ **What to change:** nothing. A boot applies and verifies exactly what it did: a runtime without `tables` runs the same sequences in the same order.
49
+
50
+ - 812c464: `runtime.vexConfig` hands the query engine its settings.
51
+
52
+ Moss built the vex engine with no `config`, so a deployment ran on vex's defaults — 100 rows for a list that states no limit, 1000 at most, a ten-second read timeout — and had no way to change one.
53
+
54
+ `NiscRuntime` takes an optional `vexConfig`, passed to `createQueryEngine` as its `config` unread: `defaultLimit`, `maxLimit`, `capAuthored`, `statementTimeoutMs` and the rest of `QueryEngineConfig['config']`. Unset, the engine is built exactly as before.
55
+
56
+ **What to change:** nothing. Set `vexConfig` in your runtime to change one of the engine's numbers — for example `vexConfig: { capAuthored: true }` to keep seeded entries under `maxLimit`.
57
+
58
+ - 770f754: A frame the websocket transport refuses closes that connection; it no longer ends the process.
59
+
60
+ `attachSocket` listened for a connection's messages and its close, and not for its errors. `ws` reports what it refuses from a client — a malformed frame, text that is not UTF-8, a message over its size limit — as an `error` on that connection, and Node throws an `error` nobody listens for. So one such frame, from any client that could open the socket, signed in or not, ended the server process and every session on it. The transport now listens: `ws` has already closed the connection with the status that says why (1002, 1007, 1009), one line is logged (`[moss/node] a connection was closed on what it sent: …`), and nothing else is touched. Every host that calls `attachSocket` gets it — `serve`, `nisc start`, the vite plugin, an app's own listener.
61
+
62
+ **What to change:** nothing. An app this had happened to was not running. A process-level `uncaughtException` handler that was catching these no longer hears them.
63
+
64
+ - 61a4060: A sign-in made over the socket no longer hands the page its token. It reaches the page sealed, and only that browser can open it.
65
+
66
+ `session.grant(token)` happens on a socket, and a socket cannot write a cookie — so the token has to travel through the page to the terminal's next upgrade, where the session cookie is written. It used to travel as itself, which for that moment put it where any script in the page could take it. Now it travels encrypted with a key the browser holds in a second cookie no script can read (the _seal_), given by the answer to the browser's first upgrade. The page hands the sealed sign-in back and cannot open it; neither can anybody it is shown to, on this machine or another — without that browser's seal it opens nothing, and after a minute it opens nothing at all.
67
+
68
+ **The setup this stops working for:** none that worked. What is new for a browser: a terminal on `browserEnv()` now names `sealed=1` in the socket's address, and a browser that opens a socket to its app is given one more cookie — `nisc.seal` (`__Http-nisc.seal` over https): `HttpOnly`, `SameSite=Lax`, sent with the socket's path and no other, kept until the browser closes. It is given whether or not anybody signs in. It is a key, not a name: it is not stored or looked up on the server, and no page request carries it, so a page drawn for nobody stays cacheable for everybody.
69
+ - **Any credential, any number of processes.** Nothing is kept on the server between the sign-in and the upgrade that completes it, so it does not matter which process answers either, and the token can be moss's own or an app's provider's.
70
+ - **Terminals that keep their own token are handed it as before:** a process on `nodeEnv`, a page served from another origin, a `WireEnv` without `tokens.held`, a transport that cannot answer an upgrade late. `{ type: 'session', token }` is unchanged for them.
71
+ - **A browser that does not keep the seal** — it sends none back with the sealed sign-in — is told (`seal_not_kept`); its terminal stops asking, and the next sign-in reaches it as a token. That costs such a browser one failed sign-in.
72
+ - **A terminal written by hand** that wants sealed sign-ins: `?sealed=1` on the address from the app's own origin; a `{ type: 'session', sealed }` message is offered back with `offerToken(null, sealed)`.
73
+
74
+ The seal's name over https is what keeps a script from supplying it: the seal is given after the page's script has started, and a script already running then could otherwise set one of its own first and open the sign-in that follows. `__Http-` is a name a browser lets only an HTTP answer set. Not closed: a browser that does not know that prefix treats it as any other name; and a server on a sibling subdomain can still set one, which with a script in the page as well is the same opening.
75
+
76
+ **What to change:** nothing.
77
+
78
+ - 8012cd8: A message a terminal sends over the socket is at most 256 KB; a host that takes larger ones says so with `attachSocket`'s new `maxMessageBytes`.
79
+
80
+ **The setup this stops working for:** an app whose terminal sends a message over 256 KB — in practice a file put into a model value as base64 (a picked picture is megabytes). That message now closes the connection with `1009` and what it carried does not arrive; the terminal reconnects as after any other close, and a signed-in person's shell is as it was. To keep the old behaviour, a host that calls `attachSocket` passes the size it takes: `attachSocket(httpServer, server.socket, '/socket', { maxMessageBytes: 100 * 1024 * 1024 })` is what `ws` did before. `serve()`, `nisc start` and the vite plugin take the default and cannot raise it; an app on one of those that needs more attaches the socket itself. Better than raising it, and what `AGENTS.md` rule 9a says: a file never goes over the socket — the picker sends it to a route the app mounts, and the event carries what the route answered.
81
+
82
+ Why there is a limit. `attachSocket` created its `WebSocketServer` with no `maxPayload`, so the limit was `ws`'s own 100 MiB. Whatever a message carries, the server keeps — the value in the shell, and again in the last frame it sent — and sends back down in every later frame of that canvas. So the limit is what one connection, signed in or not, can make the process hold and re-send. Measured per open connection: 0.2 MB with nothing sent, 1.5 MB after a 256 KB value, 3.3 MB after 1 MiB, 48 MB after 16 MiB. Compression does not bound it — a 64 MB message of one repeated letter is 60 KB on the wire — so the count is of the message once inflated. What a terminal legitimately sends is an event: a press, a typed value, a row handed back. A few KB.
83
+
84
+ **What to change:** nothing, unless a terminal of yours sends more than 256 KB in one message — then one of the two things above. A typed value still has about 250,000 characters of room.
85
+
86
+ - 10875eb: A terminal's session token no longer rides the socket's address. It is offered in a header of the same request, and a token in the address is not read.
87
+
88
+ **The setup this stops working for:** a terminal and a server that are not the same version. The wire protocol is now 2 and the server speaks nothing older, so a terminal built before this is refused with `client_too_old` and a `4426` close — the existing "reload to get the current build" path — and a terminal built after it is refused by an older server with `server_too_old`. An app's terminal and server are one package and deploy together, so in practice this is a tab left open across the deploy: it reloads once. Three things written by hand also change:
89
+ - **A terminal written by hand** (`new WebSocket(`…/socket?token=…`)`, as a check or a script does) names the protocol and offers the token: `new WebSocket(`${base}/socket?protocol=${PROTOCOL}`, offerToken(token))`. `PROTOCOL` and `offerToken` are exported from `@niscorp/moss`; `offerToken(null)` is a terminal that is nobody.
90
+ - **A `WireEnv` of your own**: `socket` takes `{ url, offered }` where it took `url`, and constructs `new WebSocket(url, offered)`. One argument on purpose — an env that kept the old shape would have gone on compiling and connected everybody as nobody; this way it does not compile.
91
+ - **A transport of your own** (anything that is not `attachSocket`) hands over what the request offered: `connection.upgrade = { offered }`, the `Sec-WebSocket-Protocol` header split on commas, and answers the subprotocol `nisc`. Without it every terminal is served as nobody.
92
+
93
+ Why. The token rode the upgrade's query string, and an address is what every proxy, load balancer and access log between a browser and the app writes down. The request has one header every host lets a terminal set, a browser included: the subprotocols it offers. So the terminal offers `nisc`, and beside it its token, base64url (a subprotocol is an HTTP token; a session token need not be); the server answers `nisc` and never the other. Who a terminal is is still decided on the upgrade request, before anything is served, so there is no connection that is open and waiting to be told. A server that kept reading `?token=` for older terminals would have kept the address open for as long as anything used it, which is why protocol 1 is refused rather than served.
94
+
95
+ **What to change:** nothing in an app that uses `createWire` with `browserEnv()` or `nodeEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. Otherwise one of the three above. Anything that read `?token=` off the socket's address — a proxy rule, a check — no longer finds it there.
96
+
97
+ - fc50d20: `AGENTS.md` says where files go. Rule 9a: file pickers live in the kit; a file never goes over the socket; the app saves it wherever it wants. The review pass's "no `fetch` outside the endpoint layer" gains its one exception, to send a file. No code changed.
98
+
99
+ A picker that puts a file in its model value sends it over the socket as base64, and the tree brings it back on every render of that canvas. Measured against a moss server: one 15 MB file was 20 MB up and 100 MB down across five renders. Sent by the picker to a route the app mounts on its server, or to a system the app already has, the same file put nothing on the socket.
100
+
101
+ moss gains a test and nothing else: a route an app adds to the built server reads who is asking, as moss's own surfaces do.
102
+
103
+ **What to change:** nothing for the rule itself. But this release also limits a message a terminal sends to 256 KB (the moss entry on the socket's message limit), so a picker that emits a file's bytes as its model value now works only for a file under about 190 KB: send the file from the picker, as rule 9a says, or raise the limit where the app attaches the socket.
104
+
105
+ ## 0.3.2
106
+
107
+ ### Patch Changes
108
+
109
+ - a7d4de4: `server.charterReport()` — the charter report the server was verified by.
110
+
111
+ `createServer` runs `verifyCharter` at boot and again on every `refresh`, refuses on the report's `errors`, and read nothing else of it. The rest was computed and dropped: the `warnings` (an action no role grants, an `allow` that matches nothing) and each role's closure `issues`. A host that wanted them had to run `verifyCharter` itself, over a data universe it built by hand.
112
+
113
+ `charterReport()` returns that report: boot's, then that of each `refresh` that passed. A refresh that is refused leaves the one the server is still serving on. Nothing is printed, and boot refuses exactly what it refused before.
114
+
115
+ ```ts
116
+ const server = await createServer(app, runtime);
117
+ for (const warning of server.charterReport().warnings)
118
+ console.warn(`${warning.rule}: ${warning.detail}`);
119
+ ```
120
+
121
+ DOCS.md says one thing about what it holds: a push whose target is a binding (`@event.payload`, `$.target`) is listed among a role's `issues` as "not in the catalog", though it is resolved when the step runs.
122
+
123
+ **What to change:** nothing.
124
+
125
+ - f70d461: DOCS and DESIGN say what boot refuses. `createServer` refuses on `verifyCharter`'s errors. The closure audit's findings are filed under each role's `issues` in the report and are neither refused nor printed: a role granted an action that pushes one it is not granted boots, and the press does nothing. Two source comments now say the same. No code changed.
126
+
127
+ **What to change:** nothing.
128
+
129
+ - a7d4de4: The docs say a charter defines a role named `public`. A request with no session, and a signed-in principal with no assignment, resolve to that role, and the name is fixed. A charter without it still boots and nothing is said; those requests then fail with `Unknown role "public"` (a 500, a socket closed `4500`, a page served undrawn). `public: []` grants nothing. README, DOCS and DESIGN now say so, and a test holds it. No code changed.
130
+
131
+ **What to change:** nothing, for a charter that has the role. One that names its visitor role something else adds `public` beside it.
132
+
133
+ - 979b3e3: `src/principal.ts` is text again. One separator in `wearableOf` was written as a raw NUL byte where the same file writes the escape `'\0'` two functions down, so git treated the whole file as binary: its diffs showed `Bin`, and a text search (`git grep -I`) skipped the file that defines `wearableOf`, `resolveFor` and `verifyCharter`.
134
+
135
+ The byte is now the escape. The string it produces is the same one, and the built package is the same code: every built file is identical apart from the names of two chunks, which are hashes that take the embedded source text in.
136
+
137
+ **What to change:** nothing.
138
+
139
+ ## 0.3.1
140
+
141
+ ### Patch Changes
142
+
143
+ - fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
144
+
145
+ ```ts
146
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
147
+ prism.version; // the version that is installed, not the range that asked for it
148
+ ```
149
+
150
+ Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
151
+
152
+ **What to change:** nothing. An app that read a version by path can read it by name.
153
+
154
+ - 1e6d55d: A pool's `query` and `transaction` are called on the pool, and a transaction's `query` on the transaction — never taken off the object first. A driver's own object has them as methods that need their receiver, and taken off they failed inside the driver, on a property nothing in nisc names:
155
+ - **strata** — `migrate` and `upgradeStore` over a `PGlite` threw `Cannot read properties of undefined (reading '_checkReady')`; `status` and `readLedger` did too, once a ledger existed. A pool whose `transaction` hands a checked-out `pg` client through as the transaction failed in `migrate` the same way.
156
+ - **moss** — `createTideStore` took `query` off the transaction. Over a pool that hands its client through, every transaction of the store failed inside the driver, and tide recorded the run as deferred: nothing threw, and the effect never ran.
157
+ - **vex** — `createPostgresAdapter` with a read limit set (`limitReads`) threw on a pool whose `transaction` is a method.
158
+
159
+ A `PGlite` now works as a pool as it is, and so does a `pg` wrapper that passes its client through. A pool built from closures (`createPglitePool`, a wrapper that builds its own `query`) behaves as before.
160
+
161
+ **What to change:** nothing.
162
+
3
163
  ## 0.3.0
4
164
 
5
165
  ### Minor Changes
package/DESIGN.md CHANGED
@@ -107,7 +107,10 @@ The organizing principle: an app hands over **artifacts** and an
107
107
  live in the terminal.
108
108
  - **Coherence is refused, not documented.** `createServer` runs `verifyCharter`
109
109
  (with nova's closure audit injected over effective definitions) and
110
- `verifyVariants`, and throws on errors. If it boots, it's coherent.
110
+ `verifyVariants`, and throws on errors. The closure audit's findings are not
111
+ errors: they are filed under each role's `issues` in the report, and boot
112
+ neither refuses on them nor prints them. If it boots, the charter and the
113
+ variants are coherent; a push to an ungranted action can still be in it.
111
114
 
112
115
  The test of the principle: moss adds no new vocabulary. Reads are vex, writes are
113
116
  vex, compute is functions, UI is actions, permissions are the charter. The server
@@ -132,9 +135,12 @@ compiles it.
132
135
  ## The socket
133
136
 
134
137
  The authority channel. Transport-blind: the protocol speaks through a
135
- four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`), and the
136
- RFC 6455 plumbing lives with each runtime's entry (`ws` on Node in `./node`,
137
- Bun-native later). One connection per client carries every canvas — ten open
138
+ four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`, and what
139
+ the upgrade request offered), and the RFC 6455 plumbing lives with each
140
+ runtime's entry (`ws` on Node in `./node`, Bun-native later). Who a terminal is
141
+ is decided on that request, from its headers — a session cookie its browser
142
+ sent, or a token it offers as a subprotocol beside `nisc` — and never from its
143
+ address, which every proxy on the way logs. One connection per client carries every canvas — ten open
138
144
  canvases are ten canvas ids on one pipe.
139
145
 
140
146
  **Down:** `hello` (the resolved catalog on connect, and the protocol the server speaks — the terminal names its own on the upgrade), `catalog` (declared for
@@ -160,11 +166,12 @@ Operational shape, all falling out of "the message is state, not history":
160
166
  same rule holds before the first connect: nothing is sent on a socket that is
161
167
  not open and nothing is held for when it is. A server-drawn page (below) is on
162
168
  screen before its socket, so a press in that moment is dropped.
163
- - **Durability.** The projection (once built) is the durable thing; the shell is
164
- a warm cache rebuilt from definitions + projection. Evicting an idle shell and
165
- restarting the process are both safe — shells rehydrate on the next connection.
166
- This is why an idle sweep can exist at all, and why `reset` costs nothing but
167
- the screen someone was on.
169
+ - **Durability.** The database is the durable thing; a shell is a warm cache,
170
+ rebuilt on the next connection from definitions and whatever the app reads
171
+ from rows as it builds. Evicting an idle shell, restarting the process and
172
+ `reset` cost the same and nothing more: what was only in the shell — the
173
+ screens someone had opened, and what they had typed. This is why an idle
174
+ sweep can exist at all.
168
175
  - **Recovery.** `reset` (up) throws a session's shell away and serves its
169
176
  replacement. It names no canvas, because it is the recovery for a session
170
177
  whose canvases are the broken thing; it is protocol-level, so no action
@@ -189,6 +196,58 @@ Operational shape, all falling out of "the message is state, not history":
189
196
  - **Size.** Two optional reductions — transport compression and frame deltas —
190
197
  sit under the protocol, both off the app's books. See below.
191
198
 
199
+ ### Where a browser keeps its session
200
+
201
+ A terminal served by the app it talks to does not hold its session. Its browser
202
+ does, in a cookie no script can read, and sends it by itself with the two
203
+ requests that need to know who is asking: the page, and the upgrade that opens
204
+ the socket. A token in the page — in storage, in a cookie script can read — is
205
+ there for anything else that runs in the page to take; one the page never has
206
+ cannot be taken from it.
207
+
208
+ - **The answer to the upgrade is where the cookie is written.** A cookie is set
209
+ by an HTTP response and by nothing else, and the upgrade is the one request
210
+ every terminal already makes. So who is asking is decided *before* the
211
+ request is answered, and the answer carries the cookie.
212
+ - **A sign-in over the socket reaches it sealed.** `session.grant` happens on a
213
+ socket, which cannot write a cookie; the token has to travel through the
214
+ page to the next upgrade. It travels encrypted with a key the browser holds
215
+ in a second cookie no script can read or set — the *seal*, given by the
216
+ answer to the browser's first upgrade under a name (`__Http-`) a browser
217
+ lets only an HTTP answer set. The page can hand a sealed sign-in back and
218
+ cannot open it, and neither can anybody it is shown to: without that
219
+ browser's seal it opens nothing. Nothing is kept here between the two
220
+ requests, so it works whichever process answers the second, and it works
221
+ for any credential — moss's own, or an app's provider's. The seal rides only
222
+ the socket's path, so no page request carries it and a page drawn for nobody
223
+ is still the same for everybody.
224
+ - **Only for the app's own page.** A browser sends a cookie with any page's
225
+ request to this host, a stranger's included, and the socket is the whole
226
+ app. So the cookies are read and written only when the request's `Origin` is
227
+ the host it was addressed to (or one `runtime.origins` lists, behind a proxy
228
+ that rewrites `Host`). From anywhere else a terminal is who the token it
229
+ offers says, or nobody.
230
+ - **No route answers to it.** The HTTP surfaces read `Authorization` and
231
+ nothing else, so no request another site can make a browser send does
232
+ anything as the person. A page request does read it — every site may link to
233
+ a page, and none can read the answer.
234
+ - **Its name is the terminal's token key**, so several people can be signed in
235
+ on one origin, each in a seat. It ends with the port when the page is on
236
+ one: a browser keeps cookies by host, not by port, and two apps on localhost
237
+ would sign each other out. Over https it is `__Host-` prefixed and `Secure`,
238
+ which a browser lets nothing but this host set.
239
+ - **What the page sees is a flag** (`<name>.held=1`), with no secret in it: how
240
+ a terminal knows to let go of a token it was holding, and that a page drawn
241
+ for somebody was drawn for it.
242
+ - **Signing out says so.** moss revokes its own credential, and a cookie that
243
+ no longer resolves is taken back on the next upgrade. An app's own provider's
244
+ token may go on resolving, so a terminal that was signed out says it is
245
+ leaving, and the cookie is taken back whatever it holds.
246
+ - **Any other terminal holds its own token** — a process, a page served from
247
+ somewhere else, a browser that refuses cookies — offers it, and is handed a
248
+ sign-in as its token, as before. A token such a page of the app's own offers
249
+ (one an earlier build left in storage) is moved into the cookie and let go of.
250
+
192
251
  ### What a frame costs
193
252
 
194
253
  A server-authored shell pays for its inversion in bytes: every change re-sends
@@ -233,7 +292,11 @@ Three rules keep it honest:
233
292
  everyone — so one encode serves the whole room.
234
293
  2. **Decisively smaller, or whole.** A delta is only sent at ≤60% of the frame.
235
294
  Below that it wins even after deflate; above it, deflate on the whole frame
236
- does as well and the terminal does less work.
295
+ does as well and the terminal does less work. And a frame over 64 KB is not
296
+ compared at all: the encode's cost follows the size of the frames, not of
297
+ the change, on the thread every session shares — about 7 ms at 64 KB, a
298
+ second at 2.7 MB — so past that length, on either side of the change, the
299
+ canvas is sent whole before anything is spent on finding out.
237
300
  3. **Checksummed, always.** Every delta carries a hash of the frame it should
238
301
  rebuild. A terminal that lands anywhere else discards the result and sends
239
302
  `resync` — the failure this layer must not have is a screen that is silently
@@ -304,7 +367,10 @@ the shell for the life of the process.
304
367
  The shell is built from the manifest: canvases and fragments are data; a canvas's
305
368
  `initial` may be a candidate list, and the first action the principal holds
306
369
  mounts — so login is the anonymous principal's application (the charter's
307
- `public` grant) by derivation, not a special case. `inputs(session)` and
370
+ `public` grant) by derivation, not a special case. The role name is fixed and
371
+ the charter has to define it, as `public: []` if it grants nothing: boot does
372
+ not check that it is there, and a request that resolves to a missing `public`
373
+ fails. `inputs(session)` and
308
374
  `seeds(session)` are the app's per-principal boot hooks — boot data and boot
309
375
  instances. Endpoint calls ride the server's own HTTP surfaces
310
376
  with the session's token — the server shell is just another principal-bound
@@ -383,11 +449,11 @@ Six things had to be true, and each is a small, separate decision:
383
449
  `initializing`" is the shell saying its first screen is complete — a signal
384
450
  that was always there. The wait is bounded (300 ms by default): a document
385
451
  must not hang on a slow integration, and a skeleton is a legitimate screen.
386
- - **Who is asking comes off a cookie**, because a page request carries nothing
387
- else. The wire keeps a copy of the session token there (`browserEnv`'s
388
- `cookie`), and it is read for exactly one thing — choosing whose screen to
389
- draw. Every other surface still wants the token itself, so the copy opens no
390
- door: a cross-site request that carried it could draw a page it cannot read.
452
+ - **Who is asking comes off the browser's session cookie**, because a page
453
+ request carries nothing else (*Where a browser keeps its session*). It is
454
+ read here and never written: the upgrade is where it is set and taken back,
455
+ and one writer cannot disagree with itself. A cross-site request that carried
456
+ it could draw a page it cannot read.
391
457
  - **An anonymous page and its socket are two shells that must name their
392
458
  instances alike.** A principal's page is drawn from their durable shell and
393
459
  the socket attaches to that same shell — same ids, nothing to arrange. Nobody
@@ -593,11 +659,16 @@ On the record, so nothing reads as finished that isn't:
593
659
  drawn for nobody (a file, on a static host) connects, and is served a page
594
660
  shell for as long as it stays — even when that page turns out not to be live
595
661
  for them either. Closing such a connection once its frames are sent is unbuilt.
596
- - **A stricter cookie.** The cookie is a copy of the token, readable by the
597
- page's script like the token itself. An `HttpOnly` one — with the socket
598
- reading it at the upgrade, the token out of the URL and out of script — needs
599
- login to finish over HTTP (a socket message cannot set a cookie) and an Origin
600
- check on the upgrade that does not exist today.
662
+ - **A seal no script can supply, in every browser.** The seal is given by the
663
+ answer to a browser's first upgrade, after the page's script has started; a
664
+ script already running then could set one of its own first, and open the
665
+ sign-in that follows. Its `__Http-` name is what stops that — a browser lets
666
+ only an HTTP answer set it — and a browser that does not know the prefix
667
+ does not stop it. Nor does the name stop a *server* on a sibling subdomain
668
+ from setting one; with a script in the page as well, that is the same
669
+ opening. `__Host-Http-` would close it, and would put the seal on every page
670
+ request, ending the sharing of pages drawn for nobody. Over plain http there
671
+ is no such name, and nothing on the way is private either.
601
672
 
602
673
  ## Boundaries
603
674