@shaferllc/keel 0.36.0 → 0.59.0

package/dist/core/crypto.js

@@ -7,6 +7,9 @@
  *
  *   const token = await encryption.encrypt({ userId: 1 });
  *   await encryption.decrypt(token);             // { userId: 1 } | null
+ *
+ *   const token = await jwt.sign({ sub: "42" }, { expiresIn: "1h" });
+ *   await jwt.verify(token);                      // { sub: "42", iat, exp } | null
  */
 import { config } from "./helpers.js";
 /* --------------------------- shared utilities -------------------------- */
@@ -51,13 +54,22 @@ export const hash = {
         const derived = await pbkdf2(password, salt, iterations);
         return `pbkdf2_sha256$${iterations}$${b64(salt)}$${b64(derived)}`;
     },
-    /** Verify a password against a stored hash. */
+    /** Verify a password against a stored hash. Returns false for any malformed hash. */
     async verify(hashed, password) {
         const [algo, iter, salt64, hash64] = hashed.split("$");
         if (algo !== "pbkdf2_sha256" || !iter || !salt64 || !hash64)
             return false;
-        const derived = await pbkdf2(password, fromB64(salt64), Number(iter));
-        return safeEqual(b64(derived), hash64);
+        const iterations = Number(iter);
+        if (!Number.isInteger(iterations) || iterations < 1)
+            return false;
+        try {
+            const derived = await pbkdf2(password, fromB64(salt64), iterations);
+            return safeEqual(b64(derived), hash64);
+        }
+        catch {
+            // Malformed base64 salt/hash, etc. — treat as a non-match, never throw.
+            return false;
+        }
     },
     /** Whether a hash was made with fewer iterations than the current default. */
     needsRehash(hashed, iterations = DEFAULT_ITERATIONS) {
@@ -95,3 +107,84 @@ export const encryption = {
         }
     },
 };
+const DURATION = /^(\d+)\s*(s|m|h|d)$/;
+const UNIT = { s: 1, m: 60, h: 3600, d: 86400 };
+/** Coerce a lifetime to seconds — a bare number passes through; `"1h"` → 3600. */
+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. 30, "30s", "15m", "1h", "7d").`);
+    return Number(match[1]) * UNIT[match[2]];
+}
+/* base64url — JWT segments use the URL-safe alphabet with no padding. */
+function b64url(bytes) {
+    return b64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(str) {
+    const pad = str.length % 4 ? "=".repeat(4 - (str.length % 4)) : "";
+    return fromB64(str.replace(/-/g, "+").replace(/_/g, "/") + pad);
+}
+function b64urlJson(value) {
+    return b64url(new TextEncoder().encode(JSON.stringify(value)));
+}
+/** HMAC-SHA256 the signing input, returned base64url — the JWT signature. */
+async function hmacSha256(data, secret) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+    return b64url(new Uint8Array(sig));
+}
+const JWT_HEADER = b64urlJson({ alg: "HS256", typ: "JWT" });
+export const jwt = {
+    /** Sign a payload into an HS256 JWT. Adds `iat`, and `exp` when `expiresIn` is set. */
+    async sign(payload, options = {}) {
+        const now = Math.floor(Date.now() / 1000);
+        const claims = { ...payload, iat: now };
+        if (options.subject !== undefined)
+            claims.sub = options.subject;
+        if (options.issuer !== undefined)
+            claims.iss = options.issuer;
+        if (options.audience !== undefined)
+            claims.aud = options.audience;
+        if (options.expiresIn !== undefined)
+            claims.exp = now + seconds(options.expiresIn);
+        const body = `${JWT_HEADER}.${b64urlJson(claims)}`;
+        const sig = await hmacSha256(body, options.secret ?? appKey());
+        return `${body}.${sig}`;
+    },
+    /**
+     * Verify an HS256 JWT and return its payload, or `null` if the token is
+     * malformed, tampered, expired, not-yet-valid, or fails an issuer/audience
+     * check. Only HS256 is accepted — `alg: none` and asymmetric algs are refused,
+     * closing the classic JWT algorithm-confusion hole.
+     */
+    async verify(token, options = {}) {
+        try {
+            const parts = token.split(".");
+            if (parts.length !== 3)
+                return null;
+            const [header, body, sig] = parts;
+            const alg = JSON.parse(new TextDecoder().decode(fromB64url(header))).alg;
+            if (alg !== "HS256")
+                return null;
+            const expected = await hmacSha256(`${header}.${body}`, options.secret ?? appKey());
+            if (!safeEqual(sig, expected))
+                return null;
+            const claims = JSON.parse(new TextDecoder().decode(fromB64url(body)));
+            const now = Math.floor(Date.now() / 1000);
+            if (typeof claims.exp === "number" && now >= claims.exp)
+                return null;
+            if (typeof claims.nbf === "number" && now < claims.nbf)
+                return null;
+            if (options.issuer !== undefined && claims.iss !== options.issuer)
+                return null;
+            if (options.audience !== undefined && claims.aud !== options.audience)
+                return null;
+            return claims;
+        }
+        catch {
+            return null;
+        }
+    },
+};

package/dist/core/database.d.ts

@@ -14,10 +14,18 @@ export interface WriteResult {
     rowsAffected: number;
     insertId?: number | string;
 }
+/** A page of results plus pagination metadata, returned by `paginate()`. */
+export interface Paginated<T> {
+    data: T[];
+    total: number;
+    perPage: number;
+    currentPage: number;
+    lastPage: number;
+}
 /** The bridge to your database driver. */
 export interface Connection {
     /** Run a SELECT (or any row-returning query) and return the rows. */
-    select<T = Row>(sql: string, bindings: unknown[]): Promise<T[]>;
+    select(sql: string, bindings: unknown[]): Promise<Row[]>;
     /** Run an INSERT/UPDATE/DELETE and return write metadata. */
     write(sql: string, bindings: unknown[]): Promise<WriteResult>;
 }
@@ -41,7 +49,13 @@ export declare class QueryBuilder<T extends Row = Row> {
     whereIn(column: string, values: unknown[]): this;
     whereNull(column: string): this;
     whereNotNull(column: string): this;
+    whereNotIn(column: string, values: unknown[]): this;
+    whereBetween(column: string, [min, max]: [unknown, unknown]): this;
+    whereLike(column: string, pattern: string): this;
     orderBy(column: string, direction?: "asc" | "desc"): this;
+    /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
+    latest(column?: string): this;
+    oldest(column?: string): this;
     limit(n: number): this;
     offset(n: number): this;
     private whereClause;
@@ -49,6 +63,17 @@ export declare class QueryBuilder<T extends Row = Row> {
     first(): Promise<T | null>;
     count(): Promise<number>;
     exists(): Promise<boolean>;
+    private aggregate;
+    sum(column: string): Promise<number>;
+    avg(column: string): Promise<number>;
+    min(column: string): Promise<number>;
+    max(column: string): Promise<number>;
+    /** The value of a single column from the first matching row (or null). */
+    value<V = unknown>(column: string): Promise<V | null>;
+    /** An array of a single column across all matching rows. */
+    pluck<V = unknown>(column: string): Promise<V[]>;
+    /** A page of results plus pagination metadata. */
+    paginate(page?: number, perPage?: number): Promise<Paginated<T>>;
     insert(data: Row): Promise<WriteResult>;
     insertGetId(data: Row): Promise<number | string | undefined>;
     update(data: Row): Promise<WriteResult>;

package/dist/core/database.js

@@ -65,10 +65,30 @@ export class QueryBuilder {
         this.wheres.push({ boolean: "AND", sql: `${column} IS NOT NULL`, bindings: [] });
         return this;
     }
+    whereNotIn(column, values) {
+        const marks = values.map(() => "?").join(", ");
+        this.wheres.push({ boolean: "AND", sql: `${column} NOT IN (${marks})`, bindings: values });
+        return this;
+    }
+    whereBetween(column, [min, max]) {
+        this.wheres.push({ boolean: "AND", sql: `${column} BETWEEN ? AND ?`, bindings: [min, max] });
+        return this;
+    }
+    whereLike(column, pattern) {
+        this.wheres.push({ boolean: "AND", sql: `${column} LIKE ?`, bindings: [pattern] });
+        return this;
+    }
     orderBy(column, direction = "asc") {
         this.orders.push(`${column} ${direction.toUpperCase()}`);
         return this;
     }
+    /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
+    latest(column = "created_at") {
+        return this.orderBy(column, "desc");
+    }
+    oldest(column = "created_at") {
+        return this.orderBy(column, "asc");
+    }
     limit(n) {
         this._limit = n;
         return this;
@@ -94,7 +114,7 @@ export class QueryBuilder {
             sql += ` LIMIT ${this._limit}`;
         if (this._offset != null)
             sql += ` OFFSET ${this._offset}`;
-        return conn().select(placeholders(sql), where.bindings);
+        return (await conn().select(placeholders(sql), where.bindings));
     }
     async first() {
         this._limit = 1;
@@ -103,12 +123,55 @@ export class QueryBuilder {
     }
     async count() {
         const where = this.whereClause();
-        const rows = await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings);
+        const rows = (await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings));
         return Number(rows[0]?.count ?? 0);
     }
     async exists() {
         return (await this.count()) > 0;
     }
+    async aggregate(fn, column) {
+        const where = this.whereClause();
+        const rows = (await conn().select(placeholders(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${where.sql}`), where.bindings));
+        return Number(rows[0]?.agg ?? 0);
+    }
+    sum(column) {
+        return this.aggregate("SUM", column);
+    }
+    avg(column) {
+        return this.aggregate("AVG", column);
+    }
+    min(column) {
+        return this.aggregate("MIN", column);
+    }
+    max(column) {
+        return this.aggregate("MAX", column);
+    }
+    /** The value of a single column from the first matching row (or null). */
+    async value(column) {
+        this.columns = column;
+        const row = await this.first();
+        return row ? row[column] : null;
+    }
+    /** An array of a single column across all matching rows. */
+    async pluck(column) {
+        this.columns = column;
+        const rows = await this.get();
+        return rows.map((row) => row[column]);
+    }
+    /** A page of results plus pagination metadata. */
+    async paginate(page = 1, perPage = 15) {
+        const total = await this.count();
+        this._limit = perPage;
+        this._offset = (Math.max(1, page) - 1) * perPage;
+        const data = await this.get();
+        return {
+            data,
+            total,
+            perPage,
+            currentPage: page,
+            lastPage: Math.max(1, Math.ceil(total / perPage)),
+        };
+    }
     /* ------------------------------- writes ------------------------------ */
     async insert(data) {
         const keys = Object.keys(data);

package/dist/core/decorators.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Request decorators — attach named, computed values to the current request,
+ * resolved lazily and memoized for the life of that request. Inspired by
+ * Fastify's `decorateRequest`, but without its footguns: you register a resolver
+ * once, and Keel computes it on first access and caches it per request (keyed off
+ * the Hono context via a WeakMap, so there's no shared-state leak between
+ * requests and no V8 shape deopt to design around).
+ *
+ *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+ *
+ *   // anywhere in the request — computed once, then cached:
+ *   const user = await decorated<User>("user");
+ *
+ * (Decorating the *application* is already the service container's job —
+ * `bind` / `singleton` / `instance` / `make`, with `bound()` as `hasDecorator`.)
+ */
+import type { Context } from "hono";
+/** Resolves a decorator's value from the current request context. */
+export type RequestResolver<T = unknown> = (c: Context) => T | Promise<T>;
+/**
+ * Register a request decorator. Throws if `name` is already registered — a
+ * collision guard, like Fastify's.
+ */
+export declare function decorateRequest<T>(name: string, resolver: RequestResolver<T>): void;
+/** Whether a request decorator has been registered. */
+export declare function hasRequestDecorator(name: string): boolean;
+/**
+ * The value of a decorator for the current request — computed on first access
+ * via its resolver, then cached for the rest of the request. Always returns a
+ * promise (resolvers may be async).
+ */
+export declare function decorated<T = unknown>(name: string): Promise<T>;
+/**
+ * Imperatively set a decorator's value for the current request, overriding the
+ * resolver — e.g. from an auth middleware that already resolved the user.
+ */
+export declare function setRequestValue<T>(name: string, value: T): void;
+/** Clear all registered decorators (test helper). */
+export declare function clearRequestDecorators(): void;

package/dist/core/decorators.js

@@ -0,0 +1,72 @@
+/**
+ * Request decorators — attach named, computed values to the current request,
+ * resolved lazily and memoized for the life of that request. Inspired by
+ * Fastify's `decorateRequest`, but without its footguns: you register a resolver
+ * once, and Keel computes it on first access and caches it per request (keyed off
+ * the Hono context via a WeakMap, so there's no shared-state leak between
+ * requests and no V8 shape deopt to design around).
+ *
+ *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+ *
+ *   // anywhere in the request — computed once, then cached:
+ *   const user = await decorated<User>("user");
+ *
+ * (Decorating the *application* is already the service container's job —
+ * `bind` / `singleton` / `instance` / `make`, with `bound()` as `hasDecorator`.)
+ */
+import { ctx } from "./request.js";
+const resolvers = new Map();
+// Per-request memo, keyed by the context object so it's GC'd with the request.
+const memo = new WeakMap();
+function bag(c) {
+    let b = memo.get(c);
+    if (!b) {
+        b = new Map();
+        memo.set(c, b);
+    }
+    return b;
+}
+/**
+ * Register a request decorator. Throws if `name` is already registered — a
+ * collision guard, like Fastify's.
+ */
+export function decorateRequest(name, resolver) {
+    if (resolvers.has(name)) {
+        throw new Error(`Request decorator "${name}" is already registered.`);
+    }
+    resolvers.set(name, resolver);
+}
+/** Whether a request decorator has been registered. */
+export function hasRequestDecorator(name) {
+    return resolvers.has(name);
+}
+/**
+ * The value of a decorator for the current request — computed on first access
+ * via its resolver, then cached for the rest of the request. Always returns a
+ * promise (resolvers may be async).
+ */
+export function decorated(name) {
+    const c = ctx();
+    const b = bag(c);
+    if (b.has(name))
+        return Promise.resolve(b.get(name));
+    const resolver = resolvers.get(name);
+    if (!resolver) {
+        throw new Error(`No request decorator "${name}". Register it with decorateRequest().`);
+    }
+    // Memoize the promise so concurrent access computes once.
+    const result = Promise.resolve(resolver(c));
+    b.set(name, result);
+    return result;
+}
+/**
+ * Imperatively set a decorator's value for the current request, overriding the
+ * resolver — e.g. from an auth middleware that already resolved the user.
+ */
+export function setRequestValue(name, value) {
+    bag(ctx()).set(name, value);
+}
+/** Clear all registered decorators (test helper). */
+export function clearRequestDecorators() {
+    resolvers.clear();
+}

package/dist/core/exceptions.d.ts

@@ -17,19 +17,90 @@ export declare class HttpException extends Error {
     readonly headers?: Record<string, string>;
     /** A machine-readable error code, e.g. "E_VALIDATION". */
     code?: string;
-    constructor(status: number, message?: string, headers?: Record<string, string>);
+    /** Structured context attached to the error; surfaced in the JSON body as `data`. */
+    data?: unknown;
+    constructor(status: number, message?: string, headers?: Record<string, string>, data?: unknown);
+    /**
+     * The error as a plain object, matching the JSON body the HTTP kernel renders:
+     * `{ error, status }` plus `code` and `data` when present. Subclasses that add
+     * fields (e.g. `ValidationException.errors`) override this to include them.
+     */
+    toJSON(): Record<string, unknown>;
 }
-export declare class NotFoundException extends HttpException {
-    constructor(message?: string);
+/** 400 — the request was malformed or failed validation. */
+export declare class BadRequestException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
 export declare class UnauthorizedException extends HttpException {
-    constructor(message?: string);
+    constructor(message?: string, data?: unknown);
+}
+/** 402 — payment is required to access the resource. */
+export declare class PaymentRequiredException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
 export declare class ForbiddenException extends HttpException {
-    constructor(message?: string);
+    constructor(message?: string, data?: unknown);
+}
+export declare class NotFoundException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 405 — the HTTP method isn't allowed for this resource. */
+export declare class MethodNotAllowedException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 406 — no representation matches the request's `Accept` header. */
+export declare class NotAcceptableException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 408 — the client took too long to send the request. */
+export declare class RequestTimeoutException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state (e.g. a duplicate). */
+export declare class ConflictException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 411 — a `Content-Length` header is required and was missing. */
+export declare class LengthRequiredException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
-/** 422 with per-field messages. Pairs with a future validation layer. */
+/** 422 with per-field messages. Pairs with the validation layer. */
 export declare class ValidationException extends HttpException {
     readonly errors: Record<string, string[]>;
     constructor(errors: Record<string, string[]>, message?: string);
+    toJSON(): Record<string, unknown>;
 }
+/** 429 — the client has sent too many requests in a given window. */
+export declare class TooManyRequestsException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 500 — a catch-all server error you want to raise deliberately. */
+export declare class ServerErrorException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 501 — the requested functionality isn't implemented. */
+export declare class NotImplementedException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 502 — an upstream server returned an invalid response. */
+export declare class BadGatewayException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 503 — the service is temporarily unavailable (down, overloaded). */
+export declare class ServiceUnavailableException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/**
+ * Mint a reusable, coded `HttpException` subclass — the ergonomic way to define
+ * app-specific errors with a stable, machine-readable `code`. Inspired by
+ * `@fastify/error`. The `message` may carry `%s` placeholders, filled in order
+ * from the constructor arguments.
+ *
+ *   const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+ *   throw new InsufficientFunds("$40");
+ *   // → 402  { error: "Balance too low: need $40", status: 402, code: "E_FUNDS" }
+ *
+ * The returned class extends `HttpException`, so it renders through the same
+ * path — `code` lands in the JSON body — and passes `instanceof HttpException`.
+ */
+export declare function createError(code: string, message: string, status?: number): new (...args: (string | number)[]) => HttpException;