ckb-session-kit 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,8 @@
+export { checkRequest, createSession, isActive, SessionPolicyError } from "./session.js";
+export { deserializeSession, indexedDbStore, memoryStore, serializeSession, SessionStoreConflict } from "./store.js";
+export { ScopeError, sendInScope, sessionAddress, sessionSigner } from "./transfer.js";
+export { relativeBlocksSince, SESSION_LOCK_ERRORS, sessionLockArgs, sessionLockCellDep, sessionLockErrorFrom, sessionLockScript, TESTNET_DEPLOYMENT, TESTNET_LEGACY_DEPLOYMENTS, } from "./lock.js";
+export { assertPlainXudt, assertSigningLock, closeSession, findOwnedSessionCells, findSessionCells, keyLockOf, matureCells, onchainRecipient, openSession, recoverSessions, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
+export { blocksForSeconds, cancelSubscription, chargeSubscription, findSubscriptionCells, openSubscription, subscriptionLock, subscriptionMemo, subscriptionStatus, verifySubscription, } from "./subscription.js";
+export { paymentMemo, signAccess, verifyAccess } from "./paywall.js";
+export { applyPlacements, checkPlacement, decodePlacement, encodePlacement, PLACE_BOARD, placementMemo, placementPrice, PlaceMemoError, } from "./place.js";

package/dist/lock.d.ts

@@ -0,0 +1,70 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * Client side of the on-chain session lock (contracts/session-lock).
+ *
+ * Args layout, 80 or 112 bytes:
+ * owner_lock_hash 32 | session_lock_hash 32 | max_per_tx u64 LE | min_interval u64 LE | [recipient_lock_hash 32]
+ *
+ * A token session (128 or 160 bytes) puts the token before the recipient:
+ * ... | min_interval | token_type_hash 32 | max_per_tx_token u128 LE | [recipient_lock_hash 32]
+ */
+export interface SessionLockParams {
+    /** Lock hash whose presence in a transaction's inputs grants owner mode. */
+    ownerLockHash: ccc.HexLike;
+    /** Lock hash of the session key's own lock (its key cell); grants session mode. */
+    sessionLockHash: ccc.HexLike;
+    /** Most shannons one session-mode transaction may move out, fees included. */
+    maxPerTx: bigint;
+    /** Blocks each session-locked input must have aged (relative since); 0 = no rate limit. */
+    minInterval?: bigint;
+    /** If set, the only lock session-mode spends may pay (besides change, key cell, owner). */
+    recipientLockHash?: ccc.HexLike;
+    /** A token session: the one xUDT type its cells may hold, and the most units one spend may move. */
+    token?: {
+        typeHash: ccc.HexLike;
+        maxPerTx: bigint;
+    };
+}
+/** Where the session lock code lives on a network. */
+export interface SessionLockDeployment {
+    codeHash: ccc.HexLike;
+    hashType: ccc.HashTypeLike;
+    cellDep: {
+        outPoint: {
+            txHash: ccc.HexLike;
+            index: ccc.NumLike;
+        };
+        depType: ccc.DepTypeLike;
+    };
+}
+/**
+ * The session lock deployed on CKB public testnet. Kept identical to
+ * deployment/testnet.json by a test.
+ */
+export declare const TESTNET_DEPLOYMENT: SessionLockDeployment;
+/**
+ * Earlier testnet deployments, newest first. Their code is immutable, so sessions
+ * opened under them keep their old rules; pass these to `recoverSessions` too so
+ * those sessions can still be swept. 13 Oct 2026: before token sessions (errors
+ * 19, 20) and untyped-only payments. 8 Oct 2026: before errors 16, 17 and 18.
+ */
+export declare const TESTNET_LEGACY_DEPLOYMENTS: SessionLockDeployment[];
+/** Error codes returned by the session lock, for reading node rejections. */
+export declare const SESSION_LOCK_ERRORS: Record<number, string>;
+export declare function sessionLockArgs(p: SessionLockParams): ccc.Hex;
+export declare function sessionLockScript(d: SessionLockDeployment, p: SessionLockParams): ccc.Script;
+export declare function sessionLockCellDep(d: SessionLockDeployment): ccc.CellDep;
+/** A relative `since` of `blocks` block numbers (RFC 0017), as the rate limit requires. */
+export declare function relativeBlocksSince(blocks: bigint): bigint;
+/**
+ * Pulls a session-lock error code out of a node's rejection message, if there is
+ * one. The session lock only ever runs as an input's lock: a code from a type
+ * script (xUDT on a token payment, say) is not one, and gives undefined. An
+ * input lock can still be another lock in the same transaction (the recipient's
+ * anyone-can-pay cell on a top-up); pass `sessionInputs`, the indexes of the
+ * session cells, to rule that out too.
+ */
+export declare function sessionLockErrorFrom(message: string, sessionInputs?: number[]): {
+    code: number;
+    meaning: string;
+} | undefined;

package/dist/lock.js

@@ -0,0 +1,106 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * The session lock deployed on CKB public testnet. Kept identical to
+ * deployment/testnet.json by a test.
+ */
+export const TESTNET_DEPLOYMENT = {
+    codeHash: "0xab419466529ea479590d4be7b23580ce2ddc640ba902735c9ad9a22dc64c08ce",
+    hashType: "data2",
+    cellDep: {
+        outPoint: { txHash: "0xf3098bdb9a7bb1c500990be0f1159b7e66f507fef6b7a4f904046024284877f2", index: "0x0" },
+        depType: "code",
+    },
+};
+/**
+ * Earlier testnet deployments, newest first. Their code is immutable, so sessions
+ * opened under them keep their old rules; pass these to `recoverSessions` too so
+ * those sessions can still be swept. 13 Oct 2026: before token sessions (errors
+ * 19, 20) and untyped-only payments. 8 Oct 2026: before errors 16, 17 and 18.
+ */
+export const TESTNET_LEGACY_DEPLOYMENTS = [
+    {
+        codeHash: "0x1cb7724269e2e86359b5b47cad6b1860ccd6da254c25c651056c8431d11590cd",
+        hashType: "data2",
+        cellDep: {
+            outPoint: { txHash: "0x37cfe04f64fd4dbec3803a972a51b7080f9ca1a3042535e97b7a756d0e03b071", index: "0x0" },
+            depType: "code",
+        },
+    },
+    {
+        codeHash: "0x1ae8b8f71ed1846e2823ecccd8c3f80527be2895689f5dae54a53bd42526bc20",
+        hashType: "data2",
+        cellDep: {
+            outPoint: { txHash: "0xab2e69b8b97c15bddeb80954edd6d33befcd2fe9e4243377a46f14a3e1c343d2", index: "0x0" },
+            depType: "code",
+        },
+    },
+];
+/** Error codes returned by the session lock, for reading node rejections. */
+export const SESSION_LOCK_ERRORS = {
+    10: "bad args",
+    11: "not authorised: neither owner nor session key present",
+    12: "outflow exceeds max_per_tx",
+    13: "recipient not allowed",
+    14: "rate limited: input too young",
+    15: "overflow (capacity or token amounts)",
+    16: "too many change cells: a session spend may not split the session cell",
+    17: "the key cell may not grow in a session spend",
+    18: "session cells and their change may not carry a type script (in a token session: none but the token)",
+    19: "malformed token data: under 16 bytes, or token change not exactly 16",
+    20: "token outflow exceeds max_per_tx_token",
+};
+const U64_MAX = (1n << 64n) - 1n;
+function u64le(v) {
+    if (v < 0n || v > U64_MAX)
+        throw new RangeError(`not a u64: ${v}`);
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, v, true);
+    return b;
+}
+const U128_MAX = (1n << 128n) - 1n;
+function u128le(v) {
+    if (v < 0n || v > U128_MAX)
+        throw new RangeError(`not a u128: ${v}`);
+    return ccc.numLeToBytes(v, 16);
+}
+function hash32(h, name) {
+    const b = ccc.bytesFrom(h);
+    if (b.length !== 32)
+        throw new RangeError(`${name} must be 32 bytes`);
+    return b;
+}
+export function sessionLockArgs(p) {
+    return ccc.hexFrom(ccc.bytesConcat(hash32(p.ownerLockHash, "ownerLockHash"), hash32(p.sessionLockHash, "sessionLockHash"), u64le(p.maxPerTx), u64le(p.minInterval ?? 0n), ...(p.token === undefined ? [] : [hash32(p.token.typeHash, "token.typeHash"), u128le(p.token.maxPerTx)]), ...(p.recipientLockHash === undefined ? [] : [hash32(p.recipientLockHash, "recipientLockHash")])));
+}
+export function sessionLockScript(d, p) {
+    return ccc.Script.from({ codeHash: d.codeHash, hashType: d.hashType, args: sessionLockArgs(p) });
+}
+export function sessionLockCellDep(d) {
+    return ccc.CellDep.from(d.cellDep);
+}
+/** A relative `since` of `blocks` block numbers (RFC 0017), as the rate limit requires. */
+export function relativeBlocksSince(blocks) {
+    if (blocks < 0n || blocks >= 1n << 56n)
+        throw new RangeError(`blocks out of range: ${blocks}`);
+    return (1n << 63n) | blocks;
+}
+/**
+ * Pulls a session-lock error code out of a node's rejection message, if there is
+ * one. The session lock only ever runs as an input's lock: a code from a type
+ * script (xUDT on a token payment, say) is not one, and gives undefined. An
+ * input lock can still be another lock in the same transaction (the recipient's
+ * anyone-can-pay cell on a top-up); pass `sessionInputs`, the indexes of the
+ * session cells, to rule that out too.
+ */
+export function sessionLockErrorFrom(message, sessionInputs) {
+    const m = message.match(/error code (-?\d+)/i) ?? message.match(/ValidationFailure\D+(-?\d+)/);
+    if (!m)
+        return undefined;
+    const source = message.match(/source: (Inputs|Outputs)\[(\d+)\]\.(Lock|Type)/);
+    if (source && (source[1] !== "Inputs" || source[3] !== "Lock"))
+        return undefined;
+    if (source && sessionInputs && !sessionInputs.includes(Number(source[2])))
+        return undefined;
+    const code = Number(m[1]);
+    return { code, meaning: SESSION_LOCK_ERRORS[code] ?? "unknown" };
+}

package/dist/onchain.d.ts

@@ -0,0 +1,212 @@
+import { ccc } from "@ckb-ccc/core";
+import { type SessionLockDeployment } from "./lock.js";
+import { type Session } from "./session.js";
+/**
+ * Sessions enforced by the on-chain session lock.
+ *
+ * - `openSession`  — the owner (any CCC signer: a wallet) funds a session cell under
+ *   the session lock and a key cell under the session key's own lock. One signature.
+ * - `spendInSession` — the session key alone spends from the session cell; the key
+ *   cell pays the fee. No wallet involved; the network enforces the scope. With
+ *   `topUp`, it adds to the recipient's anyone-can-pay cell instead of creating a
+ *   new one, so a payment can be any size (a new cell needs at least 61 CKB).
+ * - `closeSession` — the key cell goes back to the owner (session key signs), then
+ *   the owner sweeps the session cells (one wallet signature).
+ * - `recoverSessions` — the device holding the session key is gone: the owner's
+ *   wallet alone finds every session it opened and sweeps them back.
+ *
+ * A token session (`openSession(..., { token })`) holds an xUDT token as well as
+ * CKB; `spendInSession(..., { to, token })` pays in it, and the lock caps the
+ * units per spend as it caps shannons. Sweeps return the tokens to the owner.
+ */
+/** What the browser must remember, besides the key, to find and spend the session. */
+export type OnChainBinding = NonNullable<Session["onchain"]>;
+export interface SessionCells {
+    lock: ccc.Script;
+    keyLock: ccc.Script;
+    sessionCells: ccc.Cell[];
+    keyCells: ccc.Cell[];
+    /** Spendable balance of the session cells, in shannons. */
+    balance: bigint;
+    /** Fee budget left in the key cells, in shannons. */
+    feeBalance: bigint;
+    /** Token units in the session cells (token sessions; 0 otherwise). */
+    tokenBalance: bigint;
+}
+export declare class SessionBalanceError extends Error {
+    constructor(message: string);
+}
+/**
+ * The smallest key cell that can still be returned to the owner: a cell under the
+ * owner's lock (63 CKB for JoyID or Omnilock, whose args are 22 bytes), and never
+ * below a key cell's own 61 CKB.
+ */
+export declare function keyCellFloor(ownerLock: ccc.ScriptLike): bigint;
+/**
+ * Signs `tx`, hands its final hash to `beforeSend`, then sends it. The hash is
+ * known before anything leaves, so a caller can record the payment or the key
+ * against it first. If the send throws but the node did take the transaction (a
+ * timeout on the reply, say), the hash is returned all the same.
+ */
+export declare function signAndSend(signer: ccc.Signer, tx: ccc.Transaction, beforeSend?: (txHash: ccc.Hex) => Promise<void>): Promise<ccc.Hex>;
+export declare function keyLockOf(session: Session, client: ccc.Client): Promise<ccc.Script>;
+/** The xUDT amount in a cell's data (RFC 0052: u128 LE in the first 16 bytes). */
+export declare function tokenAmount(data: ccc.HexLike): bigint;
+export declare const tokenData: (amount: bigint, rest?: Uint8Array) => `0x${string}`;
+/** A cell's data is exactly a 16-byte amount: what the session lock accepts as token change. */
+export declare const plainTokenCell: (cell: ccc.Cell, type: ccc.Script) => boolean;
+export declare function sessionLockOf(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<ccc.Script>;
+/** Plain cells under `lock`; with `token`, also cells holding exactly that token. */
+export declare function collect(client: ccc.Client, lock: ccc.Script, token?: ccc.Script): Promise<ccc.Cell[]>;
+export declare function findSessionCells(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<SessionCells>;
+/**
+ * The recipient the session lock will enforce, taken from the session's own scope
+ * so the browser and the chain cannot disagree. The lock holds one recipient, so a
+ * scope listing several cannot be enforced on-chain and is refused.
+ */
+export declare function onchainRecipient(session: Session): string | undefined;
+/**
+ * Throws unless `lock` is known to need a signature over the whole transaction:
+ * the session lock grants owner mode to any transaction with an input under the
+ * owner's lock, so that lock is the only thing standing between a stranger and
+ * every session. An allowlist, not a blocklist (code review, 14 Oct):
+ *
+ * - secp256k1-blake160 (single or multisig), JoyID, Nostr, PW lock;
+ * - Omnilock with a signature auth flag (0x00-0x07: CKB, Ethereum, EOS, Tron,
+ *   Bitcoin, Dogecoin, multisig; 0x12: Ethereum with the message displayed) and neither administrator (0x01) nor
+ *   anyone-can-pay (0x02) mode. Auth flags 0xFC-0xFE hand the decision to
+ *   another lock or to arbitrary code, and are refused.
+ *
+ * Anyone-can-pay (RFC 0026) unlocks with no signature at all: anyone could spend
+ * the owner's cell back to itself unchanged and sweep every session.
+ *
+ * The owner must also never sign a partial (open) transaction with this lock.
+ */
+export declare function assertSigningLock(lock: ccc.Script, client: ccc.Client): Promise<void>;
+/**
+ * Owner funds the session: one transaction, one signature from `owner`.
+ * The on-chain recipient comes from `session.policy.scope.recipients`.
+ *
+ * `beforeSend` runs once the transaction is signed and before it is sent: save the
+ * session there (`store.save({ ...session, onchain: binding })`). Saved after
+ * sending, a failed save would leave funds under a key that exists nowhere. The
+ * binding then carries `openTx`, the funding transaction's hash, which
+ * `closeSession` checks before reporting that nothing is left.
+ *
+ * The key cell (`feeBudget`) must be able to return to the owner at the end: by
+ * default it is the size of a cell under the owner's lock plus 1 CKB for fees.
+ */
+export declare function openSession(owner: ccc.Signer, session: Session, deployment: SessionLockDeployment, opts: {
+    budget: bigint;
+    feeBudget?: bigint;
+    minInterval?: bigint;
+    /** A token session: put `amount` units of the xUDT `type` in it, and let one spend move at most `maxPerTx`. */
+    token?: {
+        type: ccc.ScriptLike;
+        amount: bigint;
+        maxPerTx: bigint;
+    };
+    beforeSend?: (binding: OnChainBinding) => Promise<void>;
+}): Promise<{
+    txHash: ccc.Hex;
+    binding: OnChainBinding;
+}>;
+/**
+ * Throws unless `type` is a plain xUDT (RFC 0052) on this network: the session
+ * lock reads amounts as xUDT stores them, and an xUDT with any flag set in its
+ * args either runs extension scripts the owner did not choose on every spend, or
+ * widens who may mint (owner mode by input or output type, code review 14 Oct).
+ */
+export declare function assertPlainXudt(type: ccc.Script, client: ccc.Client): Promise<void>;
+/**
+ * The session key pays `to`: `amount` shannons, or in a token session `token`
+ * units of its xUDT. The scope is checked here first, then the network checks it
+ * again in the session lock. No wallet is involved.
+ *
+ * `topUp: true` pays into an existing cell of `to` instead of creating one. `to`
+ * must be an anyone-can-pay address with at least one live cell to add to (plain
+ * for CKB, holding the session's token for `token`); that cell is consumed and
+ * recreated holding more, which the anyone-can-pay lock allows without the
+ * recipient's signature. A token paid without `topUp` goes in a new cell, whose
+ * capacity (about 142 CKB) the session also pays and must fit in `maxPerTx`.
+ *
+ * In a token session, tokens always stay in the change: a CKB payment from a
+ * cell holding tokens returns them, never burns them.
+ *
+ * `memo` is recorded in the witness of the session key's own input, which that
+ * key's signature covers: the payment commits to it (see `verifyAccess`).
+ */
+export declare function spendInSession(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding, request: {
+    to: string;
+    amount: bigint;
+    token?: undefined;
+    topUp?: boolean;
+    memo?: ccc.HexLike;
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+} | {
+    to: string;
+    token: bigint;
+    amount?: undefined;
+    topUp?: boolean;
+    memo?: ccc.HexLike;
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+}, now?: Date): Promise<ccc.Hex>;
+/** The cells created at least `blocks` blocks before the tip: those a relative `since` of `blocks` can spend. */
+export declare function matureCells(client: ccc.Client, cells: ccc.Cell[], blocks: bigint): Promise<ccc.Cell[]>;
+/**
+ * Ends the session: the owner sweeps the session cells (one wallet signature),
+ * then the key cell returns to the owner (session key signs, no wallet).
+ *
+ * The sweep goes first because it is what matters: a key cell too small to pay
+ * for the owner's lock (some wallets' locks need more than 61 CKB) must not block
+ * it. A key-cell failure is reported in `keyError`; the key stays usable for a retry.
+ *
+ * `nothingFound` means no cell is left under the session or the key: the key can
+ * be forgotten. If the funding transaction (`binding.openTx`) is still in flight
+ * or not yet indexed, this throws instead, so the key is never forgotten before
+ * the funds it controls arrive.
+ */
+export declare function closeSession(owner: ccc.Signer, session: Session, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<{
+    keyTx?: ccc.Hex;
+    sweepTx?: ccc.Hex;
+    keyError?: string;
+    nothingFound?: true;
+}>;
+/**
+ * Every live session cell this owner opened, found without any session key.
+ *
+ * Session-lock args begin with the owner's lock hash, so an indexer prefix search
+ * on the args finds them all. Only well-formed args (80 or 112 bytes; 128 or 160
+ * for a token session) are kept: a cell with malformed args would fail the lock
+ * even in owner mode, and anyone can create one with this owner's hash as a prefix
+ * to block a sweep. Likewise a typed cell is kept only if it holds the session's
+ * own token in well-formed data; anything else could make the sweep fail.
+ *
+ * Pass several deployments (`[TESTNET_DEPLOYMENT, ...TESTNET_LEGACY_DEPLOYMENTS]`)
+ * to find sessions opened under earlier versions of the lock as well.
+ */
+export declare function findOwnedSessionCells(owner: ccc.Signer, deployments: SessionLockDeployment | SessionLockDeployment[]): Promise<ccc.Cell[]>;
+/**
+ * Device-loss recovery: sweeps every session this owner opened back to the owner,
+ * in one transaction and one wallet signature. Needs nothing from the lost device.
+ *
+ * Anyone can create a cell under a session lock carrying this owner's hash and
+ * their own key, and spend it before the sweep lands, which would make a single
+ * sweep fail. So if the one transaction is refused, each session (cells sharing a
+ * session key) is swept on its own, one signature each: a cell someone else can
+ * spend fails alone, and `failed` counts the sessions not recovered.
+ *
+ * The key cell (the fee budget) is under the session key's own lock and cannot be
+ * recovered without that key; keep it small.
+ */
+export declare function recoverSessions(owner: ccc.Signer, deployments: SessionLockDeployment | SessionLockDeployment[]): Promise<{
+    txHashes: ccc.Hex[];
+    recovered: bigint;
+    cells: number;
+    failed: number;
+}>;
+/**
+ * Spends `cells` in owner mode: everything returns to the owner. Tokens go back
+ * in one cell per token type (xUDT would let a sweep burn them otherwise).
+ */
+export declare function ownerSweep(owner: ccc.Signer, deployments: SessionLockDeployment | SessionLockDeployment[], cells: ccc.Cell[]): Promise<ccc.Hex>;