ckb-session-kit 0.0.0-stage → 1.0.0

package/dist/paywall.js

@@ -0,0 +1,116 @@
+import { ccc } from "@ckb-ccc/core";
+import { tokenAmount } from "./onchain.js";
+import { sessionSigner } from "./transfer.js";
+/**
+ * Paid access, checked against the chain with no database.
+ *
+ * The payer pays with `spendInSession(…, { memo })`. The memo goes into the
+ * witness of the session key's own input, which that key's signature covers, so
+ * the payment commits to what it pays for: it cannot be reused for something else.
+ *
+ * To claim the access, the payer signs a request with the same session key
+ * (`signAccess`). A server checks both with `verifyAccess`: the payment is
+ * committed, the recipient gained enough, the memo matches, and the request is
+ * signed by the key that paid. Anyone can see the payment on-chain; only the
+ * payer can use it.
+ *
+ * One payment, one claim: a payment transaction may carry exactly one memo.
+ * Otherwise one transaction could pay the creator once and carry memos from
+ * several keys, each claiming the full amount for a different article or reader.
+ */
+/** A session payment has a handful of inputs; more is not one, and costs RPC calls to check. */
+const MAX_PAYMENT_INPUTS = 16;
+/** The memo for a payment: a short UTF-8 label, e.g. `read:article-1`. */
+export function paymentMemo(label) {
+    return ccc.hexFrom(ccc.bytesFrom(label, "utf8"));
+}
+function accessMessage(txHash, memo) {
+    return `ckb-session-kit access ${ccc.hexFrom(txHash)} ${ccc.hexFrom(memo)}`;
+}
+/** The payer's side: prove that the key which paid `txHash` is asking. */
+export async function signAccess(session, txHash, memo) {
+    const signer = sessionSigner(session, new ccc.ClientPublicTestnet());
+    const { signature } = await signer.signMessage(accessMessage(txHash, memo));
+    return { txHash: ccc.hexFrom(txHash), memo: ccc.hexFrom(memo), publicKey: signer.publicKey, signature: ccc.hexFrom(signature) };
+}
+/**
+ * The server's side. `to` is the recipient that must have been paid, as a lock
+ * script; `minAmount` in shannons. With `token` (an xUDT type script), the
+ * payment is counted in that token's units instead, and `minAmount` is in units.
+ */
+export async function verifyAccess(client, proof, expect) {
+    if (ccc.hexFrom(proof.memo) !== ccc.hexFrom(expect.memo))
+        return { ok: false, reason: "memo does not match" };
+    // Always the CKB secp256k1 scheme: a sign type chosen by the caller is not trusted.
+    let signed = false;
+    try {
+        signed = ccc.verifyMessageCkbSecp256k1(accessMessage(proof.txHash, proof.memo), proof.signature, proof.publicKey);
+    }
+    catch {
+        signed = false;
+    }
+    if (!signed)
+        return { ok: false, reason: "request not signed by the given key" };
+    const res = await client.getTransaction(proof.txHash);
+    if (!res)
+        return { ok: false, reason: "payment not found" };
+    if (res.status !== "committed")
+        return { ok: false, reason: `payment is ${res.status}, not committed` };
+    const tx = res.transaction;
+    // Cheap checks first, before resolving any input over RPC.
+    if (tx.inputs.length > MAX_PAYMENT_INPUTS)
+        return { ok: false, reason: "not a session payment: too many inputs" };
+    let memos = 0;
+    let memoAt = -1;
+    for (let i = 0; i < tx.witnesses.length; i++) {
+        let inputType;
+        try {
+            inputType = tx.getWitnessArgsAt(i)?.inputType;
+        }
+        catch {
+            continue; // not WitnessArgs: carries no memo
+        }
+        if (inputType !== undefined) {
+            memos++;
+            memoAt = i;
+        }
+    }
+    if (memos !== 1)
+        return { ok: false, reason: "a payment must carry exactly one memo" };
+    // The payer's lock: the standard secp256k1 lock of the key that signed the request.
+    const payerLock = (await new ccc.SignerCkbPublicKey(client, proof.publicKey).getAddressObjSecp256k1()).script;
+    // One lookup before all of them: anyone can sign a request for someone else's
+    // public payment, and must not get to make the server resolve every input.
+    const memoCell = memoAt < tx.inputs.length ? await client.getCell(tx.inputs[memoAt].previousOutput) : undefined;
+    if (!memoCell?.cellOutput.lock.eq(payerLock))
+        return { ok: false, reason: "the signing key did not pay this transaction" };
+    const to = ccc.Script.from(expect.to);
+    const token = expect.token && ccc.Script.from(expect.token);
+    // What a cell gives the recipient: its capacity, or with a token its units of that exact token
+    // (a committed xUDT cell always holds the 16-byte amount).
+    const value = (o, data) => !o.lock.eq(to) ? 0n : !token ? o.capacity : o.type?.eq(token) ? tokenAmount(data) : 0n;
+    let payerInput = -1;
+    let toIn = 0n;
+    for (let i = 0; i < tx.inputs.length; i++) {
+        const cell = await client.getCell(tx.inputs[i].previousOutput);
+        if (!cell)
+            return { ok: false, reason: "an input of the payment cannot be resolved" };
+        if (payerInput < 0 && cell.cellOutput.lock.eq(payerLock))
+            payerInput = i;
+        toIn += value(cell.cellOutput, cell.outputData);
+    }
+    if (payerInput < 0)
+        return { ok: false, reason: "the signing key did not pay this transaction" };
+    // The witness the payer's lock verified (the first of its group) must carry the memo.
+    const witness = tx.getWitnessArgsAt(payerInput);
+    if (!witness?.inputType || ccc.hexFrom(witness.inputType) !== ccc.hexFrom(expect.memo)) {
+        return { ok: false, reason: "the payment does not carry this memo" };
+    }
+    const toOut = tx.outputs.reduce((sum, o, i) => sum + value(o, tx.outputsData[i] ?? "0x"), 0n);
+    const paid = toOut - toIn;
+    if (paid < expect.minAmount) {
+        const shown = token ? `${paid} units` : `${ccc.fixedPointToString(paid)} CKB`;
+        return { ok: false, reason: `paid ${shown}, below the price` };
+    }
+    return { ok: true, paid };
+}

package/dist/place.d.ts

@@ -0,0 +1,104 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * CKB Place: a shared pixel board kept on-chain, with no database.
+ *
+ * A player pays the board's anyone-can-pay address with
+ * `spendInSession(…, { to: board, amount: price × pixels, topUp: true, memo })`,
+ * where `memo` (from `encodePlacement`) lists the pixels. Anyone can rebuild the
+ * board from the chain: take the transactions that touch the board's lock, keep
+ * those that paid enough for their memo (`checkPlacement`), and apply them in
+ * chain order (`applyPlacements`). Last write wins.
+ *
+ * This module is the pure part: no network. Finding and resolving the
+ * transactions is the caller's.
+ *
+ * Memo format, version 1 (bytes):
+ *
+ *     "px1" (0x70 0x78 0x31) | x u8 | y u8 | colour u8 | x | y | colour | …
+ *
+ * One to `maxPixels` pixels; each must lie on the board and use a palette index
+ * below `colours`. Anything else (wrong magic, a partial triple, a pixel off the
+ * board, too many pixels) makes the whole memo invalid: memos come from anyone,
+ * and a payment is never half-applied. A pixel may appear twice; each entry is
+ * paid for and the later one wins.
+ */
+export interface PlaceBoard {
+    /** Columns, 1–256 (x is one byte). */
+    width: number;
+    /** Rows, 1–256 (y is one byte). */
+    height: number;
+    /** Palette size, 1–256; a colour is an index below it. */
+    colours: number;
+    /** Shannons per pixel. */
+    price: bigint;
+    /** Most pixels one memo may carry; bounds the memo at 3 + 3 × maxPixels bytes. */
+    maxPixels: number;
+}
+/** The demo's board: 32×32, 16 colours, 0.1 CKB a pixel, up to 32 pixels a payment. */
+export declare const PLACE_BOARD: PlaceBoard;
+export interface Pixel {
+    x: number;
+    y: number;
+    colour: number;
+}
+export declare class PlaceMemoError extends Error {
+    constructor(message: string);
+}
+/** The memo for a placement. Throws `PlaceMemoError` for an empty, oversized or off-board list. */
+export declare function encodePlacement(pixels: Pixel[], board?: PlaceBoard): ccc.Hex;
+/** The pixels in a memo, or `undefined` if it is not a valid version-1 memo for this board. Never throws. */
+export declare function decodePlacement(memo: ccc.HexLike, board?: PlaceBoard): Pixel[] | undefined;
+/** What a placement costs, in shannons. */
+export declare function placementPrice(pixels: number, board?: PlaceBoard): bigint;
+/**
+ * The cheap part of the check, before resolving any input: the transaction
+ * carries exactly one memo, it is a valid placement, and where it sits (the
+ * witness index). `undefined` if not.
+ */
+export declare function placementMemo(tx: ccc.TransactionLike, board?: PlaceBoard): {
+    index: number;
+    pixels: Pixel[];
+} | undefined;
+export type PlacementCheck = {
+    ok: true;
+    pixels: Pixel[];
+    paid: bigint;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
+ * the cells `tx` spends, resolved, in input order.
+ *
+ * - exactly one memo, and a valid one (`placementMemo`);
+ * - the memo sits in the first witness of an input's lock group, and that lock is
+ *   not the board's: it is the witness the payer's lock verifies, so a lock that
+ *   signs its witnesses (secp256k1: the session key's key cell) commits the
+ *   payment to these pixels and no relay can swap them;
+ * - the board's lock gained at least `price × pixels` (outputs minus inputs).
+ */
+export declare function checkPlacement(tx: ccc.TransactionLike, inputs: ccc.CellOutputLike[], boardLock: ccc.ScriptLike, board?: PlaceBoard): PlacementCheck;
+/** A checked placement and where it sits in the chain. */
+export interface Placement {
+    txHash: ccc.Hex;
+    blockNumber: bigint;
+    /** Position of the transaction in its block. */
+    txIndex: number;
+    pixels: Pixel[];
+}
+/** One square of the board: its colour and the transaction that set it last. */
+export interface PlacedPixel {
+    colour: number;
+    txHash: ccc.Hex;
+    blockNumber: bigint;
+}
+/** Row-major, `width × height` long; `undefined` where nothing has been placed. */
+export type BoardState = (PlacedPixel | undefined)[];
+/**
+ * The board after `placements`, applied in chain order (block number, then
+ * position in the block) whatever order they are given in; within one
+ * placement, in memo order. Last write wins. A transaction listed twice counts
+ * once, and a pixel off the board is skipped.
+ */
+export declare function applyPlacements(placements: Placement[], board?: PlaceBoard): BoardState;

package/dist/place.js

@@ -0,0 +1,151 @@
+import { ccc } from "@ckb-ccc/core";
+/** The demo's board: 32×32, 16 colours, 0.1 CKB a pixel, up to 32 pixels a payment. */
+export const PLACE_BOARD = { width: 32, height: 32, colours: 16, price: 10000000n, maxPixels: 32 };
+export class PlaceMemoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlaceMemoError";
+    }
+}
+const MAGIC = [0x70, 0x78, 0x31]; // "px1"
+const byteSized = (n) => Number.isInteger(n) && n >= 1 && n <= 256;
+function checkBoard(board) {
+    if (!byteSized(board.width) || !byteSized(board.height) || !byteSized(board.colours)) {
+        throw new PlaceMemoError("board width, height and colours must be 1–256");
+    }
+    if (!Number.isInteger(board.maxPixels) || board.maxPixels < 1)
+        throw new PlaceMemoError("maxPixels must be at least 1");
+    if (board.price <= 0n)
+        throw new PlaceMemoError("price must be positive");
+}
+function onBoard(p, board) {
+    const ok = (v, max) => Number.isInteger(v) && v >= 0 && v < max;
+    return ok(p.x, board.width) && ok(p.y, board.height) && ok(p.colour, board.colours);
+}
+/** The memo for a placement. Throws `PlaceMemoError` for an empty, oversized or off-board list. */
+export function encodePlacement(pixels, board = PLACE_BOARD) {
+    checkBoard(board);
+    if (!pixels.length)
+        throw new PlaceMemoError("no pixels to place");
+    if (pixels.length > board.maxPixels)
+        throw new PlaceMemoError(`at most ${board.maxPixels} pixels per placement`);
+    const bytes = [...MAGIC];
+    for (const p of pixels) {
+        if (!onBoard(p, board))
+            throw new PlaceMemoError(`pixel (${p.x}, ${p.y}) colour ${p.colour} is not on the board`);
+        bytes.push(p.x, p.y, p.colour);
+    }
+    return ccc.hexFrom(new Uint8Array(bytes));
+}
+/** The pixels in a memo, or `undefined` if it is not a valid version-1 memo for this board. Never throws. */
+export function decodePlacement(memo, board = PLACE_BOARD) {
+    let bytes;
+    try {
+        checkBoard(board);
+        bytes = ccc.bytesFrom(memo);
+    }
+    catch {
+        return undefined;
+    }
+    // Length first: an oversized memo is refused before it is read.
+    const n = (bytes.length - MAGIC.length) / 3;
+    if (!Number.isInteger(n) || n < 1 || n > board.maxPixels)
+        return undefined;
+    if (MAGIC.some((b, i) => bytes[i] !== b))
+        return undefined;
+    const pixels = [];
+    for (let i = MAGIC.length; i < bytes.length; i += 3) {
+        const p = { x: bytes[i], y: bytes[i + 1], colour: bytes[i + 2] };
+        if (!onBoard(p, board))
+            return undefined;
+        pixels.push(p);
+    }
+    return pixels;
+}
+/** What a placement costs, in shannons. */
+export function placementPrice(pixels, board = PLACE_BOARD) {
+    return board.price * BigInt(pixels);
+}
+/**
+ * The cheap part of the check, before resolving any input: the transaction
+ * carries exactly one memo, it is a valid placement, and where it sits (the
+ * witness index). `undefined` if not.
+ */
+export function placementMemo(tx, board = PLACE_BOARD) {
+    const t = ccc.Transaction.from(tx);
+    let found;
+    for (let i = 0; i < t.witnesses.length; i++) {
+        let inputType;
+        try {
+            inputType = t.getWitnessArgsAt(i)?.inputType;
+        }
+        catch {
+            continue; // not WitnessArgs: carries no memo
+        }
+        if (inputType === undefined)
+            continue;
+        if (found)
+            return undefined; // two memos: which one was paid for is ambiguous
+        found = { index: i, memo: inputType };
+    }
+    if (!found || found.index >= t.inputs.length)
+        return undefined;
+    const pixels = decodePlacement(found.memo, board);
+    return pixels && { index: found.index, pixels };
+}
+/**
+ * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
+ * the cells `tx` spends, resolved, in input order.
+ *
+ * - exactly one memo, and a valid one (`placementMemo`);
+ * - the memo sits in the first witness of an input's lock group, and that lock is
+ *   not the board's: it is the witness the payer's lock verifies, so a lock that
+ *   signs its witnesses (secp256k1: the session key's key cell) commits the
+ *   payment to these pixels and no relay can swap them;
+ * - the board's lock gained at least `price × pixels` (outputs minus inputs).
+ */
+export function checkPlacement(tx, inputs, boardLock, board = PLACE_BOARD) {
+    const t = ccc.Transaction.from(tx);
+    if (inputs.length !== t.inputs.length)
+        return { ok: false, reason: "inputs not resolved" };
+    const memo = placementMemo(t, board);
+    if (!memo)
+        return { ok: false, reason: "no valid placement memo" };
+    const lock = ccc.Script.from(boardLock);
+    const cells = inputs.map((c) => ccc.CellOutput.from(c));
+    const memoLock = cells[memo.index].lock;
+    if (memoLock.eq(lock))
+        return { ok: false, reason: "the memo is in the board's own witness" };
+    if (cells.slice(0, memo.index).some((c) => c.lock.eq(memoLock))) {
+        return { ok: false, reason: "the memo is not in the first witness of its lock group" };
+    }
+    const sum = (cs) => cs.reduce((s, c) => (c.lock.eq(lock) ? s + c.capacity : s), 0n);
+    const paid = sum(t.outputs) - sum(cells);
+    const price = placementPrice(memo.pixels.length, board);
+    if (paid < price) {
+        return { ok: false, reason: `paid ${ccc.fixedPointToString(paid)} CKB for ${memo.pixels.length} pixel(s), below ${ccc.fixedPointToString(price)}` };
+    }
+    return { ok: true, pixels: memo.pixels, paid };
+}
+/**
+ * The board after `placements`, applied in chain order (block number, then
+ * position in the block) whatever order they are given in; within one
+ * placement, in memo order. Last write wins. A transaction listed twice counts
+ * once, and a pixel off the board is skipped.
+ */
+export function applyPlacements(placements, board = PLACE_BOARD) {
+    const state = new Array(board.width * board.height).fill(undefined);
+    const seen = new Set();
+    const ordered = [...placements].sort((a, b) => a.blockNumber !== b.blockNumber ? (a.blockNumber < b.blockNumber ? -1 : 1) : a.txIndex - b.txIndex);
+    for (const p of ordered) {
+        if (seen.has(p.txHash))
+            continue;
+        seen.add(p.txHash);
+        for (const px of p.pixels) {
+            if (!onBoard(px, board))
+                continue;
+            state[px.y * board.width + px.x] = { colour: px.colour, txHash: p.txHash, blockNumber: p.blockNumber };
+        }
+    }
+    return state;
+}

package/dist/session.d.ts

@@ -0,0 +1,63 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * What a session key may do. This is the off-chain mirror of what the session
+ * lock script will enforce on-chain (Week 4): the browser refuses out-of-scope
+ * requests early, and the chain refuses them regardless.
+ */
+export interface SessionScope {
+    /** Largest amount one transaction may move, in shannons. */
+    maxPerTx: bigint;
+    /** Recipient addresses allowed. Omitted means any recipient. */
+    recipients?: string[];
+}
+export interface SessionPolicy {
+    expiresAt: Date;
+    scope: SessionScope;
+}
+export interface Session {
+    /** Never leaves the browser. */
+    privateKey: ccc.Hex;
+    publicKey: ccc.Hex;
+    policy: SessionPolicy;
+    /** Set once the owner has funded the session under the on-chain session lock. */
+    onchain?: {
+        ownerLock: {
+            codeHash: ccc.Hex;
+            hashType: ccc.HashType;
+            args: ccc.Hex;
+        };
+        minInterval: bigint;
+        recipientLockHash?: ccc.Hex;
+        /** A token session: the xUDT type its cells hold, and the most units one spend may move. */
+        token?: {
+            type: {
+                codeHash: ccc.Hex;
+                hashType: ccc.HashType;
+                args: ccc.Hex;
+            };
+            maxPerTx: bigint;
+        };
+        /** The funding transaction, so a key is not forgotten while its funds are still on the way. */
+        openTx?: ccc.Hex;
+    };
+}
+export interface CreateOptions {
+    now?: Date;
+    /** Injectable for tests; defaults to the platform CSPRNG. */
+    randomBytes?: (n: number) => Uint8Array;
+}
+export declare class SessionPolicyError extends Error {
+    constructor(message: string);
+}
+export declare function createSession(policy: SessionPolicy, options?: CreateOptions): Session;
+export declare function isActive(session: Session, now?: Date): boolean;
+export type ScopeCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkRequest(session: Session, request: {
+    to: string;
+    amount: bigint;
+}, now?: Date): ScopeCheck;

package/dist/session.js

@@ -0,0 +1,54 @@
+import { ccc } from "@ckb-ccc/core";
+export class SessionPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SessionPolicyError";
+    }
+}
+const SECP256K1_N = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
+export function createSession(policy, options = {}) {
+    const now = options.now ?? new Date();
+    if (!Number.isFinite(policy.expiresAt.getTime())) {
+        throw new SessionPolicyError("expiresAt is not a valid date");
+    }
+    if (policy.expiresAt.getTime() <= now.getTime()) {
+        throw new SessionPolicyError("expiresAt must be in the future");
+    }
+    if (policy.scope.maxPerTx <= 0n) {
+        throw new SessionPolicyError("scope.maxPerTx must be positive");
+    }
+    if (policy.scope.recipients?.length === 0) {
+        throw new SessionPolicyError("scope.recipients must be omitted or non-empty");
+    }
+    const random = options.randomBytes ?? ((n) => crypto.getRandomValues(new Uint8Array(n)));
+    let privateKey;
+    // Rejection-sample until the key is a valid secp256k1 scalar (1..n-1).
+    for (;;) {
+        const candidate = ccc.hexFrom(random(32));
+        const k = BigInt(candidate);
+        if (k > 0n && k < SECP256K1_N) {
+            privateKey = candidate;
+            break;
+        }
+    }
+    // The signer only derives the public key here; no network call is made.
+    const signer = new ccc.SignerCkbPrivateKey(new ccc.ClientPublicTestnet(), privateKey);
+    return { privateKey, publicKey: signer.publicKey, policy };
+}
+export function isActive(session, now = new Date()) {
+    return now.getTime() < session.policy.expiresAt.getTime();
+}
+export function checkRequest(session, request, now = new Date()) {
+    if (!isActive(session, now))
+        return { ok: false, reason: "session expired" };
+    const { scope } = session.policy;
+    if (request.amount <= 0n)
+        return { ok: false, reason: "amount must be positive" };
+    if (request.amount > scope.maxPerTx) {
+        return { ok: false, reason: `amount exceeds maxPerTx (${ccc.fixedPointToString(scope.maxPerTx)} CKB)` };
+    }
+    if (scope.recipients && !scope.recipients.includes(request.to)) {
+        return { ok: false, reason: "recipient not in scope" };
+    }
+    return { ok: true };
+}

package/dist/store.d.ts

@@ -0,0 +1,26 @@
+import type { Session } from "./session.js";
+/**
+ * Where a session lives between page loads. The key never leaves the device:
+ * the browser store writes to IndexedDB, which is per-origin and local.
+ */
+export interface SessionStore {
+    load(): Promise<Session | undefined>;
+    /**
+     * Stores `session`. Refuses (SessionStoreConflict) to replace a *different*
+     * session: its key may hold funds, and another tab may have just saved it.
+     */
+    save(session: Session): Promise<void>;
+    /** Forgets `session`, only if it is still the stored one; another tab may have replaced it. */
+    clear(session: Session): Promise<void>;
+}
+export declare class SessionStoreConflict extends Error {
+    constructor();
+}
+export declare function serializeSession(s: Session): string;
+export declare function deserializeSession(json: string): Session;
+export declare function memoryStore(): SessionStore;
+/**
+ * One session per `key`. Pages on the same origin that each run their own
+ * session (a wallet page and a reader page, say) pass different keys.
+ */
+export declare function indexedDbStore(idb?: IDBFactory, key?: string): SessionStore;