@mostra/runtime 0.10.0 → 0.12.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.
Files changed (257) hide show
  1. package/dist/bin.js +4178 -310
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/{instance-FExcyENK.js → instance-CBUlOmzG.js} +1892 -85
  6. package/dist/instance-CBUlOmzG.js.map +1 -0
  7. package/dist/reference/cli.md +1432 -0
  8. package/dist/reference/diagnostics.json +1579 -0
  9. package/dist/reference/errors/MOSTRA_A11Y_MINOR.md +23 -0
  10. package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md +23 -0
  11. package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md +23 -0
  12. package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md +23 -0
  13. package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md +23 -0
  15. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md +23 -0
  17. package/dist/reference/errors/MOSTRA_ACTION_THREW.md +23 -0
  18. package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md +23 -0
  19. package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md +23 -0
  20. package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md +23 -0
  21. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md +23 -0
  23. package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md +23 -0
  24. package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md +23 -0
  26. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md +23 -0
  27. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md +23 -0
  28. package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
  29. package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
  30. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md +23 -0
  31. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md +23 -0
  32. package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md +23 -0
  33. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md +23 -0
  34. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md +23 -0
  35. package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md +23 -0
  36. package/dist/reference/errors/MOSTRA_BUILD_FAILED.md +23 -0
  37. package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md +23 -0
  38. package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md +23 -0
  39. package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md +23 -0
  40. package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md +23 -0
  41. package/dist/reference/errors/MOSTRA_CLI_USAGE.md +23 -0
  42. package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md +23 -0
  43. package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md +23 -0
  44. package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md +23 -0
  45. package/dist/reference/errors/MOSTRA_DEP_MISSING.md +23 -0
  46. package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md +23 -0
  47. package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md +23 -0
  48. package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md +23 -0
  49. package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md +23 -0
  50. package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md +23 -0
  51. package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md +23 -0
  52. package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md +23 -0
  53. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md +23 -0
  54. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md +23 -0
  55. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md +23 -0
  56. package/dist/reference/errors/MOSTRA_ENV_HELPER_MISSING.md +23 -0
  57. package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md +23 -0
  58. package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md +23 -0
  59. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
  60. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md +23 -0
  61. package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md +23 -0
  62. package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md +23 -0
  63. package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md +23 -0
  64. package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md +23 -0
  65. package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md +23 -0
  66. package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md +23 -0
  67. package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md +23 -0
  68. package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md +23 -0
  69. package/dist/reference/errors/MOSTRA_FIELD_SHARED.md +23 -0
  70. package/dist/reference/errors/MOSTRA_FIELD_TOO_LARGE.md +23 -0
  71. package/dist/reference/errors/MOSTRA_FIELD_UNBOUND.md +23 -0
  72. package/dist/reference/errors/MOSTRA_HOME_DISK_FULL.md +23 -0
  73. package/dist/reference/errors/MOSTRA_HOME_GC_INCOMPLETE.md +23 -0
  74. package/dist/reference/errors/MOSTRA_HOME_GONE.md +23 -0
  75. package/dist/reference/errors/MOSTRA_HOME_INTEGRITY.md +23 -0
  76. package/dist/reference/errors/MOSTRA_HOME_LEDGER_UNREADABLE.md +23 -0
  77. package/dist/reference/errors/MOSTRA_HOME_LOCKED.md +23 -0
  78. package/dist/reference/errors/MOSTRA_HOME_MISMATCH.md +23 -0
  79. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  80. package/dist/reference/errors/MOSTRA_HOME_NOT_ALWAYS_ON.md +23 -0
  81. package/dist/reference/errors/MOSTRA_HOME_NOT_OWNED.md +23 -0
  82. package/dist/reference/errors/MOSTRA_HOME_SOCKET_TOO_LONG.md +23 -0
  83. package/dist/reference/errors/MOSTRA_HOME_TOO_NEW.md +23 -0
  84. package/dist/reference/errors/MOSTRA_HOST_CONNECTION_CLOSED.md +23 -0
  85. package/dist/reference/errors/MOSTRA_HOST_CURSOR_COMPACTED.md +23 -0
  86. package/dist/reference/errors/MOSTRA_HOST_IDENTITY_UNAVAILABLE.md +23 -0
  87. package/dist/reference/errors/MOSTRA_HOST_INITIALIZE_ORDER.md +23 -0
  88. package/dist/reference/errors/MOSTRA_HOST_INTERNAL_ERROR.md +23 -0
  89. package/dist/reference/errors/MOSTRA_HOST_INVALID_PARAMS.md +23 -0
  90. package/dist/reference/errors/MOSTRA_HOST_MALFORMED.md +23 -0
  91. package/dist/reference/errors/MOSTRA_HOST_MESSAGE_TOO_LARGE.md +23 -0
  92. package/dist/reference/errors/MOSTRA_HOST_METHOD_UNKNOWN.md +23 -0
  93. package/dist/reference/errors/MOSTRA_HOST_NOTIFICATION_UNSUPPORTED.md +23 -0
  94. package/dist/reference/errors/MOSTRA_HOST_PORT_UNSUPPORTED.md +23 -0
  95. package/dist/reference/errors/MOSTRA_HOST_REQUEST_ID_REUSED.md +23 -0
  96. package/dist/reference/errors/MOSTRA_HOST_REVISION_UNSUPPORTED.md +23 -0
  97. package/dist/reference/errors/MOSTRA_HOST_SHUTDOWN_REFUSED.md +23 -0
  98. package/dist/reference/errors/MOSTRA_HOST_SUBSCRIPTION_UNKNOWN.md +23 -0
  99. package/dist/reference/errors/MOSTRA_HOST_TIMEOUT.md +23 -0
  100. package/dist/reference/errors/MOSTRA_HYGIENE_CONTENT_TYPE.md +23 -0
  101. package/dist/reference/errors/MOSTRA_HYGIENE_CSRF_MISSING.md +23 -0
  102. package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
  103. package/dist/reference/errors/MOSTRA_HYGIENE_HEADERS_TOO_LARGE.md +23 -0
  104. package/dist/reference/errors/MOSTRA_HYGIENE_HOST_REFUSED.md +23 -0
  105. package/dist/reference/errors/MOSTRA_HYGIENE_NOT_SERVED.md +23 -0
  106. package/dist/reference/errors/MOSTRA_HYGIENE_ORIGIN_REFUSED.md +23 -0
  107. package/dist/reference/errors/MOSTRA_HYGIENE_RATE_LIMITED.md +23 -0
  108. package/dist/reference/errors/MOSTRA_HYGIENE_REQUEST_MALFORMED.md +23 -0
  109. package/dist/reference/errors/MOSTRA_HYGIENE_SCOPE_DENIED.md +23 -0
  110. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_CONFLICT.md +23 -0
  111. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_MISSING.md +23 -0
  112. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_INVALID.md +23 -0
  113. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_REVOKED.md +23 -0
  114. package/dist/reference/errors/MOSTRA_LIVE_SOURCE_FAILED.md +23 -0
  115. package/dist/reference/errors/MOSTRA_LIVE_TOO_LARGE.md +23 -0
  116. package/dist/reference/errors/MOSTRA_MANIFEST_INVALID.md +23 -0
  117. package/dist/reference/errors/MOSTRA_MANIFEST_NOT_LITERAL.md +23 -0
  118. package/dist/reference/errors/MOSTRA_MANIFEST_UNKNOWN_KEY.md +23 -0
  119. package/dist/reference/errors/MOSTRA_NETWORK_EXTERNAL_FAILED.md +23 -0
  120. package/dist/reference/errors/MOSTRA_NETWORK_REQUEST_FAILED.md +23 -0
  121. package/dist/reference/errors/MOSTRA_PLATFORM_UNSUPPORTED.md +23 -0
  122. package/dist/reference/errors/MOSTRA_PUBLISH_ID_CONFLICT.md +23 -0
  123. package/dist/reference/errors/MOSTRA_PUBLISH_SOURCE_CHANGED.md +23 -0
  124. package/dist/reference/errors/MOSTRA_PUBLISH_VERIFY_FAILED.md +23 -0
  125. package/dist/reference/errors/MOSTRA_REGRESSION_ACTION_REMOVED.md +23 -0
  126. package/dist/reference/errors/MOSTRA_REGRESSION_ARIA.md +23 -0
  127. package/dist/reference/errors/MOSTRA_REGRESSION_FIELD_REMOVED.md +23 -0
  128. package/dist/reference/errors/MOSTRA_REGRESSION_LIVE_REMOVED.md +23 -0
  129. package/dist/reference/errors/MOSTRA_REGRESSION_PAGE_REMOVED.md +23 -0
  130. package/dist/reference/errors/MOSTRA_REGRESSION_PIXELS.md +23 -0
  131. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  132. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  133. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  134. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
  135. package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
  136. package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
  137. package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
  138. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  139. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  140. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  141. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  142. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  143. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  144. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  145. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  146. package/dist/reference/errors/MOSTRA_RUNTIME_BLANK.md +23 -0
  147. package/dist/reference/errors/MOSTRA_RUNTIME_NOT_READY.md +23 -0
  148. package/dist/reference/errors/MOSTRA_RUNTIME_PAGE_ERROR.md +23 -0
  149. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_CRASHED.md +23 -0
  150. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_PARKED.md +23 -0
  151. package/dist/reference/errors/MOSTRA_SECRET_MISSING.md +23 -0
  152. package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
  153. package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
  154. package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
  155. package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
  156. package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
  157. package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
  158. package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
  159. package/dist/reference/errors/MOSTRA_SMOKE_BUDGET.md +23 -0
  160. package/dist/reference/errors/MOSTRA_SMOKE_NO_EFFECT.md +23 -0
  161. package/dist/reference/errors/MOSTRA_SUBMIT_ALREADY.md +23 -0
  162. package/dist/reference/errors/MOSTRA_SUBMIT_BLOCKED.md +23 -0
  163. package/dist/reference/errors/MOSTRA_SUBMIT_CHANNEL_DENIED.md +23 -0
  164. package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +23 -0
  165. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  166. package/dist/reference/errors/MOSTRA_SUBMIT_POLICY_NONE.md +23 -0
  167. package/dist/reference/errors/MOSTRA_SUBMIT_REVISION_MOVED.md +23 -0
  168. package/dist/reference/errors/MOSTRA_SUBMIT_SIGNAL_INVALID.md +23 -0
  169. package/dist/reference/errors/MOSTRA_SUBMIT_VIEW_INVALID.md +23 -0
  170. package/dist/reference/errors/MOSTRA_TARGET_UNAVAILABLE.md +23 -0
  171. package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
  172. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
  173. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
  174. package/dist/reference/errors/MOSTRA_TYPE_ERROR.md +23 -0
  175. package/dist/reference/errors/MOSTRA_TYPE_UNTYPED_PACKAGE.md +23 -0
  176. package/dist/reference/errors/MOSTRA_VERIFY_ACTION_SKIPPED.md +23 -0
  177. package/dist/reference/errors/MOSTRA_VERIFY_BASELINE_MISSING.md +23 -0
  178. package/dist/reference/errors/MOSTRA_VERIFY_CRASHED.md +23 -0
  179. package/dist/reference/errors/MOSTRA_VERIFY_LIVE_FAILED.md +23 -0
  180. package/dist/reference/errors/MOSTRA_VERIFY_NO_BASELINE.md +23 -0
  181. package/dist/reference/errors/MOSTRA_VERIFY_SECRET_MISSING.md +23 -0
  182. package/dist/reference/errors/MOSTRA_VERIFY_SKIP_CONSEQUENCE.md +23 -0
  183. package/dist/reference/errors/MOSTRA_VERIFY_TIMEOUT.md +23 -0
  184. package/dist/reference/self-hosting.md +130 -0
  185. package/dist/reference/telemetry.md +84 -0
  186. package/dist/skill/SKILL.md +124 -0
  187. package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
  188. package/dist/skill/assets/examples/dashboard/live.ts +25 -0
  189. package/dist/skill/assets/examples/dashboard/styles.css +125 -0
  190. package/dist/skill/assets/examples/decision/index.tsx +95 -0
  191. package/dist/skill/assets/examples/decision/styles.css +125 -0
  192. package/dist/skill/assets/examples/inbox/actions.ts +23 -0
  193. package/dist/skill/assets/examples/inbox/index.tsx +109 -0
  194. package/dist/skill/assets/examples/inbox/styles.css +125 -0
  195. package/dist/skill/assets/studio.css +125 -0
  196. package/dist/skill/references/answers.md +219 -0
  197. package/dist/skill/references/design.md +154 -0
  198. package/dist/skill/references/libraries.md +167 -0
  199. package/dist/skill/references/long-lived.md +148 -0
  200. package/dist/skill/references/mcp.md +68 -0
  201. package/dist/skill/references/page.md +131 -0
  202. package/dist/skill/references/server.md +146 -0
  203. package/dist/skill/references/sharing.md +123 -0
  204. package/dist/skill/references/teams.md +78 -0
  205. package/dist/skill/references/verify.md +71 -0
  206. package/package.json +10 -5
  207. package/src/gateway/actions.ts +20 -0
  208. package/src/gateway/browser.ts +128 -1
  209. package/src/gateway/capabilities.ts +8 -0
  210. package/src/gateway/http.ts +12 -1
  211. package/src/gateway/index.ts +210 -6
  212. package/src/gateway/listener.ts +31 -6
  213. package/src/gateway/routes.ts +8 -0
  214. package/src/gateway/team.ts +181 -0
  215. package/src/gc/index.ts +5 -0
  216. package/src/instance/index.ts +22 -2
  217. package/src/interaction/ephemeral.ts +21 -0
  218. package/src/interaction/events.ts +17 -0
  219. package/src/interaction/index.ts +325 -20
  220. package/src/interaction/pause.ts +106 -0
  221. package/src/interaction/roster.ts +585 -0
  222. package/src/interaction/submissions.ts +42 -1
  223. package/src/interaction/team.ts +426 -0
  224. package/src/interaction/viewers.ts +34 -1
  225. package/src/interaction/wait.ts +150 -0
  226. package/src/ledger/index.ts +20 -1
  227. package/src/ledger/migrations.ts +86 -0
  228. package/src/link/author.ts +215 -0
  229. package/src/link/hosted.ts +51 -4
  230. package/src/link/http.ts +6 -1
  231. package/src/link/index.ts +3 -1
  232. package/src/link/manager.ts +169 -35
  233. package/src/protocol-server/client.ts +53 -0
  234. package/src/protocol-server/index.ts +1 -1
  235. package/src/server/api.ts +514 -72
  236. package/src/server/auth.ts +600 -74
  237. package/src/server/authorize.ts +816 -0
  238. package/src/server/clients.ts +235 -0
  239. package/src/server/config.ts +7 -0
  240. package/src/server/data.ts +59 -1
  241. package/src/server/directory.ts +91 -0
  242. package/src/server/feed.ts +277 -0
  243. package/src/server/handle.ts +172 -0
  244. package/src/server/hosted-pages.ts +532 -0
  245. package/src/server/hosted.ts +551 -18
  246. package/src/server/index.ts +353 -61
  247. package/src/server/mcp.ts +330 -0
  248. package/src/server/metering.ts +156 -0
  249. package/src/server/oauth-clients.ts +510 -0
  250. package/src/server/operator.ts +557 -0
  251. package/src/server/providers.ts +284 -0
  252. package/src/server/remove.ts +148 -0
  253. package/src/server/routing.ts +275 -0
  254. package/src/share/index.ts +50 -2
  255. package/src/verify/index.ts +7 -0
  256. package/src/verify/runner.ts +27 -2
  257. package/dist/instance-FExcyENK.js.map +0 -1
@@ -0,0 +1,235 @@
1
+ /**
2
+ * Who a request comes from, and how often (D165 item 13, FAILURE_MODEL §11.3). The server sits
3
+ * behind a TLS terminator, so the connection's peer is a proxy: `X-Forwarded-For` is believed only
4
+ * when the peer is one of `trustedProxies`, and read from the right, taking the first address that
5
+ * isn't a trusted proxy, so a forged leftmost entry is ignored. Rates key IPv6 addresses by their
6
+ * /64 (`rateLimits.ipv6Prefix`), so rotating addresses inside one allocation doesn't escape them.
7
+ *
8
+ * The rate limiter is a token bucket per key, in memory: a server setting, never operator
9
+ * policy, and with no setting there is no limit (D165 item 14).
10
+ */
11
+ import type { IncomingMessage } from "node:http";
12
+ import { isIPv4, isIPv6 } from "node:net";
13
+
14
+ /** An address range: an exact address, or a CIDR block (`10.0.0.0/8`, `fd00::/8`). */
15
+ interface Range {
16
+ readonly v6: boolean;
17
+ readonly bits: bigint;
18
+ readonly prefix: number;
19
+ }
20
+
21
+ /** An address as a number (IPv4 in 32 bits, IPv6 in 128), or `undefined` when it isn't one. */
22
+ function addressBits(address: string): { readonly v6: boolean; readonly bits: bigint } | undefined {
23
+ let text = address.trim();
24
+ if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
25
+ // An IPv4 address mapped into IPv6, as Node reports a dual-stack peer.
26
+ const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(text);
27
+ if (mapped) text = mapped[1] as string;
28
+ if (isIPv4(text)) {
29
+ const parts = text.split(".").map(Number);
30
+ return {
31
+ v6: false,
32
+ bits: parts.reduce((sum, part) => (sum << 8n) | BigInt(part), 0n),
33
+ };
34
+ }
35
+ if (!isIPv6(text)) return undefined;
36
+ const zone = text.indexOf("%");
37
+ if (zone !== -1) text = text.slice(0, zone);
38
+ // A trailing IPv4 part becomes two groups. It is what follows the last colon, read without a
39
+ // pattern: an address comes from a client's `X-Forwarded-For` (CodeQL js/polynomial-redos).
40
+ const last = text.slice(text.lastIndexOf(":") + 1);
41
+ if (last.includes(".")) {
42
+ if (!isIPv4(last)) return undefined;
43
+ const parts = last.split(".").map(Number);
44
+ const high = (((parts[0] as number) << 8) | (parts[1] as number)).toString(16);
45
+ const low = (((parts[2] as number) << 8) | (parts[3] as number)).toString(16);
46
+ text = `${text.slice(0, -last.length)}${high}:${low}`;
47
+ }
48
+ const [head, tail] = text.split("::") as [string, string | undefined];
49
+ const left = head === "" ? [] : head.split(":");
50
+ const right = tail === undefined ? [] : tail === "" ? [] : tail.split(":");
51
+ const groups =
52
+ tail === undefined
53
+ ? left
54
+ : [...left, ...new Array(8 - left.length - right.length).fill("0"), ...right];
55
+ if (groups.length !== 8) return undefined;
56
+ return {
57
+ v6: true,
58
+ bits: groups.reduce((sum, group) => (sum << 16n) | BigInt(Number.parseInt(group, 16)), 0n),
59
+ };
60
+ }
61
+
62
+ function parseRange(text: string): Range | undefined {
63
+ const [address, prefixText] = text.split("/") as [string, string | undefined];
64
+ const found = addressBits(address);
65
+ if (!found) return undefined;
66
+ const width = found.v6 ? 128 : 32;
67
+ const prefix = prefixText === undefined ? width : Number(prefixText);
68
+ if (!Number.isInteger(prefix) || prefix < 0 || prefix > width) return undefined;
69
+ return { v6: found.v6, bits: found.bits, prefix };
70
+ }
71
+
72
+ function inRange(range: Range, address: { readonly v6: boolean; readonly bits: bigint }): boolean {
73
+ if (range.v6 !== address.v6) return false;
74
+ const width = range.v6 ? 128n : 32n;
75
+ const shift = width - BigInt(range.prefix);
76
+ return range.bits >> shift === address.bits >> shift;
77
+ }
78
+
79
+ /** Whether every entry of `trustedProxies` is an address or a CIDR block. */
80
+ export function validProxies(entries: readonly string[]): string | undefined {
81
+ return entries.find((entry) => parseRange(entry) === undefined);
82
+ }
83
+
84
+ /** Resolves a request's client address through the configured trusted proxies. */
85
+ export interface ClientAddresses {
86
+ /** The client's address: the peer's, or the forwarded one when the peer is a trusted proxy. */
87
+ of(incoming: IncomingMessage): string | undefined;
88
+ /** The key a rate counts the address under: the address, or its IPv6 prefix. */
89
+ keyOf(address: string | undefined): string;
90
+ }
91
+
92
+ /** Options for {@link clientAddresses}. */
93
+ export interface ClientAddressOptions {
94
+ readonly trustedProxies?: readonly string[] | undefined;
95
+ /** IPv6 addresses count per this prefix (default 64). */
96
+ readonly ipv6Prefix?: number | undefined;
97
+ }
98
+
99
+ /** Builds the resolver; an entry that isn't an address or a block is ignored (checked at start). */
100
+ export function clientAddresses(options: ClientAddressOptions): ClientAddresses {
101
+ const proxies = (options.trustedProxies ?? [])
102
+ .map(parseRange)
103
+ .filter((range): range is Range => range !== undefined);
104
+ const trusted = (address: string): boolean => {
105
+ const bits = addressBits(address);
106
+ return bits !== undefined && proxies.some((range) => inRange(range, bits));
107
+ };
108
+ const ipv6Prefix = options.ipv6Prefix ?? 64;
109
+ const seen = new WeakMap<IncomingMessage, string | undefined>();
110
+ return {
111
+ of(incoming) {
112
+ if (seen.has(incoming)) return seen.get(incoming);
113
+ const peer = incoming.socket.remoteAddress;
114
+ let client = peer;
115
+ if (peer !== undefined && trusted(peer)) {
116
+ const header = incoming.headers["x-forwarded-for"];
117
+ const entries = (Array.isArray(header) ? header.join(",") : (header ?? ""))
118
+ .split(",")
119
+ .map((entry) => entry.trim())
120
+ .filter((entry) => entry !== "");
121
+ // From the right: each hop appends the address it saw; the first one that isn't one of
122
+ // ours is the client. Anything to its left was written by the client and is believed by
123
+ // no one.
124
+ for (let index = entries.length - 1; index >= 0; index--) {
125
+ const entry = entries[index] as string;
126
+ if (addressBits(entry) === undefined) break;
127
+ client = entry;
128
+ if (!trusted(entry)) break;
129
+ }
130
+ }
131
+ seen.set(incoming, client);
132
+ return client;
133
+ },
134
+ keyOf(address) {
135
+ if (address === undefined) return "unknown";
136
+ const bits = addressBits(address);
137
+ if (!bits) return `other:${address}`;
138
+ if (!bits.v6) return `v4:${bits.bits.toString(16)}`;
139
+ const shift = 128n - BigInt(ipv6Prefix);
140
+ return `v6:${(bits.bits >> shift).toString(16)}/${ipv6Prefix}`;
141
+ },
142
+ };
143
+ }
144
+
145
+ /** A rate: `count` per `perMs`. */
146
+ export interface RateLimit {
147
+ readonly count: number;
148
+ readonly perMs: number;
149
+ }
150
+
151
+ /**
152
+ * A token-bucket rate limiter over keys, in memory, bounded in the keys it keeps: each key holds up
153
+ * to `count` tokens and earns them back at `count` per `perMs`, so a burst of `count` passes and
154
+ * the sustained rate is exactly the rate.
155
+ */
156
+ export class RateLimiter {
157
+ readonly #buckets = new Map<string, { tokens: number; at: number }>();
158
+ readonly #now: () => number;
159
+ readonly #maxKeys: number;
160
+
161
+ constructor(options: { readonly now?: () => number; readonly maxKeys?: number } = {}) {
162
+ this.#now = options.now ?? (() => Date.now());
163
+ this.#maxKeys = options.maxKeys ?? 100_000;
164
+ }
165
+
166
+ /** A key's bucket, refilled to now and marked most recently used, so the bound drops the least. */
167
+ #bucket(key: string, rate: RateLimit, now: number): { tokens: number; at: number } {
168
+ const perToken = rate.perMs / rate.count;
169
+ let bucket = this.#buckets.get(key);
170
+ if (bucket) {
171
+ bucket.tokens = Math.min(rate.count, bucket.tokens + (now - bucket.at) / perToken);
172
+ bucket.at = now;
173
+ this.#buckets.delete(key);
174
+ } else {
175
+ if (this.#buckets.size >= this.#maxKeys) {
176
+ this.#buckets.delete(this.#buckets.keys().next().value as string);
177
+ }
178
+ bucket = { tokens: rate.count, at: now };
179
+ }
180
+ this.#buckets.set(key, bucket);
181
+ return bucket;
182
+ }
183
+
184
+ /** How long until every bucket holds a token: 0 when they all do now. */
185
+ #wait(
186
+ wanted: readonly { readonly key: string; readonly rate: RateLimit }[],
187
+ now: number,
188
+ ): { readonly waitMs: number; readonly buckets: { tokens: number }[] } {
189
+ let waitMs = 0;
190
+ const buckets = wanted.map(({ key, rate }) => {
191
+ const bucket = this.#bucket(key, rate, now);
192
+ if (bucket.tokens < 1)
193
+ waitMs = Math.max(waitMs, (1 - bucket.tokens) * (rate.perMs / rate.count));
194
+ return bucket;
195
+ });
196
+ return { waitMs, buckets };
197
+ }
198
+
199
+ /**
200
+ * Takes one token under `key` when there is one. Without one, nothing is taken and the answer
201
+ * says when to try again, in whole seconds (`Retry-After`).
202
+ */
203
+ take(
204
+ key: string,
205
+ rate: RateLimit,
206
+ ): { readonly ok: true } | { readonly ok: false; readonly retryAfterS: number } {
207
+ return this.takeAll([{ key, rate }]);
208
+ }
209
+
210
+ /**
211
+ * Gives back the token `takeAll` took under every key, as far as each bucket's size: an attempt
212
+ * someone refused after the rates admitted it (the operator's `limits`) costs nothing (second
213
+ * Fable review of WP-30, 2).
214
+ */
215
+ refundAll(wanted: readonly { readonly key: string; readonly rate: RateLimit }[]): void {
216
+ const now = this.#now();
217
+ for (const { key, rate } of wanted) {
218
+ const bucket = this.#bucket(key, rate, now);
219
+ bucket.tokens = Math.min(rate.count, bucket.tokens + 1);
220
+ }
221
+ }
222
+
223
+ /**
224
+ * Takes one token under every key, or none: when any bucket is empty, nothing is taken from the
225
+ * others, and the answer says when the slowest one has a token again (Fable review, 8).
226
+ */
227
+ takeAll(
228
+ wanted: readonly { readonly key: string; readonly rate: RateLimit }[],
229
+ ): { readonly ok: true } | { readonly ok: false; readonly retryAfterS: number } {
230
+ const { waitMs, buckets } = this.#wait(wanted, this.#now());
231
+ if (waitMs > 0) return { ok: false, retryAfterS: Math.max(1, Math.ceil(waitMs / 1000)) };
232
+ for (const bucket of buckets) bucket.tokens -= 1;
233
+ return { ok: true };
234
+ }
235
+ }
@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
8
8
  import { createDiagnostic, Duration, RpcError } from "@mostra/protocol";
9
9
  import * as z from "zod";
10
10
  import type { Environment } from "../log.ts";
11
+ import { validProxies } from "./clients.ts";
11
12
 
12
13
  /** A rate: `count` per `per` (a duration such as `1m`, as links' lifetimes are written). */
13
14
  const RateSchema: z.ZodType<Rate> = z.object({
@@ -214,6 +215,12 @@ export function readServerConfig(file: string | undefined, env: Environment): Re
214
215
  "The configuration key `apiOrigin` can't be on a user-content domain: sign-in and the binding live apart from tenant pages (D165 item 7).",
215
216
  );
216
217
  }
218
+ const proxy = validProxies(config.trustedProxies ?? []);
219
+ if (proxy !== undefined) {
220
+ throw invalid(
221
+ `The configuration key \`trustedProxies\` names ${JSON.stringify(proxy)}, which is neither an address nor a CIDR block.`,
222
+ );
223
+ }
217
224
  if (new Set(domains).size !== domains.length) {
218
225
  throw invalid("The configuration key `domains` names one domain twice.");
219
226
  }
@@ -59,6 +59,21 @@ export interface DataDirectory<T> {
59
59
  open(): readonly string[];
60
60
  /** Notes that a home was used now, so it isn't closed while used. */
61
61
  touch(id: string): void;
62
+ /**
63
+ * Closes a home now, if open, and holds it closed until `undrain` (`ServerHandle.drainHome`):
64
+ * every request for it meanwhile is refused with `MOSTRA_REMOTE_HOME_MOVING`, so two data
65
+ * directories never serve one home at once.
66
+ */
67
+ drain(id: string): Promise<void>;
68
+ /** Serves a drained home again (`ServerHandle.releaseHome`). */
69
+ undrain(id: string): void;
70
+ /**
71
+ * A restore from a backup by hand (`ServerHandle.restored`): the home is closed and rotates its
72
+ * incarnation before it serves anything again.
73
+ */
74
+ restored(id: string): Promise<void>;
75
+ /** Closes a home now if open (it reopens on its next request). */
76
+ closeHome(id: string): Promise<void>;
62
77
  /** Closes every home, then the directory, then releases the lock. */
63
78
  close(): Promise<void>;
64
79
  }
@@ -192,13 +207,23 @@ export async function openDataDirectory<T>(
192
207
 
193
208
  const openHome = async (id: string): Promise<OpenedHome<T>> => {
194
209
  const row = directory.read((db) =>
195
- db.get<{ data_path: string }>("SELECT data_path FROM home WHERE id = ?", id),
210
+ db.get<{ data_path: string; drained_at: string | null }>(
211
+ "SELECT data_path, drained_at FROM home WHERE id = ?",
212
+ id,
213
+ ),
196
214
  );
197
215
  if (!row) {
198
216
  throw new RpcError(
199
217
  createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message: `No hosted home ${id}.` }),
200
218
  );
201
219
  }
220
+ if (row.drained_at !== null) {
221
+ throw new RpcError(
222
+ createDiagnostic("MOSTRA_REMOTE_HOME_MOVING", {
223
+ message: "This account's pages are moving to another machine; try again in a minute.",
224
+ }),
225
+ );
226
+ }
202
227
  const homeDir = join(dir, row.data_path);
203
228
  mkdirSync(homeDir, { recursive: true, mode: 0o700 });
204
229
  const lock = holdLock(join(homeDir, "home.lock"), options.owner);
@@ -353,6 +378,39 @@ export async function openDataDirectory<T>(
353
378
  const entry = entries.get(id);
354
379
  if (entry) entry.lastUsed = Date.now();
355
380
  },
381
+ async closeHome(id) {
382
+ const entry = entries.get(id);
383
+ if (!entry) return;
384
+ entry.closing ??= closeHome(id, entry);
385
+ await entry.closing;
386
+ },
387
+ async drain(id) {
388
+ directory.write((db) =>
389
+ db.run(
390
+ "UPDATE home SET drained_at = COALESCE(drained_at, ?) WHERE id = ?",
391
+ new Date().toISOString(),
392
+ id,
393
+ ),
394
+ );
395
+ const entry = entries.get(id);
396
+ if (entry) {
397
+ entry.closing ??= closeHome(id, entry);
398
+ await entry.closing;
399
+ }
400
+ log.info("server.home_drained", { home: id });
401
+ },
402
+ undrain(id) {
403
+ directory.write((db) => db.run("UPDATE home SET drained_at = NULL WHERE id = ?", id));
404
+ log.info("server.home_released", { home: id });
405
+ },
406
+ async restored(id) {
407
+ restores.add(id);
408
+ const entry = entries.get(id);
409
+ if (entry) {
410
+ entry.closing ??= closeHome(id, entry);
411
+ await entry.closing;
412
+ }
413
+ },
356
414
  async close() {
357
415
  if (closed) return;
358
416
  closed = true;
@@ -138,4 +138,95 @@ export const SERVER_MIGRATIONS: readonly Migration[] = [
138
138
  `);
139
139
  },
140
140
  },
141
+ {
142
+ version: 2,
143
+ name: "operator, sign-in and links",
144
+ up(db) {
145
+ // WP-30 (DATA_MODEL §7.1, additive). A home an operator drained is refused until released;
146
+ // the hosted links of every home, so a handle's revokeLink finds its home; the instance link
147
+ // of each operator-issued credential; sign-ins in progress and the API origin's browser
148
+ // sessions (both by SHA-256 only); and the monthly metering keys' months.
149
+ db.exec(`
150
+ ALTER TABLE home ADD COLUMN drained_at TEXT;
151
+ ALTER TABLE home ADD COLUMN suspend_reason TEXT;
152
+ CREATE TABLE hosted_token (
153
+ token_id TEXT PRIMARY KEY,
154
+ home_id TEXT NOT NULL REFERENCES home(id),
155
+ route_id TEXT NOT NULL
156
+ );
157
+ CREATE TABLE credential_link (
158
+ account_id TEXT NOT NULL REFERENCES account(id),
159
+ subject TEXT NOT NULL,
160
+ link_id TEXT NOT NULL REFERENCES instance_link(id),
161
+ PRIMARY KEY (account_id, subject)
162
+ );
163
+ CREATE TABLE signin (
164
+ hash TEXT PRIMARY KEY,
165
+ kind TEXT NOT NULL CHECK (kind IN ('provider', 'step', 'authorize')),
166
+ data_json TEXT NOT NULL,
167
+ expires_at TEXT NOT NULL
168
+ );
169
+ CREATE TABLE browser_session (
170
+ hash TEXT PRIMARY KEY,
171
+ account_id TEXT NOT NULL REFERENCES account(id),
172
+ created_at TEXT NOT NULL,
173
+ expires_at TEXT NOT NULL
174
+ );
175
+ CREATE INDEX browser_session_account ON browser_session(account_id);
176
+ -- A host an operator supplies through routing (D165 item 7, D167): a hosted shell for one
177
+ -- home (or one route of it), its frames on <label>.<frame_domain>. Recorded with its
178
+ -- label_issued row when first served, kept forever and never moved to another home.
179
+ CREATE TABLE operator_host (
180
+ host TEXT PRIMARY KEY,
181
+ home_id TEXT NOT NULL REFERENCES home(id),
182
+ route_id TEXT,
183
+ frame_domain TEXT NOT NULL,
184
+ recorded_at TEXT NOT NULL
185
+ );
186
+ CREATE INDEX operator_host_frames ON operator_host(frame_domain);
187
+ CREATE TRIGGER operator_host_kept BEFORE DELETE ON operator_host
188
+ BEGIN
189
+ SELECT RAISE(ABORT, 'an operator host is kept forever');
190
+ END;
191
+ CREATE TRIGGER operator_host_fixed BEFORE UPDATE ON operator_host
192
+ WHEN NEW.host IS NOT OLD.host OR NEW.home_id IS NOT OLD.home_id
193
+ BEGIN
194
+ SELECT RAISE(ABORT, 'an operator host never moves to another home');
195
+ END;
196
+ `);
197
+ },
198
+ },
199
+ {
200
+ version: 3,
201
+ name: "a route's removal in progress",
202
+ up(db) {
203
+ // ServerHandle.remove spans two databases, the home's ledger and this directory, so it
204
+ // records its plan here first (the versions and client files it removes); a removal cut
205
+ // off between them is finished by the next call, and the route serves nothing meanwhile
206
+ // (Fable review of WP-30, 4).
207
+ db.exec("ALTER TABLE artifact_route ADD COLUMN removing_json TEXT");
208
+ },
209
+ },
210
+ {
211
+ version: 4,
212
+ name: "invitations in the outbound queue",
213
+ up(db) {
214
+ // WP-31 (D168): the operator's `invitations` port is delivered like `events` and `metering`,
215
+ // at least once from the same queue; a row keeps the link's token, never its URL. SQLite
216
+ // can't widen a CHECK in place, so the table is rebuilt with every row it holds.
217
+ db.exec(`
218
+ CREATE TABLE outbound_next (
219
+ id TEXT PRIMARY KEY,
220
+ port TEXT NOT NULL CHECK (port IN ('metering', 'events', 'invitations')),
221
+ payload_json TEXT NOT NULL,
222
+ attempts INTEGER NOT NULL DEFAULT 0,
223
+ next_attempt_at TEXT NOT NULL
224
+ );
225
+ INSERT INTO outbound_next (rowid, id, port, payload_json, attempts, next_attempt_at)
226
+ SELECT rowid, id, port, payload_json, attempts, next_attempt_at FROM outbound;
227
+ DROP TABLE outbound;
228
+ ALTER TABLE outbound_next RENAME TO outbound;
229
+ `);
230
+ },
231
+ },
141
232
  ];