@kirkelabs/walletless-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes are documented here. Format: [Keep a Changelog](https://keepachangelog.com/);
+versioning: [SemVer](https://semver.org/).
+
+## [0.1.0] — 2026-06-20
+
+- Initial release. A walletless web-architecture toolkit built on
+  `@kirkelabs/open-agent-access-core` and `@kirkelabs/oaa-agent-kit`.
+- **Onboarding** (`createEphemeralAccount`, `rotateAccount`, `expireAccount`,
+  `isExpired`) — tightly-scoped, round-relative auto-expiring custodial accounts,
+  authority-bounded via an oaa-agent-kit mandate.
+- **Identity** (`OtpIdentity`) — email/SMS OTP adapter: CSPRNG codes, single-use,
+  expiring, rate-limited, lockout, constant-time compare; stores only keyed
+  (peppered) pseudonymous contact references.
+- **Receipts** (`buildOrderReceipt`, `deterministicOrderId`, `attestOnChain`) —
+  hash-chained, signed, non-PII receipts with compact, size- and network-bound
+  on-chain attestation; x402-charged actions reuse oaa-agent-kit `payAndFetch`.
+- **Audit** (`createTrail`, `append`, `merkleRoot`, `anchor`, `verifyTrail`) —
+  append-only hash-chained events + an RFC 6962-style domain-separated Merkle root,
+  periodically anchored on-chain; tamper/removal is detectable.
+- **Ledger** (`createLedger`, `reconciliationSheet`) — three segregated append-only
+  books (inflow/charity/escrow), integer-only money, immutable snapshots, and a
+  human-readable per-draw reconciliation sheet.
+- **Draw** (`runDraw`, `publishDrawProof`, `blockHashSeed`/`vrfSeed`/`beaconSeed`) —
+  deterministic, recomputable winner selection (seeded Fisher–Yates, rejection
+  sampling, no `Math.random`), with a commit step and honest seed-manipulability docs.
+  Ships a frozen test vector.
+- **Privacy** (`hashPii`, `pseudonymRef`, `eraseSubject`) — keyed hashing and
+  random, erasable references; PII off-chain only.
+- CLI (`walletless init|keygen|draw|reconcile|verify|help`), a TestNet raffle
+  example, README, SECURITY, and LEGAL (gambling + AML + data-protection). MIT.
+
+> ⚠ Some modules are **EXPERIMENTAL · UNAUDITED**. TestNet by default; obtain an
+> independent audit before holding material value or processing real personal data.

package/LEGAL.md

@@ -0,0 +1,79 @@
+# Legal, regulatory & acceptable-use notice
+
+`@kirkelabs/walletless-kit` is free, open-source developer software (MIT). It provides
+**transparency and bookkeeping tooling** for walletless commerce and prize-draws — it
+does **not** provide legal, regulatory, financial, or compliance services, and using it
+does not make your activity lawful. This notice is **not legal advice**; if you operate
+in any regulated context, take your own advice. You, the operator, are solely
+responsible for compliance with all applicable laws in every jurisdiction you serve.
+
+## Nature of the software
+
+A toolkit of independent modules: ephemeral custodial onboarding, receipt-only on-chain
+proofs, a tamper-evident audit trail, segregated money ledgers, a verifiable draw, and
+privacy/erasure helpers. Kirke Labs operates no servers in your flow, holds no funds, and
+holds no keys or personal data. Everything runs in **your** infrastructure under **your**
+control.
+
+## 1. Prize draws, raffles & lotteries (gambling law)
+
+Prize draws, raffles, sweepstakes, and lotteries are **heavily regulated** and the rules
+differ by country, state, and province (e.g. the UK Gambling Act 2005 and the Gambling
+Commission; US state lottery/raffle statutes; varied EU regimes). **This package ships
+transparency tooling, not legal compliance.** In particular, **you** are responsible for:
+
+- obtaining any **licence/registration/exempt-lottery** status you need;
+- providing a genuine **free-entry route** of equal standing where required;
+- **age and geographic gating** (excluding minors and prohibited jurisdictions);
+- prize fulfilment, terms & conditions, advertising rules, and record-keeping;
+- handling and protecting entrant funds appropriately.
+
+A "verifiable" or "recomputable" draw means the winner can be re-derived from a published
+seed — it is **not** a representation that your draw is lawful, nor a substitute for
+licensing. **Draw fairness is exactly as strong as the public seed you choose** (see the
+README): block-hash seeds are validator-manipulable; use the commit step and prefer a VRF
+or randomness beacon for anything of value. Do not describe a draw as "provably fair"
+beyond what the chosen seed actually guarantees.
+
+## 2. Money handling, custody & AML
+
+The kit can hold value in **ephemeral custodial accounts** and **segregated escrow/charity
+ledgers**. Holding or transmitting other people's money may make you a regulated entity
+(money transmission / e-money / payment services) and typically triggers **AML/CFT and
+sanctions** obligations (KYC, screening, record-keeping). The custodial keys are
+**dev/TestNet-grade**: production custody requires your own KMS/HSM, segregated trust
+accounts, reconciliation controls, and an independent audit. The kit performs **no** KYC,
+sanctions screening, or licensing checks — those are yours. It transacts in the native
+Algorand coin (ALGO) only and is **TestNet by default**; MainNet is an explicit,
+cautioned opt-in.
+
+## 3. Personal data & privacy (GDPR / data protection)
+
+If you process entrants' contact details or other personal data, **you are the data
+controller**. The kit keeps personal data **off-chain** (you encrypt and can erase it) and
+places only **non-identifying references** on-chain. Two honest limits:
+
+- **Hashed contact references are pseudonymous, not anonymous** — they remain *personal
+  data*. Use the keyed (peppered) hashing provided, never bare hashes of low-entropy
+  values like emails or phone numbers.
+- **The blockchain is immutable.** "Erasure" works only because on-chain data is designed
+  to be non-identifying and unlinkable once the off-chain record (and any random reference
+  mapping) is deleted. Do **not** put personal data on-chain; if you do, it cannot be
+  erased. You remain responsible for lawful basis, retention, subject-access, and erasure.
+
+## No warranty; experimental
+
+Provided **"as is", without warranty** (see [LICENSE](./LICENSE)). Modules — and especially
+anything labelled **EXPERIMENTAL · UNAUDITED** — are not guaranteed fit for any purpose.
+Crypto-assets are volatile and largely unregulated. **You may lose funds and you bear all
+compliance risk.** Nothing here is financial, legal, or investment advice.
+
+## Jurisdiction
+
+Published globally as open source; **not targeted at any jurisdiction** and not an offer to
+provide any regulated service. You determine whether your use is lawful where you operate.
+
+## Reporting
+
+Security issues: **security@kirkelabs.com** (please do not open public issues for
+vulnerabilities affecting funds or personal data).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirke Labs — Soleman El Gelawi and Steve Kirton
+
+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

@@ -0,0 +1,91 @@
+# @kirkelabs/walletless-kit
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-00dc94?style=flat)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-00dc94?style=flat)](https://nodejs.org)
+[![Algorand](https://img.shields.io/badge/Algorand-TestNet%20by%20default-00dc94?style=flat)](https://algorand.co)
+
+**Walletless web architecture: onboard users with no wallet, prove what happened with receipts (not personal data), keep a tamper-evident audit trail and clean money trails, and run a draw anyone can recompute.** Charity prize-draws are the flagship example; every module is reusable for any walletless commerce flow.
+
+```bash
+npm i @kirkelabs/walletless-kit
+npx walletless init my-raffle
+```
+
+> ⚠️ **Experimental developer tooling, provided "as is."** It handles **custodial keys, money, and personal data**, and prize draws are **regulated**. This is *transparency tooling, not legal compliance*. Read **[Guardrails](#guardrails)** and **[LEGAL.md](./LEGAL.md)** before using real funds or real personal data. Nothing here is financial or legal advice. TestNet by default.
+
+Built on [`@kirkelabs/open-agent-access-core`](https://www.npmjs.com/package/@kirkelabs/open-agent-access-core) (proof/receipt spine) and [`@kirkelabs/oaa-agent-kit`](https://www.npmjs.com/package/@kirkelabs/oaa-agent-kit) (Algorand spend/identity/x402). The only new cryptographic primitive here is the Merkle root in `audit.js`.
+
+## What's in the box
+
+| Module | What it does |
+|--------|--------------|
+| **onboarding** | `createEphemeralAccount` / `rotateAccount` / `expireAccount` / `isExpired` — tightly-scoped, **round-relative auto-expiring** custodial accounts; authority bounded by an oaa-agent-kit mandate. |
+| **identity** | `OtpIdentity` — email/SMS OTP: CSPRNG codes, single-use, expiring, rate-limited, lockout, constant-time compare; stores only **keyed (peppered) pseudonymous** contact refs. |
+| **receipt** | `buildOrderReceipt` / `deterministicOrderId` / `signReceipt` / `verifyReceiptChain` / `attestOnChain` — hash-chained, signed, **non-PII** receipts; only the receipt *hash* goes on-chain. x402 actions via `chargeForAction`. |
+| **audit** | `createTrail` / `append` / `merkleRoot` / `merkleProof` / `verifyMerkleProof` / `anchor` / `verifyTrail` — append-only hash-chained events + an **RFC 6962** Merkle root, periodically anchored on-chain. |
+| **ledger** | `createLedger` — three segregated append-only books (inflow / charity / escrow), **integer-only money**, immutable snapshots, and a per-draw `reconciliationSheet`. |
+| **draw** | `runDraw` / `publishDrawProof` / `verifyDraw` + `commitSeedSource` / `blockHashSeed` / `vrfSeed` / `beaconSeed` — deterministic, recomputable winner selection (no `Math.random`). |
+| **privacy** | `hashPii` / `pseudonymRef` / `eraseSubject` / `assertNoPii` — keyed hashing and random, **erasable** references; PII stays off-chain. |
+
+## Quickstart
+
+```js
+import {
+  createLedger, OtpIdentity, buildOrderReceipt, createTrail, append,
+  runDraw, publishDrawProof, verifyDraw,
+} from '@kirkelabs/walletless-kit';
+
+// 1) Identity-lite: OTP, storing only a keyed pseudonymous ref (never the email).
+const id = new OtpIdentity({ pepper: process.env.PEPPER, send: sendEmail });
+await id.issueChallenge('alice@example.com');
+const { ok, contactRef } = await id.verifyChallenge('alice@example.com', code);
+
+// 2) A non-PII order receipt, hash-chained and (optionally) signed.
+const receipt = buildOrderReceipt({ orderId: 'o1', action: 'buy_ticket', quantity: 1, price: '1000000', agent: contactRef });
+
+// 3) A tamper-evident audit trail.
+let trail = createTrail();
+trail = append(trail, { type: 'ticket_sold', orderId: 'o1' });
+
+// 4) Segregated money books.
+const ledger = createLedger();
+ledger.post({ book: 'inflow', amountMicro: 1_000_000, kind: 'ticket', txRef: 'tx1' });
+
+// 5) A verifiable draw — anyone can recompute the winner from the proof.
+const entries = [contactRef /* … */];
+const proof = publishDrawProof({ entries, seed: committedSeed, winners: 1 });
+console.log(verifyDraw(proof, entries).ok); // true
+```
+
+Run the full on-chain flow on TestNet: [`examples/raffle.js`](./examples/raffle.js).
+
+## CLI
+
+```bash
+walletless init [dir]                              # scaffold a starter raffle (ships a .gitignore)
+walletless keygen --out owner.json                 # dev account, written 0600 (never printed)
+walletless draw --entries entries.json --seed <s>  # run + print a recomputable draw proof
+walletless reconcile --ledger ledger.json          # print a reconciliation sheet
+walletless verify --proof proof.json --entries entries.json   # recompute a draw / audit trail
+walletless help
+```
+
+## Guardrails
+
+These are non-negotiable; the modules enforce or document them.
+
+- **TestNet by default.** MainNet is an explicit, cautioned opt-in.
+- **Custodial keys are sensitive.** Ephemeral account keys are server-held, tightly-scoped, and auto-expiring — and **dev/TestNet-grade**. JS cannot wipe key memory; production custody needs your own **KMS/HSM** and an independent audit. Secret keys are never logged, serialized into receipts/events/snapshots, or written on-chain.
+- **Personal data stays off-chain.** The chain holds only non-identifying references. **Hashed contact refs are pseudonymous, not anonymous** — still personal data; use the keyed (peppered) hashing provided, never bare hashes. For erasable references, `pseudonymRef` gives a **random, deletable** on-chain ref so `eraseSubject` truly unlinks the subject.
+- **Draw fairness equals the seed — no more.** A block-hash seed is **manipulable** (a block producer can withhold/grind a block). Use `commitSeedSource` to announce the exact future round **before entries close**, and prefer a **VRF / drand beacon** for anything of value. Winner selection is a deterministic, recomputable function of `(seed, entries)` with rejection sampling — there is **no `Math.random`**. Don't call a draw "provably fair" beyond what your seed guarantees.
+- **Money is integer microALGO.** Never floats (they drift and break reconciliation). Ledger books are append-only with immutable snapshots.
+- **Regulated use.** Prize draws/lotteries are regulated; custodial money handling implies AML/custody duties; processing entrant data makes you a **GDPR data controller**. This package ships transparency tooling, **not** legal compliance — you own licensing, the **free-entry route**, and **age/geo gating**. See **[LEGAL.md](./LEGAL.md)**.
+- **Anything experimental is labelled EXPERIMENTAL · UNAUDITED.** Get an independent audit before holding material value or processing real personal data.
+
+## Supply chain
+
+Pinned dependency floors + committed lockfile; CI runs lint, tests, and `npm audit` on Node 20 & 22 with least-privilege permissions and SHA-pinned actions; `release.yml` publishes with **npm provenance** via OIDC. Report security issues to **security@kirkelabs.com** ([SECURITY.md](./SECURITY.md)).
+
+## Licence
+
+[MIT](./LICENSE) © 2026 Kirke Labs — [www.kirkelabs.com](https://www.kirkelabs.com)

package/bin/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * walletless-kit CLI
+ *
+ *   walletless init [dir]                 scaffold a starter raffle project
+ *   walletless keygen [--out <file>]      generate a dev Algorand account
+ *   walletless draw --entries <f> --seed <s> [--winners N]   run + print a draw proof
+ *   walletless reconcile --ledger <f> [--draw id]            print a reconciliation sheet
+ *   walletless verify --proof <f> [--entries <f>]            recompute a draw proof / audit trail
+ *   walletless help
+ */
+
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import {
+  algosdk,
+  publishDrawProof,
+  verifyDraw,
+  verifyTrail,
+  createLedger,
+} from '../src/index.js';
+
+// Copied from @kirkelabs/oaa-agent-kit — same flag-parsing convention.
+function parse(argv) {
+  const o = { _: [] };
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) o[a.slice(2)] = argv[i + 1]?.startsWith('--') ? true : argv[++i];
+    else o._.push(a);
+  }
+  return o;
+}
+
+function fail(msg) {
+  console.error(`✗ ${msg}`);
+  process.exit(1);
+}
+
+async function main() {
+  const cmd = process.argv[2];
+  const o = parse(process.argv);
+
+  if (cmd === 'keygen') {
+    const a = algosdk.generateAccount();
+    const account = { address: String(a.addr), mnemonic: algosdk.secretKeyToMnemonic(a.sk) };
+    if (o.out) {
+      await writeFile(resolve(o.out), JSON.stringify(account, null, 2), { mode: 0o600 });
+      console.log(`Wrote account to ${resolve(o.out)} (keep the mnemonic secret).`);
+    } else {
+      console.log(JSON.stringify(account, null, 2));
+      console.log(
+        '\n⚠ The mnemonic above is a SECRET (printed to your terminal). Anyone with it' +
+          '\n  controls the account. Prefer: walletless keygen --out owner.json' +
+          '\n⚠ Dev only. Fund on TestNet via https://bank.testnet.algorand.network/',
+      );
+    }
+    return;
+  }
+
+  if (cmd === 'draw') {
+    if (!o.entries || !o.seed) return fail('draw requires --entries <file.json> and --seed <seed>');
+    const entries = JSON.parse(await readFile(resolve(o.entries), 'utf8'));
+    const proof = publishDrawProof({
+      entries,
+      seed: String(o.seed),
+      winners: parseInt(o.winners || '1', 10),
+    });
+    console.log(JSON.stringify(proof, null, 2));
+    return;
+  }
+
+  if (cmd === 'reconcile') {
+    if (!o.ledger) return fail('reconcile requires --ledger <file.json> (an array of ledger entries or {drawId,entries})');
+    const data = JSON.parse(await readFile(resolve(o.ledger), 'utf8'));
+    const entries = Array.isArray(data) ? data : data.entries || [];
+    const l = createLedger();
+    for (const e of entries) l.post(e);
+    const drawId = o.draw || data.drawId || 'draw';
+    console.log(JSON.stringify(l.reconciliationSheet(drawId, { winnerProofLink: o.proof || null }), null, 2));
+    return;
+  }
+
+  if (cmd === 'verify') {
+    const path = o.proof || o.file || o._[0];
+    if (!path) return fail('verify requires --proof <file.json> (a draw proof or an audit trail)');
+    const obj = JSON.parse(await readFile(resolve(path), 'utf8'));
+    if (obj && obj.entriesRoot) {
+      if (!o.entries) return fail('verifying a draw proof also requires --entries <file.json>');
+      const entries = JSON.parse(await readFile(resolve(o.entries), 'utf8'));
+      console.log(JSON.stringify(verifyDraw(obj, entries), null, 2));
+    } else {
+      console.log(JSON.stringify(verifyTrail(obj), null, 2));
+    }
+    return;
+  }
+
+  if (cmd === 'init') {
+    const dir = resolve(o._[0] || 'my-raffle');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'package.json'), STARTER_PKG);
+    await writeFile(join(dir, 'raffle.js'), STARTER_RAFFLE);
+    await writeFile(join(dir, '.env.example'), STARTER_ENV);
+    await writeFile(join(dir, '.gitignore'), STARTER_GITIGNORE);
+    await writeFile(join(dir, 'README.md'), STARTER_README);
+    console.log(
+      `Scaffolded a raffle in ${dir}\n  cd ${dir} && npm install && cp .env.example .env && node raffle.js`,
+    );
+    return;
+  }
+
+  help();
+}
+
+function help() {
+  console.log(`
+walletless-kit — walletless web architecture (onboarding · proofs · audit · ledger · draw)
+
+Commands
+  init [dir]                              scaffold a starter raffle project
+  keygen [--out <file>]                   generate a dev Algorand account (mnemonic)
+  draw --entries <f> --seed <s> [--winners N]
+                                          run a draw and print its recomputable proof
+  reconcile --ledger <f> [--draw id]      print a per-draw reconciliation sheet
+  verify --proof <f> [--entries <f>]      recompute a draw proof or an audit trail
+  help
+
+TestNet by default. Prize draws/lotteries are regulated — see LEGAL.md.
+MIT · Kirke Labs · free & open source
+`);
+}
+
+const STARTER_PKG = `{
+  "name": "my-raffle",
+  "private": true,
+  "type": "module",
+  "dependencies": { "@kirkelabs/walletless-kit": "^0.1.0" }
+}
+`;
+
+const STARTER_ENV = `# Operator account (dev). Generate with: npx walletless keygen --out owner.json
+# SECRET — never commit your real .env. The 25 words control all funds.
+OPERATOR_MNEMONIC="word1 word2 ... word25"
+NETWORK=algorand-testnet
+`;
+
+const STARTER_GITIGNORE = `# Secrets — NEVER commit these. The mnemonic controls all funds.
+.env
+*.key
+owner.json
+node_modules/
+`;
+
+const STARTER_RAFFLE = `import {
+  getAlgod, runDraw, publishDrawProof, verifyDraw,
+  createLedger, OtpIdentity, deterministicOrderId,
+} from '@kirkelabs/walletless-kit';
+
+// A minimal, OFFLINE walletless raffle: entries -> draw -> proof -> verify.
+// See the package's examples/raffle.js for the full on-chain TestNet flow.
+const entries = ['ref_alice', 'ref_bob', 'ref_carol', 'ref_dave'];
+const seed = 'demo-seed-replace-with-a-committed-block-hash';
+
+const proof = publishDrawProof({ entries, seed, winners: 1 });
+console.log('Winner:', proof.winners[0]);
+console.log('Proof verifies:', verifyDraw(proof, entries).ok);
+
+// NOTE: a real draw must use a COMMITTED public seed (announce the future block
+// round before entries close) — see the README guardrails. Prize draws are
+// regulated; you own licensing, the free-entry route, and age/geo gating.
+`;
+
+const STARTER_README = `# my-raffle
+
+A starter walletless raffle built with @kirkelabs/walletless-kit.
+
+1. \`npx walletless keygen --out owner.json\` (TestNet operator account)
+2. Fund it on TestNet: https://bank.testnet.algorand.network/
+3. \`npm install && node raffle.js\`
+
+⚠ Prize draws/lotteries are REGULATED. This is transparency tooling, not legal
+compliance: you are responsible for licensing, a genuine free-entry route, and
+age/geo gating. Draw fairness equals the public seed you choose — use a committed
+block hash or a VRF/beacon. See the package LEGAL.md.
+`;
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});

package/examples/raffle.js

@@ -0,0 +1,101 @@
+/**
+ * examples/raffle.js — a full walletless charity prize-draw on Algorand TestNet.
+ *
+ * Flow: ephemeral guest account -> OTP (stub) -> non-PII order receipts +
+ * on-chain attestation -> audit trail + on-chain anchor -> a draw seeded by a
+ * TestNet block hash -> reconciliation sheet -> verify recomputes the winner.
+ *
+ * Run:  OPERATOR_MNEMONIC="..."  node examples/raffle.js
+ * (Fund the operator on TestNet: https://bank.testnet.algorand.network/)
+ *
+ * ⚠ Demo only. Prize draws are regulated and a block-hash seed is manipulable —
+ * see the README guardrails and LEGAL.md. TestNet by default.
+ */
+
+import {
+  getAlgod,
+  createEphemeralAccount,
+  isExpired,
+  OtpIdentity,
+  buildOrderReceipt,
+  deterministicOrderId,
+  attestOnChain,
+  createTrail,
+  append,
+  trailRoot,
+  anchor,
+  createLedger,
+  publishDrawProof,
+  verifyDraw,
+  blockHashSeed,
+} from '@kirkelabs/walletless-kit';
+import { LocalOwnerSigner } from '@kirkelabs/oaa-agent-kit';
+
+const mnemonic = process.env.OPERATOR_MNEMONIC;
+if (!mnemonic) throw new Error('Set OPERATOR_MNEMONIC (a funded TestNet account).');
+
+const algod = getAlgod({ network: 'algorand-testnet' });
+const operator = new LocalOwnerSigner({ mnemonic });
+const PEPPER = process.env.PEPPER || 'demo-pepper-at-least-16-chars';
+const log = (...a) => console.log(...a);
+
+log('Operator:', operator.address);
+const sp = await algod.getTransactionParams().do();
+log('Current round ~', Number(sp.firstValid), '\n');
+
+// 1) Ephemeral custodial guest account (round-relative expiry).
+const guest = await createEphemeralAccount({ algod, ttlRounds: 10_000, scope: { perTxMicroAlgos: 1_000_000 } });
+log('[1] Ephemeral guest account:', guest.address);
+log('    expiresRound', guest.expiryRound, '| expired now?', isExpired(guest, Number(sp.firstValid)));
+
+// 2) Identity-lite: OTP (we capture the code instead of emailing it).
+const codes = {};
+const id = new OtpIdentity({ pepper: PEPPER, send: async (c, code) => (codes[c] = code) });
+const entrants = ['alice@example.com', 'bob@example.com', 'carol@example.com'];
+const refs = [];
+for (const e of entrants) {
+  await id.issueChallenge(e);
+  const v = await id.verifyChallenge(e, codes[e]);
+  refs.push(v.contactRef);
+}
+log('\n[2] OTP-verified', refs.length, 'entrants (stored as keyed refs, not emails)');
+
+// 3) Non-PII order receipts (hash-chained) + attest the latest hash on-chain.
+const ledger = createLedger();
+let trail = createTrail();
+let prevHash = null;
+let lastReceipt = null;
+refs.forEach((ref, i) => {
+  const orderId = deterministicOrderId({ ref, item: 'raffle-ticket', n: i });
+  const receipt = buildOrderReceipt({ orderId, action: 'buy_ticket', quantity: 1, price: '1000000', agent: ref, previousHash: prevHash });
+  prevHash = receipt.receiptHash;
+  lastReceipt = receipt;
+  ledger.post({ book: 'inflow', amountMicro: 1_000_000, kind: 'ticket', ref: orderId });
+  trail = append(trail, { type: 'ticket_sold', orderId, eventId: `evt_${i}` });
+});
+const att = await attestOnChain(algod, operator, lastReceipt);
+log('\n[3] Receipts chained; latest hash attested on-chain in round', att.confirmedRound);
+log('    txid', att.txid);
+
+// 4) Audit trail -> Merkle root -> on-chain anchor.
+const root = trailRoot(trail);
+const anc = await anchor(algod, operator, root);
+log('\n[4] Audit Merkle root', root.slice(0, 16) + '… anchored in round', anc.confirmedRound);
+
+// 5) Allocate fee + charity in segregated books.
+ledger.post({ book: 'inflow', amountMicro: 100_000, kind: 'fee' });
+ledger.post({ book: 'charity', amountMicro: 2_500_000, ref: operator.address, kind: 'charity_payout', txRef: att.txid });
+
+// 6) Draw, seeded by a recent TestNet block hash (committed in advance in production).
+const seedRound = Number(sp.firstValid) - 5; // a confirmed round
+const seed = await blockHashSeed(algod, seedRound);
+log('\n[5] Seed from TestNet block', seedRound, '(⚠ manipulable — commit in advance / use VRF for value)');
+const proof = publishDrawProof({ entries: refs, seed: seed.value, winners: 1 });
+log('    Winner ref:', proof.winners[0]);
+
+// 7) Reconciliation sheet + independent verification.
+const sheet = ledger.reconciliationSheet('demo-draw-1', { winnerProofLink: `algo:${anc.txid}` });
+log('\n[6] Reconciliation:', JSON.stringify(sheet.charity), '| net', sheet.netMicroAlgos, 'µALGO');
+log('[7] verifyDraw recomputes the winner:', verifyDraw(proof, refs).ok);
+
+log('\n✅ Walletless raffle complete on TestNet: ephemeral onboarding → OTP → receipts+attestation → audit anchor → verifiable draw → reconciliation.');

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@kirkelabs/walletless-kit",
+  "version": "0.1.0",
+  "description": "Walletless web architecture toolkit: low-friction onboarding (ephemeral custodial accounts), receipt-only on-chain proofs, a tamper-evident hash-chained + Merkle audit trail, segregated money ledgers, and a verifiable, recomputable draw. Charity prize-draws are the flagship example; every module is reusable for any walletless commerce flow. Built on @kirkelabs/open-agent-access-core and @kirkelabs/oaa-agent-kit. Free & open source from Kirke Labs.",
+  "type": "module",
+  "bin": {
+    "walletless": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "LICENSE",
+    "LEGAL.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint . --ext .js",
+    "format": "prettier --write \"**/*.{js,json,md}\"",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "walletless",
+    "algorand",
+    "custodial",
+    "onboarding",
+    "audit-trail",
+    "merkle",
+    "verifiable-draw",
+    "raffle",
+    "charity",
+    "receipts",
+    "x402",
+    "oaa",
+    "privacy",
+    "gdpr",
+    "cli",
+    "nodejs"
+  ],
+  "author": "Soleman El Gelawi <soleman@kirkelabs.com> (https://www.kirkelabs.com)",
+  "contributors": [
+    "Steve Kirton <steve@kirkelabs.com> (https://www.kirkelabs.com)"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/KirkeLabs/walletless-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KirkeLabs/walletless-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KirkeLabs/walletless-kit/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "algosdk": "^3.6.0",
+    "@kirkelabs/open-agent-access-core": "^0.1.0",
+    "@kirkelabs/oaa-agent-kit": "^0.7.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0"
+  }
+}