@johnhenry/wsh 0.18.0 → 0.19.0

package/src/host-key.mjs

@@ -0,0 +1,97 @@
+/**
+ * Host-key identity for wsh (TOFU / pinning). Browser-safe, shared by the stock
+ * client and `@johnhenry/wsh/server`.
+ *
+ * ## Wire shape (an extension carried in existing frames)
+ *
+ * The wsh-v1 spec has `ServerHello.host_fingerprint` (SHA-256 of the host's
+ * Ed25519 key) but no field for the key itself and no proof the server holds
+ * it -- a bare fingerprint can be replayed by anyone. Rather than change the
+ * spec, the proof rides in the negotiable `features` string lists:
+ *
+ *  - client -> server, in `Hello.features`:  `host-key-nonce:<hex>`   (fresh, 16 bytes)
+ *  - server -> client, in `ServerHello.features`:
+ *      `host-key:<hex>`      the raw 32-byte Ed25519 host public key
+ *      `host-key-sig:<hex>`  Ed25519 signature over the proof message below
+ *    and `ServerHello.host_fingerprint` = fingerprint of that key.
+ *
+ * Proof message = `"wsh-host-key-proof-v1" 0x00 session_id 0x00 client_nonce 0x00 username`.
+ * The client's fresh nonce makes the proof unreplayable; the session id binds
+ * it to this ServerHello. It is checked BEFORE any credential is sent, so a
+ * password never goes to a host that fails its pin. Peers that don't know the
+ * strings ignore them, so nothing breaks against other implementations.
+ *
+ * Limit: the proof authenticates the ServerHello, not the byte stream -- on a
+ * plain `ws://` link an active attacker can relay a genuine ServerHello and
+ * then read/alter the rest. Pinning protects you from talking to the WRONG
+ * host; confidentiality still needs `wss://`/WebTransport (or a trusted LAN).
+ */
+
+export const HOST_KEY_NONCE_PREFIX = 'host-key-nonce:';
+export const HOST_KEY_PREFIX = 'host-key:';
+export const HOST_KEY_SIG_PREFIX = 'host-key-sig:';
+const PROOF_TAG = 'wsh-host-key-proof-v1';
+
+const enc = new TextEncoder();
+
+export function toHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function fromHex(hex) {
+  if (typeof hex !== 'string' || hex.length % 2 || /[^0-9a-f]/i.test(hex)) throw new Error('invalid hex');
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/** A refused host key. `code` is one of the `HOST_KEY_*` values below. */
+export class HostKeyError extends Error {
+  /**
+   * @param {'HOST_KEY_MISSING'|'HOST_KEY_INVALID'|'HOST_KEY_MISMATCH'|'HOST_KEY_UNKNOWN'|'HOST_KEY_REJECTED'} code
+   * @param {string} message
+   * @param {object} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'HostKeyError';
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+/** Fresh client nonce, hex. */
+export function newHostKeyNonce() {
+  return toHex(crypto.getRandomValues(new Uint8Array(16)));
+}
+
+/** Bytes the host signs / the client verifies. */
+export function hostKeyProofMessage({ sessionId, clientNonce, username }) {
+  return enc.encode(`${PROOF_TAG}\0${sessionId}\0`
+    + `${typeof clientNonce === 'string' ? clientNonce : toHex(clientNonce)}\0${username}`);
+}
+
+/** Pull the client nonce out of `Hello.features` (server side). Null when absent or malformed. */
+export function findClientNonce(features) {
+  for (const f of Array.isArray(features) ? features : []) {
+    if (typeof f === 'string' && f.startsWith(HOST_KEY_NONCE_PREFIX)) {
+      const hex = f.slice(HOST_KEY_NONCE_PREFIX.length);
+      if (/^[0-9a-f]{32,128}$/i.test(hex)) return hex.toLowerCase();
+    }
+  }
+  return null;
+}
+
+/** Pull the advertised key + signature out of `ServerHello.features` (client side). */
+export function findHostKeyAdvert(features) {
+  let key = null;
+  let sig = null;
+  for (const f of Array.isArray(features) ? features : []) {
+    if (typeof f !== 'string') continue;
+    try {
+      if (f.startsWith(HOST_KEY_SIG_PREFIX)) sig = fromHex(f.slice(HOST_KEY_SIG_PREFIX.length));
+      else if (f.startsWith(HOST_KEY_PREFIX)) key = fromHex(f.slice(HOST_KEY_PREFIX.length));
+    } catch { /* malformed -> treated as absent, then refused as INVALID by the caller */ }
+  }
+  return key || sig ? { key, sig } : null;
+}

package/src/index.d.ts

@@ -1549,8 +1549,48 @@ export class WshVirtualSessionBackend {
 // client.mjs -- WshClient
 // ============================================================================
 
+/** The host identity a server proved it holds (see `WshClient.hostKey`). */
+export interface WshHostKey {
+  /** Hex SHA-256 of the raw key (same as `fingerprint()` / `ServerHello.host_fingerprint`). */
+  fingerprint: string;
+  /** Raw 32-byte Ed25519 host public key. */
+  publicKey: Uint8Array;
+  /** `ssh-ed25519 AAAA...` form, for display or `expectHostKey`. */
+  openssh: string;
+  /** `pinned` matched `expectHostKey`; `known`/`unknown` per `knownHosts`; `unpinned` = surfaced, nothing checked. */
+  status: 'pinned' | 'known' | 'unknown' | 'unpinned';
+}
+
+/** Why a host key was refused. */
+export type WshHostKeyErrorCode =
+  | 'HOST_KEY_MISSING' | 'HOST_KEY_INVALID' | 'HOST_KEY_MISMATCH' | 'HOST_KEY_UNKNOWN' | 'HOST_KEY_REJECTED';
+
+/** Thrown by `connect()` when the host key fails the caller's policy. No credential has been sent. */
+export class HostKeyError extends Error {
+  constructor(code: WshHostKeyErrorCode, message: string, details?: { expected?: string; actual?: string });
+  readonly code: WshHostKeyErrorCode;
+  /** MISMATCH: the pinned / expected fingerprint. */
+  readonly expected?: string;
+  /** MISMATCH / UNKNOWN: the fingerprint the host presented. */
+  readonly actual?: string;
+}
+
+/** Host-key policy shared by `connect()`, `exec()` and `connectReverse()`. */
+export interface WshHostKeyOptions {
+  /** Pin: hex fingerprint (optionally `sha256:`-prefixed), raw 32-byte key, or `ssh-ed25519 AAAA...` line. Refuses on mismatch or when the host presents no key. */
+  expectHostKey?: string | Uint8Array;
+  /** TOFU store. A changed key is always refused; an unseen host is refused unless `trustOnFirstUse` / `onHostKey` accepts it. */
+  knownHosts?: WshKnownHosts;
+  /** Pin an unseen host's key into `knownHosts`. */
+  trustOnFirstUse?: boolean;
+  /** Key `knownHosts` records this host under (default: the URL's `host:port`). */
+  hostLabel?: string;
+  /** Sees the verified key before any credential is sent; return `false` (or throw) to refuse. */
+  onHostKey?: (hostKey: WshHostKey) => boolean | void | Promise<boolean | void>;
+}
+
 /** Options for WshClient.connect(). */
-export interface WshConnectOptions {
+export interface WshConnectOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
   password?: string;
@@ -1609,6 +1649,11 @@ export interface WshConnectReverseOptions {
   password?: string;
   /** Forwarded to the underlying `connect()` -- see `WshConnectOptions`. */
   webTransport?: WshWebTransportOptions;
+  expectHostKey?: WshHostKeyOptions['expectHostKey'];
+  knownHosts?: WshKnownHosts;
+  trustOnFirstUse?: boolean;
+  hostLabel?: string;
+  onHostKey?: WshHostKeyOptions['onHostKey'];
   expose?: {
     shell?: boolean;
     exec?: boolean;
@@ -1624,7 +1669,7 @@ export interface WshConnectReverseOptions {
 }
 
 /** Options for WshClient.exec(). */
-export interface WshExecOptions {
+export interface WshExecOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
   password?: string;
@@ -1776,6 +1821,15 @@ export class WshClient {
    */
   hasFeature(name: string): boolean;
 
+  /**
+   * The host's Ed25519 identity once it has proven it holds the key for this
+   * connection; `null` if the server advertised none (e.g. the Rust server).
+   */
+  readonly hostKey: WshHostKey | null;
+
+  /** Default `onHostKey` for `connect()` (a per-call option wins). */
+  onHostKey: ((hostKey: WshHostKey) => boolean | void | Promise<boolean | void>) | null;
+
   /**
    * Connect to a wsh server, authenticate, and return the session ID.
    */
@@ -1834,6 +1888,20 @@ export class WshClient {
    */
   fileList(path: string, timeout?: number): Promise<WshFileOperationResult>;
 
+  /**
+   * Write bytes to a remote file. `offset` omitted replaces the file; given,
+   * writes in place at that offset. Needs the host feature `file-write`
+   * (`@johnhenry/wsh/server` with `fs` has it); throws against a host without
+   * it. Failure is reported as `success: false` in the result.
+   */
+  fileWrite(path: string, data: Uint8Array | string, offset?: number, timeout?: number): Promise<WshFileOperationResult>;
+
+  /**
+   * Rename/move a remote file or directory. Needs the host feature
+   * `file-rename`; throws against a host without it. Refuses to overwrite.
+   */
+  fileRename(oldPath: string, newPath: string, timeout?: number): Promise<WshFileOperationResult>;
+
   /**
    * Remove a remote file or directory (`FileOp` op `"remove"`). Refused
    * today by every `wsh-server` release ("not yet implemented" -- see

package/src/index.mjs

@@ -80,6 +80,7 @@ export { WshKeyStore } from './keystore.mjs';
 
 // Host identity (TOFU) -- wsh #59
 export { WshKnownHosts } from './known-hosts.mjs';
+export { HostKeyError } from './host-key.mjs';
 
 // File transfer
 export { WshFileTransfer } from './file-transfer.mjs';

package/src/server/auth.mjs

@@ -73,3 +73,60 @@ export async function buildAuthorizer(auth) {
     return true;
   };
 }
+
+/**
+ * Whether `auth` allows public-key login at all (an allowlist and/or an
+ * `authorize` callback, or the function shorthand) and/or password login.
+ *
+ * @param {any} auth
+ * @returns {{ pubkey: boolean, password: ((user: string, pass: string) => boolean | Promise<boolean>) | null }}
+ */
+export function authMethods(auth) {
+  if (typeof auth === 'function') return { pubkey: true, password: null };
+  if (!auth) return { pubkey: false, password: null };
+  if (auth.password !== undefined && typeof auth.password !== 'function') {
+    throw new TypeError('createWshServer: auth.password must be a function (user, pass) => boolean | Promise<boolean>');
+  }
+  return {
+    pubkey: auth.authorizedKeys !== undefined || typeof auth.authorize === 'function',
+    password: auth.password ?? null,
+  };
+}
+
+/**
+ * Failure throttle for password logins, keyed (by default) on the peer's
+ * address. After `maxFailures` failures inside `windowMs` the key is locked
+ * for `lockoutMs`, during which the password callback is not even called.
+ * A success clears the key. In-memory and per-process, by design.
+ */
+export class FailureLimiter {
+  #entries = new Map();
+  #now;
+  constructor({ maxFailures = 5, windowMs = 60_000, lockoutMs = 60_000, now = Date.now } = {}) {
+    this.maxFailures = maxFailures;
+    this.windowMs = windowMs;
+    this.lockoutMs = lockoutMs;
+    this.#now = now;
+  }
+
+  /** @returns {number} ms the key is still locked out (0 = free to try) */
+  lockedFor(key) {
+    const e = this.#entries.get(key);
+    if (!e) return 0;
+    const t = this.#now();
+    if (e.lockedUntil > t) return e.lockedUntil - t;
+    if (t - e.first > this.windowMs) this.#entries.delete(key);
+    return 0;
+  }
+
+  fail(key) {
+    const t = this.#now();
+    let e = this.#entries.get(key);
+    if (!e || t - e.first > this.windowMs) { e = { count: 0, first: t, lockedUntil: 0 }; this.#entries.set(key, e); }
+    e.count++;
+    if (e.count >= this.maxFailures) e.lockedUntil = t + this.lockoutMs;
+    if (this.#entries.size > 10_000) this.#entries.delete(this.#entries.keys().next().value);
+  }
+
+  succeed(key) { this.#entries.delete(key); }
+}

package/src/server/connection.mjs

@@ -24,8 +24,12 @@ import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
 } from '../auth.mjs';
 import { FILE_CHUNK_BYTES } from './fs.mjs';
+import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
+const MAX_PENDING_WRITES = 8;
+const MAX_RENAME_PATH_BYTES = 4096;
+const WRITE_IDLE_MS = 30_000;
 
 const MAX_CHANNELS = 64;
 const USERNAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
@@ -41,13 +45,16 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {object} cfg.execOptions
  * @param {object | null} cfg.pty - normalized (see pty.mjs)
  * @param {object | null} cfg.files - from createFileAccess
+ * @param {{ pubkey: boolean, password: Function | null }} cfg.methods - which auth methods are on
+ * @param {object | null} cfg.hostKey - from loadHostKey
+ * @param {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
  * @param {number} cfg.bindTimeoutMs - how long exec output waits for the data stream
  * @param {(line: string) => void} cfg.log
  */
 export function createConnectionFactory(cfg) {
   let counter = 0;
 
-  return function attach({ send: sendBytes }) {
+  return function attach({ send: sendBytes, remote = {} }) {
     const cid = ++counter;
     const log = (m) => cfg.log(`[conn ${cid}] ${m}`);
     const state = {
@@ -56,6 +63,8 @@ export function createConnectionFactory(cfg) {
     };
     /** @type {Map<number, any>} */
     const channels = new Map();
+    /** FileOp `write`/`rename`s awaiting their FileChunk frames, by client-chosen channel id. */
+    const fileWrites = new Map();
     /** Channel ids awaiting their client-opened data stream, in OpenOk order. */
     const pendingStreams = [];
     const decoder = new FrameDecoder();
@@ -78,6 +87,8 @@ export function createConnectionFactory(cfg) {
       state.closed = true;
       for (const ch of channels.values()) ch.kill?.();
       channels.clear();
+      for (const w of fileWrites.values()) clearTimeout(w.timer);
+      fileWrites.clear();
       try { qmux.destroy(new Error(why)); } catch { /* already gone */ }
       log(`closed (${why})`);
     }
@@ -118,7 +129,7 @@ export function createConnectionFactory(cfg) {
         case MSG.SIGNAL: channels.get(m.channel_id)?.signal?.(String(m.signal ?? '')); return;
         case MSG.CLOSE: { const ch = channels.get(m.channel_id); if (ch) { ch.kill?.(); } return; }
         case MSG.FILE_OP: return handleFileOp(m);
-        case MSG.FILE_CHUNK: return channels.get(m.channel_id)?.chunk?.(m);
+        case MSG.FILE_CHUNK: return (fileWrites.has(m.channel_id) ? handleWriteChunk(m) : channels.get(m.channel_id)?.chunk?.(m));
         default: log(`ignored message type 0x${m.type.toString(16)}`);
       }
     }
@@ -133,15 +144,37 @@ export function createConnectionFactory(cfg) {
       if (m.type === MSG.HELLO) {
         const user = String(m.username ?? '');
         if (!USERNAME_RE.test(user)) return refuse(`bad username ${JSON.stringify(user)}`);
-        if (m.auth_method && m.auth_method !== 'pubkey') return refuse('this host only accepts Ed25519 pubkey auth');
+        const method = m.auth_method || 'pubkey';
+        if (method === 'password') {
+          if (!cfg.methods.password) return refuse('password auth is not enabled on this host');
+        } else if (method === 'pubkey') {
+          if (!cfg.methods.pubkey) return refuse('pubkey auth is not enabled on this host');
+        } else {
+          return refuse(`unsupported auth method ${JSON.stringify(method)}`);
+        }
         state.username = user;
-        state.nonce = generateNonce();
+        state.method = method;
         const features = [STREAM_ANNOUNCE];
-        if (cfg.files) features.push('file-transfer');
-        await send(serverHello({ sessionId: state.sessionId, features }));
-        await send(challenge({ nonce: state.nonce, sessionId: state.sessionId }));
+        if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
+        let hostFingerprint;
+        if (cfg.hostKey) {
+          hostFingerprint = cfg.hostKey.fingerprint;
+          const clientNonce = findClientNonce(m.features);
+          if (clientNonce) {
+            const sig = await cfg.hostKey.sign(hostKeyProofMessage({ sessionId: state.sessionId, clientNonce, username: user }));
+            features.push(HOST_KEY_PREFIX + toHex(cfg.hostKey.publicKey), HOST_KEY_SIG_PREFIX + toHex(sig));
+          }
+        }
+        await send(serverHello({ sessionId: state.sessionId, features, hostFingerprint }));
+        if (method === 'pubkey') {
+          state.nonce = generateNonce();
+          await send(challenge({ nonce: state.nonce, sessionId: state.sessionId }));
+        } else {
+          state.awaitingPassword = true;
+        }
         return;
       }
+      if (m.type === MSG.AUTH && state.awaitingPassword) return handlePasswordAuth(m);
       if (m.type === MSG.AUTH) {
         if (!state.nonce) return;
         if (m.method !== 'pubkey' || !(m.public_key instanceof Uint8Array) || !(m.signature instanceof Uint8Array)) {
@@ -172,6 +205,29 @@ export function createConnectionFactory(cfg) {
       }
     }
 
+    async function handlePasswordAuth(m) {
+      state.awaitingPassword = false; // one guess per connection
+      if (m.method !== 'password' || typeof m.password !== 'string') return refuse('expected a password AUTH');
+      const rl = cfg.rateLimit;
+      const key = rl.key({ address: remote.address, headers: remote.headers, username: state.username });
+      const locked = rl.limiter.lockedFor(key);
+      if (locked > 0) {
+        // Not even evaluated: a locked-out caller learns nothing and costs nothing.
+        return refuse(`too many failed attempts; try again in ${Math.ceil(locked / 1000)}s`);
+      }
+      let ok = false;
+      try { ok = (await cfg.methods.password(state.username, m.password)) === true; } catch (e) { log(`password check threw: ${e.message}`); }
+      if (!ok) {
+        rl.limiter.fail(key);
+        if (rl.failureDelayMs > 0) await new Promise((r) => setTimeout(r, rl.failureDelayMs));
+        return refuse('authentication failed');
+      }
+      rl.limiter.succeed(key);
+      state.authed = true;
+      await send(authOk({ sessionId: state.sessionId, token: randomBytes(16), ttl: 3600 }));
+      log(`authenticated ${state.username} (password)`);
+    }
+
     // ── Open ──────────────────────────────────────────────────────────
 
     function handleOpen(m) {
@@ -363,6 +419,7 @@ export function createConnectionFactory(cfg) {
     async function handleFileOp(m) {
       const channelId = m.channel_id;
       if (!cfg.files) return send(fileResult({ channelId, success: false, errorMessage: 'file access is not enabled on this server' }));
+      if (m.op === 'write' || m.op === 'rename') return startPayloadOp(m);
       try {
         const r = await cfg.files.operate(m.op, m.path, { offset: m.offset, length: m.length });
         return send(fileResult({ channelId, success: true, metadata: r.metadata ?? {}, entries: r.entries ?? [] }));
@@ -373,6 +430,61 @@ export function createConnectionFactory(cfg) {
       }
     }
 
+    // write / rename = FileOp then FileChunk frame(s) on the same channel id
+    // (rename's payload is the UTF-8 destination path); one FileResult once
+    // the last chunk lands (see WshClient.fileOperation).
+    async function startPayloadOp(m) {
+      const channelId = m.channel_id;
+      const failWrite = (errorMessage) => send(fileResult({ channelId, success: false, errorMessage }));
+      const rename = m.op === 'rename';
+      const length = Number(m.length);
+      if (!Number.isSafeInteger(length) || length < 0) return failWrite(`${m.op} needs a length`);
+      const limit = rename ? MAX_RENAME_PATH_BYTES : cfg.files.maxFileBytes;
+      if (length > limit) return failWrite(`${m.op} payload of ${length} bytes exceeds the ${limit} byte limit`);
+      if (channels.has(channelId) || fileWrites.has(channelId)) return failWrite('channel id already in use');
+      if (fileWrites.size >= MAX_PENDING_WRITES) return failWrite('too many writes in flight');
+      const w = { rename, path: m.path, offset: m.offset, length, buf: new Uint8Array(length), next: 0, timer: null };
+      const arm = () => {
+        clearTimeout(w.timer);
+        w.timer = setTimeout(() => {
+          if (fileWrites.delete(channelId)) failWrite('write timed out waiting for data');
+        }, WRITE_IDLE_MS);
+        w.timer.unref?.();
+      };
+      arm();
+      w.arm = arm;
+      fileWrites.set(channelId, w);
+    }
+
+    async function handleWriteChunk(m) {
+      const channelId = m.channel_id;
+      const w = fileWrites.get(channelId);
+      const abort = (errorMessage) => {
+        clearTimeout(w.timer);
+        fileWrites.delete(channelId);
+        return send(fileResult({ channelId, success: false, errorMessage }));
+      };
+      const data = m.data instanceof Uint8Array ? m.data : new Uint8Array(0);
+      if (m.offset !== w.next) return abort('chunks must arrive in order');
+      if (w.next + data.byteLength > w.length) return abort('chunk past the declared length');
+      w.buf.set(data, w.next);
+      w.next += data.byteLength;
+      if (!m.is_final) { w.arm(); return; }
+      clearTimeout(w.timer);
+      fileWrites.delete(channelId);
+      if (w.next !== w.length) return send(fileResult({ channelId, success: false, errorMessage: 'payload ended short of the declared length' }));
+      try {
+        const r = w.rename
+          ? await cfg.files.operate('rename', w.path, { newPath: new TextDecoder('utf-8', { fatal: true }).decode(w.buf) })
+          : await cfg.files.operate('write', w.path, { offset: w.offset, data: w.buf });
+        return send(fileResult({ channelId, success: true, metadata: r.metadata ?? {} }));
+      } catch (e) {
+        const message = e.wsh ? e.message : (e.code === 'ENOENT' ? 'no such file or directory' : `${w.rename ? 'rename' : 'write'} failed`);
+        if (!e.wsh && e.code !== 'ENOENT') log(`file write ${w.path}: ${e.message}`);
+        return send(fileResult({ channelId, success: false, errorMessage: message }));
+      }
+    }
+
     return {
       receive(bytes) { if (!state.closed) qmux.receiveBytes(bytes); },
       close() { shutdown('transport closed'); },

package/src/server/fs.mjs

@@ -1,6 +1,6 @@
 /**
  * File access for `@johnhenry/wsh/server`: FileOp requests (list, stat, read,
- * mkdir, remove) and `upload:`/`download:` file channels, confined to one
+ * write, rename, mkdir, remove) and `upload:`/`download:` file channels, confined to one
  * root directory.
  *
  * Every path a client sends is resolved against `root`; a path that would
@@ -8,8 +8,9 @@
  */
 
 import {
-  readdir, lstat, stat, readFile, writeFile, mkdir, rmdir, unlink, readlink, realpath, open,
+  readdir, lstat, stat, readFile, writeFile, mkdir, rmdir, unlink, readlink, realpath, open, rename,
 } from 'node:fs/promises';
+import { constants as fsc } from 'node:fs';
 import path from 'node:path';
 
 export const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
@@ -71,7 +72,7 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
     maxFileBytes,
 
     /** @returns {Promise<{ metadata?: object, entries?: object[] }>} */
-    async operate(op, clientPath, { offset, length } = {}) {
+    async operate(op, clientPath, { offset, length, newPath, data } = {}) {
       switch (op) {
         case 'list': {
           const dir = await resolveInside(clientPath || '/');
@@ -111,8 +112,28 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
           await ((await lstat(full)).isDirectory() ? rmdir(full) : unlink(full));
           return { metadata: { removed: clientPath } };
         }
+        case 'write': {
+          if (!(data instanceof Uint8Array)) throw fail('write needs data');
+          await this.writeAt(clientPath, data, offset);
+          return { metadata: { written: data.byteLength } };
+        }
+        case 'rename': {
+          assertWritable();
+          if (typeof newPath !== 'string' || !newPath) throw fail('rename needs a destination path');
+          const from = await resolveInside(clientPath);
+          const to = await resolveInside(newPath);
+          if (from === base || to === base) throw fail('refusing to rename the file root');
+          if (from === to) return { metadata: { renamed: clientPath, to: newPath } };
+          if (to.startsWith(from + path.sep)) throw fail('cannot move a directory into itself');
+          await lstat(from); // ENOENT -> "no such file or directory"
+          let exists = true;
+          try { await lstat(to); } catch (e) { if (e.code === 'ENOENT') exists = false; else throw e; }
+          if (exists) throw fail('destination already exists');
+          await rename(from, to);
+          return { metadata: { renamed: clientPath, to: newPath } };
+        }
         default:
-          throw fail(`"${op}" is not offered by this host (list, stat, read, mkdir, remove; use upload/download to write)`);
+          throw fail(`"${op}" is not offered by this host (list, stat, read, write, rename, mkdir, remove)`);
       }
     },
 
@@ -125,10 +146,29 @@ export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAUL
     },
 
     async writeWhole(clientPath, data) {
+      return this.writeAt(clientPath, data, undefined, { mkdirs: true });
+    },
+
+    /**
+     * Write bytes into a regular file. `offset` omitted: replace the whole
+     * file (create/truncate). `offset` given: write in place at that byte
+     * offset without truncating (creates the file if missing).
+     */
+    async writeAt(clientPath, data, offset, { mkdirs = false } = {}) {
       assertWritable();
       const full = await resolveInside(clientPath);
-      await mkdir(path.dirname(full), { recursive: true });
-      await writeFile(full, data);
+      if (full === base) throw fail('not a regular file');
+      const at = offset === undefined || offset === null ? undefined : Number(offset);
+      if (at !== undefined && (!Number.isSafeInteger(at) || at < 0)) throw fail('illegal offset');
+      if ((at ?? 0) + data.byteLength > maxFileBytes) throw fail(`write would exceed the ${maxFileBytes} byte limit`);
+      if (mkdirs) await mkdir(path.dirname(full), { recursive: true });
+      // A FIFO or device would block or misbehave on open: regular files only.
+      try {
+        if (!(await stat(full)).isFile()) throw fail('not a regular file');
+      } catch (e) { if (e.wsh) throw e; if (e.code !== 'ENOENT') throw e; }
+      if (at === undefined) { await writeFile(full, data); return; }
+      const fh = await open(full, fsc.O_RDWR | fsc.O_CREAT, 0o644);
+      try { await fh.write(data, 0, data.byteLength, at); } finally { await fh.close(); }
     },
   };
 }

package/src/server/host-key.mjs

@@ -0,0 +1,66 @@
+/**
+ * The server's own Ed25519 identity (see ../host-key.mjs for the wire shape).
+ *
+ * `hostKey` option forms:
+ *  - `true`                          ephemeral key, new every start (TOFU clients will see "changed" after a restart -- tests/demos only)
+ *  - `{ file: '/path/host_key' }`    PKCS#8 PEM; created (mode 0600) on first start, reused after -- the normal choice
+ *  - a `CryptoKeyPair`               your own key, e.g. from `generateKeyPair()`
+ */
+
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as nodeSign } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { exportPublicKeyRaw, importPublicKeyRaw, exportPublicKeySSH, sign, fingerprint } from '../auth.mjs';
+
+const PEM_OPTS = { type: 'pkcs8', format: 'pem' };
+
+function fromNodePrivateKey(priv) {
+  const x = createPublicKey(priv).export({ format: 'jwk' }).x;
+  return Buffer.from(x, 'base64url');
+}
+
+/**
+ * @returns {Promise<{ publicKey: Uint8Array, fingerprint: string, openssh: string, sign(data: Uint8Array): Promise<Uint8Array> }>}
+ */
+export async function loadHostKey(option) {
+  let raw;
+  let signFn;
+
+  if (option === true) {
+    const priv = generateKeyPairSync('ed25519').privateKey;
+    raw = new Uint8Array(fromNodePrivateKey(priv));
+    signFn = async (data) => new Uint8Array(nodeSign(null, data, priv));
+  } else if (option && typeof option === 'object' && typeof option.file === 'string') {
+    let pem;
+    try {
+      pem = await readFile(option.file, 'utf8');
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      await mkdir(path.dirname(path.resolve(option.file)), { recursive: true });
+      const fresh = generateKeyPairSync('ed25519').privateKey.export(PEM_OPTS);
+      try {
+        await writeFile(option.file, fresh, { mode: 0o600, flag: 'wx' });
+        pem = fresh;
+      } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        pem = await readFile(option.file, 'utf8'); // another start won the race
+      }
+    }
+    const priv = createPrivateKey(pem);
+    if (priv.asymmetricKeyType !== 'ed25519') throw new TypeError(`createWshServer: hostKey.file ${option.file} is not an Ed25519 key`);
+    raw = new Uint8Array(fromNodePrivateKey(priv));
+    signFn = async (data) => new Uint8Array(nodeSign(null, data, priv));
+  } else if (option && option.privateKey && option.publicKey) {
+    raw = await exportPublicKeyRaw(option.publicKey);
+    signFn = (data) => sign(option.privateKey, data);
+  } else {
+    throw new TypeError('createWshServer: hostKey must be true, { file }, or a CryptoKeyPair');
+  }
+
+  return {
+    publicKey: raw,
+    fingerprint: await fingerprint(raw),
+    openssh: await exportPublicKeySSH(await importPublicKeyRaw(raw)),
+    sign: signFn,
+  };
+}