ckb-session-kit 0.0.0-stage → 1.0.0

package/dist/store.js

@@ -0,0 +1,181 @@
+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;
+}
+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) => {
+            const held = storedKey(value);
+            if (held !== undefined && held !== s.publicKey)
+                throw new SessionStoreConflict();
+            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) => {
+                const held = storedKey(raw);
+                if (held !== undefined && held !== session.publicKey)
+                    throw new SessionStoreConflict();
+                return "put";
+            }, value);
+        },
+        clear: async (session) => {
+            await update((raw) => (storedKey(raw) === session.publicKey ? "delete" : "keep"));
+        },
+    };
+}

package/dist/subscription.d.ts

@@ -0,0 +1,221 @@
+import { ccc } from "@ckb-ccc/core";
+import { type SessionLockDeployment } from "./lock.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 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>;
+}): 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.
+ */
+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 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.
+ */
+export declare function chargeSubscription(charger: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription, opts: {
+    payTo: string;
+    topUp?: boolean;
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+}): Promise<ccc.Hex>;
+/**
+ * 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;
+}>;
+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; undefined when no cell 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.
+ */
+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>;