@iglo.tech/iglo.base 0.0.0-stage → 1.0.1-rc.0

package/dist/types/src/ssr/adapter.d.ts

@@ -0,0 +1,133 @@
+import type { SerializeOptions } from "../tools/cookie.js";
+import { type BrowserToken, type CookieAdapter, type CreateServerClientOptions, type ServerClient, type SessionCache, type SuperuserClient } from "./index.js";
+/** The paths the adapter answers. A route set to `false` is not mounted. */
+export interface AdapterRoutes {
+    /** `POST`: renews the browser token (`handleBrowserTokenRenew`). */
+    renew: string | false;
+    /** `POST` with the JSON body `{ "token": ... }`: completes a popup sign-in (`handlePopupHandOff`). */
+    popup: string | false;
+    /** `GET {oauth2Start}/{provider}`: starts the OAuth2 redirect flow (`startOAuth2`). */
+    oauth2Start: string | false;
+    /** `GET`: the provider's callback, which completes the flow (`completeOAuth2`). */
+    oauth2Callback: string | false;
+}
+export declare const DEFAULT_ROUTES: Readonly<AdapterRoutes>;
+/** The options every adapter takes. The app creates `sessionCache` and `superuser` once. */
+export interface AdapterOptions {
+    /** iglo.base's URL as the app server reaches it. */
+    url: string;
+    /** The session cache, created by the app (`createSessionCache`) and shared by its requests. */
+    sessionCache: SessionCache;
+    /** Mints browser tokens with `impersonate`. Without it, `readableCookie` must be true. */
+    superuser?: SuperuserClient;
+    /**
+     * The app's public origin, such as `https://app.example.com`. It sets the cookie security and
+     * the OAuth2 callback URL. Default: the origin of each request.
+     */
+    origin?: string;
+    /** Overrides the cookie's security (`Secure` and the `__Host-` prefix). */
+    secure?: boolean;
+    /** The session cookie's base name (default `pb_auth`). */
+    cookieName?: string;
+    cookieOptions?: Partial<SerializeOptions>;
+    /** The fallback without superuser credentials: the session cookie is readable by page scripts. */
+    readableCookie?: boolean;
+    /**
+     * The CSRF guard on state-changing requests that carry the session cookie. `false` turns it
+     * off; `allowedOrigins` lists the other origins that may send them.
+     */
+    csrf?: false | {
+        allowedOrigins?: readonly string[];
+    };
+    /** Lifetime of minted browser tokens in seconds (default 900). */
+    browserTokenDuration?: number;
+    routes?: Partial<AdapterRoutes>;
+    lang?: string;
+    clock?: () => number;
+    fetch?: CreateServerClientOptions["fetch"];
+}
+export interface ResolvedAdapterOptions extends AdapterOptions {
+    routes: AdapterRoutes;
+}
+/**
+ * Checks the configuration once, when the app creates its adapter. Without superuser
+ * credentials the adapter can only serve pages in fallback mode, so it must say so here.
+ *
+ * @throws {TypeError} without a superuser client and without `readableCookie: true`
+ */
+export declare function resolveAdapterOptions(options: AdapterOptions): ResolvedAdapterOptions;
+/** The app's public origin: the option, or the origin of the request. */
+export declare function appOrigin(request: Request, options: ResolvedAdapterOptions): string;
+/** The session of one request, resumed from its cookies. */
+export interface RequestSession {
+    /** The server client for this request only. Never shared across requests. */
+    server: ServerClient;
+    /**
+     * Mints the page's browser token for the signed-in user (`null` when nobody is signed in). A token
+     * that is minted marks the request's responses as user data (see `NoStorePolicy`).
+     */
+    browserToken: () => Promise<BrowserToken | null>;
+}
+/**
+ * Whether a request's responses carry user data, and so must not be stored by a cache. The policy
+ * is on when the request carries a session cookie (under either name, as `checkCsrf` counts them),
+ * and turns on the first time the request writes a cookie or mints a browser token. Every response
+ * of an active request gets `SSR_NO_CACHE_HEADERS` (docs/design/13-ssr.md, "Session cookie").
+ * Anonymous requests that write nothing keep their responses cacheable.
+ */
+export interface NoStorePolicy {
+    /** Whether the responses of this request carry the no-cache headers. */
+    readonly active: boolean;
+    /** A cookie was written or a browser token minted: from now on the responses are user data. */
+    markUserData(): void;
+    /**
+     * The response to send: when the policy is active, it carries the no-cache headers. A response
+     * with immutable headers comes back as a copy (see `withMutableHeaders`), so the app sends the
+     * returned response.
+     */
+    apply(response: Response): Response;
+}
+/**
+ * The policy of one request. `onActive` runs once, when the policy turns on: at once when the
+ * request carries a session cookie, otherwise at the first write or mint. For a framework that
+ * sets headers before the handler's response is sent (Nitro) it sets them as they become needed.
+ */
+export declare function noStorePolicy(request: Request, options: ResolvedAdapterOptions, onActive?: () => void): NoStorePolicy;
+/**
+ * Sets SSR_NO_CACHE_HEADERS, replacing any the app set: a user's response must not be stored with
+ * a public `Cache-Control`. The headers must be mutable: see `withMutableHeaders`.
+ */
+export declare function setNoStoreHeaders(headers: Headers): void;
+/**
+ * The response with headers that can be changed. In Node, the runtime the SSR apps run on, the
+ * headers of a `fetch()` response and of `Response.redirect()` are immutable, and so the no-cache
+ * headers could not be set on them. Such a response (an endpoint that returns a fetched response
+ * unchanged, say) is rebuilt with a copy of its headers, body and status. The copy does not keep
+ * `url` or `redirected`, which are read-only. Callers send the response this returns.
+ *
+ * A network error (`Response.error()`, status 0) cannot be copied: `new Response` rejects status 0.
+ * It is returned as it is, and so are its headers.
+ */
+export declare function withMutableHeaders(response: Response): Response;
+/**
+ * Resumes the session of one request with `createServerClient`. `cookies` is the framework's
+ * cookie access, mapped to `{ getAll, setAll, isSecure }`: writes made by the session check
+ * (a refresh, a revoked session) go through its `setAll`. Each write and each minted browser token
+ * turns `policy` on, so the adapter sets the no-cache headers on the response it returns.
+ */
+export declare function resumeSession(cookies: CookieAdapter, request: Request, options: ResolvedAdapterOptions, policy?: NoStorePolicy): Promise<RequestSession>;
+/**
+ * The CSRF guard for a request, before the app's handler runs: `undefined` lets it through, and
+ * a response is the ready 403. It only looks at requests that carry the session cookie, so
+ * the guard never rejects a sign-in form or a public page (see `checkCsrf`).
+ */
+export declare function csrfRejection(request: Request, options: ResolvedAdapterOptions): Response | undefined;
+/** A `302` to `location` that carries the cookies and headers queued by `cookies`. */
+export declare function redirectWithCookies(location: string, cookies: {
+    applyToResponse(r: Response): Response;
+}): Response;
+/**
+ * The adapter's routes. Returns the route's response, or `undefined` when the request is not for
+ * one of them (the app then handles it). The renew and popup routes run their own origin checks.
+ */
+export declare function handleRoute(request: Request, options: ResolvedAdapterOptions): Promise<Response | undefined>;

package/dist/types/src/ssr/astro.d.ts

@@ -0,0 +1,27 @@
+import { type AdapterOptions } from "./adapter.js";
+export interface AstroCookieStore {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: Record<string, unknown>): void;
+    delete(name: string, options?: Record<string, unknown>): void;
+}
+export interface AstroContext {
+    request: Request;
+    url: URL;
+    cookies: AstroCookieStore;
+    locals: object;
+}
+export interface AstroAuth {
+    /**
+     * An Astro middleware (`export const onRequest = auth.onRequest`). Sets `context.locals.pb` and
+     * `context.locals.pbBrowserToken`, answers the adapter routes and the CSRF guard, else returns
+     * `next()`.
+     */
+    onRequest(context: AstroContext, next: () => Promise<Response>): Promise<Response>;
+}
+/**
+ * Creates the Astro auth. Throws a `TypeError` without a superuser client and without
+ * `readableCookie: true` (see `resolveAdapterOptions`).
+ */
+export declare function createAstroAuth(options: AdapterOptions): AstroAuth;

package/dist/types/src/ssr/browser-client.d.ts

@@ -0,0 +1,100 @@
+import Client from "../Client.js";
+import { type AuthRecord } from "../stores/BaseAuthStore.js";
+import type { Loose } from "../tools/loose.js";
+import type { SendOptions } from "../tools/options.js";
+import type { FetchFunction } from "./no-store-fetch.js";
+/** The timers the client uses. Injected by tests, which run without sleeping. */
+export interface BrowserTimers {
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+}
+export interface CreateBrowserClientOptions {
+    url: string;
+    /** The browser token from the page (`mintBrowserToken`). Without it, the readable cookie is read. */
+    token?: string;
+    /** The user record that goes with `token`. Dropped when its id is not the token's. */
+    record?: AuthRecord;
+    /**
+     * The server's clock when `token` was minted (`BrowserToken.serverTime`, in milliseconds). The
+     * client measures its own clock against it. Without it the offset is learned from the first
+     * renewal, so pass it whenever the page has it.
+     */
+    serverTime?: number;
+    /** The adapter route that renews the token (`handleBrowserTokenRenew`). Without it, no renewal. */
+    renewUrl?: string;
+    /** The adapter route that completes a popup sign-in (`handlePopupHandOff`). */
+    handOffUrl?: string;
+    /** The session cookie's base name, for reading the readable cookie (default `pb_auth`). */
+    cookieName?: string;
+    clock?: () => number;
+    timers?: BrowserTimers;
+    fetch?: FetchFunction;
+    lang?: string;
+}
+/**
+ * The SDK client for a page. It holds a short browser token, renews it before it expires,
+ * keeps its realtime subscriptions authorized as the signed-in user changes, and hands a popup
+ * token off to the server. Create it with `createBrowserClient`.
+ */
+export declare class BrowserClient extends Client {
+    private readonly _options;
+    private readonly _clock;
+    private readonly _timers;
+    private _timer;
+    private _retries;
+    private _renewing;
+    private _disposed;
+    private _offsetMs;
+    private _lastRenewedAt;
+    private _realtimeIdentity;
+    constructor(options: CreateBrowserClientOptions);
+    /** Sends with the injected fetch (if any) unless the request names its own. */
+    send<T = Loose>(path: string, options: SendOptions): Promise<T>;
+    /**
+     * Renews the browser token now, through the renew route. Parallel callers, and the timers,
+     * share one request. A 401 clears the auth store. A network error or 5xx keeps the token and
+     * retries with a bounded backoff until it expires.
+     *
+     * @throws {ClientResponseError} when the request fails (status 0 for a network error), or
+     *   when no `renewUrl` is set
+     */
+    renew(): Promise<void>;
+    /**
+     * After `authWithOAuth2()` in a popup: posts the popup's token to the hand-off route, which
+     * writes the HttpOnly session cookie, then renews the token. The long-lived popup token is
+     * replaced in page memory by the short minted one. On any failure the popup token is cleared
+     * from the store rather than kept.
+     *
+     * @throws {ClientResponseError} when the hand-off or the renewal is refused or fails
+     */
+    handOff(): Promise<void>;
+    /** Stops the renewal timers. The client keeps working; it just stops renewing. */
+    dispose(): void;
+    private _postHandOff;
+    private _fetch;
+    /** The current token's expiry in the server's clock, in milliseconds. */
+    private _expiresAt;
+    /** This device's clock, moved onto iglo.base's clock. */
+    private _serverNow;
+    private _authChanged;
+    private _schedule;
+    /**
+     * After a network error or a 5xx: retries with a bounded backoff. Once the retries are used up,
+     * or no further retry fits before the token ends, the store is cleared at the token's expiry.
+     */
+    private _retryLaterIfSame;
+    private _retryLater;
+    private _renewOnce;
+    /**
+     * Sets a timer. A delay above `setTimeout`'s maximum is waited for in steps: the timer is
+     * re-armed when it fires, so no delay is ever cut to 1 ms.
+     */
+    private _setTimer;
+    private _cancelTimer;
+}
+/**
+ * Creates the browser client for a page. Pass the token, its record and `serverTime` from
+ * `mintBrowserToken`, which the page gets at render, and the renew route's URL. Without a token,
+ * the readable session cookie (fallback mode) is read.
+ */
+export declare function createBrowserClient(options: CreateBrowserClientOptions): BrowserClient;

package/dist/types/src/ssr/browser-token.d.ts

@@ -0,0 +1,29 @@
+import type { ServerClient } from "./server-client.js";
+import type { SuperuserClient } from "./superuser-client.js";
+import type { BrowserToken, MintBrowserTokenOptions } from "./types.js";
+/** The lifetime of a browser token when the app does not set one (15 minutes). */
+export declare const DEFAULT_BROWSER_TOKEN_DURATION_SEC = 900;
+/**
+ * What a page needs for its browser client, for the user the server client resumed: a token
+ * from the superuser client's `impersonate` (a non-refreshable one, 15 minutes by default), the
+ * server's clock at minting (`serverTime`), and the server client's validated record. The session
+ * token never leaves the server.
+ *
+ * The result is per-user: the response that carries it must be `Cache-Control: no-store` and
+ * private (`SSR_NO_CACHE_HEADERS`, from `@iglo.tech/iglo.base/ssr`), or a shared cache can hand one user's
+ * token to another. The renew route already answers with those headers.
+ *
+ * Returns `null` when nobody is signed in. Without a superuser client, the server client must
+ * be in fallback mode (`readableCookie`): the page then gets the session token, which the session
+ * cookie already exposes to page JavaScript.
+ *
+ * Errors from `impersonate` reach the caller as `ClientResponseError`, with the server's status.
+ * They mean different things, and the caller decides what each means for the session
+ * (`handleBrowserTokenRenew` does): `404` means the user is gone, while `401` (the superuser token
+ * is missing, expired or revoked) and `403` (it is not a superuser's) mean the superuser
+ * credentials were refused, which says nothing about the user's session.
+ *
+ * @throws {TypeError} without a superuser client on a server client that is not in fallback mode
+ * @throws {ClientResponseError} when `impersonate` fails (see above)
+ */
+export declare function mintBrowserToken(server: ServerClient, superuser: SuperuserClient | undefined, options?: MintBrowserTokenOptions): Promise<BrowserToken | null>;

package/dist/types/src/ssr/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/ssr/cache.d.ts

@@ -0,0 +1,9 @@
+import type { SessionCache, SessionCacheOptions } from "./types.js";
+export declare const DEFAULT_TTL_MS: number;
+export declare const DEFAULT_MAX_ENTRIES = 10000;
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Creates the per-process session cache. Pass one instance to every `createServerClient`
+ * of the process; it is never a module global.
+ */
+export declare function createSessionCache(options?: SessionCacheOptions): SessionCache;

package/dist/types/src/ssr/cookies.d.ts

@@ -0,0 +1,68 @@
+import { type AuthRecord } from "../stores/BaseAuthStore.js";
+import { type SerializeOptions } from "../tools/cookie.js";
+import type { Cookie, CookieToSet, CookieValueMap, RequestCookieAdapter } from "./types.js";
+export declare const SSR_NO_CACHE_HEADERS: Readonly<Record<string, string>>;
+export declare const DEFAULT_COOKIE_KEY = "pb_auth";
+/** The temporary cookie of the OAuth2 redirect flow (docs/design/13-ssr.md, "OAuth2"). */
+export declare const OAUTH2_COOKIE_KEY = "pb_oauth2";
+export declare const OAUTH2_COOKIE_MAX_AGE_SEC = 600;
+export declare function isLocalhost(hostname: string): boolean;
+export declare function isHttpLocalUrl(urlStr: string): boolean;
+export declare function normalizeCookies(raw: Cookie[] | CookieValueMap | undefined | null): Cookie[];
+/** The name a cookie is written under: `__Host-` prefixed on secure origins, plain otherwise. */
+export declare function cookieWireName(baseName: string, secure: boolean): string;
+/**
+ * The cookie the SDK reads, by the one name it is written under for `secure` (see
+ * `cookieWireName`). On a secure origin the plain name is never read: a sibling subdomain can set
+ * a cookie for the parent domain under any name, but only the host itself can set a `__Host-` one.
+ */
+export declare function findCookie(cookies: Cookie[], baseName: string, secure: boolean): Cookie | undefined;
+/**
+ * Whether a session cookie is present under either name. The CSRF guard does not know how the
+ * app named its cookie (`secure` may come from the app's settings), so both names count: the
+ * guard checks more requests, never fewer. Reading a value is still `findCookie`'s job.
+ */
+export declare function hasSessionCookieName(cookies: Cookie[], baseName: string): boolean;
+/**
+ * The record that belongs to a token, or null: a record for another user is dropped, since a
+ * cookie can be edited by its user. Shared by the server and the browser client.
+ */
+export declare function recordForToken(token: string, record: AuthRecord): AuthRecord;
+export declare function safeDecode(value: string): string;
+/**
+ * Reads the token and user record from a session cookie value. Adapters may hand over
+ * the value decoded (the request adapter does) or as sent by the browser (Next.js does),
+ * so the raw text is tried first and the percent-decoded text second, each decoded once.
+ */
+export declare function parseSessionValue(raw: string): {
+    token: string;
+    record: AuthRecord;
+} | undefined;
+export declare function formatSessionCookieValue(wireName: string, token: string, record: AuthRecord, options?: SerializeOptions): string;
+export interface CookieSettings {
+    cookieName?: string;
+    secure?: boolean;
+    cookieOptions?: Partial<SerializeOptions>;
+    /** Fallback mode: the session cookie is written without `HttpOnly` (docs/design/13-ssr.md). */
+    readable?: boolean;
+}
+/** `cookieOptions.secure` overrides the flag; the default is secure (`__Host-`). */
+export declare function isSecureSession(settings: CookieSettings): boolean;
+export declare function buildSessionCookieToSet(token: string, record: AuthRecord, options: CookieSettings & {
+    nowSeconds?: number;
+    exp?: number;
+}): CookieToSet;
+/** Expiring cookies for a session end. */
+export declare function buildClearedSessionCookies(settings: CookieSettings): CookieToSet[];
+/**
+ * The temporary OAuth2 cookie: HttpOnly, `SameSite=Lax` (the provider's redirect is a top-level
+ * GET), `Path=/`, `Max-Age` 600 and the same `Secure`/`__Host-` rule as the session cookie.
+ * The app's `cookieOptions` are not applied (apart from `secure`), so an app cannot make the
+ * cookie unreachable from the provider's redirect.
+ */
+export declare function buildOAuth2CookieToSet(value: string, settings: CookieSettings): CookieToSet;
+/** Expiring cookies for the temporary OAuth2 cookie, written with the same name rule. */
+export declare function buildClearedOAuth2Cookies(settings: CookieSettings): CookieToSet[];
+export declare function createRequestCookieAdapter(request: Request, options?: {
+    secure?: boolean;
+}): RequestCookieAdapter;

package/dist/types/src/ssr/csrf.d.ts

@@ -0,0 +1,38 @@
+export interface CsrfOptions {
+    /**
+     * Origins besides the request's own that may send state-changing requests, for example
+     * `https://www.example.com` when the app is served under two origins. Each entry must be an
+     * origin: a scheme, a host and an optional port, with no path.
+     */
+    allowedOrigins?: readonly string[];
+    /** The session cookie's base name (default `pb_auth`). */
+    cookieName?: string;
+}
+export type OriginCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "missing-origin" | "foreign-origin";
+};
+export type CsrfResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "missing-origin" | "foreign-origin";
+    response: Response;
+};
+/**
+ * Whether the request comes from its own origin or an allowed one. `Origin` decides; `Referer`
+ * is read only when `Origin` is absent. A request with neither, or with an `Origin` the browser
+ * sent as `null`, is rejected. The request's own origin comes from its URL: behind a proxy that
+ * changes the public origin, list the public origin in `allowedOrigins`.
+ */
+export declare function checkOrigin(request: Request, allowedOrigins?: readonly string[]): OriginCheck;
+/**
+ * The CSRF guard for an adapter's request handler, called before the handler runs. It rejects
+ * `POST`, `PUT`, `PATCH` and `DELETE` requests that carry the session cookie unless their origin
+ * passes `checkOrigin`. Requests without the session cookie (under either name), and `GET`, `HEAD`
+ * and `OPTIONS`, pass. A rejection carries a ready 403 `Response`. Frameworks with their own check
+ * (Next.js Server Actions) may skip this.
+ */
+export declare function checkCsrf(request: Request, options?: CsrfOptions): CsrfResult;

package/dist/types/src/ssr/index.d.ts

@@ -0,0 +1,12 @@
+export { ServerClient, createServerClient } from "./server-client.js";
+export { SuperuserClient, createSuperuserClient } from "./superuser-client.js";
+export { createSessionCache, DEFAULT_TTL_MS, DEFAULT_MAX_ENTRIES } from "./cache.js";
+export { createRequestCookieAdapter, SSR_NO_CACHE_HEADERS, DEFAULT_COOKIE_KEY, } from "./cookies.js";
+export { OAuth2Error, type OAuth2ErrorKind } from "./oauth2.js";
+export { checkCsrf, checkOrigin } from "./csrf.js";
+export { handlePopupHandOff } from "./popup.js";
+export { mintBrowserToken, DEFAULT_BROWSER_TOKEN_DURATION_SEC } from "./browser-token.js";
+export { handleBrowserTokenRenew, type BrowserTokenRenewOptions } from "./renew.js";
+export type { Cookie, CookieToSet, CookieAdapter, SessionCache, SessionCacheEntry, SessionCacheOptions, CreateServerClientOptions, CreateSuperuserClientOptions, RequestCookieAdapter, StartOAuth2Options, CompleteOAuth2Result, BrowserToken, MintBrowserTokenOptions, } from "./types.js";
+export type { CsrfOptions, CsrfResult, OriginCheck } from "./csrf.js";
+export type { PopupHandOffOptions } from "./popup.js";

package/dist/types/src/ssr/next.d.ts

@@ -0,0 +1,53 @@
+import { type AdapterOptions, type RequestSession } from "./adapter.js";
+import type { SerializeOptions } from "../tools/cookie.js";
+/**
+ * What `cookies()` from `next/headers` returns, typed structurally. Values are the raw text the
+ * browser sent. `set` is missing from the read-only store type, and it throws at runtime inside
+ * Server Components; the adapter swallows that and keeps the refreshed session in memory.
+ */
+export interface NextCookieStore {
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+    set?(name: string, value: string, options?: SerializeOptions): unknown;
+}
+export interface NextAuthOptions extends AdapterOptions {
+    /** NextResponse.next, supplied by the app: `next: (init) => NextResponse.next(init)`. The adapter cannot import next/server. */
+    next: (init: {
+        request: {
+            headers: Headers;
+        };
+    }) => Response;
+}
+export interface NextAuth {
+    /**
+     * middleware.ts: answers the CSRF guard and the adapter routes, and otherwise resumes the session.
+     * The pass-through response gets the cookies the session wrote, and the request it forwards gets
+     * the same cookies in its `Cookie` header, so Server Components read the refreshed session.
+     */
+    middleware(request: Request): Promise<Response>;
+    /**
+     * Server Components, route handlers and server actions: resumes the session from the cookie
+     * store the middleware prepared. Cookie writes are attempted and swallowed (a read-only store
+     * throws); a refresh made here updates memory only.
+     */
+    serverSession(input: {
+        cookies: NextCookieStore;
+        headers?: {
+            get(name: string): string | null;
+        };
+    }): Promise<RequestSession>;
+}
+/**
+ * The Next.js App Router adapter. The options carry the app's session cache and superuser client,
+ * which it creates once; nothing here keeps state between requests.
+ *
+ * It runs on the Node.js runtime only: Next.js 16 `proxy.ts` always does, and Next.js 15.5
+ * `middleware.ts` does with `export const runtime = "nodejs"`. The Edge runtime is not supported.
+ * On Edge the package's browser condition resolves to a stub, so the import fails at build time
+ * or the app answers every request with the stub's error (docs/design/13-ssr.md, "Runtime").
+ *
+ * @throws {TypeError} without a superuser client and without `readableCookie: true`
+ */
+export declare function createNextAuth(options: NextAuthOptions): NextAuth;

package/dist/types/src/ssr/no-store-fetch.d.ts

@@ -0,0 +1,7 @@
+export type FetchFunction = (url: RequestInfo | URL, config?: RequestInit) => Promise<Response>;
+/**
+ * Wraps the fetch that sends a server client's requests. It runs after `beforeSend`, so an
+ * app that replaces the send options cannot drop `cache: "no-store"` (Next.js would cache
+ * the response in its data cache otherwise).
+ */
+export declare function noStoreFetch(inner: FetchFunction | undefined, onResponse?: (response: Response) => void): FetchFunction;

package/dist/types/src/ssr/nuxt.d.ts

@@ -0,0 +1,41 @@
+import { type AdapterOptions } from "./adapter.js";
+/** The options of a cookie write, in the shape h3's `setCookie` takes. */
+export interface NuxtCookieOptions {
+    path: string;
+    httpOnly?: boolean;
+    sameSite?: boolean | "lax" | "strict" | "none";
+    secure?: boolean;
+    maxAge?: number;
+    expires?: Date;
+    domain?: string;
+}
+/** The parts of Nitro's event the middleware uses (see the file header for the mapping). */
+export interface NuxtEvent {
+    /** The request method. */
+    method: string;
+    /** The request target: the path and query, as h3's `event.path` has them. */
+    path: string;
+    /** The request headers, as Node has them (`event.node.req.headers`). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Nitro's per-request context: the middleware sets `pb` and `pbBrowserToken` on it. */
+    context: Record<string, unknown>;
+    /** Reads the request body as JSON. Only the popup route calls it. */
+    readBody?: () => Promise<unknown>;
+    /** Writes a cookie on the response (h3's `setCookie`). */
+    setCookie(name: string, value: string, options: NuxtCookieOptions): void;
+    /** Sets a header on the response (h3's `setResponseHeader`). */
+    setHeader(name: string, value: string): void;
+}
+export interface NuxtAuth {
+    /**
+     * A Nitro server middleware: sets `event.context.pb` and `event.context.pbBrowserToken`, answers
+     * the adapter routes and the CSRF guard, else lets the request continue. Returns a `Response`
+     * to answer the request, or `undefined` to continue.
+     */
+    middleware(event: NuxtEvent): Promise<Response | undefined>;
+}
+/**
+ * Creates the Nuxt auth. Throws a `TypeError` without a superuser client and without
+ * `readableCookie: true` (see `resolveAdapterOptions`).
+ */
+export declare function createNuxtAuth(options: AdapterOptions): NuxtAuth;

package/dist/types/src/ssr/oauth2.d.ts

@@ -0,0 +1,56 @@
+/** The temporary cookie's lifetime, as its `Max-Age` (see `buildOAuth2CookieToSet`). */
+export declare const OAUTH2_STATE_TTL_MS: number;
+export declare const DEFAULT_OAUTH2_COLLECTION = "users";
+export type OAuth2ErrorKind = "invalid-callback" | "unknown-provider" | "unsupported-provider" | "no-cookie-writer" | "missing-cookie" | "expired" | "state-mismatch" | "provider-error" | "missing-code";
+/**
+ * A failure of the OAuth2 redirect flow that the SDK detects itself. A failure the server
+ * reports is its `ClientResponseError`, unchanged.
+ */
+export declare class OAuth2Error extends Error {
+    readonly kind: OAuth2ErrorKind;
+    /** The provider's `error` parameter (`provider-error` only). */
+    readonly providerError?: string;
+    constructor(kind: OAuth2ErrorKind, message: string, providerError?: string);
+}
+/** What the temporary cookie carries from `startOAuth2` to `completeOAuth2`. */
+export interface OAuth2Pending {
+    state: string;
+    codeVerifier: string;
+    provider: string;
+    collection: string;
+    /** The callback URL sent to the provider; the server must get the same one. */
+    redirectURL: string;
+    redirectTo: string;
+    /** Expiry, in epoch milliseconds. */
+    exp: number;
+}
+/**
+ * A same-origin path for `redirectTo`, or `/`. Only a path that starts with one slash is kept:
+ * no `//host`, no backslash (browsers read `/\host` as `//host`), no control characters, no
+ * scheme, and nothing that resolves to another origin.
+ */
+export declare function safeRedirectPath(value: unknown): string;
+/** Equal strings compare in time that depends only on their length (the state is public). */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * The callback URL the provider redirects to. It is registered with the provider, so it must
+ * be an absolute http(s) URL; a query or fragment would not match the registration.
+ */
+export declare function validateCallbackUrl(callbackUrl: string): string;
+/**
+ * Reads the temporary cookie's value. Adapters may hand it over decoded or as the browser sent
+ * it, so the raw text is tried first and the percent-decoded text second (as the session cookie).
+ * Anything malformed is `undefined`, which the caller treats as a missing cookie.
+ */
+export declare function parseOAuth2Cookie(raw: string): OAuth2Pending | undefined;
+/** The provider's authorization URL with the callback as its `redirect_uri`. */
+export declare function withRedirectUri(authURL: string, callbackUrl: string): string;
+/**
+ * Whether the provider returns to the callback as a GET with `code`, `state` and `error` in the
+ * query string. Upstream asks Apple for `response_mode=form_post`, so Apple returns with a
+ * cross-site POST whose form body this flow does not read, and whose `SameSite=Lax` cookie the
+ * browser does not send. Only `response_mode=query`, or no `response_mode`, passes; any other
+ * mode is refused. The URL may be relative: upstream returns `?client_id=...` for a provider with
+ * no authorization endpoint, and the caller appends `redirect_uri` to it.
+ */
+export declare function returnsToQueryString(authURL: string): boolean;

package/dist/types/src/ssr/popup.d.ts

@@ -0,0 +1,14 @@
+import type { CreateServerClientOptions } from "./types.js";
+export interface PopupHandOffOptions extends Omit<CreateServerClientOptions, "cookies" | "request" | "origin"> {
+    /** Origins besides the request's own that may post the token (see `checkOrigin`). */
+    allowedOrigins?: readonly string[];
+}
+/**
+ * The adapter route that completes a popup sign-in. It accepts `POST` with the JSON body
+ * `{ "token": "..." }` from the same origin (always checked, with or without a session cookie),
+ * and checks the token with one `auth-refresh`. On success the HttpOnly session cookie is written
+ * from the refreshed token and record, and the response carries the record only: the token stays
+ * in the cookie. The posted token is the only input trusted; nothing else the browser sends is.
+ * A revoked token gets 401 and sets no cookie.
+ */
+export declare function handlePopupHandOff(request: Request, { allowedOrigins, ...options }: PopupHandOffOptions): Promise<Response>;