@shaferllc/keel 0.59.0 → 0.68.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/storage.d.ts

@@ -9,37 +9,119 @@
  *   const bytes = await storage().get("avatars/1.png");
  *   const url = storage().url("avatars/1.png");
  *
+ * Private files get a temporary URL instead of a public one:
+ *
+ *   await storage().signedUrl("invoices/42.pdf", { expiresIn: 300 });
+ *
+ * and browsers can upload straight to the bucket — the bytes never transit the
+ * app — with a signed upload URL:
+ *
+ *   await storage().signedUploadUrl("uploads/raw.mov", { contentType: "video/quicktime" });
+ *
  * Register several disks by name and select one with `storage("s3")`.
  */
-/** The bridge to a storage backend — implement it once per backend. */
+import type { MiddlewareHandler } from "hono";
+/** Whether an object is world-readable or needs a signed URL. */
+export type FileVisibility = "public" | "private";
+/** Per-write options. Disks map these onto their backend's own metadata. */
+export interface WriteOptions {
+    /**
+     * The object's MIME type. Inferred from the path's extension when omitted, so
+     * a `.png` is stored as `image/png` rather than `application/octet-stream`.
+     */
+    contentType?: string;
+    /** A `Cache-Control` value to store alongside the object. */
+    cacheControl?: string;
+    /** `"public"` or `"private"`. Disks that can't express this ignore it. */
+    visibility?: FileVisibility;
+    /** Arbitrary user metadata stored with the object. */
+    metadata?: Record<string, string>;
+}
+/** What a disk knows about a stored object. */
+export interface FileMetadata {
+    size: number;
+    contentType?: string;
+    cacheControl?: string;
+    visibility?: FileVisibility;
+    lastModified?: Date;
+    metadata?: Record<string, string>;
+}
+export interface SignedFileOptions {
+    /** Seconds the URL stays valid. Default: 3600 (one hour). */
+    expiresIn?: number;
+}
+export interface SignedUploadOptions extends SignedFileOptions {
+    /** The `Content-Type` the uploader must send. */
+    contentType?: string;
+}
+/**
+ * The bridge to a storage backend — implement it once per backend.
+ *
+ * The first six methods are required. The rest are optional capabilities: a disk
+ * that can do better than the generic implementation (native `HEAD`, a
+ * server-side copy, backend presigning) implements them, and `Storage` uses them
+ * when present.
+ */
 export interface Disk {
-    put(path: string, bytes: Uint8Array): Promise<void>;
+    put(path: string, bytes: Uint8Array, options?: WriteOptions): Promise<void>;
     get(path: string): Promise<Uint8Array | null>;
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     /** Paths currently stored, optionally filtered to those under `prefix`. */
     list(prefix?: string): Promise<string[]>;
-    /** A URL for the stored object (public or signed — the disk decides). */
+    /** A public URL for the stored object. */
     url(path: string): string;
+    /** Size, content type, and friends. `Storage.metadata()` falls back to a read. */
+    metadata?(path: string): Promise<FileMetadata | null>;
+    /** A server-side copy. `Storage.copy()` falls back to read-then-write. */
+    copy?(from: string, to: string): Promise<void>;
+    /** A server-side move. `Storage.move()` falls back to copy-then-delete. */
+    move?(from: string, to: string): Promise<void>;
+    /**
+     * A backend-presigned read URL (S3/R2 SigV4, GCS, …). When a disk doesn't
+     * implement this, `Storage.signedUrl()` signs the disk's own `url()` with
+     * `config('app.key')` — serve it with `serveStorage({ signed: true })`.
+     */
+    signedUrl?(path: string, options?: SignedFileOptions): Promise<string>;
+    /**
+     * A backend-presigned upload URL, so a browser can `PUT` straight to the
+     * bucket. There is no generic fallback — only the backend can accept the write.
+     */
+    signedUploadUrl?(path: string, options?: SignedUploadOptions): Promise<string>;
 }
 export type Contents = string | Uint8Array | ArrayBuffer;
+/** The MIME type for a path's extension, or `application/octet-stream`. */
+export declare function contentTypeFor(path: string): string;
+/**
+ * Sign a URL with `config('app.key')`, adding `expires` and `signature` query
+ * params. Verify it with `verifyStorageUrl()`.
+ */
+export declare function signStorageUrl(url: string, expiresIn?: number): Promise<string>;
+/** Whether a URL carries a valid, unexpired signature from `signStorageUrl()`. */
+export declare function verifyStorageUrl(url: string): Promise<boolean>;
 /** An in-memory `Disk` — the default; ideal for tests. Not shared across processes. */
 export declare class MemoryDisk implements Disk {
     private baseUrl;
     private files;
     constructor(baseUrl?: string);
-    put(path: string, bytes: Uint8Array): Promise<void>;
+    put(path: string, bytes: Uint8Array, options?: WriteOptions): Promise<void>;
     get(path: string): Promise<Uint8Array | null>;
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     list(prefix?: string): Promise<string[]>;
     url(path: string): string;
+    metadata(path: string): Promise<FileMetadata | null>;
+    copy(from: string, to: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
 }
 export declare class Storage {
     private disk;
     constructor(disk: Disk);
-    /** Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded). */
-    put(path: string, contents: Contents): Promise<void>;
+    /**
+     * Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded).
+     * The content type is inferred from the extension unless you pass one.
+     */
+    put(path: string, contents: Contents, options?: WriteOptions): Promise<void>;
     /** Read a file's raw bytes, or null if it doesn't exist. */
     get(path: string): Promise<Uint8Array | null>;
     /** Read a file as UTF-8 text, or null if it doesn't exist. */
@@ -47,11 +129,82 @@ export declare class Storage {
     exists(path: string): Promise<boolean>;
     delete(path: string): Promise<void>;
     list(prefix?: string): Promise<string[]>;
+    /** Size, content type, and friends — or null if the file doesn't exist. */
+    metadata(path: string): Promise<FileMetadata | null>;
+    /** A file's size in bytes, or null if it doesn't exist. */
+    size(path: string): Promise<number | null>;
+    /** Copy a file. Server-side when the disk supports it, else read-then-write. */
+    copy(from: string, to: string): Promise<void>;
+    /** Move a file. Server-side when the disk supports it, else copy-then-delete. */
+    move(from: string, to: string): Promise<void>;
+    /** A public URL for the object. Use `signedUrl()` for private ones. */
     url(path: string): string;
+    /**
+     * A temporary URL for a private object. Uses the backend's own presigning when
+     * the disk implements `signedUrl` (S3, R2, GCS); otherwise signs the disk's
+     * `url()` with `config('app.key')` — serve those with `serveStorage({ signed: true })`.
+     */
+    signedUrl(path: string, options?: SignedFileOptions): Promise<string>;
+    /**
+     * A URL the browser can `PUT` the file to directly, so the bytes never transit
+     * your app — the point of this on the edge, where proxying a large upload
+     * through a Worker is exactly what you don't want.
+     *
+     * Only the backend can accept such a write, so this requires a disk that
+     * implements `signedUploadUrl` (see the S3/R2 recipe in the storage guide).
+     */
+    signedUploadUrl(path: string, options?: SignedUploadOptions): Promise<string>;
     /** The underlying driver, for backend-specific operations. */
     get driver(): Disk;
 }
+/**
+ * A `Storage` backed by a `MemoryDisk`, with assertions — what `fakeDisk()`
+ * installs so tests never touch a real bucket.
+ */
+export declare class FakeStorage extends Storage {
+    constructor();
+    assertExists(path: string): Promise<void>;
+    assertMissing(path: string): Promise<void>;
+    /** Assert a file's contents, as UTF-8 text. */
+    assertContents(path: string, expected: string): Promise<void>;
+    /** Assert how many files are stored, optionally under a prefix. */
+    assertCount(expected: number, prefix?: string): Promise<void>;
+}
 /** Register a disk, optionally under a name (default: `"default"`). */
 export declare function setDisk(disk: Disk, name?: string): Storage;
 /** The default disk, or a named one registered with `setDisk(disk, name)`. */
 export declare function storage(name?: string): Storage;
+/**
+ * Swap a disk for an in-memory `FakeStorage` so tests never touch a real bucket,
+ * and assert against what was written. Undo with `restoreDisk()`.
+ *
+ *   const disk = fakeDisk();
+ *   await request.post("/avatars", form);
+ *   await disk.assertExists("avatars/1.png");
+ */
+export declare function fakeDisk(name?: string): FakeStorage;
+/** Restore the real disk after `fakeDisk()`. With no name, restores them all. */
+export declare function restoreDisk(name?: string): void;
+export interface ServeStorageOptions {
+    /** Which registered disk to serve from. Default: `"default"`. */
+    disk?: string;
+    /** URL prefix the files live under. Default: `"/storage"`. */
+    basePath?: string;
+    /**
+     * Require a valid signature from `signedUrl()` — the private-file mode.
+     * Unsigned or expired requests get a 403. Default: false.
+     */
+    signed?: boolean;
+    /** `Cache-Control` max-age in seconds. Omit for no header. */
+    maxAge?: number;
+}
+/**
+ * Serve files from a disk over HTTP — what makes the fallback `signedUrl()` real
+ * for disks without backend presigning (the memory disk, a local-filesystem
+ * disk). Requests that don't match `basePath`, or that name a file the disk
+ * doesn't have, fall through to your routes.
+ *
+ *   this.use(serveStorage());                                  // public files
+ *   this.use(serveStorage({ basePath: "/private", signed: true }));
+ */
+export declare function serveStorage(options?: ServeStorageOptions): MiddlewareHandler;