@botiverse/porthole 0.14.6 → 0.14.8
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/CHANGELOG.md +60 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +43 -14
- package/dist/guide/limits.js +8 -1
- package/dist/host/create-host.js +35 -4
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -0
- package/dist/server/files.js +4 -3
- package/dist/server/index.js +2 -1
- package/dist/server/server.js +89 -37
- package/dist/server/types.d.ts +23 -0
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +785 -104
- package/docs/ADOPTING.md +36 -0
- package/docs/DECISIONS.md +341 -0
- package/docs/DESIGN.md +7 -4
- package/docs/THREAT_MODEL.md +30 -5
- package/docs/insertion-entry-points.md +95 -0
- package/package.json +1 -1
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +43 -14
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +37 -4
- package/src/index.ts +1 -0
- package/src/presets/presets.ts +15 -0
- package/src/server/files.ts +8 -2
- package/src/server/index.ts +2 -1
- package/src/server/server.ts +116 -46
- package/src/server/types.ts +25 -0
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +788 -104
package/src/server/server.ts
CHANGED
|
@@ -1125,13 +1125,22 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1125
1125
|
return serveAccess(request, access, cookie, undefined, rest);
|
|
1126
1126
|
}
|
|
1127
1127
|
|
|
1128
|
+
/** A door that doesn't open (P125): its status, reason and the host's code, if any. */
|
|
1129
|
+
const doorSays = (status: number, reason: FrameBlock, method: string, code?: string): Response =>
|
|
1130
|
+
doorStatusResponse({
|
|
1131
|
+
status,
|
|
1132
|
+
reason,
|
|
1133
|
+
...(code === undefined ? {} : { code }),
|
|
1134
|
+
hostOrigins: options.hostOrigins,
|
|
1135
|
+
frameAncestors,
|
|
1136
|
+
method,
|
|
1137
|
+
});
|
|
1138
|
+
|
|
1128
1139
|
/**
|
|
1129
1140
|
* A served display's door (P125): its own ticket's, taken once, for this instance on this
|
|
1130
|
-
* origin
|
|
1131
|
-
*
|
|
1132
|
-
*
|
|
1133
|
-
* own ticket and checks again (P050), so the door only tells. No other ticket opens it, and a
|
|
1134
|
-
* nested page's shell's label serves none (`serveShellLabel`).
|
|
1141
|
+
* origin; then the door's answer for that ticket's grant (`answerDoor`, the one `doorAnswer`
|
|
1142
|
+
* gives, P126). No other ticket opens it, and a nested page's shell's label serves none
|
|
1143
|
+
* (`serveShellLabel`).
|
|
1135
1144
|
*/
|
|
1136
1145
|
async function serveDoor(
|
|
1137
1146
|
request: Request,
|
|
@@ -1140,20 +1149,12 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1140
1149
|
key: string,
|
|
1141
1150
|
): Promise<Response> {
|
|
1142
1151
|
const method = request.method.toUpperCase();
|
|
1143
|
-
const say = (status: number, reason: FrameBlock, code?: string): Response =>
|
|
1144
|
-
doorStatusResponse({
|
|
1145
|
-
status,
|
|
1146
|
-
reason,
|
|
1147
|
-
...(code === undefined ? {} : { code }),
|
|
1148
|
-
hostOrigins: options.hostOrigins,
|
|
1149
|
-
frameAncestors,
|
|
1150
|
-
method,
|
|
1151
|
-
});
|
|
1152
1152
|
if (method !== "GET" && method !== "HEAD") {
|
|
1153
|
-
return
|
|
1153
|
+
return doorSays(405, "error", method);
|
|
1154
1154
|
}
|
|
1155
|
+
let record: TicketRecord | null;
|
|
1155
1156
|
try {
|
|
1156
|
-
|
|
1157
|
+
record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
|
|
1157
1158
|
if (
|
|
1158
1159
|
record === null ||
|
|
1159
1160
|
record.door !== true ||
|
|
@@ -1162,34 +1163,61 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1162
1163
|
keys.instanceKey(record.instance) !== key ||
|
|
1163
1164
|
compiledFor(record.instance)?.config.nested === true
|
|
1164
1165
|
) {
|
|
1165
|
-
return
|
|
1166
|
+
return doorSays(401, "session", method);
|
|
1166
1167
|
}
|
|
1167
|
-
|
|
1168
|
+
} catch {
|
|
1169
|
+
return doorSays(500, "error", method);
|
|
1170
|
+
}
|
|
1171
|
+
return answerDoor(
|
|
1172
|
+
request,
|
|
1173
|
+
{
|
|
1168
1174
|
instance: record.instance,
|
|
1169
1175
|
viewer: record.viewer,
|
|
1170
1176
|
origin: originOfLabel(label),
|
|
1171
1177
|
expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
|
|
1172
1178
|
...(record.anonymous === true ? { anonymous: true } : {}),
|
|
1173
1179
|
...(record.subject === undefined ? {} : { subject: record.subject }),
|
|
1174
|
-
}
|
|
1180
|
+
},
|
|
1181
|
+
isPageRest(record.page) ? record.page : undefined,
|
|
1182
|
+
);
|
|
1183
|
+
}
|
|
1184
|
+
|
|
1185
|
+
/**
|
|
1186
|
+
* The door's answer for an access already admitted (P125, P126): the checks the content's
|
|
1187
|
+
* address runs for the same grant (the host's check, the document, its entry, the page it opens
|
|
1188
|
+
* at), so the door says what the content's address would: `open`, or `blocked` and why. It sets
|
|
1189
|
+
* no cookie and serves nothing of the content; the content's address takes its own ticket and
|
|
1190
|
+
* checks again (P050), so the door only tells. `serveDoor` answers with it once its ticket is
|
|
1191
|
+
* taken, and `doorAnswer` for a host that admitted the request itself: one answer for both.
|
|
1192
|
+
*/
|
|
1193
|
+
async function answerDoor(
|
|
1194
|
+
request: Request,
|
|
1195
|
+
access: Access,
|
|
1196
|
+
/** A page below a file set's base its frame opens at (P125). */
|
|
1197
|
+
below: string | undefined,
|
|
1198
|
+
): Promise<Response> {
|
|
1199
|
+
const method = request.method.toUpperCase();
|
|
1200
|
+
if (method !== "GET" && method !== "HEAD") {
|
|
1201
|
+
return doorSays(405, "error", method);
|
|
1202
|
+
}
|
|
1203
|
+
try {
|
|
1175
1204
|
const refused = await refusalOf(request, access);
|
|
1176
1205
|
if (refused !== null) {
|
|
1177
|
-
return
|
|
1206
|
+
return doorSays(403, "denied", method, refused.code);
|
|
1178
1207
|
}
|
|
1179
1208
|
const served = await documentOf(access.instance);
|
|
1180
1209
|
// The same document, entry and page checks the content's address runs (`serveAccess`).
|
|
1181
|
-
const below = isPageRest(record.page) ? record.page : undefined;
|
|
1182
1210
|
if (
|
|
1183
1211
|
served === null ||
|
|
1184
1212
|
("files" in served
|
|
1185
1213
|
? !entryIsPage(served.files) || ticketPage(served.files, below) === null
|
|
1186
1214
|
: below !== undefined)
|
|
1187
1215
|
) {
|
|
1188
|
-
return
|
|
1216
|
+
return doorSays(404, "not-found", method);
|
|
1189
1217
|
}
|
|
1190
1218
|
return doorResponse({ hostOrigins: options.hostOrigins, frameAncestors, method });
|
|
1191
1219
|
} catch {
|
|
1192
|
-
return
|
|
1220
|
+
return doorSays(500, "error", method);
|
|
1193
1221
|
}
|
|
1194
1222
|
}
|
|
1195
1223
|
|
|
@@ -1275,6 +1303,9 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1275
1303
|
const ancestors = nested ? nestedAncestors(access.origin, frameAncestors) : frameAncestors;
|
|
1276
1304
|
if ("files" in served) {
|
|
1277
1305
|
if (at !== undefined) {
|
|
1306
|
+
// A page's own frames (P128): its files below the base are framed by its own pages too,
|
|
1307
|
+
// on this origin (`frame-ancestors` names every ancestor). Never another origin's.
|
|
1308
|
+
const own = served.compiled.config.nestedFrames === "own";
|
|
1278
1309
|
return serveFile({
|
|
1279
1310
|
request,
|
|
1280
1311
|
set: served.files,
|
|
@@ -1286,7 +1317,7 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1286
1317
|
source: at.source,
|
|
1287
1318
|
compiled: served.compiled,
|
|
1288
1319
|
hostOrigins: options.hostOrigins,
|
|
1289
|
-
frameAncestors: ancestors,
|
|
1320
|
+
frameAncestors: own ? `${access.origin} ${ancestors}` : ancestors,
|
|
1290
1321
|
...versionOf(access.instance),
|
|
1291
1322
|
});
|
|
1292
1323
|
}
|
|
@@ -1839,22 +1870,11 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1839
1870
|
return page(404, "Nothing here", "This address names no content.", method);
|
|
1840
1871
|
}
|
|
1841
1872
|
|
|
1842
|
-
/** A
|
|
1843
|
-
|
|
1844
|
-
|
|
1873
|
+
/** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
|
|
1874
|
+
function checkGrant(
|
|
1875
|
+
clean: InstanceRef,
|
|
1845
1876
|
grant: Grant,
|
|
1846
|
-
|
|
1847
|
-
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1848
|
-
below?: string,
|
|
1849
|
-
): Promise<{
|
|
1850
|
-
readonly clean: InstanceRef;
|
|
1851
|
-
readonly key: string;
|
|
1852
|
-
readonly ticket: string;
|
|
1853
|
-
/** The door's own ticket (P125), for a display framed on its scope's origin. */
|
|
1854
|
-
readonly door: string | null;
|
|
1855
|
-
}> {
|
|
1856
|
-
const clean = cleanInstance(instance);
|
|
1857
|
-
check(clean);
|
|
1877
|
+
): { readonly anonymous: boolean; readonly viewer: string } {
|
|
1858
1878
|
const anonymous = grant.anonymous === true;
|
|
1859
1879
|
if (anonymous) {
|
|
1860
1880
|
if (grant.viewer !== undefined) {
|
|
@@ -1876,15 +1896,33 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1876
1896
|
) {
|
|
1877
1897
|
throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
|
|
1878
1898
|
}
|
|
1899
|
+
return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
|
|
1900
|
+
}
|
|
1901
|
+
|
|
1902
|
+
/** How long a grant's session lasts, checked (`sessionSeconds`). */
|
|
1903
|
+
const sessionOf = (grant: Grant): number =>
|
|
1904
|
+
seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
|
|
1905
|
+
|
|
1906
|
+
/** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
|
|
1907
|
+
async function mint(
|
|
1908
|
+
instance: InstanceRef,
|
|
1909
|
+
grant: Grant,
|
|
1910
|
+
entry?: TicketRecord["entry"],
|
|
1911
|
+
/** A page below a file set's base its frame opens at (P125: a clean address's file). */
|
|
1912
|
+
below?: string,
|
|
1913
|
+
): Promise<{
|
|
1914
|
+
readonly clean: InstanceRef;
|
|
1915
|
+
readonly key: string;
|
|
1916
|
+
readonly ticket: string;
|
|
1917
|
+
/** The door's own ticket (P125), for a display framed on its scope's origin. */
|
|
1918
|
+
readonly door: string | null;
|
|
1919
|
+
}> {
|
|
1920
|
+
const clean = cleanInstance(instance);
|
|
1921
|
+
check(clean);
|
|
1922
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
1879
1923
|
const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
|
|
1880
|
-
const sessionSeconds =
|
|
1881
|
-
grant.sessionSeconds,
|
|
1882
|
-
DEFAULT_SESSION_SECONDS,
|
|
1883
|
-
MAX_SESSION_SECONDS,
|
|
1884
|
-
"sessionSeconds",
|
|
1885
|
-
);
|
|
1924
|
+
const sessionSeconds = sessionOf(grant);
|
|
1886
1925
|
const key = keys.instanceKey(clean);
|
|
1887
|
-
const viewer = anonymous ? "" : grant.viewer;
|
|
1888
1926
|
const probe = keys.sign({
|
|
1889
1927
|
i: clean,
|
|
1890
1928
|
w: viewer,
|
|
@@ -2008,6 +2046,38 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
2008
2046
|
};
|
|
2009
2047
|
},
|
|
2010
2048
|
|
|
2049
|
+
async doorAnswer(instance, grant, request, at = {}): Promise<Response> {
|
|
2050
|
+
// A host that admitted the request itself (P126): no ticket here, the grant is its word.
|
|
2051
|
+
const clean = cleanInstance(instance);
|
|
2052
|
+
check(clean);
|
|
2053
|
+
if (!hasDoor(clean)) {
|
|
2054
|
+
throw new TypeError(
|
|
2055
|
+
"This instance has no door (P125): a nested page's frame is its shell, a url-mode app has none",
|
|
2056
|
+
);
|
|
2057
|
+
}
|
|
2058
|
+
const below = at.page;
|
|
2059
|
+
if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
|
|
2060
|
+
throw new TypeError(
|
|
2061
|
+
"A frame's page is a relative path below an artifact's files (no . or ..)",
|
|
2062
|
+
);
|
|
2063
|
+
}
|
|
2064
|
+
const { anonymous, viewer } = checkGrant(clean, grant);
|
|
2065
|
+
const sessionSeconds = sessionOf(grant);
|
|
2066
|
+
const origin = originOfLabel(labelFor(clean));
|
|
2067
|
+
return answerDoor(
|
|
2068
|
+
request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`),
|
|
2069
|
+
{
|
|
2070
|
+
instance: clean,
|
|
2071
|
+
viewer,
|
|
2072
|
+
origin,
|
|
2073
|
+
expiresAt: Date.now() + sessionSeconds * 1_000,
|
|
2074
|
+
...(anonymous ? { anonymous: true } : {}),
|
|
2075
|
+
...(grant.subject === undefined ? {} : { subject: grant.subject }),
|
|
2076
|
+
},
|
|
2077
|
+
below,
|
|
2078
|
+
);
|
|
2079
|
+
},
|
|
2080
|
+
|
|
2011
2081
|
forget(filter = {}) {
|
|
2012
2082
|
for (const [key, each] of answers) {
|
|
2013
2083
|
if (
|
package/src/server/types.ts
CHANGED
|
@@ -342,6 +342,31 @@ export interface PortholeServer {
|
|
|
342
342
|
*/
|
|
343
343
|
at?: { readonly page?: string },
|
|
344
344
|
): Promise<FrameLocation>;
|
|
345
|
+
/**
|
|
346
|
+
* A served display's door answer for a grant the host has already admitted (P126): exactly the
|
|
347
|
+
* Response its door (`DOOR_PATH<key>`, P125) answers once it has taken its own ticket for that
|
|
348
|
+
* instance and grant. The content's address's checks for that grant run here: the host's
|
|
349
|
+
* `authorize` check (`denied`, with its code), the document and its version (`not-found`), a file
|
|
350
|
+
* set's entry being a page and the page `at` names (`not-found`). The answer is `doorResponse`
|
|
351
|
+
* (open) or `doorStatusResponse` (blocked: reason, status, code), with the door's CSP (`sandbox
|
|
352
|
+
* allow-scripts`, `frame-ancestors` the host origins), `no-store`, and no cookie.
|
|
353
|
+
*
|
|
354
|
+
* It is a function, not a route, and it never takes a ticket: it is for a host that signs its own
|
|
355
|
+
* tickets (a content Worker that verifies them itself) and answers its door with it. The caller
|
|
356
|
+
* must have authenticated the request and established the grant itself, as it does before
|
|
357
|
+
* `issue`; Porthole's own door route takes its door ticket and then answers with this. `request`
|
|
358
|
+
* is what `authorize.check` is handed (and gives the method: HEAD has no body, a method other
|
|
359
|
+
* than GET or HEAD is 405); default, a GET of the door on the instance's origin. Throws, as
|
|
360
|
+
* `issue` does, for an instance or grant `issue` would refuse, and for an instance with no door
|
|
361
|
+
* (a nested page, a url-mode app).
|
|
362
|
+
*/
|
|
363
|
+
doorAnswer(
|
|
364
|
+
instance: InstanceRef,
|
|
365
|
+
grant: Grant,
|
|
366
|
+
request?: Request,
|
|
367
|
+
/** The page below a file set's base the frame opens at, as `issue`'s `at` (P125). */
|
|
368
|
+
at?: { readonly page?: string },
|
|
369
|
+
): Promise<Response>;
|
|
345
370
|
/**
|
|
346
371
|
* The access a request's cookie carries for a url-mode app on the request's origin, or null
|
|
347
372
|
* (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
|
package/src/shell/plan.ts
CHANGED
|
@@ -56,6 +56,11 @@ export interface ShellPlan {
|
|
|
56
56
|
/** The most text `copyText` carries. */
|
|
57
57
|
readonly maxCopyChars: number;
|
|
58
58
|
readonly protocolVersion: string;
|
|
59
|
+
/**
|
|
60
|
+
* `own` where the config lets content frame its own files and `srcdoc` (P128): the shell keeps
|
|
61
|
+
* those iframes and removes every other frame-like element. Absent: it removes them all.
|
|
62
|
+
*/
|
|
63
|
+
readonly nestedFrames?: "own";
|
|
59
64
|
}
|
|
60
65
|
|
|
61
66
|
export function shellPlan(config: PortholeConfig): ShellPlan | null {
|
|
@@ -103,5 +108,7 @@ export function shellPlan(config: PortholeConfig): ShellPlan | null {
|
|
|
103
108
|
maxPromptChars: config.limits.maxPromptChars,
|
|
104
109
|
maxCopyChars: MAX_COPY_CHARS,
|
|
105
110
|
protocolVersion: MCP_APPS_PROTOCOL_VERSION,
|
|
111
|
+
// Only where opted into (P128): every other plan is the same as before it.
|
|
112
|
+
...(config.nestedFrames === "own" ? { nestedFrames: "own" as const } : {}),
|
|
106
113
|
};
|
|
107
114
|
}
|