ncrypted 0.1.1 → 0.2.0

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import { privateKeyToAccount } from "viem/accounts";
 import { Ncrypted } from "./client.js";
+import { createWallet, normalizeKey, readWalletKey, usdcBalance, walletPath } from "./wallet.js";
 const HELP = `ncrypted - one-time, end-to-end encrypted secrets for agents (0.005 USDC per secret, reads free)
 
 Usage:
@@ -9,8 +11,18 @@ 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
 
-Env: NCRYPTED_WALLET_PRIVATE_KEY (Base wallet with USDC, needed for create), NCRYPTED_URL (optional)`;
+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) {
     if (!v)
         return undefined;
@@ -37,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": {
@@ -68,6 +89,56 @@ 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) => {
+                    if (e.code === "EEXIST")
+                        throw new Error(`A wallet already exists at ${walletPath()}`);
+                    throw e;
+                });
+                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());
+            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, paidSecretsAvailable: Math.floor(usdc / 0.005), freeRemainingToday: freeRemaining });
+            break;
+        }
         default:
             console.log(HELP);
     }

package/dist/client.d.ts

@@ -1,13 +1,20 @@
-export declare const DEFAULT_BASE_URL = "https://ncrypted-ai.vercel.app";
+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.2.0";
 export interface NcryptedOptions {
     /** API origin. Defaults to NCRYPTED_URL or the hosted service. */
     baseUrl?: string;
-    /** 0x-prefixed EVM private key of a wallet holding USDC on Base. Defaults to NCRYPTED_WALLET_PRIVATE_KEY. */
+    /**
+     * 0x-prefixed EVM private key of a wallet holding USDC on Base. Defaults to NCRYPTED_WALLET_PRIVATE_KEY,
+     * then the key file at NCRYPTED_WALLET_FILE or ~/.config/ncrypted/wallet.key (create one with `npx ncrypted wallet new`).
+     */
     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. */
@@ -18,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;
@@ -29,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 {
@@ -36,11 +58,76 @@ export declare class NcryptedError extends Error {
     constructor(message: string, status: number);
 }
 export declare class Ncrypted {
+    private readonly opts;
     readonly baseUrl: string;
     private payFetch?;
     constructor(opts?: NcryptedOptions);
-    /** Encrypts locally, pays 0.005 USDC via x402, stores the ciphertext and returns a one-time link. */
+    /** Resolves the paying fetch lazily, so a missing or bad wallet only affects create(), never reads. */
+    private payer;
+    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,10 +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";
-export const DEFAULT_BASE_URL = "https://ncrypted-ai.vercel.app";
+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.2.0";
 export class NcryptedError extends Error {
     status;
     constructor(message, status) {
@@ -39,45 +44,69 @@ 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 {
+    opts;
     baseUrl;
     payFetch;
     constructor(opts = {}) {
+        this.opts = opts;
         const env = typeof process !== "undefined" ? process.env : {};
         this.baseUrl = (opts.baseUrl ?? env.NCRYPTED_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-        const pk = opts.privateKey ?? env.NCRYPTED_WALLET_PRIVATE_KEY;
-        if (opts.paymentFetch)
-            this.payFetch = opts.paymentFetch;
-        else if (pk) {
-            const account = privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`));
-            this.payFetch = wrapFetchWithPaymentFromConfig(fetch, {
-                schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
+    }
+    /** Resolves the paying fetch lazily, so a missing or bad wallet only affects create(), never reads. */
+    payer() {
+        return (this.payFetch ??= (async () => {
+            if (this.opts.paymentFetch)
+                return this.opts.paymentFetch;
+            const env = typeof process !== "undefined" ? process.env : {};
+            const pk = normalizeKey(this.opts.privateKey ?? env.NCRYPTED_WALLET_PRIVATE_KEY) ?? (await readWalletKey());
+            if (!pk)
+                return undefined;
+            return wrapFetchWithPaymentFromConfig(fetch, {
+                schemes: [{ network: "eip155:*", client: new ExactEvmScheme(privateKeyToAccount(pk)) }],
                 spendControls: { maxAmountPerPayment: MAX_PRICE },
             });
-        }
+        })().catch((e) => {
+            this.payFetch = undefined;
+            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 = {}) {
-        if (!this.payFetch) {
-            throw new Error("No wallet configured. Set NCRYPTED_WALLET_PRIVATE_KEY (a Base wallet with USDC) or pass privateKey.");
+        const payFetch = await this.payer();
+        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 this.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());
@@ -88,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)
@@ -103,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);
         }
@@ -115,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);
@@ -125,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;
+};

package/dist/crypto.js

@@ -72,3 +72,64 @@ export function parseLink(link) {
         throw new Error("Not a valid ncrypted link (expected https://host/s/{id}#{key})");
     return { origin: url.origin, id: m[1], key };
 }
+// ---- Secret requests: a human seals a value to the requesting agent's X25519 public key. ----
+const REQUEST_INFO = new TextEncoder().encode("ncrypted request v1");
+/** New X25519 keypair for a secret request. publicKey goes in the request link's #fragment; keep privateKey local. */
+export async function generateRequestKeypair() {
+    const kp = (await crypto.subtle.generateKey({ name: "X25519" }, true, ["deriveBits"]));
+    const raw = new Uint8Array(await crypto.subtle.exportKey("raw", kp.publicKey));
+    return { publicKey: toB64url(raw), privateKey: await crypto.subtle.exportKey("jwk", kp.privateKey) };
+}
+async function requestKey(shared, epk, pk) {
+    const salt = new Uint8Array(epk.length + pk.length);
+    salt.set(epk);
+    salt.set(pk, epk.length);
+    const base = await crypto.subtle.importKey("raw", shared, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt, info: REQUEST_INFO }, base, { name: "AES-GCM", length: 256 }, false, [
+        "encrypt",
+        "decrypt",
+    ]);
+}
+/** Seals plaintext so only the holder of the request's private key can open it. Used by the request page. */
+export async function sealToPublicKey(plaintext, publicKey) {
+    const data = new TextEncoder().encode(plaintext);
+    if (data.length === 0)
+        throw new Error("Secret is empty");
+    if (data.length > MAX_PLAINTEXT_BYTES)
+        throw new Error(`Secret exceeds ${MAX_PLAINTEXT_BYTES} bytes`);
+    const pk = fromB64url(publicKey);
+    if (pk.length !== 32)
+        throw new Error("Invalid request public key");
+    const recipient = await crypto.subtle.importKey("raw", pk, { name: "X25519" }, false, []);
+    const eph = (await crypto.subtle.generateKey({ name: "X25519" }, true, ["deriveBits"]));
+    const epk = new Uint8Array(await crypto.subtle.exportKey("raw", eph.publicKey));
+    const shared = await crypto.subtle.deriveBits({ name: "X25519", public: recipient }, eph.privateKey, 256);
+    const key = await requestKey(shared, epk, pk);
+    const iv = randomBytes(12);
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, data));
+    return { v: VERSION, epk: toB64url(epk), iv: toB64url(iv), ciphertext: toB64url(ct) };
+}
+/** Opens a sealed payload with the request's private key. Throws if it was tampered with or sealed to another key. */
+export async function openSealed(sealed, privateKey, publicKey) {
+    const priv = await crypto.subtle.importKey("jwk", privateKey, { name: "X25519" }, false, ["deriveBits"]);
+    const epk = fromB64url(sealed.epk);
+    const eph = await crypto.subtle.importKey("raw", epk, { name: "X25519" }, false, []);
+    const shared = await crypto.subtle.deriveBits({ name: "X25519", public: eph }, priv, 256);
+    const key = await requestKey(shared, epk, fromB64url(publicKey));
+    try {
+        const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromB64url(sealed.iv) }, key, fromB64url(sealed.ciphertext));
+        return new TextDecoder().decode(pt);
+    }
+    catch {
+        throw new Error("Could not open the submitted secret: it was tampered with or sealed to a different key");
+    }
+}
+/** Splits a request link: https://host/r/{id}#{publicKey} */
+export function parseRequestLink(link) {
+    const url = new URL(link);
+    const m = url.pathname.match(/^\/r\/([A-Za-z0-9_-]{16,64})\/?$/);
+    const publicKey = url.hash.slice(1);
+    if (!m || !publicKey)
+        throw new Error("Not a valid ncrypted request link (expected https://host/r/{id}#{publicKey})");
+    return { origin: url.origin, id: m[1], publicKey };
+}

package/dist/destinations.d.ts

@@ -0,0 +1,35 @@
+export type VercelTarget = "production" | "preview" | "development";
+export interface VercelEnvDestination {
+    type: "vercel_env";
+    /** Env var name, e.g. STRIPE_SECRET_KEY. */
+    key: string;
+    /** Project name or id. Defaults to the project linked in <cwd>/.vercel/project.json. */
+    project?: string;
+    /** Team id (team_...) or slug. Defaults to the linked project's org. */
+    team?: string;
+    /** Default: production and preview. */
+    targets?: VercelTarget[];
+    /** Directory containing .vercel/project.json. Default: process.cwd(). */
+    cwd?: string;
+    comment?: string;
+}
+export interface DotenvDestination {
+    type: "dotenv";
+    key: string;
+    /** Path to the .env file. Default: ./.env */
+    path?: string;
+}
+export type Destination = VercelEnvDestination | DotenvDestination;
+export interface DeliveryResult {
+    destination: string;
+    key: string;
+    details: Record<string, unknown>;
+}
+export interface PreparedDestination {
+    deliver(value: string): Promise<DeliveryResult>;
+}
+/**
+ * Validates a destination (auth, project access, names) without touching the secret.
+ * Call this before consuming a one-time secret so a bad destination doesn't destroy it.
+ */
+export declare function prepareDestination(d: Destination): Promise<PreparedDestination>;

package/dist/destinations.js

@@ -0,0 +1,146 @@
+// Node-only destinations that receive a secret's value directly, so it never passes through the model.
+import { readFile, writeFile, chmod } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { homedir, platform } from "node:os";
+import { join, resolve, dirname } from "node:path";
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function checkKey(key) {
+    if (!KEY_RE.test(key))
+        throw new Error(`Invalid variable name "${key}" (letters, digits and _, not starting with a digit)`);
+}
+// ---------------- Vercel ----------------
+function vercelAuthPath() {
+    if (process.env.VERCEL_AUTH_FILE)
+        return process.env.VERCEL_AUTH_FILE;
+    if (platform() === "darwin")
+        return join(homedir(), "Library", "Application Support", "com.vercel.cli", "auth.json");
+    if (platform() === "win32")
+        return join(process.env.APPDATA ?? homedir(), "com.vercel.cli", "auth.json");
+    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "com.vercel.cli", "auth.json");
+}
+/** VERCEL_TOKEN, else the Vercel CLI's login session (`vercel login`). */
+async function vercelToken() {
+    if (process.env.VERCEL_TOKEN)
+        return process.env.VERCEL_TOKEN;
+    let auth;
+    try {
+        auth = JSON.parse(await readFile(vercelAuthPath(), "utf8"));
+    }
+    catch {
+        throw new Error("Not logged in to Vercel. Run `vercel login` (or set VERCEL_TOKEN) and try again.");
+    }
+    if (!auth.token)
+        throw new Error("Not logged in to Vercel. Run `vercel login` (or set VERCEL_TOKEN) and try again.");
+    if (auth.expiresAt && auth.expiresAt * (auth.expiresAt < 1e12 ? 1000 : 1) < Date.now() + 60_000) {
+        throw new Error("Your Vercel CLI session has expired. Run `vercel whoami` to refresh it (or set VERCEL_TOKEN) and try again.");
+    }
+    return auth.token;
+}
+async function linkedProject(cwd) {
+    try {
+        return JSON.parse(await readFile(join(cwd, ".vercel", "project.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function vercelApi(r, method, path, body) {
+    const res = await fetch(`https://api.vercel.com${path}${path.includes("?") ? "&" : "?"}${r.query}`, {
+        method,
+        headers: { authorization: `Bearer ${r.token}`, "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(`Vercel API ${res.status}: ${data.error?.message ?? res.statusText}`);
+    return data;
+}
+async function resolveVercel(d) {
+    checkKey(d.key);
+    const token = await vercelToken();
+    const linked = await linkedProject(d.cwd ?? process.cwd());
+    const project = d.project ?? linked?.projectId;
+    if (!project)
+        throw new Error("No Vercel project given and no .vercel/project.json here. Pass `project` (name or id) or run `vercel link`.");
+    const team = d.team ?? (d.project ? undefined : linked?.orgId);
+    const query = team ? (team.startsWith("team_") ? `teamId=${encodeURIComponent(team)}` : `slug=${encodeURIComponent(team)}`) : "";
+    const targets = d.targets?.length ? [...new Set(d.targets)] : ["production", "preview"];
+    return { token, project, query, targets };
+}
+/** Checks auth and project access before a one-time secret is consumed. */
+async function preflightVercel(d) {
+    const r = await resolveVercel(d);
+    await vercelApi(r, "GET", `/v9/projects/${encodeURIComponent(r.project)}`);
+    return r;
+}
+async function deliverVercel(value, d, r) {
+    // Sensitive vars can't target development; use encrypted there.
+    const sensitiveTargets = r.targets.filter((t) => t !== "development");
+    const entries = [
+        ...(sensitiveTargets.length ? [{ key: d.key, value, type: "sensitive", target: sensitiveTargets }] : []),
+        ...(r.targets.includes("development") ? [{ key: d.key, value, type: "encrypted", target: ["development"] }] : []),
+    ].map((e) => ({ ...e, comment: d.comment ?? "Set via ncrypted (value never shown to the agent)" }));
+    await vercelApi(r, "POST", `/v10/projects/${encodeURIComponent(r.project)}/env?upsert=true`, entries.length === 1 ? entries[0] : entries);
+    return {
+        destination: "vercel_env",
+        key: d.key,
+        details: {
+            project: r.project,
+            targets: r.targets,
+            type: sensitiveTargets.length ? "sensitive" : "encrypted",
+            note: "Redeploy for the new value to take effect.",
+        },
+    };
+}
+// ---------------- .env file ----------------
+function quoteEnv(value) {
+    if (/^[A-Za-z0-9_./:@+-]*$/.test(value))
+        return value;
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+}
+function gitIgnored(path) {
+    return new Promise((done) => execFile("git", ["check-ignore", "-q", path], { cwd: dirname(path) }, (err) => {
+        if (!err)
+            return done(true);
+        done(err.code === 1 ? false : undefined); // 128: not a git repo
+    }));
+}
+async function deliverDotenv(value, d) {
+    checkKey(d.key);
+    const path = resolve(d.path ?? ".env");
+    let text = "";
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch { }
+    const line = `${d.key}=${quoteEnv(value)}`;
+    const re = new RegExp(`^(export\\s+)?${d.key}=.*$`, "m");
+    text = re.test(text) ? text.replace(re, line) : `${text}${text && !text.endsWith("\n") ? "\n" : ""}${line}\n`;
+    await writeFile(path, text, { mode: 0o600 });
+    await chmod(path, 0o600);
+    const ignored = await gitIgnored(path);
+    return {
+        destination: "dotenv",
+        key: d.key,
+        details: {
+            path,
+            gitIgnored: ignored,
+            ...(ignored === false ? { warning: `${path} is NOT git-ignored. Add it to .gitignore before committing.` } : {}),
+        },
+    };
+}
+/**
+ * Validates a destination (auth, project access, names) without touching the secret.
+ * Call this before consuming a one-time secret so a bad destination doesn't destroy it.
+ */
+export async function prepareDestination(d) {
+    if (d.type === "vercel_env") {
+        const r = await preflightVercel(d);
+        return { deliver: (v) => deliverVercel(v, d, r) };
+    }
+    if (d.type === "dotenv") {
+        checkKey(d.key);
+        return { deliver: (v) => deliverDotenv(v, d) };
+    }
+    throw new Error(`Unknown destination type "${d.type}"`);
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./client.js";
-export { encrypt, decrypt, parseLink, MAX_PLAINTEXT_BYTES, type EncryptedPayload } from "./crypto.js";
+export { encrypt, decrypt, parseLink, parseRequestLink, sealToPublicKey, MAX_PLAINTEXT_BYTES, type EncryptedPayload, type SealedPayload } from "./crypto.js";
+export type { Destination, VercelEnvDestination, DotenvDestination, DeliveryResult, VercelTarget } from "./destinations.js";
+export { walletPath, createWallet, usdcBalance } from "./wallet.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from "./client.js";
-export { encrypt, decrypt, parseLink, MAX_PLAINTEXT_BYTES } from "./crypto.js";
+export { encrypt, decrypt, parseLink, parseRequestLink, sealToPublicKey, MAX_PLAINTEXT_BYTES } from "./crypto.js";
+export { walletPath, createWallet, usdcBalance } from "./wallet.js";

package/dist/localRequests.d.ts

@@ -0,0 +1,13 @@
+export interface LocalRequest {
+    id: string;
+    origin: string;
+    publicKey: string;
+    privateKey: JsonWebKey;
+    pollToken: string;
+    label: string;
+    expiresAt: string;
+}
+export declare function requestsDir(): string;
+export declare function saveLocalRequest(r: LocalRequest): Promise<void>;
+export declare function loadLocalRequest(id: string): Promise<LocalRequest>;
+export declare const removeLocalRequest: (id: string) => Promise<void>;

package/dist/localRequests.js

@@ -0,0 +1,25 @@
+// Node-only storage for the private keys of pending secret requests (one 0600 file per request).
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function requestsDir() {
+    return process.env.NCRYPTED_REQUESTS_DIR || join(homedir(), ".config", "ncrypted", "requests");
+}
+const fileFor = (id) => {
+    if (!/^[A-Za-z0-9_-]{16,64}$/.test(id))
+        throw new Error("Invalid request id");
+    return join(requestsDir(), `${id}.json`);
+};
+export async function saveLocalRequest(r) {
+    await mkdir(requestsDir(), { recursive: true, mode: 0o700 });
+    await writeFile(fileFor(r.id), JSON.stringify(r), { mode: 0o600 });
+}
+export async function loadLocalRequest(id) {
+    try {
+        return JSON.parse(await readFile(fileFor(id), "utf8"));
+    }
+    catch {
+        throw new Error(`No pending request ${id} on this machine (it was collected already, or created elsewhere).`);
+    }
+}
+export const removeLocalRequest = (id) => rm(fileFor(id), { force: true });

package/dist/wallet.d.ts

@@ -0,0 +1,13 @@
+export declare const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** NCRYPTED_WALLET_FILE, or ~/.config/ncrypted/wallet.key */
+export declare function walletPath(): string;
+/** Normalizes a private key, or returns undefined for empty or unexpanded "${VAR}" placeholders. */
+export declare function normalizeKey(raw: string | undefined): `0x${string}` | undefined;
+export declare function readWalletKey(): Promise<`0x${string}` | undefined>;
+/** Creates a new wallet key file (mode 0600). Refuses to overwrite an existing one. */
+export declare function createWallet(): Promise<{
+    address: string;
+    path: string;
+}>;
+/** USDC balance on Base mainnet, via a public RPC. */
+export declare function usdcBalance(address: string, rpc?: string): Promise<number>;

package/dist/wallet.js

@@ -0,0 +1,49 @@
+// Node-only helpers for the local payer wallet used to pay for secrets.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+export const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** NCRYPTED_WALLET_FILE, or ~/.config/ncrypted/wallet.key */
+export function walletPath() {
+    return process.env.NCRYPTED_WALLET_FILE || join(homedir(), ".config", "ncrypted", "wallet.key");
+}
+/** Normalizes a private key, or returns undefined for empty or unexpanded "${VAR}" placeholders. */
+export function normalizeKey(raw) {
+    const v = raw?.trim();
+    if (!v || v.startsWith("${") || v.startsWith("$"))
+        return undefined;
+    const hex = v.startsWith("0x") ? v : `0x${v}`;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hex))
+        throw new Error("Wallet private key must be 32 bytes of hex (0x + 64 hex characters)");
+    return hex;
+}
+export async function readWalletKey() {
+    try {
+        return normalizeKey(await readFile(walletPath(), "utf8"));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+/** Creates a new wallet key file (mode 0600). Refuses to overwrite an existing one. */
+export async function createWallet() {
+    const path = walletPath();
+    const key = generatePrivateKey();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${key}\n`, { mode: 0o600, flag: "wx" });
+    return { address: privateKeyToAccount(key).address, path };
+}
+/** USDC balance on Base mainnet, via a public RPC. */
+export async function usdcBalance(address, rpc = "https://mainnet.base.org") {
+    const data = `0x70a08231${address.slice(2).toLowerCase().padStart(64, "0")}`;
+    const res = await fetch(rpc, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: USDC_BASE, data }, "latest"] }),
+    });
+    const { result } = (await res.json());
+    return Number(BigInt(result)) / 1e6;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncrypted",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "One-time, end-to-end encrypted secrets for AI agents. Pay 0.005 USDC per secret via x402; the note self-destructs after one read.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,10 @@
     "./crypto": {
       "types": "./dist/crypto.d.ts",
       "default": "./dist/crypto.js"
+    },
+    "./wallet": {
+      "types": "./dist/wallet.d.ts",
+      "default": "./dist/wallet.js"
     }
   },
   "bin": {