ncrypted 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seidl Family
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# ncrypted
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK and CLI for [ncrypted](https://github.com/Seidl-Family/ncrypted): one-time, end-to-end encrypted secrets for AI agents. 0.005 USDC per secret over x402 (Base); reading is free.
+
+```ts
+import { Ncrypted } from "ncrypted";
+const nc = new Ncrypted({ privateKey: process.env.NCRYPTED_WALLET_PRIVATE_KEY });
+const { link } = await nc.create("hunter2", { ttl: 3600, emailTo: "ops@example.com" });
+const value = await nc.read(link);
+```
+
+```sh
+echo "hunter2" | npx ncrypted create --ttl 1h
+npx ncrypted read "<link>"
+```
+
+See the [main README](https://github.com/Seidl-Family/ncrypted) for details.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { Ncrypted } from "./client.js";
+const HELP = `ncrypted - one-time, end-to-end encrypted secrets for agents (0.005 USDC per secret, reads free)
+
+Usage:
+  ncrypted create [--ttl 1h] [--passphrase X] [--email to@x.com] [--note "..."] < secret.txt
+  ncrypted create --text "secret value"
+  ncrypted read <link> [--passphrase X]
+  ncrypted status <id> --receipt <token>
+  ncrypted burn <id> --receipt <token>
+
+Env: NCRYPTED_WALLET_PRIVATE_KEY (Base wallet with USDC, needed for create), NCRYPTED_URL (optional)`;
+function parseTtl(v) {
+    if (!v)
+        return undefined;
+    const m = v.match(/^(\d+)([smhd]?)$/);
+    if (!m)
+        throw new Error(`Bad --ttl "${v}" (use e.g. 30m, 1h, 7d)`);
+    return Number(m[1]) * { "": 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2]];
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(c);
+    return Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
+}
+async function main() {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        options: {
+            ttl: { type: "string" },
+            passphrase: { type: "string" },
+            email: { type: "string" },
+            note: { type: "string" },
+            text: { type: "string" },
+            receipt: { type: "string" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const [cmd, arg] = positionals;
+    const client = new Ncrypted();
+    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": {
+            const text = values.text ?? (await readStdin());
+            if (!text)
+                throw new Error("Provide the secret on stdin or with --text");
+            out(await client.create(text, { ttl: parseTtl(values.ttl), passphrase: values.passphrase, emailTo: values.email, emailNote: values.note }));
+            break;
+        }
+        case "read":
+            if (!arg)
+                throw new Error("Usage: ncrypted read <link>");
+            out(await client.read(arg, values.passphrase));
+            break;
+        case "status":
+            if (!arg || !values.receipt)
+                throw new Error("Usage: ncrypted status <id> --receipt <token>");
+            out(await client.status(arg, values.receipt));
+            break;
+        case "burn":
+            if (!arg || !values.receipt)
+                throw new Error("Usage: ncrypted burn <id> --receipt <token>");
+            await client.burn(arg, values.receipt);
+            out({ burned: true });
+            break;
+        default:
+            console.log(HELP);
+    }
+}
+main().catch((e) => {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+export declare const DEFAULT_BASE_URL = "https://ncrypted-ai.vercel.app";
+/** Hard cap on what the SDK will ever pay for one secret, whatever the server asks. */
+export declare const MAX_PRICE = "$0.01";
+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. */
+    privateKey?: string;
+    /** Bring your own x402-paying fetch instead of a private key. */
+    paymentFetch?: typeof fetch;
+}
+export interface CreateOptions {
+    /** Lifetime in seconds, 300 to 604800 (7 days). Default 86400. */
+    ttl?: number;
+    /** Extra secret the recipient must also know. Share it through a different channel than the link. */
+    passphrase?: string;
+    /** Email the link to this address. The server sees the link (including key) for that one request. */
+    emailTo?: string;
+    /** Optional short note shown in the email, e.g. "DB password for staging". Never put the secret here. */
+    emailNote?: string;
+}
+export interface CreatedSecret {
+    id: string;
+    /** Full share link including the decryption key in the #fragment. Treat it like the secret itself. */
+    link: string;
+    expiresAt: string;
+    /** Lets the creator check status or burn the secret. Not needed by the recipient. */
+    receiptToken: string;
+    emailed: boolean;
+    /** On-chain settlement transaction hash, if reported. */
+    paymentTx?: string;
+}
+export type SecretStatus = "pending" | "read" | "burned" | "expired";
+export declare class NcryptedError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class Ncrypted {
+    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. */
+    create(secret: string, opts?: CreateOptions): Promise<CreatedSecret>;
+    /** 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. */
+    read(link: string, passphrase?: string): Promise<string>;
+    /** Whether the secret has been read yet. Needs the creator's receipt token. */
+    status(id: string, receiptToken: string): Promise<{
+        status: SecretStatus;
+        readAt?: string;
+        expiresAt?: string;
+    }>;
+    /** Destroys an unread secret early. Needs the creator's receipt token. */
+    burn(id: string, receiptToken: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,133 @@
+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";
+/** Hard cap on what the SDK will ever pay for one secret, whatever the server asks. */
+export const MAX_PRICE = "$0.01";
+export class NcryptedError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+function settlementOf(res) {
+    const header = res.headers.get("payment-response") ?? res.headers.get("x-payment-response");
+    if (!header)
+        return undefined;
+    try {
+        return decodePaymentResponseHeader(header);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function errorFrom(res) {
+    let msg = res.statusText;
+    try {
+        const body = (await res.json());
+        if (body.error)
+            msg = body.error;
+    }
+    catch { }
+    if (res.status === 402) {
+        const reason = settlementOf(res)?.errorReason;
+        msg = reason
+            ? `Payment settlement failed (${reason}). You were not charged.`
+            : `Payment required (${msg}). Check the wallet holds USDC on Base.`;
+    }
+    return new NcryptedError(msg, res.status);
+}
+/** Settlement attempts per create. A failed settlement never moves funds, so retrying is safe. */
+const SETTLE_ATTEMPTS = 3;
+export class Ncrypted {
+    baseUrl;
+    payFetch;
+    constructor(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) }],
+                spendControls: { maxAmountPerPayment: MAX_PRICE },
+            });
+        }
+    }
+    /** Encrypts locally, pays 0.005 USDC via x402, stores the ciphertext and returns a one-time link. */
+    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 { payload, key } = await encrypt(secret, opts.passphrase);
+        const body = { ...payload, ttl: opts.ttl ?? 86400 };
+        // 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),
+            });
+            // 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.ok)
+            throw await errorFrom(res);
+        const data = (await res.json());
+        const link = `${data.url}#${key}`;
+        const paymentTx = settlementOf(res)?.transaction;
+        let emailed = false;
+        if (opts.emailTo) {
+            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 };
+    }
+    /** 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}` },
+            body: JSON.stringify({ to, link, note }),
+        });
+        if (!res.ok)
+            throw await errorFrom(res);
+    }
+    /** 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" });
+        if (res.status === 410 || res.status === 404) {
+            throw new NcryptedError("This secret has already been read, burned, or has expired.", 410);
+        }
+        if (!res.ok)
+            throw await errorFrom(res);
+        const payload = (await res.json());
+        return decrypt(payload, key, passphrase);
+    }
+    /** 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}` },
+        });
+        if (!res.ok)
+            throw await errorFrom(res);
+        return (await res.json());
+    }
+    /** Destroys an unread secret early. Needs the creator's receipt token. */
+    async burn(id, receiptToken) {
+        const res = await fetch(`${this.baseUrl}/api/v1/secrets/${id}`, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${receiptToken}` },
+        });
+        if (!res.ok)
+            throw await errorFrom(res);
+    }
+}

package/dist/crypto.d.ts

@@ -0,0 +1,25 @@
+export declare const VERSION = 1;
+export declare const MAX_PLAINTEXT_BYTES: number;
+export interface EncryptedPayload {
+    v: number;
+    ciphertext: string;
+    iv: string;
+    salt: string;
+    hasPassphrase: boolean;
+}
+export declare function toB64url(bytes: Uint8Array): string;
+export declare function fromB64url(s: string): Uint8Array<ArrayBuffer>;
+export declare function randomBytes(n: number): Uint8Array<ArrayBuffer>;
+/** Encrypts plaintext with a fresh random link key. Returns the payload for the server and the key for the URL fragment. */
+export declare function encrypt(plaintext: string, passphrase?: string): Promise<{
+    payload: EncryptedPayload;
+    key: string;
+}>;
+/** Decrypts a payload with the link key (and passphrase if one was set). Throws on a wrong key, passphrase or tampered data. */
+export declare function decrypt(payload: EncryptedPayload, linkKey: string, passphrase?: string): Promise<string>;
+/** Splits a share link into its id and key: https://host/s/{id}#{key} */
+export declare function parseLink(link: string): {
+    origin: string;
+    id: string;
+    key: string;
+};

package/dist/crypto.js

@@ -0,0 +1,74 @@
+// Isomorphic (Node 20+ / browser) zero-knowledge encryption for ncrypted.
+// The 256-bit link key never leaves the client; the server only sees ciphertext.
+export const VERSION = 1;
+export const MAX_PLAINTEXT_BYTES = 64 * 1024;
+const PBKDF2_ITERATIONS = 600_000;
+const INFO = new TextEncoder().encode("ncrypted v1");
+export function toB64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function fromB64url(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+export function randomBytes(n) {
+    return crypto.getRandomValues(new Uint8Array(n));
+}
+async function deriveKey(linkKey, salt, passphrase) {
+    let ikm = new Uint8Array(linkKey);
+    if (passphrase) {
+        const pw = await crypto.subtle.importKey("raw", new TextEncoder().encode(passphrase), "PBKDF2", false, ["deriveBits"]);
+        const stretched = new Uint8Array(await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations: PBKDF2_ITERATIONS }, pw, 256));
+        ikm = new Uint8Array(linkKey.length + stretched.length);
+        ikm.set(linkKey);
+        ikm.set(stretched, linkKey.length);
+    }
+    const base = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt, info: INFO }, base, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+/** Encrypts plaintext with a fresh random link key. Returns the payload for the server and the key for the URL fragment. */
+export async function encrypt(plaintext, passphrase) {
+    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 linkKey = randomBytes(32);
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = await deriveKey(linkKey, salt, passphrase);
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, data));
+    return {
+        payload: { v: VERSION, ciphertext: toB64url(ct), iv: toB64url(iv), salt: toB64url(salt), hasPassphrase: !!passphrase },
+        key: toB64url(linkKey),
+    };
+}
+/** Decrypts a payload with the link key (and passphrase if one was set). Throws on a wrong key, passphrase or tampered data. */
+export async function decrypt(payload, linkKey, passphrase) {
+    if (payload.hasPassphrase && !passphrase)
+        throw new Error("This secret requires a passphrase");
+    const key = await deriveKey(fromB64url(linkKey), fromB64url(payload.salt), payload.hasPassphrase ? passphrase : undefined);
+    try {
+        const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromB64url(payload.iv) }, key, fromB64url(payload.ciphertext));
+        return new TextDecoder().decode(pt);
+    }
+    catch {
+        throw new Error("Decryption failed: wrong key or passphrase, or the data was tampered with");
+    }
+}
+/** Splits a share link into its id and key: https://host/s/{id}#{key} */
+export function parseLink(link) {
+    const url = new URL(link);
+    const m = url.pathname.match(/^\/s\/([A-Za-z0-9_-]{16,64})\/?$/);
+    const key = url.hash.slice(1);
+    if (!m || !key)
+        throw new Error("Not a valid ncrypted link (expected https://host/s/{id}#{key})");
+    return { origin: url.origin, id: m[1], key };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export { encrypt, decrypt, parseLink, MAX_PLAINTEXT_BYTES, type EncryptedPayload } from "./crypto.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export { encrypt, decrypt, parseLink, MAX_PLAINTEXT_BYTES } from "./crypto.js";

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "ncrypted",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./crypto": {
+      "types": "./dist/crypto.d.ts",
+      "default": "./dist/crypto.js"
+    }
+  },
+  "bin": {
+    "ncrypted": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "secrets",
+    "one-time",
+    "x402",
+    "agents",
+    "mcp",
+    "encryption",
+    "usdc"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@x402/evm": "^2.28.0",
+    "@x402/fetch": "^2.28.0",
+    "viem": "^2.57.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^5.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seidl-Family/ncrypted.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/Seidl-Family/ncrypted",
+  "publishConfig": {
+    "access": "public"
+  }
+}