ckb-session-kit 0.0.0-stage → 2.0.0

package/dist/store.js

@@ -0,0 +1,192 @@
+export class SessionStoreConflict extends Error {
+    constructor() {
+        super("another session is already stored here (opened in another tab?); reload the page");
+        this.name = "SessionStoreConflict";
+    }
+}
+const UNREADABLE = "the stored session is unreadable; it may still hold a funded key, so it is never overwritten";
+/** The stored value's public key, without parsing the rest. */
+function storedKey(raw) {
+    if (raw === undefined)
+        return undefined;
+    let key;
+    try {
+        key = JSON.parse(raw).publicKey;
+    }
+    catch {
+        throw new Error(UNREADABLE);
+    }
+    if (typeof key !== "string")
+        throw new Error(UNREADABLE);
+    return key;
+}
+/**
+ * Throws SessionStoreConflict unless `session` may replace the stored value: a
+ * different key may hold funds, and a save of the same key without the on-chain
+ * binding (a stale tab that never saw the funding) would lose what finds them
+ * (review, 28 Oct).
+ */
+function assertReplaceable(raw, session) {
+    const held = storedKey(raw);
+    if (held === undefined)
+        return;
+    if (held !== session.publicKey)
+        throw new SessionStoreConflict();
+    if (!session.onchain && JSON.parse(raw).onchain)
+        throw new SessionStoreConflict();
+}
+export function serializeSession(s) {
+    const stored = {
+        v: 1,
+        privateKey: s.privateKey,
+        publicKey: s.publicKey,
+        expiresAt: s.policy.expiresAt.toISOString(),
+        maxPerTx: s.policy.scope.maxPerTx.toString(),
+        ...(s.policy.scope.recipients && { recipients: s.policy.scope.recipients }),
+        ...(s.onchain && {
+            onchain: {
+                ownerLock: s.onchain.ownerLock,
+                minInterval: s.onchain.minInterval.toString(),
+                ...(s.onchain.recipientLockHash && { recipientLockHash: s.onchain.recipientLockHash }),
+                ...(s.onchain.token && {
+                    token: { type: s.onchain.token.type, maxPerTx: s.onchain.token.maxPerTx.toString() },
+                }),
+                ...(s.onchain.openTx && { openTx: s.onchain.openTx }),
+            },
+        }),
+    };
+    return JSON.stringify(stored);
+}
+export function deserializeSession(json) {
+    let d;
+    try {
+        d = JSON.parse(json);
+    }
+    catch {
+        throw new Error(UNREADABLE);
+    }
+    if (d.v !== 1)
+        throw new Error(`unsupported stored session version: ${String(d.v)}`);
+    return {
+        privateKey: d.privateKey,
+        publicKey: d.publicKey,
+        policy: {
+            expiresAt: new Date(d.expiresAt),
+            scope: {
+                maxPerTx: BigInt(d.maxPerTx),
+                ...(d.recipients && { recipients: d.recipients }),
+            },
+        },
+        ...(d.onchain && {
+            onchain: {
+                ownerLock: {
+                    codeHash: d.onchain.ownerLock.codeHash,
+                    hashType: d.onchain.ownerLock.hashType,
+                    args: d.onchain.ownerLock.args,
+                },
+                minInterval: BigInt(d.onchain.minInterval),
+                ...(d.onchain.recipientLockHash && { recipientLockHash: d.onchain.recipientLockHash }),
+                ...(d.onchain.token && {
+                    token: {
+                        type: {
+                            codeHash: d.onchain.token.type.codeHash,
+                            hashType: d.onchain.token.type.hashType,
+                            args: d.onchain.token.type.args,
+                        },
+                        maxPerTx: BigInt(d.onchain.token.maxPerTx),
+                    },
+                }),
+                ...(d.onchain.openTx && { openTx: d.onchain.openTx }),
+            },
+        }),
+    };
+}
+export function memoryStore() {
+    let value;
+    return {
+        load: async () => (value === undefined ? undefined : deserializeSession(value)),
+        save: async (s) => {
+            assertReplaceable(value, s);
+            value = serializeSession(s);
+        },
+        clear: async (s) => {
+            if (storedKey(value) === s.publicKey)
+                value = undefined;
+        },
+    };
+}
+const DB = "ckb-session-kit";
+const STORE = "sessions";
+const KEY = "current";
+function request(r) {
+    return new Promise((resolve, reject) => {
+        r.onsuccess = () => resolve(r.result);
+        r.onerror = () => reject(r.error);
+    });
+}
+async function open(idb) {
+    const r = idb.open(DB, 1);
+    r.onupgradeneeded = () => r.result.createObjectStore(STORE);
+    return request(r);
+}
+/**
+ * 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 function indexedDbStore(idb = globalThis.indexedDB, key = KEY) {
+    // Read and write in one readwrite transaction, so two tabs cannot interleave.
+    // It resolves only once the transaction has committed, durably: a save is what
+    // makes it safe to send funds to the key.
+    const update = async (decide, value) => {
+        const db = await open(idb);
+        try {
+            const tx = db.transaction(STORE, "readwrite", { durability: "strict" });
+            const done = new Promise((resolve, reject) => {
+                tx.oncomplete = () => resolve();
+                tx.onabort = () => reject(tx.error ?? new Error("session store transaction aborted"));
+                tx.onerror = () => reject(tx.error ?? new Error("session store transaction failed"));
+            });
+            done.catch(() => { }); // awaited below; a decide() error aborts it first
+            const store = tx.objectStore(STORE);
+            const raw = await request(store.get(key));
+            let action;
+            try {
+                action = decide(raw);
+            }
+            catch (e) {
+                tx.abort();
+                throw e;
+            }
+            if (action === "put")
+                await request(store.put(value, key));
+            if (action === "delete")
+                await request(store.delete(key));
+            await done;
+        }
+        finally {
+            db.close();
+        }
+    };
+    return {
+        load: async () => {
+            const db = await open(idb);
+            try {
+                const raw = await request(db.transaction(STORE, "readonly").objectStore(STORE).get(key));
+                return raw === undefined ? undefined : deserializeSession(raw);
+            }
+            finally {
+                db.close();
+            }
+        },
+        save: async (session) => {
+            const value = serializeSession(session);
+            await update((raw) => {
+                assertReplaceable(raw, session);
+                return "put";
+            }, value);
+        },
+        clear: async (session) => {
+            await update((raw) => (storedKey(raw) === session.publicKey ? "delete" : "keep"));
+        },
+    };
+}

package/dist/subscription.d.ts

@@ -0,0 +1,317 @@
+import { ccc } from "@ckb-ccc/core";
+import { type SessionLockDeployment } from "./lock.js";
+import { type SigningLockOptions, type RetryOptions } from "./onchain.js";
+/**
+ * Subscriptions (docs/design/subscriptions.md): the same session lock, with the
+ * roles moved. The subscriber is the owner; the creator's charger key is the
+ * session key; `max_per_tx` is the price, `min_interval` the period, and the
+ * recipient the creator's payout address. So the network lets the charger take
+ * at most the price, at most once per period, only to the payout address, and
+ * the subscriber can sweep everything back alone at any time.
+ *
+ * - `openSubscription` — the subscriber funds one cell. One signature.
+ * - `chargeSubscription` — the creator's charger key takes the price, paying the
+ *   fee from its own cell. No subscriber involved.
+ * - `cancelSubscription` — the subscriber sweeps the cell back. One signature.
+ * - `verifySubscription` — the creator checks a subscription it was told about.
+ *
+ * A `Subscription` holds no private key: both sides can store it as it is.
+ *
+ * A token subscription (`token` set) is paid in an xUDT token instead: the
+ * 160-byte token layout with `max_per_tx` 0, so no CKB ever leaves the cell, and
+ * the price as `max_per_tx_token`. Charges top up the payout address's
+ * anyone-can-pay cell of that token (docs/design/subscriptions.md, "Token subscriptions").
+ */
+export interface Subscription {
+    subscriberLockHash: ccc.Hex;
+    chargerLockHash: ccc.Hex;
+    payToLockHash: ccc.Hex;
+    /** Per charge, in the subscription's asset: shannons, or token units in a token subscription. */
+    price: bigint;
+    /** Blocks between two charges of the same cell. */
+    periodBlocks: bigint;
+    /** A token subscription: the plain xUDT type script it is paid in. */
+    token?: {
+        type: {
+            codeHash: ccc.Hex;
+            hashType: ccc.HashType;
+            args: ccc.Hex;
+        };
+    };
+    /** The funding transaction, when this side opened it. */
+    openTx?: ccc.Hex;
+}
+export declare function subscriptionLock(deployment: SessionLockDeployment, sub: Subscription): ccc.Script;
+/**
+ * The memo an opening commits to, binding the subscription to one account at the
+ * creator: a hash, so the account id never appears on-chain and can double as a
+ * secret the subscriber's browser presents to the creator.
+ */
+export declare function subscriptionMemo(account: string): ccc.Hex;
+/**
+ * The most cells under one subscription's lock that a status or a charge reads
+ * (security audit, 30 Oct). Anyone can create cells under any lock, and each
+ * cell read costs RPC calls (its creating transaction, and that transaction's
+ * inputs), so without a bound one request could be made to cost thousands. A
+ * subscription in use holds one cell, or a few after top-ups; 16 is far above that.
+ *
+ * Beyond it, a status or a charge is refused with a `SessionPolicyError` of
+ * reason "too-many-cells", never answered from part of the cells: the cells
+ * left unread could hold the newest charge (so access would be denied as
+ * unpaid, with a wrong balance) or a mature cell (so a charge would leave it free
+ * to pay a second price in the same period). Refusing grants nothing and charges
+ * nothing. Only cells of the subscription's own kind count (plain CKB, or its
+ * token). The subscriber clears cells planted among them with
+ * `clearPlantedCells`, which leaves the subscription's own cells as they are,
+ * or with `cancelSubscription`.
+ */
+export declare const MAX_SUBSCRIPTION_CELLS = 16;
+/**
+ * The most transactions that only created cells under the lock that `lastCharge`
+ * pages past in the recent history (review W6 M2). Anyone can make those, but
+ * they are skipped without a fetch, so only the indexer's pages cost anything
+ * (`HISTORY_PAGE` entries each). Past it, a status or a charge is refused
+ * rather than stopping short of the last charge: blocking one period this way
+ * takes over 1024 transactions within it, each locking up at least a cell's
+ * size (153 CKB) under the subscription's lock.
+ */
+export declare const MAX_CREATED_HISTORY: number;
+/**
+ * The memo `clearPlantedCells` puts in the witness (`input_type`) of the
+ * subscriber's own input, under the subscriber's signature: a status tells its
+ * cleanup from a cancel by it, so a cleanup does not end a paid period (review
+ * W6 L2). Only the subscriber can sign it; a subscriber who marks a cancel
+ * with it keeps access only through a period already paid for.
+ */
+export declare const CLEAR_PLANTED_MEMO: `0x${string}`;
+/**
+ * The subscriber opens a subscription, in one transaction and one signature: the
+ * first period's price goes to `payTo` at once (a new cell cannot be charged for a
+ * whole period, so otherwise the first period would be free; review H1), and one
+ * cell holding `budget` shannons goes under the session lock. No key cell: the
+ * creator already owns cells under its charger key. `budget` of the cell's own
+ * size (153 CKB) plus n prices pays n more periods; what is left comes back on
+ * cancel. With a price of 153 CKB or more, the last 153 can be charged too.
+ *
+ * `account` (the subscriber's id at the creator) is committed in the witness of
+ * the subscriber's own input, which the subscriber's signature covers; the
+ * creator checks it with `verifySubscription`, so nobody else can present this
+ * subscription as theirs (review H3).
+ *
+ * `payTo` should be an anyone-can-pay address with a live cell, so a charge of
+ * any size tops it up; otherwise each charge creates a new cell and the price must
+ * be at least that cell's size (61 CKB for a plain address). Keep a plain cell in
+ * the wallet: cancelling needs one to prove ownership.
+ *
+ * With `token`, the subscription is paid in that plain xUDT and `price` is in
+ * token units: the cell holds `token.amount` units plus its own size in CKB
+ * (282 CKB; `budget` may add more, which stays until cancel), and the first price
+ * tops up `payTo`'s cell of the token. `payTo` must then be anyone-can-pay and
+ * already hold a cell of the token: no CKB may leave a token subscription, so a
+ * charge cannot pay for a new token cell.
+ */
+export declare function openSubscription(subscriber: ccc.Signer, deployment: SessionLockDeployment, opts: {
+    charger: string;
+    payTo: string;
+    price: bigint;
+    periodBlocks: bigint;
+    /** Shannons in the subscription cell. Required without `token`; with one, defaults to the cell's own size. */
+    budget?: bigint;
+    /** A token subscription: the plain xUDT it is paid in, and the units put in the cell (beyond the first price). */
+    token?: {
+        type: ccc.ScriptLike;
+        amount: bigint;
+    };
+    account?: string;
+    beforeSend?: (sub: Subscription) => Promise<void>;
+    /** Let an unreviewed charger lock through, with a warning (`allowUnreviewedOwnerLock` covers the subscriber's own lock only). */
+    allowUnreviewedChargerLock?: boolean;
+} & SigningLockOptions): Promise<{
+    txHash: ccc.Hex;
+    subscription: Subscription;
+}>;
+/**
+ * The live cells of a subscription, their balance (shannons) and token balance
+ * (units; 0 without a token), and how many blocks until one can be charged: once
+ * a cell is a period old and the last charge (the newest transaction that spent
+ * a cell under the lock) is too. Throws a `SessionPolicyError` ("too-many-cells")
+ * with over `MAX_SUBSCRIPTION_CELLS` cells under the lock.
+ */
+export declare function findSubscriptionCells(client: ccc.Client, deployment: SessionLockDeployment, sub: Subscription): Promise<{
+    lock: ccc.Script;
+    cells: ccc.Cell[];
+    balance: bigint;
+    tokenBalance: bigint;
+    nextChargeIn: bigint | undefined;
+}>;
+/**
+ * The creator's charger key takes one price from the subscription and pays it to
+ * `payTo` (topping up its anyone-can-pay cell with `topUp`). The fee comes from
+ * one of the charger's own plain cells, which goes back to it smaller. Throws a
+ * `SessionBalanceError` while no cell is a full period old or the last charge is
+ * under one, or once what is left cannot cover a price and still leave a cell behind.
+ *
+ * In a token subscription the price is in token units and always tops up
+ * `payTo`'s cell of the token (`topUp` is implied). The change keeps every
+ * shannon that came in (no CKB may leave) and the tokens less one price, in
+ * exactly 16 data bytes.
+ *
+ * With `topUp` (or a token), `payTo`'s cell is a confirmed one that no
+ * transaction in the node's pool spends, where the node can tell
+ * (`pickPayoutCell`). A charge the node rejects for a spent or unknown input is
+ * built again after clearing the client's cache, with another payout cell,
+ * after a short wait: up to `retry.attempts` in all (default 3), waiting
+ * `retry.delayMs` (default 1000) doubling each time (`rebuildOnDeadInputs`).
+ * `beforeSend` runs again with each new hash. A send whose outcome is unknown
+ * is never retried.
+ */
+export declare function chargeSubscription(charger: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription, opts: ChargeOptions): Promise<ccc.Hex>;
+type ChargeOptions = {
+    payTo: string;
+    topUp?: boolean;
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+    retry?: RetryOptions;
+};
+/**
+ * The subscriber takes everything left back, in owner mode: no creator involved
+ * and no wait. `nothingFound` means no cell is left (already cancelled, or run dry).
+ * In a token subscription the tokens come back as one token cell (`refundedTokens`).
+ * Subscriptions are also found and swept by `recoverSessions`, since their args
+ * begin with the subscriber's lock hash like any session's.
+ */
+export declare function cancelSubscription(subscriber: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription): Promise<{
+    txHash?: ccc.Hex;
+    refunded: bigint;
+    refundedTokens?: bigint;
+    nothingFound?: true;
+}>;
+/**
+ * The subscriber clears cells a third party created under the subscription's
+ * lock, without cancelling (mentor review, 2 Nov). Anyone can create cells under
+ * any lock; past `MAX_SUBSCRIPTION_CELLS` of the subscription's kind, a status or
+ * a charge is refused ("too-many-cells").
+ *
+ * A cell is the subscription's own when its creating transaction is the
+ * opening (`sub.openTx`), or had an input under the subscriber's or the
+ * charger's lock: an opening, a charge, a top-up by the subscriber. Nobody else
+ * can sign for those. Every other cell of the subscription's kind is planted:
+ * one owner-mode transaction (one signature) sweeps them to the subscriber,
+ * who keeps their CKB and tokens. The subscription's own cells are not touched,
+ * so their age and the payments that made them still count: access and the
+ * charge schedule go on as before.
+ *
+ * In a token subscription, look-alikes of the token (cells typed with the
+ * token's code and longer args that start with the token's, which xUDT accepts
+ * and anyone can create with 0 units) are planted too, and swept the same way
+ * when an owner sweep can spend them (plain xUDT, no flags; review W6 M1).
+ *
+ * Bounded: one call keeps at most `4 * MAX_SUBSCRIPTION_CELLS` cells of the
+ * kind, reads at most twice as many listed cells for each of the two scans,
+ * and looks each creating transaction up once. `more` says cells were left
+ * unread: call again once this sweep commits. Refused when none of the cells read is the
+ * subscription's own: cancel instead. `nothingFound` when nothing is planted.
+ */
+export declare function clearPlantedCells(subscriber: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription): Promise<{
+    txHash?: ccc.Hex;
+    swept: number;
+    refunded: bigint;
+    refundedTokens?: bigint;
+    more: boolean;
+    nothingFound?: true;
+}>;
+export type SubscriptionCheck = {
+    ok: true;
+    subscription: Subscription;
+    /** Shannons in the cell. */
+    balance: bigint;
+    /** Token units in the cell (token subscriptions only). */
+    tokenBalance?: bigint;
+    /** Charges the cell can still pay. */
+    chargesLeft: bigint;
+    /** The block until which the subscriber has paid: the block that created this cell, plus one period. */
+    paidThroughBlock: bigint;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The creator checks a subscription from the chain alone. Nothing in the request
+ * is trusted but the out point. The cell at `outPoint` must be live, under this
+ * deployment of the session lock (never an older one), untyped and without data,
+ * with 112-byte args holding exactly these terms, and at least `minBalance`.
+ *
+ * And the transaction that created the cell must have paid `payTo` at least one
+ * price: the opening pays the first period, every charge pays one. A cell the
+ * subscriber re-created in owner mode to reset its age paid nothing, and is
+ * refused (review H2). So access is granted up to `paidThroughBlock`; check the
+ * current cell again (`findSubscriptionCells`) once that block has passed.
+ *
+ * With `account`, the creating transaction must also carry `subscriptionMemo(account)`
+ * in the witness of an input under the subscriber's lock, which only the
+ * subscriber's signature covers: someone else's subscription cannot be claimed
+ * (review H3). The memo is in the opening only, so check `account` once, when a
+ * subscription is registered, then keep the subscription by its lock.
+ *
+ * With `token` (a token subscription), the cell must instead be typed with exactly
+ * that token and hold its amount, with 160-byte args (`max_per_tx` 0, the token's
+ * type hash, `price` in token units as `max_per_tx_token`); `minBalance` is in token
+ * units, and the payment counted is token units into `payTo`'s cells of the token.
+ * Without `token`, a 160-byte cell is refused, and the reverse.
+ */
+export declare function verifySubscription(client: ccc.Client, deployment: SessionLockDeployment, outPoint: ccc.OutPointLike, expected: {
+    charger: string;
+    payTo: string;
+    price: bigint;
+    periodBlocks: bigint;
+    minBalance?: bigint;
+    account?: string;
+    token?: ccc.ScriptLike;
+}): Promise<SubscriptionCheck>;
+export interface SubscriptionStatus {
+    /**
+     * The block until which the subscriber has paid, from the newest paying cell or
+     * a charge that took the whole balance; undefined when neither is left.
+     */
+    paidThroughBlock: bigint | undefined;
+    tip: bigint;
+    /** Whether the tip is within the paid period. */
+    active: boolean;
+    /** Shannons in the subscription's cells. */
+    balance: bigint;
+    /** Token units in the subscription's cells (token subscriptions only). */
+    tokenBalance?: bigint;
+    chargesLeft: bigint;
+    /** Blocks until the creator may charge again (0 = now). */
+    nextChargeIn: bigint | undefined;
+}
+/**
+ * Where a subscription stands, for a creator's server that keeps no database:
+ * the subscriber sends the terms' subscriber lock hash, the opening's hash and
+ * its account id on every request. The opening must have paid the first price
+ * into a cell under exactly this subscription's lock and committed to `account`
+ * under the subscriber's signature; then the live cells give the period paid for.
+ * Each must have been created by a payment, so a cell re-created by the
+ * subscriber to reset its age counts for nothing. Cancelling ends access at once.
+ * A token subscription (`sub.token`) counts payments in its token, as `verifySubscription` does.
+ *
+ * Throws a `SessionPolicyError` of reason "too-many-cells" when over
+ * `MAX_SUBSCRIPTION_CELLS` cells (or recent transactions) sit under the lock:
+ * not a verdict on the subscription, so not an `ok: false`. A server should
+ * answer it as a conflict the subscriber can clear by cancelling and opening again.
+ */
+export declare function subscriptionStatus(client: ccc.Client, deployment: SessionLockDeployment, sub: Subscription, proof: {
+    openTx: ccc.HexLike;
+    account: string;
+}): Promise<{
+    ok: true;
+    status: SubscriptionStatus;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * About how many blocks `seconds` is, from the average block time over the last
+ * `sample` blocks. Block time varies; round up when a period means "no more often than".
+ */
+export declare function blocksForSeconds(client: ccc.Client, seconds: number, sample?: bigint): Promise<bigint>;
+export {};