@botiverse/porthole 0.2.4 → 0.3.1

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 (85) hide show
  1. package/README.md +17 -11
  2. package/dist/check/check.d.ts +100 -0
  3. package/dist/check/check.js +247 -0
  4. package/dist/check/drivers.d.ts +43 -0
  5. package/dist/check/drivers.js +181 -0
  6. package/dist/check/index.d.ts +8 -0
  7. package/dist/check/index.js +8 -0
  8. package/dist/check/instrument.d.ts +71 -0
  9. package/dist/check/instrument.js +84 -0
  10. package/dist/check/lint.d.ts +21 -0
  11. package/dist/check/lint.js +131 -0
  12. package/dist/check/page-source.d.ts +2 -0
  13. package/dist/check/page-source.js +2 -0
  14. package/dist/check/page.d.ts +13 -0
  15. package/dist/check/page.js +170 -0
  16. package/dist/check/tools.d.ts +61 -0
  17. package/dist/check/tools.js +140 -0
  18. package/dist/conformance/host-kit.d.ts +26 -5
  19. package/dist/conformance/host-kit.js +46 -22
  20. package/dist/conformance/index.d.ts +1 -1
  21. package/dist/conformance/reporter.d.ts +14 -0
  22. package/dist/conformance/reporter.js +28 -0
  23. package/dist/displays/displays.d.ts +61 -0
  24. package/dist/displays/displays.js +113 -0
  25. package/dist/host/client.d.ts +110 -0
  26. package/dist/host/client.js +274 -0
  27. package/dist/index.d.ts +4 -0
  28. package/dist/index.js +6 -0
  29. package/dist/node/index.d.ts +26 -1
  30. package/dist/node/index.js +91 -1
  31. package/dist/react/frame.d.ts +79 -3
  32. package/dist/react/frame.js +183 -42
  33. package/dist/react/index.d.ts +2 -1
  34. package/dist/react/index.js +1 -0
  35. package/dist/react/view.d.ts +54 -0
  36. package/dist/react/view.js +151 -0
  37. package/dist/server/bootstrap.d.ts +27 -0
  38. package/dist/server/bootstrap.js +63 -0
  39. package/dist/server/host.d.ts +77 -8
  40. package/dist/server/host.js +268 -11
  41. package/dist/server/index.d.ts +4 -2
  42. package/dist/server/index.js +3 -1
  43. package/dist/server/pages.d.ts +19 -0
  44. package/dist/server/pages.js +8 -0
  45. package/dist/server/proxy.d.ts +24 -0
  46. package/dist/server/proxy.js +67 -0
  47. package/dist/server/server.js +14 -1
  48. package/dist/server/types.d.ts +8 -0
  49. package/docs/ADOPTING.md +278 -108
  50. package/docs/DECISIONS.md +280 -0
  51. package/docs/DESIGN.md +84 -2
  52. package/examples/app.mjs +82 -78
  53. package/examples/conformance/page.spec.mjs +23 -0
  54. package/examples/conformance/playwright.config.mjs +3 -2
  55. package/examples/conformance/porthole.spec.mjs +6 -3
  56. package/examples/displays.mjs +21 -0
  57. package/examples/mcp/server.mjs +121 -0
  58. package/examples/node/server.mjs +16 -34
  59. package/examples/workers/worker.mjs +19 -7
  60. package/package.json +13 -1
  61. package/src/check/check.ts +386 -0
  62. package/src/check/drivers.ts +242 -0
  63. package/src/check/index.ts +22 -0
  64. package/src/check/instrument.ts +138 -0
  65. package/src/check/lint.ts +238 -0
  66. package/src/check/page-source.ts +19 -0
  67. package/src/check/page.ts +230 -0
  68. package/src/check/tools.ts +206 -0
  69. package/src/conformance/host-kit.ts +82 -27
  70. package/src/conformance/index.ts +1 -0
  71. package/src/conformance/reporter.ts +38 -0
  72. package/src/displays/displays.ts +191 -0
  73. package/src/host/client.ts +395 -0
  74. package/src/index.ts +25 -0
  75. package/src/node/index.ts +112 -2
  76. package/src/react/frame.tsx +271 -57
  77. package/src/react/index.ts +9 -0
  78. package/src/react/view.tsx +237 -0
  79. package/src/server/bootstrap.ts +97 -0
  80. package/src/server/host.ts +372 -18
  81. package/src/server/index.ts +11 -1
  82. package/src/server/pages.ts +28 -0
  83. package/src/server/proxy.ts +86 -0
  84. package/src/server/server.ts +26 -2
  85. package/src/server/types.ts +5 -0
@@ -19,3 +19,27 @@ export declare function upstreamRequestHeaders(headers: Headers, origin: string,
19
19
  export declare function upstreamResponseHeaders(headers: Headers, origin: string, target: string): Headers;
20
20
  /** An `Upstream` that relays to the app by HTTP. */
21
21
  export declare function proxyTo(options?: ProxyOptions): Upstream;
22
+ type HeaderInput = Headers | Iterable<readonly [string, string]> | Readonly<Record<string, string | readonly string[] | undefined>>;
23
+ /** Whether a cookie is Porthole's own (sessions, entry nonces, the handoff). */
24
+ export declare const isPortholeCookie: (name: string) => boolean;
25
+ /** The cookie header without Porthole's own cookies, or null when nothing else is left. */
26
+ export declare function withoutPortholeCookies(cookie: string | null | undefined): string | null;
27
+ /**
28
+ * The header rewrite `proxyTo` makes, for a relay of its own (P072): a browser's request as the
29
+ * app at `target` gets it (Host, Origin, Referer naming the app; no forwarding headers, no
30
+ * Porthole cookies), and the app's answer as the browser on `origin` gets it (redirects and
31
+ * cookies kept on the content origin, Porthole's cookies never set). `websocket` keeps the
32
+ * upgrade's own headers. Pairs out, so a raw socket relay writes them as they are.
33
+ */
34
+ export declare const upstreamHeaders: {
35
+ request(input: HeaderInput, options: {
36
+ readonly origin: string;
37
+ readonly target: string;
38
+ readonly websocket?: boolean;
39
+ }): [string, string][];
40
+ response(input: HeaderInput, options: {
41
+ readonly origin: string;
42
+ readonly target: string;
43
+ }): [string, string][];
44
+ };
45
+ export {};
@@ -107,3 +107,70 @@ export function proxyTo(options = {}) {
107
107
  });
108
108
  };
109
109
  }
110
+ /** Headers from any of the shapes a relay has: fetch's, raw pairs, Node's. */
111
+ function headersOf(input) {
112
+ if (input instanceof Headers) {
113
+ return new Headers(input);
114
+ }
115
+ const out = new Headers();
116
+ const entries = Symbol.iterator in input
117
+ ? input
118
+ : Object.entries(input).flatMap(([name, value]) => value === undefined
119
+ ? []
120
+ : typeof value === "string"
121
+ ? [[name, value]]
122
+ : value.map((each) => [name, each]));
123
+ for (const [name, value] of entries) {
124
+ out.append(name, value);
125
+ }
126
+ return out;
127
+ }
128
+ /** Whether a cookie is Porthole's own (sessions, entry nonces, the handoff). */
129
+ export const isPortholeCookie = (name) => /^(?:__Host-|__Secure-)?porthole-/u.test(name);
130
+ /** The cookie header without Porthole's own cookies, or null when nothing else is left. */
131
+ export function withoutPortholeCookies(cookie) {
132
+ const kept = (cookie ?? "")
133
+ .split(";")
134
+ .map((part) => part.trim())
135
+ .filter((part) => part !== "" && !isPortholeCookie(part.split("=")[0]?.trim() ?? ""));
136
+ return kept.length === 0 ? null : kept.join("; ");
137
+ }
138
+ /**
139
+ * The header rewrite `proxyTo` makes, for a relay of its own (P072): a browser's request as the
140
+ * app at `target` gets it (Host, Origin, Referer naming the app; no forwarding headers, no
141
+ * Porthole cookies), and the app's answer as the browser on `origin` gets it (redirects and
142
+ * cookies kept on the content origin, Porthole's cookies never set). `websocket` keeps the
143
+ * upgrade's own headers. Pairs out, so a raw socket relay writes them as they are.
144
+ */
145
+ export const upstreamHeaders = {
146
+ request(input, options) {
147
+ const given = headersOf(input);
148
+ const out = upstreamRequestHeaders(given, options.origin, options.target);
149
+ const cookie = withoutPortholeCookies(given.get("cookie"));
150
+ if (cookie === null) {
151
+ out.delete("cookie");
152
+ }
153
+ else {
154
+ out.set("cookie", cookie);
155
+ }
156
+ if (options.websocket === true) {
157
+ out.delete("accept-encoding");
158
+ for (const name of ["connection", "upgrade"]) {
159
+ const value = given.get(name);
160
+ if (value !== null) {
161
+ out.set(name, value);
162
+ }
163
+ }
164
+ out.set("host", new URL(options.target).host);
165
+ }
166
+ return [...out];
167
+ },
168
+ response(input, options) {
169
+ const answer = upstreamResponseHeaders(headersOf(input), options.origin, options.target);
170
+ const cookies = answer
171
+ .getSetCookie()
172
+ .filter((each) => !isPortholeCookie(each.split("=")[0]?.trim() ?? ""));
173
+ answer.delete("set-cookie");
174
+ return [...answer, ...cookies.map((each) => ["set-cookie", each])];
175
+ },
176
+ };
@@ -270,7 +270,12 @@ export function createServer(options) {
270
270
  catch {
271
271
  given = { allow: false };
272
272
  }
273
- answer = { answer: given, until: at + authorizeTtl * 1_000 };
273
+ answer = {
274
+ answer: given,
275
+ until: at + authorizeTtl * 1_000,
276
+ scope: access.instance.scope,
277
+ subject: access.subject ?? null,
278
+ };
274
279
  if (authorizeTtl > 0) {
275
280
  if (answers.size > 10_000) {
276
281
  answers.clear();
@@ -855,6 +860,14 @@ export function createServer(options) {
855
860
  : `${PREFIX}d/${key}?ticket=${ticket}`;
856
861
  return { url: `${origin}${path}`, origin, reports: true };
857
862
  },
863
+ forget(filter = {}) {
864
+ for (const [key, each] of answers) {
865
+ if ((filter.scope === undefined || each.scope === filter.scope) &&
866
+ (filter.subject === undefined || each.subject === filter.subject)) {
867
+ answers.delete(key);
868
+ }
869
+ }
870
+ },
858
871
  urlOf(scope, path = "/") {
859
872
  if (!path.startsWith("/") || path.startsWith("//") || path.startsWith(PREFIX)) {
860
873
  throw new TypeError("A clean address's path starts with one / and isn't Porthole's own");
@@ -205,6 +205,14 @@ export interface PortholeServer {
205
205
  access(request: Request): Promise<Access | null>;
206
206
  /** The frame source every content origin matches (`https://*.example-usercontent.com`). */
207
207
  readonly contentSource: string;
208
+ /**
209
+ * Drops cached `authorize.check` answers (`ttlSeconds`): all, or a scope's, or a subject's, so a
210
+ * revocation holds at once (P072).
211
+ */
212
+ forget(filter?: {
213
+ readonly scope?: string;
214
+ readonly subject?: string;
215
+ }): void;
208
216
  /** A clean address on a scope's origin (P068): what a tab, a link, a bookmark opens. */
209
217
  urlOf(scope: string, path?: string): string;
210
218
  /** A redirect entry's state, signature checked; null for one this server didn't make. */