@livo-build/runtime 0.2.5 → 0.2.12

package/dist/telegramAuth.js

@@ -0,0 +1,108 @@
+// Telegram identity verification — the security core of linking a Telegram user to
+// a wallet. Runs server-side (bot token never leaves the server). Two sources:
+//   • Mini App initData  — verifyTelegramInitData (HMAC keyed by "WebAppData")
+//   • Login Widget data   — verifyTelegramLoginWidget (HMAC keyed by SHA256(token))
+// Both follow Telegram's documented algorithm exactly: build a data_check_string of
+// the fields (sorted, key=value, "\n"-joined, EXCLUDING `hash`), HMAC-SHA256 it, and
+// constant-time compare to the provided `hash`. Web Crypto only (Worker-safe).
+// Bare lowercase hex (NO "0x" prefix) — Telegram's `hash` is bare hex, so we must
+// not use the chain-style bytesToHex (which prefixes "0x").
+function toHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i++)
+        out += bytes[i].toString(16).padStart(2, "0");
+    return out;
+}
+const enc = (s) => new TextEncoder().encode(s);
+async function hmacSha256(keyBytes, msg) {
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, msg));
+}
+async function sha256(bytes) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+}
+// Constant-time-ish hex compare (avoids leaking the match position).
+function safeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function freshEnough(authDate, maxAgeSeconds) {
+    if (maxAgeSeconds <= 0)
+        return true;
+    if (!authDate)
+        return false;
+    return Math.floor(Date.now() / 1000) - authDate <= maxAgeSeconds;
+}
+function userFromRaw(u) {
+    return {
+        id: Number(u.id),
+        username: u.username,
+        firstName: u.first_name,
+        lastName: u.last_name,
+        languageCode: u.language_code,
+        isPremium: u.is_premium,
+        photoUrl: u.photo_url,
+    };
+}
+// Verify Telegram Mini App `initData` (the raw query string from
+// window.Telegram.WebApp.initData). Returns the verified user, or null.
+export async function verifyTelegramInitData(initData, botToken, options = {}) {
+    if (!initData || !botToken)
+        return null;
+    const params = new URLSearchParams(initData);
+    const hash = params.get("hash");
+    if (!hash)
+        return null;
+    params.delete("hash");
+    const dataCheckString = [...params.entries()]
+        .map(([k, v]) => `${k}=${v}`)
+        .sort()
+        .join("\n");
+    // secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)
+    const secretKey = await hmacSha256(enc("WebAppData"), enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, hash))
+        return null;
+    if (!freshEnough(Number(params.get("auth_date") ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    const userJson = params.get("user");
+    if (!userJson)
+        return null;
+    try {
+        return userFromRaw(JSON.parse(userJson));
+    }
+    catch {
+        return null;
+    }
+}
+// Verify Telegram Login Widget data (the object the widget hands your page, with a
+// `hash`). Returns the verified user, or null.
+export async function verifyTelegramLoginWidget(data, botToken, options = {}) {
+    const hash = data.hash;
+    if (!hash || !botToken)
+        return null;
+    const dataCheckString = Object.keys(data)
+        .filter((k) => k !== "hash" && data[k] !== undefined)
+        .sort()
+        .map((k) => `${k}=${data[k]}`)
+        .join("\n");
+    // secret_key = SHA256(bot_token) (NOTE: plain SHA-256 here, not HMAC).
+    const secretKey = await sha256(enc(botToken));
+    const calc = toHex(await hmacSha256(secretKey, enc(dataCheckString)));
+    if (!safeEqualHex(calc, String(hash)))
+        return null;
+    if (!freshEnough(Number(data.auth_date ?? 0), options.maxAgeSeconds ?? 86400))
+        return null;
+    return userFromRaw(data);
+}
+// Pull the payload from a `/start <payload>` deep-link command (the non-Mini-App
+// linking flow). Returns the trimmed payload, or null.
+export function parseStartPayload(text) {
+    const m = /^\/start(?:@\w+)?(?:\s+(.+))?$/.exec(text.trim());
+    const payload = m?.[1]?.trim();
+    return payload ? payload : null;
+}

package/dist/telegramAuth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telegramAuth.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { createHmac, createHash } from "node:crypto";
+import { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+const BOT_TOKEN = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11";
+const USER = { id: 42, username: "alice", first_name: "Alice", language_code: "en" };
+// Build a valid Mini App initData the way Telegram does — using node:crypto, an
+// INDEPENDENT implementation from the verifier's Web Crypto. Agreement = correct.
+function makeInitData(botToken, authDate, user = USER) {
+    const params = new URLSearchParams();
+    params.set("user", JSON.stringify(user));
+    params.set("auth_date", String(authDate));
+    params.set("query_id", "AAH-test");
+    const dcs = [...params.entries()].map(([k, v]) => `${k}=${v}`).sort().join("\n");
+    const secret = createHmac("sha256", "WebAppData").update(botToken).digest();
+    const hash = createHmac("sha256", secret).update(dcs).digest("hex");
+    params.set("hash", hash);
+    return params.toString();
+}
+const now = () => Math.floor(Date.now() / 1000);
+describe("verifyTelegramInitData", () => {
+    it("accepts a valid initData and returns the user", async () => {
+        const u = await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), BOT_TOKEN);
+        expect(u).not.toBeNull();
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+        expect(u?.firstName).toBe("Alice");
+    });
+    it("rejects a tampered hash", async () => {
+        const good = makeInitData(BOT_TOKEN, now());
+        const tampered = good.replace(/hash=([0-9a-f])/, (_, c) => `hash=${c === "0" ? "1" : "0"}`);
+        expect(await verifyTelegramInitData(tampered, BOT_TOKEN)).toBeNull();
+    });
+    it("rejects the wrong bot token", async () => {
+        expect(await verifyTelegramInitData(makeInitData(BOT_TOKEN, now()), "999:WRONG")).toBeNull();
+    });
+    it("rejects stale auth_date", async () => {
+        const old = makeInitData(BOT_TOKEN, now() - 100_000);
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 3600 })).toBeNull();
+        // ...but accepts it when the age check is disabled.
+        expect(await verifyTelegramInitData(old, BOT_TOKEN, { maxAgeSeconds: 0 })).not.toBeNull();
+    });
+    it("rejects empty / hashless input", async () => {
+        expect(await verifyTelegramInitData("", BOT_TOKEN)).toBeNull();
+        expect(await verifyTelegramInitData("user=%7B%7D&auth_date=1", BOT_TOKEN)).toBeNull();
+    });
+});
+describe("verifyTelegramLoginWidget", () => {
+    it("accepts valid widget data (SHA256(token) secret)", async () => {
+        const data = { id: 42, username: "alice", auth_date: now() };
+        const dcs = Object.keys(data).sort().map((k) => `${k}=${data[k]}`).join("\n");
+        const secret = createHash("sha256").update(BOT_TOKEN).digest();
+        data.hash = createHmac("sha256", secret).update(dcs).digest("hex");
+        const u = await verifyTelegramLoginWidget(data, BOT_TOKEN);
+        expect(u?.id).toBe(42);
+        expect(u?.username).toBe("alice");
+    });
+    it("rejects a bad hash", async () => {
+        expect(await verifyTelegramLoginWidget({ id: 1, auth_date: now(), hash: "deadbeef" }, BOT_TOKEN)).toBeNull();
+    });
+});
+describe("parseStartPayload", () => {
+    it("extracts the payload from /start", () => {
+        expect(parseStartPayload("/start link_abc123")).toBe("link_abc123");
+        expect(parseStartPayload("/start@MyBot tok")).toBe("tok");
+        expect(parseStartPayload("/start")).toBeNull();
+        expect(parseStartPayload("hello")).toBeNull();
+    });
+});

package/dist/telegramLinks.d.ts

@@ -0,0 +1,27 @@
+import type { D1Like } from "./store.js";
+export declare const TELEGRAM_LINKS_TABLE = "telegram_links";
+export interface TelegramLink {
+    telegramId: string;
+    address: string;
+    username?: string;
+    createdAt: number;
+}
+export declare class TelegramLinks {
+    private readonly db;
+    private readonly table;
+    private ready;
+    constructor(db: D1Like, table?: string);
+    private init;
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    link(telegramId: string | number, address: string, username?: string): Promise<void>;
+    /** Remove the link for a Telegram user. */
+    unlink(telegramId: string | number): Promise<void>;
+    /** The wallet address linked to a Telegram user, or null. */
+    walletFor(telegramId: string | number): Promise<string | null>;
+    /** The Telegram link for a wallet address, or null. */
+    telegramFor(address: string): Promise<TelegramLink | null>;
+    /** Whether a Telegram user has a linked wallet. */
+    isLinked(telegramId: string | number): Promise<boolean>;
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    all(limit?: number): Promise<TelegramLink[]>;
+}

package/dist/telegramLinks.js

@@ -0,0 +1,78 @@
+// TelegramLinks — the shared binding between a Telegram user and a wallet address,
+// stored in the project's D1 (env.DB, which is bound into BOTH the api Worker and
+// the bot). Write it from the api after verifying both proofs; read it from the bot
+// to answer "is this user's wallet connected?".
+export const TELEGRAM_LINKS_TABLE = "telegram_links";
+export class TelegramLinks {
+    db;
+    table;
+    ready = null;
+    constructor(db, table = TELEGRAM_LINKS_TABLE) {
+        this.db = db;
+        this.table = table;
+        if (!db)
+            throw new Error("TelegramLinks: no D1 binding — pass env.DB (is the project's D1 bound?)");
+    }
+    async init() {
+        if (!this.ready) {
+            this.ready = (async () => {
+                if (this.db.exec) {
+                    await this.db.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (telegram_id TEXT PRIMARY KEY, address TEXT NOT NULL, username TEXT, created_at INTEGER); CREATE INDEX IF NOT EXISTS ${this.table}_address ON ${this.table} (address);`);
+                }
+            })();
+        }
+        return this.ready;
+    }
+    /** Create/replace the link for a Telegram user (one wallet per Telegram id). */
+    async link(telegramId, address, username) {
+        await this.init();
+        await this.db
+            .prepare(`INSERT INTO ${this.table} (telegram_id, address, username, created_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(telegram_id) DO UPDATE SET address = excluded.address, username = excluded.username, created_at = excluded.created_at`)
+            .bind(String(telegramId), address.toLowerCase(), username ?? null, Date.now())
+            .run();
+    }
+    /** Remove the link for a Telegram user. */
+    async unlink(telegramId) {
+        await this.init();
+        await this.db.prepare(`DELETE FROM ${this.table} WHERE telegram_id = ?`).bind(String(telegramId)).run();
+    }
+    /** The wallet address linked to a Telegram user, or null. */
+    async walletFor(telegramId) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT address FROM ${this.table} WHERE telegram_id = ?`)
+            .bind(String(telegramId))
+            .first();
+        return row ? row.address : null;
+    }
+    /** The Telegram link for a wallet address, or null. */
+    async telegramFor(address) {
+        await this.init();
+        const row = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} WHERE address = ?`)
+            .bind(address.toLowerCase())
+            .first();
+        return row
+            ? { telegramId: row.telegram_id, address: row.address, username: row.username ?? undefined, createdAt: row.created_at }
+            : null;
+    }
+    /** Whether a Telegram user has a linked wallet. */
+    async isLinked(telegramId) {
+        return (await this.walletFor(telegramId)) !== null;
+    }
+    /** Every link — for a keeper that re-checks balances and boots ineligible users. */
+    async all(limit = 1000) {
+        await this.init();
+        const res = await this.db
+            .prepare(`SELECT telegram_id, address, username, created_at FROM ${this.table} LIMIT ?`)
+            .bind(limit)
+            .all();
+        return (res.results ?? []).map((r) => ({
+            telegramId: r.telegram_id,
+            address: r.address,
+            username: r.username ?? undefined,
+            createdAt: r.created_at,
+        }));
+    }
+}

package/dist/webhook.d.ts

@@ -0,0 +1,18 @@
+export type SignatureEncoding = "hex" | "base64";
+/** Compute the HMAC-SHA256 signature of a payload (for signing outgoing webhooks/tests). */
+export declare function signWebhook(payload: string, secret: string, encoding?: SignatureEncoding): Promise<string>;
+export interface VerifyWebhookParams {
+    /** The RAW request body (verify before JSON.parse — re-serialization changes bytes). */
+    payload: string;
+    secret: string;
+    /** The signature header value. A `scheme=` prefix (e.g. "sha256=") is stripped for hex. */
+    signature: string;
+    /** Digest encoding of `signature` (default "hex"). */
+    encoding?: SignatureEncoding;
+}
+/**
+ * Verify a webhook's HMAC-SHA256 signature against the raw body. Returns true iff the
+ * signature matches. For hex signatures a leading `algo=` prefix (GitHub's "sha256=")
+ * is stripped automatically.
+ */
+export declare function verifyWebhook(params: VerifyWebhookParams): Promise<boolean>;

package/dist/webhook.js

@@ -0,0 +1,49 @@
+// Inbound webhook signature verification (GitHub/Stripe-style HMAC-SHA256). Verify
+// that a raw request body was signed with your shared secret before trusting it.
+// Constant-time comparison; no hand-rolled crypto.
+function enc(s) {
+    return new TextEncoder().encode(s);
+}
+function toHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+function toBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+async function hmac(secret, payload) {
+    const key = await crypto.subtle.importKey("raw", enc(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, enc(payload)));
+}
+/** Constant-time string compare (length-independent leak is acceptable for digests). */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Compute the HMAC-SHA256 signature of a payload (for signing outgoing webhooks/tests). */
+export async function signWebhook(payload, secret, encoding = "hex") {
+    const mac = await hmac(secret, payload);
+    return encoding === "base64" ? toBase64(mac) : toHex(mac);
+}
+/**
+ * Verify a webhook's HMAC-SHA256 signature against the raw body. Returns true iff the
+ * signature matches. For hex signatures a leading `algo=` prefix (GitHub's "sha256=")
+ * is stripped automatically.
+ */
+export async function verifyWebhook(params) {
+    const encoding = params.encoding ?? "hex";
+    let provided = params.signature.trim();
+    if (encoding === "hex")
+        provided = provided.replace(/^[A-Za-z0-9_-]+=/, ""); // strip "sha256=" etc (hex has no '=')
+    const expected = await signWebhook(params.payload, params.secret, encoding);
+    return timingSafeEqual(expected.toLowerCase(), provided.toLowerCase());
+}

package/dist/webhook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webhook.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { signWebhook, verifyWebhook } from "./webhook.js";
+import { cached } from "./cache.js";
+describe("webhook signatures", () => {
+    it("round-trips a hex signature and strips a sha256= prefix", async () => {
+        const sig = await signWebhook("payload-body", "shh");
+        expect(await verifyWebhook({ payload: "payload-body", secret: "shh", signature: sig })).toBe(true);
+        expect(await verifyWebhook({ payload: "payload-body", secret: "shh", signature: "sha256=" + sig })).toBe(true);
+    });
+    it("rejects a wrong secret or tampered payload", async () => {
+        const sig = await signWebhook("a", "s1");
+        expect(await verifyWebhook({ payload: "a", secret: "s2", signature: sig })).toBe(false);
+        expect(await verifyWebhook({ payload: "b", secret: "s1", signature: sig })).toBe(false);
+    });
+    it("supports base64 encoding", async () => {
+        const sig = await signWebhook("x", "k", "base64");
+        expect(await verifyWebhook({ payload: "x", secret: "k", signature: sig, encoding: "base64" })).toBe(true);
+    });
+});
+function memKv() {
+    const store = new Map();
+    return {
+        store,
+        get: async (k) => store.get(k) ?? null,
+        put: async (k, v) => void store.set(k, v),
+    };
+}
+describe("cached", () => {
+    it("computes once, then serves from cache", async () => {
+        const kv = memKv();
+        let calls = 0;
+        const produce = async () => {
+            calls++;
+            return { n: 42 };
+        };
+        expect(await cached(kv, "k", produce, { ttlSeconds: 60 })).toEqual({ n: 42 });
+        expect(await cached(kv, "k", produce, { ttlSeconds: 60 })).toEqual({ n: 42 });
+        expect(calls).toBe(1);
+        expect(kv.store.has("cache:k")).toBe(true);
+    });
+    it("recomputes when the cached value is corrupt", async () => {
+        const kv = memKv();
+        kv.store.set("cache:bad", "{not json");
+        expect(await cached(kv, "bad", async () => "fresh", { ttlSeconds: 60 })).toBe("fresh");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/runtime",
-  "version": "0.2.5",
+  "version": "0.2.12",
   "description": "Livo runtime — chain signing/reads, D1 state, and logging for keepers, servers, and bots.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,9 +16,19 @@
       "import": "./dist/contracts.js"
     }
   },
-  "files": ["dist"],
-  "engines": { "node": ">=18" },
-  "keywords": ["livo", "web3", "keeper", "eip1559", "evm"],
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "livo",
+    "web3",
+    "keeper",
+    "eip1559",
+    "evm"
+  ],
   "publishConfig": {
     "access": "public"
   },