ncrypted 0.1.2 → 0.3.0

package/dist/ai-sdk.js

@@ -0,0 +1,112 @@
+// Vercel AI SDK tools for ncrypted. Usage:
+//   import { ncryptedTools } from "ncrypted/ai-sdk";
+//   await generateText({ model, tools: ncryptedTools(), prompt });
+import { tool } from "ai";
+import { z } from "zod";
+import { Ncrypted } from "./client.js";
+const errorText = (e) => `Error: ${e.message}`;
+/**
+ * Returns AI SDK tools for sharing secrets as one-time, end-to-end encrypted links (and writing them into Vercel env
+ * vars without the model seeing them). Encryption happens in your server process. The first 3 secrets per day are
+ * free; after that each costs 0.005 USDC on Base, paid via x402 from the configured wallet
+ * (NCRYPTED_WALLET_PRIVATE_KEY or ~/.config/ncrypted/wallet.key). Reads and deliveries are free.
+ */
+export function ncryptedTools(options = {}) {
+    const { include, ...clientOptions } = options;
+    const nc = new Ncrypted({ client: "ai-sdk", ...clientOptions });
+    const all = {
+        ncrypted_create: tool({
+            description: "Encrypt a password, API key, token or private note and return a one-time link that self-destructs after a single read. " +
+                "Use it whenever a credential must be shared with a person or another agent, instead of writing the value in a message. " +
+                "Never repeat the secret in your reply; share only the link. The first 3 per day are free (TTL up to 24h); then 0.005 USDC each.",
+            inputSchema: z.object({
+                secret: z.string().min(1).max(65536).describe("The sensitive value. Max 64 KB."),
+                ttlSeconds: z.number().int().min(300).max(604800).optional().describe("Expiry if never opened. Default 86400 (24h)."),
+                passphrase: z.string().optional().describe("Optional second factor; deliver it through a different channel than the link."),
+                emailTo: z.string().email().optional().describe("Email the link to this address (requires a paid secret, i.e. a funded wallet)."),
+            }),
+            execute: async ({ secret, ttlSeconds, passphrase, emailTo }) => {
+                try {
+                    const r = await nc.create(secret, { ttl: ttlSeconds, passphrase, emailTo });
+                    return {
+                        link: r.link,
+                        id: r.id,
+                        expiresAt: r.expiresAt,
+                        receiptToken: r.receiptToken,
+                        emailed: r.emailed,
+                        free: r.free,
+                        note: "The link opens exactly once. Share only the link.",
+                    };
+                }
+                catch (e) {
+                    return errorText(e);
+                }
+            },
+        }),
+        ncrypted_read: tool({
+            description: "Open an ncrypted link (https://ncrypted.ai/s/{id}#{key}) and return the secret. This destroys it permanently. Free. " +
+                "Use the value only for the task at hand and do not repeat it.",
+            inputSchema: z.object({
+                link: z.string().url().describe("The full link including the #key fragment."),
+                passphrase: z.string().optional().describe("Required only if the sender set one."),
+            }),
+            execute: async ({ link, passphrase }) => {
+                try {
+                    return await nc.read(link, passphrase);
+                }
+                catch (e) {
+                    return errorText(e);
+                }
+            },
+        }),
+        ncrypted_status: tool({
+            description: "Check whether a secret you created has been opened (pending, read, burned or expired). Free.",
+            inputSchema: z.object({ id: z.string(), receiptToken: z.string() }),
+            execute: async ({ id, receiptToken }) => {
+                try {
+                    return await nc.status(id, receiptToken);
+                }
+                catch (e) {
+                    return errorText(e);
+                }
+            },
+        }),
+        ncrypted_burn: tool({
+            description: "Destroy a secret you created before anyone opens it, e.g. if the link went to the wrong place. Free.",
+            inputSchema: z.object({ id: z.string(), receiptToken: z.string() }),
+            execute: async ({ id, receiptToken }) => {
+                try {
+                    await nc.burn(id, receiptToken);
+                    return { burned: true };
+                }
+                catch (e) {
+                    return errorText(e);
+                }
+            },
+        }),
+        ncrypted_to_vercel_env: tool({
+            description: "Open an ncrypted link and write its value straight into a Vercel project environment variable (type sensitive), so the value " +
+                "is never shown to you. Needs VERCEL_TOKEN. Vercel access is checked before the link is consumed.",
+            inputSchema: z.object({
+                link: z.string().url(),
+                passphrase: z.string().optional(),
+                key: z.string().describe("Env var name, e.g. STRIPE_SECRET_KEY."),
+                project: z.string().describe("Vercel project name or id."),
+                team: z.string().optional().describe("Vercel team id (team_...) or slug."),
+                targets: z.array(z.enum(["production", "preview", "development"])).optional().describe("Default: production and preview."),
+            }),
+            execute: async ({ link, passphrase, key, project, team, targets }) => {
+                try {
+                    const r = await nc.deliver(link, { type: "vercel_env", key, project, team, targets }, { passphrase });
+                    return { delivered: true, ...r, note: "The value was written directly and was not shown to you." };
+                }
+                catch (e) {
+                    return errorText(e);
+                }
+            },
+        }),
+    };
+    if (!include)
+        return all;
+    return Object.fromEntries(include.map((name) => [name, all[name]]));
+}

package/dist/cli.js

@@ -11,10 +11,16 @@ Usage:
   ncrypted read <link> [--passphrase X]
   ncrypted status <id> --receipt <token>
   ncrypted burn <id> --receipt <token>
+  ncrypted vercel-env <link> --key NAME [--project P] [--team T] [--target production --target preview]
+                                write a secret straight into a Vercel env var (never printed)
+  ncrypted dotenv <link> --key NAME [--path .env]
+  ncrypted request "<what you need>" [--ttl 60m]     ask a human for a secret; prints a link for them
+  ncrypted receive <id> (--vercel-key NAME [--project P] | --dotenv-key NAME [--path .env] | --print) [--wait 120]
   ncrypted wallet new           create a payer wallet at ~/.config/ncrypted/wallet.key
   ncrypted wallet               show the payer address and its USDC balance on Base
 
-Creating a secret needs a Base wallet holding a little USDC (no ETH needed). The key is read from
+The first 3 secrets per day are free (TTL up to 24h, no email). After that, creating a secret needs a Base
+wallet holding a little USDC (no ETH needed). The key is read from
 NCRYPTED_WALLET_PRIVATE_KEY, else NCRYPTED_WALLET_FILE, else ~/.config/ncrypted/wallet.key.
 NCRYPTED_URL overrides the API origin.`;
 function parseTtl(v) {
@@ -43,12 +49,21 @@ async function main() {
             note: { type: "string" },
             text: { type: "string" },
             receipt: { type: "string" },
+            key: { type: "string" },
+            project: { type: "string" },
+            team: { type: "string" },
+            target: { type: "string", multiple: true },
+            path: { type: "string" },
+            wait: { type: "string" },
+            "vercel-key": { type: "string" },
+            "dotenv-key": { type: "string" },
+            print: { type: "boolean" },
             json: { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
     const [cmd, arg] = positionals;
-    const client = new Ncrypted();
+    const client = new Ncrypted({ client: "cli" });
     const out = (v) => console.log(values.json ? JSON.stringify(v) : typeof v === "string" ? v : JSON.stringify(v, null, 2));
     switch (values.help ? "help" : cmd) {
         case "create": {
@@ -74,6 +89,35 @@ async function main() {
             await client.burn(arg, values.receipt);
             out({ burned: true });
             break;
+        case "vercel-env":
+            if (!arg || !values.key)
+                throw new Error("Usage: ncrypted vercel-env <link> --key NAME [--project P] [--target production]");
+            out(await client.deliver(arg, { type: "vercel_env", key: values.key, project: values.project, team: values.team, targets: values.target }, { passphrase: values.passphrase }));
+            break;
+        case "dotenv":
+            if (!arg || !values.key)
+                throw new Error("Usage: ncrypted dotenv <link> --key NAME [--path .env]");
+            out(await client.deliver(arg, { type: "dotenv", key: values.key, path: values.path }, { passphrase: values.passphrase }));
+            break;
+        case "request":
+            if (!arg)
+                throw new Error('Usage: ncrypted request "<what you need>" [--ttl 60m]');
+            out(await client.requestSecret(arg, { ttl: parseTtl(values.ttl) ?? 3600 }));
+            break;
+        case "receive": {
+            if (!arg)
+                throw new Error("Usage: ncrypted receive <id> (--vercel-key NAME | --dotenv-key NAME | --print)");
+            const destination = values["vercel-key"]
+                ? { type: "vercel_env", key: values["vercel-key"], project: values.project, team: values.team, targets: values.target }
+                : values["dotenv-key"]
+                    ? { type: "dotenv", key: values["dotenv-key"], path: values.path }
+                    : undefined;
+            if (!destination && !values.print)
+                throw new Error("Choose where the value goes: --vercel-key, --dotenv-key, or --print");
+            const res = await client.fulfillRequest(arg, { destination, waitSeconds: Number(parseTtl(values.wait) ?? 120) });
+            out(res.status === "received" ? res.value : res);
+            break;
+        }
         case "wallet": {
             if (arg === "new") {
                 const { address, path } = await createWallet().catch((e) => {
@@ -81,15 +125,18 @@ async function main() {
                         throw new Error(`A wallet already exists at ${walletPath()}`);
                     throw e;
                 });
-                out({ address, path, next: "Send a little USDC on Base to this address. Each secret costs 0.005 USDC; no ETH needed." });
+                out({ address, path, fundUrl: client.fundUrl(address), next: "Send a little USDC on Base to this address (or open fundUrl). Each secret costs 0.005 USDC; no ETH needed." });
                 break;
             }
             const key = normalizeKey(process.env.NCRYPTED_WALLET_PRIVATE_KEY) ?? (await readWalletKey());
-            if (!key)
-                throw new Error("No wallet configured. Run `npx ncrypted wallet new`.");
+            const { freeRemaining, freePerDay } = await client.quota();
+            if (!key) {
+                out({ wallet: null, freeRemainingToday: freeRemaining, freePerDay, next: "Run `npx ncrypted wallet new` to pay for more than the free tier." });
+                break;
+            }
             const address = privateKeyToAccount(key).address;
             const usdc = await usdcBalance(address);
-            out({ address, usdc, secretsAvailable: Math.floor(usdc / 0.005) });
+            out({ address, usdc, paidSecretsAvailable: Math.floor(usdc / 0.005), freeRemainingToday: freeRemaining });
             break;
         }
         default:

package/dist/client.d.ts

@@ -1,6 +1,8 @@
+import { type Destination, type DeliveryResult } from "./destinations.js";
 export declare const DEFAULT_BASE_URL = "https://ncrypted.ai";
 /** Hard cap on what the SDK will ever pay for one secret, whatever the server asks. */
 export declare const MAX_PRICE = "$0.01";
+export declare const SDK_VERSION = "0.3.0";
 export interface NcryptedOptions {
     /** API origin. Defaults to NCRYPTED_URL or the hosted service. */
     baseUrl?: string;
@@ -11,6 +13,8 @@ export interface NcryptedOptions {
     privateKey?: string;
     /** Bring your own x402-paying fetch instead of a private key. */
     paymentFetch?: typeof fetch;
+    /** Integration label sent as x-ncrypted-client for anonymous usage stats, e.g. "ai-sdk". Default "sdk". */
+    client?: string;
 }
 export interface CreateOptions {
     /** Lifetime in seconds, 300 to 604800 (7 days). Default 86400. */
@@ -21,6 +25,8 @@ export interface CreateOptions {
     emailTo?: string;
     /** Optional short note shown in the email, e.g. "DB password for staging". Never put the secret here. */
     emailNote?: string;
+    /** Skip the free tier and always pay (implied by emailTo). */
+    requirePayment?: boolean;
 }
 export interface CreatedSecret {
     id: string;
@@ -32,6 +38,19 @@ export interface CreatedSecret {
     emailed: boolean;
     /** On-chain settlement transaction hash, if reported. */
     paymentTx?: string;
+    /** True when created under the free tier (no payment). */
+    free: boolean;
+    /** Free secrets left today, when created for free. */
+    freeRemaining?: number;
+}
+export interface Quota {
+    freePerDay: number;
+    freeRemaining: number;
+    /** Longest TTL (seconds) allowed for free secrets. */
+    freeMaxTtl: number;
+    price: string;
+    currency: string;
+    network: string;
 }
 export type SecretStatus = "pending" | "read" | "burned" | "expired";
 export declare class NcryptedError extends Error {
@@ -45,8 +64,70 @@ export declare class Ncrypted {
     constructor(opts?: NcryptedOptions);
     /** Resolves the paying fetch lazily, so a missing or bad wallet only affects create(), never reads. */
     private payer;
-    /** Encrypts locally, pays 0.005 USDC via x402, stores the ciphertext and returns a one-time link. */
+    private headers;
+    /**
+     * Encrypts locally and stores the ciphertext, returning a one-time link. The first few secrets per day are free
+     * (TTL up to 24h, no email); after that each costs 0.005 USDC via x402 from the configured wallet.
+     */
     create(secret: string, opts?: CreateOptions): Promise<CreatedSecret>;
+    /**
+     * Reads a one-time link and writes the value straight into a destination (Vercel env var, .env file), so it never
+     * passes through the caller (e.g. an LLM). The destination is checked before the secret is consumed. If writing still
+     * fails afterwards, the value is re-saved to a new one-time link, which is returned in the error.
+     */
+    deliver(link: string, destination: Destination, opts?: {
+        passphrase?: string;
+    }): Promise<DeliveryResult>;
+    private deliverOrRescue;
+    /**
+     * Starts a secret request: returns a link for a human, who pastes the value into the page. It's encrypted in their
+     * browser to a key that only exists on this machine. Free. Complete it with fulfillRequest().
+     */
+    requestSecret(label: string, opts?: {
+        ttl?: number;
+    }): Promise<{
+        id: string;
+        url: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Waits up to waitSeconds for the human to answer a request. With a destination, the value is written there and
+     * never returned; without one, the value is returned. Resolves { status: "pending" } if not answered yet.
+     */
+    fulfillRequest(id: string, opts?: {
+        destination?: Destination;
+        waitSeconds?: number;
+    }): Promise<{
+        status: "pending";
+        expiresAt: string;
+    } | {
+        status: "delivered";
+        result: DeliveryResult;
+    } | {
+        status: "received";
+        value: string;
+    }>;
+    /** Link to a page where the wallet's owner can send it USDC on Base. */
+    fundUrl(address: string, amountUsdc?: number): string;
+    /**
+     * Sets up the local payer wallet if there isn't one. Returns its address and a funding link for the owner; funding
+     * needs only the address. With backupToOwner, the private key is also put into a one-time link (24h) for the owner,
+     * so they can recover or withdraw the funds. The key itself is never returned.
+     */
+    setupWallet(opts?: {
+        amountUsdc?: number;
+        backupToOwner?: boolean;
+    }): Promise<{
+        created: boolean;
+        address: string;
+        usdc: number;
+        fundUrl: string;
+        keyFile: string;
+        backupLink?: string;
+        backupError?: string;
+    }>;
+    /** Free-tier allowance left today and the paid price. */
+    quota(): Promise<Quota>;
     /** Sends the link by email once. Allowed only for the creator and only once per secret. */
     email(id: string, receiptToken: string, link: string, to: string, note?: string): Promise<void>;
     /** Reads and destroys a secret. Free. Works with links from any ncrypted host. */

package/dist/client.js

@@ -1,11 +1,15 @@
 import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch";
 import { ExactEvmScheme } from "@x402/evm";
 import { privateKeyToAccount } from "viem/accounts";
-import { encrypt, decrypt, parseLink } from "./crypto.js";
-import { normalizeKey, readWalletKey, walletPath } from "./wallet.js";
+import { encrypt, decrypt, parseLink, generateRequestKeypair, openSealed } from "./crypto.js";
+import { prepareDestination } from "./destinations.js";
+import { saveLocalRequest, loadLocalRequest, removeLocalRequest } from "./localRequests.js";
+import { normalizeKey, readWalletKey, createWallet, usdcBalance, walletPath } from "./wallet.js";
+import { privateKeyToAccount as accountOf } from "viem/accounts";
 export const DEFAULT_BASE_URL = "https://ncrypted.ai";
 /** Hard cap on what the SDK will ever pay for one secret, whatever the server asks. */
 export const MAX_PRICE = "$0.01";
+export const SDK_VERSION = "0.3.0";
 export class NcryptedError extends Error {
     status;
     constructor(message, status) {
@@ -40,6 +44,8 @@ async function errorFrom(res) {
     }
     return new NcryptedError(msg, res.status);
 }
+const NO_WALLET = `Run \`npx ncrypted wallet new\` to create a payer wallet at ${"~/.config/ncrypted/wallet.key"}, send it a little USDC on Base ` +
+    "(0.005 per secret, no ETH needed), or set NCRYPTED_WALLET_PRIVATE_KEY.";
 /** Settlement attempts per create. A failed settlement never moves funds, so retrying is safe. */
 const SETTLE_ATTEMPTS = 3;
 export class Ncrypted {
@@ -69,28 +75,38 @@ export class Ncrypted {
             throw e;
         }));
     }
-    /** Encrypts locally, pays 0.005 USDC via x402, stores the ciphertext and returns a one-time link. */
+    headers(extra = {}) {
+        return { "x-ncrypted-client": `${this.opts.client ?? "sdk"}/${SDK_VERSION}`, ...extra };
+    }
+    /**
+     * Encrypts locally and stores the ciphertext, returning a one-time link. The first few secrets per day are free
+     * (TTL up to 24h, no email); after that each costs 0.005 USDC via x402 from the configured wallet.
+     */
     async create(secret, opts = {}) {
         const payFetch = await this.payer();
-        if (!payFetch) {
-            throw new Error(`No wallet configured. Run \`npx ncrypted wallet new\` to create one at ${walletPath()} and send it a little USDC on Base, ` +
-                "or set NCRYPTED_WALLET_PRIVATE_KEY.");
+        const requirePayment = opts.requirePayment || !!opts.emailTo;
+        if (!payFetch && requirePayment) {
+            throw new Error(`${opts.emailTo ? "Email delivery needs a paid secret." : "requirePayment is set but no wallet is configured."} ${NO_WALLET}`);
         }
         const { payload, key } = await encrypt(secret, opts.passphrase);
         const body = { ...payload, ttl: opts.ttl ?? 86400 };
+        // Email requires a paid secret, so skip the free tier when it's requested.
+        const headers = this.headers({ "content-type": "application/json", ...(requirePayment ? { "x-ncrypted-no-free": "1" } : {}) });
         // The link is only knowable after the server assigns an id, so email goes in a second, free call.
         let res;
         for (let attempt = 1;; attempt++) {
-            res = await payFetch(`${this.baseUrl}/api/v1/secrets`, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify(body),
-            });
+            res = await (payFetch ?? fetch)(`${this.baseUrl}/api/v1/secrets`, { method: "POST", headers, body: JSON.stringify(body) });
             // Retry only when the payment was signed but settlement failed on-chain (e.g. a facilitator RPC hiccup).
             if (res.status === 402 && settlementOf(res)?.success === false && attempt < SETTLE_ATTEMPTS)
                 continue;
             break;
         }
+        if (res.status === 402 && !payFetch) {
+            const perDay = res.headers.get("x-ncrypted-free-per-day") ?? "3";
+            const maxTtl = Number(res.headers.get("x-ncrypted-free-max-ttl") ?? 86400);
+            const why = (opts.ttl ?? 86400) > maxTtl ? `Free secrets can last at most ${maxTtl / 3600}h.` : `The ${perDay} free secrets per day are used up.`;
+            throw new NcryptedError(`${why} ${NO_WALLET}`, 402);
+        }
         if (!res.ok)
             throw await errorFrom(res);
         const data = (await res.json());
@@ -101,13 +117,154 @@ export class Ncrypted {
             await this.email(data.id, data.receiptToken, link, opts.emailTo, opts.emailNote);
             emailed = true;
         }
-        return { id: data.id, link, expiresAt: data.expiresAt, receiptToken: data.receiptToken, emailed, paymentTx };
+        return {
+            id: data.id,
+            link,
+            expiresAt: data.expiresAt,
+            receiptToken: data.receiptToken,
+            emailed,
+            paymentTx,
+            free: !!data.free,
+            ...(data.free ? { freeRemaining: data.freeRemaining } : {}),
+        };
+    }
+    /**
+     * Reads a one-time link and writes the value straight into a destination (Vercel env var, .env file), so it never
+     * passes through the caller (e.g. an LLM). The destination is checked before the secret is consumed. If writing still
+     * fails afterwards, the value is re-saved to a new one-time link, which is returned in the error.
+     */
+    async deliver(link, destination, opts = {}) {
+        const target = await prepareDestination(destination);
+        const value = await this.read(link, opts.passphrase);
+        return this.deliverOrRescue(value, target);
+    }
+    async deliverOrRescue(value, target) {
+        try {
+            return await target.deliver(value);
+        }
+        catch (e) {
+            let rescue = "";
+            try {
+                const saved = await this.create(value, { ttl: 3600 });
+                rescue = ` The value was re-saved to a new one-time link (1h): ${saved.link}`;
+            }
+            catch {
+                rescue = " Re-saving the value also failed; ask for it again.";
+            }
+            throw new Error(`Delivery failed: ${e.message}.${rescue}`);
+        }
+    }
+    /**
+     * Starts a secret request: returns a link for a human, who pastes the value into the page. It's encrypted in their
+     * browser to a key that only exists on this machine. Free. Complete it with fulfillRequest().
+     */
+    async requestSecret(label, opts = {}) {
+        const { publicKey, privateKey } = await generateRequestKeypair();
+        const res = await fetch(`${this.baseUrl}/api/v1/requests`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ publicKey, label, ttl: opts.ttl ?? 3600 }),
+        });
+        if (!res.ok)
+            throw await errorFrom(res);
+        const data = (await res.json());
+        await saveLocalRequest({ id: data.id, origin: this.baseUrl, publicKey, privateKey, pollToken: data.pollToken, label, expiresAt: data.expiresAt });
+        return { id: data.id, url: `${data.url}#${publicKey}`, expiresAt: data.expiresAt };
+    }
+    /**
+     * Waits up to waitSeconds for the human to answer a request. With a destination, the value is written there and
+     * never returned; without one, the value is returned. Resolves { status: "pending" } if not answered yet.
+     */
+    async fulfillRequest(id, opts = {}) {
+        const local = await loadLocalRequest(id);
+        const target = opts.destination ? await prepareDestination(opts.destination) : undefined;
+        const deadline = Date.now() + Math.min(opts.waitSeconds ?? 0, 300) * 1000;
+        for (;;) {
+            const res = await fetch(`${local.origin}/api/v1/requests/${id}/collect`, {
+                method: "POST",
+                headers: this.headers({ authorization: `Bearer ${local.pollToken}` }),
+            });
+            if (res.status === 410) {
+                await removeLocalRequest(id);
+                throw new NcryptedError("This request expired or was already collected.", 410);
+            }
+            if (!res.ok)
+                throw await errorFrom(res);
+            const body = (await res.json());
+            if (body.status === "fulfilled" && body.sealed) {
+                const value = await openSealed(body.sealed, local.privateKey, local.publicKey);
+                await removeLocalRequest(id);
+                if (!target)
+                    return { status: "received", value };
+                return { status: "delivered", result: await this.deliverOrRescue(value, target) };
+            }
+            if (Date.now() >= deadline)
+                return { status: "pending", expiresAt: body.expiresAt ?? local.expiresAt };
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+    }
+    /** Link to a page where the wallet's owner can send it USDC on Base. */
+    fundUrl(address, amountUsdc = 1) {
+        return `${this.baseUrl}/fund?address=${address}&amount=${amountUsdc}`;
+    }
+    /**
+     * Sets up the local payer wallet if there isn't one. Returns its address and a funding link for the owner; funding
+     * needs only the address. With backupToOwner, the private key is also put into a one-time link (24h) for the owner,
+     * so they can recover or withdraw the funds. The key itself is never returned.
+     */
+    async setupWallet(opts = {}) {
+        const existing = normalizeKey(this.opts.privateKey ?? process.env.NCRYPTED_WALLET_PRIVATE_KEY) ?? (await readWalletKey());
+        let address;
+        let created = false;
+        if (existing)
+            address = accountOf(existing).address;
+        else {
+            try {
+                address = (await createWallet()).address;
+                created = true;
+            }
+            catch (e) {
+                // Another process created it at the same moment; use that one.
+                if (e.code !== "EEXIST")
+                    throw e;
+                address = accountOf((await readWalletKey())).address;
+            }
+            this.payFetch = undefined; // pick up the new wallet on the next create()
+        }
+        const result = {
+            created,
+            address,
+            usdc: await usdcBalance(address).catch(() => 0),
+            fundUrl: this.fundUrl(address, opts.amountUsdc ?? 1),
+            keyFile: existing && !(await readWalletKey()) ? "NCRYPTED_WALLET_PRIVATE_KEY" : walletPath(),
+        };
+        if (!opts.backupToOwner)
+            return result;
+        try {
+            const key = existing ?? (await readWalletKey());
+            const backup = await this.create(`ncrypted payer wallet ${address}\nPrivate key: ${key}\nNetwork: Base`, { ttl: 86_400 });
+            return { ...result, backupLink: backup.link };
+        }
+        catch (e) {
+            return {
+                ...result,
+                backupError: `Couldn't create the backup link yet (${e.message.split(".")[0]}). ` +
+                    "Once the wallet is funded, run setup again with backup to create it.",
+            };
+        }
+    }
+    /** Free-tier allowance left today and the paid price. */
+    async quota() {
+        const res = await fetch(`${this.baseUrl}/api/v1/quota`, { headers: this.headers() });
+        if (!res.ok)
+            throw await errorFrom(res);
+        return (await res.json());
     }
     /** Sends the link by email once. Allowed only for the creator and only once per secret. */
     async email(id, receiptToken, link, to, note) {
         const res = await fetch(`${this.baseUrl}/api/v1/secrets/${id}/email`, {
             method: "POST",
-            headers: { "content-type": "application/json", authorization: `Bearer ${receiptToken}` },
+            headers: this.headers({ "content-type": "application/json", authorization: `Bearer ${receiptToken}` }),
             body: JSON.stringify({ to, link, note }),
         });
         if (!res.ok)
@@ -116,7 +273,7 @@ export class Ncrypted {
     /** Reads and destroys a secret. Free. Works with links from any ncrypted host. */
     async read(link, passphrase) {
         const { origin, id, key } = parseLink(link);
-        const res = await fetch(`${origin}/api/v1/secrets/${id}/reveal`, { method: "POST" });
+        const res = await fetch(`${origin}/api/v1/secrets/${id}/reveal`, { method: "POST", headers: this.headers() });
         if (res.status === 410 || res.status === 404) {
             throw new NcryptedError("This secret has already been read, burned, or has expired.", 410);
         }
@@ -128,7 +285,7 @@ export class Ncrypted {
     /** Whether the secret has been read yet. Needs the creator's receipt token. */
     async status(id, receiptToken) {
         const res = await fetch(`${this.baseUrl}/api/v1/secrets/${id}/status`, {
-            headers: { authorization: `Bearer ${receiptToken}` },
+            headers: this.headers({ authorization: `Bearer ${receiptToken}` }),
         });
         if (!res.ok)
             throw await errorFrom(res);
@@ -138,7 +295,7 @@ export class Ncrypted {
     async burn(id, receiptToken) {
         const res = await fetch(`${this.baseUrl}/api/v1/secrets/${id}`, {
             method: "DELETE",
-            headers: { authorization: `Bearer ${receiptToken}` },
+            headers: this.headers({ authorization: `Bearer ${receiptToken}` }),
         });
         if (!res.ok)
             throw await errorFrom(res);

package/dist/crypto.d.ts

@@ -23,3 +23,24 @@ export declare function parseLink(link: string): {
     id: string;
     key: string;
 };
+export interface SealedPayload {
+    v: number;
+    epk: string;
+    iv: string;
+    ciphertext: string;
+}
+/** New X25519 keypair for a secret request. publicKey goes in the request link's #fragment; keep privateKey local. */
+export declare function generateRequestKeypair(): Promise<{
+    publicKey: string;
+    privateKey: JsonWebKey;
+}>;
+/** Seals plaintext so only the holder of the request's private key can open it. Used by the request page. */
+export declare function sealToPublicKey(plaintext: string, publicKey: string): Promise<SealedPayload>;
+/** Opens a sealed payload with the request's private key. Throws if it was tampered with or sealed to another key. */
+export declare function openSealed(sealed: SealedPayload, privateKey: JsonWebKey, publicKey: string): Promise<string>;
+/** Splits a request link: https://host/r/{id}#{publicKey} */
+export declare function parseRequestLink(link: string): {
+    origin: string;
+    id: string;
+    publicKey: string;
+};