@powerhousedao/switchboard 6.2.3-dev.24 → 6.2.3-dev.26

package/dist/server.d.mts

@@ -5,8 +5,9 @@ import { IAttachmentService } from "@powerhousedao/reactor-attachments";
 import { IRenown } from "@renown/sdk/node";
 import { DriveInput } from "@powerhousedao/shared/document-drive";
 import { DocumentModelModule, SignaturePolicy, UpgradeManifest } from "@powerhousedao/shared/document-model";
+import "@powerhousedao/reactor-workflow";
+import "@powerhousedao/shared/processors";
 import { IRenown as IRenown$1 } from "@renown/sdk";
-
 //#region src/workflow-runtime.d.mts
 /** Whether the operation intake is indexing. Same shape as the attachment
  * reference projection, because it is the same limitation. */
@@ -24,26 +25,28 @@ type WorkflowTriggersCapability = {
  * `powerhouse/reactor-drive` is wired through `addDefaultReactorDrive` and
  * uses the relationship-based child graph.
  */
-type SwitchboardDriveDocumentType = "powerhouse/document-drive" | "powerhouse/reactor-drive";
+export type SwitchboardDriveDocumentType = "powerhouse/document-drive" | "powerhouse/reactor-drive";
 /** A {@link DriveInput} extended with the optional drive-container type. */
-type SwitchboardDriveInput = DriveInput & {
+export type SwitchboardDriveInput = DriveInput & {
   documentType?: SwitchboardDriveDocumentType;
 };
-type StorageOptions = {
+export type StorageOptions = {
   type: "filesystem" | "memory" | "postgres" | "browser";
   filesystemPath?: string;
   postgresUrl?: string;
 };
-type IdentityOptions = {
-  /** Path to the keypair file. Defaults to ~/.ph/keypair.json */keypairPath?: string;
+export type IdentityOptions = {
+  /** Path to the keypair file. Defaults to ~/.ph/keypair.json */
+  keypairPath?: string;
   /**
    * If true, won't start without an existing keypair.
    * Use this to ensure the switchboard only runs with an authenticated identity.
    */
-  requireExisting?: boolean; /** Base url of the Renown instance to use */
+  requireExisting?: boolean;
+  /** Base url of the Renown instance to use */
   baseUrl?: string;
 };
-type StartServerOptions = {
+export type StartServerOptions = {
   /**
    * Pre-built ReactorClientModule (typically from
    * `@powerhousedao/reactor#ReactorClientBuilder.buildModule`). When set, the
@@ -102,7 +105,8 @@ type StartServerOptions = {
    * When configured, the switchboard will load the keypair from `ph login`
    * and can authenticate with remote services on behalf of the user.
    */
-  identity?: IdentityOptions; /** Base URL for the attachment service; defaults to `PH_SWITCHBOARD_PUBLIC_URL` then `http(s)://localhost:${port}`. */
+  identity?: IdentityOptions;
+  /** Base URL for the attachment service; defaults to `PH_SWITCHBOARD_PUBLIC_URL` then `http(s)://localhost:${port}`. */
   attachmentServiceUrl?: string;
   mcp?: boolean;
   /** Powerhouse workflows: the runtime, its subgraph, its webhooks and its
@@ -167,14 +171,17 @@ type StartServerOptions = {
     dbPoolSize?: number;
   };
 };
-type SwitchboardReactor = {
+export type SwitchboardReactor = {
   defaultDriveUrl: string | undefined;
-  reactor: IReactorClient; /** Switchboard-backed remote attachment service over its own `/attachments/*` API, for downstream consumers. */
-  attachmentService: IAttachmentService; /** Whether the authoritative attachment-reference projection is active. */
+  reactor: IReactorClient;
+  /** Switchboard-backed remote attachment service over its own `/attachments/*` API, for downstream consumers. */
+  attachmentService: IAttachmentService;
+  /** Whether the authoritative attachment-reference projection is active. */
   attachmentReferenceProjection: AttachmentReferenceProjectionCapability;
   /** Whether the workflow runtime's operation intake is indexing. Undefined
    * when workflows are off; unavailable means no document trigger fires. */
-  workflowTriggers?: WorkflowTriggersCapability; /** The Renown instance if identity was initialized */
+  workflowTriggers?: WorkflowTriggersCapability;
+  /** The Renown instance if identity was initialized */
   renown: IRenown$1 | null;
   /**
    * Port the HTTP server actually bound to. May differ from the requested
@@ -198,20 +205,25 @@ type SwitchboardReactor = {
 //#endregion
 //#region src/builder-defaults.d.mts
 type SwitchboardReactorDefaultsOptions = {
-  documentModels?: DocumentModelModule[]; /** Upgrade manifests for versioned models, one per document type. */
-  upgradeManifests?: UpgradeManifest<readonly number[]>[]; /** Default true. */
+  documentModels?: DocumentModelModule[];
+  /** Upgrade manifests for versioned models, one per document type. */
+  upgradeManifests?: UpgradeManifest<readonly number[]>[];
+  /** Default true. */
   includeBaseModels?: boolean;
   /**
    * Channel scheme. Defaults to `ChannelScheme.SWITCHBOARD`, which populates
    * `reactorModule.syncModule.syncManager` — required by reactor-api. Set
    * to `false` only if the caller will configure a scheme themselves.
    */
-  channelScheme?: ChannelScheme | false; /** Defaults to true. Set false when the caller owns SIGINT handling. */
-  signalHandlers?: boolean; /** Executor tuning. Omit to use the reactor's own defaults. */
+  channelScheme?: ChannelScheme | false;
+  /** Defaults to true. Set false when the caller owns SIGINT handling. */
+  signalHandlers?: boolean;
+  /** Executor tuning. Omit to use the reactor's own defaults. */
   executorConfig?: {
     maxSkipThreshold?: number;
     featureFlags?: Partial<ReactorFeatureFlags>;
-  }; /** Wire dynamic document-model loading via HTTP. */
+  };
+  /** Wire dynamic document-model loading via HTTP. */
   documentModelLoader?: IDocumentModelLoader;
   logger?: ILogger;
   /**
@@ -224,10 +236,11 @@ type SwitchboardReactorDefaultsOptions = {
    * Which keys may sign as which users (typically from
    * `getRenownTrustPolicyConfig`); wins over one carried by `signer`.
    */
-  trustPolicy?: Pick<SignerConfig, "trustPolicy" | "workerTrustPolicy">; /** What the client creates new documents as; see `resolveCreateSignaturePolicy`. */
+  trustPolicy?: Pick<SignerConfig, "trustPolicy" | "workerTrustPolicy">;
+  /** What the client creates new documents as; see `resolveCreateSignaturePolicy`. */
   createSignaturePolicy?: SignaturePolicy;
 };
-declare function applySwitchboardReactorDefaults(reactorBuilder: ReactorBuilder, clientBuilder: ReactorClientBuilder, options?: SwitchboardReactorDefaultsOptions): void;
+export declare function applySwitchboardReactorDefaults(reactorBuilder: ReactorBuilder, clientBuilder: ReactorClientBuilder, options?: SwitchboardReactorDefaultsOptions): void;
 //#endregion
 //#region src/server.d.mts
 /**
@@ -235,9 +248,9 @@ declare function applySwitchboardReactorDefaults(reactorBuilder: ReactorBuilder,
  * the port is free, false if the OS reports it in use. Any other error is
  * surfaced so we don't silently mask real issues (permissions, bad host, …).
  */
-declare function isPortAvailable(port: number): Promise<boolean>;
+export declare function isPortAvailable(port: number): Promise<boolean>;
 /** Derive the remote attachment service config for switchboard's own `/attachments/*` API. */
-declare function deriveAttachmentServiceConfig(options: Pick<StartServerOptions, "attachmentServiceUrl" | "https">, serverPort: number, renown: IRenown | null): {
+export declare function deriveAttachmentServiceConfig(options: Pick<StartServerOptions, "attachmentServiceUrl" | "https">, serverPort: number, renown: IRenown | null): {
   remoteUrl: string;
   jwtHandler: JwtHandler | undefined;
 };
@@ -258,7 +271,8 @@ declare function deriveAttachmentServiceConfig(options: Pick<StartServerOptions,
  * trigger the `withShutdownHook` chain that disposes the api. Programmatic
  * full teardown isn't currently exposed — wire it via SIGINT/SIGTERM.
  */
-declare const startSwitchboard: (options?: StartServerOptions) => Promise<SwitchboardReactor>;
+export declare const startSwitchboard: (options?: StartServerOptions) => Promise<SwitchboardReactor>;
 //#endregion
-export { IdentityOptions, StartServerOptions, StorageOptions, SwitchboardDriveDocumentType, SwitchboardDriveInput, SwitchboardReactor, type SwitchboardReactorDefaultsOptions, type WorkflowTriggersCapability, applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, startSwitchboard };
+export type { SwitchboardReactorDefaultsOptions, WorkflowTriggersCapability };
+export {};
 //# sourceMappingURL=server.d.mts.map

package/dist/server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/server.mts"],"mappings":";;;;;;;;;;AAmDA;;AAAA,KAAY,0BAAA;EACN,MAAA;AAAA;EAEA,MAAA;EACA,MAAA;AAAA;;;;;;;AAJN;;KCjCY,4BAAA;;KAKA,qBAAA,GAAwB,UAAA;EAClC,YAAA,GAAe,4BAAA;AAAA;AAAA,KAGL,cAAA;EACV,IAAA;EACA,cAAA;EACA,WAAA;AAAA;AAAA,KAGU,eAAA;EAf4B,+DAiBtC,WAAA;EAjBsC;;AAKxC;;EAiBE,eAAA,YAhB2C;EAmB3C,OAAA;AAAA;AAAA,KAGU,kBAAA;EAtBiC;;AAG7C;;;;;;;;;AAMA;;;;;;;;;EAkCE,OAAA,GAAU,4BAAA;EArBkB;;;;;;;EA6B5B,kBAAA;EAmDgB;;;;;;EA5ChB,WAAA;EACA,UAAA;EACA,IAAA;EAQA;;;;;EAFA,UAAA;EACA,GAAA;EACA,MAAA;EACA,KAAA,GAAQ,qBAAA;EACR,QAAA;EACA,YAAA;EACA,KAAA;IAEM,OAAA;IACA,QAAA;EAAA;EAkBY;;;;;EATlB,QAAA,GAAW,eAAA,EA4BX;EA1BA,oBAAA;EACA,GAAA;EA6CE;;EA1CF,SAAA;IACE,OAAA;EAAA;EAEF,eAAA,GAAkB,GAAA;EAClB,oBAAA;EACA,4BAAA;EAwDU;;;;;EAlDV,mBAAA;EACA,MAAA,GAAS,OAAA;EA4DD;;;;;;;;;EAlDR,aAAA;EA6C+B;;;;;;;;;EAnC/B,cAAA;;;;AC7HF;;;;;EDsIE,UAAA;IACE,UAAA;IACA,mBAAA;IACA,gBAAA;EAAA;EC3GO;;;;;;;;;EDsHT,gBAAA;IACE,OAAA;IACA,UAAA;EAAA;AAAA;AAAA,KAIQ,kBAAA;EACV,eAAA;EACA,OAAA,EAAS,cAAA,ECxIQ;ED0IjB,iBAAA,EAAmB,kBAAA,ECvInB;EDyIA,6BAAA,EAA+B,uCAAA;ECxI/B;;ED2IA,gBAAA,GAAmB,0BAAA,ECrIV;EDuIT,MAAA,EAAQ,SAAA;EClIM;;;;EDuId,IAAA;ECrIuC;AAsBzC;;;;;;;;;;;ED4HE,QAAA,QAAgB,OAAA;AAAA;;;KCvLN,iCAAA;EAIV,cAAA,GAAiB,mBAAA;EAEjB,gBAAA,GAAmB,eAAA;EAEnB,iBAAA;;;AFsBF;;;EEhBE,aAAA,GAAgB,aAAA,UFiBZ;EEfJ,cAAA,YFkBI;EEhBJ,cAAA;IACE,gBAAA;IACA,YAAA,GAAe,OAAA,CAAQ,mBAAA;EAAA;EAGzB,mBAAA,GAAsB,oBAAA;EACtB,MAAA,GAAS,OAAA;;;;ADtBX;;EC4BE,MAAA,GAAS,YAAA;ED3BkC;;;;ECgC3C,WAAA,GAAc,IAAA,CAAK,YAAA,wCDhCwB;ECkC3C,qBAAA,GAAwB,eAAA;AAAA;AAAA,iBAsBV,+BAAA,CACd,cAAA,EAAgB,cAAA,EAChB,aAAA,EAAe,oBAAA,EACf,OAAA,GAAS,iCAAA;;;;;;;;iBC4DK,eAAA,CAAgB,IAAA,WAAe,OAAA;;iBAoI/B,6BAAA,CACd,OAAA,EAAS,IAAA,CAAK,kBAAA,qCACd,UAAA,UACA,MAAA,EAAQ,OAAA;EACL,SAAA;EAAmB,UAAA,EAAY,UAAA;AAAA;;;;;;;;;;AFrQpC;;;;;AAKA;;;cE0oCa,gBAAA,GACX,OAAA,GAAS,kBAAA,KACR,OAAA,CAAQ,kBAAA"}
+{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;;KAoDY;EACN;;EAEA;EACA;;;;;;;;;;YCtCM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;EACA;;;EAGA;IACE;;EAEF,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;YAIQ;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KCvLN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;;;;;wBC6DK,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAm5BvB,mBAAgB,UAClB,uBACR,QAAQ"}

package/dist/server.mjs

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-import { i as applySwitchboardReactorDefaults, n as isPortAvailable, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-BFbus-at.mjs";
-import "./utils-BBHt2kdo.mjs";
+import { i as applySwitchboardReactorDefaults, n as isPortAvailable, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-DQCIIJzK.mjs";
 export { applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, startSwitchboard };
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89634554-85dd-5e2b-99fe-485c1c36fe72")}catch(e){}}();
-//# debugId=89634554-85dd-5e2b-99fe-485c1c36fe72
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c9f85b61-fdcb-5fe1-9b94-cceba4f2a89d")}catch(e){}}();
+//# debugId=c9f85b61-fdcb-5fe1-9b94-cceba4f2a89d

package/dist/{utils-BBHt2kdo.mjs → utils-uaBlzyjS.mjs}

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a69847ec-becf-5c25-988b-cd47759b2c19")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5ece528d-aafb-5305-a04d-e0c45c8c30a3")}catch(e){}}();
 import { reactorDriveCreateDocument, reactorDriveCreateState } from "@powerhousedao/reactor-drive";
 import { driveCreateDocument, driveCreateState } from "@powerhousedao/shared/document-drive";
 import { withSignaturePolicy } from "@powerhousedao/shared/document-model";
@@ -82,5 +82,5 @@ function isPostgresUrl(url) {
 //#endregion
 export { addDefaultReactorDrive as n, isPostgresUrl as r, addDefaultDrive as t };
 
-//# sourceMappingURL=utils-BBHt2kdo.mjs.map
-//# debugId=a69847ec-becf-5c25-988b-cd47759b2c19
+//# sourceMappingURL=utils-uaBlzyjS.mjs.map
+//# debugId=5ece528d-aafb-5305-a04d-e0c45c8c30a3

package/dist/{utils-BBHt2kdo.mjs.map → utils-uaBlzyjS.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"utils-BBHt2kdo.mjs","sources":["../src/utils.mts"],"sourcesContent":["import type { IReactorClient } from \"@powerhousedao/reactor\";\nimport {\n  reactorDriveCreateDocument,\n  reactorDriveCreateState,\n} from \"@powerhousedao/reactor-drive\";\nimport {\n  driveCreateDocument,\n  driveCreateState,\n} from \"@powerhousedao/shared/document-drive\";\nimport type { DriveInput } from \"@powerhousedao/shared/document-drive\";\nimport {\n  withSignaturePolicy,\n  type PHDocument,\n} from \"@powerhousedao/shared/document-model\";\n\n/**\n * A configured id pins the drive, and only a legacy drive can take a chosen\n * id; otherwise the client's creation default applies.\n */\nasync function underCreatePolicy<TDocument extends PHDocument>(\n  client: IReactorClient,\n  document: TDocument,\n  id: string | undefined,\n): Promise<TDocument> {\n  return id\n    ? withSignaturePolicy(document, \"legacy\", { id })\n    : withSignaturePolicy(document, await client.getCreateSignaturePolicy());\n}\n\nexport async function addDefaultDrive(\n  client: IReactorClient,\n  drive: DriveInput,\n  serverPort: number,\n) {\n  let driveId = drive.id;\n  if (!driveId || driveId.length === 0) {\n    driveId = drive.slug;\n  }\n\n  if (!driveId || driveId.length === 0) {\n    throw new Error(\"Invalid Drive Id\");\n  }\n\n  // check if the drive already exists\n  let existingDrive;\n  try {\n    existingDrive = await client.get(driveId);\n  } catch {\n    //\n  }\n\n  // already exists, return the existing drive url\n  if (existingDrive) {\n    return `http://localhost:${serverPort}/d/${driveId}`;\n  }\n\n  const { global } = driveCreateState();\n  const created = driveCreateDocument({\n    global: {\n      ...global,\n      name: drive.global.name,\n      icon: drive.global.icon ?? global.icon,\n    },\n    local: {\n      availableOffline: drive.local?.availableOffline ?? false,\n      sharingType: drive.local?.sharingType ?? \"public\",\n      listeners: drive.local?.listeners ?? [],\n      triggers: drive.local?.triggers ?? [],\n    },\n  });\n\n  const document = await underCreatePolicy(client, created, drive.id);\n  if (drive.slug && drive.slug.length > 0) {\n    document.header.slug = drive.slug;\n  }\n  if (drive.global.name) {\n    document.header.name = drive.global.name;\n  }\n  if (drive.preferredEditor) {\n    document.header.meta = { preferredEditor: drive.preferredEditor };\n  }\n\n  try {\n    await client.create(document);\n  } catch (e) {\n    const errorMessage = e instanceof Error ? e.message : String(e);\n    if (!errorMessage.includes(\"already exists\")) {\n      throw e;\n    }\n  }\n\n  return `http://localhost:${serverPort}/d/${driveId}`;\n}\n\nexport async function addDefaultReactorDrive(\n  client: IReactorClient,\n  drive: DriveInput,\n  serverPort: number,\n) {\n  let driveId = drive.id;\n  if (!driveId || driveId.length === 0) {\n    driveId = drive.slug;\n  }\n\n  if (!driveId || driveId.length === 0) {\n    throw new Error(\"Invalid Drive Id\");\n  }\n\n  let existingDrive;\n  try {\n    existingDrive = await client.get(driveId);\n  } catch {\n    //\n  }\n\n  if (existingDrive) {\n    return `http://localhost:${serverPort}/d/${driveId}`;\n  }\n\n  const { global, local } = reactorDriveCreateState();\n  const created = reactorDriveCreateDocument({\n    global: {\n      ...global,\n      name: drive.global.name,\n      icon: drive.global.icon ?? global.icon,\n    },\n    local: {\n      ...local,\n      availableOffline: drive.local?.availableOffline ?? local.availableOffline,\n      sharingType: drive.local?.sharingType ?? local.sharingType,\n    },\n  });\n\n  const document = await underCreatePolicy(client, created, drive.id);\n  if (drive.slug && drive.slug.length > 0) {\n    document.header.slug = drive.slug;\n  }\n  if (drive.global.name) {\n    document.header.name = drive.global.name;\n  }\n  if (drive.preferredEditor) {\n    document.header.meta = { preferredEditor: drive.preferredEditor };\n  }\n\n  try {\n    await client.create(document);\n  } catch (e) {\n    const errorMessage = e instanceof Error ? e.message : String(e);\n    if (!errorMessage.includes(\"already exists\")) {\n      throw e;\n    }\n  }\n\n  return `http://localhost:${serverPort}/d/${driveId}`;\n}\n\nexport function isPostgresUrl(url: string) {\n  return url.startsWith(\"postgresql\") || url.startsWith(\"postgres\");\n}\n"],"names":[],"mappings":";;;;;;;;;;AAmBA,eAAe,kBACb,QACA,UACA,IACoB;AACpB,QAAO,KACH,oBAAoB,UAAU,UAAU,EAAE,IAAI,CAAC,GAC/C,oBAAoB,UAAU,MAAM,OAAO,0BAA0B,CAAC;;AAG5E,eAAsB,gBACpB,QACA,OACA,YACA;CACA,IAAI,UAAU,MAAM;AACpB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,WAAU,MAAM;AAGlB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,OAAM,IAAI,MAAM,mBAAmB;CAIrC,IAAI;AACJ,KAAI;AACF,kBAAgB,MAAM,OAAO,IAAI,QAAQ;SACnC;AAKR,KAAI,cACF,QAAO,oBAAoB,WAAW,KAAK;CAG7C,MAAM,EAAE,WAAW,kBAAkB;CAerC,MAAM,WAAW,MAAM,kBAAkB,QAdzB,oBAAoB;EAClC,QAAQ;GACN,GAAG;GACH,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO,QAAQ,OAAO;GACnC;EACD,OAAO;GACL,kBAAkB,MAAM,OAAO,oBAAoB;GACnD,aAAa,MAAM,OAAO,eAAe;GACzC,WAAW,MAAM,OAAO,aAAa,EAAE;GACvC,UAAU,MAAM,OAAO,YAAY,EAAE;GACtC;EACF,CAAC,EAEwD,MAAM,GAAG;AACnE,KAAI,MAAM,QAAQ,MAAM,KAAK,SAAS,EACpC,UAAS,OAAO,OAAO,MAAM;AAE/B,KAAI,MAAM,OAAO,KACf,UAAS,OAAO,OAAO,MAAM,OAAO;AAEtC,KAAI,MAAM,gBACR,UAAS,OAAO,OAAO,EAAE,iBAAiB,MAAM,iBAAiB;AAGnE,KAAI;AACF,QAAM,OAAO,OAAO,SAAS;UACtB,GAAG;AAEV,MAAI,EADiB,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,EAC7C,SAAS,iBAAiB,CAC1C,OAAM;;AAIV,QAAO,oBAAoB,WAAW,KAAK;;AAG7C,eAAsB,uBACpB,QACA,OACA,YACA;CACA,IAAI,UAAU,MAAM;AACpB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,WAAU,MAAM;AAGlB,KAAI,CAAC,WAAW,QAAQ,WAAW,EACjC,OAAM,IAAI,MAAM,mBAAmB;CAGrC,IAAI;AACJ,KAAI;AACF,kBAAgB,MAAM,OAAO,IAAI,QAAQ;SACnC;AAIR,KAAI,cACF,QAAO,oBAAoB,WAAW,KAAK;CAG7C,MAAM,EAAE,QAAQ,UAAU,yBAAyB;CAcnD,MAAM,WAAW,MAAM,kBAAkB,QAbzB,2BAA2B;EACzC,QAAQ;GACN,GAAG;GACH,MAAM,MAAM,OAAO;GACnB,MAAM,MAAM,OAAO,QAAQ,OAAO;GACnC;EACD,OAAO;GACL,GAAG;GACH,kBAAkB,MAAM,OAAO,oBAAoB,MAAM;GACzD,aAAa,MAAM,OAAO,eAAe,MAAM;GAChD;EACF,CAAC,EAEwD,MAAM,GAAG;AACnE,KAAI,MAAM,QAAQ,MAAM,KAAK,SAAS,EACpC,UAAS,OAAO,OAAO,MAAM;AAE/B,KAAI,MAAM,OAAO,KACf,UAAS,OAAO,OAAO,MAAM,OAAO;AAEtC,KAAI,MAAM,gBACR,UAAS,OAAO,OAAO,EAAE,iBAAiB,MAAM,iBAAiB;AAGnE,KAAI;AACF,QAAM,OAAO,OAAO,SAAS;UACtB,GAAG;AAEV,MAAI,EADiB,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,EAC7C,SAAS,iBAAiB,CAC1C,OAAM;;AAIV,QAAO,oBAAoB,WAAW,KAAK;;AAG7C,SAAgB,cAAc,KAAa;AACzC,QAAO,IAAI,WAAW,aAAa,IAAI,IAAI,WAAW,WAAW","debug_id":"a69847ec-becf-5c25-988b-cd47759b2c19"}
+{"version":3,"file":"utils-uaBlzyjS.mjs","sources":["../src/utils.mts"],"sourcesContent":["import type { IReactorClient } from \"@powerhousedao/reactor\";\nimport {\n  reactorDriveCreateDocument,\n  reactorDriveCreateState,\n} from \"@powerhousedao/reactor-drive\";\nimport {\n  driveCreateDocument,\n  driveCreateState,\n} from \"@powerhousedao/shared/document-drive\";\nimport type { DriveInput } from \"@powerhousedao/shared/document-drive\";\nimport {\n  withSignaturePolicy,\n  type PHDocument,\n} from \"@powerhousedao/shared/document-model\";\n\n/**\n * A configured id pins the drive, and only a legacy drive can take a chosen\n * id; otherwise the client's creation default applies.\n */\nasync function underCreatePolicy<TDocument extends PHDocument>(\n  client: IReactorClient,\n  document: TDocument,\n  id: string | undefined,\n): Promise<TDocument> {\n  return id\n    ? withSignaturePolicy(document, \"legacy\", { id })\n    : withSignaturePolicy(document, await client.getCreateSignaturePolicy());\n}\n\nexport async function addDefaultDrive(\n  client: IReactorClient,\n  drive: DriveInput,\n  serverPort: number,\n) {\n  let driveId = drive.id;\n  if (!driveId || driveId.length === 0) {\n    driveId = drive.slug;\n  }\n\n  if (!driveId || driveId.length === 0) {\n    throw new Error(\"Invalid Drive Id\");\n  }\n\n  // check if the drive already exists\n  let existingDrive;\n  try {\n    existingDrive = await client.get(driveId);\n  } catch {\n    //\n  }\n\n  // already exists, return the existing drive url\n  if (existingDrive) {\n    return `http://localhost:${serverPort}/d/${driveId}`;\n  }\n\n  const { global } = driveCreateState();\n  const created = driveCreateDocument({\n    global: {\n      ...global,\n      name: drive.global.name,\n      icon: drive.global.icon ?? global.icon,\n    },\n    local: {\n      availableOffline: drive.local?.availableOffline ?? false,\n      sharingType: drive.local?.sharingType ?? \"public\",\n      listeners: drive.local?.listeners ?? [],\n      triggers: drive.local?.triggers ?? [],\n    },\n  });\n\n  const document = await underCreatePolicy(client, created, drive.id);\n  if (drive.slug && drive.slug.length > 0) {\n    document.header.slug = drive.slug;\n  }\n  if (drive.global.name) {\n    document.header.name = drive.global.name;\n  }\n  if (drive.preferredEditor) {\n    document.header.meta = { preferredEditor: drive.preferredEditor };\n  }\n\n  try {\n    await client.create(document);\n  } catch (e) {\n    const errorMessage = e instanceof Error ? e.message : String(e);\n    if (!errorMessage.includes(\"already exists\")) {\n      throw e;\n    }\n  }\n\n  return `http://localhost:${serverPort}/d/${driveId}`;\n}\n\nexport async function addDefaultReactorDrive(\n  client: IReactorClient,\n  drive: DriveInput,\n  serverPort: number,\n) {\n  let driveId = drive.id;\n  if (!driveId || driveId.length === 0) {\n    driveId = drive.slug;\n  }\n\n  if (!driveId || driveId.length === 0) {\n    throw new Error(\"Invalid Drive Id\");\n  }\n\n  let existingDrive;\n  try {\n    existingDrive = await client.get(driveId);\n  } catch {\n    //\n  }\n\n  if (existingDrive) {\n    return `http://localhost:${serverPort}/d/${driveId}`;\n  }\n\n  const { global, local } = reactorDriveCreateState();\n  const created = reactorDriveCreateDocument({\n    global: {\n      ...global,\n      name: drive.global.name,\n      icon: drive.global.icon ?? global.icon,\n    },\n    local: {\n      ...local,\n      availableOffline: drive.local?.availableOffline ?? local.availableOffline,\n      sharingType: drive.local?.sharingType ?? local.sharingType,\n    },\n  });\n\n  const document = await underCreatePolicy(client, created, drive.id);\n  if (drive.slug && drive.slug.length > 0) {\n    document.header.slug = drive.slug;\n  }\n  if (drive.global.name) {\n    document.header.name = drive.global.name;\n  }\n  if (drive.preferredEditor) {\n    document.header.meta = { preferredEditor: drive.preferredEditor };\n  }\n\n  try {\n    await client.create(document);\n  } catch (e) {\n    const errorMessage = e instanceof Error ? e.message : String(e);\n    if (!errorMessage.includes(\"already exists\")) {\n      throw e;\n    }\n  }\n\n  return `http://localhost:${serverPort}/d/${driveId}`;\n}\n\nexport function isPostgresUrl(url: string) {\n  return url.startsWith(\"postgresql\") || url.startsWith(\"postgres\");\n}\n"],"names":[],"mappings":"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","debug_id":"5ece528d-aafb-5305-a04d-e0c45c8c30a3"}

package/dist/utils.d.mts

@@ -1,10 +1,9 @@
 import { IReactorClient } from "@powerhousedao/reactor";
 import { DriveInput } from "@powerhousedao/shared/document-drive";
-
 //#region src/utils.d.mts
-declare function addDefaultDrive(client: IReactorClient, drive: DriveInput, serverPort: number): Promise<string>;
-declare function addDefaultReactorDrive(client: IReactorClient, drive: DriveInput, serverPort: number): Promise<string>;
-declare function isPostgresUrl(url: string): boolean;
+export declare function addDefaultDrive(client: IReactorClient, drive: DriveInput, serverPort: number): Promise<string>;
+export declare function addDefaultReactorDrive(client: IReactorClient, drive: DriveInput, serverPort: number): Promise<string>;
+export declare function isPostgresUrl(url: string): boolean;
 //#endregion
-export { addDefaultDrive, addDefaultReactorDrive, isPostgresUrl };
+export {};
 //# sourceMappingURL=utils.d.mts.map

package/dist/utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.mts"],"mappings":";;;;iBA6BsB,eAAA,CACpB,MAAA,EAAQ,cAAA,EACR,KAAA,EAAO,UAAA,EACP,UAAA,WAAkB,OAAA;AAAA,iBA8DE,sBAAA,CACpB,MAAA,EAAQ,cAAA,EACR,KAAA,EAAO,UAAA,EACP,UAAA,WAAkB,OAAA;AAAA,iBA2DJ,aAAA,CAAc,GAAA"}
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.mts"],"mappings":";;;wBA6BsB,gBACpB,QAAQ,gBACR,OAAO,YACP,qBAAkB;wBA8DE,uBACpB,QAAQ,gBACR,OAAO,YACP,qBAAkB;wBA2DJ,cAAc"}

package/dist/utils.mjs

@@ -1,4 +1,4 @@
-import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-BBHt2kdo.mjs";
+import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-uaBlzyjS.mjs";
 export { addDefaultDrive, addDefaultReactorDrive, isPostgresUrl };
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4dfe0eb9-58d9-5240-969e-d37feaef290c")}catch(e){}}();
-//# debugId=4dfe0eb9-58d9-5240-969e-d37feaef290c
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e030fa72-327e-52e2-9ac0-68feb4ef300a")}catch(e){}}();
+//# debugId=e030fa72-327e-52e2-9ac0-68feb4ef300a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.2.3-dev.24",
+  "version": "6.2.3-dev.26",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "@openfeature/core": "1.9.1",
     "@openfeature/env-var-provider": "0.3.1",
     "@openfeature/server-sdk": "1.19.0",
-    "@powerhousedao/config": "6.2.3-dev.24",
+    "@powerhousedao/config": "6.2.3-dev.26",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
@@ -55,36 +55,36 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.24",
-    "@powerhousedao/reactor": "6.2.3-dev.24",
-    "@powerhousedao/shared": "6.2.3-dev.24",
-    "@powerhousedao/vetra": "6.2.3-dev.24",
-    "@powerhousedao/reactor-api": "6.2.3-dev.24",
-    "@powerhousedao/reactor-attachments": "6.2.3-dev.24",
-    "@powerhousedao/reactor-drive": "6.2.3-dev.24",
-    "@powerhousedao/reactor-group": "6.2.3-dev.24",
-    "@powerhousedao/reactor-workflow": "6.2.3-dev.24",
-    "@powerhousedao/workflow": "6.2.3-dev.24",
-    "@powerhousedao/pglite-fs": "6.2.3-dev.24",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.26",
+    "@powerhousedao/reactor": "6.2.3-dev.26",
+    "@powerhousedao/shared": "6.2.3-dev.26",
+    "@powerhousedao/vetra": "6.2.3-dev.26",
+    "@powerhousedao/reactor-api": "6.2.3-dev.26",
+    "@powerhousedao/reactor-attachments": "6.2.3-dev.26",
+    "@powerhousedao/reactor-drive": "6.2.3-dev.26",
+    "@powerhousedao/reactor-group": "6.2.3-dev.26",
+    "@powerhousedao/reactor-workflow": "6.2.3-dev.26",
+    "@powerhousedao/workflow": "6.2.3-dev.26",
+    "@powerhousedao/pglite-fs": "6.2.3-dev.26",
     "@pyroscope/nodejs": "^0.4.5",
-    "@renown/sdk": "6.2.3-dev.24",
+    "@renown/sdk": "6.2.3-dev.26",
     "@sentry/node": "^10.53.1",
     "@sentry/opentelemetry": "^10.53.1",
-    "document-model": "6.2.3-dev.24",
+    "document-model": "6.2.3-dev.26",
     "dotenv": "^16.4.7",
-    "express": "^4.21.2",
+    "express": "^4.22.1",
     "graphql": "^16",
     "graphql-tag": "^2",
     "kysely": "0.28.16",
     "kysely-pglite-dialect": "1.2.0",
     "pg": "8.18.0",
-    "vite": "8.0.10"
+    "vite": "8.3.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.25",
     "@types/node": "25.2.3",
     "@types/pg": "8.16.0",
-    "tsdown": "0.21.1",
+    "tsdown": "0.23.0",
     "concurrently": "9.2.1",
     "nodemon": "3.1.11",
     "react": "19.2.6",

package/test/attachments/byte-grants.test.ts

@@ -0,0 +1,287 @@
+import type { AttachmentHash } from "@powerhousedao/reactor";
+import type { AttachmentBuildResult } from "@powerhousedao/reactor-attachments";
+import type {
+  AttachmentAccessResult,
+  IAttachmentAccessService,
+} from "@powerhousedao/reactor-api";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Writable } from "node:stream";
+import { describe, expect, it, vi } from "vitest";
+import type { AttachmentActorContext } from "../../src/attachments/auth.js";
+import {
+  makeDownloadHandler,
+  makeStatHandler,
+} from "../../src/attachments/routes.js";
+import { AttachmentUrlSigner } from "../../src/attachments/url-signer.js";
+
+const HASH = "c".repeat(64) as AttachmentHash;
+const REF = `attachment://v1:${HASH}`;
+const NOW_MS = Date.parse("2026-09-24T00:00:00.000Z");
+const SIGNER = new AttachmentUrlSigner("s".repeat(32), () => NOW_MS);
+
+const ACTOR: AttachmentActorContext = {
+  user: {
+    address: "0xreader",
+    chainId: 1,
+    networkId: "mainnet",
+    appKey: "did:key:zApp",
+  },
+  authEnabled: true,
+};
+
+const HEADER = {
+  hash: HASH,
+  status: "available",
+  mimeType: "text/plain",
+  fileName: "a.txt",
+  sizeBytes: 0,
+  extension: "txt",
+  createdAtUtc: "2026-09-01T00:00:00.000Z",
+  lastAccessedAtUtc: "2026-09-01T00:00:00.000Z",
+  expiresAtUtc: null,
+};
+
+function makeReq(query: string): IncomingMessage {
+  return {
+    method: "GET",
+    url: `/attachments/${HASH}${query}`,
+    headers: {},
+    params: { hash: HASH },
+    once: () => undefined,
+  } as unknown as IncomingMessage;
+}
+
+function makeRes() {
+  const headers: Record<string, string> = {};
+  const chunks: Buffer[] = [];
+  const res = new Writable({
+    write(chunk: Buffer, _encoding, callback) {
+      chunks.push(Buffer.from(chunk));
+      callback();
+    },
+  });
+  Object.assign(res, {
+    statusCode: 200,
+    setHeader(name: string, value: string | number | readonly string[]) {
+      headers[name.toLowerCase()] = String(value);
+    },
+  });
+  Object.defineProperty(res, "_headers", { get: () => headers });
+  Object.defineProperty(res, "_body", {
+    get: () => Buffer.concat(chunks).toString("utf8"),
+  });
+  return res as unknown as ServerResponse & {
+    readonly _headers: Record<string, string>;
+    readonly _body: string;
+  };
+}
+
+function makeAttachments() {
+  const stat = vi.fn().mockResolvedValue(HEADER);
+  const get = vi.fn().mockResolvedValue({
+    header: HEADER,
+    body: new ReadableStream<Uint8Array>({ start: (c) => c.close() }),
+  });
+  return {
+    attachments: { store: { stat, get } } as unknown as AttachmentBuildResult,
+    stat,
+    get,
+  };
+}
+
+function makeAccess(result: AttachmentAccessResult | Error) {
+  const canReadAttachment = vi.fn(() =>
+    result instanceof Error ? Promise.reject(result) : Promise.resolve(result),
+  );
+  return {
+    access: { canReadAttachment } as IAttachmentAccessService,
+    canReadAttachment,
+  };
+}
+
+const ALLOWED: AttachmentAccessResult = {
+  kind: "allowed",
+  documentId: "canonical-doc" as never,
+  ref: REF as never,
+};
+
+function signedQuery(documentId = "doc-1", ttl = 300): string {
+  return `?${SIGNER.sign(HASH, documentId, ttl).query}`;
+}
+
+describe.each([
+  ["HEAD", makeStatHandler, "stat"],
+  ["GET", makeDownloadHandler, "get"],
+] as const)("%s /attachments/:hash grants", (_, makeHandler, storeCall) => {
+  async function run(
+    query: string,
+    access: IAttachmentAccessService,
+    actor: AttachmentActorContext | undefined = ACTOR,
+    signer: AttachmentUrlSigner | null = SIGNER,
+  ) {
+    const store = makeAttachments();
+    const res = makeRes();
+    await makeHandler(store.attachments, access, signer)(
+      makeReq(query),
+      res,
+      undefined,
+      actor,
+    );
+    return { res, store: store[storeCall] };
+  }
+
+  it("refuses a hash-only request with 404 without consulting access or storage", async () => {
+    const { access, canReadAttachment } = makeAccess(ALLOWED);
+    const { res, store } = await run("", access);
+
+    expect(res.statusCode).toBe(404);
+    expect(JSON.parse(res._body)).toEqual({ error: "Attachment not found" });
+    expect(canReadAttachment).not.toHaveBeenCalled();
+    expect(store).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["duplicated", "?documentId=a&documentId=b"],
+    ["blank", "?documentId=%20"],
+  ])("refuses a %s documentId with 404", async (_, query) => {
+    const { access, canReadAttachment } = makeAccess(ALLOWED);
+    const { res } = await run(query, access);
+
+    expect(res.statusCode).toBe(404);
+    expect(canReadAttachment).not.toHaveBeenCalled();
+  });
+
+  it("authorizes a documentId through the access service as the caller", async () => {
+    const { access, canReadAttachment } = makeAccess(ALLOWED);
+    const { res, store } = await run("?documentId=doc-1", access);
+
+    expect(res.statusCode).toBe(200);
+    expect(res._headers["cache-control"]).toBe("private");
+    expect(canReadAttachment).toHaveBeenCalledWith({
+      documentId: "doc-1",
+      attachmentRef: REF,
+      userAddress: "0xreader",
+      appKey: "did:key:zApp",
+    });
+    expect(store).toHaveBeenCalledOnce();
+  });
+
+  it("passes the anonymous caller as an empty subject", async () => {
+    const { access, canReadAttachment } = makeAccess(ALLOWED);
+    await run("?documentId=doc-1", access, {
+      user: undefined,
+      authEnabled: true,
+    });
+
+    expect(canReadAttachment).toHaveBeenCalledWith(
+      expect.objectContaining({ userAddress: undefined, appKey: undefined }),
+    );
+  });
+
+  it("answers a denied decision with the same 404 as an unknown hash", async () => {
+    const { access } = makeAccess({ kind: "denied" });
+    const { res, store } = await run("?documentId=doc-1", access);
+
+    expect(res.statusCode).toBe(404);
+    expect(JSON.parse(res._body)).toEqual({ error: "Attachment not found" });
+    expect(store).not.toHaveBeenCalled();
+  });
+
+  it("answers projection-unavailable with 503", async () => {
+    const { access } = makeAccess({ kind: "projection-unavailable" });
+    const { res, store } = await run("?documentId=doc-1", access);
+
+    expect(res.statusCode).toBe(503);
+    expect(store).not.toHaveBeenCalled();
+  });
+
+  it("answers an access failure with an opaque 500", async () => {
+    const { access } = makeAccess(new Error("db down"));
+    const { res, store } = await run("?documentId=doc-1", access);
+
+    expect(res.statusCode).toBe(500);
+    expect(res._body).not.toContain("db down");
+    expect(store).not.toHaveBeenCalled();
+  });
+
+  it("serves a valid signed URL without re-running the gate, even anonymously", async () => {
+    const { access, canReadAttachment } = makeAccess({ kind: "denied" });
+    const { res, store } = await run(signedQuery(), access, {
+      user: undefined,
+      authEnabled: true,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(canReadAttachment).not.toHaveBeenCalled();
+    expect(store).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    [
+      "tampered documentId",
+      () => signedQuery().replace("documentId=doc-1", "documentId=doc-2"),
+    ],
+    [
+      "tampered signature",
+      () =>
+        signedQuery().replace(
+          /signature=(.)/,
+          (_, c: string) => `signature=${c === "A" ? "B" : "A"}`,
+        ),
+    ],
+    [
+      "extended expiry",
+      () => signedQuery().replace(/expires=\d+/, "expires=9999999999"),
+    ],
+    ["missing signature", () => signedQuery().replace(/&signature=[^&]+/, "")],
+    ["missing expiry", () => signedQuery().replace(/&expires=\d+/, "")],
+  ])(
+    "refuses a %s with 404 and never falls back to the gate",
+    async (_, query) => {
+      const { access, canReadAttachment } = makeAccess(ALLOWED);
+      const { res, store } = await run(query(), access);
+
+      expect(res.statusCode).toBe(404);
+      expect(canReadAttachment).not.toHaveBeenCalled();
+      expect(store).not.toHaveBeenCalled();
+    },
+  );
+
+  it("refuses an expired signed URL with 404", async () => {
+    const { access } = makeAccess(ALLOWED);
+    const expired = new AttachmentUrlSigner(
+      "s".repeat(32),
+      () => NOW_MS + 301_000,
+    );
+    const { res } = await run(signedQuery(), access, ACTOR, expired);
+
+    expect(res.statusCode).toBe(404);
+  });
+
+  it("refuses a signed URL when this server has no signer", async () => {
+    const { access } = makeAccess(ALLOWED);
+    const { res } = await run(signedQuery(), access, ACTOR, null);
+
+    expect(res.statusCode).toBe(404);
+  });
+});
+
+describe("GET /attachments/:hash re-fetch anchor", () => {
+  it("passes the granted canonical documentId to the store", async () => {
+    const { attachments, get } = makeAttachments();
+    const { access } = makeAccess(ALLOWED);
+
+    await makeDownloadHandler(attachments, access, SIGNER)(
+      makeReq("?documentId=doc-1"),
+      makeRes(),
+      undefined,
+      ACTOR,
+    );
+
+    expect(get).toHaveBeenCalledWith(
+      HASH,
+      expect.any(AbortSignal),
+      "canonical-doc",
+    );
+  });
+});