@needmoretruth/nmts-cli 0.38.0 → 0.39.0

package/dist/drive-erase.js

@@ -0,0 +1,161 @@
+// Erasing files for good, without a terminal: the targets resolved, the treasury's storage let go,
+// the server's records destroyed and the entries taken out of the sealed list — decided, done and
+// handed back rather than printed.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS, WHICH IS THE WHOLE REASON THIS FILE EXISTS — the argument
+//    `drive-edit.ts` makes one verb family over. `commands/erase.ts` is a terminal's shape: it
+//    prints the list, asks for the typed sentence and answers an exit code. The SDK is somebody
+//    else's program and needs the same act with none of those. A second implementation of "what
+//    order do these three destructions happen in" would be a second place for the rules below to
+//    be got right, and the copy nobody re-reads is the one that quietly disagrees — about the one
+//    verb in this package that nothing can undo.
+//
+// ⛔ NOTHING HERE WRITES TO A STREAM, PICKS AN EXIT CODE OR ASKS ANYBODY ANYTHING. The confirmation
+//    is the caller's: a terminal types a sentence, a program passes one. This file is reached only
+//    after somebody decided, and it destroys what it is given.
+//
+// ⛔ THE SERVER GOES FIRST AND THE LIST LAST, which is the order the trash keeps and for the same
+//    reason: a row erased before its list entry leaves a file the person can see and never open.
+//    A release that FAILS stops the run before a single row is touched — nothing is erased behind
+//    one. A release the server REFUSES ("that storage was bought by the wallet, not by credits")
+//    is an answer rather than a failure: it is reported on that file and the erase goes on.
+//
+// ⛔ THE PROOF IS THE CALLER'S TO BUILD AND IS NOT DERIVED HERE. Both doors ask for the account
+//    code's own proof, and WHETHER this run may make one is a policy question with two different
+//    answers — the command line asks for an agreement first (`account-proof.ts`), a library caller
+//    has already made that decision by calling. So it arrives as a value. Nothing here reaches for
+//    `node:`: the SDK's browser entry bundles what this exports.
+//
+// ⚠ THE PIECES IT BORROWS COME FROM `drive-edit/` DIRECTLY, the way that folder's own files borrow
+//   from each other. This is a sibling of that family rather than an outside caller.
+import { request, ServerError } from "./api.js";
+import { DriveEditError, resolving } from "./drive-edit/errors.js";
+import { filesUnder, uniqueById } from "./drive-edit/tree.js";
+import { buildIndex, fullPathOf, KIND_FILE } from "./drive-paths.js";
+import { NmtsError } from "./errors.js";
+import { readFileList } from "./manifest.js";
+import { applyToList, batchTargets } from "./manifest-write.js";
+import { BINARY_NAME } from "./product.js";
+/** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
+const BATCH = 200;
+/** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */
+const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
+/**
+ * Work out what erasing these paths would destroy, without destroying anything.
+ *
+ * ⛔ ITS OWN STEP BECAUSE ONE CALLER HAS TO SHOW THE LIST BEFORE IT ASKS. `nmts erase` prints every
+ *    file it is about to destroy and then waits for a typed sentence; folding this into the act
+ *    would leave the terminal with nothing to print, and reading the list twice would leave the
+ *    two reads free to disagree about what is in it.
+ */
+export async function planErase(input, paths) {
+    const list = await readFileList(input.server, input.apiKey, input.code, input.accountId);
+    const entries = list.manifest?.entries ?? [];
+    const index = buildIndex(entries);
+    const targets = resolving(() => batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." }));
+    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
+    const going = uniqueById([...targets, ...files]);
+    if (files.length === 0) {
+        throw new DriveEditError("NOT_FOUND", `Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
+            exitCode: 4,
+        });
+    }
+    return {
+        files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })),
+        going: going.map((e) => e.id),
+    };
+}
+/**
+ * Destroy what the plan names. ⛔ Irreversible, and nothing below asks whether the caller meant it.
+ */
+export async function eraseFiles(input, plan, options = {}) {
+    const releases = [];
+    if (options.releaseStorage === true) {
+        for (const f of plan.files) {
+            const path = f.path;
+            try {
+                const reply = await request(input.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
+                    method: "POST",
+                    body: {},
+                    token: input.apiKey,
+                    accountProof: input.accountProof,
+                });
+                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
+            }
+            catch (error) {
+                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
+                //    out of the balance, and a balance that cannot cover it means the release did not
+                //    happen — erasing behind it would destroy the account's key to bytes that are still
+                //    being served and still being paid for. Nothing is erased, and the two numbers say
+                //    exactly how far short the balance is.
+                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
+                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
+                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
+                        exitCode: 4,
+                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
+                            `to erase the file and let its storage run out on its own.`,
+                    });
+                }
+                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
+                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
+                //   server could not do, stops the run before a row is touched.
+                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
+                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    let erased = 0;
+    for (let i = 0; i < plan.files.length; i += BATCH) {
+        const reply = await request(input.server, "/v1/items/erase", {
+            method: "POST",
+            body: { item_ids: plan.files.slice(i, i + BATCH).map((f) => f.id) },
+            token: input.apiKey,
+            accountProof: input.accountProof,
+        });
+        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
+            ? Number(Reflect.get(reply, "erased"))
+            : 0;
+    }
+    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
+    //    ids this run erased leave it, whatever another device wrote in between.
+    const ids = new Set(plan.going);
+    const result = await applyToList(input, (current) => {
+        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
+        return still.length === 0 ? null : { op: "purge", ids: still };
+    });
+    return { erased, files: [...plan.files], releases, seq: result.seq };
+}
+/**
+ * Resolve these paths and destroy what they name, in one call.
+ *
+ * ⚠ FOR A CALLER THAT HAS ALREADY DECIDED. Anything that shows a person what is about to go should
+ *   use `planErase` first, so what it shows is what it then destroys.
+ */
+export async function erasePaths(input, paths, options = {}) {
+    return eraseFiles(input, await planErase(input, paths), options);
+}
+/** The three counts a release answers with, read defensively. */
+function counts(reply) {
+    const n = (name) => {
+        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+        return typeof v === "number" ? v : 0;
+    };
+    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
+}
+/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
+function fee(reply) {
+    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
+    const charged = at("fee_credits");
+    return {
+        feeCredits: typeof charged === "number" ? charged : 0,
+        fromDeposit: at("from_deposit") === true,
+    };
+}
+/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
+function amount(error, field) {
+    const value = error.details[field];
+    return typeof value === "number" ? String(value) : "?";
+}

package/dist/platform-sign.d.ts

@@ -25,14 +25,22 @@ export declare const DELEGATION_MAX_TTL_SECS = 2592000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export declare const SCOPE_BITS: {
     readonly files_read: 1;
     readonly files_write: 2;
     readonly storage_spend: 4;
     readonly register: 8;
+    readonly files_erase: 16;
 };
-/** One of the four names above. */
+/** One of the five names above. */
 export type ScopeName = keyof typeof SCOPE_BITS;
 /** Every bit a token may carry. */
 export declare const SCOPE_ALL: number;

package/dist/platform-sign.js

@@ -53,15 +53,23 @@ export const DELEGATION_MAX_TTL_SECS = 2_592_000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export const SCOPE_BITS = {
     files_read: 1,
     files_write: 2,
     storage_spend: 4,
     register: 8,
+    files_erase: 16,
 };
 /** Every bit a token may carry. */
-export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register;
+export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register | SCOPE_BITS.files_erase;
 /**
  * A new key pair, from the runtime's own random source.
  *

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.38.0";
+export declare const VERSION = "0.39.0";
 /** 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.38.0";
+export const VERSION = "0.39.0";
 /** 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/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);
+}