@cloakely/sdk 0.8.0 → 0.8.1

package/dist/private/client.d.ts

@@ -104,6 +104,8 @@ export declare class CloakPrivate {
     private state;
     /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
     sync(pool: Address): Promise<OwnedNote[]>;
+    /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
+    history(pool: Address): Promise<OwnedNote[]>;
     balance(pool: Address): Promise<bigint>;
     /** The most a single relayed call of this kind can move from `pool`: the balance minus the relayer's fee. */
     maxSpendable(pool: Address, kind?: RelayKind): Promise<bigint>;

package/dist/private/client.js

@@ -249,6 +249,11 @@ export class CloakPrivate {
         s.notes.forEach((x, i) => (x.spent = Boolean(flags[i])));
         return s.notes.filter((x) => !x.spent);
     }
+    /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
+    async history(pool) {
+        await this.sync(pool);
+        return [...this.state(pool).notes];
+    }
     async balance(pool) {
         return (await this.sync(pool)).reduce((a, x) => a + x.amount, 0n);
     }

package/dist/private/links.d.ts

@@ -22,6 +22,18 @@ export declare const newLinkSecret: () => Uint8Array;
 export declare function linkKeys(secret: Uint8Array, passcode?: string): Promise<CloakKeys>;
 /** The cloak: address a link's money is sent to. */
 export declare function linkAddress(keys: CloakKeys): Promise<string>;
+/** The 8-hex-digit check a locked link carries: the first 4 bytes of a hash of the account the passcode opens. */
+export declare function linkCheck(keys: CloakKeys): Promise<string>;
+/** Thrown when a link's check says the passcode is wrong. */
+export declare class WrongPasscodeError extends Error {
+    constructor(riddle: boolean);
+}
+/**
+ * Opens a link's account. A locked link with a check tries the code (and the ways a phone may have mangled it) and
+ * throws WrongPasscodeError if none matches, without touching the network. A link without a check (made before
+ * checks existed) opens with the code as typed; an empty account is then all a wrong code looks like.
+ */
+export declare function openLinkKeys(l: ClaimLink, passcode?: string): Promise<CloakKeys>;
 export interface ClaimLink {
     secret: Uint8Array;
     /** Block the link was funded in. Shown to the claimer; scanning still starts at the vaults' first block, because
@@ -40,7 +52,15 @@ export interface ClaimLink {
     hint?: string;
     /** Split into this many equal shares: each person who opens the link claims one (a red envelope). */
     shares?: number;
+    /** A short check of the account a passcode opens, so a wrong passcode is caught on the device, before any
+     *  network call. It tells a guesser nothing a copy of the link didn't already: each guess still costs a full scrypt. */
+    check?: string;
 }
+/**
+ * A claim link: https://cloak.boblabs.tech/claim#c<letters and digits>. Everything after the # is one run of letters
+ * and digits (base 62), because chat apps end a link at characters like "-", "_", "." or "%" (WhatsApp and Telegram
+ * both cut links that way) and a cut link loses the money's key.
+ */
 export declare function buildClaimLink(l: ClaimLink, origin?: string): string;
 /** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
 export declare function parseClaimLink(link: string): ClaimLink;

package/dist/private/links.js

@@ -21,7 +21,7 @@
  */
 import { scryptAsync } from "@noble/hashes/scrypt";
 import { randomBytes } from "@noble/hashes/utils";
-import { concat, isAddress, keccak256, toBytes } from "viem";
+import { concat, isAddress, keccak256, toBytes, toHex } from "viem";
 import { CloakKeys, formatCloakAddress, parseCloakAddress } from "./crypto.js";
 export const LINK_ORIGIN = "https://cloak.boblabs.tech";
 export const LINK_MESSAGE_MAX = 140;
@@ -64,9 +64,46 @@ export async function linkKeys(secret, passcode) {
 export async function linkAddress(keys) {
     return formatCloakAddress((await keys.main()).pubKey, keys.encPub);
 }
-export function buildClaimLink(l, origin = LINK_ORIGIN) {
+/** The 8-hex-digit check a locked link carries: the first 4 bytes of a hash of the account the passcode opens. */
+export async function linkCheck(keys) {
+    return keccak256(concat([toBytes("cloak-link-check-v1"), toBytes(await linkAddress(keys))])).slice(2, 10);
+}
+/** Thrown when a link's check says the passcode is wrong. */
+export class WrongPasscodeError extends Error {
+    constructor(riddle) {
+        super(riddle ? "That's not the answer. Check the spelling and try again." : "That's not the passcode. Check it with the sender and try again.");
+        this.name = "WrongPasscodeError";
+    }
+}
+/** Ways a phone may have typed the same code: curly quotes and long dashes from autocorrect, a trailing full stop. */
+function passcodeVariants(code) {
+    const base = normalizePasscode(code);
+    const straight = base.replace(/[\u2018\u2019\u201b\u2032]/g, "'").replace(/[\u201c\u201d\u2033]/g, '"').replace(/[\u2013\u2014\u2212]/g, "-");
+    return [...new Set([base, straight, straight.replace(/[.!?]+$/, "")])].filter(Boolean);
+}
+/**
+ * Opens a link's account. A locked link with a check tries the code (and the ways a phone may have mangled it) and
+ * throws WrongPasscodeError if none matches, without touching the network. A link without a check (made before
+ * checks existed) opens with the code as typed; an empty account is then all a wrong code looks like.
+ */
+export async function openLinkKeys(l, passcode) {
+    if (!l.locked)
+        return linkKeys(l.secret);
+    if (!passcode || !normalizePasscode(passcode))
+        throw new Error(l.hint ? "Type the answer." : "Enter the passcode.");
+    if (!l.check)
+        return linkKeys(l.secret, passcode);
+    for (const v of passcodeVariants(passcode)) {
+        const k = await linkKeys(l.secret, v);
+        if ((await linkCheck(k)) === l.check)
+            return k;
+    }
+    throw new WrongPasscodeError(!!l.hint);
+}
+/** The fields of a claim link as query parameters (the secret in hex). */
+function claimParams(l) {
     const p = new URLSearchParams();
-    p.set("k", b64url(l.secret));
+    p.set("k", toHex(l.secret).slice(2));
     p.set("b", l.block.toString());
     if (l.token)
         p.set("t", l.token);
@@ -85,24 +122,69 @@ export function buildClaimLink(l, origin = LINK_ORIGIN) {
         p.set("q", q);
     if (l.shares && l.shares > 1)
         p.set("n", String(Math.min(Math.floor(l.shares), LINK_SHARES_MAX)));
-    return `${origin.replace(/\/+$/, "")}/claim#${p.toString()}`;
+    if (l.check && /^[0-9a-f]{8}$/.test(l.check))
+        p.set("c", l.check);
+    return p;
+}
+/**
+ * A claim link: https://cloak.boblabs.tech/claim#c<letters and digits>. Everything after the # is one run of letters
+ * and digits (base 62), because chat apps end a link at characters like "-", "_", "." or "%" (WhatsApp and Telegram
+ * both cut links that way) and a cut link loses the money's key.
+ */
+export function buildClaimLink(l, origin = LINK_ORIGIN) {
+    return `${origin.replace(/\/+$/, "")}/claim#c${toBase62(new TextEncoder().encode(claimParams(l).toString()))}`;
+}
+const B62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function toBase62(bytes) {
+    // a leading 1 byte keeps leading zero bytes; the payload is a few hundred bytes, so plain bigint math is fine
+    let n = BigInt(toHex(concat([new Uint8Array([1]), bytes])));
+    let out = "";
+    while (n > 0n) {
+        out = B62[Number(n % 62n)] + out;
+        n /= 62n;
+    }
+    return out;
+}
+function fromBase62(s) {
+    let n = 0n;
+    for (const ch of s) {
+        const v = B62.indexOf(ch);
+        if (v < 0)
+            throw new Error("bad link");
+        n = n * 62n + BigInt(v);
+    }
+    let hex = n.toString(16);
+    if (hex.length % 2)
+        hex = "0" + hex;
+    const b = toBytes(`0x${hex}`);
+    if (b[0] !== 1)
+        throw new Error("bad link");
+    return b.slice(1);
 }
 /** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
 export function parseClaimLink(link) {
-    const frag = link.includes("#") ? link.slice(link.indexOf("#") + 1) : link;
+    let frag = (link.includes("#") ? link.slice(link.indexOf("#") + 1) : link).trim();
+    if (/^c[0-9A-Za-z]+$/.test(frag)) {
+        try {
+            frag = new TextDecoder("utf-8", { fatal: true }).decode(fromBase62(frag.slice(1)));
+        }
+        catch {
+            throw new Error("This claim link is cut short or damaged. Ask the sender to copy the whole link again.");
+        }
+    }
     const p = new URLSearchParams(frag);
     const k = p.get("k");
     if (!k)
         throw new Error("This isn't a Cloak claim link.");
     let secret;
     try {
-        secret = unb64url(k);
+        secret = /^[0-9a-fA-F]{64}$/.test(k) ? toBytes(`0x${k}`) : unb64url(k);
     }
     catch {
         throw new Error("This claim link is damaged. Ask the sender to copy it again.");
     }
     if (secret.length !== 32)
-        throw new Error("This claim link is cut short. Ask the sender to copy it again.");
+        throw new Error("This claim link is cut short. Ask the sender to copy the whole link again.");
     const b = p.get("b") ?? "0";
     const t = p.get("t");
     const a = p.get("a");
@@ -116,6 +198,7 @@ export function parseClaimLink(link) {
         locked: p.get("p") === "1",
         hint: cleanLinkText(p.get("q"), LINK_HINT_MAX) || undefined,
         shares: /^\d{1,2}$/.test(p.get("n") ?? "") && Number(p.get("n")) > 1 ? Math.min(Number(p.get("n")), LINK_SHARES_MAX) : undefined,
+        check: /^[0-9a-f]{8}$/.test(p.get("c") ?? "") ? p.get("c") : undefined,
     };
 }
 /** Checks an amount and returns it as a plain decimal, or throws a plain-language error. Empty means "payer chooses". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloakely/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Cloak on Elysium: sealed-bid token launches and private trading (shielded balances, private swaps, batch auctions, private sends) with on-device zero-knowledge proofs.",
   "keywords": [
     "cloak",