@needmoretruth/nmts-cli 0.36.3 → 0.38.1

package/dist/s3/server.d.ts

@@ -1,58 +1,20 @@
-import { type Server } 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";
-import { type DriveObject } from "./listing.ts";
-import { type GatewayCredential } from "./sigv4.ts";
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { GatewayOptions } from "./contract.ts";
+import type { GatewayCredential } from "./sigv4.ts";
+export type { DriveSource, DriveWriter, GatewayOptions } from "./contract.ts";
 /** Where the drive is served. Loopback, always — see the note above. */
 export declare const BIND_ADDRESS = "127.0.0.1";
-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 {
-    readonly credential: GatewayCredential;
-    readonly source: DriveSource;
-    /** 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;
-}
 /** 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

@@ -6,18 +6,12 @@
 //    account -- and the key it checks was printed on somebody's terminal. This is the same call the
 //    rest of the system made on 2026-08-20 when every container port was pulled back to loopback.
 //
-// ⛔ 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.
+// ⚠ WHAT EACH REQUEST IS ANSWERED WITH IS IN `routes.ts`, and what a caller has to hand this in
+//   `contract.ts`. What is here is the socket and the pair: the two things that decide who can
+//   reach the drive at all.
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { BUCKET, 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 { errorXml, listBucketsXml, listObjectsXml } from "./xml.js";
+import { fail, handle } from "./routes.js";
 /** Where the drive is served. Loopback, always — see the note above. */
 export const BIND_ADDRESS = "127.0.0.1";
 /** A random pair, made fresh every time the gateway starts and stored nowhere. */
@@ -29,217 +23,16 @@ export function newCredential() {
         id += letters[byte % letters.length] ?? "A";
     return { accessKeyId: id.slice(0, 20), secretAccessKey: randomBytes(30).toString("base64url") };
 }
-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 when this machine has not agreed to spending. */
-function readOnlyBecause() {
-    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.");
-}
-function objectHeaders(object) {
-    return {
-        "content-type": "application/octet-stream",
-        "last-modified": new Date(object.entry.updatedAt).toUTCString(),
-        etag: object.etag,
-        "accept-ranges": "none",
-    };
-}
-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 = verifySignature({ method, url, headers: req.headers }, options.credential, options.now?.() ?? Date.now());
-    if (!verdict.ok) {
-        fail(res, verdict.code === "InvalidAccessKeyId" ? 403 : 403, verdict.code, verdict.message, pathname);
-        return;
-    }
-    const { bucket, key } = splitPath(pathname);
-    if (pathname === "/" && (method === "GET" || method === "HEAD")) {
-        const body = listBucketsXml(BUCKET, 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);
-        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 options.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: 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 options.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 = options.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", readOnlyBecause(), pathname);
-            return;
-        }
-        const handled = await handleMultipart({
-            req,
-            res,
-            bucket: 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", readOnlyBecause(), 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", readOnlyBecause(), 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);
-}
-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 +41,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.

package/docs/commands/put.md

@@ -3,8 +3,8 @@
 Commands: put
 Tiers: put=medium · put.wallet=high(wallet)
 
-This is the command that spends. The price is one credit per started mebibyte, printed before the
-upload starts. In the default mode it asks first (answer at the terminal, or run with `--yes`);
+`put` spends credits: one per started mebibyte, and the price is printed before the upload
+starts. In the default mode it asks first (answer at the terminal, or run with `--yes`);
 in an auto mode it runs when you judge it is what the person wants.
 
 ```sh

package/docs/commands/wallet.md

@@ -74,12 +74,10 @@ Three coin subcommands sign, and every signed transaction is irreversible by any
   explorer. It is outside the wallet unlock and its ceiling. A standing share of every WAL
   payment is `nmts tip`, not a gift on its own.
 
-One more reads the gifts back, and one flag on it publishes a name:
-
-- `wallet hall` prints the gift hall of fame — the developer, then the ten largest senders as read
-  from the public chain, with the rest of the list at nmts.me/hall; reading it signs nothing and
-  needs no NMTS key. `--name <name>` (1 to 24 characters, no links, not an address) signs a
-  short message with the wallet this account pays from — the wallet a gift left from — so the
-  server shows that name beside its address, and `--remove` puts the entry back to a shortened
-  address. Reading which wallet that is opens the file list, so naming yourself needs an API key
-  where reading the hall needs none.
+`wallet hall` prints the gift hall of fame — the developer, then the ten largest senders as read
+from the public chain, with the rest of the list at nmts.me/hall; reading it signs nothing and
+needs no NMTS key. `--name <name>` (1 to 24 characters, no links, not an address) signs a
+short message with the wallet this account pays from — the wallet a gift left from — so the
+server shows that name beside its address, and `--remove` puts the entry back to a shortened
+address. Reading which wallet that is opens the file list, so naming yourself needs an API key
+where reading the hall needs none.

package/docs/commands/whoami.md

@@ -3,10 +3,10 @@
 Commands: whoami
 Tiers: whoami=none · whoami.reveal=high(reveal)
 
-Prints the account id the stored code belongs to, offline, with no server call. `--json` gives it
+Prints the account id the stored NMTS key belongs to, offline, with no server call. `--json` gives it
 to a program.
 
 `--reveal` prints the NMTS key itself. An agent never needs this — the tool already holds the
-code — so it is locked until a person runs `nmts unlock reveal` at a terminal, and then asked about
+key — so it is locked until a person runs `nmts unlock reveal` at a terminal, and then asked about
 on every run in every mode but skip-permissions. Never write the NMTS key anywhere it can be read
 again: a log, a commit, a file, a message. It is the only key to the account and cannot be rotated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needmoretruth/nmts-cli",
-  "version": "0.36.3",
+  "version": "0.38.1",
   "description": "Command-line and MCP access to NMTS (NeedMoreTruthStorage, https://nmts.me): open-source, end-to-end encrypted storage on the Walrus network. No fee to NMTS; you pay the network from your own wallet. For people and for their agents.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -77,6 +77,14 @@
       "types": "./dist/drive-paths.d.ts",
       "default": "./dist/drive-paths.js"
     },
+    "./drive-edit": {
+      "types": "./dist/drive-edit.d.ts",
+      "default": "./dist/drive-edit.js"
+    },
+    "./s3-gateway": {
+      "types": "./dist/s3-gateway.d.ts",
+      "default": "./dist/s3-gateway.js"
+    },
     "./upload-file": {
       "types": "./dist/upload-file.d.ts",
       "default": "./dist/upload-file.js"