bitlabs-cli-linux-amd64 1.0.8 → 2.0.0

package/packages/callback-core/sqlite-wallet.cjs

@@ -0,0 +1,165 @@
+'use strict';
+// Licensed under the Apache License, Version 2.0. See LICENSE.
+const { DatabaseSync } = require('node:sqlite');
+const { CallbackFailure, validUID, validID } = require('./core.cjs');
+
+// Reference adapter for a Node server with durable local disk. Every process must
+// share this database. Ephemeral/serverless disk or multiple independent replicas
+// are unsupported: replace this adapter with the publisher's transactional wallet.
+class SQLiteWallet {
+  #db; #app; #environment; #policy; #maxBalance; #scale;
+  constructor({ filename, appId, environment, currencyScale, reconciliationPolicy = 'review',
+    maxBalanceMinor = 9000000000000000000n }) {
+    if (!filename || filename === ':memory:') throw new Error('A persistent SQLite filename is required');
+    if (!validID(appId) || !validID(environment)) throw new Error('Explicit app/environment required');
+    if (!Number.isInteger(currencyScale) || currencyScale < 0 || currencyScale > 6) throw new Error('Explicit currencyScale from 0 through 6 required');
+    if (!['review', 'full-reversal'].includes(reconciliationPolicy)) throw new Error('Unknown reconciliation policy');
+    if (typeof maxBalanceMinor !== 'bigint' || maxBalanceMinor <= 0n) throw new Error('Invalid balance bound');
+    this.#app = appId; this.#environment = environment; this.#policy = reconciliationPolicy;
+    this.#maxBalance = maxBalanceMinor; this.#scale = currencyScale;
+    this.#db = new DatabaseSync(filename);
+    this.#db.exec(`PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL;
+      CREATE TABLE IF NOT EXISTS wallet_metadata (
+        app TEXT NOT NULL, environment TEXT NOT NULL, currency_scale INTEGER NOT NULL,
+        PRIMARY KEY(app, environment));
+      CREATE TABLE IF NOT EXISTS accounts (
+        app TEXT NOT NULL, environment TEXT NOT NULL, uid TEXT NOT NULL, balance_minor TEXT NOT NULL,
+        PRIMARY KEY(app, environment, uid));
+      CREATE TABLE IF NOT EXISTS receipts (
+        app TEXT NOT NULL, environment TEXT NOT NULL, namespace TEXT NOT NULL, tx TEXT NOT NULL,
+        uid TEXT NOT NULL, fingerprint TEXT NOT NULL, activity TEXT NOT NULL, ref TEXT,
+        amount_minor TEXT NOT NULL, currency_scale INTEGER NOT NULL, outcome TEXT NOT NULL, reason TEXT,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY(app, environment, namespace, tx));
+      CREATE TABLE IF NOT EXISTS ledger (
+        app TEXT NOT NULL, environment TEXT NOT NULL, tx TEXT NOT NULL, uid TEXT NOT NULL,
+        kind TEXT NOT NULL CHECK(kind IN ('CREDIT','REVERSAL')), amount_minor TEXT NOT NULL, ref TEXT,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY(app, environment, tx),
+        FOREIGN KEY(app, environment, uid) REFERENCES accounts(app, environment, uid));
+      -- Prevent multiple adjustment transaction IDs from reversing the same credit.
+      CREATE UNIQUE INDEX IF NOT EXISTS one_reversal_per_credit ON ledger(app, environment, ref)
+        WHERE kind='REVERSAL';
+      CREATE TABLE IF NOT EXISTS review_actions (
+        id INTEGER PRIMARY KEY, app TEXT NOT NULL, environment TEXT NOT NULL, tx TEXT NOT NULL,
+        actor TEXT NOT NULL, outcome TEXT NOT NULL, reason TEXT, created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP);
+    `);
+    try {
+      this.#transaction(() => {
+        const metadata = this.#db.prepare('SELECT currency_scale FROM wallet_metadata WHERE app=? AND environment=?')
+          .get(this.#app, this.#environment);
+        if (metadata) {
+          if (metadata.currency_scale !== this.#scale) throw new Error('Currency scale change requires an explicit reviewed migration');
+        } else {
+          const existing = this.#db.prepare('SELECT uid FROM accounts WHERE app=? AND environment=? LIMIT 1')
+            .get(this.#app, this.#environment);
+          if (existing) throw new Error('Existing wallet without currency metadata requires an explicit reviewed migration');
+          this.#db.prepare('INSERT INTO wallet_metadata(app,environment,currency_scale) VALUES(?,?,?)')
+            .run(this.#app, this.#environment, this.#scale);
+        }
+      });
+    } catch (error) { this.#db.close(); throw error; }
+  }
+  #transaction(work) {
+    this.#db.exec('BEGIN IMMEDIATE');
+    try { const value = work(); this.#db.exec('COMMIT'); return value; }
+    catch (error) { this.#db.exec('ROLLBACK'); throw error; }
+  }
+  #receipt(tx, namespace = 'live') {
+    return this.#db.prepare('SELECT * FROM receipts WHERE app=? AND environment=? AND namespace=? AND tx=?')
+      .get(this.#app, this.#environment, namespace, tx);
+  }
+  #account(uid) {
+    return this.#db.prepare('SELECT * FROM accounts WHERE app=? AND environment=? AND uid=?')
+      .get(this.#app, this.#environment, uid);
+  }
+  #recordLedger(event, kind, delta) {
+    const account = this.#account(event.uid);
+    if (!account) throw new CallbackFailure('UNKNOWN_USER', 404);
+    const next = BigInt(account.balance_minor) + delta;
+    if (next < 0n || next > this.#maxBalance) throw new CallbackFailure('BALANCE_OUT_OF_BOUNDS');
+    this.#db.prepare('INSERT INTO ledger(app,environment,tx,uid,kind,amount_minor,ref) VALUES(?,?,?,?,?,?,?)')
+      .run(this.#app, this.#environment, event.tx, event.uid, kind, delta.toString(), event.ref);
+    this.#db.prepare('UPDATE accounts SET balance_minor=? WHERE app=? AND environment=? AND uid=?')
+      .run(next.toString(), this.#app, this.#environment, event.uid);
+  }
+  #reverse(event) {
+    const original = this.#receipt(event.ref);
+    if (!original) return { outcome: 'held', applied: false, reason: 'ORIGINAL_NOT_OBSERVED' };
+    if (original.activity !== 'COMPLETE' || original.outcome !== 'credited' || original.uid !== event.uid)
+      return { outcome: 'held', applied: false, reason: 'ORIGINAL_MISMATCH' };
+    if (original.currency_scale !== event.currencyScale || BigInt(original.amount_minor) <= 0n ||
+        (event.amountMinor < 0n ? -event.amountMinor : event.amountMinor) !== BigInt(original.amount_minor))
+      return { outcome: 'held', applied: false, reason: 'PARTIAL_OR_UNKNOWN_ADJUSTMENT' };
+    const reversed = this.#db.prepare("SELECT tx FROM ledger WHERE app=? AND environment=? AND ref=? AND kind='REVERSAL'")
+      .get(this.#app, this.#environment, event.ref);
+    if (reversed) return { outcome: 'held', applied: false, reason: 'ORIGINAL_ALREADY_REVERSED' };
+    const account = this.#account(event.uid);
+    if (!account) return { outcome: 'held', applied: false, reason: 'ORIGINAL_ACCOUNT_UNAVAILABLE' };
+    if (BigInt(account.balance_minor) < BigInt(original.amount_minor))
+      return { outcome: 'held', applied: false, reason: 'INSUFFICIENT_BALANCE' };
+    this.#recordLedger(event, 'REVERSAL', -BigInt(original.amount_minor));
+    return { outcome: 'reversed', applied: true };
+  }
+  apply(event) {
+    if (event.appId !== this.#app || event.environment !== this.#environment)
+      throw new CallbackFailure('APP_ENVIRONMENT_MISMATCH', 409);
+    if (event.currencyScale !== this.#scale) throw new CallbackFailure('CURRENCY_SCALE_MISMATCH', 409);
+    if (!validUID(event.uid) || !validID(event.tx) || typeof event.amountMinor !== 'bigint' ||
+        !['COMPLETE', 'RECONCILIATION'].includes(event.activity) ||
+        typeof event.debug !== 'boolean' || !Number.isInteger(event.currencyScale) || event.currencyScale < 0 || event.currencyScale > 6 ||
+        (event.activity === 'RECONCILIATION' && (!validID(event.ref) || event.ref === event.tx)) ||
+        !/^[a-f0-9]{64}$/.test(event.fingerprint) ||
+        (event.activity === 'COMPLETE' && event.amountMinor < 0n)) throw new CallbackFailure('INVALID_EVENT');
+    return this.#transaction(() => {
+      const namespace = event.debug ? 'debug' : 'live';
+      const prior = this.#receipt(event.tx, namespace);
+      if (prior) {
+        if (prior.fingerprint !== event.fingerprint) throw new CallbackFailure('DUPLICATE_CONTENT_CONFLICT', 409);
+        return prior.outcome === 'held' ? { outcome: 'held', applied: false, reason: prior.reason }
+          : { outcome: 'duplicate', applied: false };
+      }
+      if (!event.debug && !this.#account(event.uid)) throw new CallbackFailure('UNKNOWN_USER', 404);
+      let result;
+      if (event.debug) result = { outcome: 'debug', applied: false };
+      else if (event.activity === 'COMPLETE') {
+        this.#recordLedger(event, 'CREDIT', event.amountMinor);
+        result = { outcome: 'credited', applied: true };
+      } else result = this.#policy === 'full-reversal' ? this.#reverse(event)
+        : { outcome: 'held', applied: false, reason: 'RECONCILIATION_POLICY_REVIEW' };
+      this.#db.prepare(`INSERT INTO receipts(app,environment,namespace,tx,uid,fingerprint,activity,ref,
+        amount_minor,currency_scale,outcome,reason) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`)
+        .run(this.#app, this.#environment, namespace, event.tx, event.uid, event.fingerprint, event.activity,
+          event.ref, event.amountMinor.toString(), event.currencyScale, result.outcome, result.reason || null);
+      return result;
+    });
+  }
+  // Called only by the publisher's reviewed administrative workflow, never by HTTP input.
+  // Explicitly approves a full reversal of this exact held receipt; no partial policy is inferred.
+  resolveHeld(tx, { expectedFingerprint, actor }) {
+    if (!validID(actor)) throw new CallbackFailure('REVIEW_ACTOR_REQUIRED');
+    return this.#transaction(() => {
+      const held = this.#receipt(tx);
+      if (!held || held.fingerprint !== expectedFingerprint) throw new CallbackFailure('STALE_REVIEW', 409);
+      if (held.outcome !== 'held') return { outcome: 'duplicate', applied: false };
+      const result = this.#reverse({ tx, uid: held.uid, ref: held.ref,
+        amountMinor: BigInt(held.amount_minor), currencyScale: held.currency_scale });
+      this.#db.prepare('UPDATE receipts SET outcome=?,reason=? WHERE app=? AND environment=? AND namespace=? AND tx=?')
+        .run(result.outcome, result.reason || null, this.#app, this.#environment, 'live', tx);
+      this.#db.prepare('INSERT INTO review_actions(app,environment,tx,actor,outcome,reason) VALUES(?,?,?,?,?,?)')
+        .run(this.#app, this.#environment, tx, actor, result.outcome, result.reason || null);
+      return result;
+    });
+  }
+  // Account creation is a server/admin operation. Never create accounts from callbacks.
+  addAccount(uid, initialBalanceMinor = 0n) {
+    if (!validUID(uid) || typeof initialBalanceMinor !== 'bigint' || initialBalanceMinor < 0n || initialBalanceMinor > this.#maxBalance)
+      throw new Error('Invalid account');
+    this.#db.prepare('INSERT INTO accounts(app,environment,uid,balance_minor) VALUES(?,?,?,?)')
+      .run(this.#app, this.#environment, uid, initialBalanceMinor.toString());
+  }
+  getBalance(uid) { const row = this.#account(uid); return row ? BigInt(row.balance_minor) : null; }
+  getReceipt(tx, namespace = 'live') { return this.#receipt(tx, namespace) || null; }
+  close() { this.#db.close(); }
+}
+module.exports = { SQLiteWallet };

package/packages/callback-core/test/callback.test.cjs

@@ -0,0 +1,265 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { mkdtempSync, rmSync } = require('node:fs');
+const { tmpdir } = require('node:os');
+const path = require('node:path');
+const { createHmac } = require('node:crypto');
+const { DatabaseSync } = require('node:sqlite');
+const { Worker } = require('node:worker_threads');
+const { createCallbackHandler } = require('../core.cjs');
+const { SQLiteWallet } = require('../sqlite-wallet.cjs');
+const origin = 'https://rewards.fixture.invalid';
+const secret = 'synthetic-fixture-secret';
+const corePath = path.resolve(__dirname, '../core.cjs');
+const walletPath = path.resolve(__dirname, '../sqlite-wallet.cjs');
+function options(wallet, overrides = {}) {
+  return { appId: 'fixture-app', environment: 'staging', secret, publicOrigin: origin,
+    callbackPath: '/bitlabs/callback', currencyScale: 2, maxRewardMinor: 1000000n, wallet, ...overrides };
+}
+function signRaw(query, { signingSecret = secret, signingOrigin = origin, targetPath = '/bitlabs/callback' } = {}) {
+  const target = targetPath + '?' + query;
+  return target + '&hash=' + createHmac('sha1', signingSecret).update(signingOrigin + target).digest('hex');
+}
+function signed(params = {}, signing = {}) {
+  return signRaw(new URLSearchParams({ uid: 'user_1', tx: 'event_1', val: '5.25', usd: '1.00',
+    activity_type: 'COMPLETE', ...params }).toString(), signing);
+}
+function fixture(t, policy = 'review') {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bitlabs-callback-'));
+  const filename = path.join(dir, 'wallet.sqlite');
+  const wallet = new SQLiteWallet({ filename, appId: 'fixture-app', environment: 'staging', currencyScale: 2, reconciliationPolicy: policy });
+  wallet.addAccount('user_1');
+  t.after(() => { wallet.close(); rmSync(dir, { recursive: true, force: true }); });
+  return { filename, wallet, handle: createCallbackHandler(options(wallet)) };
+}
+function body(response) { return JSON.parse(response.body); }
+
+test('valid signed currency value is committed once; missing/invalid signatures fail closed', async t => {
+  const { wallet, handle } = fixture(t);
+  for (const rawTarget of ['/bitlabs/callback?uid=user_1', signed().replace(/.$/, 'z'),
+    signed({}, { signingSecret: 'wrong' }), signed({ debug: 'true' }).split('&hash=')[0]]) {
+    const response = await handle({ rawTarget });
+    assert.equal(response.status, 403); assert.equal(response.headers['Cache-Control'], 'no-store, max-age=0');
+  }
+  assert.equal(wallet.getBalance('user_1'), 0n);
+  const response = await handle({ rawTarget: signed() });
+  assert.deepEqual(body(response), { outcome: 'CREDITED', applied: true });
+  assert.equal(wallet.getBalance('user_1'), 525n); // USD is not multiplied into the reward.
+  assert.equal(body(await handle({ rawTarget: signed() })).outcome, 'DUPLICATE');
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('raw encoding is authenticated exactly; duplicate parameters and malformed encoding are rejected', async t => {
+  const { wallet, handle } = fixture(t);
+  const query = 'uid=user_1&tx=encoded&val=1.25&activity_type=COMPLETE&note=%2F%20%2b%CE%B1+z';
+  assert.equal((await handle({ rawTarget: signRaw(query) })).status, 200);
+  assert.equal((await handle({ rawTarget: signRaw(query).replace('%2F', '%2f') })).status, 403);
+  assert.equal((await handle({ rawTarget: signRaw(query + '&uid=user_2') })).status, 400);
+  assert.equal((await handle({ rawTarget: signRaw(query + '&%75id=user_2') })).status, 400);
+  assert.equal((await handle({ rawTarget: signRaw(query + '&hash=extra') })).status, 400);
+  for (const encoding of ['%GG', '%FF', '%'])
+    assert.equal((await handle({ rawTarget: signRaw(query.replace('encoded', 'bad') + '&bad=' + encoding) })).status, 400);
+  assert.equal(wallet.getBalance('user_1'), 125n);
+});
+
+test('configured origin and exact path are the only signing authority', async t => {
+  const { handle } = fixture(t);
+  assert.equal((await handle({ rawTarget: signed({}, { signingOrigin: 'https://attacker.invalid' }) })).status, 403);
+  assert.equal((await handle({ rawTarget: signed({}, { targetPath: '/rewritten' }) })).status, 400);
+  assert.equal((await handle({ rawTarget: origin + signed() })).status, 400);
+  assert.equal((await handle({ rawTarget: signed(), method: 'POST' })).status, 405);
+  assert.throws(() => createCallbackHandler(options({}, { publicOrigin: 'https://x.invalid/path' })));
+});
+
+test('signed debug creates an isolated persisted receipt without consuming live transaction identities', async t => {
+  const { wallet, handle } = fixture(t);
+  assert.equal(body(await handle({ rawTarget: signed({ debug: 'true' }) })).outcome, 'DEBUG');
+  assert.equal(wallet.getBalance('user_1'), 0n);
+  assert.equal(wallet.getReceipt('event_1'), null);
+  assert.equal(wallet.getReceipt('event_1', 'debug').outcome, 'debug');
+  assert.equal(body(await handle({ rawTarget: signed() })).outcome, 'CREDITED');
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('unknown users and invalid/missing fields never create accounts or successful receipts', async t => {
+  const { wallet, handle } = fixture(t);
+  assert.equal((await handle({ rawTarget: signed({ uid: 'missing_user' }) })).status, 404);
+  for (const changed of [{ uid: '' }, { uid: 'a'.repeat(66) }, { tx: '' }, { activity_type: 'OTHER' },
+    { debug: '1' }, { val: '' }, { val: 'NaN' }, { val: 'Infinity' }, { val: '1e3' }, { val: '-1' },
+    { val: '0x10' }, { val: '1.001' }, { val: '10000.01' }, { val: '9007199254740993' }]) {
+    assert.equal((await handle({ rawTarget: signed(changed) })).status, 422, JSON.stringify(changed));
+  }
+  assert.equal(wallet.getBalance('missing_user'), null);
+  assert.equal(wallet.getBalance('user_1'), 0n);
+  assert.equal(wallet.getReceipt('event_1'), null);
+});
+
+test('fixed-scale zero and fractional rewards have exact integer balances', async t => {
+  const { wallet, handle } = fixture(t);
+  for (const [tx, val] of [['zero', '0'], ['decimal1', '0.10'], ['decimal2', '0.20']])
+    assert.equal((await handle({ rawTarget: signed({ tx, val }) })).status, 200);
+  assert.equal(wallet.getBalance('user_1'), 30n);
+});
+
+test('a conflicting duplicate never silently replaces a persisted reward', async t => {
+  const { wallet, handle } = fixture(t);
+  await handle({ rawTarget: signed() });
+  const response = await handle({ rawTarget: signed({ val: '7.00' }) });
+  assert.equal(response.status, 409); assert.equal(body(response).outcome, 'DUPLICATE_CONTENT_CONFLICT');
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('duplicate delivery survives another connection and a restart', async t => {
+  const { wallet, handle, filename } = fixture(t);
+  await handle({ rawTarget: signed() });
+  for (let i = 0; i < 2; i++) {
+    const another = new SQLiteWallet({ filename, appId: 'fixture-app', environment: 'staging', currencyScale: 2 });
+    assert.equal(body(await createCallbackHandler(options(another))({ rawTarget: signed() })).outcome, 'DUPLICATE');
+    another.close();
+  }
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('concurrent separate connections credit once under SQLite uniqueness and atomic transactions', async t => {
+  const { wallet, filename } = fixture(t);
+  const results = await Promise.all(Array.from({ length: 6 }, () => new Promise((resolve, reject) => {
+    const worker = new Worker(`
+      const { parentPort, workerData } = require('node:worker_threads');
+      const { SQLiteWallet } = require(workerData.walletPath);
+      const { createCallbackHandler } = require(workerData.corePath);
+      const wallet = new SQLiteWallet({ filename: workerData.filename, appId:'fixture-app', environment:'staging',currencyScale:2 });
+      createCallbackHandler({appId:'fixture-app',environment:'staging',secret:workerData.secret,
+        publicOrigin:workerData.origin,callbackPath:'/bitlabs/callback',currencyScale:2,maxRewardMinor:1000000n,wallet})
+        ({rawTarget:workerData.rawTarget}).then(result => { wallet.close(); parentPort.postMessage(result); });
+    `, { eval: true, workerData: { filename, walletPath, corePath, secret, origin, rawTarget: signed() } });
+    worker.once('message', resolve); worker.once('error', reject);
+    worker.once('exit', code => { if (code) reject(new Error('Worker exited ' + code)); });
+  })));
+  assert.equal(results.filter(result => body(result).outcome === 'CREDITED').length, 1);
+  assert.equal(results.filter(result => body(result).outcome === 'DUPLICATE').length, 5);
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('receipt-write failure rolls back ledger and balance; a later retry succeeds', async t => {
+  const { wallet, handle, filename } = fixture(t);
+  const db = new DatabaseSync(filename);
+  db.exec("CREATE TRIGGER fixture_failure BEFORE INSERT ON receipts BEGIN SELECT RAISE(ABORT, 'synthetic failure'); END;");
+  assert.equal((await handle({ rawTarget: signed() })).status, 503);
+  assert.equal(wallet.getBalance('user_1'), 0n); assert.equal(wallet.getReceipt('event_1'), null);
+  assert.equal(db.prepare('SELECT COUNT(*) n FROM ledger').get().n, 0);
+  db.exec('DROP TRIGGER fixture_failure'); db.close();
+  assert.equal(body(await handle({ rawTarget: signed() })).outcome, 'CREDITED');
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('handler awaits durable storage and never acknowledges an adapter failure', async () => {
+  let commit;
+  const handler = createCallbackHandler(options({ apply: () => new Promise(resolve => { commit = resolve; }) }));
+  let finished = false;
+  const response = handler({ rawTarget: signed() }).then(r => { finished = true; return r; });
+  await new Promise(resolve => setImmediate(resolve)); assert.equal(finished, false);
+  commit({ outcome: 'credited', applied: true }); assert.equal((await response).status, 200);
+  const broken = createCallbackHandler(options({ apply() { throw new Error('private database details'); } }));
+  const result = await broken({ rawTarget: signed() });
+  assert.equal(result.status, 503); assert.equal(result.body.includes('private'), false);
+});
+
+test('default reconciliation policy durably holds a referenced adjustment without changing balances', async t => {
+  const { wallet, handle } = fixture(t);
+  await handle({ rawTarget: signed() });
+  const rawTarget = signed({ tx: 'adjustment', ref: 'event_1', activity_type: 'RECONCILIATION' });
+  const result = await handle({ rawTarget });
+  assert.deepEqual(body(result), { outcome: 'REVIEW_REQUIRED', applied: false, reason: 'RECONCILIATION_POLICY_REVIEW' });
+  assert.equal(result.status, 200); assert.equal(wallet.getReceipt('adjustment').outcome, 'held');
+  assert.equal(body(await handle({ rawTarget })).outcome, 'REVIEW_REQUIRED');
+  assert.equal(wallet.getBalance('user_1'), 525n);
+});
+
+test('explicit full-reversal policy handles positive or negative adjustment values once', async t => {
+  const { wallet, handle } = fixture(t, 'full-reversal');
+  for (const [tx, val] of [['positive', '5.25'], ['negative', '-5.25']]) {
+    await handle({ rawTarget: signed({ tx }) });
+    const rawTarget = signed({ tx: tx + '_rev', ref: tx, val, activity_type: 'RECONCILIATION' });
+    assert.equal(body(await handle({ rawTarget })).outcome, 'REVERSED');
+    assert.equal(body(await handle({ rawTarget })).outcome, 'DUPLICATE');
+    assert.equal(wallet.getBalance('user_1'), 0n);
+    const again = await handle({ rawTarget: signed({ tx: tx + '_rev2', ref: tx, val, activity_type: 'RECONCILIATION' }) });
+    assert.equal(body(again).reason, 'ORIGINAL_ALREADY_REVERSED');
+  }
+});
+
+test('partial adjustment, wrong original user and insufficient balance are held', async t => {
+  const { wallet, handle, filename } = fixture(t, 'full-reversal');
+  await handle({ rawTarget: signed() });
+  assert.equal(body(await handle({ rawTarget: signed({ tx: 'partial', val: '2', ref: 'event_1', activity_type: 'RECONCILIATION' }) })).reason,
+    'PARTIAL_OR_UNKNOWN_ADJUSTMENT');
+  wallet.addAccount('user_2');
+  assert.equal(body(await handle({ rawTarget: signed({ uid: 'user_2', tx: 'wrong-user', ref: 'event_1', activity_type: 'RECONCILIATION' }) })).reason,
+    'ORIGINAL_MISMATCH');
+  const db = new DatabaseSync(filename); // Simulate spending performed by the publisher's wallet.
+  db.prepare("UPDATE accounts SET balance_minor='0' WHERE uid='user_1'").run(); db.close();
+  assert.equal(body(await handle({ rawTarget: signed({ tx: 'spent', ref: 'event_1', activity_type: 'RECONCILIATION' }) })).reason,
+    'INSUFFICIENT_BALANCE');
+  assert.equal(wallet.getBalance('user_1'), 0n);
+});
+
+test('adjustment before original remains held until an explicit audited resolution', async t => {
+  const { wallet, handle, filename } = fixture(t, 'full-reversal');
+  const adjustment = signed({ tx: 'early', ref: 'event_1', activity_type: 'RECONCILIATION' });
+  assert.equal(body(await handle({ rawTarget: adjustment })).reason, 'ORIGINAL_NOT_OBSERVED');
+  await handle({ rawTarget: signed() });
+  assert.equal(wallet.getBalance('user_1'), 525n);
+  const receipt = wallet.getReceipt('early');
+  assert.throws(() => wallet.resolveHeld('early', { expectedFingerprint: 'wrong', actor: 'reviewer_1' }));
+  assert.deepEqual(wallet.resolveHeld('early', { expectedFingerprint: receipt.fingerprint, actor: 'reviewer_1' }),
+    { outcome: 'reversed', applied: true });
+  assert.equal(wallet.getBalance('user_1'), 0n);
+  assert.equal(wallet.resolveHeld('early', { expectedFingerprint: receipt.fingerprint, actor: 'reviewer_1' }).applied, false);
+  const db = new DatabaseSync(filename); assert.equal(db.prepare('SELECT COUNT(*) n FROM review_actions').get().n, 1); db.close();
+});
+
+test('application and environment namespaces remain separate', async t => {
+  const { wallet, handle, filename } = fixture(t);
+  await handle({ rawTarget: signed() });
+  const production = new SQLiteWallet({ filename, appId: 'fixture-app', environment: 'production', currencyScale: 2 });
+  production.addAccount('user_1');
+  const productionHandler = createCallbackHandler(options(production, { environment: 'production', secret: 'production-synthetic' }));
+  assert.equal((await productionHandler({ rawTarget: signed() })).status, 403);
+  assert.equal((await productionHandler({ rawTarget: signed({}, { signingSecret: 'production-synthetic' }) })).status, 200);
+  assert.equal(production.getBalance('user_1'), 525n); assert.equal(wallet.getBalance('user_1'), 525n);
+  const mismatch = createCallbackHandler(options(wallet, { environment: 'production' }));
+  assert.equal((await mismatch({ rawTarget: signed() })).status, 409);
+  production.close();
+});
+
+test('official historical HMAC example authenticates without URL normalization', async () => {
+  // Public documentation fixture, not a production credential. Verified 2026-09-22:
+  // https://developer.bitlabs.ai/docs/securing-callbacks-through-hashing
+  const handler = createCallbackHandler(options({ apply() { throw new Error('incomplete legacy payload'); } }, {
+    publicOrigin: 'https://publisher.com', callbackPath: '/complete', secret: 'JLOIAUNMHFli7ZJOQVEzm98rzqnm9',
+  }));
+  const response = await handler({ rawTarget: '/complete?uid=8cc877ee-af19-488d-b28d-216fb866b996&val=500&hash=dbcd6bb8ca677344592842a52b4fca9bec36cd4b' });
+  // Signature is valid. The old docs example omits our required transaction/activity fields.
+  assert.equal(response.status, 422); assert.equal(body(response).outcome, 'INVALID_TRANSACTION_ID');
+});
+
+test('wallet currency scale is bound durably and cannot silently change on another deployment', async t => {
+  const { wallet, handle, filename } = fixture(t);
+  await handle({ rawTarget: signed() });
+  assert.throws(() => new SQLiteWallet({ filename, appId: 'fixture-app', environment: 'staging', currencyScale: 0 }),
+    /explicit reviewed migration/);
+  const changed = createCallbackHandler(options(wallet, { currencyScale: 0 }));
+  const response = await changed({ rawTarget: signed({ tx: 'changed-scale', val: '5' }) });
+  assert.equal(response.status, 409); assert.equal(body(response).outcome, 'CURRENCY_SCALE_MISMATCH');
+  assert.equal(wallet.getBalance('user_1'), 525n); assert.equal(wallet.getReceipt('changed-scale'), null);
+});
+
+test('adapter-provided reasons and custom errors cannot expose arbitrary runtime data', async () => {
+  const handler = createCallbackHandler(options({ apply: () => ({ outcome: 'held', applied: false, reason: 'secret or raw callback URL' }) }));
+  const response = await handler({ rawTarget: signed() });
+  assert.equal(body(response).reason, 'REVIEW_REQUIRED'); assert.equal(response.body.includes('secret'), false);
+  const { CallbackFailure } = require('../core.cjs');
+  const failed = createCallbackHandler(options({ apply: () => { throw new CallbackFailure('private runtime detail', 422); } }));
+  assert.equal(body(await failed({ rawTarget: signed() })).outcome, 'TEMPORARY_STORAGE_FAILURE');
+});

package/schemas/capabilities.json

@@ -0,0 +1,86 @@
+{
+  "schema_version": "1",
+  "release_status": "unreleased",
+  "operations": [
+    {
+      "id": "management.app.read",
+      "documented": true,
+      "enabled": "pinned-helper-staging",
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Read selected app in dashboard"
+    },
+    {
+      "id": "management.app.create",
+      "documented": true,
+      "enabled": "pinned-helper-staging",
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Create app in dashboard"
+    },
+    {
+      "id": "management.safe-config.patch",
+      "documented": true,
+      "enabled": "pinned-helper-staging",
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Configure reviewed fields in dashboard"
+    },
+    {
+      "id": "management.currency.patch",
+      "documented": true,
+      "enabled": false,
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Review base conversion, reward share and preview in dashboard"
+    },
+    {
+      "id": "management.app-token.retrieve",
+      "documented": false,
+      "enabled": false,
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Copy public App/API Token from dashboard into public client configuration"
+    },
+    {
+      "id": "callbacks.register",
+      "documented": false,
+      "enabled": false,
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Save general reward callback in dashboard"
+    },
+    {
+      "id": "callbacks.test-url",
+      "documented": true,
+      "enabled": false,
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Use dashboard Callback Tester; nested API payload, permissions and debug behavior require live validation"
+    },
+    {
+      "id": "callbacks.perform-test",
+      "documented": false,
+      "enabled": false,
+      "live_contract_verified": false,
+      "last_live_verification": null,
+      "fallback": "Use dashboard Callback Tester"
+    }
+  ],
+  "recipes": [
+    {
+      "id": "iframe-node-sqlite-v1",
+      "implementation": "local-reference",
+      "provider_delivery_verified": false,
+      "production_certified": false,
+      "host": "Node with persistent local disk; not ephemeral/serverless storage",
+      "wallet": "SQLite reference or separately certified existing wallet adapter",
+      "deferred": [
+        "user-based API",
+        "native SDKs",
+        "serverless SQLite",
+        "additional hosts"
+      ]
+    }
+  ]
+}

package/schemas/evidence.schema.json

@@ -0,0 +1,110 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": "1"
+    },
+    "setup_id": {
+      "type": "string",
+      "pattern": "^(?![Bb][Ll][Pp][Uu][Bb]_)[A-Za-z0-9][A-Za-z0-9_-]{0,79}$"
+    },
+    "plan_sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "app_id": {
+      "type": "string",
+      "pattern": "^(?![Bb][Ll][Pp][Uu][Bb]_)[A-Za-z0-9][A-Za-z0-9_-]{0,79}$"
+    },
+    "environment": {
+      "type": "string",
+      "enum": [
+        "staging",
+        "production"
+      ]
+    },
+    "recipe": {
+      "const": "iframe-node-sqlite-v1"
+    },
+    "implementation_revision": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{40}$"
+    },
+    "checks": {
+      "type": "array",
+      "maxItems": 9,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": [
+              "client_build",
+              "signature_fixtures",
+              "wallet_transactions",
+              "reconciliation",
+              "debug_isolation",
+              "callback_registered",
+              "signed_callback_observed",
+              "wallet_test_isolation",
+              "production_approval"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "PASS",
+              "FAIL",
+              "NOT_RUN",
+              "HUMAN_CONFIRMED"
+            ]
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "local_test",
+              "server_receipt",
+              "human"
+            ]
+          },
+          "observed_at": {
+            "type": "string"
+          },
+          "implementation_revision": {
+            "type": "string"
+          },
+          "artifact_sha256": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "note": {
+            "type": "string",
+            "maxLength": 300
+          }
+        },
+        "required": [
+          "id",
+          "status",
+          "source",
+          "observed_at",
+          "implementation_revision"
+        ]
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "setup_id",
+    "plan_sha256",
+    "app_id",
+    "environment",
+    "recipe",
+    "implementation_revision",
+    "checks"
+  ],
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "BitLabs reported completion evidence v1",
+  "description": "Imported evidence is not an authenticated attestation. CLI enforces source/status/age/revision binding."
+}