Move Patchwork to ARK 0.8.0-alpha.1

.changeset/keyhive-0-6.md

@@ -0,0 +1,15 @@
+---
+"@inkandswitch/patchwork": minor
+"@inkandswitch/patchwork-bootloader": minor
+"@inkandswitch/patchwork-elements": patch
+---
+
+Move to `@automerge/automerge-repo-keyhive` 0.8.0-alpha.1 and `@keyhive/keyhive` 0.6.0. The other exact pins move with them so the consumer's tree keeps a single copy of automerge-repo: `@automerge/automerge-repo` and its adapters, `@automerge/react` and `@automerge/vanillajs` to 2.6.0-subduction.49, and `@automerge/automerge-subduction` to 0.20.1. The shipped automerge-repo patch makes the same changes as before, rebased onto 2.6.0-subduction.49. A site applying the patch from `@inkandswitch/patchwork/dist/patches` should take the new one.
+
+ARK no longer ships named sync servers, so a keyhive build finds its server's identity at startup. The tab and the automerge protocol handler worker fetch the server's contact card from `/keyhive/contact-card` on the `syncServers.subduction` host, and keep the last card fetched so a start without a network can use it. The server has to serve that endpoint. `keyhive.syncServer` and the `PatchworkKeyhiveSyncServer` type are gone; point `syncServers.subduction` at the server instead. `keyhive: true` and `keyhive: { useIdFactory }` are unchanged.
+
+New in `@inkandswitch/patchwork-bootloader`: `loadSyncServerIdentity(url, storage)` from `@inkandswitch/patchwork-bootloader/keyhive-sync-server`, for a site that builds its own keyhive Repo.
+
+The new keyhive can't read state written by 0.3, so keyhive state moves to a new `<prefix>-keyhive-0.8` database and the old one is left untouched. Existing installs start with fresh keyhive state on upgrade.
+
+The keyhive access gates in `patchwork-elements` use ARK's `accessForDoc`, which replaces `bestAccessForDoc`. ARK no longer has public access, so a document opens only for its members.

core/bootloader/package.json

@@ -39,6 +39,10 @@
       "import": "./dist/storage.js",
       "types": "./dist/storage.d.ts"
     },
+    "./keyhive-sync-server": {
+      "import": "./dist/keyhive-sync-server.js",
+      "types": "./dist/keyhive-sync-server.d.ts"
+    },
     "./service-worker": {
       "import": "./dist/service-worker.js",
       "types": "./dist/service-worker.d.ts"

core/bootloader/src/automerge-protocol-handler.ts

@@ -22,13 +22,11 @@ import {
 } from "@automerge/automerge-repo/slim";
 
 import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
-import type {
-  AutomergeRepoKeyhive,
-  SyncServerSelection,
-} from "@automerge/automerge-repo-keyhive";
+import type { AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
 
 import { loadOrCreateSigner } from "./signer.js";
 import { keyhiveStorageName, storagePrefix } from "./storage.js";
+import { loadSyncServerIdentity } from "./keyhive-sync-server.js";
 import { startWorkerControl } from "./worker-control.js";
 import { AUTOMERGE_WASM, SUBDUCTION_WASM } from "./emitted.js";
 import { createResolver } from "./resolver.js";
@@ -41,7 +39,7 @@ import {
 
 declare const __SYNC_SERVER__: {
   url: string;
-  keyhive?: SyncServerSelection;
+  keyhive?: boolean;
   useIdFactory?: boolean;
 };
 
@@ -106,7 +104,7 @@ async function buildRepo(): Promise<Repo> {
   await initWasm();
 
   const { repo, hive } = syncServer.keyhive
-    ? await buildKeyhiveRepo(syncServer.keyhive)
+    ? await buildKeyhiveRepo()
     : { repo: await buildPlainRepo() };
 
   builtRepo = repo;
@@ -127,27 +125,27 @@ async function buildPlainRepo(): Promise<Repo> {
   });
 }
 
-async function buildKeyhiveRepo(
-  keyhiveSyncServer: SyncServerSelection
-): Promise<{ repo: Repo; hive: AutomergeRepoKeyhive }> {
+async function buildKeyhiveRepo(): Promise<{
+  repo: Repo;
+  hive: AutomergeRepoKeyhive;
+}> {
   const { initKeyhiveWasm, initializeAutomergeRepoKeyhive } =
     await import("@automerge/automerge-repo-keyhive");
   initKeyhiveWasm();
+  const keyhiveStorage = new IndexedDBStorageAdapter(keyhiveStorageName);
   const { hive, repo } = await initializeAutomergeRepoKeyhive({
     // ARK injects an `idFactory` deriving document ids from keyhive. A site
     // can opt out of it with `keyhive: { useIdFactory: false }`.
     createRepo: ({ idFactory, ...config }) =>
       new Repo(
         syncServer.useIdFactory === false ? config : { ...config, idFactory }
       ),
-    storage: new IndexedDBStorageAdapter(keyhiveStorageName),
+    storage: keyhiveStorage,
     peerIdSuffix:
       `${storagePrefix}-resolver` + Math.random().toString(36).slice(2),
     automaticArchiveIngestion: true,
     cachingMode: "periodic",
-    // ARK selects the relay via `syncServer`, which pairs the contact card with
-    // the matching peer id. Omitting it defaults to "subduction".
-    syncServer: keyhiveSyncServer,
+    syncServer: await loadSyncServerIdentity(syncServer.url, keyhiveStorage),
     repo: {
       storage: new IndexedDBStorageAdapter(),
       subductionWebsocketEndpoints: [syncServer.url],

core/bootloader/src/keyhive-sync-server.ts

@@ -0,0 +1,62 @@
+import type {
+  PeerId,
+  StorageAdapterInterface,
+} from "@automerge/automerge-repo/slim";
+import type { SyncServerIdentity } from "@automerge/automerge-repo-keyhive";
+
+const CONTACT_CARD_KEY = ["patchwork", "sync-server-contact-card"];
+
+/**
+ * The keyhive identity of the sync server at `url` (a ws:// or wss:// URL),
+ * which serves its contact card at `/keyhive/contact-card` on the same host.
+ *
+ * The card is fetched on every start so a server that has been redeployed
+ * with a new card is picked up. The last card fetched for each URL is kept
+ * in `storage` so a start without a network still has one. Fails only when
+ * no card can be fetched and none was saved for `url`.
+ *
+ * The card is trusted on first use. Nothing here checks it against a known
+ * identity so it is only as trustworthy as the connection it came over.
+ *
+ * Keyhive's wasm must be initialized before this is called.
+ */
+export async function loadSyncServerIdentity(
+  url: string,
+  storage: StorageAdapterInterface
+): Promise<SyncServerIdentity> {
+  const { ContactCard } = await import("@automerge/automerge-repo-keyhive");
+  const key = [...CONTACT_CARD_KEY, url];
+
+  // The server's keyhive identity and its subduction peer id are the same
+  // key. ARK identifies a peer by the base64 of that key.
+  const identity = (contactCard: Uint8Array): SyncServerIdentity => {
+    const id = ContactCard.fromBytes(contactCard).individualId.toBytes();
+    const peerId = btoa(String.fromCharCode(...id)) as PeerId;
+    return { contactCard, peerId };
+  };
+
+  try {
+    const fetched = identity(await fetchContactCard(url));
+    await storage.save(key, fetched.contactCard);
+    return fetched;
+  } catch (error) {
+    const saved = await storage.load(key);
+    if (!saved) {
+      throw new Error(`no keyhive contact card for ${url}`, { cause: error });
+    }
+    console.warn(
+      `using the saved keyhive contact card for ${url}. Fetching it failed`,
+      error
+    );
+    return identity(saved);
+  }
+}
+
+async function fetchContactCard(url: string): Promise<Uint8Array> {
+  const cardUrl = new URL("/keyhive/contact-card", url.replace(/^ws/, "http"));
+  const response = await fetch(cardUrl);
+  if (!response.ok) {
+    throw new Error(`GET ${cardUrl} responded with ${response.status}`);
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}

core/bootloader/src/storage.ts

@@ -13,10 +13,10 @@ export const storagePrefix =
     : DEFAULT_STORAGE_PREFIX;
 
 /**
- * The keyhive version this build stores state for. Keyhive versions can't read
- * each other's state, so each gets its own database; `${storagePrefix}-keyhive`
- * (no version) holds the state written by automerge-repo-keyhive 0.5.
+ * The automerge-repo-keyhive version this build stores keyhive state for.
+ * Versions can't read each other's state, so each gets its own database;
+ * `${storagePrefix}-keyhive` (no version) holds the state written by 0.5.
  */
-export const keyhiveStorageVersion = "0.6";
+export const keyhiveStorageVersion = "0.8";
 
 export const keyhiveStorageName = `${storagePrefix}-keyhive-${keyhiveStorageVersion}`;

core/elements/src/legacy-impl.ts

@@ -323,12 +323,12 @@ export class LegacyImpl {
     if (this.#element.hive && this.#docUrl) {
       // Legacy (padded-zero) doc: skip keyhive gate
       if (isKeyhiveDoc(this.#docUrl)) {
-        const bestAccess = await this.#element.hive.bestAccessForDoc(
+        const access = await this.#element.hive.accessForDoc(
           this.#element.hive.active.individual.id,
           this.#docUrl
         );
         if (epoch !== this.#initEpoch) return;
-        const accessLevel = bestAccess ? bestAccess.toString() : "None";
+        const accessLevel = access ? access.toString() : "None";
 
         if (accessLevel === "None") {
           this.#state = State.unable;
@@ -559,11 +559,11 @@ export class LegacyImpl {
       let accessCheckSucceeded = false;
       try {
         if (!isKeyhiveDoc(this.#docUrl)) return;
-        const bestAccess = await this.#element.hive.bestAccessForDoc(
+        const access = await this.#element.hive.accessForDoc(
           this.#element.hive.active.individual.id,
           this.#docUrl
         );
-        hasAccess = !!bestAccess;
+        hasAccess = !!access;
         accessCheckSucceeded = true;
       } catch {
         return;

core/elements/src/patchwork-view.ts

@@ -318,12 +318,12 @@ export function registerPatchworkViewElement(
           const keyhiveDoc = isKeyhiveDoc(this.url);
 
           if (keyhiveDoc) {
-            const bestAccess = await params.hive.bestAccessForDoc(
+            const access = await params.hive.accessForDoc(
               params.hive.active.individual.id,
               this.url
             );
             if (epoch !== this.#initEpoch) return;
-            const accessLevel = bestAccess ? bestAccess.toString() : "None";
+            const accessLevel = access ? access.toString() : "None";
 
             if (accessLevel === "None") {
               this.#state = State.unable;
@@ -508,11 +508,11 @@ export function registerPatchworkViewElement(
           let accessCheckSucceeded = false;
           try {
             if (!isKeyhiveDoc(this.url)) return;
-            const bestAccess = await params.hive.bestAccessForDoc(
+            const access = await params.hive.accessForDoc(
               params.hive.active.individual.id,
               this.url
             );
-            hasAccess = !!bestAccess;
+            hasAccess = !!access;
             accessCheckSucceeded = true;
           } catch {
             return;

core/patchwork/src/repo.ts

@@ -6,25 +6,23 @@ import {
   SUBDUCTION_WASM,
 } from "@inkandswitch/patchwork-bootloader/emitted";
 import * as AutomergeRepo from "@automerge/automerge-repo/slim";
-import type {
-  AutomergeRepoKeyhive,
-  SyncServerSelection,
-} from "@automerge/automerge-repo-keyhive";
+import type { AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
 // eslint-disable-next-line
 // @ts-ignore — the default init is a wasm-bindgen runtime helper not in the .d.ts
 import initSubduction from "@automerge/automerge-subduction/slim";
 import {
   keyhiveStorageName,
   storagePrefix,
 } from "@inkandswitch/patchwork-bootloader/storage";
+import { loadSyncServerIdentity } from "@inkandswitch/patchwork-bootloader/keyhive-sync-server";
 import type { SignerIdentity } from "./types.js";
 import debug from "debug";
 
 const log = debug("patchwork:setup:repo");
 
 declare const __SYNC_SERVER__: {
   url: string;
-  keyhive?: SyncServerSelection;
+  keyhive?: boolean;
   useIdFactory?: boolean;
 };
 const syncServer =
@@ -75,6 +73,7 @@ export async function createRepo(): Promise<TabRepo> {
     const { initKeyhiveWasm, initializeAutomergeRepoKeyhive } =
       await import("@automerge/automerge-repo-keyhive");
     initKeyhiveWasm();
+    const keyhiveStorage = new IndexedDBStorageAdapter(keyhiveStorageName);
     const { hive, repo } = await initializeAutomergeRepoKeyhive({
       // ARK injects an `idFactory` deriving document ids from keyhive. A site
       // can opt out of it with `keyhive: { useIdFactory: false }`.
@@ -84,12 +83,11 @@ export async function createRepo(): Promise<TabRepo> {
             ? repoConfig
             : { ...repoConfig, idFactory }
         ),
-      storage: new IndexedDBStorageAdapter(keyhiveStorageName),
+      storage: keyhiveStorage,
       peerIdSuffix: storagePrefix + Math.random().toString(36).slice(2),
       automaticArchiveIngestion: true,
       cachingMode: "periodic",
-      // ARK selects the relay via `syncServer`, defaulting to "subduction".
-      syncServer: syncServer.keyhive,
+      syncServer: await loadSyncServerIdentity(syncServer.url, keyhiveStorage),
       repo: {
         storage: new IndexedDBStorageAdapter(),
         subductionWebsocketEndpoints: [syncServer.url],

core/patchwork/src/site-kit/index.ts

@@ -12,7 +12,6 @@ export type {
   PatchworkIconsOptions,
   PatchworkHtmlOptions,
   PatchworkNetlifyOptions,
-  PatchworkKeyhiveSyncServer,
   PatchworkKeyhiveOptions,
   PatchworkSyncServersOptions,
 } from "./options.js";

core/patchwork/src/site-kit/options.ts

@@ -1,5 +1,3 @@
-import type { SyncServerIdentity } from "@automerge/automerge-repo-keyhive";
-
 /**
  * The bundler-agnostic option shape for a Patchwork site's generated
  * static assets (icons, index.html, manifest.webmanifest, Netlify config).
@@ -36,17 +34,7 @@ export interface PatchworkNetlifyOptions {
   immutableAssets?: boolean;
 }
 
-export type PatchworkKeyhiveSyncServer =
-  | "keyhive"
-  | "subduction"
-  | ({ url: string } & SyncServerIdentity);
-
 export interface PatchworkKeyhiveOptions {
-  /**
-   * Which relay ARK registers and grants access to. Default `"subduction"`.
-   * A custom identity also carries the WebSocket URL to reach it on.
-   */
-  syncServer?: PatchworkKeyhiveSyncServer;
   /**
    * Use the `idFactory` ARK injects into the repo config, which derives
    * document ids from keyhive. Default true. `false` drops it and lets the
@@ -58,7 +46,7 @@ export interface PatchworkKeyhiveOptions {
 export type PatchworkSyncServersOptions = {
   /** wss:// URL for the legacy automerge-repo sync-server channel (connected on demand via connectClassicSync). Default: wss://sync3.automerge.org. Pass false to skip its preconnect hint. */
   classic?: string | false;
-  /** wss:// URL for the subduction channel. Default: wss://subduction.sync.inkandswitch.com. Overrides the URL a named `keyhive.syncServer` would otherwise imply. */
+  /** wss:// URL for the subduction channel. Default: wss://subduction.sync.inkandswitch.com. A keyhive build uses it too, and fetches the server's contact card from `/keyhive/contact-card` on the same host. */
   subduction?: string;
 };
 
@@ -93,9 +81,9 @@ export interface PatchworkSiteOptions {
   backgroundColor?: string;
 
   /**
-   * Enables keyhive for this build. `true` takes every default; an object
-   * picks the relay and turns individual behaviour off. Omitted or `false`
-   * builds a plain subduction repo.
+   * Enables keyhive for this build, against the `syncServers.subduction`
+   * server. `true` takes every default; an object turns individual behaviour
+   * off. Omitted or `false` builds a plain subduction repo.
    */
   keyhive?: boolean | PatchworkKeyhiveOptions;
 

core/patchwork/src/site-kit/sync-servers.ts

@@ -1,5 +1,4 @@
 import type { PatchworkSiteOptions } from "./options.js";
-import type { SyncServerSelection } from "@automerge/automerge-repo-keyhive";
 
 // Mirrors core/bootloader/src/sync-config.ts's DEFAULT_CLASSIC_SYNC_SERVER
 // and automerge-protocol-handler-worker.ts's SUBDUCTION_SYNC_URL selection —
@@ -9,32 +8,19 @@ import type { SyncServerSelection } from "@automerge/automerge-repo-keyhive";
 export const DEFAULT_SYNC_SERVERS = {
   classic: "wss://sync3.automerge.org",
   subduction: "wss://subduction.sync.inkandswitch.com",
-  keyhive: "wss://keyhive.sync.automerge.org",
 };
 
 export function resolvePrimarySyncServer(options: PatchworkSiteOptions): {
   url: string;
-  keyhive?: SyncServerSelection;
+  keyhive?: boolean;
   useIdFactory?: boolean;
 } {
-  const subduction = (options.syncServers || undefined)?.subduction;
-  if (!options.keyhive) {
-    return { url: subduction ?? DEFAULT_SYNC_SERVERS.subduction };
-  }
+  const url =
+    (options.syncServers || undefined)?.subduction ??
+    DEFAULT_SYNC_SERVERS.subduction;
+  if (!options.keyhive) return { url };
   const keyhive = options.keyhive === true ? {} : options.keyhive;
-  const useIdFactory = keyhive.useIdFactory ?? true;
-  const syncServer = keyhive.syncServer ?? "subduction";
-  if (typeof syncServer === "string") {
-    return {
-      keyhive: syncServer,
-      url: subduction ?? DEFAULT_SYNC_SERVERS[syncServer],
-      useIdFactory,
-    };
-  }
-  // A custom relay carries the only URL it can be reached on, so it wins over
-  // `syncServers.subduction`.
-  const { url, ...identity } = syncServer;
-  return { keyhive: identity, url, useIdFactory };
+  return { url, keyhive: true, useIdFactory: keyhive.useIdFactory ?? true };
 }
 
 function wsToHttpOrigin(wsUrl: string): string {

core/patchwork/src/vite/patchwork-plugin.ts

@@ -87,7 +87,6 @@ export type {
   PatchworkIconsOptions,
   PatchworkHtmlOptions,
   PatchworkNetlifyOptions,
-  PatchworkKeyhiveSyncServer,
   PatchworkKeyhiveOptions,
   PatchworkSyncServersOptions,
 } from "../site-kit/options.js";