@needmoretruth/nmts-cli 0.36.3 → 0.38.1

package/dist/product.d.ts

@@ -9,7 +9,7 @@ export declare const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export declare const VERSION = "0.36.3";
+export declare const VERSION = "0.38.1";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export declare const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/product.js

@@ -18,7 +18,7 @@ export const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export const VERSION = "0.36.3";
+export const VERSION = "0.38.1";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/s3/contract.d.ts

@@ -0,0 +1,80 @@
+import type { Readable } from "node:stream";
+import type { PlaintextSink } from "../download-sink.ts";
+import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
+import type { DriveObject } from "./listing.ts";
+import type { GatewayCredential } from "./sigv4.ts";
+export interface DriveSource {
+    /** The account's live file list. Called per request; the caller decides what to cache. */
+    entries(): Promise<readonly ManifestEntry[]>;
+    /**
+     * Fetch, decrypt and deliver one file into the sink.
+     *
+     * ⛔ INJECTED RATHER THAN IMPORTED so this server can be driven by a real S3 client in a test
+     *    without an account, a network and somebody's credits. A gateway whose only test is an
+     *    end-to-end one is a gateway whose refusals are never tested at all.
+     */
+    fetch(object: DriveObject, sink: PlaintextSink): Promise<void>;
+    /**
+     * How to change the drive, when this machine has agreed to spending.
+     *
+     * ⛔ ABSENT MEANS READ ONLY, AND THAT IS A REFUSAL RATHER THAN A GAP. Uploading spends credits,
+     *    which is one of the three things this tool asks a person about once per machine, and a
+     *    gateway cannot ask: its stdin is not a terminal and the caller is a program. So the
+     *    agreement has to exist beforehand, and where it does not, every write says so.
+     */
+    readonly write?: DriveWriter;
+}
+export interface DriveWriter {
+    /** Store `body` at this key. `size` is the byte count the client declared. */
+    put(key: string, body: Readable, size: number): Promise<void>;
+    /** Send one file to the trash, where it stays recoverable for thirty days. */
+    trash(object: DriveObject): Promise<void>;
+    /**
+     * Staging for uploads that arrive in pieces. Absent means this gateway refuses them.
+     *
+     * ⚠ Separate from `put` because the pieces have to land somewhere before they are one file, and
+     *   where that is belongs to whoever is running this rather than to the protocol.
+     */
+    readonly multipart?: {
+        begin(key: string): Promise<string>;
+        part(uploadId: string, partNumber: number, body: Readable, size: number, expectedSha256: string | null): Promise<string>;
+        complete(uploadId: string): Promise<string>;
+        abort(uploadId: string): Promise<void>;
+    };
+}
+export interface GatewayOptions {
+    /**
+     * Every pair that may sign a request here, each optionally held to named buckets.
+     *
+     * ⛔ A LIST RATHER THAN ONE PAIR BECAUSE A BUCKET IS AN ACCOUNT. `nmts s3` makes one pair for one
+     *    drive; a business serving many of its users' accounts hands each of them a pair of their
+     *    own, and the restriction on the pair is what stops one customer reading another's bucket.
+     */
+    readonly credentials: readonly GatewayCredential[];
+    /**
+     * Which drive answers to this bucket name, or null when none does.
+     *
+     * ⛔ THE GATEWAY DOES NOT KNOW WHAT A BUCKET IS. It was one name and one drive for as long as the
+     *    only caller was the command-line tool; asked by a business's server it is a lookup that
+     *    server does, and one it may do differently per name. What must not change is that a name
+     *    this resolver refuses looks exactly like a name the caller may not touch (see below).
+     */
+    readonly bucketOf: (name: string) => DriveSource | null | Promise<DriveSource | null>;
+    /**
+     * The names `ListBuckets` answers with, before the signing pair's own restriction is applied.
+     *
+     * ⚠ ABSENT IS A REAL ANSWER RATHER THAN A GAP. A gateway in front of a business's own lookup
+     *   cannot enumerate its customers, so what it can honestly name is what the presented pair is
+     *   held to — and an unrestricted pair on such a gateway is told nothing, which is true.
+     */
+    readonly bucketNames?: () => readonly string[] | Promise<readonly string[]>;
+    /** Called with one line whenever a request is answered, so a person can watch what a tool does. */
+    readonly log?: (line: string) => void;
+    /** Passed in so a test can hold the clock still. */
+    readonly now?: () => number;
+    /**
+     * The sentence a write gets from a read-only drive. `nmts s3` says what a person runs on this
+     * machine to allow spending; a gateway somebody else runs has a different way in, and says its own.
+     */
+    readonly readOnlyBecause?: string | undefined;
+}

package/dist/s3/contract.js

@@ -0,0 +1,3 @@
+// What whoever runs the gateway has to hand it: where a bucket's files come from, how (or whether)
+// they may be changed, and who may sign for them.
+export {};

package/dist/s3/drive.d.ts

@@ -0,0 +1,108 @@
+import type { PlaintextSink } from "../download-sink.ts";
+import type { Network } from "../network.ts";
+import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
+import type { ReadOptions } from "../walrus.ts";
+import type { DriveObject } from "./listing.ts";
+import type { DriveSource } from "./server.ts";
+import { type Staging } from "./staging.ts";
+/**
+ * How long a file list may be reused before it is fetched again.
+ *
+ * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
+ *    mean a server round trip and a decryption for each one, so a listing of a large drive would
+ *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
+ *    device can be up to this long in appearing here, which is the trade and is written in the
+ *    tool's own words when it starts.
+ */
+export declare const LIST_CACHE_MS = 5000;
+/**
+ * Where a drive comes from, for whoever is running the gateway.
+ *
+ * ⛔ SIX FUNCTIONS AND NO CREDENTIAL. The command-line tool holds an open session; the SDK holds a
+ *    client whose key may be in a business's sealed store and is borrowed one call at a time.
+ *    Nothing in this file may care which, so nothing in this file is handed a key -- `withCode`
+ *    borrows one for the length of a comparison and the caller decides what that costs.
+ */
+export interface DriveAccount {
+    /** The account's file list, read fresh from the server. Empty for an account that has none. */
+    readList(): Promise<readonly ManifestEntry[]>;
+    /**
+     * Borrow the account's code for the length of `use`.
+     *
+     * ⚠ ASKED FOR ONE THING ONLY: opening the hash this drive recorded for a file already at the key,
+     *   which is sealed under the account's own data key and cannot be compared without it.
+     */
+    withCode<T>(use: (code: string) => Promise<T>): Promise<T>;
+    /** Make this folder path, and any folder above it that is missing. */
+    makeFolder(path: string): Promise<void>;
+    /** Store one local file under `name`, in `folder` — the top of the account when undefined. */
+    store(local: string, name: string, folder: string | undefined): Promise<void>;
+    /** Send one path — with its leading slash — to the trash, where it stays for thirty days. */
+    trash(path: string): Promise<void>;
+    /** Fetch, decrypt and deliver one file into the sink. `fetchObject` below is how both do it. */
+    fetch(object: DriveObject, sink: PlaintextSink): Promise<void>;
+}
+export interface DriveSourceOptions {
+    readonly account: DriveAccount;
+    /**
+     * Where the pieces of a multipart upload wait until they are one file.
+     *
+     * ⛔ 0700, AND MADE WHEN IT IS FIRST NEEDED. Pieces are somebody's plaintext; leaving them in a
+     *    shared temporary directory under a predictable name would put them where any other account
+     *    on the machine could read them, for as long as the upload takes and afterwards.
+     */
+    readonly stagingRoot: string;
+    /**
+     * False makes this drive read only, and that is a refusal rather than a gap — the gateway
+     * answers every write with the sentence naming what would allow it.
+     */
+    readonly writable: boolean;
+    /**
+     * The staging an earlier source for the same bucket was using, when there was one.
+     *
+     * ⛔ AN UPLOAD IN PIECES OUTLIVES THE SOURCE IT BEGAN UNDER. A caller that rebuilds its sources —
+     *    a gateway re-asking whose bucket this is — would otherwise hand the next piece to a staging
+     *    that has never heard of the upload, and a large file could never finish.
+     */
+    readonly multipart?: Staging | undefined;
+    /** How long a file list may be reused. `LIST_CACHE_MS` unless a caller has a reason. */
+    readonly listCacheMs?: number | undefined;
+    /**
+     * Told the key when it already held exactly these bytes, so nothing was sent.
+     *
+     * ⭐ NOT AN ERROR. An unchanged file costs nothing to re-offer, which is what stops a backup that
+     *    runs nightly paying for the nights nothing changed. The words a person reads are the
+     *    caller's — this file has no terminal.
+     */
+    readonly onAlreadyStored?: ((key: string) => void) | undefined;
+}
+/** Everything `fetchObject` needs to open one file: where to ask, and whose key opens it. */
+export interface ObjectReader {
+    readonly server: string;
+    /**
+     * What goes in the one header the server reads: an API key, or a delegation token.
+     *
+     * ⛔ NAMED FOR WHAT IT IS RATHER THAN FOR ONE OF THE TWO. A field called `apiKey` carrying a
+     *    delegation token is how a reader comes to believe a delegated client cannot do something it
+     *    can.
+     */
+    readonly bearer: string;
+    readonly code: string;
+    readonly chain: Network;
+    /** Hosts to read stored bytes from, instead of the network's own aggregators. */
+    readonly read?: ReadOptions | undefined;
+}
+/**
+ * `photos/2026/a.jpg` → the folder to make and the name to store under.
+ *
+ * A key with no slash lands at the top of the account, which is `undefined` rather than `""`: the
+ * two mean the same thing to a person and different things to the upload path.
+ */
+export declare function placeOf(key: string): {
+    folder: string | undefined;
+    name: string;
+};
+/** The real reader: the stored bytes, opened with this account's key and delivered to the sink. */
+export declare function fetchObject(reader: ObjectReader, object: DriveObject, sink: PlaintextSink): Promise<void>;
+/** One account as the protocol layer sees it: a cached list, a reader, and a writer when allowed. */
+export declare function createDriveSource(options: DriveSourceOptions): DriveSource;

package/dist/s3/drive.js

@@ -0,0 +1,136 @@
+// One account behind the gateway: its file list, its reader, and the rule every upload passes.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS, WHICH IS THE WHOLE REASON THIS FILE EXISTS. `nmts s3` serves
+//    the drive of whoever is at this machine; the SDK's gateway serves whichever account a
+//    business's resolver hands back. What the two do with an upload -- spool it, ask whether the
+//    key already holds exactly these bytes, make the folders above it, store it, forget the cached
+//    list -- is the same work, and a second copy of it would be a second place for the same-file
+//    rule to be got right. The two differ only in where the account comes from, which is the seam
+//    below.
+//
+// ⛔ THE SAME-FILE QUESTION IS ANSWERED HERE AND NOWHERE ELSE. Both ways of uploading -- one PUT,
+//    or pieces staged and joined -- end in `storeFile`, so a rule written here cannot disagree with
+//    itself; written in the protocol layer it would have to be written twice, once for each, and
+//    the two would differ the first time one of them changed.
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir as makeDir, rm as removeFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { fetchFile } from "../download.js";
+import { NmtsError } from "../errors.js";
+import { refusalFor, verdictForKey } from "./same-file.js";
+import { createStaging } from "./staging.js";
+/**
+ * How long a file list may be reused before it is fetched again.
+ *
+ * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
+ *    mean a server round trip and a decryption for each one, so a listing of a large drive would
+ *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
+ *    device can be up to this long in appearing here, which is the trade and is written in the
+ *    tool's own words when it starts.
+ */
+export const LIST_CACHE_MS = 5_000;
+/**
+ * `photos/2026/a.jpg` → the folder to make and the name to store under.
+ *
+ * A key with no slash lands at the top of the account, which is `undefined` rather than `""`: the
+ * two mean the same thing to a person and different things to the upload path.
+ */
+export function placeOf(key) {
+    const at = key.lastIndexOf("/");
+    if (at < 0)
+        return { folder: undefined, name: key };
+    const folder = key.slice(0, at);
+    return { folder: folder === "" ? undefined : folder, name: key.slice(at + 1) };
+}
+/** The real reader: the stored bytes, opened with this account's key and delivered to the sink. */
+export async function fetchObject(reader, object, sink) {
+    const wrapped = object.entry.dekWrapped;
+    if (wrapped === undefined)
+        throw new NmtsError("That entry has no key in the file list.");
+    await fetchFile({
+        base: reader.server,
+        apiKey: reader.bearer,
+        accountCode: reader.code,
+        itemId: object.entry.id,
+        size: object.size,
+        dekWrapped: wrapped,
+        contentHashCt: object.entry.contentHashCt,
+        chain: reader.chain,
+        sink,
+        ...(reader.read === undefined ? {} : { read: reader.read }),
+    });
+}
+/** One account as the protocol layer sees it: a cached list, a reader, and a writer when allowed. */
+export function createDriveSource(options) {
+    const account = options.account;
+    const cacheMs = options.listCacheMs ?? LIST_CACHE_MS;
+    let cached = [];
+    let cachedAt = 0;
+    const entries = async () => {
+        if (Date.now() - cachedAt < cacheMs)
+            return cached;
+        cached = await account.readList();
+        cachedAt = Date.now();
+        return cached;
+    };
+    /**
+     * Store one local file at a drive key, making the folders above it if they are missing.
+     *
+     * ⭐ IDENTICAL CONTENT IS NOT AN ERROR. Nothing is sent and nothing is charged, and the caller is
+     *    told the upload finished — because the statement it was making, "that file is at that key",
+     *    is true. Answering 409 there is what made every backup run fail on every file it had already
+     *    stored, and a sync tool writes 409 down as a failure.
+     */
+    const storeFile = async (key, path) => {
+        const { folder, name } = placeOf(key);
+        const known = await entries();
+        const verdict = await account.withCode((code) => verdictForKey(known, key, code, path));
+        if (verdict === "same") {
+            options.onAlreadyStored?.(key);
+            return;
+        }
+        if (verdict !== "free")
+            throw refusalFor(verdict, key);
+        if (folder !== undefined)
+            await account.makeFolder(folder);
+        await account.store(path, name, folder);
+        cachedAt = 0;
+    };
+    return {
+        entries,
+        fetch: (object, sink) => account.fetch(object, sink),
+        ...(options.writable
+            ? {
+                write: {
+                    // ⛔ THE BODY IS SPOOLED TO A FILE FIRST, 0600, and deleted whatever happens. The
+                    //    upload path reserves storage, cuts parts and seals them from a file, and giving it
+                    //    a socket instead would mean either holding whole uploads in memory or writing a
+                    //    second upload path — and a second upload path is a second place for "what if the
+                    //    reservation succeeds and the part fails" to be got right.
+                    put: async (key, body, size) => {
+                        await makeDir(options.stagingRoot, { recursive: true, mode: 0o700 });
+                        const spool = join(options.stagingRoot, randomUUID());
+                        try {
+                            await pipeline(body, createWriteStream(spool, { mode: 0o600 }));
+                            const written = (await stat(spool)).size;
+                            if (written !== size) {
+                                throw new NmtsError(`The upload said ${size} bytes and ${written} arrived. Nothing was stored.`);
+                            }
+                            await storeFile(key, spool);
+                        }
+                        finally {
+                            await removeFile(spool, { force: true });
+                        }
+                    },
+                    multipart: options.multipart ?? createStaging(options.stagingRoot, storeFile),
+                    trash: async (object) => {
+                        await account.trash(`/${object.key}`);
+                        cachedAt = 0;
+                    },
+                },
+            }
+            : {}),
+    };
+}

package/dist/s3/listing.d.ts

@@ -1,6 +1,13 @@
 import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
 import type { ObjectRow } from "./xml.ts";
-/** The one bucket. Named for what it is, and not configurable: two names for one drive is worse. */
+/**
+ * The bucket `nmts s3` serves. Named for what it is, and not configurable: two names for one drive
+ * is worse.
+ *
+ * ⚠ IT IS THIS COMMAND'S ANSWER, NOT THE SERVER'S RULE. The gateway takes a resolver, because a
+ *   business running it in front of many of its users' accounts has one bucket per account; what
+ *   `nmts s3` hands it is a resolver that knows this name and no other.
+ */
 export declare const BUCKET = "drive";
 /** S3's own ceiling, and the default when a client does not ask for one. */
 export declare const MAX_KEYS_LIMIT = 1000;

package/dist/s3/listing.js

@@ -13,7 +13,14 @@
 //   prefix. Real S3 has no folders, so an empty one cannot exist there; this drive does have them,
 //   and hiding them would make `rclone lsd` describe a drive that is not the one in the browser.
 import { buildIndex, fullPathOf, isLive, KIND_FOLDER } from "../drive-paths.js";
-/** The one bucket. Named for what it is, and not configurable: two names for one drive is worse. */
+/**
+ * The bucket `nmts s3` serves. Named for what it is, and not configurable: two names for one drive
+ * is worse.
+ *
+ * ⚠ IT IS THIS COMMAND'S ANSWER, NOT THE SERVER'S RULE. The gateway takes a resolver, because a
+ *   business running it in front of many of its users' accounts has one bucket per account; what
+ *   `nmts s3` hands it is a resolver that knows this name and no other.
+ */
 export const BUCKET = "drive";
 /** S3's own ceiling, and the default when a client does not ask for one. */
 export const MAX_KEYS_LIMIT = 1000;

package/dist/s3/routes.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { GatewayOptions } from "./contract.ts";
+export declare function fail(res: ServerResponse, status: number, code: string, message: string, resource: string): void;
+export declare function handle(req: IncomingMessage, res: ServerResponse, options: GatewayOptions): Promise<void>;

package/dist/s3/routes.js

@@ -0,0 +1,249 @@
+// Which answer an S3 request gets: the signature first, then the bucket, then the verb.
+//
+// ⛔ WHAT IS NOT ANSWERED IS REFUSED, LOUDLY. An S3 client that asks for something this gateway does
+//    not do gets 501 and a sentence naming what it does do. The alternative -- answering an empty
+//    listing, or a 200 with nothing behind it -- is how a backup tool reports success over a backup
+//    that never happened.
+import { listObjects, objectsOf, folderPrefixesOf, MAX_KEYS_LIMIT } from "./listing.js";
+import { handleMultipart, isMultipartRequest } from "./multipart.js";
+import { responseSink } from "./response-sink.js";
+import { isKeyConflict } from "./same-file.js";
+import { STREAMING_PAYLOAD, STREAMING_PAYLOAD_TRAILER, verifyAgainst, } from "./sigv4.js";
+import { errorXml, listBucketsXml, listObjectsXml } from "./xml.js";
+/**
+ * What a caller signed with a pair it may not use here.
+ *
+ * ⛔ THE SAME ANSWER WHETHER OR NOT THE BUCKET EXISTS, which is why the restriction is checked
+ *    before the resolver is asked. Answering `NoSuchBucket` for a name the caller may not touch
+ *    would turn this gateway into a way of asking "does this business have a customer called…",
+ *    one guess at a time.
+ */
+const NOT_YOURS = "That access key may not use that bucket.";
+export function fail(res, status, code, message, resource) {
+    const body = errorXml(code, message, resource);
+    res.writeHead(status, { "content-type": "application/xml", "content-length": String(Buffer.byteLength(body)) });
+    res.end(body);
+}
+/** `/drive/photos/a.jpg` → bucket `drive`, key `photos/a.jpg`. */
+function splitPath(pathname) {
+    const trimmed = pathname.replace(/^\//, "");
+    const at = trimmed.indexOf("/");
+    if (at < 0)
+        return { bucket: decodeURIComponent(trimmed), key: "" };
+    return { bucket: decodeURIComponent(trimmed.slice(0, at)), key: decodeURIComponent(trimmed.slice(at + 1)) };
+}
+function headerOf(req, name) {
+    const raw = req.headers[name];
+    return Array.isArray(raw) ? raw.join(",") : raw;
+}
+/** The one sentence a write gets from `nmts s3` when this machine has not agreed to spending. */
+function readOnlyOnThisMachine() {
+    return ("This gateway is read only. Uploading spends credits, and this machine has not agreed to " +
+        "spending — `nmts consent grant spend`, run by the person whose account this is, is what " +
+        "changes that. Nothing was written.");
+}
+/** Whether the pair that signed is allowed anywhere near this bucket name. */
+function mayTouch(credential, bucket) {
+    const only = credential.buckets;
+    return only === undefined || only.includes(bucket);
+}
+/** What `ListBuckets` says: what the gateway can name, narrowed to what this pair may touch. */
+async function bucketsFor(options, credential) {
+    const only = credential.buckets;
+    if (options.bucketNames === undefined)
+        return only ?? [];
+    const named = await options.bucketNames();
+    return only === undefined ? named : named.filter((name) => only.includes(name));
+}
+function objectHeaders(object) {
+    return {
+        "content-type": "application/octet-stream",
+        "last-modified": new Date(object.entry.updatedAt).toUTCString(),
+        etag: object.etag,
+        "accept-ranges": "none",
+    };
+}
+export async function handle(req, res, options) {
+    const url = req.url ?? "/";
+    const at = url.indexOf("?");
+    const pathname = at < 0 ? url : url.slice(0, at);
+    const query = new URLSearchParams(at < 0 ? "" : url.slice(at + 1));
+    const method = (req.method ?? "GET").toUpperCase();
+    const verdict = verifyAgainst({ method, url, headers: req.headers }, options.credentials, options.now?.() ?? Date.now());
+    if (!verdict.ok) {
+        fail(res, 403, verdict.code, verdict.message, pathname);
+        return;
+    }
+    const credential = verdict.credential;
+    const { bucket, key } = splitPath(pathname);
+    if (pathname === "/" && (method === "GET" || method === "HEAD")) {
+        const body = listBucketsXml(await bucketsFor(options, credential), new Date(0).toISOString());
+        res.writeHead(200, { "content-type": "application/xml", "content-length": String(Buffer.byteLength(body)) });
+        res.end(method === "HEAD" ? undefined : body);
+        return;
+    }
+    if (!mayTouch(credential, bucket)) {
+        fail(res, 403, "AccessDenied", NOT_YOURS, pathname);
+        return;
+    }
+    const source = await options.bucketOf(bucket);
+    if (source === null) {
+        fail(res, 404, "NoSuchBucket", `No bucket named ${bucket} is served here.`, pathname);
+        return;
+    }
+    // ⛔ MEASURED, NOT GUESSED: rclone's first act when copying a file is to create the bucket, and a
+    //    refusal here ends the copy before the upload is ever attempted. The bucket exists, so the
+    //    honest answer to "make it" is that it is made.
+    if (key === "" && method === "PUT") {
+        res.writeHead(200, { "content-length": "0" });
+        res.end();
+        return;
+    }
+    const entries = await source.entries();
+    if (key === "" && (method === "GET" || method === "HEAD")) {
+        const objects = objectsOf(entries);
+        const listing = listObjects(objects, folderPrefixesOf(entries), {
+            prefix: query.get("prefix") ?? "",
+            delimiter: query.get("delimiter") ?? "",
+            maxKeys: Number(query.get("max-keys") ?? MAX_KEYS_LIMIT) || MAX_KEYS_LIMIT,
+            after: query.get("continuation-token") ?? query.get("start-after") ?? query.get("marker"),
+        });
+        const body = listObjectsXml({
+            bucket,
+            prefix: query.get("prefix") ?? "",
+            delimiter: query.get("delimiter") ?? "",
+            maxKeys: Number(query.get("max-keys") ?? MAX_KEYS_LIMIT) || MAX_KEYS_LIMIT,
+            v2: query.get("list-type") === "2",
+            contents: listing.contents,
+            commonPrefixes: listing.commonPrefixes,
+            truncated: listing.truncated,
+            next: listing.next,
+            encodingType: query.get("encoding-type"),
+        });
+        res.writeHead(200, { "content-type": "application/xml", "content-length": String(Buffer.byteLength(body)) });
+        res.end(method === "HEAD" ? undefined : body);
+        options.log?.(`${method} list prefix=${query.get("prefix") ?? ""} → ${listing.contents.length} keys`);
+        return;
+    }
+    if (method === "HEAD" || method === "GET") {
+        const object = objectsOf(entries).find((o) => o.key === key);
+        if (object === undefined) {
+            fail(res, 404, "NoSuchKey", "This account's file list has no such file.", pathname);
+            return;
+        }
+        if (method === "HEAD") {
+            res.writeHead(200, { ...objectHeaders(object), "content-length": String(object.size) });
+            res.end();
+            options.log?.(`HEAD ${key}`);
+            return;
+        }
+        if (object.entry.dekWrapped === undefined) {
+            fail(res, 500, "InternalError", "That entry has no key in the file list.", pathname);
+            return;
+        }
+        const sink = responseSink(res, { headers: objectHeaders(object) });
+        try {
+            await source.fetch(object, sink);
+            options.log?.(`GET ${key} → ${object.size} bytes`);
+        }
+        catch (error) {
+            await sink.abandon();
+            if (!res.headersSent) {
+                fail(res, 502, "InternalError", error instanceof Error ? error.message : String(error), pathname);
+            }
+            options.log?.(`GET ${key} → failed`);
+        }
+        return;
+    }
+    const writer = source.write;
+    // ⛔ WHETHER A TAKEN KEY IS A CONFLICT IS NOT DECIDED HERE.
+    //    It used to be, on the strength of the NAME alone, and both upload paths carried their own
+    //    copy of that check. The question is now about CONTENT — is the file arriving the file
+    //    already there — and it cannot be answered until the bytes have arrived, so it is answered
+    //    once, by the writer, at the point both paths meet. What reaches this layer is the verdict:
+    //    a writer that returns normally means the key now holds these bytes (whether it had to send
+    //    them or they were already there), and one that throws a conflict means something else is at
+    //    that key. ⭐ The status matters: 409 is a request the drive declined, 500 is a fault of ours.
+    const refuseConflict = (error) => {
+        fail(res, 409, "InvalidRequest", error instanceof Error ? error.message : String(error), pathname);
+    };
+    if (isMultipartRequest(method, query) && key !== "") {
+        if (writer === undefined) {
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
+            return;
+        }
+        const handled = await handleMultipart({
+            req,
+            res,
+            bucket,
+            key,
+            method,
+            query,
+            writer,
+            payloadHash: /^[0-9a-f]{64}$/.test(verdict.payloadHash) ? verdict.payloadHash : null,
+            fail: (status, code, message) => fail(res, status, code, message, pathname),
+            ...(options.log === undefined ? {} : { log: options.log }),
+        });
+        if (handled)
+            return;
+    }
+    if (method === "PUT" && key !== "") {
+        if (writer === undefined) {
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
+            return;
+        }
+        const declared = headerOf(req, "x-amz-content-sha256");
+        if (declared === STREAMING_PAYLOAD || declared === STREAMING_PAYLOAD_TRAILER) {
+            fail(res, 501, "NotImplemented", "This gateway does not read chunk-signed uploads yet. Tell the client to send the body " +
+                "unsigned (the AWS CLI calls this --no-sign-payload on http endpoints; rclone already " +
+                "does it).", pathname);
+            return;
+        }
+        const length = Number(headerOf(req, "content-length") ?? "");
+        if (!Number.isInteger(length) || length < 0) {
+            fail(res, 411, "MissingContentLength", "This gateway needs to know the size before it starts.", pathname);
+            return;
+        }
+        try {
+            await writer.put(key, req, length);
+        }
+        catch (error) {
+            if (isKeyConflict(error)) {
+                refuseConflict(error);
+                return;
+            }
+            fail(res, 500, "InternalError", error instanceof Error ? error.message : String(error), pathname);
+            return;
+        }
+        res.writeHead(200, { "content-length": "0" });
+        res.end();
+        options.log?.(`PUT ${key} → ${length} bytes`);
+        return;
+    }
+    if (method === "DELETE" && key !== "") {
+        if (writer === undefined) {
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
+            return;
+        }
+        const object = objectsOf(entries).find((o) => o.key === key);
+        if (object === undefined) {
+            // S3 answers 204 for a key that is not there, and clients rely on it: a sync that deletes
+            // the same key twice must not fail the second time.
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        try {
+            await writer.trash(object);
+        }
+        catch (error) {
+            fail(res, 500, "InternalError", error instanceof Error ? error.message : String(error), pathname);
+            return;
+        }
+        res.writeHead(204);
+        res.end();
+        options.log?.(`DELETE ${key} → trash`);
+        return;
+    }
+    fail(res, 501, "NotImplemented", `This gateway does not answer ${method} on that address.`, pathname);
+}