@mostra/runtime 0.0.0-stage → 0.2.0
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.
- package/LICENSE +202 -0
- package/README.md +39 -2
- package/dist/bin.d.ts +1 -0
- package/dist/bin.js +236 -0
- package/dist/bin.js.map +1 -0
- package/dist/builder/child/main.d.ts +1 -0
- package/dist/builder/child/main.js +1408 -0
- package/dist/builder/child/main.js.map +1 -0
- package/dist/child-xrHmytks.js +49 -0
- package/dist/child-xrHmytks.js.map +1 -0
- package/dist/deps/child/install.d.ts +1 -0
- package/dist/deps/child/install.js +33 -0
- package/dist/deps/child/install.js.map +1 -0
- package/dist/index.d.ts +221 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/instance-CzBkUyHu.js +15920 -0
- package/dist/instance-CzBkUyHu.js.map +1 -0
- package/dist/types-NjNy7gXX.js +57 -0
- package/dist/types-NjNy7gXX.js.map +1 -0
- package/package.json +87 -3
- package/src/actions/index.ts +622 -0
- package/src/addressing/index.ts +281 -0
- package/src/bin.ts +240 -0
- package/src/builder/child/dev.ts +383 -0
- package/src/builder/child/fields.ts +363 -0
- package/src/builder/child/main.ts +47 -0
- package/src/builder/child/plugins.ts +195 -0
- package/src/builder/child/scan.ts +459 -0
- package/src/builder/child/spa.ts +348 -0
- package/src/builder/coverage.ts +72 -0
- package/src/builder/index.ts +406 -0
- package/src/builder/types.ts +180 -0
- package/src/deps/child/install.ts +30 -0
- package/src/deps/index.ts +918 -0
- package/src/deps/installer.ts +321 -0
- package/src/deps/lock.ts +82 -0
- package/src/deps/scan.ts +266 -0
- package/src/deps/specifier.ts +64 -0
- package/src/deps/warm.ts +57 -0
- package/src/dev/index.ts +518 -0
- package/src/faults.ts +65 -0
- package/src/gate.ts +55 -0
- package/src/gateway/actions.ts +268 -0
- package/src/gateway/browser.ts +650 -0
- package/src/gateway/capabilities.ts +760 -0
- package/src/gateway/controls.ts +91 -0
- package/src/gateway/dev.ts +119 -0
- package/src/gateway/http.ts +229 -0
- package/src/gateway/identity.ts +101 -0
- package/src/gateway/index.ts +1299 -0
- package/src/gateway/integrity.ts +117 -0
- package/src/gateway/listener.ts +217 -0
- package/src/gateway/routes.ts +197 -0
- package/src/gateway/serve.ts +138 -0
- package/src/gc/index.ts +451 -0
- package/src/home/acquire.ts +276 -0
- package/src/home/index.ts +16 -0
- package/src/home/paths.ts +192 -0
- package/src/home/platform.ts +34 -0
- package/src/home/record.ts +76 -0
- package/src/home/settings.ts +113 -0
- package/src/index.ts +30 -0
- package/src/instance/index.ts +979 -0
- package/src/interaction/ephemeral.ts +300 -0
- package/src/interaction/events.ts +355 -0
- package/src/interaction/fields.ts +392 -0
- package/src/interaction/index.ts +1013 -0
- package/src/interaction/outbox.ts +493 -0
- package/src/interaction/policy.ts +26 -0
- package/src/interaction/results.ts +341 -0
- package/src/interaction/runs.ts +313 -0
- package/src/interaction/signals.ts +120 -0
- package/src/interaction/submissions.ts +585 -0
- package/src/interaction/subscriptions.ts +258 -0
- package/src/interaction/viewers.ts +187 -0
- package/src/interaction/wait.ts +201 -0
- package/src/ledger/index.ts +442 -0
- package/src/ledger/migrations.ts +596 -0
- package/src/ledger/requests.ts +105 -0
- package/src/ledger/types.ts +28 -0
- package/src/live/index.ts +573 -0
- package/src/log.ts +316 -0
- package/src/processes/child.ts +67 -0
- package/src/processes/environment.ts +64 -0
- package/src/processes/identity.ts +191 -0
- package/src/processes/index.ts +19 -0
- package/src/processes/manager.ts +543 -0
- package/src/protocol-server/client.ts +94 -0
- package/src/protocol-server/index.ts +91 -0
- package/src/protocol-server/server.ts +518 -0
- package/src/protocol-server/streams.ts +81 -0
- package/src/publish/checks.ts +92 -0
- package/src/publish/digest.ts +87 -0
- package/src/publish/index.ts +23 -0
- package/src/publish/manifest.ts +409 -0
- package/src/publish/methods.ts +96 -0
- package/src/publish/publisher.ts +913 -0
- package/src/publish/source.ts +272 -0
- package/src/publish/tar.ts +110 -0
- package/src/registry/index.ts +481 -0
- package/src/registry/store.ts +136 -0
- package/src/secrets/index.ts +223 -0
- package/src/service/idle.ts +64 -0
- package/src/service/index.ts +3 -0
- package/src/service/unit.ts +250 -0
- package/src/verify/fields.ts +125 -0
- package/src/verify/index.ts +913 -0
- package/src/verify/regression.ts +157 -0
- package/src/verify/runner.ts +230 -0
- package/src/verify/sandbox.ts +407 -0
- package/src/verify/typecheck.ts +371 -0
- package/src/workers/index.ts +17 -0
- package/src/workers/launcher.ts +260 -0
- package/src/workers/pool.ts +708 -0
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Integrity of served versions (FAILURE_MODEL §3: reads verify content). Before a version's
|
|
3
|
+
* files are served, its stored tree is checked once against the output digest its manifest
|
|
4
|
+
* records, and the change time of every file is remembered. A file served later whose change time
|
|
5
|
+
* differs (any write or `chmod` changes it) makes the whole version checked again, so a version
|
|
6
|
+
* altered while the gateway runs is refused from the next request on, not after a restart.
|
|
7
|
+
*/
|
|
8
|
+
import { readdir, realpath, stat } from "node:fs/promises";
|
|
9
|
+
import { join } from "node:path";
|
|
10
|
+
import type { Log } from "../log.ts";
|
|
11
|
+
import type { FoundFile } from "./serve.ts";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* How long a damaged version's verdict is kept before its files are hashed again, unless its
|
|
15
|
+
* directory was replaced (a republish rebuilds it in place, D98 and WP-03).
|
|
16
|
+
*/
|
|
17
|
+
const DAMAGE_TTL_MS = 10_000;
|
|
18
|
+
|
|
19
|
+
/** What the integrity checks need to know about versions. */
|
|
20
|
+
export interface VersionStore {
|
|
21
|
+
/** The directory of a published version (`versions/<id>`). */
|
|
22
|
+
versionDir(versionId: string): string;
|
|
23
|
+
/** What is wrong with a version's stored files, or `undefined` when they match their digest. */
|
|
24
|
+
damage(versionId: string): Promise<string | undefined>;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The checks of one gateway. */
|
|
28
|
+
export interface VersionIntegrity {
|
|
29
|
+
/** The version's damage, or `undefined` when its stored files match their digest. */
|
|
30
|
+
check(versionId: string): Promise<string | undefined>;
|
|
31
|
+
/**
|
|
32
|
+
* Whether `file`, found in the version's `client/` tree, may be served: `undefined` when it may,
|
|
33
|
+
* else what is wrong. A file whose change time differs from the last check checks the version
|
|
34
|
+
* again.
|
|
35
|
+
*/
|
|
36
|
+
serve(versionId: string, file: FoundFile): Promise<string | undefined>;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The change time of every file under `root`, by real path. */
|
|
40
|
+
async function changeTimes(root: string): Promise<Map<string, number>> {
|
|
41
|
+
const times = new Map<string, number>();
|
|
42
|
+
const real = await realpath(root);
|
|
43
|
+
for (const entry of await readdir(real, { recursive: true, withFileTypes: true })) {
|
|
44
|
+
if (entry.isDirectory()) continue;
|
|
45
|
+
const path = await realpath(join(entry.parentPath, entry.name));
|
|
46
|
+
const info = await stat(path);
|
|
47
|
+
if (info.isFile()) times.set(path, info.ctimeMs);
|
|
48
|
+
}
|
|
49
|
+
return times;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Creates the integrity checks of one gateway. */
|
|
53
|
+
export function versionIntegrity(store: VersionStore, log: Log): VersionIntegrity {
|
|
54
|
+
const verified = new Map<string, Map<string, number>>();
|
|
55
|
+
const damaged = new Map<
|
|
56
|
+
string,
|
|
57
|
+
{ readonly damage: string; readonly until: number; readonly dir: string }
|
|
58
|
+
>();
|
|
59
|
+
/** The identity of a version's directory: a rebuild puts a new one in place. */
|
|
60
|
+
const dirIdentity = async (versionId: string): Promise<string> => {
|
|
61
|
+
try {
|
|
62
|
+
const info = await stat(store.versionDir(versionId));
|
|
63
|
+
return `${info.ino}:${info.ctimeMs}`;
|
|
64
|
+
} catch {
|
|
65
|
+
return "missing";
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
const running = new Map<string, Promise<string | undefined>>();
|
|
69
|
+
|
|
70
|
+
const check = (versionId: string): Promise<string | undefined> => {
|
|
71
|
+
if (verified.has(versionId)) return Promise.resolve(undefined);
|
|
72
|
+
const pending = running.get(versionId);
|
|
73
|
+
if (pending) return pending;
|
|
74
|
+
const started = (async () => {
|
|
75
|
+
const dir = await dirIdentity(versionId);
|
|
76
|
+
const known = damaged.get(versionId);
|
|
77
|
+
if (known && known.until > Date.now() && known.dir === dir) return known.damage;
|
|
78
|
+
// Change times first: a write between them and the hashing is caught by the hashing, and
|
|
79
|
+
// a write after it by the change time.
|
|
80
|
+
let times: Map<string, number>;
|
|
81
|
+
try {
|
|
82
|
+
times = await changeTimes(join(store.versionDir(versionId), "client"));
|
|
83
|
+
} catch (error) {
|
|
84
|
+
times = new Map();
|
|
85
|
+
log.warn("gateway.version_unreadable", {
|
|
86
|
+
versionId,
|
|
87
|
+
code: (error as NodeJS.ErrnoException).code,
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
const damage = await store.damage(versionId);
|
|
91
|
+
if (damage !== undefined) {
|
|
92
|
+
log.error("gateway.version_damaged", { versionId, damage });
|
|
93
|
+
damaged.set(versionId, { damage, until: Date.now() + DAMAGE_TTL_MS, dir });
|
|
94
|
+
return damage;
|
|
95
|
+
}
|
|
96
|
+
damaged.delete(versionId);
|
|
97
|
+
verified.set(versionId, times);
|
|
98
|
+
return undefined;
|
|
99
|
+
})().finally(() => running.delete(versionId));
|
|
100
|
+
running.set(versionId, started);
|
|
101
|
+
return started;
|
|
102
|
+
};
|
|
103
|
+
|
|
104
|
+
return {
|
|
105
|
+
check,
|
|
106
|
+
async serve(versionId, file) {
|
|
107
|
+
if (verified.get(versionId)?.get(file.path) === file.ctimeMs) return undefined;
|
|
108
|
+
// First sight of this file, or it changed since the check: check the version again.
|
|
109
|
+
verified.delete(versionId);
|
|
110
|
+
const damage = await check(versionId);
|
|
111
|
+
if (damage !== undefined) return damage;
|
|
112
|
+
return verified.get(versionId)?.get(file.path) === file.ctimeMs
|
|
113
|
+
? undefined
|
|
114
|
+
: "a file changed while the version was checked";
|
|
115
|
+
},
|
|
116
|
+
};
|
|
117
|
+
}
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One gateway listener: a Node HTTP server on a leased port with a Hono app behind it. Every
|
|
3
|
+
* request's envelope (exact `Host`, plain path, single headers) is checked before routing,
|
|
4
|
+
* methods other than GET, HEAD and POST are refused, upgrades are refused after their `Origin`
|
|
5
|
+
* check unless the listener takes them (a dev sandbox's HMR WebSocket, D140 item 12; terminals add
|
|
6
|
+
* theirs, WP-22), and every response leaves with the base headers.
|
|
7
|
+
*/
|
|
8
|
+
import { createServer, type IncomingMessage, type Server } from "node:http";
|
|
9
|
+
import type { Duplex } from "node:stream";
|
|
10
|
+
import { getRequestListener } from "@hono/node-server";
|
|
11
|
+
import {
|
|
12
|
+
checkRequest,
|
|
13
|
+
createDiagnostic,
|
|
14
|
+
type Refusal,
|
|
15
|
+
type RequestPolicy,
|
|
16
|
+
refusal,
|
|
17
|
+
} from "@mostra/protocol";
|
|
18
|
+
import { Hono } from "hono";
|
|
19
|
+
import type { Log } from "../log.ts";
|
|
20
|
+
import { BASE_HEADERS, type HttpEnv, headerPairs, refusalResponse } from "./http.ts";
|
|
21
|
+
import { refuse } from "./routes.ts";
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Node's limit on request headers for gateway listeners. Every port of the loopback host shares one
|
|
25
|
+
* cookie jar, and any artifact's page can fill it; Chromium, Firefox and WebKit keep about 410 KB
|
|
26
|
+
* per host (100 cookies of 4 KiB), so a jar filled to the brim fits with room to spare
|
|
27
|
+
* (VERIFIED_FACTS, WP-05). A request past this limit is answered with a page that clears the
|
|
28
|
+
* host's cookies (D98 item 9).
|
|
29
|
+
*/
|
|
30
|
+
export const MAX_HEADER_SIZE: number = 1024 * 1024;
|
|
31
|
+
|
|
32
|
+
/** A listener: its server and its Hono app. */
|
|
33
|
+
export interface Listener {
|
|
34
|
+
readonly server: Server;
|
|
35
|
+
readonly app: Hono<HttpEnv>;
|
|
36
|
+
/** Stops accepting connections and closes the open ones. */
|
|
37
|
+
close(): Promise<void>;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Writes a refusal straight to a socket, for upgrades and envelope failures before Hono. */
|
|
41
|
+
function writeRaw(
|
|
42
|
+
socket: Duplex,
|
|
43
|
+
refused: Refusal,
|
|
44
|
+
extra: { readonly html?: string; readonly headers?: readonly string[] } = {},
|
|
45
|
+
): void {
|
|
46
|
+
const body = extra.html ?? JSON.stringify(refused.diagnostic);
|
|
47
|
+
const headers = [
|
|
48
|
+
`HTTP/1.1 ${refused.status} Refused`,
|
|
49
|
+
"connection: close",
|
|
50
|
+
extra.html !== undefined
|
|
51
|
+
? "content-type: text/html; charset=utf-8"
|
|
52
|
+
: "content-type: application/json; charset=utf-8",
|
|
53
|
+
`content-length: ${Buffer.byteLength(body)}`,
|
|
54
|
+
"cache-control: no-store",
|
|
55
|
+
...Object.entries(BASE_HEADERS).map(([name, value]) => `${name}: ${value}`),
|
|
56
|
+
...(extra.headers ?? []),
|
|
57
|
+
];
|
|
58
|
+
socket.end(`${headers.join("\r\n")}\r\n\r\n${body}`);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* The answer to headers past {@link MAX_HEADER_SIZE}: a page that says what happened and clears
|
|
63
|
+
* the host's cookies, which is what made them that large (D98 item 9). `Clear-Site-Data` acts on
|
|
64
|
+
* the host, so it empties the jar every port shares; Mostra's sessions return when a link is
|
|
65
|
+
* opened again. The page runs nothing and can't be framed.
|
|
66
|
+
*/
|
|
67
|
+
function headersTooLarge(socket: Duplex): void {
|
|
68
|
+
const refused = refusal(
|
|
69
|
+
"MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
|
|
70
|
+
"This browser sent more cookies than any page here sets.",
|
|
71
|
+
);
|
|
72
|
+
const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Mostra</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:flex;flex-direction:column;justify-content:center;align-items:center;gap:.25rem;padding:2rem;text-align:center;color-scheme:light dark}h1{font-size:1.25rem;margin:0}p{margin:0;opacity:.8}code{opacity:.5;font-size:.75rem;margin-top:1rem}</style></head><body><h1>This browser sent more cookies than Mostra accepts</h1><p>A page on this machine filled them. They have been cleared: open your link again.</p><code>MOSTRA_HYGIENE_HEADERS_TOO_LARGE</code></body></html>`;
|
|
73
|
+
writeRaw(socket, refused, {
|
|
74
|
+
html,
|
|
75
|
+
headers: [
|
|
76
|
+
'clear-site-data: "cookies"',
|
|
77
|
+
"content-security-policy: default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
|
|
78
|
+
],
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Creates a listener whose routes `configure` mounts; the server isn't bound yet. */
|
|
83
|
+
export function createListener(options: {
|
|
84
|
+
readonly policy: () => RequestPolicy;
|
|
85
|
+
readonly log: Log;
|
|
86
|
+
readonly frameAncestors: () => string;
|
|
87
|
+
readonly configure: (app: Hono<HttpEnv>) => void;
|
|
88
|
+
/**
|
|
89
|
+
* Takes an upgrade whose Host, target and Origin passed the checks (a dev sandbox's HMR
|
|
90
|
+
* WebSocket, D140 item 12), or answers why it is refused. Without it every upgrade is refused.
|
|
91
|
+
*/
|
|
92
|
+
readonly upgrade?: (
|
|
93
|
+
incoming: IncomingMessage,
|
|
94
|
+
socket: Duplex,
|
|
95
|
+
head: Buffer,
|
|
96
|
+
) => Refusal | undefined;
|
|
97
|
+
}): Listener {
|
|
98
|
+
const app = new Hono<HttpEnv>();
|
|
99
|
+
options.configure(app);
|
|
100
|
+
app.notFound((c) =>
|
|
101
|
+
refuse(options, refusal("MOSTRA_HYGIENE_NOT_SERVED", "Nothing is served at this path."), {
|
|
102
|
+
method: c.req.method,
|
|
103
|
+
path: new URL(c.req.url).pathname,
|
|
104
|
+
document: false,
|
|
105
|
+
}),
|
|
106
|
+
);
|
|
107
|
+
app.onError((error, c) => {
|
|
108
|
+
options.log.error("gateway.handler_failed", { error, path: new URL(c.req.url).pathname });
|
|
109
|
+
return refusalResponse(
|
|
110
|
+
{
|
|
111
|
+
status: 500,
|
|
112
|
+
diagnostic: createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", {
|
|
113
|
+
message: "The gateway failed to answer this request.",
|
|
114
|
+
}),
|
|
115
|
+
},
|
|
116
|
+
{ document: false, method: c.req.method },
|
|
117
|
+
);
|
|
118
|
+
});
|
|
119
|
+
const listener = getRequestListener(app.fetch, { overrideGlobalObjects: false });
|
|
120
|
+
|
|
121
|
+
const server = createServer({ maxHeaderSize: MAX_HEADER_SIZE }, (incoming, outgoing) => {
|
|
122
|
+
const policy = options.policy();
|
|
123
|
+
const method = incoming.method ?? "";
|
|
124
|
+
const envelope =
|
|
125
|
+
checkRequest(policy, {
|
|
126
|
+
method,
|
|
127
|
+
target: incoming.url ?? "",
|
|
128
|
+
headers: headerPairs(incoming),
|
|
129
|
+
}) ??
|
|
130
|
+
(method === "GET" || method === "HEAD" || method === "POST"
|
|
131
|
+
? undefined
|
|
132
|
+
: method === "OPTIONS"
|
|
133
|
+
? // A preflight never gets an Access-Control-* answer: no other origin may call in.
|
|
134
|
+
refusal(
|
|
135
|
+
"MOSTRA_HYGIENE_ORIGIN_REFUSED",
|
|
136
|
+
"This gateway answers no cross-origin requests.",
|
|
137
|
+
)
|
|
138
|
+
: refusal(
|
|
139
|
+
"MOSTRA_HYGIENE_NOT_SERVED",
|
|
140
|
+
`This gateway doesn't serve ${method} requests.`,
|
|
141
|
+
405,
|
|
142
|
+
));
|
|
143
|
+
if (envelope) {
|
|
144
|
+
options.log.warn("gateway.refused", {
|
|
145
|
+
code: envelope.diagnostic.code,
|
|
146
|
+
status: envelope.status,
|
|
147
|
+
method,
|
|
148
|
+
origin: policy.origin,
|
|
149
|
+
});
|
|
150
|
+
const response = refusalResponse(envelope, { document: false, method });
|
|
151
|
+
// A request refused before routing ends its connection: nothing else is read from it.
|
|
152
|
+
outgoing.shouldKeepAlive = false;
|
|
153
|
+
outgoing.writeHead(response.status, {
|
|
154
|
+
...Object.fromEntries(response.headers),
|
|
155
|
+
connection: "close",
|
|
156
|
+
});
|
|
157
|
+
void response.text().then((text) => outgoing.end(text));
|
|
158
|
+
return;
|
|
159
|
+
}
|
|
160
|
+
void listener(incoming, outgoing);
|
|
161
|
+
});
|
|
162
|
+
// A client that sends something Node can't parse gets a 400 and its connection closed.
|
|
163
|
+
server.on("clientError", (error: NodeJS.ErrnoException, socket) => {
|
|
164
|
+
if (!socket.writable) {
|
|
165
|
+
socket.destroy();
|
|
166
|
+
return;
|
|
167
|
+
}
|
|
168
|
+
if (error.code === "HPE_HEADER_OVERFLOW") {
|
|
169
|
+
options.log.warn("gateway.refused", {
|
|
170
|
+
code: "MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
|
|
171
|
+
status: 431,
|
|
172
|
+
origin: options.policy().origin,
|
|
173
|
+
});
|
|
174
|
+
headersTooLarge(socket);
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
writeRaw(
|
|
178
|
+
socket,
|
|
179
|
+
refusal("MOSTRA_HYGIENE_REQUEST_MALFORMED", "The request couldn't be parsed."),
|
|
180
|
+
);
|
|
181
|
+
});
|
|
182
|
+
server.on("upgrade", (incoming: IncomingMessage, socket: Duplex, head: Buffer) => {
|
|
183
|
+
const policy = options.policy();
|
|
184
|
+
const checked = checkRequest(policy, {
|
|
185
|
+
method: incoming.method ?? "",
|
|
186
|
+
target: incoming.url ?? "",
|
|
187
|
+
headers: headerPairs(incoming),
|
|
188
|
+
intent: "upgrade",
|
|
189
|
+
});
|
|
190
|
+
const refused =
|
|
191
|
+
checked ??
|
|
192
|
+
(options.upgrade
|
|
193
|
+
? options.upgrade(incoming, socket, head)
|
|
194
|
+
: refusal("MOSTRA_HYGIENE_NOT_SERVED", "This gateway serves no WebSocket here."));
|
|
195
|
+
if (refused === undefined) return;
|
|
196
|
+
options.log.warn("gateway.refused", {
|
|
197
|
+
code: refused.diagnostic.code,
|
|
198
|
+
status: refused.status,
|
|
199
|
+
method: "UPGRADE",
|
|
200
|
+
origin: policy.origin,
|
|
201
|
+
});
|
|
202
|
+
writeRaw(socket, refused);
|
|
203
|
+
});
|
|
204
|
+
server.headersTimeout = 30_000;
|
|
205
|
+
server.requestTimeout = 120_000;
|
|
206
|
+
|
|
207
|
+
return {
|
|
208
|
+
server,
|
|
209
|
+
app,
|
|
210
|
+
close: () =>
|
|
211
|
+
new Promise((resolve) => {
|
|
212
|
+
if (!server.listening) return resolve();
|
|
213
|
+
server.close(() => resolve());
|
|
214
|
+
server.closeAllConnections();
|
|
215
|
+
}),
|
|
216
|
+
};
|
|
217
|
+
}
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Route declarations (D96): every gateway endpoint declares what it is for (its intent), whether
|
|
3
|
+
* it needs a session, whether it takes a capability token or ticket, and the scope it needs. One
|
|
4
|
+
* runner applies the checks in one order for all of them, so an endpoint a later package adds is
|
|
5
|
+
* behind the same checks by construction:
|
|
6
|
+
*
|
|
7
|
+
* 1. the `Origin` and content type its intent needs (`checkRequest`; the envelope was checked
|
|
8
|
+
* before routing);
|
|
9
|
+
* 2. the rate limit, on token paths;
|
|
10
|
+
* 3. the session, bound to this origin, with a live token (401, 410);
|
|
11
|
+
* 4. the session's CSRF token, on mutations;
|
|
12
|
+
* 5. the scope.
|
|
13
|
+
*
|
|
14
|
+
* A route declared without a handler is a browser-protocol path a later package serves
|
|
15
|
+
* (INTERFACES §4): it answers 501 once every check has passed.
|
|
16
|
+
*/
|
|
17
|
+
import {
|
|
18
|
+
type CapabilityScope,
|
|
19
|
+
checkRequest,
|
|
20
|
+
type Refusal,
|
|
21
|
+
type RequestIntent,
|
|
22
|
+
type RequestPolicy,
|
|
23
|
+
refusal,
|
|
24
|
+
scopeAllows,
|
|
25
|
+
} from "@mostra/protocol";
|
|
26
|
+
import type { Context, Hono } from "hono";
|
|
27
|
+
import type { Log } from "../log.ts";
|
|
28
|
+
import type { Capabilities, ResolvedSession } from "./capabilities.ts";
|
|
29
|
+
import {
|
|
30
|
+
cookieValues,
|
|
31
|
+
type HttpEnv,
|
|
32
|
+
headerPairs,
|
|
33
|
+
isRefusal,
|
|
34
|
+
refusalResponse,
|
|
35
|
+
wantsDocument,
|
|
36
|
+
} from "./http.ts";
|
|
37
|
+
|
|
38
|
+
/** What a route needs before its handler runs. */
|
|
39
|
+
export interface RouteSpec {
|
|
40
|
+
readonly method: "GET" | "POST";
|
|
41
|
+
/** A Hono path pattern. */
|
|
42
|
+
readonly path: string;
|
|
43
|
+
readonly intent: RequestIntent;
|
|
44
|
+
/** `session`: a session of this origin, for the listener's artifact, is required. */
|
|
45
|
+
readonly auth: "none" | "session";
|
|
46
|
+
/** The route takes a capability token or a frame ticket: failures are rate-limited (D97 item 8). */
|
|
47
|
+
readonly tokenPath?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* The scope the request needs beyond `view`, from its path parameters. `any-action` means some
|
|
50
|
+
* action scope; the handler checks the exact function (D96).
|
|
51
|
+
*/
|
|
52
|
+
readonly scope?: (params: Readonly<Record<string, string>>) => CapabilityScope | "any-action";
|
|
53
|
+
/** Serves the request. Absent: declared for a later package, answered with 501. */
|
|
54
|
+
readonly handler?: (context: RouteContext) => Response | Promise<Response>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** What a handler receives. */
|
|
58
|
+
export interface RouteContext {
|
|
59
|
+
readonly request: Request;
|
|
60
|
+
readonly params: Readonly<Record<string, string>>;
|
|
61
|
+
/** The artifact this request is for; always set on `auth: "session"` routes. */
|
|
62
|
+
readonly artifactId: string | undefined;
|
|
63
|
+
/** The session, for `auth: "session"` routes. */
|
|
64
|
+
readonly session?: ResolvedSession;
|
|
65
|
+
/** Whether the client is navigating (answer with HTML rather than JSON). */
|
|
66
|
+
readonly document: boolean;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** What a listener contributes to every route's checks. */
|
|
70
|
+
export interface ListenerChecks {
|
|
71
|
+
/** The listener's origin and Host allowlist, known once it is bound. */
|
|
72
|
+
readonly policy: () => RequestPolicy;
|
|
73
|
+
readonly capabilities: Capabilities;
|
|
74
|
+
readonly log: Log;
|
|
75
|
+
/** The session cookie's name on this listener: `mostra-<port>` (D98 item 1). */
|
|
76
|
+
readonly cookieName: () => string;
|
|
77
|
+
/** Who may frame this listener's refusal pages: `'none'` on the shell, the shell's origin on artifacts. */
|
|
78
|
+
readonly frameAncestors: () => string;
|
|
79
|
+
/** The artifact a request is for: fixed on an artifact's listener, from the path on the shell. */
|
|
80
|
+
readonly artifactOf: (params: Readonly<Record<string, string>>) => string | undefined;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** Logs a refusal without any of the request's capability material, and answers it. */
|
|
84
|
+
export function refuse(
|
|
85
|
+
checks: Pick<ListenerChecks, "log" | "policy" | "frameAncestors">,
|
|
86
|
+
refused: Refusal & { readonly retryAfter?: number },
|
|
87
|
+
request: { readonly method: string; readonly path: string; readonly document: boolean },
|
|
88
|
+
): Response {
|
|
89
|
+
checks.log.warn("gateway.refused", {
|
|
90
|
+
code: refused.diagnostic.code,
|
|
91
|
+
status: refused.status,
|
|
92
|
+
method: request.method,
|
|
93
|
+
// The path never carries a token (links keep it in the fragment); a ticket query is redacted
|
|
94
|
+
// by the log's redactor all the same.
|
|
95
|
+
path: request.path,
|
|
96
|
+
origin: checks.policy().origin,
|
|
97
|
+
});
|
|
98
|
+
return refusalResponse(refused, {
|
|
99
|
+
document: request.document,
|
|
100
|
+
method: request.method,
|
|
101
|
+
frameAncestors: checks.frameAncestors(),
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
const NOT_SERVED_YET = (method: string, path: string): Refusal =>
|
|
106
|
+
refusal(
|
|
107
|
+
"MOSTRA_HYGIENE_NOT_SERVED",
|
|
108
|
+
`This Mostra release doesn't serve ${method} ${path} yet.`,
|
|
109
|
+
501,
|
|
110
|
+
);
|
|
111
|
+
|
|
112
|
+
/** Mounts routes on a listener's Hono app behind the common checks. */
|
|
113
|
+
export function mount(
|
|
114
|
+
app: Hono<HttpEnv>,
|
|
115
|
+
checks: ListenerChecks,
|
|
116
|
+
routes: readonly RouteSpec[],
|
|
117
|
+
): void {
|
|
118
|
+
for (const route of routes) {
|
|
119
|
+
const handle = async (c: Context<HttpEnv>): Promise<Response> => {
|
|
120
|
+
const request = c.req.raw;
|
|
121
|
+
const url = new URL(request.url);
|
|
122
|
+
const document = wantsDocument(request.headers);
|
|
123
|
+
const meta = { method: request.method, path: url.pathname, document };
|
|
124
|
+
const params = c.req.param() as Record<string, string>;
|
|
125
|
+
const incoming = c.env.incoming;
|
|
126
|
+
const facts = {
|
|
127
|
+
method: request.method,
|
|
128
|
+
target: incoming.url ?? url.pathname,
|
|
129
|
+
headers: headerPairs(incoming),
|
|
130
|
+
};
|
|
131
|
+
// 1. Origin and content type; CSRF comes once the session is known.
|
|
132
|
+
const policy = checks.policy();
|
|
133
|
+
const early = checkRequest(policy, {
|
|
134
|
+
...facts,
|
|
135
|
+
intent: route.intent === "mutation" ? "exchange" : route.intent,
|
|
136
|
+
});
|
|
137
|
+
if (early) return refuse(checks, early, meta);
|
|
138
|
+
const artifactId = checks.artifactOf(params);
|
|
139
|
+
if (route.auth === "session" && artifactId === undefined) {
|
|
140
|
+
return refuse(
|
|
141
|
+
checks,
|
|
142
|
+
refusal("MOSTRA_HYGIENE_NOT_SERVED", "No artifact is served at this path."),
|
|
143
|
+
meta,
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
// 2. The rate limit holds every attempt while too many failed.
|
|
147
|
+
if (route.tokenPath && artifactId !== undefined) {
|
|
148
|
+
const limited = checks.capabilities.limited(artifactId);
|
|
149
|
+
if (limited) return refuse(checks, limited, meta);
|
|
150
|
+
}
|
|
151
|
+
// 3. The session.
|
|
152
|
+
let session: ResolvedSession | undefined;
|
|
153
|
+
if (route.auth === "session" && artifactId !== undefined) {
|
|
154
|
+
const resolved = checks.capabilities.session(
|
|
155
|
+
cookieValues(request.headers.get("cookie"), checks.cookieName()),
|
|
156
|
+
policy.origin,
|
|
157
|
+
artifactId,
|
|
158
|
+
);
|
|
159
|
+
if (isRefusal(resolved)) return refuse(checks, resolved, meta);
|
|
160
|
+
session = resolved;
|
|
161
|
+
// 4. The CSRF token of this session.
|
|
162
|
+
if (route.intent === "mutation") {
|
|
163
|
+
const csrf = checkRequest(policy, { ...facts, intent: "mutation", csrf: session.csrf });
|
|
164
|
+
if (csrf) return refuse(checks, csrf, meta);
|
|
165
|
+
}
|
|
166
|
+
// 5. The scope.
|
|
167
|
+
const needed = route.scope?.(params);
|
|
168
|
+
const allowed =
|
|
169
|
+
needed === undefined
|
|
170
|
+
? true
|
|
171
|
+
: needed === "any-action"
|
|
172
|
+
? session.grant.scopes.some((scope) => scope.startsWith("action:"))
|
|
173
|
+
: scopeAllows(session.grant.scopes, needed);
|
|
174
|
+
if (!allowed) {
|
|
175
|
+
return refuse(
|
|
176
|
+
checks,
|
|
177
|
+
refusal(
|
|
178
|
+
"MOSTRA_HYGIENE_SCOPE_DENIED",
|
|
179
|
+
`This link doesn't carry the ${needed === "any-action" ? "action" : needed} scope.`,
|
|
180
|
+
),
|
|
181
|
+
meta,
|
|
182
|
+
);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
if (!route.handler) return refuse(checks, NOT_SERVED_YET(request.method, url.pathname), meta);
|
|
186
|
+
return route.handler({
|
|
187
|
+
request,
|
|
188
|
+
params,
|
|
189
|
+
artifactId,
|
|
190
|
+
...(session ? { session } : {}),
|
|
191
|
+
document,
|
|
192
|
+
});
|
|
193
|
+
};
|
|
194
|
+
if (route.method === "GET") app.get(route.path, handle);
|
|
195
|
+
else app.post(route.path, handle);
|
|
196
|
+
}
|
|
197
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Static files (RT-05, VR-03): the gateway serves a published version's client build and the
|
|
3
|
+
* shell's built page straight from disk, with no process. A file is found only under its root,
|
|
4
|
+
* through a path the hygiene checks already proved plain, and only when its real path stays inside
|
|
5
|
+
* the root. Responses support `HEAD`, a single byte range (media seeking needs it) and conditional
|
|
6
|
+
* requests.
|
|
7
|
+
*/
|
|
8
|
+
import { createReadStream } from "node:fs";
|
|
9
|
+
import { realpath, stat } from "node:fs/promises";
|
|
10
|
+
import { extname, join, sep } from "node:path";
|
|
11
|
+
import { Readable } from "node:stream";
|
|
12
|
+
import { BASE_HEADERS } from "./http.ts";
|
|
13
|
+
|
|
14
|
+
const TYPES: Readonly<Record<string, string>> = {
|
|
15
|
+
".html": "text/html; charset=utf-8",
|
|
16
|
+
".js": "text/javascript; charset=utf-8",
|
|
17
|
+
".mjs": "text/javascript; charset=utf-8",
|
|
18
|
+
".css": "text/css; charset=utf-8",
|
|
19
|
+
".json": "application/json; charset=utf-8",
|
|
20
|
+
".map": "application/json; charset=utf-8",
|
|
21
|
+
".txt": "text/plain; charset=utf-8",
|
|
22
|
+
".md": "text/markdown; charset=utf-8",
|
|
23
|
+
".csv": "text/csv; charset=utf-8",
|
|
24
|
+
".xml": "application/xml; charset=utf-8",
|
|
25
|
+
".svg": "image/svg+xml",
|
|
26
|
+
".png": "image/png",
|
|
27
|
+
".jpg": "image/jpeg",
|
|
28
|
+
".jpeg": "image/jpeg",
|
|
29
|
+
".gif": "image/gif",
|
|
30
|
+
".webp": "image/webp",
|
|
31
|
+
".avif": "image/avif",
|
|
32
|
+
".ico": "image/x-icon",
|
|
33
|
+
".bmp": "image/bmp",
|
|
34
|
+
".woff": "font/woff",
|
|
35
|
+
".woff2": "font/woff2",
|
|
36
|
+
".ttf": "font/ttf",
|
|
37
|
+
".otf": "font/otf",
|
|
38
|
+
".wasm": "application/wasm",
|
|
39
|
+
".mp4": "video/mp4",
|
|
40
|
+
".webm": "video/webm",
|
|
41
|
+
".ogg": "audio/ogg",
|
|
42
|
+
".mp3": "audio/mpeg",
|
|
43
|
+
".wav": "audio/wav",
|
|
44
|
+
".m4a": "audio/mp4",
|
|
45
|
+
".pdf": "application/pdf",
|
|
46
|
+
".zip": "application/zip",
|
|
47
|
+
".cast": "application/x-asciicast",
|
|
48
|
+
".glb": "model/gltf-binary",
|
|
49
|
+
".gltf": "model/gltf+json",
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
/** The `Content-Type` of a file, by extension. */
|
|
53
|
+
export function contentType(path: string): string {
|
|
54
|
+
return TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** A file found under a root. */
|
|
58
|
+
export interface FoundFile {
|
|
59
|
+
readonly path: string;
|
|
60
|
+
readonly size: number;
|
|
61
|
+
readonly mtimeMs: number;
|
|
62
|
+
/** When its contents or mode last changed; integrity checks compare it (FAILURE_MODEL §3). */
|
|
63
|
+
readonly ctimeMs: number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Finds the regular file `path` (a decoded, plain path starting with `/`) names under `root`, or
|
|
68
|
+
* `undefined`. Its real path must stay under the root's real path, so a link can't lead out.
|
|
69
|
+
*/
|
|
70
|
+
export async function findFile(root: string, path: string): Promise<FoundFile | undefined> {
|
|
71
|
+
if (path.includes("\0")) return undefined;
|
|
72
|
+
try {
|
|
73
|
+
const realRoot = await realpath(root);
|
|
74
|
+
const real = await realpath(join(realRoot, path));
|
|
75
|
+
if (real !== realRoot && !real.startsWith(`${realRoot}${sep}`)) return undefined;
|
|
76
|
+
const info = await stat(real);
|
|
77
|
+
return info.isFile()
|
|
78
|
+
? { path: real, size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs }
|
|
79
|
+
: undefined;
|
|
80
|
+
} catch {
|
|
81
|
+
return undefined;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Answers a request for a found file, with the given extra headers. */
|
|
86
|
+
export function fileResponse(
|
|
87
|
+
file: FoundFile,
|
|
88
|
+
request: Request,
|
|
89
|
+
headers: Readonly<Record<string, string>>,
|
|
90
|
+
): Response {
|
|
91
|
+
const etag = `W/"${file.size.toString(36)}-${Math.trunc(file.mtimeMs).toString(36)}"`;
|
|
92
|
+
const base: Record<string, string> = {
|
|
93
|
+
...BASE_HEADERS,
|
|
94
|
+
"content-type": contentType(file.path),
|
|
95
|
+
"accept-ranges": "bytes",
|
|
96
|
+
etag,
|
|
97
|
+
...headers,
|
|
98
|
+
};
|
|
99
|
+
if (request.headers.get("if-none-match") === etag) {
|
|
100
|
+
return new Response(null, { status: 304, headers: base });
|
|
101
|
+
}
|
|
102
|
+
const head = request.method === "HEAD";
|
|
103
|
+
const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get("range") ?? "");
|
|
104
|
+
if (range && (range[1] !== "" || range[2] !== "")) {
|
|
105
|
+
let start: number;
|
|
106
|
+
let end: number;
|
|
107
|
+
if (range[1] === "") {
|
|
108
|
+
// A suffix range: the last N bytes.
|
|
109
|
+
start = Math.max(0, file.size - Number(range[2]));
|
|
110
|
+
end = file.size - 1;
|
|
111
|
+
} else {
|
|
112
|
+
start = Number(range[1]);
|
|
113
|
+
end = range[2] === "" ? file.size - 1 : Math.min(Number(range[2]), file.size - 1);
|
|
114
|
+
}
|
|
115
|
+
if (start > end || start >= file.size) {
|
|
116
|
+
return new Response(null, {
|
|
117
|
+
status: 416,
|
|
118
|
+
headers: { ...base, "content-range": `bytes */${file.size}` },
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
const body = head
|
|
122
|
+
? null
|
|
123
|
+
: (Readable.toWeb(createReadStream(file.path, { start, end })) as ReadableStream);
|
|
124
|
+
return new Response(body, {
|
|
125
|
+
status: 206,
|
|
126
|
+
headers: {
|
|
127
|
+
...base,
|
|
128
|
+
"content-range": `bytes ${start}-${end}/${file.size}`,
|
|
129
|
+
"content-length": String(end - start + 1),
|
|
130
|
+
},
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
const body = head ? null : (Readable.toWeb(createReadStream(file.path)) as ReadableStream);
|
|
134
|
+
return new Response(body, {
|
|
135
|
+
status: 200,
|
|
136
|
+
headers: { ...base, "content-length": String(file.size) },
|
|
137
|
+
});
|
|
138
|
+
}
|