@shaferllc/keel 0.58.0 → 0.59.0

package/dist/core/auth.d.ts

@@ -21,7 +21,11 @@ export declare class Auth {
     login(id: string | number): void;
     /** Log the current user out. */
     logout(): void;
-    /** The authenticated user's id, or null. */
+    /**
+     * The authenticated user's id, or null. A token verified by `bearerAuth()`
+     * wins; otherwise it falls back to the session (set via `login()`). Reads the
+     * request context directly so token-only APIs work without a session store.
+     */
     id(): string | null;
     /** Whether a user is authenticated. */
     check(): boolean;
@@ -34,8 +38,23 @@ export declare class Auth {
 export declare function auth(): Auth;
 /**
  * A guard middleware: rejects unauthenticated requests with a 401, or redirects
- * if `redirectTo` is set.
+ * if `redirectTo` is set. Honors both session logins and a `bearerAuth()` token.
  */
 export declare function authGuard(options?: {
     redirectTo?: string;
 }): MiddlewareHandler;
+/**
+ * Token (API) auth: read a `Bearer` JWT from the `Authorization` header, verify
+ * it, and make its `sub` the authenticated user id — so `auth().user()` resolves
+ * through your registered provider, exactly as with session auth. Issue the
+ * token in your login handler with `jwt.sign({ sub: String(user.id) }, …)`.
+ *
+ *   router.get("/api/me", bearerAuth(), async () => json(await auth().user()));
+ *
+ * Rejects a missing or invalid token with a 401. Pass `{ optional: true }` to
+ * let the request through unauthenticated (e.g. content that varies by login
+ * but doesn't require it) — `auth().check()` is then false downstream.
+ */
+export declare function bearerAuth(options?: {
+    optional?: boolean;
+}): MiddlewareHandler;

package/dist/core/auth.js

@@ -12,6 +12,8 @@
  *   await auth().user();      // the full user (via your provider)
  */
 import { session } from "./session.js";
+import { ctx } from "./request.js";
+import { jwt } from "./crypto.js";
 const KEY = "auth_id";
 let provider;
 /** Tell Keel how to load the authenticated user from its id. */
@@ -27,9 +29,17 @@ export class Auth {
     logout() {
         session().forget(KEY);
     }
-    /** The authenticated user's id, or null. */
+    /**
+     * The authenticated user's id, or null. A token verified by `bearerAuth()`
+     * wins; otherwise it falls back to the session (set via `login()`). Reads the
+     * request context directly so token-only APIs work without a session store.
+     */
     id() {
-        return session().get(KEY, null);
+        const fromToken = ctx().get("auth_id");
+        if (fromToken != null)
+            return String(fromToken);
+        const data = ctx().get("session");
+        return data && data[KEY] != null ? String(data[KEY]) : null;
     }
     /** Whether a user is authenticated. */
     check() {
@@ -56,7 +66,7 @@ export function auth() {
 }
 /**
  * A guard middleware: rejects unauthenticated requests with a 401, or redirects
- * if `redirectTo` is set.
+ * if `redirectTo` is set. Honors both session logins and a `bearerAuth()` token.
  */
 export function authGuard(options = {}) {
     return async (c, next) => {
@@ -68,3 +78,28 @@ export function authGuard(options = {}) {
         await next();
     };
 }
+/**
+ * Token (API) auth: read a `Bearer` JWT from the `Authorization` header, verify
+ * it, and make its `sub` the authenticated user id — so `auth().user()` resolves
+ * through your registered provider, exactly as with session auth. Issue the
+ * token in your login handler with `jwt.sign({ sub: String(user.id) }, …)`.
+ *
+ *   router.get("/api/me", bearerAuth(), async () => json(await auth().user()));
+ *
+ * Rejects a missing or invalid token with a 401. Pass `{ optional: true }` to
+ * let the request through unauthenticated (e.g. content that varies by login
+ * but doesn't require it) — `auth().check()` is then false downstream.
+ */
+export function bearerAuth(options = {}) {
+    return async (c, next) => {
+        const token = c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        const payload = token ? await jwt.verify(token) : null;
+        if (!payload || payload.sub == null) {
+            if (options.optional)
+                return next();
+            return c.json({ error: "Unauthenticated", status: 401 }, 401);
+        }
+        c.set("auth_id", String(payload.sub));
+        await next();
+    };
+}

package/dist/core/crypto.d.ts

@@ -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
  */
 export declare const hash: {
     /** Hash a password (PBKDF2-SHA256 with a random salt). */
@@ -22,3 +25,50 @@ export declare const encryption: {
     /** Decrypt a value; returns null if the payload is tampered or invalid. */
     decrypt<T = unknown>(payload: string): Promise<T | null>;
 };
+/** Standard registered claims, plus whatever custom fields you sign. */
+export interface JwtPayload {
+    /** Subject — conventionally the user id. */
+    sub?: string;
+    /** Issued-at (seconds since the epoch); set automatically by `sign`. */
+    iat?: number;
+    /** Expiry (seconds since the epoch); set from `expiresIn`. */
+    exp?: number;
+    /** Not-before (seconds since the epoch); the token is invalid until then. */
+    nbf?: number;
+    /** Issuer. */
+    iss?: string;
+    /** Audience. */
+    aud?: string;
+    [claim: string]: unknown;
+}
+export interface JwtSignOptions {
+    /** Lifetime — seconds (number) or a duration string like `"30s"`, `"15m"`, `"1h"`, `"7d"`. */
+    expiresIn?: number | string;
+    /** Sets the `iss` claim. */
+    issuer?: string;
+    /** Sets the `aud` claim. */
+    audience?: string;
+    /** Sets the `sub` claim (overrides any `sub` already in the payload). */
+    subject?: string;
+    /** Signing secret; defaults to `config('app.key')`. */
+    secret?: string;
+}
+export interface JwtVerifyOptions {
+    /** Require this `iss`; a token that doesn't match is rejected. */
+    issuer?: string;
+    /** Require this `aud`; a token that doesn't match is rejected. */
+    audience?: string;
+    /** Verifying secret; defaults to `config('app.key')`. */
+    secret?: string;
+}
+export declare const jwt: {
+    /** Sign a payload into an HS256 JWT. Adds `iat`, and `exp` when `expiresIn` is set. */
+    sign(payload: JwtPayload, options?: JwtSignOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    verify<T extends JwtPayload = JwtPayload>(token: string, options?: JwtVerifyOptions): Promise<T | null>;
+};

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 -------------------------- */
@@ -104,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/index.d.ts

@@ -18,7 +18,8 @@ export type { StaticOptions } from "./static.js";
 export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
 export type { Disk, Contents } from "./storage.js";
 export { dump, dd } from "./debug.js";
-export { hash, encryption } from "./crypto.js";
+export { hash, encryption, jwt } from "./crypto.js";
+export type { JwtPayload, JwtSignOptions, JwtVerifyOptions } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
 export type { RateLimiterOptions } from "./rate-limit.js";
 export { db, setConnection, QueryBuilder } from "./database.js";
@@ -62,7 +63,7 @@ export { validate, validateRequest, validated } from "./validation.js";
 export type { Schema, RequestSchemas } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export type { SessionOptions } from "./session.js";
-export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
+export { Auth, auth, authGuard, bearerAuth, setUserProvider } from "./auth.js";
 export type { UserProvider } from "./auth.js";
 export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
 export type { GateCallback, BeforeCallback } from "./authorization.js";

package/dist/core/index.js

@@ -10,7 +10,7 @@ export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
 export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
 export { dump, dd } from "./debug.js";
-export { hash, encryption } from "./crypto.js";
+export { hash, encryption, jwt } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
 export { db, setConnection, QueryBuilder } from "./database.js";
 export { Model } from "./model.js";
@@ -35,7 +35,7 @@ export { TestClient, TestResponse, testClient } from "./testing.js";
 export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
 export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
-export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
+export { Auth, auth, authGuard, bearerAuth, setUserProvider } from "./auth.js";
 export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
 export { Transformer } from "./transformer.js";
 export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",