@mostra/runtime 0.9.0 → 0.11.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 (279) hide show
  1. package/dist/bin.js +6628 -9
  2. package/dist/bin.js.map +1 -1
  3. package/dist/builder/child/main.js +2 -2
  4. package/dist/{child-Chiavhdx.js → child-BmNZ4a70.js} +2 -2
  5. package/dist/{child-Chiavhdx.js.map → child-BmNZ4a70.js.map} +1 -1
  6. package/dist/deps/child/install.js +1 -1
  7. package/dist/{directories-mJ1qlVht.js → directories-BLJjeSPD.js} +5 -5
  8. package/dist/directories-BLJjeSPD.js.map +1 -0
  9. package/dist/{files-FygSJIzK.js → files-DGeWuE4I.js} +2 -2
  10. package/dist/{files-FygSJIzK.js.map → files-DGeWuE4I.js.map} +1 -1
  11. package/dist/index.d.ts +2 -0
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +2 -2
  14. package/dist/{instance-EnaZPs14.js → instance-DCiUHvgZ.js} +3835 -255
  15. package/dist/instance-DCiUHvgZ.js.map +1 -0
  16. package/dist/reference/cli.md +1322 -0
  17. package/dist/reference/diagnostics.json +1552 -0
  18. package/dist/reference/errors/MOSTRA_A11Y_MINOR.md +23 -0
  19. package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md +23 -0
  20. package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md +23 -0
  21. package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md +23 -0
  23. package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md +23 -0
  24. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md +23 -0
  26. package/dist/reference/errors/MOSTRA_ACTION_THREW.md +23 -0
  27. package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md +23 -0
  28. package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md +23 -0
  29. package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md +23 -0
  30. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  31. package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md +23 -0
  32. package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md +23 -0
  33. package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
  34. package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md +23 -0
  35. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md +23 -0
  36. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md +23 -0
  37. package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
  38. package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
  39. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md +23 -0
  40. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md +23 -0
  41. package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md +23 -0
  42. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md +23 -0
  43. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md +23 -0
  44. package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md +23 -0
  45. package/dist/reference/errors/MOSTRA_BUILD_FAILED.md +23 -0
  46. package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md +23 -0
  47. package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md +23 -0
  48. package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md +23 -0
  49. package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md +23 -0
  50. package/dist/reference/errors/MOSTRA_CLI_USAGE.md +23 -0
  51. package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md +23 -0
  52. package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md +23 -0
  53. package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md +23 -0
  54. package/dist/reference/errors/MOSTRA_DEP_MISSING.md +23 -0
  55. package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md +23 -0
  56. package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md +23 -0
  57. package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md +23 -0
  58. package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md +23 -0
  59. package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md +23 -0
  60. package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md +23 -0
  61. package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md +23 -0
  62. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md +23 -0
  63. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md +23 -0
  64. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md +23 -0
  65. package/dist/reference/errors/MOSTRA_ENV_HELPER_MISSING.md +23 -0
  66. package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md +23 -0
  67. package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md +23 -0
  68. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
  69. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md +23 -0
  70. package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md +23 -0
  71. package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md +23 -0
  72. package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md +23 -0
  73. package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md +23 -0
  74. package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md +23 -0
  75. package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md +23 -0
  76. package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md +23 -0
  77. package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md +23 -0
  78. package/dist/reference/errors/MOSTRA_FIELD_SHARED.md +23 -0
  79. package/dist/reference/errors/MOSTRA_FIELD_TOO_LARGE.md +23 -0
  80. package/dist/reference/errors/MOSTRA_FIELD_UNBOUND.md +23 -0
  81. package/dist/reference/errors/MOSTRA_HOME_DISK_FULL.md +23 -0
  82. package/dist/reference/errors/MOSTRA_HOME_GC_INCOMPLETE.md +23 -0
  83. package/dist/reference/errors/MOSTRA_HOME_GONE.md +23 -0
  84. package/dist/reference/errors/MOSTRA_HOME_INTEGRITY.md +23 -0
  85. package/dist/reference/errors/MOSTRA_HOME_LEDGER_UNREADABLE.md +23 -0
  86. package/dist/reference/errors/MOSTRA_HOME_LOCKED.md +23 -0
  87. package/dist/reference/errors/MOSTRA_HOME_MISMATCH.md +23 -0
  88. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  89. package/dist/reference/errors/MOSTRA_HOME_NOT_ALWAYS_ON.md +23 -0
  90. package/dist/reference/errors/MOSTRA_HOME_NOT_OWNED.md +23 -0
  91. package/dist/reference/errors/MOSTRA_HOME_SOCKET_TOO_LONG.md +23 -0
  92. package/dist/reference/errors/MOSTRA_HOME_TOO_NEW.md +23 -0
  93. package/dist/reference/errors/MOSTRA_HOST_CONNECTION_CLOSED.md +23 -0
  94. package/dist/reference/errors/MOSTRA_HOST_CURSOR_COMPACTED.md +23 -0
  95. package/dist/reference/errors/MOSTRA_HOST_IDENTITY_UNAVAILABLE.md +23 -0
  96. package/dist/reference/errors/MOSTRA_HOST_INITIALIZE_ORDER.md +23 -0
  97. package/dist/reference/errors/MOSTRA_HOST_INTERNAL_ERROR.md +23 -0
  98. package/dist/reference/errors/MOSTRA_HOST_INVALID_PARAMS.md +23 -0
  99. package/dist/reference/errors/MOSTRA_HOST_MALFORMED.md +23 -0
  100. package/dist/reference/errors/MOSTRA_HOST_MESSAGE_TOO_LARGE.md +23 -0
  101. package/dist/reference/errors/MOSTRA_HOST_METHOD_UNKNOWN.md +23 -0
  102. package/dist/reference/errors/MOSTRA_HOST_NOTIFICATION_UNSUPPORTED.md +23 -0
  103. package/dist/reference/errors/MOSTRA_HOST_PORT_UNSUPPORTED.md +23 -0
  104. package/dist/reference/errors/MOSTRA_HOST_REQUEST_ID_REUSED.md +23 -0
  105. package/dist/reference/errors/MOSTRA_HOST_REVISION_UNSUPPORTED.md +23 -0
  106. package/dist/reference/errors/MOSTRA_HOST_SHUTDOWN_REFUSED.md +23 -0
  107. package/dist/reference/errors/MOSTRA_HOST_SUBSCRIPTION_UNKNOWN.md +23 -0
  108. package/dist/reference/errors/MOSTRA_HOST_TIMEOUT.md +23 -0
  109. package/dist/reference/errors/MOSTRA_HYGIENE_CONTENT_TYPE.md +23 -0
  110. package/dist/reference/errors/MOSTRA_HYGIENE_CSRF_MISSING.md +23 -0
  111. package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
  112. package/dist/reference/errors/MOSTRA_HYGIENE_HEADERS_TOO_LARGE.md +23 -0
  113. package/dist/reference/errors/MOSTRA_HYGIENE_HOST_REFUSED.md +23 -0
  114. package/dist/reference/errors/MOSTRA_HYGIENE_NOT_SERVED.md +23 -0
  115. package/dist/reference/errors/MOSTRA_HYGIENE_ORIGIN_REFUSED.md +23 -0
  116. package/dist/reference/errors/MOSTRA_HYGIENE_RATE_LIMITED.md +23 -0
  117. package/dist/reference/errors/MOSTRA_HYGIENE_REQUEST_MALFORMED.md +23 -0
  118. package/dist/reference/errors/MOSTRA_HYGIENE_SCOPE_DENIED.md +23 -0
  119. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_CONFLICT.md +23 -0
  120. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_MISSING.md +23 -0
  121. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_INVALID.md +23 -0
  122. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_REVOKED.md +23 -0
  123. package/dist/reference/errors/MOSTRA_LIVE_SOURCE_FAILED.md +23 -0
  124. package/dist/reference/errors/MOSTRA_LIVE_TOO_LARGE.md +23 -0
  125. package/dist/reference/errors/MOSTRA_MANIFEST_INVALID.md +23 -0
  126. package/dist/reference/errors/MOSTRA_MANIFEST_NOT_LITERAL.md +23 -0
  127. package/dist/reference/errors/MOSTRA_MANIFEST_UNKNOWN_KEY.md +23 -0
  128. package/dist/reference/errors/MOSTRA_NETWORK_EXTERNAL_FAILED.md +23 -0
  129. package/dist/reference/errors/MOSTRA_NETWORK_REQUEST_FAILED.md +23 -0
  130. package/dist/reference/errors/MOSTRA_PLATFORM_UNSUPPORTED.md +23 -0
  131. package/dist/reference/errors/MOSTRA_PUBLISH_ID_CONFLICT.md +23 -0
  132. package/dist/reference/errors/MOSTRA_PUBLISH_SOURCE_CHANGED.md +23 -0
  133. package/dist/reference/errors/MOSTRA_PUBLISH_VERIFY_FAILED.md +23 -0
  134. package/dist/reference/errors/MOSTRA_REGRESSION_ACTION_REMOVED.md +23 -0
  135. package/dist/reference/errors/MOSTRA_REGRESSION_ARIA.md +23 -0
  136. package/dist/reference/errors/MOSTRA_REGRESSION_FIELD_REMOVED.md +23 -0
  137. package/dist/reference/errors/MOSTRA_REGRESSION_LIVE_REMOVED.md +23 -0
  138. package/dist/reference/errors/MOSTRA_REGRESSION_PAGE_REMOVED.md +23 -0
  139. package/dist/reference/errors/MOSTRA_REGRESSION_PIXELS.md +23 -0
  140. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  141. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  142. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  143. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
  144. package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
  145. package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
  146. package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
  147. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  148. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  149. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  150. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  151. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  152. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  153. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  154. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  155. package/dist/reference/errors/MOSTRA_RUNTIME_BLANK.md +23 -0
  156. package/dist/reference/errors/MOSTRA_RUNTIME_NOT_READY.md +23 -0
  157. package/dist/reference/errors/MOSTRA_RUNTIME_PAGE_ERROR.md +23 -0
  158. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_CRASHED.md +23 -0
  159. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_PARKED.md +23 -0
  160. package/dist/reference/errors/MOSTRA_SECRET_MISSING.md +23 -0
  161. package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
  162. package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
  163. package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
  164. package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
  165. package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
  166. package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
  167. package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
  168. package/dist/reference/errors/MOSTRA_SMOKE_BUDGET.md +23 -0
  169. package/dist/reference/errors/MOSTRA_SMOKE_NO_EFFECT.md +23 -0
  170. package/dist/reference/errors/MOSTRA_SUBMIT_ALREADY.md +23 -0
  171. package/dist/reference/errors/MOSTRA_SUBMIT_BLOCKED.md +23 -0
  172. package/dist/reference/errors/MOSTRA_SUBMIT_CHANNEL_DENIED.md +23 -0
  173. package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +23 -0
  174. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  175. package/dist/reference/errors/MOSTRA_SUBMIT_POLICY_NONE.md +23 -0
  176. package/dist/reference/errors/MOSTRA_SUBMIT_REVISION_MOVED.md +23 -0
  177. package/dist/reference/errors/MOSTRA_SUBMIT_SIGNAL_INVALID.md +23 -0
  178. package/dist/reference/errors/MOSTRA_SUBMIT_VIEW_INVALID.md +23 -0
  179. package/dist/reference/errors/MOSTRA_TARGET_UNAVAILABLE.md +23 -0
  180. package/dist/reference/errors/MOSTRA_TYPE_ERROR.md +23 -0
  181. package/dist/reference/errors/MOSTRA_TYPE_UNTYPED_PACKAGE.md +23 -0
  182. package/dist/reference/errors/MOSTRA_VERIFY_ACTION_SKIPPED.md +23 -0
  183. package/dist/reference/errors/MOSTRA_VERIFY_BASELINE_MISSING.md +23 -0
  184. package/dist/reference/errors/MOSTRA_VERIFY_CRASHED.md +23 -0
  185. package/dist/reference/errors/MOSTRA_VERIFY_LIVE_FAILED.md +23 -0
  186. package/dist/reference/errors/MOSTRA_VERIFY_NO_BASELINE.md +23 -0
  187. package/dist/reference/errors/MOSTRA_VERIFY_SECRET_MISSING.md +23 -0
  188. package/dist/reference/errors/MOSTRA_VERIFY_SKIP_CONSEQUENCE.md +23 -0
  189. package/dist/reference/errors/MOSTRA_VERIFY_TIMEOUT.md +23 -0
  190. package/dist/reference/self-hosting.md +130 -0
  191. package/dist/reference/telemetry.md +84 -0
  192. package/dist/skill/SKILL.md +122 -0
  193. package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
  194. package/dist/skill/assets/examples/dashboard/live.ts +25 -0
  195. package/dist/skill/assets/examples/dashboard/styles.css +125 -0
  196. package/dist/skill/assets/examples/decision/index.tsx +95 -0
  197. package/dist/skill/assets/examples/decision/styles.css +125 -0
  198. package/dist/skill/assets/examples/inbox/actions.ts +23 -0
  199. package/dist/skill/assets/examples/inbox/index.tsx +109 -0
  200. package/dist/skill/assets/examples/inbox/styles.css +125 -0
  201. package/dist/skill/assets/studio.css +125 -0
  202. package/dist/skill/references/answers.md +217 -0
  203. package/dist/skill/references/design.md +154 -0
  204. package/dist/skill/references/libraries.md +167 -0
  205. package/dist/skill/references/long-lived.md +148 -0
  206. package/dist/skill/references/mcp.md +68 -0
  207. package/dist/skill/references/page.md +131 -0
  208. package/dist/skill/references/server.md +146 -0
  209. package/dist/skill/references/sharing.md +123 -0
  210. package/dist/skill/references/verify.md +71 -0
  211. package/package.json +12 -5
  212. package/src/actions/index.ts +163 -10
  213. package/src/bin.ts +78 -1
  214. package/src/gateway/actions.ts +40 -4
  215. package/src/gateway/browser.ts +162 -95
  216. package/src/gateway/capabilities.ts +23 -6
  217. package/src/gateway/http.ts +12 -1
  218. package/src/gateway/index.ts +282 -20
  219. package/src/gateway/listener.ts +31 -6
  220. package/src/gateway/routes.ts +23 -7
  221. package/src/gc/index.ts +19 -0
  222. package/src/instance/index.ts +60 -2
  223. package/src/interaction/ephemeral.ts +32 -23
  224. package/src/interaction/events.ts +21 -1
  225. package/src/interaction/imports.ts +317 -0
  226. package/src/interaction/index.ts +228 -15
  227. package/src/interaction/outbox.ts +9 -0
  228. package/src/interaction/pause.ts +106 -0
  229. package/src/interaction/results.ts +8 -1
  230. package/src/interaction/runs.ts +52 -2
  231. package/src/interaction/submissions.ts +59 -2
  232. package/src/interaction/tally.ts +129 -0
  233. package/src/interaction/viewers.ts +34 -1
  234. package/src/ledger/index.ts +124 -10
  235. package/src/ledger/migrations.ts +234 -0
  236. package/src/ledger/types.ts +8 -0
  237. package/src/link/author.ts +215 -0
  238. package/src/link/binding.ts +289 -0
  239. package/src/link/hosted.ts +101 -0
  240. package/src/link/http.ts +141 -0
  241. package/src/link/index.ts +10 -0
  242. package/src/link/manager.ts +1489 -0
  243. package/src/link/relay.ts +512 -0
  244. package/src/live/index.ts +112 -2
  245. package/src/platform/filesystems.ts +78 -0
  246. package/src/platform/index.ts +1 -0
  247. package/src/protocol-server/client.ts +53 -0
  248. package/src/protocol-server/index.ts +19 -2
  249. package/src/protocol-server/server.ts +38 -7
  250. package/src/protocol-server/websocket.ts +161 -0
  251. package/src/publish/bundle.ts +398 -0
  252. package/src/publish/manifest.ts +9 -0
  253. package/src/publish/methods.ts +12 -1
  254. package/src/publish/publisher.ts +127 -0
  255. package/src/registry/index.ts +35 -14
  256. package/src/server/api.ts +881 -0
  257. package/src/server/auth.ts +1139 -0
  258. package/src/server/authorize.ts +816 -0
  259. package/src/server/clients.ts +235 -0
  260. package/src/server/config.ts +228 -0
  261. package/src/server/data.ts +427 -0
  262. package/src/server/directory.ts +210 -0
  263. package/src/server/feed.ts +191 -0
  264. package/src/server/handle.ts +172 -0
  265. package/src/server/hosted-pages.ts +532 -0
  266. package/src/server/hosted.ts +1323 -0
  267. package/src/server/index.ts +650 -0
  268. package/src/server/mcp.ts +330 -0
  269. package/src/server/metering.ts +156 -0
  270. package/src/server/oauth-clients.ts +510 -0
  271. package/src/server/operator.ts +498 -0
  272. package/src/server/providers.ts +284 -0
  273. package/src/server/relay.ts +1163 -0
  274. package/src/server/remove.ts +148 -0
  275. package/src/server/routing.ts +275 -0
  276. package/src/share/index.ts +110 -6
  277. package/src/verify/runner.ts +23 -2
  278. package/dist/directories-mJ1qlVht.js.map +0 -1
  279. package/dist/instance-EnaZPs14.js.map +0 -1
@@ -0,0 +1,1489 @@
1
+ /**
2
+ * The owner instance's links to remote servers (ARCHITECTURE §15.3, INTERFACES §18.2, D165 items 1
3
+ * to 3): sign-in by the device grant, the refresh token kept in the home and the access token in
4
+ * memory, one binding per signed-in server, and over it the hosted home's deliveries (imported into
5
+ * this home's ledger and its own outbox in one transaction), the sync cursor (the hosted home's
6
+ * events copied once each), and version pushes, queued while a server can't be reached.
7
+ */
8
+ import { createHash, randomUUID } from "node:crypto";
9
+ import {
10
+ appendFileSync,
11
+ existsSync,
12
+ mkdirSync,
13
+ readdirSync,
14
+ readFileSync,
15
+ rmSync,
16
+ writeFileSync,
17
+ } from "node:fs";
18
+ import { hostname } from "node:os";
19
+ import { join } from "node:path";
20
+ import {
21
+ createDiagnostic,
22
+ type EventsNotifyParams,
23
+ eventsAckMethod,
24
+ eventsSubscribeMethod,
25
+ type HostedPushResult,
26
+ type HostedRoute,
27
+ hostedPushMethod,
28
+ hostedSubmissionMethod,
29
+ LinkId,
30
+ type ListingEntry,
31
+ type MethodDefinition,
32
+ portRelayAuthorMethod,
33
+ portSubmissionsDeliverMethod,
34
+ type RemoteLink,
35
+ type RemoteLinkResult,
36
+ type RemoteLoginResult,
37
+ RpcError,
38
+ remoteLinkMethod,
39
+ remoteLoginMethod,
40
+ remoteLoginWaitMethod,
41
+ remoteLogoutMethod,
42
+ remoteStatusMethod,
43
+ remoteTokenMethod,
44
+ type ServerLiveValueParams,
45
+ SubmissionEnvelope,
46
+ type SubmissionPolicy,
47
+ type SubmissionsDeliverResult,
48
+ type VersionPush,
49
+ viewRevokeMethod,
50
+ viewUrlMethod,
51
+ } from "@mostra/protocol";
52
+ import { appendEvent, followEvents, type ImportSource } from "../interaction/index.ts";
53
+ import type { Ledger, LedgerDb } from "../ledger/index.ts";
54
+ import type { Environment, Log } from "../log.ts";
55
+ import { renamePathSync } from "../platform/index.ts";
56
+ import { handler, type MethodHandler } from "../protocol-server/index.ts";
57
+ import { listingDigest } from "../publish/index.ts";
58
+ import type { RemoteShares } from "../share/index.ts";
59
+ import { type Binding, type BindingSession, ownerInitialize, startBinding } from "./binding.ts";
60
+ import { postForm, type RemoteAddress, remoteRequest, testServerAddress } from "./http.ts";
61
+ import { createOwnerRelay, type OwnerRelayOptions } from "./relay.ts";
62
+
63
+ /** The CLI's client ID at every server's authorization server (D166 item 5). */
64
+ const CLIENT_ID = "mostra-cli";
65
+ const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
66
+ /** A token is refreshed this long before it expires, so a binding never meets its expiry. */
67
+ const REFRESH_AHEAD_MS = 5 * 60_000;
68
+ /** The first retry of a push that failed; each later one doubles, up to five minutes. */
69
+ const PUSH_RETRY_MS = 1_000;
70
+ const PUSH_RETRY_MAX_MS = 5 * 60_000;
71
+
72
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
73
+
74
+ /** A server's short, stable key: 16 Crockford base32 characters of the SHA-256 of its origin. */
75
+ /** Failures a push is tried again after: the connection, not the server's answer (§11.2). */
76
+ const PUSH_TRANSPORT_FAILURES: ReadonlySet<string> = new Set([
77
+ "MOSTRA_HOST_CONNECTION_CLOSED",
78
+ "MOSTRA_HOST_TIMEOUT",
79
+ "MOSTRA_REMOTE_UNREACHABLE",
80
+ "MOSTRA_REMOTE_LOGIN_FAILED",
81
+ "MOSTRA_REMOTE_OPERATOR_UNAVAILABLE",
82
+ "MOSTRA_REMOTE_RATE_LIMITED",
83
+ ]);
84
+
85
+ export function serverKey(server: string): string {
86
+ const digest = createHash("sha256").update(server, "utf8").digest();
87
+ let out = "";
88
+ let buffer = 0;
89
+ let bits = 0;
90
+ for (const byte of digest) {
91
+ buffer = ((buffer << 8) | byte) & 0xffff;
92
+ bits += 8;
93
+ while (bits >= 5 && out.length < 16) {
94
+ bits -= 5;
95
+ out += CROCKFORD.charAt((buffer >> bits) & 31);
96
+ }
97
+ if (out.length >= 16) break;
98
+ }
99
+ return out;
100
+ }
101
+
102
+ /** An API origin as the instance keeps it: scheme and host, no path. */
103
+ export function serverOrigin(value: string): string {
104
+ let url: URL;
105
+ try {
106
+ url = new URL(value.includes("://") ? value : `https://${value}`);
107
+ } catch {
108
+ throw invalid(`${value} isn't a server address.`);
109
+ }
110
+ if (url.protocol !== "https:" && url.protocol !== "http:")
111
+ throw invalid(`${value} isn't an https: address.`);
112
+ if (url.protocol === "http:" && !loopbackName(url.hostname)) {
113
+ throw invalid(`${value} must be https: (plain http is only for a server on this machine).`);
114
+ }
115
+ return url.origin;
116
+ }
117
+
118
+ function loopbackName(host: string): boolean {
119
+ return (
120
+ host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1" || host === "[::1]"
121
+ );
122
+ }
123
+
124
+ function invalid(message: string): RpcError {
125
+ return new RpcError(createDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message }));
126
+ }
127
+
128
+ function loginFailed(message: string): RpcError {
129
+ return new RpcError(createDiagnostic("MOSTRA_REMOTE_LOGIN_FAILED", { message }));
130
+ }
131
+
132
+ /** What the link keeps for a server in `<home>/keys/remote/<server key>.json` (DATA_MODEL §7.3). */
133
+ /**
134
+ * How this home signs in to a server: a person's sign-in (the device grant's refresh token, rotated
135
+ * at every use) or a key the server's operator issued (`remote/link`, D167), used as is.
136
+ */
137
+ type Credentials =
138
+ | { readonly server: string; readonly instanceId: string; readonly refreshToken: string }
139
+ | { readonly server: string; readonly instanceId: string; readonly key: string };
140
+
141
+ /** The secret a home's credentials hold. */
142
+ const credentialSecret = (credentials: Credentials): string =>
143
+ "key" in credentials ? credentials.key : credentials.refreshToken;
144
+
145
+ /** A `remote_link` row. */
146
+ interface LinkRow {
147
+ readonly server: string;
148
+ readonly account_id: string | null;
149
+ readonly account_name: string | null;
150
+ readonly instance_id: string | null;
151
+ readonly is_default: number;
152
+ readonly linked_at: string;
153
+ readonly state: "signed-in" | "signed-out";
154
+ readonly incarnation: string | null;
155
+ readonly follow_cursor: string | null;
156
+ readonly relay_mark: number;
157
+ }
158
+
159
+ /** What the link needs from the instance. */
160
+ export interface LinkOptions {
161
+ readonly home: string;
162
+ readonly ledger: Ledger;
163
+ readonly log: Log;
164
+ readonly env: Environment;
165
+ readonly runtimeVersion: string;
166
+ /** Registers a value no log or event may show (the instance's redactor). */
167
+ readonly protect: (value: string) => void;
168
+ /** Imports a delivered hosted submission (the interaction core's, D165 item 1). */
169
+ readonly importSubmission: (
170
+ envelope: SubmissionEnvelope,
171
+ source: ImportSource,
172
+ ) => SubmissionsDeliverResult;
173
+ /** A version's sealed directory. */
174
+ readonly versionDir: (versionId: string) => string;
175
+ /** Runs what hosted homes relay here (D165 item 4). */
176
+ readonly actions: OwnerRelayOptions["actions"];
177
+ /** Hosted pages' live interest changed. */
178
+ readonly liveChanged?: () => void;
179
+ /** Answers remote MCP's relayed authoring (`port/relay.author`, D165 item 5). */
180
+ readonly author?: (server: string, params: unknown) => Promise<unknown>;
181
+ /** The clock (tests move it). */
182
+ readonly now?: () => number;
183
+ }
184
+
185
+ /** A pushed version's answer: its hosted route. */
186
+ export interface Pushed {
187
+ readonly versionId: string;
188
+ readonly number: number;
189
+ readonly route: HostedRoute;
190
+ readonly server: string;
191
+ readonly home: string;
192
+ }
193
+
194
+ /** The owner's side of every remote server this home links to. */
195
+ export interface Link {
196
+ /** The `remote/*` methods for the instance's own clients. */
197
+ methods(): MethodHandler[];
198
+ /** Dials every server this home is signed in to. */
199
+ start(): void;
200
+ stop(): Promise<void>;
201
+ /** The server a name means: the given one, or the one signed in to last. */
202
+ resolveServer(server: string | undefined): string;
203
+ /**
204
+ * Hosts an artifact on a server: records it as hosted there and pushes its latest version, so
205
+ * every later publish follows (D165 item 3). Resolves once the server holds the version.
206
+ */
207
+ host(artifactId: string, server: string): Promise<Pushed>;
208
+ /** A publish of an artifact hosted somewhere: queue its push to every such server. */
209
+ published(artifactId: string, versionId: string): void;
210
+ /** The open session with a server's hosted home, waiting for one up to `timeoutMs`. */
211
+ session(server: string, timeoutMs?: number): Promise<BindingSession>;
212
+ /** Whether a server's binding is open now. */
213
+ connected(server: string): boolean;
214
+ /** `remote` shares (INTERFACES §18.2): hosted links minted on this home's hosted homes. */
215
+ shares(): RemoteShares;
216
+ /** This home's links, as `remote/status` answers them. */
217
+ status(): RemoteLink[];
218
+ /**
219
+ * The server an artifact is hosted on, whose hosted home holds its shared state and live values
220
+ * (D165 item 1); `undefined` for an artifact that isn't hosted. Shared to several servers, the
221
+ * first it was shared to.
222
+ */
223
+ hostedOn(artifactId: string): string | undefined;
224
+ /** Every server an artifact is hosted on now, in the order it was shared to them. */
225
+ hostedServers(artifactId: string): string[];
226
+ /**
227
+ * Calls a method on a server's hosted home for this home's client: a hosted artifact's
228
+ * `state/*` and `live/push` (D165 item 1). `MOSTRA_REMOTE_UNREACHABLE` when it can't be reached.
229
+ */
230
+ forward<P, R>(server: string, definition: MethodDefinition<P, R>, params: P): Promise<R>;
231
+ /** The live sources hosted pages want of this instance's producers (D165 item 4). */
232
+ liveInterest(): Iterable<{ readonly artifactId: string; readonly key: string }>;
233
+ /**
234
+ * A produced value of a hosted artifact goes to its hosted home, its one copy (D165 item 1):
235
+ * `true` when the artifact is hosted, and nothing is kept here.
236
+ */
237
+ forwardLive(
238
+ artifactId: string,
239
+ versionId: string,
240
+ produced: () => ServerLiveValueParams,
241
+ ): boolean;
242
+ }
243
+
244
+ /** One server's link at run time. */
245
+ interface Connection {
246
+ readonly server: string;
247
+ binding: Binding;
248
+ access?: { token: string; expiresAt: number };
249
+ refreshing?: Promise<string> | undefined;
250
+ refreshTimer?: ReturnType<typeof setTimeout> | undefined;
251
+ state: RemoteLink["state"];
252
+ since: string;
253
+ lastError?: string;
254
+ home?: string;
255
+ incarnation?: string;
256
+ pushing?: Promise<void> | undefined;
257
+ pushTimer?: ReturnType<typeof setTimeout> | undefined;
258
+ }
259
+
260
+ /** A sign-in in progress: the device grant's code and its outcome. */
261
+ interface Login {
262
+ readonly id: string;
263
+ readonly server: string;
264
+ readonly result: RemoteLoginResult;
265
+ outcome?:
266
+ | { ok: true; account: { id: string; name?: string }; instanceId: string }
267
+ | { ok: false; error: RpcError };
268
+ waiters: (() => void)[];
269
+ }
270
+
271
+ /** Creates the owner's link manager. */
272
+ export function createLink(options: LinkOptions): Link {
273
+ const { ledger, log } = options;
274
+ const now = options.now ?? Date.now;
275
+ const connectTo: RemoteAddress | undefined = testServerAddress(
276
+ options.env["MOSTRA_TEST_SERVER_ADDRESS"],
277
+ );
278
+ const keysDir = join(options.home, "keys", "remote");
279
+ const connections = new Map<string, Connection>();
280
+ const logins = new Map<string, Login>();
281
+ let stopped = false;
282
+
283
+ const credentialsFile = (server: string): string => join(keysDir, `${serverKey(server)}.json`);
284
+ const readCredentials = (server: string): Credentials | undefined => {
285
+ const file = credentialsFile(server);
286
+ if (!existsSync(file)) return undefined;
287
+ try {
288
+ const parsed = JSON.parse(readFileSync(file, "utf8")) as Credentials;
289
+ const secret =
290
+ (parsed as { refreshToken?: unknown; key?: unknown }).refreshToken ??
291
+ (parsed as { key?: unknown }).key;
292
+ if (parsed.server !== server || typeof secret !== "string") return undefined;
293
+ options.protect(secret);
294
+ return parsed;
295
+ } catch {
296
+ return undefined;
297
+ }
298
+ };
299
+ const writeCredentials = (credentials: Credentials): void => {
300
+ mkdirSync(keysDir, { recursive: true, mode: 0o700 });
301
+ options.protect(credentialSecret(credentials));
302
+ // Written beside it, then renamed: a crash never leaves half a token (as secrets are, D131).
303
+ const target = credentialsFile(credentials.server);
304
+ const temporary = `${target}.${process.pid}.tmp`;
305
+ writeFileSync(temporary, JSON.stringify(credentials), { mode: 0o600 });
306
+ renamePathSync(temporary, target);
307
+ };
308
+ const forgetCredentials = (server: string): void => {
309
+ rmSync(credentialsFile(server), { force: true });
310
+ };
311
+ /**
312
+ * The hosted links this home's remote shares minted, kept beside its credentials (mode 0600,
313
+ * never in the ledger, D44), so `share/list` shows them again: their secrets are the hosted
314
+ * home's, which this home can't derive.
315
+ */
316
+ const linksFile = (server: string): string => join(keysDir, `${serverKey(server)}.links.json`);
317
+ const readLinks = (server: string): Record<string, string> => {
318
+ try {
319
+ const parsed = JSON.parse(readFileSync(linksFile(server), "utf8")) as Record<string, string>;
320
+ for (const url of Object.values(parsed)) protectLink(url);
321
+ return parsed;
322
+ } catch {
323
+ return {};
324
+ }
325
+ };
326
+ const writeLinks = (server: string, links: Record<string, string>): void => {
327
+ mkdirSync(keysDir, { recursive: true, mode: 0o700 });
328
+ const target = linksFile(server);
329
+ const temporary = `${target}.${process.pid}.tmp`;
330
+ writeFileSync(temporary, JSON.stringify(links), { mode: 0o600 });
331
+ renamePathSync(temporary, target);
332
+ };
333
+ /** A link's secret is in its fragment: it never reaches a log. */
334
+ const protectLink = (url: string): void => {
335
+ const secret = /#t=([^&]+)/.exec(url)?.[1];
336
+ if (secret !== undefined) options.protect(secret);
337
+ };
338
+
339
+ const linkRow = (db: LedgerDb, server: string): LinkRow | undefined =>
340
+ db.get<LinkRow>("SELECT * FROM remote_link WHERE server = ?", server);
341
+
342
+ const owned =
343
+ (server: string) =>
344
+ (db: LedgerDb, artifactId: string): boolean =>
345
+ db.get(
346
+ "SELECT 1 FROM hosted_artifact WHERE artifact_id = ? AND server = ?",
347
+ artifactId,
348
+ server,
349
+ ) !== undefined;
350
+
351
+ /** A fresh access token, refreshing (and rotating the refresh token) when it's due. */
352
+ const accessToken = (connection: Connection): Promise<string> => {
353
+ if (connection.access && connection.access.expiresAt - now() > REFRESH_AHEAD_MS) {
354
+ return Promise.resolve(connection.access.token);
355
+ }
356
+ connection.refreshing ??= (async () => {
357
+ // Its `finally` clears the registration, so it must run after `??=` made it (a refresh that
358
+ // fails before its first await would otherwise stay registered, refused, for good).
359
+ await Promise.resolve();
360
+ try {
361
+ const credentials = readCredentials(connection.server);
362
+ if (!credentials) throw loginFailed(`This home isn't signed in to ${connection.server}.`);
363
+ // An operator's key is the bearer itself: nothing to refresh, and the server asks the
364
+ // operator again while the binding is open.
365
+ if ("key" in credentials) return credentials.key;
366
+ const answer = await postForm(
367
+ connection.server,
368
+ "/oauth/token",
369
+ {
370
+ client_id: CLIENT_ID,
371
+ grant_type: "refresh_token",
372
+ refresh_token: credentials.refreshToken,
373
+ },
374
+ connectTo,
375
+ );
376
+ if (answer.status !== 200 || typeof answer.json["access_token"] !== "string") {
377
+ const error = String(answer.json["error"] ?? answer.status);
378
+ if (error === "invalid_grant")
379
+ signedOut(connection, "the sign-in was revoked or has expired");
380
+ throw loginFailed(`${connection.server} refused this home's sign-in (${error}).`);
381
+ }
382
+ const token = answer.json["access_token"] as string;
383
+ const refresh = answer.json["refresh_token"];
384
+ options.protect(token);
385
+ // The rotated refresh token is durable before the access token is used (§18.5).
386
+ if (typeof refresh === "string")
387
+ writeCredentials({ ...credentials, refreshToken: refresh });
388
+ connection.access = {
389
+ token,
390
+ expiresAt: now() + Number(answer.json["expires_in"] ?? 3600) * 1000,
391
+ };
392
+ scheduleRefresh(connection);
393
+ return token;
394
+ } finally {
395
+ connection.refreshing = undefined;
396
+ }
397
+ })();
398
+ return connection.refreshing;
399
+ };
400
+
401
+ /** Refreshes the token in band before it expires, so the server never closes the binding. */
402
+ const scheduleRefresh = (connection: Connection): void => {
403
+ if (connection.refreshTimer) clearTimeout(connection.refreshTimer);
404
+ if (!connection.access) return;
405
+ const delay = Math.max(1_000, connection.access.expiresAt - now() - REFRESH_AHEAD_MS + 1_000);
406
+ connection.refreshTimer = setTimeout(() => {
407
+ connection.refreshTimer = undefined;
408
+ void (async () => {
409
+ try {
410
+ const token = await accessToken(connection);
411
+ const session = connection.binding.session;
412
+ if (session) await session.call(remoteTokenMethod, { accessToken: token });
413
+ } catch (error) {
414
+ log.warn("link.refresh_failed", {
415
+ server: connection.server,
416
+ error: (error as Error).message,
417
+ });
418
+ }
419
+ })();
420
+ }, delay);
421
+ connection.refreshTimer.unref?.();
422
+ };
423
+
424
+ const signedOut = (connection: Connection, why: string): void => {
425
+ connection.state = "signed-out";
426
+ connection.lastError = why;
427
+ connection.since = new Date(now()).toISOString();
428
+ ledger.write((db) =>
429
+ db.run("UPDATE remote_link SET state = 'signed-out' WHERE server = ?", connection.server),
430
+ );
431
+ void connection.binding.stop();
432
+ log.warn("link.signed_out", { server: connection.server, why });
433
+ };
434
+
435
+ /** Sessions whose follow failed: their later pages are never copied (Opus review of WP-29, 2). */
436
+ const broken = new WeakSet<BindingSession>();
437
+
438
+ /**
439
+ * Reads again each followed submission this home doesn't hold (restored from a backup taken
440
+ * before it, or a delivery it committed and then lost) and imports it as a delivery would, keeping
441
+ * its IDs; its local deliveries repeat their derived IDs (FAILURE_MODEL §11.2). The IDs wait in
442
+ * `remote_missing`, written with the cursor that passed them, until imported: a read that fails
443
+ * is tried again on the next page and the next session (Opus review of WP-29, 3).
444
+ */
445
+ const reimporting = new Set<string>();
446
+ /** Tests: the one submission whose first read again fails (`MOSTRA_TEST_REIMPORT_FAIL`). */
447
+ let failOnce = options.env["MOSTRA_TEST_REIMPORT_FAIL"];
448
+ const reimport = (
449
+ connection: Connection,
450
+ session: BindingSession,
451
+ source: ImportSource,
452
+ ): void => {
453
+ const missing = ledger.read((db) =>
454
+ db
455
+ .all<{ submission_id: string }>(
456
+ "SELECT submission_id FROM remote_missing WHERE server = ? ORDER BY noted_at, submission_id",
457
+ connection.server,
458
+ )
459
+ .map((row) => row.submission_id),
460
+ );
461
+ for (const submissionId of missing) {
462
+ const key = `${connection.server} ${submissionId}`;
463
+ if (reimporting.has(key)) continue;
464
+ reimporting.add(key);
465
+ void (async () => {
466
+ try {
467
+ if (failOnce === submissionId) {
468
+ failOnce = undefined;
469
+ throw new Error("a test's failed read");
470
+ }
471
+ const envelope = await session.call(
472
+ hostedSubmissionMethod,
473
+ { submissionId },
474
+ { timeoutMs: 30_000 },
475
+ );
476
+ const answer = options.importSubmission(envelope, source);
477
+ // Imported, or refused for good (it can never be held here): it waits no longer.
478
+ if (answer.accepted || !answer.retry) {
479
+ ledger.write((db) =>
480
+ db.run(
481
+ "DELETE FROM remote_missing WHERE server = ? AND submission_id = ?",
482
+ connection.server,
483
+ submissionId,
484
+ ),
485
+ );
486
+ }
487
+ log.info("link.submission_reimported", {
488
+ server: connection.server,
489
+ submissionId,
490
+ accepted: answer.accepted,
491
+ });
492
+ } catch (error) {
493
+ log.warn("link.reimport_failed", { server: connection.server, submissionId, error });
494
+ } finally {
495
+ reimporting.delete(key);
496
+ }
497
+ })();
498
+ }
499
+ };
500
+
501
+ /** Copies one page of followed events, then acknowledges it (the sync cursor, §18.2). */
502
+ const follow = (
503
+ connection: Connection,
504
+ page: EventsNotifyParams,
505
+ session: BindingSession,
506
+ ): void => {
507
+ const home = connection.home;
508
+ const incarnation = connection.incarnation;
509
+ if (!home || !incarnation) return;
510
+ const source: ImportSource = {
511
+ server: connection.server,
512
+ serverKey: serverKey(connection.server),
513
+ home,
514
+ incarnation,
515
+ };
516
+ ledger.write((db) => {
517
+ const followed = followEvents(db, {
518
+ events: page.events,
519
+ source,
520
+ owned: owned(connection.server),
521
+ });
522
+ db.run(
523
+ "UPDATE remote_link SET follow_cursor = ?, incarnation = ? WHERE server = ?",
524
+ page.cursor,
525
+ incarnation,
526
+ connection.server,
527
+ );
528
+ for (const submissionId of followed.missing) {
529
+ db.run(
530
+ "INSERT OR IGNORE INTO remote_missing (server, submission_id, noted_at) VALUES (?, ?, ?)",
531
+ connection.server,
532
+ submissionId,
533
+ new Date(now()).toISOString(),
534
+ );
535
+ }
536
+ return followed;
537
+ });
538
+ reimport(connection, session, source);
539
+ session.notify(eventsAckMethod.method, {
540
+ subscriptionId: page.subscriptionId,
541
+ cursor: page.cursor,
542
+ });
543
+ };
544
+
545
+ /** Every binding message, appended to a file (tests: the relay's secrets grep). */
546
+ const traceFile = options.env["MOSTRA_TEST_BINDING_TRACE"];
547
+ const trace =
548
+ traceFile === undefined || traceFile === ""
549
+ ? undefined
550
+ : (direction: "out" | "in", text: string): void =>
551
+ appendFileSync(traceFile, `${direction} ${Date.now()} ${text}\n`);
552
+ /**
553
+ * The binding's session, or the one opening now: a relay message can arrive while the session's
554
+ * own start (its subscription) is still under way, and an update sent then mustn't be lost.
555
+ */
556
+ const readyMs = Number(options.env["MOSTRA_TEST_RELAY_READY_MS"] ?? "") || 10_000;
557
+ const readySoon = (connection: Connection): Promise<BindingSession | undefined> => {
558
+ let timer: ReturnType<typeof setTimeout> | undefined;
559
+ return Promise.race([
560
+ connection.binding.ready(),
561
+ new Promise<undefined>((resolve) => {
562
+ timer = setTimeout(() => resolve(undefined), readyMs);
563
+ }),
564
+ ]).finally(() => clearTimeout(timer));
565
+ };
566
+ const relay = createOwnerRelay({
567
+ ledger,
568
+ log,
569
+ actions: options.actions,
570
+ now,
571
+ loseAcks: Number(options.env["MOSTRA_TEST_RELAY_LOSE_ACK"] ?? "0") || 0,
572
+ ...(options.liveChanged ? { liveChanged: options.liveChanged } : {}),
573
+ });
574
+
575
+ const onRequest =
576
+ (connection: Connection) =>
577
+ (method: string, params: unknown): unknown => {
578
+ if (method === portRelayAuthorMethod.method) {
579
+ if (!options.author) {
580
+ throw new RpcError(
581
+ createDiagnostic("MOSTRA_REMOTE_NO_INSTANCE", {
582
+ message: "This instance takes no authoring from a chat host.",
583
+ }),
584
+ );
585
+ }
586
+ return options.author(connection.server, params);
587
+ }
588
+ if (relay.handles(method)) {
589
+ return relay.request(
590
+ connection.server,
591
+ () => connection.binding.session ?? readySoon(connection),
592
+ method,
593
+ params,
594
+ () => connection.binding.reconnect(),
595
+ );
596
+ }
597
+ if (method === portSubmissionsDeliverMethod.method) {
598
+ const parsed = SubmissionEnvelope.safeParse(
599
+ (params as { envelope?: unknown })?.envelope ?? params,
600
+ );
601
+ if (!parsed.success)
602
+ return { accepted: false, reason: "invalid: not a submission envelope", retry: false };
603
+ if (!connection.home || !connection.incarnation) {
604
+ return { accepted: false, reason: "the session isn't open yet", retry: true };
605
+ }
606
+ return options.importSubmission(parsed.data, {
607
+ server: connection.server,
608
+ serverKey: serverKey(connection.server),
609
+ home: connection.home,
610
+ incarnation: connection.incarnation,
611
+ });
612
+ }
613
+ throw new RpcError(
614
+ createDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", {
615
+ message: `This instance doesn't serve ${method}.`,
616
+ }),
617
+ );
618
+ };
619
+
620
+ const connect = (server: string): Connection => {
621
+ const existing = connections.get(server);
622
+ if (existing && existing.state !== "signed-out") return existing;
623
+ const connection: Connection = {
624
+ server,
625
+ binding: undefined as unknown as Binding,
626
+ state: "connecting",
627
+ since: new Date(now()).toISOString(),
628
+ };
629
+ connections.set(server, connection);
630
+ connection.binding = startBinding({
631
+ ...(trace ? { trace } : {}),
632
+ server,
633
+ ...(connectTo ? { connectTo } : {}),
634
+ accessToken: () => accessToken(connection),
635
+ initialize: () => {
636
+ const row = ledger.read((db) => linkRow(db, server));
637
+ return ownerInitialize({
638
+ name: "mostra-runtime",
639
+ version: options.runtimeVersion,
640
+ instanceId: row?.instance_id ?? "",
641
+ relayMark: row?.relay_mark ?? 0,
642
+ ...(row?.incarnation && row.follow_cursor
643
+ ? { followed: { incarnation: row.incarnation, cursor: row.follow_cursor } }
644
+ : {}),
645
+ });
646
+ },
647
+ onRequest: onRequest(connection),
648
+ onNotification: (method, params, session) => {
649
+ if (method !== "events/notify") return;
650
+ // A page that can't be copied ends the connection: no later page may commit the cursor
651
+ // past it, and the next session resumes after what was committed (Opus review of WP-29, 2).
652
+ if (broken.has(session)) return;
653
+ try {
654
+ follow(connection, params as EventsNotifyParams, session);
655
+ } catch (error) {
656
+ broken.add(session);
657
+ log.warn("link.follow_failed", { server, error });
658
+ connection.binding.reconnect();
659
+ }
660
+ },
661
+ onOpen: async (session) => {
662
+ connection.home = session.result.instance.home;
663
+ connection.incarnation = session.result.instance.incarnation ?? "";
664
+ const row = ledger.read((db) => linkRow(db, server));
665
+ const sameIncarnation = row?.incarnation === connection.incarnation;
666
+ // A new incarnation is a hosted home restored from a backup (FAILURE_MODEL §11.2): this
667
+ // instance keeps what it imported, continues after the lower of what it committed and the
668
+ // restored head, and records the window the server lost (`remote.regressed`).
669
+ const head = session.result.instance.cursor ?? "0";
670
+ const regressed =
671
+ row?.incarnation !== null &&
672
+ row?.incarnation !== undefined &&
673
+ !sameIncarnation &&
674
+ row.follow_cursor !== null;
675
+ const after = sameIncarnation
676
+ ? (row?.follow_cursor ?? undefined)
677
+ : regressed
678
+ ? String(Math.min(Number(row?.follow_cursor ?? "0"), Number(head)))
679
+ : undefined;
680
+ if (regressed) {
681
+ ledger.write((db) => {
682
+ appendEvent(db, {
683
+ artifactId: null,
684
+ type: "remote.regressed",
685
+ actor: { kind: "mostra" },
686
+ payload: {
687
+ server,
688
+ home: connection.home,
689
+ from: row?.follow_cursor,
690
+ to: head,
691
+ incarnation: { from: row?.incarnation, to: connection.incarnation },
692
+ },
693
+ });
694
+ db.run(
695
+ "UPDATE remote_link SET follow_cursor = ?, incarnation = ? WHERE server = ?",
696
+ after ?? null,
697
+ connection.incarnation ?? null,
698
+ server,
699
+ );
700
+ });
701
+ log.warn("link.home_regressed", { server, from: row?.follow_cursor, to: head });
702
+ }
703
+ await session.call(eventsSubscribeMethod, {
704
+ name: `owner:${row?.instance_id ?? ""}`,
705
+ ...(after !== undefined ? { after } : {}),
706
+ });
707
+ connection.state = "connected";
708
+ connection.since = new Date(now()).toISOString();
709
+ delete connection.lastError;
710
+ if (connection.home && connection.incarnation) {
711
+ reimport(connection, session, {
712
+ server,
713
+ serverKey: serverKey(server),
714
+ home: connection.home,
715
+ incarnation: connection.incarnation,
716
+ });
717
+ }
718
+ void drainPushes(connection);
719
+ },
720
+ onClose: (why) => {
721
+ relay.closed(server);
722
+ if (connection.state === "signed-out") return;
723
+ if (connection.state === "connected") connection.since = new Date(now()).toISOString();
724
+ connection.state = "offline";
725
+ connection.lastError = why;
726
+ },
727
+ onUnauthorized: () => {
728
+ delete connection.access;
729
+ },
730
+ log,
731
+ });
732
+ return connection;
733
+ };
734
+
735
+ /** The canonical listing of a version's output, with sizes (DATA_MODEL §2), read from its directory. */
736
+ const listingOf = (versionDir: string): ListingEntry[] => {
737
+ const entries: ListingEntry[] = [];
738
+ const walk = (dir: string, relative: string): void => {
739
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
740
+ const path = `${relative}/${entry.name}`;
741
+ const absolute = join(dir, entry.name);
742
+ if (entry.isDirectory()) walk(absolute, path);
743
+ else if (entry.isFile()) {
744
+ const bytes = readFileSync(absolute);
745
+ entries.push([
746
+ path,
747
+ false,
748
+ createHash("sha256").update(bytes).digest("hex"),
749
+ bytes.length,
750
+ ]);
751
+ }
752
+ }
753
+ };
754
+ for (const top of ["client", "server"]) {
755
+ if (existsSync(join(versionDir, top))) walk(join(versionDir, top), top);
756
+ }
757
+ const registry = readFileSync(join(versionDir, "registry.json"));
758
+ entries.push([
759
+ "registry.json",
760
+ false,
761
+ createHash("sha256").update(registry).digest("hex"),
762
+ registry.length,
763
+ ]);
764
+ return entries;
765
+ };
766
+
767
+ /** Pushes one version: the push, then the files the server names as missing, then the push again. */
768
+ const pushVersion = async (
769
+ connection: Connection,
770
+ artifactId: string,
771
+ versionId: string,
772
+ ): Promise<Pushed> => {
773
+ const row = ledger.read((db) =>
774
+ db.get<{ number: number; source_digest: string; env_digest: string; output_digest: string }>(
775
+ "SELECT number, source_digest, env_digest, output_digest FROM version WHERE id = ? AND artifact_id = ?",
776
+ versionId,
777
+ artifactId,
778
+ ),
779
+ );
780
+ if (!row) throw invalid(`${artifactId} has no version ${versionId}.`);
781
+ const dir = options.versionDir(versionId);
782
+ const listing = listingOf(dir);
783
+ if (
784
+ listingDigest(listing.map(([path, executable, sha256]) => ({ path, executable, sha256 }))) !==
785
+ row.output_digest
786
+ ) {
787
+ throw new RpcError(
788
+ createDiagnostic("MOSTRA_HOME_INTEGRITY", {
789
+ message: `Version ${versionId}'s files don't match its output digest; publish its source again first.`,
790
+ }),
791
+ );
792
+ }
793
+ const version: VersionPush = {
794
+ versionId,
795
+ number: row.number,
796
+ sourceDigest: row.source_digest,
797
+ envDigest: row.env_digest,
798
+ outputDigest: row.output_digest,
799
+ manifest: readFileSync(join(dir, "manifest.json"), "utf8"),
800
+ registry: readFileSync(join(dir, "registry.json"), "utf8"),
801
+ lock: readFileSync(join(dir, "lock.yaml"), "utf8"),
802
+ listing,
803
+ // The policy in force here (D102): the hosted home follows the owner's host's choice.
804
+ ...(() => {
805
+ const found = ledger.read(
806
+ (db) =>
807
+ db.get<{ policy_json: string | null }>(
808
+ "SELECT policy_json FROM artifact WHERE id = ?",
809
+ artifactId,
810
+ )?.policy_json,
811
+ );
812
+ return found ? { policy: JSON.parse(found) as SubmissionPolicy } : {};
813
+ })(),
814
+ };
815
+ const session = await connection.binding.ready();
816
+ let answer: HostedPushResult = await session.call(hostedPushMethod, { artifactId, version });
817
+ for (let round = 0; answer.status === "missing" && round < 3; round += 1) {
818
+ const wanted = new Set(answer.files);
819
+ const token = await accessToken(connection);
820
+ for (const [path, , sha256, size] of listing) {
821
+ if (!wanted.has(sha256) || !path.startsWith("client/")) continue;
822
+ wanted.delete(sha256);
823
+ const body = readFileSync(join(dir, path));
824
+ if (body.length !== size) throw invalid(`${path} changed while it was pushed.`);
825
+ const put = await remoteRequest(connection.server, `/files/${sha256}`, {
826
+ method: "PUT",
827
+ headers: { authorization: `Bearer ${token}`, "content-type": "application/octet-stream" },
828
+ body,
829
+ timeoutMs: 300_000,
830
+ ...(connectTo ? { connectTo } : {}),
831
+ });
832
+ if (put.status !== 201 && put.status !== 200) {
833
+ throw new RpcError(
834
+ createDiagnostic("MOSTRA_REMOTE_UNREACHABLE", {
835
+ message: `${connection.server} refused the file ${path} (${put.status}).`,
836
+ }),
837
+ );
838
+ }
839
+ }
840
+ answer = await session.call(hostedPushMethod, { artifactId, version });
841
+ }
842
+ if (answer.status !== "complete") {
843
+ throw new RpcError(
844
+ createDiagnostic("MOSTRA_REMOTE_UNREACHABLE", {
845
+ message: `${connection.server} still lacks files of ${versionId} after they were sent.`,
846
+ }),
847
+ );
848
+ }
849
+ ledger.write((db) => {
850
+ db.run(
851
+ "UPDATE hosted_artifact SET hosted_home = ?, route_id = ?, label = ? WHERE artifact_id = ? AND server = ?",
852
+ session.result.instance.home,
853
+ answer.route.routeId,
854
+ answer.route.label,
855
+ artifactId,
856
+ connection.server,
857
+ );
858
+ db.run(
859
+ "UPDATE version_push SET state = 'complete' WHERE artifact_id = ? AND version_id = ? AND server = ?",
860
+ artifactId,
861
+ versionId,
862
+ connection.server,
863
+ );
864
+ });
865
+ log.info("link.pushed", { server: connection.server, artifactId, versionId });
866
+ return {
867
+ versionId,
868
+ number: answer.number,
869
+ route: answer.route,
870
+ server: connection.server,
871
+ home: session.result.instance.home,
872
+ };
873
+ };
874
+
875
+ /** Sends every pending push of a server, oldest first, retrying with backoff while it fails. */
876
+ /**
877
+ * Whether a push failed for good: the server (or this home, for a damaged version) answered it
878
+ * with a refusal, not a connection that closed or a call that timed out. Such a push is never
879
+ * tried again, and nothing waits behind it (Opus review of WP-29, 10).
880
+ */
881
+ const refusedForGood = (error: unknown): error is RpcError =>
882
+ error instanceof RpcError && !PUSH_TRANSPORT_FAILURES.has(error.diagnostic.code);
883
+
884
+ /** Records a push the server refused for good, and says so in `remote/status`. */
885
+ const refusePush = (
886
+ connection: Connection,
887
+ artifactId: string,
888
+ versionId: string,
889
+ error: RpcError,
890
+ ): void => {
891
+ const why = `${error.diagnostic.code}: ${error.diagnostic.message}`;
892
+ ledger.write((db) => {
893
+ db.run(
894
+ "UPDATE version_push SET state = 'refused', refusal = ? WHERE artifact_id = ? AND version_id = ? AND server = ? AND state = 'pending'",
895
+ why,
896
+ artifactId,
897
+ versionId,
898
+ connection.server,
899
+ );
900
+ // A first share the server refused hosts nothing: the artifact isn't shared there.
901
+ db.run(
902
+ "DELETE FROM hosted_artifact WHERE artifact_id = ? AND server = ? AND route_id = ''",
903
+ artifactId,
904
+ connection.server,
905
+ );
906
+ });
907
+ connection.lastError = `The server refused ${artifactId}'s version ${versionId}: ${why}`;
908
+ log.warn("link.push_refused", {
909
+ server: connection.server,
910
+ artifactId,
911
+ versionId,
912
+ code: error.diagnostic.code,
913
+ });
914
+ };
915
+
916
+ const drainPushes = (connection: Connection, attempt = 0): Promise<void> => {
917
+ if (connection.pushing) return connection.pushing;
918
+ // One drain at a time per server. The drain is registered before its body runs, and only it
919
+ // clears itself: a drain that found nothing to push ends before its first await, and the
920
+ // registration must never outlive it, or every later publish would wait for nothing.
921
+ const drain = (async () => {
922
+ await Promise.resolve();
923
+ try {
924
+ for (;;) {
925
+ if (stopped || !connection.binding.session) return;
926
+ const next = ledger.read((db) =>
927
+ db.get<{ artifact_id: string; version_id: string }>(
928
+ "SELECT artifact_id, version_id FROM version_push WHERE server = ? AND state = 'pending' ORDER BY created_at, rowid LIMIT 1",
929
+ connection.server,
930
+ ),
931
+ );
932
+ if (!next) return;
933
+ try {
934
+ await pushVersion(connection, next.artifact_id, next.version_id);
935
+ } catch (error) {
936
+ if (!refusedForGood(error)) throw error;
937
+ refusePush(connection, next.artifact_id, next.version_id, error);
938
+ }
939
+ }
940
+ } catch (error) {
941
+ log.warn("link.push_failed", {
942
+ server: connection.server,
943
+ error: (error as Error).message,
944
+ });
945
+ ledger.write((db) =>
946
+ db.run(
947
+ "UPDATE version_push SET attempts = attempts + 1 WHERE server = ? AND state = 'pending'",
948
+ connection.server,
949
+ ),
950
+ );
951
+ if (connection.pushTimer || stopped) return;
952
+ connection.pushTimer = setTimeout(
953
+ () => {
954
+ connection.pushTimer = undefined;
955
+ void drainPushes(connection, attempt + 1);
956
+ },
957
+ Math.min(PUSH_RETRY_MAX_MS, PUSH_RETRY_MS * 2 ** attempt),
958
+ );
959
+ connection.pushTimer.unref?.();
960
+ }
961
+ })();
962
+ connection.pushing = drain;
963
+ void drain.finally(() => {
964
+ if (connection.pushing === drain) connection.pushing = undefined;
965
+ });
966
+ return drain;
967
+ };
968
+
969
+ const queuePush = (db: LedgerDb, artifactId: string, versionId: string, server: string): void => {
970
+ db.run(
971
+ `INSERT INTO version_push (artifact_id, version_id, server, state, attempts, created_at) VALUES (?, ?, ?, 'pending', 0, ?)
972
+ ON CONFLICT (artifact_id, version_id, server) DO NOTHING`,
973
+ artifactId,
974
+ versionId,
975
+ server,
976
+ new Date(now()).toISOString(),
977
+ );
978
+ };
979
+
980
+ const resolveServer = (server: string | undefined): string => {
981
+ if (server !== undefined) return serverOrigin(server);
982
+ const last = ledger.read((db) =>
983
+ db.get<{ server: string }>("SELECT server FROM remote_link ORDER BY linked_at DESC LIMIT 1"),
984
+ );
985
+ if (!last) {
986
+ throw invalid(
987
+ "Name the server to sign in to: mostra login <server>. No server is configured by default.",
988
+ );
989
+ }
990
+ return last.server;
991
+ };
992
+
993
+ /** Records this home's link to a server, rebinding its marks only to the same link (WP-29). */
994
+ const recordLink = (
995
+ server: string,
996
+ account: { readonly id: string; readonly name?: string | undefined },
997
+ instanceId: string,
998
+ isDefault: boolean,
999
+ ): void => {
1000
+ ledger.write((db) =>
1001
+ db.run(
1002
+ `INSERT INTO remote_link (server, account_id, account_name, instance_id, is_default, linked_at, state)
1003
+ VALUES (?, ?, ?, ?, ?, ?, 'signed-in')
1004
+ ON CONFLICT (server) DO UPDATE SET
1005
+ -- Another link (after --forget, or another account) starts with no marks: a mark
1006
+ -- of the old link would make the new one's home look restored (Opus review of
1007
+ -- WP-29, 9).
1008
+ relay_mark = CASE WHEN remote_link.instance_id IS excluded.instance_id
1009
+ AND remote_link.account_id = excluded.account_id THEN remote_link.relay_mark ELSE 0 END,
1010
+ follow_cursor = CASE WHEN remote_link.instance_id IS excluded.instance_id
1011
+ AND remote_link.account_id = excluded.account_id THEN remote_link.follow_cursor ELSE NULL END,
1012
+ incarnation = CASE WHEN remote_link.instance_id IS excluded.instance_id
1013
+ AND remote_link.account_id = excluded.account_id THEN remote_link.incarnation ELSE NULL END,
1014
+ account_id = excluded.account_id, account_name = excluded.account_name,
1015
+ instance_id = excluded.instance_id, is_default = excluded.is_default, linked_at = excluded.linked_at,
1016
+ state = 'signed-in'`,
1017
+ server,
1018
+ account.id,
1019
+ account.name ?? null,
1020
+ instanceId,
1021
+ isDefault ? 1 : 0,
1022
+ new Date(now()).toISOString(),
1023
+ ),
1024
+ );
1025
+ };
1026
+
1027
+ /**
1028
+ * Links this home with a key the server's operator issued (`remote/link`, D167): the server says
1029
+ * which account and instance link the key binds, the key is kept like a refresh token, and the
1030
+ * binding opens with it at once.
1031
+ */
1032
+ const linkWithKey = async (
1033
+ requested: string,
1034
+ key: string,
1035
+ makeDefault: boolean,
1036
+ ): Promise<RemoteLinkResult> => {
1037
+ const server = serverOrigin(requested);
1038
+ options.protect(key);
1039
+ const answer = await postForm(
1040
+ server,
1041
+ "/link",
1042
+ makeDefault ? { default: "1" } : {},
1043
+ connectTo,
1044
+ key,
1045
+ );
1046
+ const account = answer.json["account"] as { id?: unknown; name?: unknown } | undefined;
1047
+ const instanceId = answer.json["instanceId"];
1048
+ if (
1049
+ answer.status !== 200 ||
1050
+ typeof account?.id !== "string" ||
1051
+ typeof instanceId !== "string" ||
1052
+ !LinkId.is(instanceId)
1053
+ ) {
1054
+ throw loginFailed(
1055
+ `${server} didn't admit this key (${String(answer.json["message"] ?? answer.status)}).`,
1056
+ );
1057
+ }
1058
+ const name = typeof account.name === "string" ? account.name : undefined;
1059
+ const isDefault = answer.json["default"] === true;
1060
+ writeCredentials({ server, key, instanceId });
1061
+ recordLink(server, { id: account.id, name }, instanceId, isDefault);
1062
+ const previous = connections.get(server);
1063
+ if (previous) {
1064
+ await previous.binding.stop();
1065
+ if (previous.refreshTimer) clearTimeout(previous.refreshTimer);
1066
+ connections.delete(server);
1067
+ }
1068
+ connect(server);
1069
+ log.info("link.linked_with_key", { server, instanceId });
1070
+ return {
1071
+ server,
1072
+ account: { id: account.id, ...(name !== undefined ? { name } : {}) },
1073
+ instanceId,
1074
+ default: isDefault,
1075
+ };
1076
+ };
1077
+
1078
+ /** Starts a sign-in: the device grant's code, then polls for the token in the background. */
1079
+ const login = async (
1080
+ requested: string | undefined,
1081
+ makeDefault = false,
1082
+ ): Promise<RemoteLoginResult> => {
1083
+ const server = resolveServer(requested);
1084
+ const existing = ledger.read((db) => linkRow(db, server));
1085
+ const started = await postForm(
1086
+ server,
1087
+ "/oauth/device",
1088
+ {
1089
+ client_id: CLIENT_ID,
1090
+ mostra_name: hostname().slice(0, 128) || "Mostra instance",
1091
+ ...(existing?.instance_id ? { mostra_instance: existing.instance_id } : {}),
1092
+ ...(makeDefault ? { mostra_default: "1" } : {}),
1093
+ },
1094
+ connectTo,
1095
+ );
1096
+ const deviceCode = started.json["device_code"];
1097
+ const userCode = started.json["user_code"];
1098
+ const uri = started.json["verification_uri"];
1099
+ if (
1100
+ started.status !== 200 ||
1101
+ typeof deviceCode !== "string" ||
1102
+ typeof userCode !== "string" ||
1103
+ typeof uri !== "string"
1104
+ ) {
1105
+ throw loginFailed(
1106
+ `${server} didn't start a sign-in (${String(started.json["error"] ?? started.status)}).`,
1107
+ );
1108
+ }
1109
+ options.protect(deviceCode);
1110
+ const expiresIn = Number(started.json["expires_in"] ?? 600);
1111
+ const interval = Math.max(1, Number(started.json["interval"] ?? 5));
1112
+ const complete = started.json["verification_uri_complete"];
1113
+ const result: RemoteLoginResult = {
1114
+ loginId: `login_${randomUUID()}`,
1115
+ server,
1116
+ verificationUri: uri,
1117
+ ...(typeof complete === "string" ? { verificationUriComplete: complete } : {}),
1118
+ userCode,
1119
+ expiresAt: new Date(now() + expiresIn * 1000).toISOString(),
1120
+ };
1121
+ const pending: Login = { id: result.loginId, server, result, waiters: [] };
1122
+ logins.set(result.loginId, pending);
1123
+ const finish = (outcome: NonNullable<Login["outcome"]>): void => {
1124
+ pending.outcome = outcome;
1125
+ for (const wake of pending.waiters.splice(0)) wake();
1126
+ setTimeout(() => logins.delete(pending.id), 10 * 60_000).unref();
1127
+ };
1128
+ void (async () => {
1129
+ let wait = interval * 1000;
1130
+ const deadline = now() + expiresIn * 1000;
1131
+ while (!stopped && now() < deadline) {
1132
+ await new Promise((resolve) => setTimeout(resolve, wait).unref());
1133
+ let answer: { status: number; json: Record<string, unknown> };
1134
+ try {
1135
+ answer = await postForm(
1136
+ server,
1137
+ "/oauth/token",
1138
+ { client_id: CLIENT_ID, grant_type: DEVICE_GRANT, device_code: deviceCode },
1139
+ connectTo,
1140
+ );
1141
+ } catch {
1142
+ continue;
1143
+ }
1144
+ const error = answer.json["error"];
1145
+ if (error === "authorization_pending") continue;
1146
+ if (error === "slow_down") {
1147
+ wait += 5_000;
1148
+ continue;
1149
+ }
1150
+ if (answer.status !== 200 || typeof answer.json["refresh_token"] !== "string") {
1151
+ finish({
1152
+ ok: false,
1153
+ error: loginFailed(
1154
+ `${server} refused the sign-in (${String(error ?? answer.status)}).`,
1155
+ ),
1156
+ });
1157
+ return;
1158
+ }
1159
+ const account = answer.json["mostra_account"] as { id: string; name?: string };
1160
+ const instanceId = String(answer.json["mostra_instance"]);
1161
+ const refreshToken = answer.json["refresh_token"] as string;
1162
+ const accessToken = String(answer.json["access_token"]);
1163
+ options.protect(accessToken);
1164
+ writeCredentials({ server, refreshToken, instanceId });
1165
+ recordLink(server, account, instanceId, answer.json["mostra_default"] === true);
1166
+ const previous = connections.get(server);
1167
+ if (previous) {
1168
+ await previous.binding.stop();
1169
+ connections.delete(server);
1170
+ }
1171
+ const connection = connect(server);
1172
+ connection.access = {
1173
+ token: accessToken,
1174
+ expiresAt: now() + Number(answer.json["expires_in"] ?? 3600) * 1000,
1175
+ };
1176
+ scheduleRefresh(connection);
1177
+ log.info("link.signed_in", { server, instanceId });
1178
+ finish({
1179
+ ok: true,
1180
+ account: { id: account.id, ...(account.name ? { name: account.name } : {}) },
1181
+ instanceId,
1182
+ });
1183
+ return;
1184
+ }
1185
+ finish({
1186
+ ok: false,
1187
+ error: loginFailed(`The sign-in to ${server} expired before it was approved.`),
1188
+ });
1189
+ })();
1190
+ return result;
1191
+ };
1192
+
1193
+ const status = (): RemoteLink[] =>
1194
+ ledger.read((db) => {
1195
+ const rows = db.all<LinkRow>("SELECT * FROM remote_link ORDER BY linked_at");
1196
+ return rows.map((row): RemoteLink => {
1197
+ const connection = connections.get(row.server);
1198
+ const pending =
1199
+ db.get<{ n: number }>(
1200
+ "SELECT COUNT(*) AS n FROM version_push WHERE server = ? AND state = 'pending'",
1201
+ row.server,
1202
+ )?.n ?? 0;
1203
+ const state: RemoteLink["state"] =
1204
+ row.state === "signed-out" ? "signed-out" : (connection?.state ?? "offline");
1205
+ return {
1206
+ server: row.server,
1207
+ account: {
1208
+ id: row.account_id ?? "",
1209
+ ...(row.account_name ? { name: row.account_name } : {}),
1210
+ },
1211
+ instanceId: row.instance_id ?? "",
1212
+ name: hostname().slice(0, 128) || "Mostra instance",
1213
+ default: row.is_default === 1,
1214
+ state,
1215
+ since: connection?.since ?? row.linked_at,
1216
+ pendingPushes: pending,
1217
+ ...(connection?.lastError ? { lastError: connection.lastError } : {}),
1218
+ };
1219
+ });
1220
+ });
1221
+
1222
+ const self: Link = {
1223
+ methods() {
1224
+ return [
1225
+ handler(remoteLoginMethod, (params) => login(params.server, params.default === true)),
1226
+ handler(remoteLinkMethod, (params) =>
1227
+ linkWithKey(params.server, params.key, params.default === true),
1228
+ ),
1229
+ handler(remoteLoginWaitMethod, async (params) => {
1230
+ const pending = logins.get(params.loginId);
1231
+ if (!pending) throw invalid(`No sign-in ${params.loginId} is in progress.`);
1232
+ if (!pending.outcome && params.timeoutMs > 0) {
1233
+ await new Promise<void>((resolve) => {
1234
+ const timer = setTimeout(resolve, params.timeoutMs);
1235
+ pending.waiters.push(() => {
1236
+ clearTimeout(timer);
1237
+ resolve();
1238
+ });
1239
+ });
1240
+ }
1241
+ const outcome = pending.outcome;
1242
+ if (!outcome) return { status: "pending" as const };
1243
+ if (!outcome.ok) throw outcome.error;
1244
+ return {
1245
+ status: "signed-in" as const,
1246
+ server: pending.server,
1247
+ account: outcome.account,
1248
+ instanceId: outcome.instanceId,
1249
+ };
1250
+ }),
1251
+ handler(remoteLogoutMethod, async (params) => {
1252
+ const servers =
1253
+ params.server !== undefined
1254
+ ? [serverOrigin(params.server)]
1255
+ : ledger
1256
+ .read((db) =>
1257
+ db.all<{ server: string }>(
1258
+ "SELECT server FROM remote_link WHERE state = 'signed-in'",
1259
+ ),
1260
+ )
1261
+ .map((row) => row.server);
1262
+ const done: string[] = [];
1263
+ for (const server of servers) {
1264
+ const credentials = readCredentials(server);
1265
+ const connection = connections.get(server);
1266
+ if (connection) {
1267
+ await connection.binding.stop();
1268
+ if (connection.refreshTimer) clearTimeout(connection.refreshTimer);
1269
+ if (connection.pushTimer) clearTimeout(connection.pushTimer);
1270
+ connections.delete(server);
1271
+ }
1272
+ // An operator's key is the operator's to revoke: signing out only forgets it here.
1273
+ if (credentials && "refreshToken" in credentials) {
1274
+ try {
1275
+ await postForm(
1276
+ server,
1277
+ "/oauth/revoke",
1278
+ { token: credentials.refreshToken, client_id: CLIENT_ID },
1279
+ connectTo,
1280
+ );
1281
+ } catch (error) {
1282
+ // The token is forgotten here whatever the server says: a later sign-in rebinds the link.
1283
+ log.warn("link.revoke_failed", { server, error: (error as Error).message });
1284
+ }
1285
+ }
1286
+ forgetCredentials(server);
1287
+ // The instance link is kept unless --forget, so the artifacts it owns stay its own.
1288
+ ledger.write((db) =>
1289
+ db.run(
1290
+ `UPDATE remote_link SET state = 'signed-out'${params.forget ? ", instance_id = NULL" : ""} WHERE server = ?`,
1291
+ server,
1292
+ ),
1293
+ );
1294
+ done.push(server);
1295
+ }
1296
+ return { servers: done };
1297
+ }),
1298
+ handler(remoteStatusMethod, () => ({ links: status() })),
1299
+ ];
1300
+ },
1301
+ start() {
1302
+ const rows = ledger.read((db) =>
1303
+ db.all<{ server: string }>("SELECT server FROM remote_link WHERE state = 'signed-in'"),
1304
+ );
1305
+ for (const row of rows) {
1306
+ if (readCredentials(row.server)) connect(row.server);
1307
+ }
1308
+ },
1309
+ async stop() {
1310
+ stopped = true;
1311
+ for (const connection of connections.values()) {
1312
+ if (connection.refreshTimer) clearTimeout(connection.refreshTimer);
1313
+ if (connection.pushTimer) clearTimeout(connection.pushTimer);
1314
+ await connection.binding.stop();
1315
+ }
1316
+ connections.clear();
1317
+ },
1318
+ resolveServer,
1319
+ async host(artifactId, server) {
1320
+ const latest = ledger.write((db) => {
1321
+ const link = linkRow(db, server);
1322
+ if (link?.state !== "signed-in") {
1323
+ throw loginFailed(
1324
+ `This home isn't signed in to ${server}: run mostra login ${server} first.`,
1325
+ );
1326
+ }
1327
+ const artifact = db.get<{ latest_version_id: string | null }>(
1328
+ "SELECT latest_version_id FROM artifact WHERE id = ?",
1329
+ artifactId,
1330
+ );
1331
+ if (!artifact?.latest_version_id)
1332
+ throw invalid(`${artifactId} has no published version to share.`);
1333
+ db.run(
1334
+ `INSERT INTO hosted_artifact (artifact_id, server, hosted_home, route_id, label, shared_at) VALUES (?, ?, '', '', '', ?)
1335
+ ON CONFLICT (artifact_id, server) DO UPDATE SET stopped_at = NULL`,
1336
+ artifactId,
1337
+ server,
1338
+ new Date(now()).toISOString(),
1339
+ );
1340
+ queuePush(db, artifactId, artifact.latest_version_id, server);
1341
+ return artifact.latest_version_id;
1342
+ });
1343
+ const connection = connections.get(server) ?? connect(server);
1344
+ let pushed: Pushed;
1345
+ try {
1346
+ pushed = await pushVersion(connection, artifactId, latest);
1347
+ } catch (error) {
1348
+ if (refusedForGood(error)) refusePush(connection, artifactId, latest, error);
1349
+ throw error;
1350
+ }
1351
+ void drainPushes(connection);
1352
+ return pushed;
1353
+ },
1354
+ published(artifactId, versionId) {
1355
+ const servers = ledger.write((db) => {
1356
+ const rows = db.all<{ server: string }>(
1357
+ "SELECT server FROM hosted_artifact WHERE artifact_id = ? AND stopped_at IS NULL",
1358
+ artifactId,
1359
+ );
1360
+ for (const row of rows) queuePush(db, artifactId, versionId, row.server);
1361
+ return rows.map((row) => row.server);
1362
+ });
1363
+ for (const server of servers) {
1364
+ const connection = connections.get(server);
1365
+ if (connection) void drainPushes(connection);
1366
+ }
1367
+ },
1368
+ async session(server, timeoutMs = 10_000) {
1369
+ const connection = connections.get(server);
1370
+ if (!connection || connection.state === "signed-out") {
1371
+ throw loginFailed(`This home isn't signed in to ${server}.`);
1372
+ }
1373
+ if (connection.binding.session) return connection.binding.session;
1374
+ let timer: ReturnType<typeof setTimeout> | undefined;
1375
+ try {
1376
+ return await Promise.race([
1377
+ connection.binding.ready(),
1378
+ new Promise<never>((_resolve, reject) => {
1379
+ timer = setTimeout(
1380
+ () =>
1381
+ reject(
1382
+ new RpcError(
1383
+ createDiagnostic("MOSTRA_REMOTE_UNREACHABLE", {
1384
+ message: `${server} can't be reached now${connection.lastError ? `: ${connection.lastError}` : ""}.`,
1385
+ }),
1386
+ ),
1387
+ ),
1388
+ timeoutMs,
1389
+ );
1390
+ }),
1391
+ ]);
1392
+ } finally {
1393
+ if (timer) clearTimeout(timer);
1394
+ }
1395
+ },
1396
+ connected(server) {
1397
+ return connections.get(server)?.binding.session !== undefined;
1398
+ },
1399
+ status: () => status(),
1400
+ liveInterest: () => relay.liveInterest(),
1401
+ forwardLive: (artifactId, versionId, produced) => {
1402
+ // Every server the artifact is hosted on keeps its own copy for its viewers (Opus review of
1403
+ // WP-29): one artifact may be shared to several servers (D165).
1404
+ const servers = ledger.read((db) =>
1405
+ db
1406
+ .all<{ server: string }>(
1407
+ "SELECT server FROM hosted_artifact WHERE artifact_id = ? AND stopped_at IS NULL AND route_id != '' ORDER BY shared_at",
1408
+ artifactId,
1409
+ )
1410
+ .map((row) => row.server),
1411
+ );
1412
+ if (servers.length === 0) return false;
1413
+ const value = produced();
1414
+ for (const server of servers) {
1415
+ const connection = connections.get(server);
1416
+ relay.sendLive(
1417
+ server,
1418
+ () => (connection ? (connection.binding.session ?? readySoon(connection)) : undefined),
1419
+ artifactId,
1420
+ versionId,
1421
+ value,
1422
+ );
1423
+ }
1424
+ return true;
1425
+ },
1426
+ hostedServers: (artifactId) =>
1427
+ ledger.read((db) =>
1428
+ db
1429
+ .all<{ server: string }>(
1430
+ "SELECT server FROM hosted_artifact WHERE artifact_id = ? AND stopped_at IS NULL AND route_id != '' ORDER BY shared_at",
1431
+ artifactId,
1432
+ )
1433
+ .map((row) => row.server),
1434
+ ),
1435
+ hostedOn: (artifactId) =>
1436
+ ledger.read(
1437
+ (db) =>
1438
+ db.get<{ server: string }>(
1439
+ "SELECT server FROM hosted_artifact WHERE artifact_id = ? AND stopped_at IS NULL AND route_id != '' ORDER BY shared_at LIMIT 1",
1440
+ artifactId,
1441
+ )?.server,
1442
+ ),
1443
+ forward: async (server, definition, params) => {
1444
+ let session: BindingSession;
1445
+ try {
1446
+ session = await self.session(server, 3000);
1447
+ } catch (error) {
1448
+ if (error instanceof RpcError) throw error;
1449
+ throw new RpcError(
1450
+ createDiagnostic("MOSTRA_REMOTE_UNREACHABLE", {
1451
+ message: `${server} can't be reached now; the hosted artifact's state lives there, so nothing was written.`,
1452
+ }),
1453
+ );
1454
+ }
1455
+ return session.call(definition, params, { timeoutMs: 30_000 });
1456
+ },
1457
+ shares: () => ({
1458
+ mint: async (input) => {
1459
+ const server = resolveServer(input.server);
1460
+ await self.host(input.artifactId, server);
1461
+ const session = await self.session(server);
1462
+ const minted = await session.call(viewUrlMethod, {
1463
+ artifact: { artifactId: input.artifactId },
1464
+ ...(input.scopes !== undefined ? { scopes: input.scopes } : {}),
1465
+ ...(input.ttl !== undefined ? { ttl: input.ttl } : {}),
1466
+ ...(input.viewer !== undefined ? { viewer: input.viewer } : {}),
1467
+ });
1468
+ protectLink(minted.url);
1469
+ writeLinks(server, { ...readLinks(server), [minted.tokenId]: minted.url });
1470
+ return {
1471
+ server,
1472
+ url: minted.url,
1473
+ tokenId: minted.tokenId,
1474
+ hostname: new URL(minted.url).host,
1475
+ ...(minted.expiresAt !== undefined ? { expiresAt: minted.expiresAt } : {}),
1476
+ };
1477
+ },
1478
+ url: (server, tokenId) => readLinks(server)[tokenId],
1479
+ revoke: async (server, tokenId) => {
1480
+ const session = await self.session(server);
1481
+ await session.call(viewRevokeMethod, { tokenId });
1482
+ const links = readLinks(server);
1483
+ delete links[tokenId];
1484
+ writeLinks(server, links);
1485
+ },
1486
+ }),
1487
+ };
1488
+ return self;
1489
+ }