@needmoretruth/nmts-sdk 0.1.1

package/dist/put-wallet.js

@@ -0,0 +1,116 @@
+// One file in, bought with the account's OWN WALLET: the same seal-push-record path as the credit
+// rail, with the storage bought on the Sui chain instead of out of the treasury. The shared types,
+// the shared spellings and the credit rail itself are `put.ts`.
+//
+// ⛔ THIS IS THE FILE THAT SIGNS. `pay: "wallet"` spends WAL for the storage and SUI for the
+//    relay's tip and the chain fees, out of the wallet this account pays from — `wallet` when the
+//    caller named one, and otherwise the account's own number. None of it comes back and there is
+//    no agreement step — a library has nobody to ask — so calling `put` IS the agreement, exactly
+//    as the credit rail says.
+//
+// ⛔ THE ORDER IS THE SAFETY, AND IT IS NOT THIS FILE'S. The price, both balances and a shortfall
+//    all come before the first signature, and that order is the command-line tool's `walletPut`,
+//    whose chain, signers and wire are handed in as seams. A second copy of it here would be a
+//    second thing to keep right about money that cannot be got back.
+//
+// ⛔ NO STANDING GIFT AND NO SPENDING LEDGER. Both are a person's act on one machine under one
+//    agreement; a library that kept either would be deciding for a caller who never asked it to.
+import { folderIdFor, loadCrypto, walletPut, } from "@needmoretruth/nmts-cli";
+import { readList } from "./list.js";
+import { DEFAULT_PART_BYTES, destinationOf, pathOf, requireName, } from "./put.js";
+import { withAccount } from "./session.js";
+import { requireWalletIndex } from "./wallets.js";
+/**
+ * Seal, buy with the account's OWN WALLET, push and record one file.
+ *
+ * ⛔ NOBODY IS ASKED, BECAUSE THERE IS NOBODY TO ASK. The command-line tool prints the review and
+ *    holds it against a standing wallet agreement; in a library the code that can spend is already
+ *    in this process and the caller wrote the call, so calling this IS the agreement — exactly as
+ *    the credit rail already says. What does not change is the order: the price, the balances and
+ *    a shortfall all come before the first signature.
+ */
+export async function putSourceWithWallet(opened, source, name, options, seams = {}) {
+    requireName(name);
+    const destination = destinationOf(options.to);
+    // ⛔ A NAMED WALLET IS JUDGED BEFORE ANYTHING IS OPENED: a number that is not one is a call to
+    //    fix, and refusing it here costs nobody the opening of a business's sealed store.
+    const named = options.wallet === undefined ? null : requireWalletIndex(options.wallet);
+    // ⛔ ONE BORROW FOR THE WHOLE RAIL. The code seals the file AND derives the wallet that signs,
+    //    so `WalletPutContext.code` is the same borrowed copy the list was opened with rather than a
+    //    second opening of a business's store partway through a call that is about to spend.
+    return withAccount(opened, async (held) => {
+        const { entries, padding: rule, activeWallet } = await readList(held);
+        const parentId = folderIdFor(options.to, entries, "Nothing was sent and nothing was signed.");
+        const outcome = await walletPut({
+            code: held.code,
+            apiKey: held.apiKey,
+            server: held.server,
+            network: held.network,
+            accountId: held.accountId,
+            crypt: await loadCrypto(),
+            partSize: options.partSize ?? DEFAULT_PART_BYTES,
+            rule,
+            // ⛔ RESOLVED BEFORE ANYTHING IS PRICED, out of the list this call just read — the address
+            //    the review names has to be the address that signs, and asking for the number later
+            //    would let those two differ.
+            wallet: named ?? activeWallet,
+        }, { source, name, parentId, destination }, {
+            ...seams,
+            epochs: options.epochs,
+            storage: options.storage,
+            dryRun: options.dryRun,
+            onStep: options.onStep,
+            onProgress: options.onProgress,
+        });
+        const { review } = outcome;
+        if (outcome.kind === "review") {
+            return {
+                dryRun: true,
+                paid: "wallet",
+                name,
+                path: pathOf(destination, name),
+                bytes: review.bytes,
+                sealedBytes: review.sealedBytes,
+                parts: review.parts,
+                credits: 0,
+                wal: review.budget.walNeededFrost.toString(),
+                sui: review.budget.suiNeededMist.toString(),
+                epochs: review.epochs,
+                endEpoch: review.endEpoch,
+                storage: storageOf(review),
+                wallet: {
+                    address: review.budget.address,
+                    wal: review.budget.walFrost === null ? null : review.budget.walFrost.toString(),
+                    sui: review.budget.suiMist === null ? null : review.budget.suiMist.toString(),
+                },
+                shortfall: review.budget.shortfall,
+            };
+        }
+        return {
+            dryRun: false,
+            paid: "wallet",
+            id: outcome.itemId,
+            name: outcome.savedAs,
+            path: pathOf(destination, outcome.savedAs),
+            bytes: review.bytes,
+            sealedBytes: review.sealedBytes,
+            parts: review.parts,
+            credits: 0,
+            // ⛔ A RESUMED RUN SIGNED NOTHING NOW, so it spent nothing now — the same answer `credits`
+            //    gives on the other rail, and what a caller adding up a month of uploads needs it to say.
+            wal: outcome.resumed ? "0" : review.budget.walNeededFrost.toString(),
+            sui: outcome.resumed ? "0" : review.budget.suiNeededMist.toString(),
+            endEpoch: review.endEpoch,
+            resumed: outcome.resumed,
+            renamed: outcome.savedAs !== name,
+            fileListVersion: outcome.fileListVersion,
+        };
+    });
+}
+/** The storage choice without the chain row it was picked from — the numbers a caller can use. */
+function storageOf(review) {
+    const { storage } = review;
+    return storage.kind === "buy"
+        ? { kind: "buy" }
+        : { kind: "reuse", objectId: storage.objectId, cutToBytes: storage.cutToBytes, leftoverBytes: storage.leftoverBytes };
+}

package/dist/put.d.ts

@@ -0,0 +1,151 @@
+import { type BlobProtocol, type FileUploadStep, type PlaintextSource, type UploadApi } from "@needmoretruth/nmts-cli";
+import { type Opened } from "./session.ts";
+/** 64 MiB — the same part size the command-line tool uses when nobody says otherwise. */
+export declare const DEFAULT_PART_BYTES: number;
+/** The two things a credit-paid upload talks to: the server that sells storage, the relay. */
+export interface UploadRail {
+    api: UploadApi;
+    protocol: BlobProtocol;
+    relayUrl: string;
+    /** The storage network's current epoch, when it could be read. */
+    currentEpoch: number | null;
+}
+export interface PutOptions {
+    /** The name it gets in the account. Defaults to the local file's own name. Required for bytes. */
+    name?: string | undefined;
+    /** Destination folder as `list()` prints it, `photos/2026`. The top of the account when absent. */
+    to?: string | undefined;
+    /**
+     * How much of the file goes into one part, in bytes. Defaults to 64 MiB.
+     *
+     * Bigger parts mean fewer reservations against the account's daily allowance; smaller parts
+     * mean less memory and a shorter piece of work to lose when something goes wrong.
+     */
+    partSize?: number | undefined;
+    /**
+     * Which money buys the storage: the account's credits (the default), or the account's own
+     * wallet — WAL for the storage and SUI for the relay's tip and the chain fees.
+     */
+    pay?: "credits" | "wallet" | undefined;
+    /**
+     * `pay: "wallet"` only: which of this key's wallets pays, by index. Absent = the one the account
+     * pays from. Naming one here is for this upload alone and writes nothing —
+     * `setActiveWallet()` is how an account changes which wallet pays.
+     */
+    wallet?: number | undefined;
+    /** `pay: "wallet"` only: how many of the storage network's epochs to buy. Default 2. */
+    epochs?: number | undefined;
+    /**
+     * `pay: "wallet"` only: use a storage resource the wallet already holds instead of buying new
+     * storage. `fit` cuts the smallest one that fits and leaves the rest free, `whole` binds one
+     * whole, and an object id names one. A held resource serves a one-part file.
+     */
+    storage?: string | undefined;
+    /** Work out what it would cost and stop. Nothing is sealed, signed, sent or spent. */
+    dryRun?: boolean | undefined;
+    /** Told about each step as it starts, so a long upload visibly moves. */
+    onStep?: ((step: FileUploadStep) => void) | undefined;
+    /** Told as sealed bytes leave for the relay — the honest measure of an upload's progress. */
+    onProgress?: ((sent: number, total: number) => void) | undefined;
+}
+/** Where a wallet-paid part's storage came from. */
+export type PutStorage = {
+    kind: "buy";
+} | {
+    kind: "reuse";
+    objectId: string;
+    /** Bytes the resource was cut down to first, or null when it was bound whole. */
+    cutToBytes: number | null;
+    /** What the resource holds beyond this file — left free by a cut, bound with it when whole. */
+    leftoverBytes: number;
+};
+/** What every answer about one upload says, whoever paid and whether or not it ran. */
+interface PutFacts {
+    /** The name it got — numbered, `report (2).pdf`, if the requested one was taken. */
+    name: string;
+    /** Full path in the account. */
+    path: string;
+    /** Plaintext bytes. */
+    bytes: number;
+    /** Bytes the storage network holds for it, padding and sealing included. */
+    sealedBytes: number;
+    parts: number;
+}
+interface Uploaded extends PutFacts {
+    dryRun: false;
+    /** The server's id for the file. */
+    id: string;
+    resumed: boolean;
+    renamed: boolean;
+    /** The file-list version this write produced. */
+    fileListVersion: number;
+}
+export interface CreditsPut extends Uploaded {
+    paid: "credits";
+    /** Credits this call spent. 0 when it finished an upload an earlier call had already paid for. */
+    credits: number;
+}
+export interface WalletPut extends Uploaded {
+    paid: "wallet";
+    /** Always 0: a wallet-paid upload takes no credits from the account. */
+    credits: 0;
+    /**
+     * WAL that left the wallet, in FROST — the chain's smallest unit, as a decimal string because
+     * a JSON number would round it. "0" when this call resumed one an earlier call paid for.
+     */
+    wal: string;
+    /** SUI that left the wallet, in MIST: the relay's tip plus the measured register fees. */
+    sui: string;
+    /** The epoch the storage runs to. */
+    endEpoch: number;
+}
+/** What `put()` answers. Narrow on `paid` to read the numbers of one rail. */
+export type PutResult = CreditsPut | WalletPut;
+interface Reviewed extends PutFacts {
+    /** Nothing was sealed, signed, sent or spent: this is what it would have cost. */
+    dryRun: true;
+}
+export interface CreditsReview extends Reviewed {
+    paid: "credits";
+    credits: number;
+}
+export interface WalletReview extends Reviewed {
+    paid: "wallet";
+    credits: 0;
+    /** WAL it would spend, in FROST, as a decimal string. */
+    wal: string;
+    /** SUI it would spend, in MIST: the relay's tip plus the measured register fees. */
+    sui: string;
+    epochs: number;
+    endEpoch: number;
+    storage: PutStorage;
+    /** The paying wallet: its address, and what it holds — null for a balance the chain would not say. */
+    wallet: {
+        address: string;
+        wal: string | null;
+        sui: string | null;
+    };
+    /**
+     * Set when the wallet is short: the sentence naming both numbers. A real `put()` with these
+     * numbers would throw rather than sign.
+     */
+    shortfall: string | null;
+}
+/** What `put({ dryRun: true })` answers. */
+export type PutReview = CreditsReview | WalletReview;
+/** Bytes already in memory, read as a source. Copies each piece it yields. */
+export declare function bytesSource(bytes: Uint8Array): PlaintextSource;
+/** The reservation key names the destination as typed; this is the one spelling of "as typed". */
+export declare function destinationOf(to: string | undefined): string;
+export declare function pathOf(destination: string, name: string): string;
+export declare function requireName(name: string): void;
+/**
+ * Seal, buy with CREDITS, push and record one file.
+ *
+ * `rail` is asked for after the price is known, because the relay's timeout is sized to the
+ * sealed length, and a rail built before the plan would have to guess it.
+ */
+export declare function putSource(opened: Opened, source: PlaintextSource, name: string, options: PutOptions, rail: (sealedBytes: number) => Promise<UploadRail>): Promise<CreditsPut | CreditsReview>;
+/** A file path's own name, for `put("/tmp/x/report.pdf")`. */
+export declare function nameOf(localPath: string): string;
+export {};

package/dist/put.js

@@ -0,0 +1,168 @@
+// One file in, bought with the account's CREDITS: sealed here, its storage bought, the sealed bytes
+// pushed, and the file named in the account's sealed list. The other rail — the account's own
+// wallet — is `put-wallet.ts`; everything else about an upload is the same on both, and the answers
+// both rails give live here because `put()` returns one of them and a caller reads them as one shape.
+//
+// ⛔ THE ONLY THING IN THIS PACKAGE THAT SPENDS, WITH ITS OTHER RAIL. Credits are storage a donation
+//    pool has already paid the network for. Neither rail's money comes back. There is no agreement
+//    step here as there is in the command-line tool — a library has nobody to ask — so calling `put`
+//    IS the agreement, and the README says so before it says how.
+//
+// ⛔ THE PLAINTEXT NEVER LEAVES THIS PROCESS. What goes to the storage network is the sealed
+//    stream; what goes to the server is its length and a name that is itself inside the sealed
+//    list. The machinery that keeps a half-finished upload from becoming money that bought nothing
+//    is the command-line tool's own (`uploadFile`); this file only wires it.
+//
+// ⛔ THE RAIL IS A PARAMETER. The server and the relay are handed in, so a test drives this exact
+//    code against fakes rather than a second copy of the order that decides when money moves.
+//
+// ⛔ NO SPENDING LEDGER. The command-line tool holds one, because a ledger counts what one machine
+//    signed under one agreement. A library that kept one would be deciding for a caller who never
+//    asked it to.
+import { basename } from "node:path";
+import { addEntry, clearItemRecord, clearReservation, CREDIT_BYTES, folderIdFor, NmtsError, partKeysOf, planAndPrice, setTrashed, UPLOAD_EPOCHS, uploadFile, } from "@needmoretruth/nmts-cli";
+import { readList } from "./list.js";
+import { withAccount, withDataKey } from "./session.js";
+/** 64 MiB — the same part size the command-line tool uses when nobody says otherwise. */
+export const DEFAULT_PART_BYTES = 64 * 2 ** 20;
+/** Bytes already in memory, read as a source. Copies each piece it yields. */
+export function bytesSource(bytes) {
+    return {
+        size: bytes.length,
+        async *read(offset, length) {
+            const end = Math.min(offset + length, bytes.length);
+            const chunk = 4 * 2 ** 20;
+            for (let at = offset; at < end; at += chunk) {
+                yield bytes.slice(at, Math.min(at + chunk, end));
+            }
+        },
+    };
+}
+/** The reservation key names the destination as typed; this is the one spelling of "as typed". */
+export function destinationOf(to) {
+    return (to ?? "").replace(/^\.?\//, "").replace(/\/$/, "");
+}
+export function pathOf(destination, name) {
+    return destination === "" ? name : `${destination}/${name}`;
+}
+export function requireName(name) {
+    if (name.length === 0) {
+        throw new NmtsError("The file has no name.", {
+            exitCode: 2,
+            nextStep: "Nothing was sent. Pass `name` — bytes in memory have no name of their own.",
+        });
+    }
+}
+/**
+ * ⛔ AN OPTION THAT WOULD BE IGNORED IS A REFUSAL, not a shrug. `epochs` and `storage` buy a term
+ *    and a resource on the chain, and `wallet` says which wallet signs for them; credits buy a
+ *    fixed term from the treasury, hold no resource and are signed for by nobody, so a caller who
+ *    asked for any of the three and paid with credits did not get what they asked for.
+ */
+function refuseWalletOnlyOptions(options) {
+    const asked = options.wallet !== undefined
+        ? "wallet"
+        : options.epochs !== undefined
+            ? "epochs"
+            : options.storage !== undefined
+                ? "storage"
+                : null;
+    if (asked === null)
+        return;
+    throw new NmtsError(`\`${asked}\` only applies with \`pay: "wallet"\`.`, {
+        exitCode: 2,
+        nextStep: `Nothing was sent and nothing was charged. Add \`pay: "wallet"\` to buy the storage from the account's own wallet, or drop \`${asked}\` to pay with credits.`,
+    });
+}
+/**
+ * Seal, buy with CREDITS, push and record one file.
+ *
+ * `rail` is asked for after the price is known, because the relay's timeout is sized to the
+ * sealed length, and a rail built before the plan would have to guess it.
+ */
+export async function putSource(opened, source, name, options, rail) {
+    requireName(name);
+    refuseWalletOnlyOptions(options);
+    const destination = destinationOf(options.to);
+    const partSize = options.partSize ?? DEFAULT_PART_BYTES;
+    // ⛔ THE REFUSALS ABOVE COST NO KEY. Everything from here needs the account's code, and this is
+    //    the one place this call borrows it — whoever holds it, and however many requests follow.
+    return withAccount(opened, async (held) => {
+        // ⛔ THE LIST IS READ BEFORE THE PRICE IS QUOTED. The rounding rule that hides a file's true size
+        //    lives in the sealed list, it changes how many bytes are stored, and so it changes the price.
+        //    And it is read before anything is sealed or paid for, so a destination that does not exist
+        //    stops the upload while there is still nothing to lose.
+        const { entries, padding: rule } = await readList(held);
+        const parentId = folderIdFor(options.to, entries, "Nothing was sent and nothing was charged.");
+        const { plan, sealedBytes, credits } = planAndPrice(source.size, partSize, rule);
+        if (options.dryRun === true) {
+            // ⛔ Nothing above this line spent anything and nothing below it runs. The price is arithmetic
+            //    on the file's size and the account's rounding rule — the same arithmetic the server does.
+            return { dryRun: true, paid: "credits", name, path: pathOf(destination, name), bytes: source.size, sealedBytes, parts: plan.length, credits };
+        }
+        const built = await rail(sealedBytes);
+        const result = await withDataKey(held.code, (crypt, dataKey) => uploadFile({
+            api: built.api,
+            protocol: built.protocol,
+            crypt,
+            dataKey,
+            source,
+            name,
+            parentId,
+            destination,
+            relayUrl: built.relayUrl,
+            epochs: UPLOAD_EPOCHS,
+            currentEpoch: built.currentEpoch,
+            partSize,
+            padding: { rule, unitBytes: CREDIT_BYTES },
+            ...(options.onStep === undefined ? {} : { onStep: options.onStep }),
+        }));
+        const now = Date.now();
+        // ⛔ FROM `result.entry`, NOT FROM THIS CALL. The key that opens the stored bytes is the key they
+        //    were sealed with, which on a resume belongs to the call that sealed them.
+        const added = await addEntry({
+            server: held.server,
+            apiKey: held.apiKey,
+            code: held.code,
+            accountId: held.accountId,
+            entry: {
+                id: result.itemId,
+                parentId,
+                kind: 1,
+                name: result.entry.name,
+                size: result.entry.plaintextLen,
+                createdAt: now,
+                updatedAt: now,
+                dekWrapped: result.entry.dekWrapped,
+                contentHashCt: result.entry.contentHashCt,
+            },
+        });
+        // ⛔ ONLY NOW, AND EVERY PART. Until the entry is in the list the file is paid for and invisible,
+        //    and the records are what let a second call finish the job without spending again.
+        clearItemRecord(result.fileKey);
+        for (const record of partKeysOf(result.fileKey, result.parts))
+            clearReservation(record);
+        // The displaced file, when this machine is set to overwrite, goes to the trash on the server
+        // only after the new one is in the list — until then the caller still had the file they started with.
+        if (added.replaced)
+            await setTrashed(held.server, held.apiKey, added.replaced.id, true);
+        return {
+            dryRun: false,
+            paid: "credits",
+            id: result.itemId,
+            name: added.name,
+            path: pathOf(destination, added.name),
+            bytes: source.size,
+            sealedBytes,
+            parts: plan.length,
+            credits: result.resumed ? 0 : credits,
+            resumed: result.resumed,
+            renamed: added.name !== name,
+            fileListVersion: added.seq,
+        };
+    });
+}
+/** A file path's own name, for `put("/tmp/x/report.pdf")`. */
+export function nameOf(localPath) {
+    return basename(localPath);
+}

package/dist/root.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Which process holds the key.
+ *
+ * A third, `gateway` — the key inside an S3-compatible gateway process a business runs — is not
+ * built yet. When it is, it is another implementation in this file and another row in the test
+ * registry, and no verb moves.
+ */
+export type RootMode = "device" | "managed";
+/**
+ * Who the server is asked to believe is calling.
+ *
+ * One kind for now. A business acting for a person it has delegation for is `{ kind: "delegation";
+ * token: string }`, and it arrives with the Platform API rather than before it.
+ */
+export type Identity = {
+    kind: "api-key";
+    apiKey: string;
+};
+/** Something that holds one account's NMTS key and will lend it for the length of one piece of work. */
+export interface Root {
+    readonly mode: RootMode;
+    readonly identity: Identity;
+    withCode<T>(use: (code: string) => Promise<T>): Promise<T>;
+}
+/** What the device root takes. Two secrets, because they do two different jobs — see the README. */
+export interface Credentials {
+    /** Opens the files and derives the wallet. Never leaves this process. */
+    accountCode: string;
+    /** Makes the server answer. Opens nothing; can be revoked on the account screen. */
+    apiKey: string;
+}
+/** What the managed root takes: a way to open the sealed code, and the key the server answers to. */
+export interface ManagedCredentials {
+    /**
+     * Opens the account's code out of wherever this business sealed it, and answers it.
+     *
+     * Called once for each call this package makes on the account, and never for anything else. How
+     * the code is sealed — a cloud key service, a master key, a hardware module — is the business's
+     * own decision and this package does not reach into it.
+     */
+    openCode: () => Promise<string>;
+    /** Makes the server answer. Opens nothing; can be revoked on the account screen. */
+    apiKey: string;
+}
+/**
+ * A credential is text or it is a refusal.
+ *
+ * ⛔ THE REFUSAL NEVER CONTAINS THE VALUE. It names what was missing and what to do; a caller's log
+ *    is not a place an account code should be able to reach.
+ */
+export declare function requireText(value: unknown, what: string, nextStep: string): string;
+/**
+ * The key is in THIS process: a browser, an app, a game client, a developer's own program.
+ *
+ * The code is checked when it is first used rather than here, so that making one of these does no
+ * work and a code that is not one fails on the first call, where the caller can act on it.
+ */
+export declare function deviceRoot(credentials: Credentials): Root;
+/**
+ * The key is in a BUSINESS'S STORE: it sealed the code and opens it when something needs it.
+ *
+ * ⛔ ASKED EVERY TIME AND KEPT NOWHERE. This package holds no copy between calls, which is what
+ *    makes the business's own store the only place the code lives at rest: revoking it there ends
+ *    the access, and a long-running process that was asked once does not go on holding it. The cost
+ *    is one `openCode` per call, and the test registry counts exactly that.
+ */
+export declare function managedRoot(source: ManagedCredentials): Root;

package/dist/root.js

@@ -0,0 +1,76 @@
+// Who holds the NMTS key — the one thing that differs between a person's own program and a
+// business running this for other people, and the only place in the package where it differs.
+//
+// ⛔ EVERY VERB TAKES A ROOT, AND THERE ARE TWO ROOTS, NOT TWO SETS OF VERBS. Everything an account
+//    can do is derived from its key, so the question "who holds it" has exactly one seam: which
+//    process the key is in. Splitting the verbs by mode instead would mean writing each one twice,
+//    and a verb written twice is a verb that ends up working for one holder and not the other.
+//    `test/roots.ts` walks every verb through both, so a verb that only works one way is a red test
+//    rather than a discovery made by whoever tried it second.
+//
+// ⛔ A JAVASCRIPT STRING CANNOT BE ZEROED, so `withCode` does what a runtime with immutable strings
+//    allows: it lends the code for one piece of work, keeps no reference of its own afterwards, and
+//    never stores what it opened. What is derived FROM the code is wiped — `withDataKey` in
+//    `session.ts` zeroes the derivation before it returns. The device root is the exception by
+//    definition: the caller handed it the code, so the caller's own object holds it.
+//
+// ⛔ NO SERVER AND NO NETWORK HERE. A root answers "who holds the key" and "who does the server
+//    think is calling". Where to talk is `NmtsOptions`, because the same key is the same account on
+//    any server, and a root carrying an address would be a key that only worked against one.
+import { NmtsError } from "@needmoretruth/nmts-cli";
+const CODE_NEXT_STEP = "Pass `accountCode` to Nmts.device(), or set NMTS_ACCOUNT_CODE_FILE and use `Nmts.fromEnv()`.";
+const OPENED_NOTHING_NEXT_STEP = "Nothing was sent. `openCode` answered no account code, so there was nothing to open the account with.";
+/**
+ * A credential is text or it is a refusal.
+ *
+ * ⛔ THE REFUSAL NEVER CONTAINS THE VALUE. It names what was missing and what to do; a caller's log
+ *    is not a place an account code should be able to reach.
+ */
+export function requireText(value, what, nextStep) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NmtsError(`No ${what} was given.`, { exitCode: 3, nextStep });
+    }
+    return value.trim();
+}
+/**
+ * The key is in THIS process: a browser, an app, a game client, a developer's own program.
+ *
+ * The code is checked when it is first used rather than here, so that making one of these does no
+ * work and a code that is not one fails on the first call, where the caller can act on it.
+ */
+export function deviceRoot(credentials) {
+    const { accountCode, apiKey } = credentials;
+    return {
+        mode: "device",
+        identity: { kind: "api-key", apiKey },
+        async withCode(use) {
+            return use(requireText(accountCode, "account code", CODE_NEXT_STEP));
+        },
+    };
+}
+/**
+ * The key is in a BUSINESS'S STORE: it sealed the code and opens it when something needs it.
+ *
+ * ⛔ ASKED EVERY TIME AND KEPT NOWHERE. This package holds no copy between calls, which is what
+ *    makes the business's own store the only place the code lives at rest: revoking it there ends
+ *    the access, and a long-running process that was asked once does not go on holding it. The cost
+ *    is one `openCode` per call, and the test registry counts exactly that.
+ */
+export function managedRoot(source) {
+    const { openCode, apiKey } = source;
+    return {
+        mode: "managed",
+        identity: { kind: "api-key", apiKey },
+        async withCode(use) {
+            let code = requireText(await openCode(), "account code", OPENED_NOTHING_NEXT_STEP);
+            try {
+                return await use(code);
+            }
+            finally {
+                // The local would go out of scope anyway. Dropping it here is what a reader can check, and
+                // what stops a later edit from quietly holding the code past the work that borrowed it.
+                code = null;
+            }
+        },
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,54 @@
+import { type CryptoGlue, type Network } from "@needmoretruth/nmts-cli";
+import { type Root } from "./root.ts";
+/** Where an account talks. Not the root's business: one key is one account on any server. */
+export interface ServerOptions {
+    /** The NMTS server. Defaults to https://nmts.me. */
+    server?: string | undefined;
+    /**
+     * `mainnet` or `testnet`. Defaults to mainnet for the public server and must be stated for any
+     * other — guessing would look for files on a network they were never stored on.
+     */
+    network?: string | undefined;
+}
+/** An account this process can act for: the root that holds its key, and where it talks. */
+export interface Opened {
+    readonly root: Root;
+    readonly apiKey: string;
+    readonly server: string;
+    readonly network: Network;
+}
+/** The account WHILE one call holds its code — everything the library surface underneath takes. */
+export interface Held {
+    readonly code: string;
+    readonly apiKey: string;
+    readonly server: string;
+    readonly network: Network;
+    readonly accountId: string;
+}
+/**
+ * Check what can be checked without the code, and work out where this account talks.
+ *
+ * The key is only checked for being present; the server is what judges a key, on the first request.
+ * Nothing here borrows the code, so a caller who got the key wrong is refused without a business's
+ * store having been opened for nothing.
+ */
+export declare function openAccount(root: Root, options?: ServerOptions): Opened;
+/**
+ * Borrow the account's code for the length of `body`, and work out the account it names.
+ *
+ * ⛔ ONE CALL, ONE BORROW. Every verb in this package wraps the whole of itself in this, so a
+ *    managed root is asked to open its sealed code exactly once however many requests the verb makes.
+ *
+ * ⛔ THE ACCOUNT ID IS DERIVED HERE RATHER THAN KEPT, because deriving it is the only check there
+ *    is that a code is one: nothing about a string says which account it opens until the engine has
+ *    parsed it. It is a pure function of the code, and the code is only here.
+ */
+export declare function withAccount<T>(opened: Opened, body: (held: Held) => Promise<T>): Promise<T>;
+/**
+ * Run `body` with the account's data key, then wipe it.
+ *
+ * The data key wraps every file key in the account. It exists for exactly as long as the work
+ * that needs it, and the derivation output it came out of — which holds every other key too — is
+ * zeroed before `body` even starts.
+ */
+export declare function withDataKey<T>(code: string, body: (crypt: CryptoGlue, dataKey: Uint8Array) => Promise<T>): Promise<T>;