@needmoretruth/nmts-cli 0.35.0 → 0.36.1

package/dist/manifest-chunk-cache.js

@@ -6,46 +6,45 @@
 //    rewrote one chunk costs one download instead of the whole list.
 //
 // ⛔ AND IT IS STILL CHECKED ON THE WAY OUT. The reader re-hashes what it reads from here before
-//    opening it (`manifest-chunk-flow.ts`). A directory on this machine is not a trusted store:
-//    whoever holds the machine can edit it, and the index is the only thing that says which bytes
-//    belong to which version.
+//    opening it (`manifest-chunk-flow.ts`). A store on this machine is not a trusted one: whoever
+//    holds the machine can edit it, and the index is the only thing that says which bytes belong
+//    to which version.
 //
 // ⛔ WHAT IS STORED IS SEALED. These are the account's names, folders and file keys, sealed with
-//    the NMTS key — the same bytes the server holds and cannot read. They are written 0600 in
-//    a 0700 directory, beside the kept copy of the index and for the same reason.
+//    the NMTS key — the same bytes the server holds and cannot read. Where they land, and how
+//    private that place is, is the host's business: on this machine it is a 0600 file in a 0700
+//    directory, beside the kept copy of the index and for the same reason.
 //
 // ⚠ NOTHING HERE THROWS. A cache that cannot be read or written is a slower command, never a
 //   broken one: every function answers "no copy" and the network path behind it does the work.
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { configDir } from "./credentials.js";
-/** A chunk's name: base64url SHA-256, unpadded — 43 characters, and it becomes a file name. */
+import { fromUtf8, utf8 } from "./bytes.js";
+import { host } from "./host.js";
+/** A chunk's name: base64url SHA-256, unpadded — 43 characters, and it becomes part of a key. */
 const NAME = /^[A-Za-z0-9_-]{43}$/;
 /**
- * ⛔ AN ACCOUNT ID BECOMES PART OF A PATH HERE, so it is CHECKED rather than trusted — the same
+ * ⛔ AN ACCOUNT ID BECOMES PART OF A KEY HERE, so it is CHECKED rather than trusted — the same
  *    check `manifest.ts` makes on the kept list, and for the same reason: a value that reaches a
- *    path join unchecked is how `..` becomes a write somewhere else.
+ *    key unchecked is how `..` becomes a write somewhere else on a host that spells keys as paths.
  */
 const ACCOUNT = /^[A-Za-z0-9_-]{1,64}$/;
-/** Where one account's chunks live, or null when the id is not one this tool derived. */
-function dirFor(accountId) {
-    if (!ACCOUNT.test(accountId))
-        return null;
-    return join(configDir(), "file-list-chunks", accountId);
+/** The key prefix one account's chunks live under, or null when the id is not one this tool derived. */
+function areaFor(accountId) {
+    return ACCOUNT.test(accountId) ? `chunks/${accountId}/` : null;
 }
-function pathFor(accountId, hash) {
-    const dir = dirFor(accountId);
-    if (dir === null || !NAME.test(hash))
-        return null;
-    return join(dir, `${hash}.ct`);
+function keyFor(accountId, hash) {
+    const area = areaFor(accountId);
+    return area === null || !NAME.test(hash) ? null : `${area}${hash}`;
 }
 /** The sealed bytes this machine holds under that name, or null when it holds none. */
-export function readCachedChunk(accountId, hash) {
-    const path = pathFor(accountId, hash);
-    if (path === null)
+export async function readCachedChunk(accountId, hash) {
+    const key = keyFor(accountId, hash);
+    if (key === null)
         return null;
     try {
-        const text = readFileSync(path, "utf8").trim();
+        const held = await host().state.read(key);
+        if (held === undefined)
+            return null;
+        const text = fromUtf8(held).trim();
         return text === "" ? null : text;
     }
     catch {
@@ -53,18 +52,16 @@ export function readCachedChunk(accountId, hash) {
     }
 }
 /** Keep these sealed bytes under that name. Silent when the machine will not take them. */
-export function writeCachedChunk(accountId, hash, ct) {
-    const dir = dirFor(accountId);
-    const path = pathFor(accountId, hash);
-    if (dir === null || path === null)
+export async function writeCachedChunk(accountId, hash, ct) {
+    const key = keyFor(accountId, hash);
+    if (key === null)
         return;
     try {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-        writeFileSync(path, `${ct}\n`, { mode: 0o600 });
+        await host().state.write(key, utf8(`${ct}\n`));
     }
     catch {
-        // Out of space, read-only home, a directory somebody removed underneath: the next read of the
-        // list fetches from the server instead, which is what this cache is an optimisation of.
+        // Out of space, a read-only home, a browser that would not open its database: the next read of
+        // the list fetches from the server instead, which is what this cache is an optimisation of.
     }
 }
 /**
@@ -76,27 +73,25 @@ export function writeCachedChunk(accountId, hash, ct) {
  *    abandoned. Called after every complete read and every successful write, which is exactly when
  *    "what the list names" is known.
  */
-export function pruneChunkCache(accountId, keep) {
-    const dir = dirFor(accountId);
-    if (dir === null)
+export async function pruneChunkCache(accountId, keep) {
+    const area = areaFor(accountId);
+    if (area === null)
         return;
-    let names;
+    let held;
     try {
-        names = readdirSync(dir);
+        held = await host().state.keys(area);
     }
     catch {
         return;
     }
-    for (const name of names) {
-        if (!name.endsWith(".ct"))
-            continue;
-        if (keep.has(name.slice(0, -3)))
+    for (const key of held) {
+        if (keep.has(key.slice(area.length)))
             continue;
         try {
-            rmSync(join(dir, name), { force: true });
+            await host().state.remove(key);
         }
         catch {
-            // A copy that will not delete costs disk and nothing else; it is named by a hash, so it can
+            // A copy that will not delete costs space and nothing else; it is named by a hash, so it can
             // never be handed back as some other version.
         }
     }

package/dist/manifest-chunk-flow.js

@@ -18,12 +18,13 @@
 // PURE OF COMMANDS: it takes a derived key and a server, and knows nothing about what an edit
 //   means. Deciding WHICH entries the list should hold is `manifest-write.ts`'s job; deciding which
 //   entry goes in which chunk is the shared packer's.
+import { fromBase64Url, toBase64Url } from "./bytes.js";
 import { request, ServerError } from "./api.js";
 import { AAD, DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 import { pruneChunkCache, readCachedChunk, writeCachedChunk } from "./manifest-chunk-cache.js";
 import { keepTrying } from "./net-retry.js";
-import { registerNodeZstd } from "./zstd-node.js";
+import { host } from "./host.js";
 import { AAD_FILE_LIST_CHUNK, chunkFingerprint, decodeChunk, decodeFileList, encodeChunk, encodeIndex, FILE_LIST_VERSION_CHUNKED, } from "./shared/lib/drive/manifest-chunks.js";
 import { packAll, repack } from "./shared/lib/drive/manifest-pack.js";
 /** How many chunk requests are in flight at once. Enough to fill a link, few enough to stay fair. */
@@ -42,10 +43,10 @@ export class ManifestChunkError extends NmtsError {
     }
 }
 function sealUnder(io, aad, body) {
-    return Buffer.from(io.crypt.envelope_seal(io.key, utf8.encode(aad), body)).toString("base64url");
+    return toBase64Url(io.crypt.envelope_seal(io.key, utf8.encode(aad), body));
 }
 function openUnder(io, aad, ct) {
-    return io.crypt.envelope_open(io.key, utf8.encode(aad), Buffer.from(ct, "base64url"));
+    return io.crypt.envelope_open(io.key, utf8.encode(aad), fromBase64Url(ct));
 }
 /** What the two chunk routes answer. Narrowed here rather than trusted. */
 function ctOf(answer) {
@@ -63,7 +64,7 @@ function ctOf(answer) {
  * is a version nobody will ask for again.
  */
 export async function openChunks(io, index) {
-    registerNodeZstd();
+    await host().zstd.register();
     const refs = index.chunks;
     const out = new Array(refs.length);
     let next = 0;
@@ -78,12 +79,12 @@ export async function openChunks(io, index) {
         }
     };
     await Promise.all(Array.from({ length: Math.min(CONCURRENCY, refs.length) }, worker));
-    pruneChunkCache(io.accountId, new Set(refs.map((c) => c.h)));
+    await pruneChunkCache(io.accountId, new Set(refs.map((c) => c.h)));
     return out;
 }
 /** One chunk: from this machine if it has it, else from the server — verified either way. */
 async function openOne(io, ref, indexSeq) {
-    const cached = readCachedChunk(io.accountId, ref.h);
+    const cached = await readCachedChunk(io.accountId, ref.h);
     let ct = cached;
     if (ct === null) {
         try {
@@ -119,7 +120,7 @@ async function openOne(io, ref, indexSeq) {
         throw new ManifestChunkError(`Part of the file list holds ${doc.items.length} entries where the index says ${ref.n}.`);
     }
     if (cached === null)
-        writeCachedChunk(io.accountId, ref.h, ct);
+        await writeCachedChunk(io.accountId, ref.h, ct);
     return doc.items;
 }
 /**
@@ -133,7 +134,7 @@ async function openOne(io, ref, indexSeq) {
  *   the chunks written by the losing attempt are named by no index and the server sweeps them.
  */
 export async function writeChunkedList(io, plan) {
-    registerNodeZstd();
+    await host().zstd.register();
     const packed = plan.previous.length > 0 ? repack(plan.previous, plan.entries) : packAll(plan.entries);
     const rows = [];
     const held = [];
@@ -168,7 +169,7 @@ export async function writeChunkedList(io, plan) {
     body.fill(0);
     const refs = rows.map((r) => r.h);
     const seq = await putIndex(io, plan.baseSeq, ct, refs, fresh);
-    pruneChunkCache(io.accountId, new Set(refs));
+    await pruneChunkCache(io.accountId, new Set(refs));
     return { seq, ct, held };
 }
 /**
@@ -197,7 +198,7 @@ async function putIndex(io, baseSeq, ct, refs, fresh) {
             for (const name of refs) {
                 if (again.has(name))
                     continue;
-                const kept = readCachedChunk(io.accountId, name);
+                const kept = await readCachedChunk(io.accountId, name);
                 if (kept !== null)
                     again.set(name, kept);
             }
@@ -231,7 +232,7 @@ async function putChunks(io, chunks) {
                 token: io.apiKey,
                 body: { ct },
             }), { retryable: (error) => error instanceof ServerError && error.status === 429 });
-            writeCachedChunk(io.accountId, name, ct);
+            await writeCachedChunk(io.accountId, name, ct);
         }
     };
     await Promise.all(Array.from({ length: Math.min(CONCURRENCY, names.length) }, worker));
@@ -259,14 +260,14 @@ function seqOf(answer) {
  *   refusing here would refuse in a case the command used to handle.
  */
 export async function namedChunks(code, ct) {
-    registerNodeZstd();
+    await host().zstd.register();
     const crypt = await loadCrypto();
     const [from, to] = DERIVED.fileListKey;
     const derived = crypt.kdf_derive(crypt.account_code_parse(code));
     const key = derived.slice(from, to);
     derived.fill(0);
     try {
-        const body = crypt.envelope_open(key, utf8.encode(AAD.fileList), Buffer.from(ct, "base64url"));
+        const body = crypt.envelope_open(key, utf8.encode(AAD.fileList), fromBase64Url(ct));
         const doc = await decodeFileList(body);
         body.fill(0);
         return doc.v === FILE_LIST_VERSION_CHUNKED ? doc.index.chunks.map((c) => c.h) : [];
@@ -292,7 +293,7 @@ export async function keptChunks(code, accountId, indexCt) {
         return null;
     const out = [];
     for (const name of names) {
-        const ct = readCachedChunk(accountId, name);
+        const ct = await readCachedChunk(accountId, name);
         if (ct === null) {
             throw new NmtsError("This machine holds the file list's index but not all of its parts.", {
                 exitCode: 4,

package/dist/manifest-write.js

@@ -236,7 +236,7 @@ export async function addEntry(input) {
     let replaced;
     // ⛔ SETTLED ONCE, OUTSIDE THE RETRY LOOP. What the machine is set to and whether a mode is on
     //    are facts about this run, not about the list version a compare-and-swap happened to read.
-    const choice = decide(input.onCollision).choice;
+    const choice = (await decide(input.onCollision)).choice;
     const result = await applyManyToList(input, (entries) => {
         const plan = planAddition(entries, input.entry, choice);
         alreadyThere = plan.alreadyThere ?? null;

package/dist/manifest.d.ts

@@ -30,7 +30,7 @@ export interface KeptList {
  *   write out a good copy because an old one is unreadable would be refusing the very thing it is
  *   for.
  */
-export declare function readKeptList(accountId: string): KeptList | null;
+export declare function readKeptList(accountId: string): Promise<KeptList | null>;
 /**
  * Record a version this machine WROTE, so the server cannot serve an older one back afterwards.
  *
@@ -40,7 +40,7 @@ export declare function readKeptList(accountId: string): KeptList | null;
  */
 export declare function recordWrittenList(accountId: string, seq: number, ct: string): Promise<void>;
 /** True when this machine has a record for the account — i.e. a rollback would be visible. */
-export declare function hasSeenBefore(accountId: string): boolean;
+export declare function hasSeenBefore(accountId: string): Promise<boolean>;
 export interface FileList {
     /** null when the account has no list yet — a new account, not an error. */
     manifest: Manifest | null;

package/dist/manifest.js

@@ -27,12 +27,11 @@
 //    exactly as the single blob was, and the chunks are kept by name in the chunk store
 //    (`manifest-chunk-cache.ts`), which is pruned to what the list just read names. So the copy is
 //    still complete — it is simply in two places, and `nmts listfile` writes them out as one file.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { request } from "./api.js";
+import { fromBase64Url, fromUtf8, toBase64Url, utf8 } from "./bytes.js";
 import { AAD, DERIVED, loadCrypto } from "./crypto.js";
-import { configDir } from "./credentials.js";
 import { NmtsError } from "./errors.js";
+import { host } from "./host.js";
 import { openChunks } from "./manifest-chunk-flow.js";
 import { decodeFileList, FILE_LIST_VERSION_CHUNKED, } from "./shared/lib/drive/manifest-chunks.js";
 function asResponse(value) {
@@ -53,26 +52,26 @@ function asResponse(value) {
 }
 /** base64url SHA-256 of a sealed blob — the value a later list carries as its `prev`. */
 async function fingerprint(ct) {
-    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(ct));
-    return Buffer.from(digest).toString("base64url");
-}
-function statePath() {
-    return join(configDir(), "file-list-state.json");
+    const digest = await crypto.subtle.digest("SHA-256", utf8(ct));
+    return toBase64Url(new Uint8Array(digest));
 }
+/** The one key this machine's record of what it has seen lives under. */
+const STATE_KEY = "manifest/state";
 /**
- * Where this machine keeps one account's sealed file list.
+ * The key this machine keeps one account's sealed file list under.
  *
- * ⛔ AN ACCOUNT ID BECOMES PART OF A PATH HERE, so it is CHECKED rather than trusted. Every id this
- *    tool has comes from its own derivation and is base64url, but a value that reaches a path join
- *    unchecked is how `..` becomes a write somewhere else, and the check costs one line.
+ * ⛔ AN ACCOUNT ID BECOMES PART OF A KEY HERE, so it is CHECKED rather than trusted. Every id this
+ *    tool has comes from its own derivation and is base64url, but a value that reaches a key
+ *    unchecked is how `..` becomes a write somewhere else on a host that spells keys as paths, and
+ *    the check costs one line.
  */
-function keptListPath(accountId) {
+function keptListKey(accountId) {
     if (!/^[A-Za-z0-9_-]{1,64}$/.test(accountId)) {
         throw new NmtsError("That is not an account id this tool derived.", {
             nextStep: "Nothing was written. This is a fault in the tool rather than in the account.",
         });
     }
-    return join(configDir(), `file-list-${accountId}.json`);
+    return `manifest/${accountId}`;
 }
 /** This machine's copy of one account's sealed file list. */
 /**
@@ -104,9 +103,12 @@ function isKeptList(value) {
  *   write out a good copy because an old one is unreadable would be refusing the very thing it is
  *   for.
  */
-export function readKeptList(accountId) {
+export async function readKeptList(accountId) {
     try {
-        const parsed = JSON.parse(readFileSync(keptListPath(accountId), "utf8"));
+        const held = await host().state.read(keptListKey(accountId));
+        if (held === undefined)
+            return null;
+        const parsed = JSON.parse(fromUtf8(held));
         return isKeptList(parsed) ? parsed : null;
     }
     catch {
@@ -121,17 +123,19 @@ export function readKeptList(accountId) {
  *    a run that then read an older list from the server must not overwrite the newest copy with
  *    it. The record refuses a lower version while it exists; this is what holds when it does not.
  */
-function writeKept(accountId, seq, ct) {
-    const held = readKeptList(accountId);
+async function writeKept(accountId, seq, ct) {
+    const held = await readKeptList(accountId);
     if (held !== null && held.seq > seq)
         return;
     const copy = { seq, savedAt: new Date().toISOString(), ct };
-    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
-    writeFileSync(keptListPath(accountId), `${JSON.stringify(copy, null, 2)}\n`, { mode: 0o600 });
+    await host().state.write(keptListKey(accountId), utf8(`${JSON.stringify(copy, null, 2)}\n`));
 }
-function readSeen() {
+async function readSeen() {
     try {
-        const parsed = JSON.parse(readFileSync(statePath(), "utf8"));
+        const held = await host().state.read(STATE_KEY);
+        if (held === undefined)
+            return {};
+        const parsed = JSON.parse(fromUtf8(held));
         return typeof parsed === "object" && parsed !== null ? parsed : {};
     }
     catch {
@@ -147,14 +151,13 @@ function readSeen() {
  *    would be two chances for a caller to update one and not the other — after which the machine
  *    would hold a copy of one version while claiming to have seen another.
  */
-function writeSeen(accountId, seq, fp, ct) {
-    const all = readSeen();
+async function writeSeen(accountId, seq, fp, ct) {
+    const all = await readSeen();
     all[accountId] = { seq, fingerprint: fp };
-    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
-    writeFileSync(statePath(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    await host().state.write(STATE_KEY, utf8(`${JSON.stringify(all, null, 2)}\n`));
     // The record goes first: it is the safety device, and a machine that failed to keep a copy must
     // still refuse an older list afterwards.
-    writeKept(accountId, seq, ct);
+    await writeKept(accountId, seq, ct);
 }
 /**
  * Record a version this machine WROTE, so the server cannot serve an older one back afterwards.
@@ -164,11 +167,11 @@ function writeSeen(accountId, seq, fp, ct) {
  *    a rollback.
  */
 export async function recordWrittenList(accountId, seq, ct) {
-    writeSeen(accountId, seq, await fingerprint(ct), ct);
+    await writeSeen(accountId, seq, await fingerprint(ct), ct);
 }
 /** True when this machine has a record for the account — i.e. a rollback would be visible. */
-export function hasSeenBefore(accountId) {
-    return existsSync(statePath()) && accountId in readSeen();
+export async function hasSeenBefore(accountId) {
+    return accountId in (await readSeen());
 }
 /**
  * Fetch and open the account's file list.
@@ -178,10 +181,10 @@ export function hasSeenBefore(accountId) {
  */
 export async function readFileList(base, apiKey, accountCode, accountId) {
     const answer = asResponse(await request(base, "/v1/manifest", { token: apiKey }));
-    const first = !hasSeenBefore(accountId);
+    const first = !(await hasSeenBefore(accountId));
     if (answer.state === "absent")
         return { manifest: null, firstTimeOnThisMachine: first };
-    const seen = readSeen()[accountId];
+    const seen = (await readSeen())[accountId];
     if (seen !== undefined && answer.seq < seen.seq) {
         throw new NmtsError(`The server offered file-list version ${answer.seq}; this machine already saw ${seen.seq}.`, {
             nextStep: "Nothing was changed. A list that goes backwards means an older copy is being served, " +
@@ -214,7 +217,7 @@ export async function readFileList(base, apiKey, accountCode, accountId) {
     try {
         let body;
         try {
-            body = crypt.envelope_open(key, new TextEncoder().encode(AAD.fileList), Buffer.from(answer.ct, "base64url"));
+            body = crypt.envelope_open(key, utf8(AAD.fileList), fromBase64Url(answer.ct));
         }
         catch {
             throw new NmtsError("The file list did not open with this account's key.", {
@@ -252,7 +255,7 @@ export async function readFileList(base, apiKey, accountCode, accountId) {
         // ⛔ THE VERSION THAT IS KEPT IS THE SEALED ONE, and so are the bytes it came out of. Believing
         //    the server's column here would let it decide which copy this machine keeps. The bytes are
         //    the INDEX at version 2; its chunks are kept beside it, by name, in the chunk store.
-        writeSeen(accountId, manifest.seq, fp, answer.ct);
+        await writeSeen(accountId, manifest.seq, fp, answer.ct);
         return out;
     }
     finally {

package/dist/mcp-tools/tiers.js

@@ -141,7 +141,7 @@ export function withTiers(tools, asker) {
             ...tool,
             description: `${tierLine(tier)}${tool.description}`,
             annotations: annotationsOf(tool.name),
-            run: async (args) => (await passTool(tool.name, args, currentMode(), asker())) ?? (await tool.run(args)),
+            run: async (args) => (await passTool(tool.name, args, await currentMode(), asker())) ?? (await tool.run(args)),
         };
     });
 }

package/dist/network.d.ts

@@ -1,6 +1,6 @@
 export declare const NETWORKS: readonly ["mainnet", "testnet"];
 export type Network = (typeof NETWORKS)[number];
-export declare const NETWORK_ENV_VAR = "NMTS_NETWORK";
+export { NETWORK_ENV_VAR } from "./env-vars.ts";
 /**
  * Decide the network for this run.
  *

package/dist/network.js

@@ -9,10 +9,14 @@
 // ⛔ SO THE RULE HERE IS: the live server implies mainnet, and ANY other server must say which
 //    network it is. There is no fallback. A tool that has to guess where somebody's files are
 //    should stop instead.
+import { NETWORK_ENV_VAR } from "./env-vars.js";
 import { NmtsError } from "./errors.js";
+import { host } from "./host.js";
 import { DEFAULT_SERVER } from "./server.js";
 export const NETWORKS = ["mainnet", "testnet"];
-export const NETWORK_ENV_VAR = "NMTS_NETWORK";
+// Re-exported: the name itself lives in a module with no imports, because `nmts --help`
+// prints it (`env-vars.ts`).
+export { NETWORK_ENV_VAR } from "./env-vars.js";
 function isNetwork(value) {
     return NETWORKS.includes(value);
 }
@@ -23,7 +27,7 @@ function isNetwork(value) {
  * make: the live server is mainnet. Anything else and it refuses.
  */
 export function resolveNetwork(server, explicit) {
-    const stated = explicit ?? process.env[NETWORK_ENV_VAR];
+    const stated = explicit ?? host().env(NETWORK_ENV_VAR);
     if (stated !== undefined && stated.length > 0) {
         if (!isNetwork(stated)) {
             throw new NmtsError(`Not a network: ${stated}`, {

package/dist/platform-sign.d.ts

@@ -0,0 +1,143 @@
+/** The fixed prefix of a business signature. `1` is the format version, so a later shape is `bs2_`. */
+export declare const BUSINESS_PREFIX = "nmts_bs1_";
+/** …and of a delegation token. */
+export declare const DELEGATION_PREFIX = "nmts_dt1_";
+/** What a business signature covers, before the moment, the nonce, the method, the path and the digest. */
+export declare const BUSINESS_CONTEXT = "nmts/p1/business/v1";
+/** What a business signs over a delegation payload. */
+export declare const DELEGATION_CONTEXT = "nmts/p1/delegation/v1";
+/** What the NEW key signs over the old one when a business replaces its key. */
+export declare const ROTATE_CONTEXT = "nmts/p1/rotate/v1";
+/** Ed25519 key and signature lengths, named because a parser and a refusal both state them. */
+export declare const PUBKEY_LEN = 32;
+export declare const PRIVATE_KEY_LEN = 32;
+export declare const SIGNATURE_LEN = 64;
+/**
+ * The random half of a delegation payload, and of a business signature: 16 bytes each, so two
+ * credentials made in the same second for the same thing are still different strings.
+ */
+export declare const NONCE_LEN = 16;
+/** The longest life a delegation token may be minted with — thirty days. */
+export declare const DELEGATION_MAX_TTL_SECS = 2592000;
+/**
+ * What a delegation token may open, by name.
+ *
+ * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
+ *    business asking for "read and write" asks for the number a person's key already means by it.
+ *    `register` is the fourth and opens exactly one door: making the account the token names.
+ */
+export declare const SCOPE_BITS: {
+    readonly files_read: 1;
+    readonly files_write: 2;
+    readonly storage_spend: 4;
+    readonly register: 8;
+};
+/** One of the four names above. */
+export type ScopeName = keyof typeof SCOPE_BITS;
+/** Every bit a token may carry. */
+export declare const SCOPE_ALL: number;
+/** A business's key pair, both halves base64url. The private half never travels. */
+export interface BusinessKeyPair {
+    /** 32 bytes, base64url. This is what is registered, and it is not a secret. */
+    publicKey: string;
+    /** 32 bytes, base64url. ⛔ The only copy: nothing can derive it back from the public half. */
+    privateKey: string;
+}
+/**
+ * A new key pair, from the runtime's own random source.
+ *
+ * ⚠ The randomness is the curve library's, which is the platform's `crypto.getRandomValues`. There
+ *   is no second source here: a key drawn from anything weaker is a business somebody else can
+ *   speak for.
+ */
+export declare function generateBusinessKeys(): BusinessKeyPair;
+/** The public half of a private key, so a caller never has to keep the two in step by hand. */
+export declare function businessPublicKey(privateKey: string): string;
+/**
+ * The bytes a business signature covers.
+ *
+ * `path` is the request path as it is sent, with no query string: no Platform door takes one, and
+ * a signature that did not cover a parameter the server then read would be a signature over half
+ * the request.
+ *
+ * ⚠ THE NONCE IS SIGNED AS THE TEXT THAT TRAVELS, base64url, on its own line after the moment —
+ *   so the sender and the receiver agree about the field without either re-encoding it.
+ */
+export declare function businessSigningInput(ts: number, nonce: string, method: string, path: string, body: Uint8Array): Uint8Array;
+/** The bytes a delegation signature covers: the context, then the payload exactly as it travels. */
+export declare function delegationSigningInput(payload: Uint8Array): Uint8Array;
+/** The bytes the new key signs during a rotation: the context, then the key being replaced. */
+export declare function rotationSigningInput(oldPublicKey: string): Uint8Array;
+/** What one signed request is about. */
+export interface BusinessRequest {
+    /** The business account's public id, base64url — what the server knows it by. */
+    accountId: string;
+    privateKey: string;
+    method: string;
+    /** The path as it will be sent, `/p1/business`. */
+    path: string;
+    /** The request body exactly as it will be sent. Empty for a GET. */
+    body?: Uint8Array | undefined;
+    /** Unix seconds. Absent = now. The server accepts a window either side of its own clock. */
+    at?: number | undefined;
+    /**
+     * The 16 random bytes this one request carries, base64url.
+     *
+     * ⚠ FOR A TEST THAT NEEDS THE SAME CREDENTIAL TWICE, and for nothing else. Left out, it is drawn
+     *   from the runtime's random source, which is what makes two identical requests two requests.
+     */
+    nonce?: string | undefined;
+}
+/**
+ * The whole `Authorization: Bearer` value for one request to a Platform door.
+ *
+ * ⛔ ONE SIGNATURE, ONE REQUEST. The server remembers each accepted signature for the length of its
+ *    clock window and refuses a second presentation of the same one, so a value from here is not a
+ *    credential to keep — it is made for the request it is about and spent on it.
+ *
+ * ⛔ AND THAT IS WHY THE NONCE IS HERE. Ed25519 is deterministic and the moment is whole seconds,
+ *    so two identical requests inside one second would otherwise be the same bytes — and the
+ *    second of them would be refused as a replay of the first.
+ */
+export declare function signBusinessRequest(request: BusinessRequest): string;
+/** What one delegation token says. */
+export interface DelegationRequest {
+    /** The business's own account id, base64url. */
+    business: string;
+    /** The account id of the user this token speaks for, base64url. */
+    user: string;
+    privateKey: string;
+    /** What the token may do. At least one; an empty set opens nothing. */
+    scope: readonly ScopeName[];
+    /** How long it lasts, in seconds. At most [`DELEGATION_MAX_TTL_SECS`]. */
+    ttlSecs: number;
+    /** Unix seconds this life is counted from. Absent = now. */
+    at?: number | undefined;
+    /**
+     * The 16 random bytes in the payload, base64url.
+     *
+     * ⚠ FOR A TEST THAT NEEDS THE SAME TOKEN TWICE, and for nothing else. Left out, it is drawn from
+     *   the runtime's random source, which is what makes two tokens with identical fields differ.
+     */
+    nonce?: string | undefined;
+}
+/**
+ * Mint one delegation token.
+ *
+ * ⛔ THE LIFE IS REFUSED HERE AS WELL AS THERE. A token longer than the ceiling is refused by the
+ *    server as malformed, which reaches the business as an authentication failure on somebody
+ *    else's request; refusing it where it is made names the mistake to the program that made it.
+ */
+export declare function mintDelegation(request: DelegationRequest): string;
+/**
+ * The proof the new key makes of itself when a business replaces its key.
+ *
+ * ⛔ THE OLD KEY IS IN THE MESSAGE, so this proof is about THIS replacement and cannot be lifted
+ *    onto another. The request carrying it is signed by the old key, so a rotation needs both
+ *    halves in one hand.
+ */
+export declare function rotationProof(oldPublicKey: string, newPrivateKey: string): string;
+/** The bitmask these scope names make. */
+export declare function scopeMask(scopes: readonly ScopeName[]): number;
+/** Does this signature hold over these bytes? Here so a caller can check its own work offline. */
+export declare function signatureHolds(publicKey: string, message: Uint8Array, signature: string): boolean;