ckb-session-kit 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,305 @@
 This project follows [semantic versioning](https://semver.org/). The session lock is
 deployed on CKB **testnet only**; there is no mainnet deployment yet.
 
+## 2.0.0 (2026-11-03)
+
+### Upgrading from 1.0.0
+Every 1.0.0 export is still there with the same signature; new parameters are
+optional. Some calls that 1.0.0 accepted are now refused, on purpose:
+- `assertSigningLock`, `openSession`, `openSubscription` refuse an owner (or
+  charger) lock that opens with no signature: PW-Lock (its deployed build is
+  anyone-can-pay) and the Nostr lock in proof of work mode
+  (`reason: "owner-lock-unsafe"`; no option lets these through). Sessions
+  already open under such a lock should be closed or recovered now.
+- They also refuse configurations not reviewed: Omnilock auth 0x07 or mode bits
+  other than time-lock (0x04) and supply (0x08), secp256k1, multisig or Nostr
+  locks with args their code would not accept, and any unknown lock
+  (`reason: "owner-lock-unreviewed"`). Pass `allowUnreviewedOwnerLock: true`
+  once you have checked the lock to get the 1.0.0 behaviour back, with a warning;
+  for the creator's charger lock in `openSubscription`, pass
+  `allowUnreviewedChargerLock: true`.
+- Anyone-can-pay, PW-Lock and always-success referenced by data hash
+  (`data`, `data1`, `data2`) are refused like their type-hash versions.
+- A send whose outcome cannot be checked throws `SendOutcomeUnknownError`
+  (with the tx hash); it is never retried, so check the hash before resending.
+- `openSession` and `openSubscription` refuse `TESTNET_LEGACY_DEPLOYMENTS`,
+  `hashType: "data"`, and a deployment whose cell dep does not hold its code on
+  the client's network (one `getCellLive` per client and deployment).
+- `closeSession` refuses a signer whose lock is not the session's owner lock.
+- `openSession` with no rate limit, or `minInterval` 1, calls `console.warn`
+  (or `opts.onWarning`).
+- `SessionPolicyError` and `SessionBalanceError` carry a `reason`; code that
+  matched error messages should match `reason` instead.
+
+The wallet matrix's locks (secp256k1, Omnilock 0x12 / Bitcoin / Dogecoin,
+Nostr signing mode, JoyID) all pass unchanged.
+
+### Fixed (Week 6 adversarial review, 2 Nov)
+- Token subscriptions: look-alike cells typed `xUDT(token.args ++ extra)`
+  (xUDT accepts them, anyone can create them with 0 units, and the indexer's
+  type filter matched them by prefix) counted toward `MAX_SUBSCRIPTION_CELLS`
+  but were never swept. The filter now asks for the exact script length, only
+  cells really of the subscription's kind count, raw reads are bounded, and
+  `clearPlantedCells` and `cancelSubscription` sweep spendable look-alikes back
+  to the subscriber (M1).
+- A status or a charge counted every recent transaction under the lock toward
+  its budget of 64, creations by anyone included, and before the age check.
+  Now only spends count, an entry older than the period is never counted, and
+  creation-only entries are paged past under their own budget of 1024
+  (`MAX_CREATED_HISTORY`); past either budget it still refuses (M2).
+- `clearPlantedCells`: sweeps at most 30 cells per transaction, so a status
+  never dates the cleanup as a charge (L3); with cells left unread, sweeps the
+  planted cells it read instead of refusing (L1); marks its transaction with
+  `CLEAR_PLANTED_MEMO` in the subscriber's own witness, so a status does not
+  take it for a cancel and a charge of the whole balance stays paid (L2).
+- `signAndSend` throws `SendOutcomeUnknownError` (new export) when a send fails
+  and the status lookup fails too, instead of rethrowing the send's error: a
+  `Dead` answer from CCC's fallback node after a lost reply was retried and
+  could pay twice (L4). It is never retried.
+- Payout cells under `payTo` are listed by the indexer's filter (plain and
+  empty, or exactly the token with 16 data bytes), so junk planted under an
+  anyone-can-pay address no longer pushes the real cells out of reach (L5).
+- `assertSigningLock` refuses anyone-can-pay, PW-Lock and always-success by the
+  data hash of their deployed binaries under every data hash_type (`data`,
+  `data1`, `data2`), not only by type id (L6).
+
+### Changed (Week 6 adversarial review, 2 Nov)
+- `openSubscription` checks the creator's charger lock with its own opt-in,
+  `allowUnreviewedChargerLock`; `allowUnreviewedOwnerLock` now covers the
+  subscriber's lock only (I1).
+- `openSession` raises `no-rate-limit` for `minInterval` 1 too (I3).
+- The testnet scripts keep `.env.smoke` at the repository root whatever the
+  current directory (I4).
+- Docs: a multisig with a since or an Omnilock time-lock also delays the
+  owner's sweep (I2).
+
+### Added (mentor review, tracker #47, 2 Nov)
+- Payout cell contention. A top-up (`spendInSession` with `topUp`,
+  `chargeSubscription`, `openSubscription`) picks the recipient's cell with
+  `pickPayoutCell`: confirmed cells first, shuffled, and the first free one of
+  up to `MAX_POOL_CHECKS` (4) cells checked with `get_live_cell` and
+  `include_tx_pool`, so a cell another payment in the node's pool spends is
+  skipped. At most `MAX_PAYOUT_CELLS` (64) of the recipient's cells are read.
+- `spendInSession` and `chargeSubscription` take `retry: { attempts, delayMs }`
+  (`RetryOptions`, `DEFAULT_RETRY`: 3 attempts, 1000 ms doubling, with jitter).
+  A send the node refuses for a spent input (`Dead`, `Unknown`, or an RBF
+  refusal, `poolConflict`) is built again with another payout cell; the cell a
+  `Dead` refusal names is not picked again. It used to be retried once, with no
+  wait, and only with a client cache. A send whose outcome is unknown is still
+  never retried.
+- `SessionBalanceError` reason `"payout-busy"`: every payout cell checked is
+  spent in the pool and none is left. Nothing is sent; it is retried like a
+  refusal. The demo's charge route answers it with 503 and retry.
+- `createPayoutCells(funder, payTo, { count, capacity?, token? })` gives an
+  anyone-can-pay address more cells to top up. `npm run setup:creator` uses it
+  and now gives the demo's creator eight cells (was three).
+- `clearPlantedCells(subscriber, deployment, subscription)`: the subscriber
+  sweeps cells a third party created under the subscription's lock back to
+  itself, keeping the subscription's own cells, so it no longer has to cancel
+  and open again past `MAX_SUBSCRIPTION_CELLS`.
+
+### Changed (mentor review, 2 Nov)
+- `assertSigningLock` accepts only reviewed owner lock configurations:
+  secp256k1, multisig (v1, v2), Omnilock with auth 0x00-0x06 or 0x12 and no
+  mode other than time-lock or supply, the Nostr lock in signing mode
+  (`args[0]` = 0), and JoyID. The wallet matrix's locks all still pass.
+- PW-Lock is now refused. The build deployed on mainnet and testnet is
+  lay2dev/pw-lock's anyone-can-pay variant: with no signature in the witness it
+  unlocks by payment, whatever the args, so anyone could sweep every session.
+- The Nostr lock in proof of work mode (`args[0]` not 0) is now refused: it
+  unlocks with work, not the holder's key.
+- Anyone-can-pay is refused by code hash on both networks (and the older
+  deployments pw-core lists), whatever the client's network; always-success
+  too. These refusals carry `reason: "owner-lock-unsafe"`.
+- Locks and configurations not reviewed (Omnilock auth 0xFC-0xFE, other Omnilock
+  auth flags or mode bits, the ckb-proxy-locks, unknown locks, args the lock's
+  code would not accept, multisig v2 beta) are refused with
+  `reason: "owner-lock-unreviewed"`. Omnilock auth 0x07 and unknown Omnilock mode
+  bits used to pass.
+- Subscription cells are listed with the indexer's type filter (no type, or the
+  subscription's token), so cells under any other type script no longer count
+  toward `MAX_SUBSCRIPTION_CELLS`.
+- The last charge is the newest spend with an input under the charger's lock,
+  not any spend: a `clearPlantedCells` does not delay the next charge. A spend
+  that cannot be told apart still counts as a charge.
+- Chained payments are not used; the README says why.
+
+### Added
+- `openSession` warns when a session has no rate limit (`minInterval` left out
+  or 0): every spend is within `maxPerTx`, but spends can repeat every block
+  until the session is empty. The warning (`SessionWarning`, code
+  `"no-rate-limit"`) goes to the new `opts.onWarning` before anything is
+  signed, which may throw to stop the opening, or to `console.warn` without one.
+  The demos' sessions open with no rate limit, so they now warn in the console.
+- 23 CKB-VM tests of aggregate outflow across inputs (mentor review, 2 Nov):
+  cells with the same args share one limit per transaction (CKB and token), a
+  subscription's merged cells pay one price, cells with other args are checked
+  on their own, and owner mode sweeps several cells at once. No fault found; the
+  lock is unchanged.
+- README and SECURITY-EVIDENCE: browser expiry revokes nothing on chain (funds
+  stay at risk until the owner's sweep is confirmed); a period is a block count,
+  not a fixed duration; the aggregate-outflow behaviour.
+- `allowUnreviewedOwnerLock` (`SigningLockOptions`) on `assertSigningLock`,
+  `openSession` and `openSubscription`: lets an unreviewed owner or charger lock
+  through with a `console.warn`. It never lets an "owner-lock-unsafe" lock
+  through.
+- `SessionPolicyReason` gains `"owner-lock-unsafe"` and `"owner-lock-unreviewed"`.
+- `SessionBalanceError.reason` (`SessionBalanceReason`): `"no-fee-cell"` or
+  `"no-payout-cell"` when the cells missing are the payer's or the recipient's own
+  (a charger with no fee cell, a `payTo` with no cell to top up), so a server can
+  tell them from the subscription's state without matching messages. The demo's
+  charge route now uses it.
+- `SessionPolicyError.reason` (`SessionPolicyReason`): `"payto-not-anyone-can-pay"`
+  when a charge needs to top up `payTo` and `payTo` is not anyone-can-pay. The
+  demo's charge route answers it with 503 (the deployment's setup, not the
+  subscription's state) instead of 409.
+
+### Fixed (audit round 2, 31 Oct)
+- Demo: enforced CSP now also sets `object-src 'none'`, `base-uri 'none'` and
+  `form-action 'self'`; the full policy (scripts, styles, images, testnet RPC and
+  JoyID aggregator only) is sent as `Content-Security-Policy-Report-Only`.
+- CI: GitHub actions pinned to commit SHAs, checkouts with
+  `persist-credentials: false`.
+- `openSession` and `openSubscription` refuse `TESTNET_LEGACY_DEPLOYMENTS`
+  (`assertCurrentDeployment`, new). `openSession` used to accept them: a token
+  session under the 13 Oct lock was stuck for good (that code refuses 128/160-byte
+  args before owner mode), and new sessions under the 8 Oct one lacked errors
+  16-18. Spending, closing, recovering, charging and cancelling still accept old
+  deployments, so funds under them can come back.
+- Before building an opening, the deployment's cell dep is read from the
+  client's network (`getCellLive`; a dep group is resolved) and must hold code
+  hashing to `codeHash` (data hash, or type hash for `hashType: "type"`).
+  `TESTNET_DEPLOYMENT` on a mainnet client, a typo in `codeHash` or a wrong out
+  point used to put funds under a lock with no code. One lookup per client and
+  deployment. `hashType: "data"` is refused too: the lock faults under CKB-VM
+  version 0. There is still no mainnet deployment; README and API.md say how to
+  pass your own.
+- `spendInSession` and `chargeSubscription`: a key or charger cell above its
+  floor but short of the fee threw CCC's plain "Insufficient CKB"; it is now
+  `SessionBalanceError` with reason `"no-fee-cell"`. The charger's fee cells must
+  hold at least the floor plus 0.01 CKB. Found by the round-2 property suite,
+  added in `test/property-library.test.ts` and `test/property-fuzz.test.ts`,
+  which now fails on any plain error.
+- `addTopUp` (top-ups in `spendInSession`, `chargeSubscription`,
+  `openSubscription`) skips a payee token cell the payment would take past
+  2^128 - 1 units, and throws `SessionBalanceError` `"no-payout-cell"` if every
+  cell would, instead of a plain overflow error.
+- `closeSession` refuses a signer whose lock is not `binding.ownerLock` with a
+  `SessionPolicyError`, before asking it to sign. After a wallet switch, the
+  new wallet was shown a sweep of the old wallet's session to itself (the lock
+  refused it on-chain, so nothing was lost).
+- `closeSession` can finish once the session is empty on-chain: with the
+  funding committed and nothing indexed, it asks the node whether the funding's
+  outputs under the session and the key are still live, and reports
+  `nothingFound` when all are spent. Before, a close whose key return was taken
+  but whose reply was lost (or a close from a second tab) left a key that could
+  never be forgotten. The key return now goes through `signAndSend`, so a lost
+  reply the node did take is reported as `keyTx`.
+  It reports `nothingFound` only once the node's indexer has reached the tip
+  and a second search still finds nothing, so a later spend's key cell that is
+  not indexed yet never lets the key be forgotten.
+- CCC's client cache lists a client's own outputs as live until cleared, so a
+  tab (or a warm server instance) built every later spend on cells another tab
+  had spent, and the node rejected each one. `spendInSession`, `closeSession`,
+  `chargeSubscription` and `cancelSubscription` now leave out cached-only cells
+  the node no longer has, and on a rejection for a spent or unknown input clear
+  the cache and build the transaction once more.
+- `verifyAccess`, `verifySubscription` and `subscriptionStatus` read payments
+  with `getTransactionNoCache`. `getTransaction` answers from the cache when
+  the node no longer knows a transaction, so a payment that was reorged out kept
+  granting access on a long-lived server client.
+- Demo: one "unknown" answer just after a lost send no longer makes a page
+  forget the session key (about 62 CKB stranded once the funding lands) or a
+  payment record. A key or record is forgotten only when the node rejected the
+  transaction, or has not known it for 10 minutes (the rule the payment polls
+  already used); meanwhile the page keeps polling it.
+- Demo: every page's wallet lookup drops a late answer from the previous
+  wallet, and the subscribe page drops a status refresh started for the
+  previous wallet, asset or opening, and clears its status and notes on
+  disconnect.
+- Demo: the CKB Place board asks again about a placement `get_transaction`
+  missed once, instead of leaving it off the board until a reload.
+- Demo: the charge route builds a new CCC client per request.
+
+### Fixed (security audit, 30 Oct)
+- `recoverSessions`: when the one sweep is refused, sessions are now swept one
+  session lock at a time (full lock hash), not one session key hash at a time. A
+  planted cell under other args carrying the victim's public key hash (a foreign
+  type script the sweep cannot consume) joined the victim's group and blocked its
+  recovery on every retry. `findOwnedSessionCells` keeps a typed cell only if its
+  type is a plain xUDT on the network (`assertPlainXudt`'s rules) holding exactly
+  the 16-byte amount a session makes.
+- `spendInSession` pays the fee from the largest key cell (ties: lowest out
+  point), not the first one listed: a 61 CKB cell anyone sent to the key address,
+  or the old key cell beside a top-up, blocked every spend. Still one key cell in
+  and one smaller one out, as the lock requires.
+- `verifyAccess` and `checkPlacement` count only memos in witnesses a signature
+  covers: the first witness of each secp256k1 lock group, and any past the
+  inputs. The session cell's and an anyone-can-pay cell's witnesses are signed by
+  nobody, so whoever relayed a payment could add a memo there and void it for
+  good (or, on a CKB Place board, choose the pixels of a payment without one).
+  Several signed memos still fail. `placementMemo` takes the resolved inputs as
+  an optional third argument for the exact check; without them it is a prefilter.
+- Docs: with a recipient set, up to `max_per_tx` per transaction can still leave
+  as the miner fee (the recipient rule covers outputs only). The README and
+  `openSession` now say so and recommend a rate limit (`minInterval`) whenever a
+  recipient is set. The lock is unchanged.
+- `subscriptionStatus`, `chargeSubscription` and `findSubscriptionCells` read at
+  most `MAX_SUBSCRIPTION_CELLS` (16, exported) cells under a subscription's lock,
+  and at most 64 recent transactions of its history. Beyond that they throw
+  `SessionPolicyError` with the new reason `"too-many-cells"` instead of reading
+  part of the cells, which could deny a paid-up subscriber or let a cell left out
+  of a charge pay a second price in the period. Planted cells (anyone can create
+  them) made each status request look up every creating transaction and all its
+  inputs again: 100 cells cost 3,307 RPC calls. `cancelSubscription` still reads
+  and sweeps every cell, so the subscriber can clear planted ones.
+- Subscription payments are checked once per transaction within a call, and a
+  transaction whose outputs to `payTo` already fall short is refused before its
+  inputs are looked up.
+- `chargeSubscription` picks its fee cell from the first 64 cells under the
+  charger's lock instead of reading all of them.
+- Demo: `/api/subscription` answers `"too-many-cells"` with 409 (the page shows
+  it), not 503 with retry.
+- Demo: the charger address is the creator's key, so `CHARGER_KEY` on the server
+  could spend the creator's income and payout cells. New `npm run setup:charger`
+  creates a separate key (`.env.charger`, written once, mode 0600) and prints its
+  address and next steps; the docs now require a charger key of its own holding
+  only fee cells. `CHARGER` is replaced once that key is funded and set on Vercel.
+
+### Fixed (30 Oct)
+- `chargeSubscription` and `nextChargeIn` date the last charge from the
+  subscription lock's indexer history, not from its change cell: a charge of the
+  whole balance (the last 153 CKB with a price of 153 CKB or more) leaves no
+  change, so a younger top-up could pay a second price under a period later.
+- `subscriptionStatus` counts that last whole-balance charge as a paid period;
+  it used to end access as soon as the last period was paid. A cancel still ends
+  access at once.
+
+### Fixed (code review, 28 Oct)
+- Token overflow guard: a planted cell of 2^128-1 free tokens could push the
+  subscriber's own cell out of a cancel (the guard kept cells in indexer order), and
+  blocked `closeSession` and `recoverSessions` of token sessions (no guard at all).
+  One guard now serves sessions, recovery and subscriptions; it keeps cells created
+  by the owner or the key first.
+- `recoverSessions`, `closeSession`, `cancelSubscription`: an owner sweep the node
+  accepted is reported as sent even when the reply times out (it skipped the
+  check `signAndSend` does). `recoverSessions` now throws when the owner holds no
+  plain cell, instead of reporting every session as failed.
+- `chargeSubscription` waits a full period after the last charge, not only after
+  the oldest cell: a top-up cell older than the last charge's change could pay a
+  second price in the same period. `nextChargeIn` counts the same way.
+- Session stores: a save of the same key without the on-chain binding (from a
+  stale tab) is refused with `SessionStoreConflict` instead of dropping the binding.
+- Demo: the charge route answers 503 with `retry` when the creator's own cells are
+  missing (no fee cell for the charger, no payout cell to top up), not 409.
+- `chargeSubscription` pays its fee from a random one of the charger's cells, and a
+  CKB `openSubscription` tops up a random payout cell, so concurrent charges and
+  openings rarely compete for one cell.
+
+### Changed
+- `verifyAccess` resolves a payment's inputs in parallel once the memo check
+  passes; subscription charges and status fetch each creating transaction once.
+
 ## 1.0.0 (2026-10-27)
 
 First stable release. Everything below is on testnet, with a smoke script and explorer

package/README.md

@@ -38,6 +38,42 @@ Its first example application is pay-per-read: a reader unlocks articles for
 1 CKB each with no wallet prompt, and the session can only ever pay the creator.
 The problem is not specific to that application.
 
+## Install
+
+```bash
+npm install ckb-session-kit
+```
+
+[ckb-session-kit on npm](https://www.npmjs.com/package/ckb-session-kit) (v2.0.0, ESM, Node 20 or later
+and browsers). The API is in [docs/API.md](docs/API.md); the walkthrough in
+[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md).
+
+New in 2.0.0 (details and upgrade notes in [CHANGELOG.md](CHANGELOG.md)):
+
+- `openSession(owner, session, deployment, { ..., onWarning })`: called with a
+  `SessionWarning` (`"no-rate-limit"`) before anything is signed; throw from it
+  to stop the opening. Without it the warning goes to `console.warn`.
+- `SigningLockOptions` (`{ allowUnreviewedOwnerLock?: boolean }`), taken by
+  `assertSigningLock`, `openSession` and `openSubscription`: owner locks are
+  checked against a list of reviewed configurations (see
+  [Which wallets can own a session](#which-wallets-can-own-a-session)). Refusals
+  carry `reason: "owner-lock-unsafe"` (never allowed) or
+  `"owner-lock-unreviewed"` (allowed, with a warning, by this option).
+- `RetryOptions` (`{ attempts?, delayMs? }`, defaults in `DEFAULT_RETRY`: 3
+  attempts from 1000 ms, doubling, with jitter), passed as `retry` to
+  `spendInSession` and `chargeSubscription`: a send the node refuses for a spent
+  input is built again with another payout cell (`poolConflict` tells an RBF
+  refusal apart). The retry loop itself is internal (not exported).
+- `pickPayoutCell(client, lock, cells, avoid?)`: the payout cell a top-up uses,
+  confirmed and free in the node's pool (`MAX_POOL_CHECKS`, `MAX_PAYOUT_CELLS`).
+  When none is free, `SessionBalanceError` with reason `"payout-busy"`.
+- `createPayoutCells(funder, payTo, { count, capacity?, token? })`: more
+  anyone-can-pay cells for a creator, so concurrent payments do not compete.
+- `clearPlantedCells(subscriber, deployment, subscription)`: sweeps cells a third
+  party created under a subscription's lock, keeping the subscription's own.
+- `assertCurrentDeployment(client, deployment)`, `MAX_SUBSCRIPTION_CELLS`, and the
+  `SessionPolicyReason` / `SessionBalanceReason` types for the errors' `reason`.
+
 ## Try it
 
 ```bash
@@ -131,7 +167,9 @@ this work on CKB:
   The anyone-can-pay lock accepts the top-up without the creator's signature.
 - **A stolen key can only pay the creator.** The session's recipient is the
   creator's anyone-can-pay address, so the session lock refuses any other output,
-  and `max_per_tx` caps each unlock.
+  and `max_per_tx` caps each unlock. The fee is not an output: up to `max_per_tx`
+  per transaction can still go to the miner, so give a session with a recipient a
+  rate limit (`minInterval`) too.
 
 ```ts
 const session = createSession({ expiresAt, scope: { maxPerTx: 5n * CKB, recipients: [creatorAcp] } });
@@ -177,8 +215,22 @@ then unlock articles for 1 CKB each with no popup.
 
 A session cell with a recipient occupies 153 CKB, so a 200 CKB session has 47 CKB
 to spend; the rest comes back on close. Each payment consumes one of the creator's
-cells, so readers paying at the same moment compete for them; the library picks
-one at random, and `npm run setup:creator` gives the demo's creator three.
+anyone-can-pay cells, so readers paying at the same moment compete for them. A
+top-up picks a confirmed cell that no transaction in the node's pool spends
+(`pickPayoutCell`; at most 4 cells checked, 64 read). If the node still refuses
+the payment for a spent cell, it is built again with another cell after a short
+wait, up to 3 attempts by default (`retry: { attempts, delayMs }`). A send whose
+outcome is unknown is never retried. When every cell is busy, nothing is sent
+and the error says `"payout-busy"`. Give a creator more cells with
+`createPayoutCells(funder, payTo, { count })`; `npm run setup:creator` gives the
+demo's creator eight.
+`npm run smoke:contention` checks it on testnet: four payers pay one creator at the same moment, every payment must commit, and a hand-built double top-up shows the node's own refusal.
+
+Chained payments (topping up a cell another payment created while that payment
+is still in the pool) are not used: if the first payment is dropped or slow to
+propagate, every payment built on it is stuck or dropped too, and a reader's
+session would wait on someone else's transaction. More cells and a pool-aware
+pick avoid that.
 
 ## Example: CKB Place, a pixel board on testnet
 
@@ -283,6 +335,13 @@ subscriber's money held; the creator's side did not, and the library now covers
 - access follows payments, not the live cell, so re-creating the cell to reset its age gains nothing;
 - the opening commits to an account id (hashed) under the subscriber's signature, so nobody can present someone else's subscription.
 
+Several mature cells of one subscription can be merged in one charge, and
+together they still pay at most one price. Each subscription is checked on its
+own: two subscribers' cells charged in one transaction are refused (error 13),
+since each sees the other's change as a third party, so a creator sends one
+charge per subscriber. A subscriber's cancel sweeps every cell of the
+subscription in one transaction.
+
 A charge costs the session lock 20,999 cycles.
 
 `npm run smoke:subscription` runs it on testnet. Run on 26 Oct 2026:
@@ -309,6 +368,28 @@ ran it on 27 Oct 2026 with the demo token:
 **Try it in the browser:** [ckb-session-kit.vercel.app/subscribe](https://ckb-session-kit.vercel.app/subscribe):
 2 CKB per 60 blocks; members' notes the server releases only while you are paid up.
 
+**Deploying it.** The server that charges holds the charger key (`CHARGER_KEY` in
+the deployment's environment, on Vercel for the demo). Make it a **key of its
+own, never the creator's key** or the key behind the payout address: the lock
+limits what the charger can take from subscriptions, but nothing limits what a
+key can do with its own cells, so a leak of the server's environment would also
+hand over all the creator's income. Give it only a few fee cells. `npm run
+setup:charger` creates one in `.env.charger` (gitignored) and prints its address
+and the next steps; nothing is sent. A status or a charge reads at most
+`MAX_SUBSCRIPTION_CELLS` (16) cells under one subscription's lock and refuses
+beyond that (`SessionPolicyError`, reason `"too-many-cells"`), so planted cells
+cannot make one request cost thousands of RPC calls. Only cells of the
+subscription's kind count (plain CKB, or exactly its token): the indexer leaves
+other cells out, including look-alikes of the token with longer args. The
+subscriber clears planted ones without cancelling:
+`clearPlantedCells(wallet, deployment, subscription)` sweeps every cell not made
+by the opening, a charge or the subscriber (and any look-alike of the token)
+back to the subscriber, at most 30 per transaction, one signature each, and
+leaves the subscription's own cells as they are. Only the subscriber's and the
+charger's spends count toward the 64 recent transactions a status reads;
+creations by anyone else are paged past, up to 1024 per period.
+`npm run smoke:clear-planted` checks it on testnet: 16 planted cells block the status and charges, `clearPlantedCells` clears them, and the next charge stays on time.
+
 ## Which wallets can own a session
 
 The owner signs to open, close and recover, so the owner's wallet must work. `npm
@@ -331,6 +412,30 @@ Ethereum wallets. Fixed, with a test built from the lock CCC derives for an
 Ethereum account. **JoyID** signs with a passkey and cannot be scripted; it was
 tested by hand in the demo (10 Oct).
 
+`openSession` and `openSubscription` check the owner's lock first
+(`assertSigningLock`). The session lock gives owner mode to any transaction that
+spends a cell under the owner's lock, so a lock that opens without the owner's
+signature would let anyone sweep every session. Since 2 Nov the check is a list
+of reviewed configurations:
+
+| Owner lock | Result |
+|---|---|
+| secp256k1 (CKB default), secp256k1 multisig, with or without a since | accepted |
+| Omnilock, auth 0x00-0x06 or 0x12, no mode or only time-lock or supply | accepted |
+| Nostr lock, signing mode (`args[0]` is 0) | accepted |
+| JoyID | accepted (its code is closed: reviewed from its documentation) |
+| Anyone-can-pay, PW-Lock, always-success (by type id, or their deployed binaries by data hash) | refused: they open with no signature |
+| Omnilock in anyone-can-pay or administrator mode | refused |
+| Nostr lock in proof of work mode (`args[0]` not 0) | refused: anyone who does the work can unlock it |
+| Omnilock auth 0xFC-0xFE, the proxy locks, any other lock | refused unless you pass `allowUnreviewedOwnerLock: true` (`allowUnreviewedChargerLock` for a subscription's charger) |
+
+PW-Lock is refused because the build deployed on CKB is its anyone-can-pay
+variant: a transaction with no signature in the witness takes the payment path,
+whatever the args. MetaMask and other Ethereum wallets get an Omnilock (0x12)
+from CCC, which is accepted. `allowUnreviewedOwnerLock` lets an unreviewed lock
+through with a warning; use it only once you have checked that the lock cannot
+open without its holder's signature. It never lets a refused lock through.
+
 ## The on-chain session lock
 
 [`contracts/session-lock`](contracts/session-lock/src/main.rs) is a CKB lock script in
@@ -341,15 +446,28 @@ Rust. A cell under it can be spent two ways:
 - **Session mode** — the transaction also spends the session key's *key cell*. The
   network then enforces, on-chain:
   - **outflow limit** — at most `max_per_tx` shannons leave per transaction, fees
-    included, so the fee cannot be used to drain the cell;
+    included, so the fee cannot be used to drain the cell. The limit is for all
+    the session's cells together: cells under the same lock (same args) are one
+    script group, so taking `max_per_tx` from each of three cells is refused.
+    Cells of another session or subscription (other args) are checked on their
+    own, against their own limit and recipient; one session's unused limit never
+    covers another's;
   - **recipient allowlist** (optional) — payments may only go to one lock (plus
     change, the key cell, and the owner). The key cell may come back smaller
     (it pays the fee) but never larger, so the key cannot park session funds in
-    its own cell and pay anyone from there;
+    its own cell and pay anyone from there. The fee is not an output, so the
+    allowlist does not see it: a leaked key can still give up to `max_per_tx`
+    per transaction to the miner as fee, paying the recipient nothing. Set a
+    rate limit (`min_interval`) whenever you set a recipient;
   - **rate limit** (optional) — each session cell must have aged `min_interval`
     blocks before it can be spent again (relative `since`). The limit is **per
     cell**: with *n* session cells, the key can spend from each of them in the same
-    block. `openSession` creates one cell;
+    block. `openSession` creates one cell. With `min_interval` 0 there is no
+    rate limit: every spend is within `max_per_tx`, but spends can repeat in
+    every block until the cell is empty, and `openSession` warns
+    (`SessionWarning`, `"no-rate-limit"`; also for `min_interval` 1, almost the same). The interval is a number of blocks,
+    not a fixed time: block time varies (see the
+    [average block time](https://explorer.nervos.org/charts/average-block-time));
   - **no splitting** — a session spend may send at most one cell back to the
     session lock, so the key can merge session cells but never multiply them,
     which makes the per-cell rate limit a per-session one for sessions opened
@@ -364,13 +482,16 @@ Rust. A cell under it can be spent two ways:
 Signatures are delegated to the standard secp256k1 locks of the owner and the
 session key (the pattern sUDT's owner mode uses), so the script carries no
 cryptography: **7.6 KB, no allocator, no C, 15,651 cycles per run** — about 0.9% of
-a session spend (29,031 on a token spend, 1.7%). 74 tests run it in the real CKB-VM, most asserting a specific
+a session spend (29,031 on a token spend, 1.7%). 144 tests run it in the real CKB-VM, most asserting a specific
 rejection code, and CI builds the contract and requires them.
 
 **What it cannot do:** enforce an expiry time. A CKB script can prove time has
 passed (`since` is a lower bound) but never that it has not. Expiry is enforced
 in the browser; the owner can revoke on-chain at any moment, and the session
-cell's balance caps the total at risk.
+cell's balance caps the total at risk. **Expiry in the browser revokes nothing
+on chain.** After `expiresAt` the key still satisfies the lock, and the funds
+stay at risk until the owner's sweep (`closeSession` or `recoverSessions`)
+is confirmed.
 
 **Enforced where:**
 
@@ -385,9 +506,15 @@ cell's balance caps the total at risk.
 ### If a session key leaks
 
 The key cannot be revoked by expiry: after `expiresAt` it still satisfies the lock
-until the owner acts. Until then it can move at most `max_per_tx` per transaction,
-only to the recipient if one is set, and, with a rate limit, once per
-`min_interval` blocks per session cell. The owner should sweep at once:
+until the owner's sweep is confirmed on chain. The browser forgetting the key, or
+refusing to use it, does not change that. Until then it can move at most `max_per_tx` per transaction,
+only to the recipient if one is set (or to the miner as fee: the recipient rule
+covers outputs, and the fee is not one), and, with a rate limit, once per
+`min_interval` blocks per session cell. Without a rate limit, a leaked key can
+repeat spends of `max_per_tx` in every block until the session is empty, each
+one within the limit; a recipient does not slow it down, since it can burn
+`max_per_tx` in fees every block. Set
+`min_interval` whenever you set a recipient. The owner should sweep at once:
 
 - with the key still at hand: `closeSession(wallet, session, deployment, binding)`;
 - without it (device lost or wiped): `recoverSessions(wallet, deployment)` finds
@@ -399,9 +526,11 @@ paying a higher fee, so sweep early, and resweep what is left. Keep budgets
 small: the budget is the most a session can ever lose.
 
 **Owner and session locks must need a signature.** The lock trusts that an input
-under the owner's lock means the owner signed. Plain secp256k1, JoyID and
-Omnilock are fine; an anyone-can-pay owner lock is not, since anyone may spend
-into it and would get owner mode.
+under the owner's lock means the owner signed. Plain secp256k1, JoyID, signing
+Omnilock and the Nostr lock in signing mode are fine; anyone-can-pay, PW-Lock and
+the Nostr lock in proof of work mode are not, since anyone could spend the
+owner's cell and get owner mode. See [which wallets can own a
+session](#which-wallets-can-own-a-session).
 
 A session-lock cell occupies 121 CKB (153 CKB with a recipient), so its balance
 and its change must stay above that.
@@ -413,6 +542,21 @@ see [`deployment/testnet.json`](deployment/testnet.json). The code is immutable.
 Earlier deployments (8 Oct, before errors 16–18; 13 Oct, before token sessions)
 are kept in `TESTNET_LEGACY_DEPLOYMENTS`, so `recoverSessions` still sweeps
 sessions opened under them.
+`openSession` and `openSubscription` refuse them: new cells go under the current
+lock only.
+
+Reference the lock with `hash_type` `data1` or `data2` (or `type`, for a
+type-id deployment). Under `data` (CKB-VM version 0) the binary faults on load,
+owner mode included, so a cell under it could never be spent; the library
+refuses such a deployment when opening.
+
+Before it builds an opening, the library reads the deployment's cell dep from
+the client's network (`getCellLive`, a dep group resolved) and refuses unless it
+holds code hashing to `codeHash` (`assertCurrentDeployment`), once per client
+and deployment. `TESTNET_DEPLOYMENT` on a mainnet client is therefore refused.
+There is no mainnet deployment and no `MAINNET_DEPLOYMENT` constant: to use the
+lock on mainnet, deploy the binary yourself (byte-identical, see below) and pass
+your own `SessionLockDeployment` (`codeHash`, `hashType: "data2"`, `cellDep`).
 
 Verify the deployed lock yourself. The deployed binary was built with rustc
 1.99.0 on the x86_64-pc-windows-gnu host (pinned in
@@ -431,7 +575,13 @@ The last command compares the build's data hash with `codeHash` in
 the same three steps. Another host or rustc builds a working lock with other
 bytes, so its hash will not match.
 
-`npm run smoke:lock` runs every rule against public testnet. Run on 14 Oct 2026, on the current lock:
+[`docs/SECURITY-EVIDENCE.md`](docs/SECURITY-EVIDENCE.md) collects the evidence
+for each rule and error code in one report: the check in the script, the accepted
+transactions, the node's rejection text, the CKB-VM tests, and which rules have
+only been shown in CKB-VM tests. `npm run evidence` re-checks its logs against
+testnet, read-only.
+
+`npm run smoke:lock` runs the rules in the table below against public testnet. Run on 14 Oct 2026, on the current lock:
 
 | Step | Network said |
 |---|---|
@@ -465,13 +615,20 @@ that an over-limit spend is refused. Run on 8 Oct 2026:
 ## Limits
 
 What this does not do, in one place. Each is stated where it applies above.
+What has and has not been shown on testnet is in
+[`docs/SECURITY-EVIDENCE.md`](docs/SECURITY-EVIDENCE.md#5-not-covered-and-limits).
 
 - **Testnet only, not audited.** The lock has had community and adversarial
   reviews, each finding fixed with a regression test, but no external audit.
   Do not put mainnet funds behind it.
 - **Expiry is not on-chain.** A CKB script cannot prove that time has *not*
-  passed, so `expiresAt` is checked in the browser. A leaked key stays valid
-  until the owner sweeps; the session's balance is the most it can lose.
+  passed, so `expiresAt` is checked in the browser. Browser expiry does not
+  revoke the key's on-chain authority: a leaked key stays valid, and the funds
+  stay at risk, until the owner's sweep transaction is confirmed. The session's
+  balance is the most it can lose.
+- **No rate limit means repeated spends.** With `min_interval` 0, each spend
+  is within `max_per_tx`, but spends can repeat every block until the balance
+  is gone. `openSession` warns; set `minInterval`.
 - **The rate limit is per cell.** `openSession` makes one cell and the lock
   forbids splitting, but anyone adding more cells under the same session lock
   gives the key more cells to spend from (with their own money, never the owner's).
@@ -486,11 +643,14 @@ What this does not do, in one place. Each is stated where it applies above.
 - **An access proof does not expire.** It is a bearer token for one article:
   whoever holds the signed proof can fetch that article again. It cannot be
   used for another article or by another payment.
-- **Owner locks must need a signature.** An anyone-can-pay owner lock would give
-  anyone owner mode; `openSession` refuses one.
+- **Owner locks must need a signature.** An owner lock that opens without one
+  (anyone-can-pay, PW-Lock, Nostr in proof of work mode) would give anyone owner
+  mode; `openSession` refuses it, and refuses locks it has not reviewed unless
+  `allowUnreviewedOwnerLock` is set.
 - **Subscription periods are in blocks, and charges need the creator online.**
-  The lock's rate limit is a block count, so a period is an estimate of time
-  (`blocksForSeconds`). Nothing charges by itself: the creator's server must
+  The lock's rate limit is a block count, not a fixed duration: block time
+  varies (see the [average block time](https://explorer.nervos.org/charts/average-block-time)), so a period is an
+  estimate of time (`blocksForSeconds`). Nothing charges by itself: the creator's server must
   send each charge, one transaction per subscriber. Cancelling ends access at
   once, and the current period's price is not refunded.
 - **Sessions are not cheap to open.** A session cell occupies 121 CKB (153 with a

package/dist/deployment.d.ts

@@ -0,0 +1,21 @@
+import { ccc } from "@ckb-ccc/core";
+import { type SessionLockDeployment } from "./lock.js";
+/**
+ * Throws a `SessionPolicyError` unless new cells may go under `deployment` on
+ * `client`'s network:
+ *
+ * - it is not one of `TESTNET_LEGACY_DEPLOYMENTS` (older code with fewer rules;
+ *   the 13 Oct one cannot even spend a token session's 128/160-byte args);
+ * - its `hashType` is not `data`: under CKB-VM version 0 the lock faults on
+ *   load, owner mode included, so such cells could never be spent;
+ * - its cell dep is live on this network and holds the code: the code cell's
+ *   data hashes to `codeHash` (`data1`, `data2`) or its type script hashes to
+ *   it (`type`). A `depGroup` cell dep is resolved and any member may match.
+ *   This catches a testnet deployment on a mainnet client, a typo in
+ *   `codeHash` and a wrong out point, any of which would leave funds under a
+ *   lock no code can run.
+ *
+ * A passing check is remembered for that client and deployment; a failing one
+ * is not, so the next call looks again.
+ */
+export declare function assertCurrentDeployment(client: ccc.Client, deployment: SessionLockDeployment): Promise<void>;