@kirkelabs/walletless-kit 0.1.0

package/src/onboarding.js

@@ -0,0 +1,120 @@
+/**
+ * onboarding.js — low-friction guest onboarding via EPHEMERAL CUSTODIAL accounts.
+ *
+ * A guest gets a fresh, server-held Algorand account that is tightly scoped and
+ * auto-expires. The user signs nothing. This trades self-custody for low friction,
+ * so it is handled defensively:
+ *   - The secret key is generated from a CSPRNG (oaa-agent-kit LocalOwnerSigner)
+ *     and attached NON-ENUMERABLY, so it never lands in JSON.stringify, logs,
+ *     receipts, events, or ledger snapshots. JS cannot wipe key memory — these are
+ *     DEV/TestNet-grade; production custody needs your own KMS/HSM (see LEGAL.md).
+ *   - Expiry is ROUND-RELATIVE (live round + ttlRounds), never a hard-coded round
+ *     (a static default silently expires — a footgun we will not repeat).
+ *   - Authority can be bounded by composing an oaa-agent-kit mandate, so a leaked
+ *     ephemeral key is loss-limited (per-tx cap / payee allowlist / expiry).
+ */
+
+import algosdk from 'algosdk';
+import { LocalOwnerSigner, createMandate } from '@kirkelabs/oaa-agent-kit';
+
+const MS_DEFAULT_TTL = 50_000; // ~2 days of rounds on Algorand (~2.8s/round)
+
+/**
+ * Create an ephemeral custodial account. The returned object is safe to persist
+ * (no secret in its enumerable fields); the signer is reachable via the
+ * non-enumerable `.signer` for server-side signing only.
+ *
+ * @param {object} opts
+ * @param {algosdk.Algodv2} opts.algod
+ * @param {number} [opts.ttlRounds]  rounds until expiry (added to the live round)
+ * @param {object} [opts.scope]      optional authority bound: {perTxMicroAlgos, allowlist?, owner?}
+ * @param {string} [opts.network]    'algorand-testnet' (default) | 'algorand'
+ */
+export async function createEphemeralAccount({
+  algod,
+  ttlRounds = MS_DEFAULT_TTL,
+  scope = null,
+  network = 'algorand-testnet',
+}) {
+  if (!Number.isInteger(ttlRounds) || ttlRounds <= 0)
+    throw new Error('createEphemeralAccount: ttlRounds must be a positive integer');
+  const sp = await algod.getTransactionParams().do();
+  const expiryRound = Number(sp.lastValid) + ttlRounds; // round-relative
+
+  const signer = LocalOwnerSigner.random(); // CSPRNG key, held in-process only
+  let mandate = null;
+  if (scope && scope.perTxMicroAlgos != null) {
+    mandate = createMandate({
+      owner: scope.owner ?? signer.address,
+      perTxMicroAlgos: scope.perTxMicroAlgos,
+      allowlist: scope.allowlist ?? [],
+      expiryRound,
+      network,
+    });
+  }
+
+  const account = {
+    address: signer.address,
+    network,
+    createdAtRound: Number(sp.firstValid),
+    expiryRound,
+    scope: scope ? { ...scope } : null,
+    mandate,
+  };
+  // The secret signer is NON-ENUMERABLE: it is excluded from JSON/logs/snapshots.
+  Object.defineProperty(account, 'signer', { value: signer, enumerable: false });
+  return account;
+}
+
+/** True if the account has passed its expiry round. */
+export function isExpired(account, currentRound) {
+  if (account == null || account.expiryRound == null)
+    throw new Error('isExpired: account.expiryRound is required');
+  if (currentRound == null) throw new Error('isExpired: currentRound is required');
+  return Number(currentRound) > Number(account.expiryRound);
+}
+
+/** Sweep the full balance of an ephemeral account to `toAddress` (close-out). */
+async function sweep(algod, fromSigner, toAddress) {
+  if (!algosdk.isValidAddress(String(toAddress)))
+    throw new Error('sweep: invalid destination address');
+  const sp = await algod.getTransactionParams().do();
+  const txn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+    sender: fromSigner.address,
+    receiver: toAddress,
+    amount: 0,
+    closeRemainderTo: toAddress, // close the ephemeral account, sweeping everything
+    suggestedParams: sp,
+  });
+  const [signed] = await fromSigner.signTxns([txn]);
+  const { txid } = await algod.sendRawTransaction(signed).do();
+  await algosdk.waitForConfirmation(algod, txid, 10);
+  return txid;
+}
+
+/**
+ * Expire an account NOW: sweep its balance back to the operator and abandon it.
+ * @returns {Promise<{txid:string, sweptTo:string}>}
+ */
+export async function expireAccount({ algod, account, to }) {
+  if (!account?.signer) throw new Error('expireAccount: account.signer is required');
+  const txid = await sweep(algod, account.signer, to);
+  return { txid, sweptTo: String(to) };
+}
+
+/**
+ * Rotate to a fresh ephemeral account (e.g. on suspected key compromise) and
+ * sweep the old balance into it. Inherits scope/network unless overridden.
+ * @returns {Promise<{account:object, sweepTxid:string}>}
+ */
+export async function rotateAccount({ algod, account, ttlRounds, scope, network }) {
+  if (!account?.signer) throw new Error('rotateAccount: account.signer is required');
+  const next = await createEphemeralAccount({
+    algod,
+    ttlRounds: ttlRounds ?? MS_DEFAULT_TTL,
+    scope: scope ?? account.scope,
+    network: network ?? account.network,
+  });
+  const sweepTxid = await sweep(algod, account.signer, next.address);
+  return { account: next, sweepTxid };
+}

package/src/privacy.js

@@ -0,0 +1,98 @@
+/**
+ * privacy.js — keep personal data OFF-chain and make erasure real.
+ *
+ * Design rules (see LEGAL.md, data-protection section):
+ *   - Personal data (email/phone/name) lives off-chain, encrypted and deletable.
+ *   - The chain holds only NON-identifying references.
+ *   - Contact references are KEYED (HMAC with a per-deployment pepper), never a
+ *     bare hash — a raw SHA-256 of an email/phone is brute-forceable because the
+ *     input space is small/enumerable. A keyed hash is pseudonymous; it is still
+ *     personal data under GDPR, but not trivially reversible.
+ *   - For references that must survive on-chain yet remain erasable, prefer a
+ *     RANDOM nonce (`pseudonymRef`) stored off-chain over a deterministic hash of
+ *     the PII: deleting the off-chain mapping then makes the on-chain ref
+ *     unlinkable. A deterministic PII hash would stay linkable to anyone who
+ *     re-encounters the same PII, defeating erasure.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Keyed, pseudonymous reference for a contact value (email/phone/etc).
+ * Stable for a given (pepper, value) so you can de-duplicate entrants, but not
+ * reversible without the pepper. NOT anonymous — still personal data.
+ * @param {string} value e.g. an email or phone number
+ * @param {string} pepper a secret, per-deployment key (keep out of the repo/chain)
+ * @returns {string} hex HMAC-SHA256
+ */
+export function hashPii(value, pepper) {
+  if (typeof value !== 'string' || value.length === 0)
+    throw new Error('hashPii: value must be a non-empty string');
+  if (typeof pepper !== 'string' || pepper.length < 16)
+    throw new Error('hashPii: pepper must be a secret string of at least 16 chars');
+  return createHmac('sha256', pepper).update(value, 'utf8').digest('hex');
+}
+
+/** Constant-time comparison of two contact hashes (avoid timing side-channels). */
+export function hashEquals(a, b) {
+  const ba = Buffer.from(String(a), 'utf8');
+  const bb = Buffer.from(String(b), 'utf8');
+  if (ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}
+
+/**
+ * A subject record that maps a RANDOM, erasable on-chain reference to off-chain
+ * PII. Put `ref` on-chain (it is just a random nonce); keep `contactHash` and the
+ * encrypted PII in your off-chain store. `eraseSubject` deletes everything off
+ * chain, after which `ref` is permanently unlinkable.
+ *
+ * @param {object} opts
+ * @param {string} opts.contact   raw contact value (NOT stored as-is)
+ * @param {string} opts.pepper    secret keyed-hash pepper
+ * @returns {{ ref: string, contactHash: string, createdRef: true }}
+ */
+export function pseudonymRef({ contact, pepper }) {
+  const contactHash = hashPii(contact, pepper);
+  // Random 16-byte nonce — independent of the PII, so erasing the off-chain map
+  // makes it unlinkable. This is what (optionally) goes on-chain.
+  const ref = randomBytes(16).toString('hex');
+  return { ref, contactHash, createdRef: true };
+}
+
+/**
+ * Erase a subject from an off-chain store. Removes the encrypted PII and the
+ * ref->contact mapping so any on-chain `ref` becomes unlinkable. On-chain
+ * receipts/anchors (which hold no PII) intentionally remain.
+ *
+ * @param {Map|object} store a Map (or plain object) keyed by `ref`
+ * @param {string} ref the random reference to erase
+ * @returns {{ erased: boolean, ref: string }}
+ */
+export function eraseSubject(store, ref) {
+  if (ref == null) throw new Error('eraseSubject: ref is required');
+  let erased = false;
+  if (store instanceof Map) {
+    erased = store.delete(ref);
+  } else if (store && typeof store === 'object') {
+    if (Object.prototype.hasOwnProperty.call(store, ref)) {
+      delete store[ref];
+      erased = true;
+    }
+  } else {
+    throw new Error('eraseSubject: store must be a Map or object');
+  }
+  return { erased, ref };
+}
+
+/** Assert an object carries no obvious PII before it is written on-chain. */
+const PII_KEYS = /^(email|phone|name|firstname|lastname|address|dob|ip|contact)$/i;
+export function assertNoPii(obj, path = '$') {
+  if (obj == null || typeof obj !== 'object') return true;
+  for (const [k, v] of Object.entries(obj)) {
+    if (PII_KEYS.test(k))
+      throw new Error(`assertNoPii: possible PII field "${k}" at ${path} must not go on-chain`);
+    if (v && typeof v === 'object') assertNoPii(v, `${path}.${k}`);
+  }
+  return true;
+}

package/src/receipt.js

@@ -0,0 +1,138 @@
+/**
+ * receipt.js — receipt-only on-chain proofs. The user signs NOTHING.
+ *
+ * An order receipt is a compact, NON-PII record that hash-chains to the previous
+ * one (tamper-evident) and can be signed by the operator. Only the receipt HASH
+ * is attested on-chain — never the body, never any personal data. x402-charged
+ * actions go through oaa-agent-kit's hardened `payAndFetch` (SSRF guard, timeout,
+ * response-size cap, redirect:error, allowedHosts, confirm hook).
+ */
+
+import algosdk from 'algosdk';
+import {
+  createReceiptId,
+  hashCanonicalJson,
+  signReceipt as coreSignReceipt,
+  verifyReceiptSignature,
+} from '@kirkelabs/open-agent-access-core';
+import { payAndFetch, makeAlgorandPayer } from '@kirkelabs/oaa-agent-kit';
+import { assertNoPii } from './privacy.js';
+
+/** Canonical hash payload: the receipt without its own hash/signature fields. */
+function hashPayload(r) {
+  const c = { ...r };
+  delete c.receiptHash;
+  delete c.signature;
+  return c;
+}
+
+/** A deterministic, reproducible order id from a seed (no randomness/clock). */
+export function deterministicOrderId(seed) {
+  return `ord_${hashCanonicalJson(seed).slice(0, 24)}`;
+}
+
+/**
+ * Build a non-PII, hash-chained order receipt. Throws if any field looks like PII
+ * (so a receipt can never carry personal data on-chain). Pass `previousHash`
+ * (the prior receipt's `receiptHash`) to chain.
+ */
+export function buildOrderReceipt(input = {}) {
+  // Reject PII on the RAW input (before we drop unknown keys), so a caller can
+  // never smuggle personal data into anything that may be attested on-chain.
+  assertNoPii(input);
+  const {
+    orderId,
+    action,
+    quantity,
+    price,
+    agent,
+    previousHash = null,
+    receiptId,
+    timestamp,
+  } = input;
+  if (orderId == null || action == null) throw new Error('buildOrderReceipt: orderId and action are required');
+  const receipt = {
+    receiptVersion: '0.1',
+    receiptType: 'walletless_order',
+    receiptId: receiptId ?? createReceiptId(),
+    orderId: String(orderId),
+    action: String(action),
+    quantity: quantity == null ? null : Number(quantity),
+    price: price == null ? null : String(price), // string/integer — never a float literal
+    agent: agent == null ? null : String(agent),
+    previousHash,
+    timestamp: timestamp ?? new Date().toISOString(),
+  };
+  assertNoPii(receipt);
+  receipt.receiptHash = hashCanonicalJson(hashPayload(receipt));
+  return receipt;
+}
+
+/** Operator-sign a receipt (ed25519, via core). */
+export function signReceipt(receipt, { privateKeyPem, publicKeyPem }) {
+  return coreSignReceipt(receipt, privateKeyPem, publicKeyPem);
+}
+
+/**
+ * Verify a chain of receipts: each links to the previous, each hash recomputes,
+ * and any signature present is valid. Robust to malformed input (never throws).
+ * @returns {{ok:boolean, count:number, errors:string[]}}
+ */
+export function verifyReceiptChain(receipts) {
+  const errors = [];
+  if (!Array.isArray(receipts)) return { ok: false, count: 0, errors: ['not_an_array'] };
+  let prev = null;
+  receipts.forEach((r, i) => {
+    try {
+      if ((r.previousHash ?? null) !== prev) errors.push(`receipt ${i + 1}: previousHash mismatch`);
+      if (r.receiptHash !== hashCanonicalJson(hashPayload(r)))
+        errors.push(`receipt ${i + 1}: receiptHash mismatch`);
+      if (r.signature && !verifyReceiptSignature(r)) errors.push(`receipt ${i + 1}: bad signature`);
+      prev = r.receiptHash;
+    } catch (e) {
+      errors.push(`receipt ${i + 1}: ${e.message}`);
+    }
+  });
+  return { ok: errors.length === 0, count: receipts.length, errors };
+}
+
+/**
+ * Attest a receipt on-chain as a compact, NON-PII note: only
+ * `walletless-receipt:v1:<receiptHash>` (the receipt body stays off-chain).
+ * Network-bound (genesis via suggestedParams) and size-bounded (note ≤ 1 KB).
+ * @returns {Promise<{txid:string, confirmedRound:number, receiptHash:string}>}
+ */
+export async function attestOnChain(algod, signer, receipt) {
+  if (!receipt?.receiptHash) throw new Error('attestOnChain: receipt has no receiptHash');
+  assertNoPii(receipt);
+  const note = new TextEncoder().encode(`walletless-receipt:v1:${receipt.receiptHash}`);
+  if (note.length > 1024) throw new Error('attestOnChain: note exceeds 1KB');
+  const sp = await algod.getTransactionParams().do();
+  const txn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+    sender: signer.address,
+    receiver: signer.address,
+    amount: 0,
+    note,
+    suggestedParams: sp,
+  });
+  const [signed] = await signer.signTxns([txn]);
+  const { txid } = await algod.sendRawTransaction(signed).do();
+  const res = await algosdk.waitForConfirmation(algod, txid, 10);
+  return {
+    txid,
+    confirmedRound: Number(res.confirmedRound ?? res['confirmed-round']),
+    receiptHash: receipt.receiptHash,
+  };
+}
+
+/**
+ * Pay-and-fetch an x402-charged action from a mandate-bound agent account, reusing
+ * oaa-agent-kit's hardened client. `fetchPolicy` (allowInsecure, allowedHosts,
+ * timeoutMs, maxBytes, maxAmountMicroAlgos, confirm) is forwarded verbatim — set
+ * `allowedHosts` when the action URL is not fully trusted.
+ */
+export async function chargeForAction({ algod, account, mandate, url, method, body, ...fetchPolicy }) {
+  const payer =
+    algod && account && mandate ? makeAlgorandPayer({ algod, account, mandate }) : undefined;
+  return payAndFetch(url, { payer, method, body, ...fetchPolicy });
+}