@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/run-log.d.ts

@@ -0,0 +1,78 @@
+/** One request this run made, and what came back. */
+export interface HttpEvent {
+    readonly kind: "http";
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    /** The server's own sentence when it refused. Redacted, like everything else here. */
+    readonly error?: string;
+}
+/** One failure this run reported. */
+export interface ErrorEvent {
+    readonly kind: "error";
+    readonly message: string;
+}
+export type RunEvent = HttpEvent | ErrorEvent;
+/** One line of the log. Short field names: the file has a size cap and this is most of it. */
+export interface RunRecord {
+    /** When the run finished, ISO 8601 in UTC. */
+    readonly t: string;
+    /** The version that ran. A report about a fixed bug is answered by this field alone. */
+    readonly v: string;
+    readonly cmd: string;
+    readonly args: readonly string[];
+    readonly exit: number;
+    readonly ms: number;
+    readonly events: readonly RunEvent[];
+}
+/** Set this to `1` and nothing is written. */
+export declare const NO_RUN_LOG_ENV_VAR = "NMTS_NO_RUN_LOG";
+/**
+ * How much of the log is kept.
+ *
+ * ⛔ A CAP AND NOT A ROTATION SCHEDULE. This file grows by a few hundred bytes per command and is
+ *    read by one command that sends at most 32 KiB of it, so "the newest quarter of a megabyte" is
+ *    both more than anybody attaches and small enough that nobody notices it.
+ */
+export declare const MAX_LOG_BYTES: number;
+/** The most runs `--attach-log` will take. */
+export declare const MAX_ATTACHED_RUNS = 20;
+/** Where the log lives. Inside the tool's own directory, which is already 0700. */
+export declare function runLogPath(): string;
+/** Has the person turned it off? */
+export declare function runLogIsOff(): boolean;
+/**
+ * One request came back. Called from `api.ts`, which is the only place that knows.
+ *
+ * ⚠ The path is recorded as it was requested, query string and all. Anything secret in it is a
+ *   label by the time it lands: `redact` runs over the whole record before it is written.
+ */
+export declare function noteRequest(method: string, path: string, status: number, error?: string): void;
+/** This run failed, with this sentence. Called from the entry point's own catch. */
+export declare function noteFailure(message: string): void;
+/** Throw away what has been collected. For tests, and for a second run inside one process. */
+export declare function forgetRun(): void;
+/**
+ * Which word was the command.
+ *
+ * ⚠ A HEURISTIC, AND IT IS ALLOWED TO BE. This is a record, not a second parser: the real one runs
+ *   inside `run()` and has already thrown by the time a failed command line reaches here. What it
+ *   must not do is pick up the VALUE of an option as the command, which is why it skips them.
+ */
+export declare function commandOf(argv: readonly string[]): string;
+/**
+ * The argument tokens, with the values that must not be written replaced by their labels.
+ *
+ * ⛔ BOTH SPELLINGS. `--message x` and `--message=x` are the same option, and a table that covered
+ *    one of them would write the other into the file.
+ */
+export declare function safeArgs(argv: readonly string[]): string[];
+/**
+ * Write this run down, and forget what was collected.
+ *
+ * Returns nothing and throws nothing: see the header. A run that could not be written is a run
+ * that is missing from a report, which is a smaller problem than a command that failed for it.
+ */
+export declare function recordRun(argv: readonly string[], exit: number, ms: number, now?: Date): void;
+/** The newest `count` runs, oldest first. An unreadable or missing file is no runs. */
+export declare function readRuns(count: number): RunRecord[];

package/dist/run-log.js

@@ -0,0 +1,301 @@
+// What this tool did, written down so that a report can carry it.
+//
+// ⛔ WHY IT EXISTS. The most useful thing in any report is the sequence: the command that was run,
+//    what the server answered, and the sentence it failed with. Asking a person — or an agent — to
+//    reconstruct that from memory produces "it did not work", and asking them to paste a terminal
+//    produces whatever else was on the screen. So the tool keeps its own record, and `nmts support
+//    send --attach-log` is the only thing that reads it.
+//
+// ⛔ IT IS REDACTED ON THE WAY TO THE DISK, NOT ON THE WAY OUT OF IT. A file that held the real
+//    values and was cleaned when it was attached would still be a file full of secrets sitting in
+//    a home directory, and a home directory ends up in a backup, a synced folder and a container
+//    image. `redact.ts` runs before every write here. The attachment runs it again, which costs
+//    nothing and covers a line written by an older version of this tool.
+//
+// ⛔ WHAT IS NEVER IN IT: file contents, the NMTS key, the API key, a passphrase. Not because
+//    they are filtered — because nothing here is ever handed them. What is written is the command
+//    name, the argument tokens, the addresses called, the status numbers, and error sentences.
+//
+// ⛔ WRITING IT MUST NEVER MAKE A COMMAND FAIL. A full disk, a read-only home directory and a
+//    config directory owned by somebody else are all ordinary, and none of them is a reason for
+//    `nmts get` to report a failure it did not have. Every write is inside a `try` that swallows.
+//    ⚠ There is no debug switch in this tool to say so through, so it is silent — which is why
+//      this paragraph is here rather than a line of output.
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { OPTIONS_TAKING_A_VALUE } from "./args.js";
+import { configDir, modesAreEnforced } from "./credentials.js";
+import { redact } from "./redact.js";
+import { VERSION } from "./product.js";
+/** Set this to `1` and nothing is written. */
+export const NO_RUN_LOG_ENV_VAR = "NMTS_NO_RUN_LOG";
+/**
+ * How much of the log is kept.
+ *
+ * ⛔ A CAP AND NOT A ROTATION SCHEDULE. This file grows by a few hundred bytes per command and is
+ *    read by one command that sends at most 32 KiB of it, so "the newest quarter of a megabyte" is
+ *    both more than anybody attaches and small enough that nobody notices it.
+ */
+export const MAX_LOG_BYTES = 256 * 1024;
+/**
+ * How many events one run records.
+ *
+ * ⚠ THE NEWEST ARE KEPT. A run that made two thousand requests failed at the end of them, and the
+ *   last twenty are the ones that say why.
+ */
+const MAX_EVENTS = 100;
+/** The most runs `--attach-log` will take. */
+export const MAX_ATTACHED_RUNS = 20;
+/**
+ * Options whose VALUE must never be written down, and what stands in for it.
+ *
+ * ⛔ `--code`, `--passphrase` AND `--api-key` DO NOT EXIST TODAY, and they are here anyway. The
+ *    rule in `args.ts` is that no option carries a secret; this table is what makes the log safe
+ *    on the day somebody argues for an exception to it.
+ */
+const HIDDEN_VALUES = {
+    "--message": "[message]",
+    "--omit": "[omitted]",
+    "--code": "[account-code]",
+    "--api-key": "[api-key]",
+    "--passphrase": "[secret]",
+    "--token": "[secret]",
+};
+/**
+ * What this run has seen so far.
+ *
+ * ⛔ MODULE STATE, AND IT HAS TO BE. What is being collected is one process's own history, and the
+ *    two places that report into it — the request path and the entry point — have no object in
+ *    common and should not be given one just for this.
+ */
+let collected = [];
+/** Where the log lives. Inside the tool's own directory, which is already 0700. */
+export function runLogPath() {
+    return join(configDir(), "runs.jsonl");
+}
+/** Has the person turned it off? */
+export function runLogIsOff() {
+    return process.env[NO_RUN_LOG_ENV_VAR] === "1";
+}
+function remember(event) {
+    if (runLogIsOff())
+        return;
+    collected.push(event);
+    if (collected.length > MAX_EVENTS)
+        collected = collected.slice(-MAX_EVENTS);
+}
+/**
+ * One request came back. Called from `api.ts`, which is the only place that knows.
+ *
+ * ⚠ The path is recorded as it was requested, query string and all. Anything secret in it is a
+ *   label by the time it lands: `redact` runs over the whole record before it is written.
+ */
+export function noteRequest(method, path, status, error) {
+    remember(error === undefined ? { kind: "http", method, path, status } : { kind: "http", method, path, status, error });
+}
+/** This run failed, with this sentence. Called from the entry point's own catch. */
+export function noteFailure(message) {
+    remember({ kind: "error", message });
+}
+/** Throw away what has been collected. For tests, and for a second run inside one process. */
+export function forgetRun() {
+    collected = [];
+}
+/**
+ * Which word was the command.
+ *
+ * ⚠ A HEURISTIC, AND IT IS ALLOWED TO BE. This is a record, not a second parser: the real one runs
+ *   inside `run()` and has already thrown by the time a failed command line reaches here. What it
+ *   must not do is pick up the VALUE of an option as the command, which is why it skips them.
+ */
+export function commandOf(argv) {
+    const takesValue = new Set(OPTIONS_TAKING_A_VALUE);
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === undefined)
+            continue;
+        if (takesValue.has(token)) {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("-"))
+            continue;
+        return token;
+    }
+    return "";
+}
+/**
+ * The argument tokens, with the values that must not be written replaced by their labels.
+ *
+ * ⛔ BOTH SPELLINGS. `--message x` and `--message=x` are the same option, and a table that covered
+ *    one of them would write the other into the file.
+ */
+export function safeArgs(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === undefined)
+            continue;
+        const hidden = HIDDEN_VALUES[token];
+        if (hidden !== undefined) {
+            out.push(token);
+            if (i + 1 < argv.length) {
+                out.push(hidden);
+                i += 1;
+            }
+            continue;
+        }
+        const equals = token.indexOf("=");
+        if (equals > 0) {
+            const head = token.slice(0, equals);
+            const label = HIDDEN_VALUES[head];
+            if (label !== undefined) {
+                out.push(`${head}=${label}`);
+                continue;
+            }
+        }
+        out.push(redact(token));
+    }
+    return out;
+}
+/** Write one line, creating the file 0600 if it is not there yet. */
+function append(line) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = runLogPath();
+    if (!existsSync(path)) {
+        writeFileSync(path, "", { mode: 0o600 });
+        if (modesAreEnforced())
+            chmodSync(path, 0o600);
+    }
+    appendFileSync(path, line);
+    if (statSync(path).size > MAX_LOG_BYTES)
+        trim(path);
+}
+/**
+ * Drop the oldest whole lines until what is left fits.
+ *
+ * ⛔ WHOLE LINES. Cutting the file at a byte offset leaves a half-written JSON object at the top,
+ *    and a reader that meets one has to decide whether the file is corrupt or merely trimmed.
+ */
+function trim(path) {
+    const lines = readFileSync(path, "utf8").split("\n");
+    const kept = [];
+    let bytes = 0;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i];
+        if (line === undefined || line === "")
+            continue;
+        const size = Buffer.byteLength(line, "utf8") + 1;
+        if (bytes + size > MAX_LOG_BYTES)
+            break;
+        kept.unshift(line);
+        bytes += size;
+    }
+    writeFileSync(path, kept.length === 0 ? "" : `${kept.join("\n")}\n`, { mode: 0o600 });
+}
+/**
+ * Write this run down, and forget what was collected.
+ *
+ * Returns nothing and throws nothing: see the header. A run that could not be written is a run
+ * that is missing from a report, which is a smaller problem than a command that failed for it.
+ */
+export function recordRun(argv, exit, ms, now = new Date()) {
+    if (runLogIsOff()) {
+        forgetRun();
+        return;
+    }
+    const cmd = commandOf(argv);
+    // Everything after the command word is the arguments. A run with no command at all (`--help`,
+    // a bare `nmts`) has no such word, and then every token is an argument.
+    const from = cmd === "" ? 0 : argv.indexOf(cmd) + 1;
+    const record = {
+        t: now.toISOString(),
+        v: VERSION,
+        cmd,
+        args: safeArgs(argv.slice(from)),
+        exit,
+        ms,
+        events: collected.map(redactEvent),
+    };
+    forgetRun();
+    try {
+        append(`${JSON.stringify(record)}\n`);
+    }
+    catch {
+        // Swallowed on purpose. See the header: the log is a convenience and the command is the work.
+    }
+}
+function redactEvent(event) {
+    if (event.kind === "error")
+        return { kind: "error", message: redact(event.message) };
+    const path = redact(event.path);
+    if (event.error === undefined)
+        return { kind: "http", method: event.method, path, status: event.status };
+    return { kind: "http", method: event.method, path, status: event.status, error: redact(event.error) };
+}
+function isEvent(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = Reflect.get(value, "kind");
+    if (kind === "error")
+        return typeof Reflect.get(value, "message") === "string";
+    if (kind !== "http")
+        return false;
+    return (typeof Reflect.get(value, "method") === "string" &&
+        typeof Reflect.get(value, "path") === "string" &&
+        typeof Reflect.get(value, "status") === "number");
+}
+/**
+ * Read a line back, refusing what this version cannot understand.
+ *
+ * ⛔ NARROWED, NOT ASSERTED. The file is written by whichever version of this tool ran last, and
+ *    the one after it may write a field this one has never heard of. A line that does not parse is
+ *    dropped rather than half-read into an attachment.
+ */
+function asRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const at = (name) => Reflect.get(value, name);
+    const args = at("args");
+    const events = at("events");
+    if (typeof at("t") !== "string" || typeof at("cmd") !== "string")
+        return null;
+    if (typeof at("exit") !== "number" || !Array.isArray(args) || !Array.isArray(events))
+        return null;
+    return {
+        t: String(at("t")),
+        v: typeof at("v") === "string" ? String(at("v")) : "",
+        cmd: String(at("cmd")),
+        args: args.filter((a) => typeof a === "string"),
+        exit: Number(at("exit")),
+        ms: typeof at("ms") === "number" ? Number(at("ms")) : 0,
+        events: events.filter(isEvent),
+    };
+}
+/** The newest `count` runs, oldest first. An unreadable or missing file is no runs. */
+export function readRuns(count) {
+    let text;
+    try {
+        text = readFileSync(runLogPath(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const record = asRecord(parsed);
+        if (record !== null)
+            records.push(record);
+    }
+    return count >= records.length ? records : records.slice(records.length - count);
+}

package/dist/s3/listing.d.ts

@@ -0,0 +1,47 @@
+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. */
+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;
+export interface DriveObject extends ObjectRow {
+    /** The entry this key came from, for the reader that follows a HEAD or GET. */
+    readonly entry: ManifestEntry;
+}
+export interface Listing {
+    readonly contents: readonly ObjectRow[];
+    readonly commonPrefixes: readonly string[];
+    readonly truncated: boolean;
+    readonly next: string | null;
+}
+export interface ListQuery {
+    readonly prefix: string;
+    /** Only `/` means anything to S3 clients, but any string is legal and is honoured here. */
+    readonly delimiter: string;
+    readonly maxKeys: number;
+    /** Where to resume: a continuation token, a marker, or start-after. All three are just a key. */
+    readonly after: string | null;
+}
+/**
+ * An ETag that is stable for a file and changes when the file does.
+ *
+ * ⛔ IT ENDS IN `-1` FOR A REASON. S3 clients treat an ETag that looks like a hex digest as the
+ *    MD5 of the object and check downloads against it; this drive has no MD5 of anything -- the
+ *    bytes are encrypted before they leave the machine and the digest it does keep is a different
+ *    function. The `-N` suffix is S3's own mark for "assembled from parts, not an MD5", and every
+ *    client already knows to skip the check when it sees one. Without it a correct download is
+ *    reported as corrupt.
+ */
+export declare function etagOf(entry: ManifestEntry): string;
+/** Every live file in the account, as keys, in the order S3 promises: ascending by key. */
+export declare function objectsOf(entries: readonly ManifestEntry[]): DriveObject[];
+/** Every live folder, as a key ending in the delimiter — see the note at the top of this file. */
+export declare function folderPrefixesOf(entries: readonly ManifestEntry[]): string[];
+/**
+ * Apply prefix, delimiter and paging the way `ListObjects` does.
+ *
+ * The rules are S3's: a key is returned whole unless it holds the delimiter after the prefix, in
+ * which case everything up to and including that delimiter becomes a common prefix and the key
+ * itself is not listed. Common prefixes and keys share one page budget and one cursor.
+ */
+export declare function listObjects(objects: readonly DriveObject[], folders: readonly string[], query: ListQuery): Listing;

package/dist/s3/multipart.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DriveWriter } from "./server.ts";
+/** S3's own ceiling, and a bound on what one client can stage on this machine. */
+export declare const MAX_PARTS = 10000;
+export interface MultipartContext {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly bucket: string;
+    readonly key: string;
+    readonly method: string;
+    readonly query: URLSearchParams;
+    readonly writer: DriveWriter;
+    /** The declared payload hash from the signature, when it was a real digest. */
+    readonly payloadHash: string | null;
+    readonly fail: (status: number, code: string, message: string) => void;
+    readonly log?: ((line: string) => void) | undefined;
+}
+/** True when this request belongs to a multipart upload rather than a plain object call. */
+export declare function isMultipartRequest(method: string, query: URLSearchParams): boolean;
+/** Answer one multipart request. Returns false when the shape is not one this gateway knows. */
+export declare function handleMultipart(context: MultipartContext): Promise<boolean>;

package/dist/s3/response-sink.d.ts

@@ -0,0 +1,8 @@
+import type { ServerResponse } from "node:http";
+import type { PlaintextSink } from "../download-sink.ts";
+export interface ResponseSinkOptions {
+    /** Headers to send with the 200, once the size is known. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** A sink that writes one file into an HTTP response and never leaves a short body looking whole. */
+export declare function responseSink(res: ServerResponse, options: ResponseSinkOptions): PlaintextSink;

package/dist/s3/same-file.d.ts

@@ -0,0 +1,54 @@
+import type { ManifestEntry } from "../shared/lib/drive/manifest-codec.ts";
+import { NmtsError } from "../errors.ts";
+/** What this drive holds at a key, compared with what is arriving. */
+export type SameFile = 
+/** Nothing is at that key. */
+"free"
+/** Byte-for-byte what is already there. Nothing to upload. */
+ | "same"
+/** Something else is there. */
+ | "differs"
+/** Something is there and this drive has no recorded hash for it, so the question cannot be put. */
+ | "unknown";
+/**
+ * Thrown when a key holds a DIFFERENT file. The gateway answers 409 rather than 500: the request
+ * was well formed and the drive declined it, which is what that status is for.
+ */
+export declare class KeyConflict extends NmtsError {
+    constructor(message: string);
+}
+/** True when a thrown value is that refusal, without importing the class into the protocol layer. */
+export declare function isKeyConflict(error: unknown): boolean;
+/** The SHA-256 of a file on this machine, read in pieces so a large one costs no memory. */
+export declare function hashOfFile(path: string): Promise<Uint8Array>;
+/**
+ * Open the hash this drive recorded for a file, with the account's own key.
+ *
+ * `null` when the entry carries none — files stored before the field existed do not have one, and
+ * that is a real state rather than an error. A hash that is present and will not open IS an error:
+ * it means the file list was written by another account or altered, and answering "no hash" there
+ * would quietly turn a tampered list into an upload.
+ */
+export declare function recordedHash(accountCode: string, contentHashCt: string | undefined): Promise<Uint8Array | null>;
+/**
+ * The whole question, for one key: what does this drive hold there, and is the file on disk it?
+ *
+ * ⛔ IT IS ONE FUNCTION SO THERE IS ONE ANSWER. Both ways of uploading — a single PUT, and pieces
+ *    staged and joined — reach the drive through the same store, and this is what that store asks.
+ *    Written at the two call sites instead, the two would differ the first time one of them
+ *    changed, and the difference would show up only above whatever size the client switches at.
+ *
+ * ⚠ THE FILE IS HASHED ONLY WHEN THE KEY IS TAKEN. An upload onto a free key is the common case
+ *   and pays nothing for this.
+ */
+export declare function verdictForKey(entries: readonly ManifestEntry[], key: string, accountCode: string, path: string): Promise<SameFile>;
+/** The verdict, given what is on record and what arrived. */
+export declare function compare(recorded: Uint8Array | null | undefined, arriving: Uint8Array): SameFile;
+/**
+ * What to tell a client whose upload was declined.
+ *
+ * ⛔ IT NAMES WHICH OF THE TWO HAPPENED. "There is already a file there" is the same sentence for a
+ *    file that changed and for a file this drive cannot compare, and the two need different things
+ *    from the person reading the log.
+ */
+export declare function refusalFor(verdict: "differs" | "unknown", key: string): KeyConflict;

package/dist/s3/server.d.ts

@@ -0,0 +1,58 @@
+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";
+/** 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;
+export declare function createGateway(options: GatewayOptions): Server;

package/dist/s3/server.js

@@ -1,7 +1,7 @@
 // The gateway itself: an S3 request in, this account's drive out.
 //
-// ⛔ LOOPBACK ONLY, AND NO OPTION TO CHANGE IT. The machine running this already holds the account
-//    code, and one signature is all that stands between a request and every file in the account.
+// ⛔ LOOPBACK ONLY, AND NO OPTION TO CHANGE IT. The machine running this already holds the NMTS
+//    key, and one signature is all that stands between a request and every file in the account.
 //    Bound to an address other people can reach, that one signature becomes the whole lock on the
 //    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.

package/dist/s3/sigv4.d.ts

@@ -0,0 +1,46 @@
+/** How far a request's own timestamp may sit from ours before it is refused. AWS uses the same. */
+export declare const MAX_CLOCK_SKEW_MS: number;
+/** The literals a client may put in `x-amz-content-sha256` instead of a hex digest. */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+export declare const STREAMING_PAYLOAD = "STREAMING-AWS4-HMAC-SHA256-PAYLOAD";
+export declare const STREAMING_PAYLOAD_TRAILER = "STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER";
+export interface IncomingRequest {
+    readonly method: string;
+    /** Raw request target, path and query together, exactly as it came off the wire. */
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+export interface GatewayCredential {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+}
+export type Verified = {
+    readonly ok: true;
+    readonly payloadHash: string;
+} | {
+    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 {
+    readonly accessKeyId: string;
+    readonly date: string;
+    readonly region: string;
+    readonly service: string;
+    readonly signedHeaders: readonly string[];
+    readonly signature: string;
+}
+/** Pull apart `AWS4-HMAC-SHA256 Credential=…, SignedHeaders=…, Signature=…`. */
+export declare function parseAuthorization(header: string | undefined): AuthorizationParts | null;
+/** `20260824T232759Z` → epoch milliseconds, or null if it is not that shape. */
+export declare function amzDateToMs(stamp: string | undefined): number | null;
+/**
+ * Rebuild the string the client signed and check that the signature matches.
+ *
+ * The clock is passed in rather than read here: a test that cannot choose "now" cannot check the
+ * 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;
+export {};

package/dist/s3/sigv4.js

@@ -1,7 +1,7 @@
 // AWS Signature Version 4, the verifying half.
 //
 // ⛔ WHY A LOCAL SERVER CHECKS SIGNATURES AT ALL. This gateway listens on the loopback address of a
-//    machine that already holds an account code, and a request that reaches it can upload, read and
+//    machine that already holds an NMTS key, and a request that reaches it can upload, read and
 //    delete that account's files. "It is only local" is not an argument: every other program on the
 //    machine, and every page a browser on it loads, can also reach 127.0.0.1. The signature is the
 //    one thing that separates the tool the person started from everything else running as them.

package/dist/s3/staging.d.ts

@@ -0,0 +1,10 @@
+import { type Readable } from "node:stream";
+/** What the staging does with a finished file: store it in the drive at that key. */
+export type StoreFile = (key: string, path: string) => Promise<void>;
+export interface Staging {
+    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 declare function createStaging(root: string, store: StoreFile): Staging;