@shaferllc/keel 0.59.0 → 0.66.0

package/dist/core/social.js

@@ -0,0 +1,337 @@
+/**
+ * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". Like Adonis
+ * Ally, this owns the OAuth dance only: it hands you a normalized `SocialUser`,
+ * and *you* find-or-create your own user and log them in (with a session,
+ * `jwt`, or an access `token`). It stores nothing.
+ *
+ *   const github = social.github({ clientId, clientSecret, redirectUri });
+ *
+ *   // 1. send the user off to the provider
+ *   router.get("/auth/github", () => redirect(github.redirect({ state })));
+ *
+ *   // 2. handle the callback
+ *   router.get("/auth/github/callback", async () => {
+ *     const gh = await github.user(request.query("code"));   // { id, email, name, … }
+ *     const user = await users.firstOrCreate({ github_id: gh.id }, { email: gh.email });
+ *     auth().login(user.id);
+ *   });
+ *
+ * Every driver is `fetch`-based — no SDK, no native deps — so it runs on Node and
+ * the edge alike. Presets cover GitHub, Google, and Discord; build your own with
+ * `oauthDriver()` for anything else OAuth2.
+ */
+/** Thrown when the token exchange or profile fetch fails. */
+export class OAuthError extends Error {
+    provider;
+    constructor(message, provider) {
+        super(message);
+        this.provider = provider;
+        this.name = "OAuthError";
+    }
+}
+/** A random, URL-safe `state` for CSRF protection — stash it, then verify on callback. */
+export function oauthState(bytes = 16) {
+    const raw = crypto.getRandomValues(new Uint8Array(bytes));
+    let s = "";
+    for (const b of raw)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** A generic OAuth 2.0 authorization-code driver. */
+export class OAuthDriver {
+    spec;
+    config;
+    constructor(spec, config) {
+        this.spec = spec;
+        this.config = config;
+    }
+    /** Build the provider's authorize URL to redirect the user to. */
+    redirect(options = {}) {
+        const scopes = options.scopes ?? this.config.scopes ?? this.spec.defaultScopes;
+        const url = new URL(this.spec.authorizeUrl);
+        url.searchParams.set("client_id", this.config.clientId);
+        url.searchParams.set("redirect_uri", this.config.redirectUri);
+        url.searchParams.set("response_type", "code");
+        if (scopes.length)
+            url.searchParams.set("scope", scopes.join(this.spec.scopeSeparator ?? " "));
+        if (options.state)
+            url.searchParams.set("state", options.state);
+        for (const [key, value] of Object.entries(options.params ?? {}))
+            url.searchParams.set(key, value);
+        return url.toString();
+    }
+    /** Exchange an authorization `code` (from the callback) for an access token. */
+    async exchangeCode(code) {
+        const res = await fetch(this.spec.tokenUrl, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                code,
+                redirect_uri: this.config.redirectUri,
+                grant_type: "authorization_code",
+            }),
+        });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok || data.error) {
+            throw new OAuthError(`Token exchange failed: ${data.error_description ?? data.error ?? res.status}`, this.spec.name);
+        }
+        return {
+            accessToken: String(data.access_token),
+            tokenType: data.token_type,
+            refreshToken: data.refresh_token,
+            expiresIn: data.expires_in,
+            scope: data.scope,
+            raw: data,
+        };
+    }
+    /** Fetch the normalized user for an already-obtained access token. */
+    userFromToken(token) {
+        return this.spec.fetchUser(token);
+    }
+    /** The full callback step: exchange the `code`, then fetch the user. */
+    async user(code) {
+        return this.userFromToken(await this.exchangeCode(code));
+    }
+}
+/** Build a driver for any OAuth2 provider from a spec + config. */
+export function oauthDriver(spec, config) {
+    return new OAuthDriver(spec, config);
+}
+/* -------------------------------- helpers ------------------------------- */
+async function getJson(url, token, headers = {}) {
+    const res = await fetch(url, {
+        headers: { authorization: `Bearer ${token.accessToken}`, accept: "application/json", ...headers },
+    });
+    return (await res.json().catch(() => ({})));
+}
+/* ------------------------------- providers ------------------------------ */
+/** GitHub OAuth (`user:email` gives access to a verified primary email). */
+export function github(config) {
+    return new OAuthDriver({
+        name: "github",
+        authorizeUrl: "https://github.com/login/oauth/authorize",
+        tokenUrl: "https://github.com/login/oauth/access_token",
+        defaultScopes: ["read:user", "user:email"],
+        async fetchUser(token) {
+            const headers = { "user-agent": "keel", accept: "application/vnd.github+json" };
+            const data = await getJson("https://api.github.com/user", token, headers);
+            let email = data.email ?? null;
+            if (!email) {
+                // The public profile hides email unless set — pull the verified primary.
+                const emails = (await getJson("https://api.github.com/user/emails", token, headers));
+                if (Array.isArray(emails)) {
+                    email = emails.find((e) => e.primary && e.verified)?.email ?? emails[0]?.email ?? null;
+                }
+            }
+            return {
+                id: String(data.id),
+                email,
+                name: data.name ?? null,
+                nickname: data.login ?? null,
+                avatarUrl: data.avatar_url ?? null,
+                token,
+                raw: data,
+            };
+        },
+    }, config);
+}
+/** Google OAuth / OpenID Connect. */
+export function google(config) {
+    return new OAuthDriver({
+        name: "google",
+        authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl: "https://oauth2.googleapis.com/token",
+        defaultScopes: ["openid", "email", "profile"],
+        async fetchUser(token) {
+            const data = await getJson("https://openidconnect.googleapis.com/v1/userinfo", token);
+            return {
+                id: String(data.sub),
+                email: data.email ?? null,
+                name: data.name ?? null,
+                nickname: data.given_name ?? data.email ?? null,
+                avatarUrl: data.picture ?? null,
+                token,
+                raw: data,
+            };
+        },
+    }, config);
+}
+/** Discord OAuth. */
+export function discord(config) {
+    return new OAuthDriver({
+        name: "discord",
+        authorizeUrl: "https://discord.com/oauth2/authorize",
+        tokenUrl: "https://discord.com/api/oauth2/token",
+        defaultScopes: ["identify", "email"],
+        async fetchUser(token) {
+            const data = await getJson("https://discord.com/api/users/@me", token);
+            const id = String(data.id);
+            const avatar = data.avatar;
+            return {
+                id,
+                email: data.email ?? null,
+                name: data.global_name ?? data.username ?? null,
+                nickname: data.username ?? null,
+                avatarUrl: avatar ? `https://cdn.discordapp.com/avatars/${id}/${avatar}.png` : null,
+                token,
+                raw: data,
+            };
+        },
+    }, config);
+}
+/** Percent-encode per RFC 3986 (OAuth's stricter rules — encodes `!*'()` too). */
+function pctEncode(value) {
+    return encodeURIComponent(value).replace(/[!*'()]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+function bytesToB64(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+async function hmacSha1(base, key) {
+    const cryptoKey = await crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "HMAC", hash: "SHA-1" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(base));
+    return bytesToB64(new Uint8Array(sig));
+}
+/**
+ * Compute an OAuth 1.0a HMAC-SHA1 signature (RFC 5849). `params` holds every
+ * signed parameter with *raw* (unencoded) values — the oauth_* fields plus any
+ * query/body params, minus `oauth_signature`. Exposed for signing custom API
+ * requests beyond the built-in flow.
+ */
+export async function oauth1Signature(input) {
+    const paramString = Object.keys(input.params)
+        .sort()
+        .map((k) => `${pctEncode(k)}=${pctEncode(input.params[k])}`)
+        .join("&");
+    const baseUrl = input.url.split(/[?#]/)[0]; // the base string excludes query/fragment
+    const base = [input.method.toUpperCase(), pctEncode(baseUrl), pctEncode(paramString)].join("&");
+    const key = `${pctEncode(input.consumerSecret)}&${pctEncode(input.tokenSecret ?? "")}`;
+    return hmacSha1(base, key);
+}
+function oauthNonce() {
+    return bytesToB64(crypto.getRandomValues(new Uint8Array(16))).replace(/[^A-Za-z0-9]/g, "");
+}
+function parseForm(body) {
+    const out = {};
+    for (const pair of body.split("&")) {
+        const i = pair.indexOf("=");
+        if (i === -1)
+            continue;
+        out[decodeURIComponent(pair.slice(0, i))] = decodeURIComponent(pair.slice(i + 1));
+    }
+    return out;
+}
+/** A generic OAuth 1.0a driver. */
+export class OAuth1Driver {
+    spec;
+    config;
+    constructor(spec, config) {
+        this.spec = spec;
+        this.config = config;
+    }
+    /** Sign a request and build its `Authorization: OAuth …` header. */
+    async authHeader(method, url, extraOauth, tokenSecret, queryParams = {}) {
+        const oauth = {
+            oauth_consumer_key: this.config.clientId,
+            oauth_nonce: oauthNonce(),
+            oauth_signature_method: "HMAC-SHA1",
+            oauth_timestamp: String(Math.floor(Date.now() / 1000)),
+            oauth_version: "1.0",
+            ...extraOauth,
+        };
+        const signature = await oauth1Signature({
+            method,
+            url,
+            params: { ...oauth, ...queryParams },
+            consumerSecret: this.config.clientSecret,
+            tokenSecret,
+        });
+        const header = { ...oauth, oauth_signature: signature };
+        return ("OAuth " +
+            Object.keys(header)
+                .sort()
+                .map((k) => `${pctEncode(k)}="${pctEncode(header[k])}"`)
+                .join(", "));
+    }
+    /** Step 1 — obtain a temporary request token. Stash its `tokenSecret` for the callback. */
+    async requestToken() {
+        const header = await this.authHeader("POST", this.spec.requestTokenUrl, { oauth_callback: this.config.redirectUri }, "");
+        const res = await fetch(this.spec.requestTokenUrl, { method: "POST", headers: { authorization: header } });
+        const body = await res.text();
+        if (!res.ok)
+            throw new OAuthError(`Request token failed: ${res.status} ${body}`, this.spec.name);
+        const parsed = parseForm(body);
+        return { token: parsed.oauth_token ?? "", tokenSecret: parsed.oauth_token_secret ?? "", raw: parsed };
+    }
+    /** Step 2 — the URL to send the user to, carrying the request token. */
+    redirect(requestToken) {
+        const t = typeof requestToken === "string" ? requestToken : requestToken.token;
+        const url = new URL(this.spec.authorizeUrl);
+        url.searchParams.set("oauth_token", t);
+        return url.toString();
+    }
+    /** Step 3 — swap the callback's `oauth_token` + `oauth_verifier` for an access token. */
+    async accessToken(oauthToken, verifier, requestTokenSecret) {
+        const header = await this.authHeader("POST", this.spec.accessTokenUrl, { oauth_token: oauthToken, oauth_verifier: verifier }, requestTokenSecret);
+        const res = await fetch(this.spec.accessTokenUrl, { method: "POST", headers: { authorization: header } });
+        const body = await res.text();
+        if (!res.ok)
+            throw new OAuthError(`Access token failed: ${res.status} ${body}`, this.spec.name);
+        const parsed = parseForm(body);
+        return { token: parsed.oauth_token ?? "", tokenSecret: parsed.oauth_token_secret ?? "", raw: parsed };
+    }
+    /** The full callback step: exchange for an access token, then fetch the user. */
+    async user(oauthToken, verifier, requestTokenSecret) {
+        const token = await this.accessToken(oauthToken, verifier, requestTokenSecret);
+        return this.spec.fetchUser(token, this);
+    }
+    /** A signed GET against the provider's API on the user's behalf (for `fetchUser`). */
+    async get(url, token) {
+        const query = {};
+        new URL(url).searchParams.forEach((v, k) => (query[k] = v));
+        const header = await this.authHeader("GET", url, { oauth_token: token.token }, token.tokenSecret, query);
+        const res = await fetch(url, { headers: { authorization: header } });
+        return (await res.json().catch(() => ({})));
+    }
+}
+/** Build a driver for any OAuth 1.0a provider from a spec + config. */
+export function oauth1Driver(spec, config) {
+    return new OAuth1Driver(spec, config);
+}
+/** Twitter / X (OAuth 1.0a). Enable "Request email" in your app settings for `email`. */
+export function twitter(config) {
+    return new OAuth1Driver({
+        name: "twitter",
+        requestTokenUrl: "https://api.twitter.com/oauth/request_token",
+        authorizeUrl: "https://api.twitter.com/oauth/authenticate",
+        accessTokenUrl: "https://api.twitter.com/oauth/access_token",
+        async fetchUser(token, driver) {
+            const data = await driver.get("https://api.twitter.com/1.1/account/verify_credentials.json?include_email=true", token);
+            return {
+                id: String(data.id_str ?? data.id),
+                email: data.email ?? null,
+                name: data.name ?? null,
+                nickname: data.screen_name ?? null,
+                avatarUrl: data.profile_image_url_https ?? null,
+                token,
+                raw: data,
+            };
+        },
+    }, config);
+}
+/** All social providers under one namespace: `social.github({...})`, `social.twitter({...})`. */
+export const social = {
+    // OAuth 2.0
+    github,
+    google,
+    discord,
+    driver: oauthDriver,
+    state: oauthState,
+    // OAuth 1.0a
+    twitter,
+    driver1: oauth1Driver,
+};

package/dist/core/tokens.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+ */
+/** A verified token, as returned by `verifyToken`. */
+export interface AccessToken {
+    /** Public lookup key (the part before the `.`). Pass to `revokeToken`. */
+    selector: string;
+    /** The id of the entity the token belongs to (usually a user id). */
+    tokenableId: string;
+    /** Optional human label, for a "your tokens" management screen. */
+    name: string | null;
+    /** Granted abilities/scopes; `["*"]` means all. */
+    abilities: string[];
+    /** Epoch-ms of last successful use, or null if never (updated on verify). */
+    lastUsedAt: number | null;
+    /** Epoch-ms expiry, or null for a token that never expires. */
+    expiresAt: number | null;
+}
+export interface CreateTokenOptions {
+    /** Abilities/scopes to grant. Defaults to `["*"]` (everything). */
+    abilities?: string[];
+    /** Lifetime — seconds (number) or a duration string (`"30d"`, `"12h"`). No expiry if omitted. */
+    expiresIn?: number | string;
+    /** A human label for the token. */
+    name?: string;
+    /** Which registered connection to store the token on. */
+    connection?: string;
+}
+export interface IssuedToken {
+    /** The plaintext token — `keel_<selector>.<verifier>`. Shown once; store the hash only. */
+    token: string;
+    selector: string;
+    abilities: string[];
+    expiresAt: number | null;
+}
+/** Change the table personal access tokens are stored in (default `personal_access_tokens`). */
+export declare function setTokensTable(name: string): void;
+/** Mint a new access token for an entity. Returns the plaintext once — persist nothing but the hash. */
+export declare function createToken(tokenableId: string | number, options?: CreateTokenOptions): Promise<IssuedToken>;
+/**
+ * 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 declare function verifyToken(token: string, connection?: string): Promise<AccessToken | null>;
+/** Whether a verified token grants an ability (`["*"]` grants everything). */
+export declare function tokenAllows(token: AccessToken | null | undefined, ability: string): boolean;
+/** The negation of `tokenAllows`. */
+export declare function tokenDenies(token: AccessToken | null | undefined, ability: string): boolean;
+/** Revoke a single token by its selector (the part before the `.`). */
+export declare function revokeToken(selector: string, connection?: string): Promise<void>;
+/** Revoke every token belonging to an entity — a "log out everywhere" switch. */
+export declare function revokeTokens(tokenableId: string | number, connection?: string): Promise<void>;
+/** List an entity's tokens (metadata only — the secret is never stored). */
+export declare function listTokens(tokenableId: string | number, connection?: string): Promise<AccessToken[]>;

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;