@opendatalabs/vana-sdk 4.4.0 → 4.5.0

package/dist/direct/connect-handler.d.ts

@@ -0,0 +1,246 @@
+/**
+ * One Fetch-API handler for every backend route the connect flow needs.
+ *
+ * @remarks
+ * `createVanaConnectHandler` answers four routes under one base path. The
+ * action is the last path segment, so mount it as a catch-all
+ * (`app/api/vana/[action]/route.ts` in Next.js, or `app.use("/api/vana",
+ * toNodeHandler(handler))` in Express):
+ *
+ * | Route                         | Does                                                 |
+ * | ----------------------------- | ---------------------------------------------------- |
+ * | `GET  config`                 | Sheet config: client id, app name, Account origin.   |
+ * | `POST request`                | Create a request bound to this browser, or re-sign one it already holds. Returns `{ request, embed }`. |
+ * | `GET  status?requestId=`      | Status of a bound request.                           |
+ * | `GET  data?requestId=`        | Read the approved data of a bound request.           |
+ *
+ * Binding: a created request is bound to the browser by an HttpOnly,
+ * `SameSite=Lax` cookie carrying an HMAC-SHA256 tag, keyed by a secret
+ * derived from the app key with HKDF. The handler signs, reports and reads
+ * only requests bound to the calling browser (and, with `session`, to the
+ * app's own signed-in user). See `src/connect/WIRE_CONTRACT.md` for the
+ * wire contract a non-JS backend implements instead.
+ *
+ * What a request asks for is the controller's: its PDPP `grants` (each
+ * stream requested as `pdpp.<source>.<stream>`) and legacy `scopes`. The
+ * browser never chooses; `POST request` reports the scopes it sent.
+ *
+ * Creating a request is rate limited (`rateLimit`; by default in memory,
+ * per client IP and per session, which is not production-grade). In
+ * production, require a signed-in user with `session` and put a shared
+ * limiter in front of `POST request`.
+ *
+ * @category Direct
+ * @module direct/connect-handler
+ */
+import { type DirectDataController } from "./controller.js";
+import type { VanaConnectConfig } from "../connect/http-transports.js";
+export type { VanaConnectConfig };
+/** The create input the handler forwards, minus what it sets itself. */
+export type VanaConnectCreateOptions = Omit<Parameters<DirectDataController["createAccessRequest"]>[0], "returnUrl">;
+/** What a {@link VanaConnectRateLimit} decides. */
+export type VanaConnectRateLimitDecision = {
+    ok: true;
+} | {
+    ok: false;
+    /** Sent as `Retry-After`, in whole seconds. */
+    retryAfterSeconds?: number;
+};
+/**
+ * Decide whether one `POST request` that creates a request may proceed.
+ *
+ * @remarks
+ * Called after the origin and `session` checks and before the controller
+ * creates anything. `session` is the hash of the app's session id when
+ * `session` is configured. Re-signing a request the browser already holds is
+ * not rate limited: it creates nothing and needs a valid binding.
+ */
+export type VanaConnectRateLimit = (input: {
+    request: Request;
+    session?: string;
+}) => VanaConnectRateLimitDecision | Promise<VanaConnectRateLimitDecision>;
+/** Options for {@link createMemoryRateLimit}. */
+export interface MemoryRateLimitOptions {
+    /** Creates allowed per key per window. Defaults to 10. */
+    max?: number;
+    /** Window length in ms. Defaults to 60000. */
+    windowMs?: number;
+    /**
+     * The caller's IP. Defaults to {@link defaultClientIp}, which trusts proxy
+     * headers; behind anything else, supply the address your platform vouches
+     * for.
+     */
+    clientIp?: (request: Request) => string | null;
+    /** Keys kept before the oldest are dropped. Defaults to 10000. */
+    maxKeys?: number;
+    /** Clock in ms. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The caller's IP as the default rate limit sees it.
+ *
+ * @remarks
+ * `CF-Connecting-IP`, then `X-Real-IP`, then the last `X-Forwarded-For`
+ * hop (the one your proxy appended), then the socket address when the
+ * request came through {@link toNodeHandler}. Headers are only as honest as
+ * the proxy in front of you: without one, a client can set them.
+ *
+ * @param request - The incoming request.
+ * @returns An IP string, or `null` when nothing names one.
+ */
+export declare function defaultClientIp(request: Request): string | null;
+/**
+ * An in-memory, fixed-window rate limit per client IP and per session.
+ *
+ * @remarks
+ * The default for `createVanaConnectHandler`. Not production-grade: each
+ * server instance (and each serverless cold start) counts on its own, and
+ * the IP comes from headers a client can forge without a trusted proxy.
+ * In production, require `session` and pass a `rateLimit` backed by a
+ * shared store (Redis, your platform's limiter).
+ *
+ * @param options - Limit, window, IP source and memory bound.
+ * @returns A {@link VanaConnectRateLimit}.
+ */
+export declare function createMemoryRateLimit(options?: MemoryRateLimitOptions): VanaConnectRateLimit;
+/** Options for {@link createVanaConnectHandler}. */
+export interface VanaConnectHandlerOptions {
+    /**
+     * The app's controller; it holds the key and talks to Vana. It must
+     * implement the connect methods (`authorizeRequestRead`, `getEndpoints`,
+     * `getEnv`, and `deriveSecret` unless `bindingSecret` is set), as every
+     * `createDirectDataController` controller does.
+     */
+    controller: DirectDataController;
+    /**
+     * Absolute URL Vana returns the person to after approving in a tab. Its
+     * origin is also the only `Origin` accepted on `POST` (see
+     * {@link VanaConnectHandlerOptions.allowedOrigins}).
+     */
+    returnUrl: string;
+    /**
+     * The embed client id Vana Account registered for this app's origin. Without
+     * it `GET config` reports `clientId: null` and the browser cannot open the
+     * sheet (it falls back to a tab).
+     */
+    clientId?: string;
+    /** Label on the sheet chrome. Defaults to the controller's app name. */
+    appName?: string;
+    /**
+     * Bind requests to the app's own signed-in user too. Return a stable user or
+     * session id, or `null` to refuse with `401`. Only a hash of it is stored.
+     *
+     * @remarks
+     * Recommended for production. Without it, anyone who can load your page
+     * can create requests on your app's behalf; the browser binding only stops
+     * them reading someone else's.
+     */
+    session?: (request: Request) => string | null | Promise<string | null>;
+    /**
+     * Extra create input per request (questions, owner, ...). Called on each
+     * create.
+     */
+    createOptions?: (request: Request) => VanaConnectCreateOptions | Promise<VanaConnectCreateOptions>;
+    /**
+     * Custom read for `GET data`. Defaults to
+     * `controller.readApprovedData({ requestId })`. The result is sent as JSON.
+     */
+    read?: (input: {
+        controller: DirectDataController;
+        requestId: string;
+        request: Request;
+    }) => Promise<unknown>;
+    /**
+     * Origins accepted on `POST`. Defaults to the origin of `returnUrl`. A
+     * request without an `Origin` header (a non-browser client) is accepted.
+     */
+    allowedOrigins?: string[];
+    /**
+     * Secret for the binding cookie. Defaults to a key derived from the app key
+     * with HKDF-SHA256 (`controller.deriveSecret`). Set it to rotate bindings
+     * independently of the app key.
+     */
+    bindingSecret?: string;
+    /**
+     * Rate limit for creating requests. Defaults to
+     * {@link createMemoryRateLimit}() (10 per minute per IP and per session,
+     * in memory, not production-grade). Pass your own shared limiter in
+     * production, or `false` when one already sits in front of this route.
+     * A refusal answers `429 rate_limited` with `Retry-After`.
+     */
+    rateLimit?: VanaConnectRateLimit | false;
+    /** Cookie `Path`. Defaults to `/`. */
+    cookiePath?: string;
+    /** Clock in ms. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** A Fetch-API request handler. */
+export type VanaConnectHandler = (request: Request) => Promise<Response>;
+/** Error codes in a handler error body: `{ error: { code, message } }`. */
+export type VanaConnectErrorCode = "not_found" | "method_not_allowed" | "invalid_request" | "forbidden_origin" | "unauthenticated" | "request_not_bound" | "not_approved" | "scope_not_approved" | "payment_required" | "personal_server_error" | "rate_limited" | "internal_error";
+/** HKDF `info` the default binding key is derived with. */
+export declare const CONNECT_BINDING_KEY_PURPOSE = "vana-sdk/connect/request-binding/v1";
+/** Cookie name binding one request to the browser. */
+export declare function connectBindingCookieName(requestId: string): string;
+/**
+ * Create the connect handler.
+ *
+ * @example
+ * ```typescript
+ * // app/api/vana/[action]/route.ts
+ * import { createVanaConnectHandler } from "@opendatalabs/vana-sdk/server";
+ * // createDirectDataController({ grants: [{ source_id, streams }], ... })
+ * import { vana } from "@/lib/vana";
+ *
+ * const handler = createVanaConnectHandler({
+ *   controller: vana,
+ *   returnUrl: `${process.env.APP_URL}/connect/return`,
+ *   clientId: "my-app",
+ * });
+ * export { handler as GET, handler as POST };
+ * ```
+ *
+ * @param options - Controller, return URL, sheet client id and hooks.
+ * @returns A `(request: Request) => Promise<Response>` handler.
+ * @throws {@link DirectConfigError} when `returnUrl` is not an absolute URL,
+ * or the controller lacks a connect method it needs.
+ */
+export declare function createVanaConnectHandler(options: VanaConnectHandlerOptions): VanaConnectHandler;
+/** The parts of a Node `IncomingMessage` {@link toNodeHandler} reads. */
+export interface NodeRequestLike {
+    method?: string;
+    url?: string;
+    /** Express sets this to the URL before mount-path stripping. */
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** A body already parsed by middleware (Express `json()`), if any. */
+    body?: unknown;
+    socket?: {
+        encrypted?: boolean;
+        remoteAddress?: string;
+    };
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array | string>;
+}
+/** The parts of a Node `ServerResponse` {@link toNodeHandler} writes. */
+export interface NodeResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string | string[]): unknown;
+    end(chunk?: Uint8Array | string): unknown;
+}
+/** Options for {@link toNodeHandler}. */
+export interface ToNodeHandlerOptions {
+    /**
+     * Public origin of the app (`https://app.example`). Defaults to the
+     * request's `Host` header and `X-Forwarded-Proto` (or the socket's TLS).
+     */
+    origin?: string;
+}
+/**
+ * Adapt a Fetch-API handler to Node's `(req, res)` (http, Express, Fastify's
+ * raw mode).
+ *
+ * @param handler - A handler such as {@link createVanaConnectHandler}'s.
+ * @param options - Public origin override.
+ * @returns A `(req, res) => Promise<void>` listener.
+ */
+export declare function toNodeHandler(handler: VanaConnectHandler, options?: ToNodeHandlerOptions): (req: NodeRequestLike, res: NodeResponseLike) => Promise<void>;