@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/request.d.ts

@@ -33,6 +33,8 @@ interface ResponseHelper {
     text(body: string, status?: number): Response;
     html(body: string, status?: number): Response;
     redirect(location: string, status?: number): Response;
+    /** Redirect to the `Referer` header, or `fallback` (default "/") if absent. */
+    back(fallback?: string, status?: number): Response;
     /** Send a value — objects become JSON, everything else becomes text. */
     send(data: unknown, status?: number): Response;
     /** Set the response status (chainable). */
@@ -47,6 +49,8 @@ interface ResponseHelper {
     hasHeader(name: string): boolean;
     /** Set the Content-Type (chainable). */
     type(mime: string): ResponseHelper;
+    /** Mark the response as a downloadable attachment via Content-Disposition (chainable). */
+    attachment(filename?: string): ResponseHelper;
     /** Append a value to a (possibly multi-value) header (chainable). */
     append(name: string, value: string): ResponseHelper;
     /** Remove a response header (chainable). */
@@ -74,6 +78,20 @@ export declare const request: {
     readonly method: string;
     readonly path: string;
     readonly url: string;
+    /** The request protocol — "https" or "http" — honoring X-Forwarded-Proto. */
+    readonly protocol: string;
+    /** Whether the request came in over HTTPS. */
+    readonly secure: boolean;
+    /** The host with port, honoring X-Forwarded-Host (e.g. "example.com:443"). */
+    readonly host: string;
+    /** The host without port (e.g. "example.com"). */
+    readonly hostname: string;
+    /** Scheme + host — "https://example.com" — with no trailing slash. */
+    readonly origin: string;
+    /** The absolute request URL, rebuilt from the (proxy-aware) origin. */
+    readonly fullUrl: string;
+    /** The raw query string without the leading "?" (empty when none). */
+    readonly querystring: string;
     /** The response status (useful after `await next()` in middleware). */
     readonly status: number;
     header(name: string): string | undefined;
@@ -128,6 +146,14 @@ export declare const request: {
     language(languages: string[]): string | null;
     /** Accepted languages, ordered by preference. */
     languages(): string[];
+    /** The best of the offered content encodings per Accept-Encoding, or null. */
+    encoding(encodings: string[]): string | null;
+    /** Accepted content encodings, ordered by preference. */
+    encodings(): string[];
+    /** The best of the offered charsets per Accept-Charset, or null. */
+    charset(charsets: string[]): string | null;
+    /** Accepted charsets, ordered by preference. */
+    charsets(): string[];
     /** A single input (from query or body), with an optional fallback (async). */
     input<T = unknown>(key: string, fallback?: T): Promise<T>;
     /** Only the named inputs (async). */

package/dist/core/request.js

@@ -67,6 +67,20 @@ function negotiate(headerName, offered) {
             return a;
     return null;
 }
+/* ------------------------------ url / host ----------------------------- */
+/* Proxy-aware URL introspection: X-Forwarded-* wins over the raw URL, so an
+ * app behind a TLS-terminating proxy sees the client's protocol and host. */
+/** The first value of a (possibly comma-listed) header. */
+function firstForwarded(name) {
+    const v = ctx().req.header(name);
+    return v ? v.split(",")[0].trim() : undefined;
+}
+function requestProtocol() {
+    return firstForwarded("x-forwarded-proto") ?? new URL(ctx().req.url).protocol.replace(/:$/, "");
+}
+function requestHost() {
+    return firstForwarded("x-forwarded-host") ?? ctx().req.header("host") ?? new URL(ctx().req.url).host;
+}
 /* ------------------------------ responses ------------------------------ */
 /* These work inside a handler AND standalone (e.g. as a static route value).
  * Inside a request they build on the context (merging any headers); outside a
@@ -98,6 +112,9 @@ export function html(body, status) {
 }
 export function redirect(location, status) {
     const c = maybeCtx();
+    // Koa-style `redirect("back")`: bounce to the Referer, or "/" if there isn't one.
+    if (location === "back")
+        location = c?.req.header("referer") ?? "/";
     return c
         ? c.redirect(location, status)
         : new Response(null, { status: status ?? 302, headers: { location } });
@@ -115,6 +132,9 @@ export const response = {
     redirect(location, status) {
         return redirect(location, status);
     },
+    back(fallback = "/", status) {
+        return redirect(ctx().req.header("referer") ?? fallback, status);
+    },
     send(data, status) {
         return typeof data === "object" && data !== null
             ? json(data, status)
@@ -143,6 +163,18 @@ export const response = {
         ctx().header("content-type", mime);
         return response;
     },
+    attachment(filename) {
+        if (filename === undefined) {
+            ctx().header("content-disposition", "attachment");
+        }
+        else {
+            // Quote the ASCII-safe name; add RFC 5987 filename* for anything else.
+            const ascii = filename.replace(/[^\x20-\x7e]/g, "?").replace(/["\\]/g, "_");
+            const encoded = encodeURIComponent(filename);
+            ctx().header("content-disposition", `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`);
+        }
+        return response;
+    },
     append(name, value) {
         ctx().header(name, value, { append: true });
         return response;
@@ -189,6 +221,35 @@ export const request = {
     get url() {
         return ctx().req.url;
     },
+    /** The request protocol — "https" or "http" — honoring X-Forwarded-Proto. */
+    get protocol() {
+        return requestProtocol();
+    },
+    /** Whether the request came in over HTTPS. */
+    get secure() {
+        return requestProtocol() === "https";
+    },
+    /** The host with port, honoring X-Forwarded-Host (e.g. "example.com:443"). */
+    get host() {
+        return requestHost();
+    },
+    /** The host without port (e.g. "example.com"). */
+    get hostname() {
+        return requestHost().split(":")[0];
+    },
+    /** Scheme + host — "https://example.com" — with no trailing slash. */
+    get origin() {
+        return `${requestProtocol()}://${requestHost()}`;
+    },
+    /** The absolute request URL, rebuilt from the (proxy-aware) origin. */
+    get fullUrl() {
+        const u = new URL(ctx().req.url);
+        return `${requestProtocol()}://${requestHost()}${u.pathname}${u.search}`;
+    },
+    /** The raw query string without the leading "?" (empty when none). */
+    get querystring() {
+        return new URL(ctx().req.url).search.replace(/^\?/, "");
+    },
     /** The response status (useful after `await next()` in middleware). */
     get status() {
         return ctx().res.status;
@@ -332,6 +393,22 @@ export const request = {
     languages() {
         return parseAccept(ctx().req.header("accept-language"));
     },
+    /** The best of the offered content encodings per Accept-Encoding, or null. */
+    encoding(encodings) {
+        return negotiate("accept-encoding", encodings);
+    },
+    /** Accepted content encodings, ordered by preference. */
+    encodings() {
+        return parseAccept(ctx().req.header("accept-encoding"));
+    },
+    /** The best of the offered charsets per Accept-Charset, or null. */
+    charset(charsets) {
+        return negotiate("accept-charset", charsets);
+    },
+    /** Accepted charsets, ordered by preference. */
+    charsets() {
+        return parseAccept(ctx().req.header("accept-charset"));
+    },
     /** A single input (from query or body), with an optional fallback (async). */
     async input(key, fallback) {
         const all = await this.all();

package/dist/core/shield.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Security headers — the "shield" for server-rendered apps. One middleware that
+ * sets the defensive HTTP headers browsers act on: a Content-Security-Policy,
+ * HSTS, clickjacking and MIME-sniffing guards, and a referrer policy.
+ *
+ *   this.use(securityHeaders());   // sensible defaults
+ *
+ *   this.use(securityHeaders({
+ *     csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+ *     hsts: { maxAge: 15552000, includeSubDomains: true },
+ *     frameGuard: "DENY",
+ *   }));
+ *
+ * Each header can be turned off with `false`. CSP takes a ready-made string or a
+ * directives object whose camelCase keys become `kebab-case` (`defaultSrc` →
+ * `default-src`). Pair with [`csrf()`](./csrf.ts) for form protection.
+ */
+import type { MiddlewareHandler } from "hono";
+export interface HstsOptions {
+    /** Max-age in seconds. Default 180 days. */
+    maxAge?: number;
+    /** Apply to subdomains too. Default true. */
+    includeSubDomains?: boolean;
+    /** Add `preload` (only if you've submitted to the HSTS preload list). Default false. */
+    preload?: boolean;
+}
+export interface SecurityHeadersOptions {
+    /** Content-Security-Policy — a raw string, a directives object, or `false` to omit. */
+    csp?: string | Record<string, string[]> | false;
+    /** Strict-Transport-Security. `true` for defaults, an object to tune, `false` to omit. Default off unless set. */
+    hsts?: boolean | HstsOptions;
+    /** X-Frame-Options clickjacking guard. Default `"SAMEORIGIN"`; `false` to omit. */
+    frameGuard?: false | "DENY" | "SAMEORIGIN";
+    /** X-Content-Type-Options: nosniff. Default true. */
+    noSniff?: boolean;
+    /** Referrer-Policy. Default `"strict-origin-when-cross-origin"`; `false` to omit. */
+    referrerPolicy?: string | false;
+}
+export declare function securityHeaders(options?: SecurityHeadersOptions): MiddlewareHandler;

package/dist/core/shield.js

@@ -0,0 +1,60 @@
+/**
+ * Security headers — the "shield" for server-rendered apps. One middleware that
+ * sets the defensive HTTP headers browsers act on: a Content-Security-Policy,
+ * HSTS, clickjacking and MIME-sniffing guards, and a referrer policy.
+ *
+ *   this.use(securityHeaders());   // sensible defaults
+ *
+ *   this.use(securityHeaders({
+ *     csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+ *     hsts: { maxAge: 15552000, includeSubDomains: true },
+ *     frameGuard: "DENY",
+ *   }));
+ *
+ * Each header can be turned off with `false`. CSP takes a ready-made string or a
+ * directives object whose camelCase keys become `kebab-case` (`defaultSrc` →
+ * `default-src`). Pair with [`csrf()`](./csrf.ts) for form protection.
+ */
+/** camelCase directive names → the kebab-case CSP spelling. */
+function buildCsp(directives) {
+    return Object.entries(directives)
+        .map(([key, values]) => {
+        const name = key.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+        return values.length ? `${name} ${values.join(" ")}` : name;
+    })
+        .join("; ");
+}
+export function securityHeaders(options = {}) {
+    const frame = options.frameGuard === undefined ? "SAMEORIGIN" : options.frameGuard;
+    const referrer = options.referrerPolicy === undefined ? "strict-origin-when-cross-origin" : options.referrerPolicy;
+    const noSniff = options.noSniff !== false;
+    // Precompute the static header values once.
+    const csp = options.csp === false || options.csp === undefined
+        ? null
+        : typeof options.csp === "string"
+            ? options.csp
+            : buildCsp(options.csp);
+    let hstsValue = null;
+    if (options.hsts) {
+        const h = options.hsts === true ? {} : options.hsts;
+        const parts = [`max-age=${h.maxAge ?? 15552000}`];
+        if (h.includeSubDomains !== false)
+            parts.push("includeSubDomains");
+        if (h.preload)
+            parts.push("preload");
+        hstsValue = parts.join("; ");
+    }
+    return async (c, next) => {
+        await next();
+        if (csp)
+            c.header("Content-Security-Policy", csp);
+        if (hstsValue)
+            c.header("Strict-Transport-Security", hstsValue);
+        if (frame)
+            c.header("X-Frame-Options", frame);
+        if (noSniff)
+            c.header("X-Content-Type-Options", "nosniff");
+        if (referrer)
+            c.header("Referrer-Policy", referrer);
+    };
+}

package/dist/core/social.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+/** An OAuth token set returned by the provider's token endpoint. */
+export interface OAuthToken {
+    accessToken: string;
+    tokenType?: string;
+    refreshToken?: string;
+    /** Seconds until the access token expires, if the provider says. */
+    expiresIn?: number;
+    scope?: string;
+    /** The raw token response, for provider-specific fields. */
+    raw: Record<string, unknown>;
+}
+/**
+ * A provider's user, normalized to a common shape across every driver. `Token`
+ * is the OAuth2 `OAuthToken` by default, or an `OAuth1Token` for OAuth 1.0a
+ * providers.
+ */
+export interface SocialUser<Token = OAuthToken> {
+    /** The provider's stable id for this user (always a string). */
+    id: string;
+    email: string | null;
+    name: string | null;
+    /** Username / handle (e.g. GitHub login, Discord username). */
+    nickname: string | null;
+    avatarUrl: string | null;
+    /** The token used to fetch this profile — for calling the provider's API. */
+    token: Token;
+    /** The raw provider profile, for fields not in the normalized shape. */
+    raw: Record<string, unknown>;
+}
+export interface OAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    /** The callback URL registered with the provider. */
+    redirectUri: string;
+    /** Override the provider's default scopes. */
+    scopes?: string[];
+}
+export interface RedirectOptions {
+    /** A CSRF `state` value — generate with `oauthState()`, stash it, verify on callback. */
+    state?: string;
+    /** Scopes for this redirect (overrides config + provider defaults). */
+    scopes?: string[];
+    /** Extra query parameters to add to the authorize URL (e.g. `prompt`, `access_type`). */
+    params?: Record<string, string>;
+}
+/** The provider-specific bits an `OAuthDriver` needs. */
+export interface ProviderSpec {
+    name: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    defaultScopes: string[];
+    /** How scopes are joined in the URL — space for most, comma for a few. */
+    scopeSeparator?: string;
+    /** Fetch and normalize the provider's user for an access token. */
+    fetchUser(token: OAuthToken): Promise<SocialUser>;
+}
+/** Thrown when the token exchange or profile fetch fails. */
+export declare class OAuthError extends Error {
+    readonly provider: string;
+    constructor(message: string, provider: string);
+}
+/** A random, URL-safe `state` for CSRF protection — stash it, then verify on callback. */
+export declare function oauthState(bytes?: number): string;
+/** A generic OAuth 2.0 authorization-code driver. */
+export declare class OAuthDriver {
+    private spec;
+    private config;
+    constructor(spec: ProviderSpec, config: OAuthConfig);
+    /** Build the provider's authorize URL to redirect the user to. */
+    redirect(options?: RedirectOptions): string;
+    /** Exchange an authorization `code` (from the callback) for an access token. */
+    exchangeCode(code: string): Promise<OAuthToken>;
+    /** Fetch the normalized user for an already-obtained access token. */
+    userFromToken(token: OAuthToken): Promise<SocialUser>;
+    /** The full callback step: exchange the `code`, then fetch the user. */
+    user(code: string): Promise<SocialUser>;
+}
+/** Build a driver for any OAuth2 provider from a spec + config. */
+export declare function oauthDriver(spec: ProviderSpec, config: OAuthConfig): OAuthDriver;
+/** GitHub OAuth (`user:email` gives access to a verified primary email). */
+export declare function github(config: OAuthConfig): OAuthDriver;
+/** Google OAuth / OpenID Connect. */
+export declare function google(config: OAuthConfig): OAuthDriver;
+/** Discord OAuth. */
+export declare function discord(config: OAuthConfig): OAuthDriver;
+export interface OAuth1Config {
+    /** Consumer (API) key. */
+    clientId: string;
+    /** Consumer (API) secret. */
+    clientSecret: string;
+    /** The `oauth_callback` URL registered with the provider. */
+    redirectUri: string;
+}
+/** An OAuth 1.0a token pair — both the request token and the final access token. */
+export interface OAuth1Token {
+    token: string;
+    tokenSecret: string;
+    raw: Record<string, string>;
+}
+export interface OAuth1ProviderSpec {
+    name: string;
+    requestTokenUrl: string;
+    authorizeUrl: string;
+    accessTokenUrl: string;
+    fetchUser(token: OAuth1Token, driver: OAuth1Driver): Promise<SocialUser<OAuth1Token>>;
+}
+/**
+ * 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 declare function oauth1Signature(input: {
+    method: string;
+    url: string;
+    params: Record<string, string>;
+    consumerSecret: string;
+    tokenSecret?: string;
+}): Promise<string>;
+/** A generic OAuth 1.0a driver. */
+export declare class OAuth1Driver {
+    private spec;
+    private config;
+    constructor(spec: OAuth1ProviderSpec, config: OAuth1Config);
+    /** Sign a request and build its `Authorization: OAuth …` header. */
+    private authHeader;
+    /** Step 1 — obtain a temporary request token. Stash its `tokenSecret` for the callback. */
+    requestToken(): Promise<OAuth1Token>;
+    /** Step 2 — the URL to send the user to, carrying the request token. */
+    redirect(requestToken: string | OAuth1Token): string;
+    /** Step 3 — swap the callback's `oauth_token` + `oauth_verifier` for an access token. */
+    accessToken(oauthToken: string, verifier: string, requestTokenSecret: string): Promise<OAuth1Token>;
+    /** The full callback step: exchange for an access token, then fetch the user. */
+    user(oauthToken: string, verifier: string, requestTokenSecret: string): Promise<SocialUser<OAuth1Token>>;
+    /** A signed GET against the provider's API on the user's behalf (for `fetchUser`). */
+    get(url: string, token: OAuth1Token): Promise<Record<string, unknown>>;
+}
+/** Build a driver for any OAuth 1.0a provider from a spec + config. */
+export declare function oauth1Driver(spec: OAuth1ProviderSpec, config: OAuth1Config): OAuth1Driver;
+/** Twitter / X (OAuth 1.0a). Enable "Request email" in your app settings for `email`. */
+export declare function twitter(config: OAuth1Config): OAuth1Driver;
+/** All social providers under one namespace: `social.github({...})`, `social.twitter({...})`. */
+export declare const social: {
+    github: typeof github;
+    google: typeof google;
+    discord: typeof discord;
+    driver: typeof oauthDriver;
+    state: typeof oauthState;
+    twitter: typeof twitter;
+    driver1: typeof oauth1Driver;
+};