@halofy/agent-connect 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# Halofy agent lifecycle installer
+
+Status: production release candidate; activation remains gated on exact npm
+publication and deployed protocol verification.
+
+This package contains the host-neutral client pieces for installation-bound
+agent connections:
+
+- Ed25519 installation keys and signed canonical HTTP requests;
+- a bounded AES-256-GCM pending queue with a mode-`0600` key/file fallback;
+- deterministic session hashes, JSONL cursoring, exact supported UTF-8 text,
+  stable structured tool events, explicit digest-only capture-gap records,
+  prefix acknowledgement, and suffix retry;
+- signed heartbeat, open, append, recall, context-use, commit, status, and
+  close transport methods;
+- a stdio-to-signed-Streamable-HTTP MCP proof proxy; and
+- the local claim consumer used by the Claude Code adapter.
+
+The one supported Claude Code setup path is the lifecycle installer:
+
+```bash
+npx --yes @halofy/agent-connect@0.1.0 install claude-code \
+  --server https://app.halofy.ai \
+  --claim '<one-time-claim>'
+```
+
+Run the server-returned command in the operating-system terminal from the
+project where Claude Code runs, never in agent chat. The installer displays
+the capture disclosure, requires the recipient to type `CONNECT`, generates
+the Ed25519 private key locally, consumes the one-use claim in a JSON body,
+copies the reviewed runtime out of the transient npx cache, and installs the
+signed MCP proxy and lifecycle hooks together. It replaces an existing Halofy
+bearer MCP entry and legacy Halofy hooks in place while preserving unrelated
+Claude settings. It never runs both Halofy capture paths for one host session.
+
+The current storage backend is the explicitly reported mode-`0600` file
+fallback (or the closest Windows ACL), not hardware-backed storage. No bearer
+or claim is stored in the runtime queue or Claude configuration.
+
+The request canonicalization in `src/crypto.mjs` follows AL4's strict raw path
+and query rules. Publication is fail-closed until the package tarball, current
+Claude fixtures, cross-implementation signature fixtures, and deployed server
+protocol have all passed for the exact version.
+
+The Claude adapter advertises archive protocol v1 explicitly. Its current
+body capabilities are user/assistant text, structured tool inputs/results and
+failures, and host artifact references. Inline images and artifact bodies are
+represented by digest-only placeholders and make coverage partial;
+`images`/`artifactBodies` remain false until the signed chunk-upload protocol,
+encrypted retry queue, and real-host fixtures are verified. The adapter never
+opens an arbitrary transcript-referenced local file to fill that gap.
+
+Run focused checks from this directory:
+
+```bash
+npm test
+npm run check
+```
+
+Content-free local queue/version evidence is available without decrypting or
+printing any pending event body:
+
+```bash
+node kernel/integrations/agent-runtime/bin/halofy-agent.mjs diagnostics
+```

package/bin/halofy-agent.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { ConnectionStore, defaultRuntimeDirectory } from "../src/storage.mjs";
+import { loadActiveConnection } from "../src/active.mjs";
+import { runStdioMcpProxy } from "../src/mcp-proxy.mjs";
+import { BoundedEncryptedQueue } from "../src/queue.mjs";
+import { runClaudeLifecycleHook } from "../src/claude-hook.mjs";
+import { join } from "node:path";
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? null : process.argv[index + 1];
+}
+
+const command = process.argv[2];
+const hookEvent = command === "hook" ? process.argv[3] : null;
+const hookEvents = new Set([
+  "SessionStart", "UserPromptSubmit", "Stop", "PreCompact", "SessionEnd",
+  "SubagentStart", "SubagentStop", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
+]);
+if (!["mcp", "diagnostics", "hook"].includes(command) ||
+    (command === "hook" && !hookEvents.has(hookEvent))) {
+  process.stderr.write("Usage: halofy-agent <mcp|diagnostics|hook EVENT> [--connection <installation-id>]\n");
+  process.exitCode = 2;
+} else {
+  try {
+    const installationId = option("--connection");
+    const connection = installationId
+      ? await new ConnectionStore(defaultRuntimeDirectory()).load(installationId)
+      : await loadActiveConnection("claude-code");
+    if (!connection) throw new Error("no active installation-bound connection");
+    if (command === "mcp") {
+      await runStdioMcpProxy(connection);
+    } else if (command === "hook") {
+      await runClaudeLifecycleHook(connection, hookEvent);
+    } else {
+      const queue = new BoundedEncryptedQueue(join(defaultRuntimeDirectory(), connection.installationId));
+      process.stdout.write(`${JSON.stringify({
+        installationId: connection.installationId,
+        clientKind: connection.clientKind,
+        protocolVersion: connection.protocolVersion,
+        pluginVersion: connection.pluginVersion,
+        proofStorage: connection.proofStorage,
+        queue: await queue.diagnostics(),
+      }, null, 2)}\n`);
+    }
+  } catch (error) {
+    process.stderr.write(`${error?.message || "Halofy MCP proxy unavailable"}\n`);
+    process.exitCode = 1;
+  }
+}

package/bin/install.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runInstaller } from "../src/installer-cli.mjs";
+
+try {
+  const result = await runInstaller(process.argv.slice(2));
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${error?.message || "installation failed"}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@halofy/agent-connect",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Signed Halofy lifecycle installer and runtime for supported agents",
+  "bin": {
+    "agent-connect": "bin/install.mjs",
+    "halofy-agent": "bin/halofy-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/halofyai/halomem.git",
+    "directory": "kernel/integrations/agent-runtime"
+  },
+  "homepage": "https://github.com/halofyai/halomem/tree/master/kernel/integrations/agent-runtime",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check src/*.mjs && node --check bin/*.mjs",
+    "prepack": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/active.mjs

@@ -0,0 +1,15 @@
+import { join } from "node:path";
+import { ConnectionStore, defaultRuntimeDirectory, readJson } from "./storage.mjs";
+
+export async function loadActiveConnection(clientKind = "claude-code", root = defaultRuntimeDirectory()) {
+  const explicit = process.env.HALOFY_INSTALLATION_ID;
+  const marker = explicit ? { installationId: explicit } : await readJson(join(root, `active-${clientKind}.json`));
+  if (!marker?.installationId || marker.protocolVersion === "legacy") return null;
+  return new ConnectionStore(root).load(marker.installationId);
+}
+
+export async function hasLifecycleMarker(clientKind = "claude-code", root = defaultRuntimeDirectory()) {
+  if (process.env.HALOFY_INSTALLATION_ID) return true;
+  const marker = await readJson(join(root, `active-${clientKind}.json`));
+  return Boolean(marker?.installationId && marker.protocolVersion !== "legacy");
+}

package/src/claude-config.mjs

@@ -0,0 +1,139 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { readJson, writePrivateFile } from "./storage.mjs";
+
+const CLAUDE_HOOKS = Object.freeze({
+  SessionStart: { matcher: "startup|resume|clear|compact", timeout: 15 },
+  UserPromptSubmit: { timeout: 15 },
+  Stop: { timeout: 20 },
+  PreCompact: { timeout: 20 },
+  SessionEnd: { timeout: 20 },
+  SubagentStart: { timeout: 8 },
+  SubagentStop: { timeout: 12 },
+  PostToolUse: { timeout: 8 },
+  PostToolUseFailure: { timeout: 8 },
+  PostToolBatch: { timeout: 8 },
+});
+
+function commandArg(value) {
+  const text = String(value);
+  if (/[^A-Za-z0-9_./:@+-]/.test(text)) {
+    if (/[\0\r\n"`$\\]/.test(text)) throw new Error("local integration path cannot be encoded safely for a Claude command hook");
+    return `"${text}"`;
+  }
+  return text;
+}
+
+function managedHookCommand(nodePath, runtimePath, eventName, installationId) {
+  return [nodePath, runtimePath, "hook", eventName, "--connection", installationId]
+    .map(commandArg).join(" ");
+}
+
+function managedHookRegistration(nodePath, runtimePath, eventName, installationId, definition) {
+  return {
+    ...(definition.matcher ? { matcher: definition.matcher } : {}),
+    hooks: [{
+      type: "command",
+      command: managedHookCommand(nodePath, runtimePath, eventName, installationId),
+      timeout: definition.timeout,
+    }],
+  };
+}
+
+function isManagedHalofyHook(hook) {
+  const command = String(hook?.command || "");
+  return /(?:halofy-agent\.mjs\s+hook\s+|claude-code\/scripts\/(?:session-start|session-end|lifecycle-hook|mcp-router)\.mjs)/.test(command);
+}
+
+function normalizedMcpUrl(entry) {
+  const value = entry?.url || entry?.httpUrl || entry?.serverUrl;
+  if (typeof value !== "string") return null;
+  try { return new URL(value); } catch { return null; }
+}
+
+function isHalofyMcpEntry(name, entry, serverUrl) {
+  if (!entry || typeof entry !== "object") return false;
+  const command = String(entry.command || "");
+  if (/halofy-(?:agent|mcp)|agent-runtime|agent-connect/i.test(command)) return true;
+  const candidate = normalizedMcpUrl(entry);
+  if (!candidate) return false;
+  const server = new URL(serverUrl);
+  return ["halofy", "halomem"].includes(String(name).toLowerCase()) &&
+    candidate.origin === server.origin && candidate.pathname.replace(/\/+$/, "") === "/mcp";
+}
+
+function removeHalofyEntries(map, serverUrl) {
+  if (!map || typeof map !== "object" || Array.isArray(map)) return 0;
+  let removed = 0;
+  for (const [name, entry] of Object.entries(map)) {
+    if (isHalofyMcpEntry(name, entry, serverUrl)) {
+      delete map[name];
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+/**
+ * Installs one lifecycle-bound Claude connection. Existing Halofy bearer MCP
+ * entries and legacy Halofy hooks are replaced in place; unrelated Claude
+ * settings and MCP servers are preserved.
+ */
+export async function configureClaudeProject({
+  projectRoot,
+  installationId,
+  serverUrl,
+  nodePath = process.execPath,
+  runtimePath,
+  claudeConfigPath = join(homedir(), ".claude.json"),
+}) {
+  if (!/^[A-Za-z0-9_-]{1,160}$/.test(String(installationId))) throw new Error("invalid installation id");
+  if (!runtimePath) throw new Error("installed runtime path is required");
+  const server = new URL(serverUrl);
+  const root = resolve(projectRoot);
+  const mcpPath = join(root, ".mcp.json");
+  const settingsPath = join(root, ".claude", "settings.json");
+  const mcp = await readJson(mcpPath, {});
+  mcp.mcpServers = mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {};
+  const replacedProjectMcpEntries = removeHalofyEntries(mcp.mcpServers, server.toString());
+  mcp.mcpServers.halofy = {
+    type: "stdio",
+    command: resolve(nodePath),
+    args: [resolve(runtimePath), "mcp", "--connection", installationId],
+  };
+
+  const settings = await readJson(settingsPath, {});
+  settings.hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  for (const [eventName, definition] of Object.entries(CLAUDE_HOOKS)) {
+    const current = Array.isArray(settings.hooks[eventName]) ? settings.hooks[eventName] : [];
+    const unrelated = current.filter((registration) =>
+      !Array.isArray(registration?.hooks) || !registration.hooks.some(isManagedHalofyHook));
+    settings.hooks[eventName] = [
+      ...unrelated,
+      managedHookRegistration(nodePath, runtimePath, eventName, installationId, definition),
+    ];
+  }
+
+  let replacedClaudeMcpEntries = 0;
+  const claude = await readJson(claudeConfigPath, null);
+  if (claude && typeof claude === "object") {
+    replacedClaudeMcpEntries += removeHalofyEntries(claude.mcpServers, server.toString());
+    const projects = claude.projects && typeof claude.projects === "object" ? claude.projects : {};
+    for (const [path, project] of Object.entries(projects)) {
+      if (resolve(path) !== root || !project || typeof project !== "object") continue;
+      replacedClaudeMcpEntries += removeHalofyEntries(project.mcpServers, server.toString());
+    }
+    if (replacedClaudeMcpEntries > 0) {
+      await writePrivateFile(claudeConfigPath, `${JSON.stringify(claude, null, 2)}\n`);
+    }
+  }
+
+  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  return {
+    mcpPath,
+    settingsPath,
+    hookEvents: Object.keys(CLAUDE_HOOKS),
+    replacedLegacyMcpEntries: replacedProjectMcpEntries + replacedClaudeMcpEntries,
+  };
+}

package/src/claude-hook.mjs

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { LifecycleRuntime } from "./runtime.mjs";
+import { normalizeClaudeHookEvent } from "./session.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+
+function id(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
+export function readHookInput(stream = process.stdin) {
+  return new Promise((resolve) => {
+    let raw = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => { raw += chunk; });
+    stream.on("end", () => {
+      try { resolve(JSON.parse(raw)); } catch { resolve({}); }
+    });
+    stream.on("error", () => resolve({}));
+  });
+}
+
+function hostSession(input) {
+  return String(input.session_id || "");
+}
+
+function childSession(input) {
+  const parent = hostSession(input);
+  const child = input.agent_id || input.agent_type || input.subagent_id;
+  return child ? `${parent}:subagent:${child}` : parent;
+}
+
+function recallText(result, eventName) {
+  const blocks = Array.isArray(result?.blocks) ? result.blocks : Array.isArray(result) ? result : [];
+  const rankedBlocks = blocks
+    .filter((block) => block && typeof block.recallRef === "string" &&
+      typeof block.content === "string" && block.content.trim())
+    .slice(0, 12)
+    .map((block, rank) => ({
+      rank: rank + 1,
+      recallRef: block.recallRef.slice(0, 256),
+      content: block.content.trim(),
+    }));
+  if (rankedBlocks.length === 0) return null;
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>`,
+    },
+  });
+}
+
+async function catchUp(runtime, input, session = hostSession(input)) {
+  const transcriptPath = input.agent_transcript_path || input.transcript_path;
+  if (!transcriptPath || !session) return;
+  await runtime.captureClaudeTranscript(session, String(transcriptPath));
+}
+
+async function within(milliseconds, action) {
+  return Promise.race([
+    action(),
+    new Promise((resolve) => setTimeout(() => resolve(null), milliseconds)),
+  ]);
+}
+
+/** Runs one reviewed Claude hook. Brownouts never block the host session. */
+export async function runClaudeLifecycleHook(connection, eventName, {
+  input,
+  root = defaultRuntimeDirectory(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  try {
+    const hookInput = input ?? await readHookInput();
+    const session = hostSession(hookInput);
+    if (!session) return { handled: true };
+    const runtime = new LifecycleRuntime(connection, { root });
+
+    if (eventName === "SessionStart") {
+      await runtime.replay();
+      await runtime.heartbeat(connection.capabilities || {});
+      const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
+      const recalled = await runtime.recall(
+        session,
+        `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`,
+      );
+      const output = recallText(recalled, "SessionStart");
+      if (output) stdout.write(output);
+    } else if (eventName === "UserPromptSubmit") {
+      const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
+      if (prompt.trim()) {
+        const recalled = await runtime.recall(session, prompt);
+        const output = recallText(recalled, "UserPromptSubmit");
+        if (output) stdout.write(output);
+      }
+    } else if (eventName === "Stop") {
+      if (!hookInput.stop_hook_active) {
+        await catchUp(runtime, hookInput);
+        await runtime.commitIfThreshold(session);
+      }
+    } else if (eventName === "PreCompact") {
+      await catchUp(runtime, hookInput);
+      const cursor = await runtime.cursors.get(runtime.sessionHash(session));
+      await runtime.enqueueEvent(session, normalizeClaudeHookEvent("compaction", hookInput, {
+        sessionHash: runtime.sessionHash(session),
+        sequence: cursor.sequence + 1,
+      }));
+      await runtime.commit(session, "pre_compaction");
+    } else if (eventName === "SessionEnd") {
+      await within(15_000, async () => {
+        await catchUp(runtime, hookInput);
+        await runtime.close(session);
+      });
+    } else if (eventName === "SubagentStart") {
+      await runtime.resolveSession(childSession(hookInput), session);
+    } else if (eventName === "SubagentStop") {
+      const child = childSession(hookInput);
+      await within(10_000, async () => {
+        await catchUp(runtime, hookInput, child);
+        await runtime.close(child, "session_end");
+      });
+    } else if (["PostToolUse", "PostToolUseFailure"].includes(eventName)) {
+      await catchUp(runtime, hookInput);
+      const sessionHash = runtime.sessionHash(session);
+      const cursor = await runtime.cursors.get(sessionHash);
+      const common = { ...hookInput, event_id: hookInput.event_id || id(`${hookInput.tool_use_id}:${eventName}`) };
+      await runtime.enqueueEvents(session, [
+        normalizeClaudeHookEvent("tool_call", common, { sessionHash, sequence: cursor.sequence + 1 }),
+        normalizeClaudeHookEvent("tool_result", {
+          ...common,
+          ...(eventName === "PostToolUseFailure" ? { tool_error: hookInput.error || true } : {}),
+        }, { sessionHash, sequence: cursor.sequence + 2 }),
+      ]);
+    } else if (eventName === "PostToolBatch") {
+      const records = Array.isArray(hookInput.tool_calls) ? hookInput.tool_calls : [];
+      for (const record of records.slice(0, 100)) {
+        const sessionHash = runtime.sessionHash(session);
+        const cursor = await runtime.cursors.get(sessionHash);
+        await runtime.enqueueEvents(session, [
+          normalizeClaudeHookEvent("tool_call", record, { sessionHash, sequence: cursor.sequence + 1 }),
+          normalizeClaudeHookEvent("tool_result", record, { sessionHash, sequence: cursor.sequence + 2 }),
+        ]);
+      }
+    } else {
+      throw new Error("unsupported Claude lifecycle hook");
+    }
+    return { handled: true };
+  } catch (error) {
+    const code = error && typeof error === "object" && typeof error.code === "string"
+      ? error.code : "runtime_unavailable";
+    stderr.write(`[halofy] lifecycle hook degraded: ${code}\n`);
+    return { handled: true, degraded: true };
+  }
+}

package/src/crypto.mjs

@@ -0,0 +1,143 @@
+import {
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign as signBytes,
+} from "node:crypto";
+
+const SIGNING_PREFIX = "halofy-installation-v1";
+
+function base64url(value) {
+  return Buffer.from(value).toString("base64url");
+}
+
+export function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function generateInstallationKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const publicJwk = publicKey.export({ format: "jwk" });
+  const privateJwk = privateKey.export({ format: "jwk" });
+  const thumbprintInput = JSON.stringify({ crv: publicJwk.crv, kty: publicJwk.kty, x: publicJwk.x });
+  return {
+    publicJwk,
+    privateJwk,
+    thumbprint: base64url(createHash("sha256").update(thumbprintInput).digest()),
+  };
+}
+
+function strictDecode(value, label) {
+  const bytes = [];
+  for (let index = 0; index < value.length;) {
+    if (value[index] === "%") {
+      const encoded = value.slice(index + 1, index + 3);
+      if (!/^[0-9A-Fa-f]{2}$/.test(encoded)) throw new Error(`${label} has malformed percent encoding`);
+      bytes.push(Number.parseInt(encoded, 16));
+      index += 3;
+      continue;
+    }
+    const codePoint = value.codePointAt(index);
+    const character = String.fromCodePoint(codePoint);
+    bytes.push(...Buffer.from(character, "utf8"));
+    index += character.length;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes));
+  } catch {
+    throw new Error(`${label} is not valid UTF-8`);
+  }
+}
+
+function percentEncode(value) {
+  let output = "";
+  for (const byte of Buffer.from(value, "utf8")) {
+    const unreserved =
+      (byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a) ||
+      (byte >= 0x30 && byte <= 0x39) || [0x2d, 0x2e, 0x5f, 0x7e].includes(byte);
+    output += unreserved ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  }
+  return output;
+}
+
+/**
+ * Provisional v1 canonical query encoding. The lifecycle contract must freeze
+ * this byte representation before a public runtime is published.
+ */
+export function canonicalPathAndQuery(input) {
+  if (typeof input !== "string" || !input.startsWith("/") || input.includes("#")) {
+    throw new Error("request target must be origin-form without a fragment");
+  }
+  const queryIndex = input.indexOf("?");
+  const rawPath = queryIndex === -1 ? input : input.slice(0, queryIndex);
+  const rawQuery = queryIndex === -1 ? null : input.slice(queryIndex + 1);
+  if (rawPath !== "/" && rawPath.endsWith("/")) throw new Error("path has a trailing empty segment");
+  const rawSegments = rawPath.split("/");
+  if (rawSegments[0] !== "" || (rawPath !== "/" && rawSegments.slice(1).some((segment) => segment === ""))) {
+    throw new Error("path has an empty segment");
+  }
+  const path = rawPath === "/" ? "/" : `/${rawSegments.slice(1).map((segment) => {
+    const decoded = strictDecode(segment, "path segment");
+    if (decoded === "." || decoded === ".." || /[\0\\/]/.test(decoded)) {
+      throw new Error("path segment changes route structure");
+    }
+    return percentEncode(decoded);
+  }).join("/")}`;
+  if (rawQuery === null || rawQuery === "") return path;
+  const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+  const pairs = rawQuery.split("&").map((pair) => {
+    const equals = pair.indexOf("=");
+    const rawName = equals === -1 ? pair : pair.slice(0, equals);
+    const rawValue = equals === -1 ? "" : pair.slice(equals + 1);
+    return [percentEncode(strictDecode(rawName, "query name")), percentEncode(strictDecode(rawValue, "query value"))];
+  }).sort(([leftKey, leftValue], [rightKey, rightValue]) =>
+    compare(leftKey, rightKey) || compare(leftValue, rightValue),
+  );
+  return `${path}?${pairs.map(([key, value]) => `${key}=${value}`).join("&")}`;
+}
+
+export function canonicalRequest({ method, path, bodyBytes, timestamp, nonce }) {
+  const body = Buffer.isBuffer(bodyBytes) ? bodyBytes : Buffer.from(bodyBytes ?? "");
+  return [
+    SIGNING_PREFIX,
+    String(method).toUpperCase(),
+    canonicalPathAndQuery(path),
+    sha256(body),
+    timestamp,
+    nonce,
+  ].join("\n");
+}
+
+export function signInstallationRequest({
+  installationId,
+  privateJwk,
+  method,
+  path,
+  bodyBytes = Buffer.alloc(0),
+  timestamp = new Date().toISOString(),
+  nonce = randomBytes(16).toString("base64url"),
+}) {
+  const canonicalMethod = String(method).toUpperCase();
+  if (!/^[A-Z]+$/.test(canonicalMethod)) throw new Error("request method is not canonical ASCII");
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(timestamp) ||
+      new Date(timestamp).toISOString() !== timestamp) {
+    throw new Error("request timestamp is not canonical UTC");
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(nonce) || Buffer.from(nonce, "base64url").length < 16 ||
+      Buffer.from(nonce, "base64url").length > 64) {
+    throw new Error("request nonce must encode 16-64 bytes without padding");
+  }
+  const canonical = canonicalRequest({ method, path, bodyBytes, timestamp, nonce });
+  const signature = signBytes(null, Buffer.from(canonical), createPrivateKey({ key: privateJwk, format: "jwk" }));
+  return {
+    canonical,
+    headers: {
+      Authorization: `Halofy-Installation ${installationId}`,
+      "X-Halofy-Timestamp": timestamp,
+      "X-Halofy-Nonce": nonce,
+      "X-Halofy-Body-SHA256": sha256(bodyBytes),
+      "X-Halofy-Signature": signature.toString("base64url"),
+    },
+  };
+}