@zerc20/storage-sdk 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@zerc20/storage-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript SDK for zerc20-storage: private note delivery for zERC20 on the Internet Computer.",
+  "type": "module",
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kbizikav/zerc20-v2-new.git",
+    "directory": "storage/sdk"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "demo": "node demo/serve.ts"
+  },
+  "dependencies": {
+    "@dfinity/vetkeys": "~0.4.0",
+    "@icp-sdk/core": "^6.1.1",
+    "@noble/ciphers": "^2.3.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@scure/base": "^2.4.0"
+  },
+  "devDependencies": {
+    "@dfinity/pic": "0.25.0",
+    "@types/node": "24.19.2",
+    "typescript": "6.0.3",
+    "vite": "8.3.4",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/candid.ts

@@ -0,0 +1,116 @@
+// The zerc20_storage Candid interface (canister/zerc20_storage.did), by hand: generated bindings
+// target the older @dfinity/* packages.
+
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+
+export type KindName = 'Outgoing' | 'Lane';
+export type Kind = { [K in KindName]: { [P in K]: null } }[KindName];
+
+export type Action =
+  | {
+      OpenChannel: {
+        inbox: Uint8Array;
+        enc_announcement: Uint8Array;
+        outgoing_id: Uint8Array;
+        enc_outgoing: Uint8Array;
+      };
+    }
+  | { Put: { kind: Kind; id: Uint8Array; data: Uint8Array } };
+
+export interface AuditRequest {
+  target: Uint8Array;
+  notify_key: Uint8Array;
+  transport_public_key: Uint8Array;
+  expiry_ns: bigint;
+  signature: Uint8Array;
+}
+
+export interface Registration {
+  address: Uint8Array;
+  public_key: Uint8Array;
+  notify_key: Uint8Array;
+  escrow: Uint8Array;
+  expiry_ns: bigint;
+  signature: Uint8Array;
+}
+
+export interface Slot {
+  data: Uint8Array;
+  at_ns: bigint;
+}
+
+export interface AuditRecord {
+  auditor: Uint8Array;
+  target: Uint8Array;
+  notify_key: Uint8Array;
+  transport_public_key: Uint8Array;
+  expiry_ns: bigint;
+  signature: Uint8Array;
+  at_ns: bigint;
+}
+
+export type CanisterError = { Occupied: Uint8Array } | { Rejected: string };
+export type Result<T> = { Ok: T } | { Err: CanisterError };
+
+export interface Service {
+  escrow_public_key: ActorMethod<[], Result<Uint8Array>>;
+  register: ActorMethod<[Registration, bigint], Result<null>>;
+  registration: ActorMethod<[Uint8Array, [] | [Uint8Array]], [] | [Registration]>;
+  audit_escrow_key: ActorMethod<[AuditRequest], Result<Uint8Array>>;
+  get_audits: ActorMethod<[bigint, number], AuditRecord[]>;
+  submit: ActorMethod<[Action[], bigint], Result<null>>;
+  get_announcements: ActorMethod<[Uint8Array, number, number], Uint8Array[]>;
+  get_slots: ActorMethod<[Kind, Uint8Array[]], ([] | [Slot])[]>;
+  get_log: ActorMethod<[bigint, number], Uint8Array[]>;
+  log_length: ActorMethod<[], bigint>;
+}
+
+export const idlFactory: IDL.InterfaceFactory = ({ IDL }) => {
+  const Blob = IDL.Vec(IDL.Nat8);
+  const Error = IDL.Variant({ Occupied: Blob, Rejected: IDL.Text });
+  const BlobResult = IDL.Variant({ Ok: Blob, Err: Error });
+  const UnitResult = IDL.Variant({ Ok: IDL.Null, Err: Error });
+  const Kind = IDL.Variant({ Outgoing: IDL.Null, Lane: IDL.Null });
+  const Action = IDL.Variant({
+    OpenChannel: IDL.Record({ inbox: Blob, enc_announcement: Blob, outgoing_id: Blob, enc_outgoing: Blob }),
+    Put: IDL.Record({ kind: Kind, id: Blob, data: Blob }),
+  });
+  const AuditRequest = IDL.Record({
+    target: Blob,
+    notify_key: Blob,
+    transport_public_key: Blob,
+    expiry_ns: IDL.Nat64,
+    signature: Blob,
+  });
+  const Registration = IDL.Record({
+    address: Blob,
+    public_key: Blob,
+    notify_key: Blob,
+    escrow: Blob,
+    expiry_ns: IDL.Nat64,
+    signature: Blob,
+  });
+  const Slot = IDL.Record({ data: Blob, at_ns: IDL.Nat64 });
+  const AuditRecord = IDL.Record({
+    auditor: Blob,
+    target: Blob,
+    notify_key: Blob,
+    transport_public_key: Blob,
+    expiry_ns: IDL.Nat64,
+    signature: Blob,
+    at_ns: IDL.Nat64,
+  });
+  return IDL.Service({
+    escrow_public_key: IDL.Func([], [BlobResult], []),
+    register: IDL.Func([Registration, IDL.Nat64], [UnitResult], []),
+    registration: IDL.Func([Blob, IDL.Opt(Blob)], [IDL.Opt(Registration)], ['query']),
+    audit_escrow_key: IDL.Func([AuditRequest], [BlobResult], []),
+    get_audits: IDL.Func([IDL.Nat64, IDL.Nat32], [IDL.Vec(AuditRecord)], ['query']),
+    submit: IDL.Func([IDL.Vec(Action), IDL.Nat64], [UnitResult], []),
+    get_announcements: IDL.Func([Blob, IDL.Nat32, IDL.Nat32], [IDL.Vec(Blob)], ['query']),
+    get_slots: IDL.Func([Kind, IDL.Vec(Blob)], [IDL.Vec(IDL.Opt(Slot))], ['query']),
+    get_log: IDL.Func([IDL.Nat64, IDL.Nat32], [IDL.Vec(Blob)], ['query']),
+    log_length: IDL.Func([], [IDL.Nat64], ['query']),
+  });
+};

package/src/canister.ts

@@ -0,0 +1,85 @@
+// A zerc20_storage canister, called anonymously.
+
+import { Actor, type ActorSubclass, type Agent, HttpAgent } from '@icp-sdk/core/agent';
+import { Principal } from '@icp-sdk/core/principal';
+import { DerivedPublicKey } from '@dfinity/vetkeys';
+import { idlFactory, type Action, type CanisterError, type Registration, type Result, type Service } from './candid.js';
+import { hex } from './crypto.js';
+import { REGISTER_POW_BITS, actionsDigest, registerDigest, requiredPowBits, solvePow } from './wire.js';
+
+/** A definite answer from the canister: `Occupied` (the slot holds other data) or `Rejected`. */
+export class StorageError extends Error {
+  constructor(readonly error: CanisterError) {
+    super('Occupied' in error ? `occupied: 0x${hex(error.Occupied)}` : `rejected: ${error.Rejected}`);
+  }
+
+  get occupied(): boolean {
+    return 'Occupied' in this.error;
+  }
+}
+
+/** Each request gives up after this, so that one that hangs does not hold its caller forever. A call cut off may still
+ * have landed, as one whose connection drops may. */
+const TIMEOUT_MS = 30_000;
+
+const fetchWithTimeout: typeof fetch = (input, init) => {
+  const timeout = AbortSignal.timeout(TIMEOUT_MS);
+  return fetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout });
+};
+
+export function unwrap<T>(result: Result<T>): T {
+  if ('Err' in result) throw new StorageError(result.Err);
+  return result.Ok;
+}
+
+export class CanisterClient {
+  readonly canisterId: Principal;
+  /** Queries answered by a single replica: cheap, but only good for spotting news. */
+  readonly actor: ActorSubclass<Service>;
+  /** Every method as an update call, so the subnet agrees on the answer. */
+  readonly replicated: ActorSubclass<Service>;
+  #escrowPublicKey?: Promise<DerivedPublicKey>;
+
+  /** A client over HTTP. A local replica (an `http://` host on this machine) has its root key fetched; the IC's is
+   * built in. A root key fetched from anywhere else would let whoever is on the path forge every certified answer. */
+  static async connect(host: string, canisterId: Principal | string): Promise<CanisterClient> {
+    const url = new URL(host);
+    const local = url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    const agent = await HttpAgent.create({ host, shouldFetchRootKey: local, fetch: fetchWithTimeout });
+    return new CanisterClient(agent, canisterId);
+  }
+
+  constructor(agent: Agent, canisterId: Principal | string) {
+    this.canisterId = Principal.from(canisterId);
+    const config = { agent, canisterId: this.canisterId };
+    this.actor = Actor.createActor<Service>(idlFactory, config);
+    this.replicated = Actor.createActor<Service>(idlFactory, { ...config, queryStrategy: 'update' });
+  }
+
+  /** The key owners IBE-encrypt their escrows with. Fixed for the canister's lifetime. */
+  escrowPublicKey(): Promise<DerivedPublicKey> {
+    this.#escrowPublicKey ??= this.actor.escrow_public_key().then((r) => DerivedPublicKey.deserialize(unwrap(r)));
+    this.#escrowPublicKey.catch(() => (this.#escrowPublicKey = undefined));
+    return this.#escrowPublicKey;
+  }
+
+  /** `address`'s registration with `notifyKey`, by default its current one: a query, which one replica answers.
+   * Unverified: check it with `verifyRegistration`. Call `replicated.registration` where a stale answer matters. */
+  async registration(address: Uint8Array, notifyKey?: Uint8Array): Promise<Registration | null> {
+    const r = await this.actor.registration(address, notifyKey ? [notifyKey] : []);
+    return r[0] ?? null;
+  }
+
+  /** Solves the proof of work and registers. An identical registration that is already stored is a
+   * no-op, so a call whose outcome is unknown can be repeated. */
+  async register(registration: Registration): Promise<void> {
+    const nonce = await solvePow(registerDigest(registration), REGISTER_POW_BITS);
+    unwrap(await this.actor.register(registration, nonce));
+  }
+
+  /** Solves the proof of work and submits the batch. Throws `StorageError` on a definite failure. */
+  async submit(actions: Action[]): Promise<void> {
+    const nonce = await solvePow(actionsDigest(actions), requiredPowBits(actions));
+    unwrap(await this.actor.submit(actions, nonce));
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,113 @@
+// Primitives: HKDF-SHA256, ChaCha20-Poly1305 with random nonces, X25519 ECIES, and byte helpers.
+
+import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+
+export { bytesToHex as hex, hexToBytes as unhex, randomBytes };
+
+export const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text);
+
+export function concat(...parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}
+
+export function u32be(n: number): Uint8Array {
+  const out = new Uint8Array(4);
+  new DataView(out.buffer).setUint32(0, n, false);
+  return out;
+}
+
+export function u64be(n: bigint): Uint8Array {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, n, false);
+  return out;
+}
+
+export const readU32 = (bytes: Uint8Array, at: number): number =>
+  new DataView(bytes.buffer, bytes.byteOffset).getUint32(at, false);
+
+export const readU64 = (bytes: Uint8Array, at: number): bigint =>
+  new DataView(bytes.buffer, bytes.byteOffset).getBigUint64(at, false);
+
+export function equal(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((byte, i) => byte === b[i]);
+}
+
+/** Lexicographic (= big-endian numeric, for equal lengths) comparison. */
+export function compare(a: Uint8Array, b: Uint8Array): number {
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return a.length - b.length;
+}
+
+/** `u32_be(len) ‖ part` for every part, so fields can never run into each other. */
+export function lengthPrefixed(parts: Uint8Array[]): Uint8Array {
+  return concat(...parts.flatMap((part) => [u32be(part.length), part]));
+}
+
+/** Unix time in ns from the local clock. */
+export const nowNs = (): bigint => BigInt(Date.now()) * 1_000_000n;
+
+const KDF_SALT = utf8('zerc20/storage/kdf/v1');
+
+/** HKDF-SHA256 of `key`, domain-separated by `label` and the length-prefixed `parts`. */
+export function kdf(key: Uint8Array, label: string, parts: Uint8Array[] = []): Uint8Array {
+  return hkdf(sha256, key, KDF_SALT, lengthPrefixed([utf8(label), ...parts]), 32);
+}
+
+/** SHA-256 of `tag` and `parts`, each length-prefixed: what anyone can compute, where `kdf` needs a key. */
+export function taggedHash(tag: string, parts: Uint8Array[]): Uint8Array {
+  return sha256(lengthPrefixed([utf8(tag), ...parts]));
+}
+
+/** `nonce(12) ‖ ChaCha20-Poly1305`. The nonce is random so that a retry after a failed but
+ * already-visible call never reuses a (key, nonce) pair. */
+export function seal(key: Uint8Array, aad: Uint8Array, msg: Uint8Array): Uint8Array {
+  const nonce = randomBytes(12);
+  return concat(nonce, chacha20poly1305(key, nonce, aad).encrypt(msg));
+}
+
+export function open(key: Uint8Array, aad: Uint8Array, blob: Uint8Array): Uint8Array | null {
+  if (blob.length < 12) return null;
+  try {
+    return chacha20poly1305(key, blob.subarray(0, 12), aad).decrypt(blob.subarray(12));
+  } catch {
+    return null;
+  }
+}
+
+/** ECIES to an X25519 public key: `ephemeral_pk(32) ‖ seal(..)`. `null` for a low-order key, whose
+ * shared secret anyone could compute. */
+export function sealTo(publicKey: Uint8Array, label: string, aad: Uint8Array, msg: Uint8Array): Uint8Array | null {
+  const ephemeral = x25519.utils.randomSecretKey();
+  const ephemeralPk = x25519.getPublicKey(ephemeral);
+  let shared: Uint8Array;
+  try {
+    shared = x25519.getSharedSecret(ephemeral, publicKey);
+  } catch {
+    return null;
+  }
+  return concat(ephemeralPk, seal(kdf(shared, label, [ephemeralPk, publicKey]), aad, msg));
+}
+
+export function openFrom(secret: Uint8Array, label: string, aad: Uint8Array, blob: Uint8Array): Uint8Array | null {
+  if (blob.length < 32) return null;
+  const ephemeralPk = blob.subarray(0, 32);
+  try {
+    const shared = x25519.getSharedSecret(secret, ephemeralPk);
+    const key = kdf(shared, label, [ephemeralPk, x25519.getPublicKey(secret)]);
+    return open(key, aad, blob.subarray(32));
+  } catch {
+    return null;
+  }
+}