@needmoretruth/nmts-cli 0.36.3 → 0.38.0

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/server.d.ts

@@ -1,4 +1,4 @@
-import { type Server } from "node:http";
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import type { Readable } from "node:stream";
 import type { PlaintextSink } from "../download-sink.ts";
 import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
@@ -46,13 +46,52 @@ export interface DriveWriter {
     };
 }
 export interface GatewayOptions {
-    readonly credential: GatewayCredential;
-    readonly source: DriveSource;
+    /**
+     * 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;
 }
 /** A random pair, made fresh every time the gateway starts and stored nowhere. */
 export declare function newCredential(): GatewayCredential;
+/** A plain Node request handler, so this can be mounted in somebody else's server. */
+export type GatewayHandler = (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * The gateway as a handler, which is the form that listens to nothing.
+ *
+ * ⛔ SEPARATE FROM `createGateway` BECAUSE WHO LISTENS IS NOT THIS FILE'S DECISION. The
+ *    command-line tool binds loopback and says why at the top of this file; a business mounting
+ *    this behind its own TLS has already made that decision, and a library that opened a socket of
+ *    its own would be making it again, differently.
+ */
+export declare function gatewayHandler(options: GatewayOptions): GatewayHandler;
 export declare function createGateway(options: GatewayOptions): Server;

package/dist/s3/server.js

@@ -12,14 +12,23 @@
 //    that never happened.
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { BUCKET, listObjects, objectsOf, folderPrefixesOf, MAX_KEYS_LIMIT } from "./listing.js";
+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, verifySignature, } from "./sigv4.js";
+import { STREAMING_PAYLOAD, STREAMING_PAYLOAD_TRAILER, verifyAgainst, } from "./sigv4.js";
 import { errorXml, listBucketsXml, listObjectsXml } from "./xml.js";
 /** Where the drive is served. Loopback, always — see the note above. */
 export const BIND_ADDRESS = "127.0.0.1";
+/**
+ * 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.";
 /** A random pair, made fresh every time the gateway starts and stored nowhere. */
 export function newCredential() {
     const letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
@@ -46,12 +55,25 @@ function headerOf(req, name) {
     const raw = req.headers[name];
     return Array.isArray(raw) ? raw.join(",") : raw;
 }
-/** The one sentence a write gets when this machine has not agreed to spending. */
-function readOnlyBecause() {
+/** 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",
@@ -66,20 +88,26 @@ async function handle(req, res, options) {
     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 = verifySignature({ method, url, headers: req.headers }, options.credential, options.now?.() ?? Date.now());
+    const verdict = verifyAgainst({ method, url, headers: req.headers }, options.credentials, options.now?.() ?? Date.now());
     if (!verdict.ok) {
-        fail(res, verdict.code === "InvalidAccessKeyId" ? 403 : 403, verdict.code, verdict.message, pathname);
+        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(BUCKET, new Date(0).toISOString());
+        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 (bucket !== BUCKET) {
-        fail(res, 404, "NoSuchBucket", `This gateway serves one bucket, named ${BUCKET}.`, pathname);
+    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
@@ -90,7 +118,7 @@ async function handle(req, res, options) {
         res.end();
         return;
     }
-    const entries = await options.source.entries();
+    const entries = await source.entries();
     if (key === "" && (method === "GET" || method === "HEAD")) {
         const objects = objectsOf(entries);
         const listing = listObjects(objects, folderPrefixesOf(entries), {
@@ -100,7 +128,7 @@ async function handle(req, res, options) {
             after: query.get("continuation-token") ?? query.get("start-after") ?? query.get("marker"),
         });
         const body = listObjectsXml({
-            bucket: BUCKET,
+            bucket,
             prefix: query.get("prefix") ?? "",
             delimiter: query.get("delimiter") ?? "",
             maxKeys: Number(query.get("max-keys") ?? MAX_KEYS_LIMIT) || MAX_KEYS_LIMIT,
@@ -134,7 +162,7 @@ async function handle(req, res, options) {
         }
         const sink = responseSink(res, { headers: objectHeaders(object) });
         try {
-            await options.source.fetch(object, sink);
+            await source.fetch(object, sink);
             options.log?.(`GET ${key} → ${object.size} bytes`);
         }
         catch (error) {
@@ -146,7 +174,7 @@ async function handle(req, res, options) {
         }
         return;
     }
-    const writer = options.source.write;
+    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
@@ -160,13 +188,13 @@ async function handle(req, res, options) {
     };
     if (isMultipartRequest(method, query) && key !== "") {
         if (writer === undefined) {
-            fail(res, 501, "NotImplemented", readOnlyBecause(), pathname);
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
             return;
         }
         const handled = await handleMultipart({
             req,
             res,
-            bucket: BUCKET,
+            bucket,
             key,
             method,
             query,
@@ -180,7 +208,7 @@ async function handle(req, res, options) {
     }
     if (method === "PUT" && key !== "") {
         if (writer === undefined) {
-            fail(res, 501, "NotImplemented", readOnlyBecause(), pathname);
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
             return;
         }
         const declared = headerOf(req, "x-amz-content-sha256");
@@ -213,7 +241,7 @@ async function handle(req, res, options) {
     }
     if (method === "DELETE" && key !== "") {
         if (writer === undefined) {
-            fail(res, 501, "NotImplemented", readOnlyBecause(), pathname);
+            fail(res, 501, "NotImplemented", options.readOnlyBecause ?? readOnlyOnThisMachine(), pathname);
             return;
         }
         const object = objectsOf(entries).find((o) => o.key === key);
@@ -238,8 +266,16 @@ async function handle(req, res, options) {
     }
     fail(res, 501, "NotImplemented", `This gateway does not answer ${method} on that address.`, pathname);
 }
-export function createGateway(options) {
-    return createServer((req, res) => {
+/**
+ * The gateway as a handler, which is the form that listens to nothing.
+ *
+ * ⛔ SEPARATE FROM `createGateway` BECAUSE WHO LISTENS IS NOT THIS FILE'S DECISION. The
+ *    command-line tool binds loopback and says why at the top of this file; a business mounting
+ *    this behind its own TLS has already made that decision, and a library that opened a socket of
+ *    its own would be making it again, differently.
+ */
+export function gatewayHandler(options) {
+    return (req, res) => {
         handle(req, res, options).catch((error) => {
             if (!res.headersSent) {
                 fail(res, 500, "InternalError", error instanceof Error ? error.message : String(error), req.url ?? "/");
@@ -248,5 +284,8 @@ export function createGateway(options) {
                 res.destroy();
             }
         });
-    });
+    };
+}
+export function createGateway(options) {
+    return createServer(gatewayHandler(options));
 }

package/dist/s3/sigv4.d.ts

@@ -13,6 +13,14 @@ export interface IncomingRequest {
 export interface GatewayCredential {
     readonly accessKeyId: string;
     readonly secretAccessKey: string;
+    /**
+     * The only buckets this pair may touch. Absent means every bucket the gateway serves.
+     *
+     * ⛔ IT IS WHAT KEEPS ONE CUSTOMER'S KEY OFF ANOTHER CUSTOMER'S BUCKET. A gateway in front of
+     *    many accounts hands each caller its own pair, and without this every pair would open every
+     *    account the resolver knows.
+     */
+    readonly buckets?: readonly string[] | undefined;
 }
 export type Verified = {
     readonly ok: true;
@@ -22,6 +30,16 @@ export type Verified = {
     readonly code: string;
     readonly message: string;
 };
+/** What `verifyAgainst` answers: the same verdict, plus which of the pairs signed. */
+export type VerifiedAgainst = {
+    readonly ok: true;
+    readonly payloadHash: string;
+    readonly credential: GatewayCredential;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
 /** `k=v&k2=v2` in the order AWS wants: encoded, sorted by key and then by value. */
 export declare function canonicalQuery(rawQuery: string): string;
 interface AuthorizationParts {
@@ -43,4 +61,12 @@ export declare function amzDateToMs(stamp: string | undefined): number | null;
  * skew rule at all, and that rule is the one that stops a captured request being replayed tomorrow.
  */
 export declare function verifySignature(request: IncomingRequest, credential: GatewayCredential, now: number): Verified;
+/**
+ * The whole check, against every pair a gateway answers to: which one signed, and whether it did.
+ *
+ * ⚠ THE THREE REFUSALS ARE DIFFERENT ON PURPOSE. "No authorization header at all", "a key this
+ *   gateway does not have" and "a signature that does not hold" are three different things for
+ *   whoever is reading a client's logs, and none of them says anything about what is in the drive.
+ */
+export declare function verifyAgainst(request: IncomingRequest, credentials: readonly GatewayCredential[], now: number): VerifiedAgainst;
 export {};

package/dist/s3/sigv4.js

@@ -21,6 +21,7 @@ export const MAX_CLOCK_SKEW_MS = 15 * 60 * 1000;
 export const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
 export const STREAMING_PAYLOAD = "STREAMING-AWS4-HMAC-SHA256-PAYLOAD";
 export const STREAMING_PAYLOAD_TRAILER = "STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER";
+/** One refusal, shaped so it satisfies both verdict types — neither of which has an `ok: true`. */
 function refuse(code, message) {
     return { ok: false, code, message };
 }
@@ -166,3 +167,39 @@ export function verifySignature(request, credential, now) {
     }
     return { ok: true, payloadHash };
 }
+/**
+ * Which of a gateway's pairs the request named, without telling the clock how many there are.
+ *
+ * ⛔ EVERY PAIR IS COMPARED AND THE LOOP DOES NOT STOP EARLY. An access key id is not a secret --
+ *    it travels in the header in the clear -- but a scan that returned at the first match would
+ *    take a length of time that says WHERE in the list a key sits, and that is a fact about the
+ *    gateway's customers rather than about the request.
+ */
+function named(credentials, accessKeyId) {
+    const wanted = Buffer.from(accessKeyId, "utf8");
+    let found = null;
+    for (const candidate of credentials) {
+        const id = Buffer.from(candidate.accessKeyId, "utf8");
+        if (id.length === wanted.length && timingSafeEqual(id, wanted))
+            found = candidate;
+    }
+    return found;
+}
+/**
+ * The whole check, against every pair a gateway answers to: which one signed, and whether it did.
+ *
+ * ⚠ THE THREE REFUSALS ARE DIFFERENT ON PURPOSE. "No authorization header at all", "a key this
+ *   gateway does not have" and "a signature that does not hold" are three different things for
+ *   whoever is reading a client's logs, and none of them says anything about what is in the drive.
+ */
+export function verifyAgainst(request, credentials, now) {
+    const auth = parseAuthorization(headerValue(request.headers, "authorization"));
+    if (auth === null)
+        return refuse("AccessDenied", "no AWS Signature Version 4 authorization header");
+    const credential = named(credentials, auth.accessKeyId);
+    if (credential === null) {
+        return refuse("InvalidAccessKeyId", "that access key is not one this gateway answers to");
+    }
+    const verdict = verifySignature(request, credential, now);
+    return verdict.ok ? { ok: true, payloadHash: verdict.payloadHash, credential } : verdict;
+}

package/dist/s3/xml.d.ts

@@ -1,7 +1,14 @@
 /** The five characters XML cannot carry raw. */
 export declare function escapeXml(value: string): string;
 export declare function errorXml(code: string, message: string, resource: string): string;
-export declare function listBucketsXml(bucket: string, createdAt: string): string;
+/**
+ * The answer to `ListBuckets`.
+ *
+ * ⚠ AN EMPTY LIST IS A LEGAL ANSWER AND EVERY CLIENT HANDLES IT. A gateway in front of a
+ *   business's own lookup cannot enumerate that business's customers, and naming none is the true
+ *   answer there — the caller reaches its own bucket by asking for it by name.
+ */
+export declare function listBucketsXml(buckets: readonly string[], createdAt: string): string;
 export declare function initiateUploadXml(bucket: string, key: string, uploadId: string): string;
 export declare function completeUploadXml(bucket: string, key: string, etag: string): string;
 export interface ObjectRow {

package/dist/s3/xml.js

@@ -23,11 +23,20 @@ export function errorXml(code, message, resource) {
     return (`${HEAD}<Error><Code>${escapeXml(code)}</Code><Message>${escapeXml(message)}</Message>` +
         `<Resource>${escapeXml(resource)}</Resource></Error>`);
 }
-export function listBucketsXml(bucket, createdAt) {
+/**
+ * The answer to `ListBuckets`.
+ *
+ * ⚠ AN EMPTY LIST IS A LEGAL ANSWER AND EVERY CLIENT HANDLES IT. A gateway in front of a
+ *   business's own lookup cannot enumerate that business's customers, and naming none is the true
+ *   answer there — the caller reaches its own bucket by asking for it by name.
+ */
+export function listBucketsXml(buckets, createdAt) {
+    const rows = buckets
+        .map((bucket) => `<Bucket><Name>${escapeXml(bucket)}</Name>` +
+        `<CreationDate>${escapeXml(createdAt)}</CreationDate></Bucket>`)
+        .join("");
     return (`${HEAD}<ListAllMyBucketsResult xmlns="${NS}"><Owner><ID>nmts</ID>` +
-        `<DisplayName>nmts</DisplayName></Owner><Buckets><Bucket>` +
-        `<Name>${escapeXml(bucket)}</Name><CreationDate>${escapeXml(createdAt)}</CreationDate>` +
-        `</Bucket></Buckets></ListAllMyBucketsResult>`);
+        `<DisplayName>nmts</DisplayName></Owner><Buckets>${rows}</Buckets></ListAllMyBucketsResult>`);
 }
 export function initiateUploadXml(bucket, key, uploadId) {
     return (`${HEAD}<InitiateMultipartUploadResult xmlns="${NS}">` +

package/dist/s3-gateway.d.ts

@@ -0,0 +1,8 @@
+export { createGateway, gatewayHandler } from "./s3/server.ts";
+export type { DriveSource, DriveWriter, GatewayHandler, GatewayOptions } from "./s3/server.ts";
+export { createDriveSource, fetchObject, placeOf, LIST_CACHE_MS } from "./s3/drive.ts";
+export type { DriveAccount, DriveSourceOptions, ObjectReader } from "./s3/drive.ts";
+export { createStaging } from "./s3/staging.ts";
+export type { Staging, StoreFile } from "./s3/staging.ts";
+export type { GatewayCredential } from "./s3/sigv4.ts";
+export type { DriveObject } from "./s3/listing.ts";

package/dist/s3-gateway.js

@@ -0,0 +1,13 @@
+// The S3 gateway as a library: the server `nmts s3` runs, for somebody else's infrastructure.
+//
+// ⛔ ONE IMPLEMENTATION, AND THIS IS THE DOOR TO IT. A business putting NMTS behind its own storage
+//    adapters needs the protocol this package already speaks, in its own process, in front of
+//    whichever of its customers' accounts a request names. A copy of the server in the SDK would
+//    be a second place for a signature check, a listing and a multipart upload to be got right,
+//    and the copy nobody re-reads is the one that quietly disagrees.
+//
+// ⚠ WHAT IS NOT HERE: the bucket name `nmts s3` uses, the address it binds, and the pair it prints
+//   when it starts. Those are that command's answers to questions a business answers for itself.
+export { createGateway, gatewayHandler } from "./s3/server.js";
+export { createDriveSource, fetchObject, placeOf, LIST_CACHE_MS } from "./s3/drive.js";
+export { createStaging } from "./s3/staging.js";

package/docs/commands/create.md

@@ -3,8 +3,8 @@
 Commands: create
 Tiers: create=high
 
-Signs in with one account's key and creates another, printing the new code once — nothing can
-print it again, because the server stores a one-way verifier and never the NMTS key. This is how a
+Signs in with one account's key and creates another, printing the new NMTS key once — nothing
+can print it again, because the server stores a one-way verifier and never the NMTS key. This is how a
 service that keeps its customers' files in NMTS gives each customer a drive; the first account of
 all has to be made in a browser. It needs a key with `files:write` and a live human check behind
 it, and the server allows two a day and five a week per key.

package/docs/commands/env.md

@@ -8,7 +8,7 @@ gives the same thing to parse. It reports the operating system; whether this is
 container and whether root here is root on the host; whether a file written here can be kept
 private (measured, not guessed); whether there is a terminal and whether a browser could be
 opened; whether an NMTS key and an API key were found and where each came from; if the stored
-code is sealed, whether a passphrase is actually reachable; which agent left a marker here; and
+NMTS key is sealed, whether a passphrase is actually reachable; which agent left a marker here; and
 what the version check last found. The `advice` it returns is written to be repeated to the person
 as-is — do that when something in it is a `warn`.
 

package/docs/commands/extend.md

@@ -15,9 +15,6 @@ nmts extend notes/report.pdf --epochs 4   # how many epochs to add (default 2)
 If the account holds a standing share (`nmts tip`), that share of the WAL just paid goes to the
 developer right after the extension, without a question.
 
-```sh
-```
-
 Both forms print the price in WAL, the chain fee in SUI measured by a dry run of the exact
 transaction (`null` in `--json` when it could not be measured, never 0), and what the wallet
 holds. A wallet short of either exits 4 with the two numbers before anything else; a balance the

package/docs/commands/login.md

@@ -7,7 +7,7 @@ Tiers: login=none · login.plain=high(unsafe-code-storage) · login.env=high(pla
 (`NMTS_API_KEY_FILE`, `NMTS_API_KEY`) with the server, and stores that too. It prints the key's
 public handle and never the key. It does not replace a stored key unless the run says so.
 
-Every later command needs the passphrase, from `NMTS_PASSPHRASE` or a terminal. A sealed code with
+Every later command needs the passphrase, from `NMTS_PASSPHRASE` or a terminal. A sealed key with
 no passphrase in reach is not a usable credential; `nmts env` says which case this machine is in.
 
 Two other shapes exist and both are locked until a person opens them once, at a terminal:

package/docs/commands/logout.md

@@ -5,7 +5,7 @@ Tiers: logout=none
 
 Removes the NMTS key and API key this tool stored on this machine. Nothing on the server
 changes: the key stays valid until revoked (`nmts key revoke`, or the account screen), and the
-account is untouched. A code that came from an environment variable or a file is not touched
+account is untouched. An NMTS key that came from an environment variable or a file is not touched
 either — this only forgets what `nmts login` wrote.
 
 Run it when a machine is handed over or a task is finished on a machine the person does not keep.

package/docs/commands/marks.md

@@ -5,5 +5,5 @@ Tiers: star=none · unstar=none · pin=none · unpin=none · label=none · unlab
 
 Free and reversible; nothing here asks. `star <files>` gathers files in favourites, `pin <files>`
 holds them at the top of their folder, and `label <name> <files>` attaches a word you choose; the
-`un-` forms take each off. A label exists while a file wears it. `label --rename <old> <new>`
+`un-` forms take each off. A label exists while a file has it. `label --rename <old> <new>`
 renames a label on every file that carries it; `unlabel <name> --all` takes it off all of them.

package/docs/commands/mcp.md

@@ -28,6 +28,6 @@ codex    mcp add nmts -- nmts mcp --out /where/files/should/land
 opencode mcp add nmts -- nmts mcp --out /where/files/should/land
 ```
 
-A sealed stored code is opened once, at startup; `nmts mcp` never prompts, so a sealed code with
+A sealed stored NMTS key is opened once, at startup; `nmts mcp` never prompts, so a sealed key with
 no `NMTS_PASSPHRASE` exits 3 at startup rather than hang. Arguments are checked against what each
 tool declares — `"dry_run": "true"` is a refusal, not an upload.