@shaferllc/keel 0.58.0 → 0.66.0

package/dist/core/tokens.js

@@ -0,0 +1,155 @@
+/**
+ * Personal access tokens — opaque, database-backed bearer tokens for API and
+ * mobile clients, an alternative to the stateless [`jwt`](./crypto.ts). Unlike a
+ * JWT, an opaque token can be *revoked* instantly (it's a row you delete), carries
+ * *abilities* (scopes), and tracks *last used* — at the cost of a lookup per
+ * request. Built on the `db()` layer, so it runs anywhere a `Connection` does.
+ *
+ *   const { token } = await createToken(user.id, { abilities: ["posts:write"] });
+ *   // → "keel_<selector>.<verifier>"  — show once, never recoverable
+ *
+ *   const record = await verifyToken(token);  // { tokenableId, abilities, … } | null
+ *   tokenAllows(record, "posts:write");        // true
+ *
+ * Pair it with `tokenAuth()` in ./auth.ts to protect routes. The token splits
+ * into a public *selector* (indexed, for lookup) and a secret *verifier* (stored
+ * only as a SHA-256 hash) — so a leaked database can't mint working tokens, and
+ * verification needs no `RETURNING`/auto-increment (portable across every driver).
+ *
+ * Expected table (`personal_access_tokens` by default), all timestamps epoch-ms:
+ *   selector TEXT UNIQUE, hash TEXT, tokenable_id TEXT, name TEXT,
+ *   abilities TEXT (JSON), last_used_at INTEGER, expires_at INTEGER, created_at INTEGER
+ */
+import { db } from "./database.js";
+/** The table tokens are stored in; override with `setTokensTable`. */
+let table = "personal_access_tokens";
+/** Change the table personal access tokens are stored in (default `personal_access_tokens`). */
+export function setTokensTable(name) {
+    table = name;
+}
+/* -------------------------------- crypto -------------------------------- */
+const DURATION = /^(\d+)\s*(s|m|h|d)$/;
+const UNIT = { s: 1, m: 60, h: 3600, d: 86400 };
+function seconds(value) {
+    if (typeof value === "number")
+        return value;
+    const match = DURATION.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid duration "${value}" (use e.g. 3600, "30m", "12h", "30d").`);
+    return Number(match[1]) * UNIT[match[2]];
+}
+function base64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomToken(size) {
+    return base64url(crypto.getRandomValues(new Uint8Array(size)));
+}
+/** SHA-256 of the verifier, base64url — what we actually persist. */
+async function sha256(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return base64url(new Uint8Array(digest));
+}
+/** Constant-time string compare, so a bad hash can't be timed byte-by-byte. */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++)
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return result === 0;
+}
+/* ------------------------------- lifecycle ------------------------------ */
+/** Mint a new access token for an entity. Returns the plaintext once — persist nothing but the hash. */
+export async function createToken(tokenableId, options = {}) {
+    const selector = randomToken(12);
+    const verifier = randomToken(24);
+    const abilities = options.abilities ?? ["*"];
+    const expiresAt = options.expiresIn != null ? Date.now() + seconds(options.expiresIn) * 1000 : null;
+    await db(table, options.connection).insert({
+        selector,
+        hash: await sha256(verifier),
+        tokenable_id: String(tokenableId),
+        name: options.name ?? null,
+        abilities: JSON.stringify(abilities),
+        last_used_at: null,
+        expires_at: expiresAt,
+        created_at: Date.now(),
+    });
+    return { token: `keel_${selector}.${verifier}`, selector, abilities, expiresAt };
+}
+/**
+ * Verify a plaintext token and return its record, or `null` if it's malformed,
+ * unknown, tampered, or expired. On success it stamps `last_used_at`. An expired
+ * token is deleted in passing, so the table self-prunes as stale tokens are tried.
+ */
+export async function verifyToken(token, connection) {
+    const match = /^keel_([^.]+)\.(.+)$/.exec(token);
+    if (!match)
+        return null;
+    const selector = match[1];
+    const verifier = match[2];
+    const row = await db(table, connection).where("selector", selector).first();
+    if (!row)
+        return null;
+    if (!safeEqual(await sha256(verifier), String(row.hash)))
+        return null;
+    const expiresAt = row.expires_at != null ? Number(row.expires_at) : null;
+    if (expiresAt != null && Date.now() >= expiresAt) {
+        await db(table, connection).where("selector", selector).delete();
+        return null;
+    }
+    const now = Date.now();
+    await db(table, connection).where("selector", selector).update({ last_used_at: now });
+    return {
+        selector,
+        tokenableId: String(row.tokenable_id),
+        name: row.name ?? null,
+        abilities: parseAbilities(row.abilities),
+        lastUsedAt: now,
+        expiresAt,
+    };
+}
+/** Whether a verified token grants an ability (`["*"]` grants everything). */
+export function tokenAllows(token, ability) {
+    if (!token)
+        return false;
+    return token.abilities.includes("*") || token.abilities.includes(ability);
+}
+/** The negation of `tokenAllows`. */
+export function tokenDenies(token, ability) {
+    return !tokenAllows(token, ability);
+}
+/** Revoke a single token by its selector (the part before the `.`). */
+export async function revokeToken(selector, connection) {
+    await db(table, connection).where("selector", selector).delete();
+}
+/** Revoke every token belonging to an entity — a "log out everywhere" switch. */
+export async function revokeTokens(tokenableId, connection) {
+    await db(table, connection).where("tokenable_id", String(tokenableId)).delete();
+}
+/** List an entity's tokens (metadata only — the secret is never stored). */
+export async function listTokens(tokenableId, connection) {
+    const rows = await db(table, connection).where("tokenable_id", String(tokenableId)).get();
+    return rows.map((row) => ({
+        selector: String(row.selector),
+        tokenableId: String(row.tokenable_id),
+        name: row.name ?? null,
+        abilities: parseAbilities(row.abilities),
+        lastUsedAt: row.last_used_at != null ? Number(row.last_used_at) : null,
+        expiresAt: row.expires_at != null ? Number(row.expires_at) : null,
+    }));
+}
+function parseAbilities(value) {
+    if (typeof value !== "string")
+        return Array.isArray(value) ? value : ["*"];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : ["*"];
+    }
+    catch {
+        return ["*"];
+    }
+}

package/dist/db/d1.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A Keel `Connection` for Cloudflare D1. Pass your D1 binding (from `env.DB`)
+ * and register it — dialect `"sqlite"`:
+ *
+ *   import { d1Connection } from "@shaferllc/keel/db/d1";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *
+ *   setConnection(d1Connection(env.DB), "sqlite");
+ *
+ * The binding is duck-typed — this module imports no driver and no
+ * `@cloudflare/workers-types`, so it stays edge-native and dependency-free. Any
+ * object shaped like a D1 database works.
+ */
+import type { Connection, Row } from "../core/database.js";
+/** The slice of the D1 `Database` API this adapter uses. */
+export interface D1Like {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            all<T = Row>(): Promise<{
+                results?: T[];
+            }>;
+            run(): Promise<{
+                meta: {
+                    changes?: number;
+                    last_row_id?: number;
+                };
+            }>;
+        };
+    };
+}
+/** Build a `Connection` backed by a Cloudflare D1 binding. */
+export declare function d1Connection(database: D1Like): Connection;

package/dist/db/d1.js

@@ -0,0 +1,26 @@
+/**
+ * A Keel `Connection` for Cloudflare D1. Pass your D1 binding (from `env.DB`)
+ * and register it — dialect `"sqlite"`:
+ *
+ *   import { d1Connection } from "@shaferllc/keel/db/d1";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *
+ *   setConnection(d1Connection(env.DB), "sqlite");
+ *
+ * The binding is duck-typed — this module imports no driver and no
+ * `@cloudflare/workers-types`, so it stays edge-native and dependency-free. Any
+ * object shaped like a D1 database works.
+ */
+/** Build a `Connection` backed by a Cloudflare D1 binding. */
+export function d1Connection(database) {
+    return {
+        async select(sql, bindings) {
+            const { results } = await database.prepare(sql).bind(...bindings).all();
+            return results ?? [];
+        },
+        async write(sql, bindings) {
+            const { meta } = await database.prepare(sql).bind(...bindings).run();
+            return { rowsAffected: meta.changes ?? 0, insertId: meta.last_row_id };
+        },
+    };
+}

package/dist/db/libsql.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A Keel `Connection` for libSQL / Turso. Pass an `@libsql/client` client (it
+ * runs on Node and the edge — Turso speaks HTTP) and register it with dialect
+ * `"sqlite"`:
+ *
+ *   import { libsqlConnection } from "@shaferllc/keel/db/libsql";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *   import { createClient } from "@libsql/client";
+ *
+ *   const client = createClient({ url: env.TURSO_URL, authToken: env.TURSO_TOKEN });
+ *   setConnection(libsqlConnection(client), "sqlite");
+ *
+ * The client is duck-typed — this module imports no driver, so it never bundles
+ * `@libsql/client`.
+ */
+import type { Connection, Row } from "../core/database.js";
+/** The slice of the `@libsql/client` API this adapter uses. */
+export interface LibSqlLike {
+    execute(stmt: {
+        sql: string;
+        args: unknown[];
+    }): Promise<{
+        rows: Row[];
+        rowsAffected: number;
+        lastInsertRowid?: bigint | number;
+    }>;
+}
+/** Build a `Connection` backed by an `@libsql/client` client. */
+export declare function libsqlConnection(client: LibSqlLike): Connection;

package/dist/db/libsql.js

@@ -0,0 +1,32 @@
+/**
+ * A Keel `Connection` for libSQL / Turso. Pass an `@libsql/client` client (it
+ * runs on Node and the edge — Turso speaks HTTP) and register it with dialect
+ * `"sqlite"`:
+ *
+ *   import { libsqlConnection } from "@shaferllc/keel/db/libsql";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *   import { createClient } from "@libsql/client";
+ *
+ *   const client = createClient({ url: env.TURSO_URL, authToken: env.TURSO_TOKEN });
+ *   setConnection(libsqlConnection(client), "sqlite");
+ *
+ * The client is duck-typed — this module imports no driver, so it never bundles
+ * `@libsql/client`.
+ */
+/** Build a `Connection` backed by an `@libsql/client` client. */
+export function libsqlConnection(client) {
+    return {
+        async select(sql, bindings) {
+            const { rows } = await client.execute({ sql, args: bindings });
+            // Normalize libSQL's Row objects to plain records for casts/serialization.
+            return rows.map((row) => ({ ...row }));
+        },
+        async write(sql, bindings) {
+            const { rowsAffected, lastInsertRowid } = await client.execute({ sql, args: bindings });
+            return {
+                rowsAffected,
+                insertId: lastInsertRowid != null ? Number(lastInsertRowid) : undefined,
+            };
+        },
+    };
+}

package/dist/db/pg.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A Keel `Connection` for Postgres. Pass any node-postgres-compatible client —
+ * a `pg` `Pool`/`Client` on Node, or `@neondatabase/serverless` on the edge (both
+ * expose the same `query(text, values)` API) — and register it with dialect
+ * `"postgres"`:
+ *
+ *   import { pgConnection } from "@shaferllc/keel/db/pg";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *   import { Pool } from "pg"; // or "@neondatabase/serverless"
+ *
+ *   setConnection(pgConnection(new Pool({ connectionString })), "postgres");
+ *
+ * The client is duck-typed — this module imports no driver, so it works with
+ * whichever Postgres client you install and never bundles one.
+ *
+ * Note on `insertId`: Postgres only returns an inserted row when the statement
+ * has a `RETURNING` clause. This adapter surfaces `rows[0].id` when present;
+ * otherwise `insertId` is `undefined` (so `insertGetId()` needs a `RETURNING id`).
+ */
+import type { Connection, Row } from "../core/database.js";
+/** The slice of the node-postgres client API this adapter uses. */
+export interface PgLike {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Row[];
+        rowCount: number | null;
+    }>;
+}
+/** Build a `Connection` backed by a node-postgres-compatible client. */
+export declare function pgConnection(client: PgLike): Connection;

package/dist/db/pg.js

@@ -0,0 +1,33 @@
+/**
+ * A Keel `Connection` for Postgres. Pass any node-postgres-compatible client —
+ * a `pg` `Pool`/`Client` on Node, or `@neondatabase/serverless` on the edge (both
+ * expose the same `query(text, values)` API) — and register it with dialect
+ * `"postgres"`:
+ *
+ *   import { pgConnection } from "@shaferllc/keel/db/pg";
+ *   import { setConnection } from "@shaferllc/keel/core";
+ *   import { Pool } from "pg"; // or "@neondatabase/serverless"
+ *
+ *   setConnection(pgConnection(new Pool({ connectionString })), "postgres");
+ *
+ * The client is duck-typed — this module imports no driver, so it works with
+ * whichever Postgres client you install and never bundles one.
+ *
+ * Note on `insertId`: Postgres only returns an inserted row when the statement
+ * has a `RETURNING` clause. This adapter surfaces `rows[0].id` when present;
+ * otherwise `insertId` is `undefined` (so `insertGetId()` needs a `RETURNING id`).
+ */
+/** Build a `Connection` backed by a node-postgres-compatible client. */
+export function pgConnection(client) {
+    return {
+        async select(sql, bindings) {
+            const { rows } = await client.query(sql, bindings);
+            return rows;
+        },
+        async write(sql, bindings) {
+            const { rows, rowCount } = await client.query(sql, bindings);
+            const insertId = rows?.[0]?.id;
+            return { rowsAffected: rowCount ?? 0, insertId };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.58.0",
+  "version": "0.66.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -28,6 +28,18 @@
     "./vite": {
       "types": "./dist/vite/index.d.ts",
       "import": "./dist/vite/index.js"
+    },
+    "./db/d1": {
+      "types": "./dist/db/d1.d.ts",
+      "import": "./dist/db/d1.js"
+    },
+    "./db/pg": {
+      "types": "./dist/db/pg.d.ts",
+      "import": "./dist/db/pg.js"
+    },
+    "./db/libsql": {
+      "types": "./dist/db/libsql.d.ts",
+      "import": "./dist/db/libsql.js"
     }
   },
   "files": [