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

package/dist/types/src/ssr/react-router.d.ts

@@ -0,0 +1,53 @@
+import { type AdapterOptions, type RequestSession } from "./adapter.js";
+export interface ReactRouterAuth {
+    /**
+     * For a loader, action or resource route. Returns `{ response }` when the CSRF guard or an
+     * adapter route answers the request: return that response as it is. Otherwise returns `{ session,
+     * headers }`: the resumed session, and a `headers()` function. Call `headers()` when the route
+     * builds its response, as the last step before it returns: it reads the cookies written up to
+     * that call, so a sign-in or sign-out made later in the handler is not in an earlier call's
+     * result. The route returns its data with it, for example `data(value, { headers: headers() })`
+     * or `redirect(url, { headers: headers() })`. The route module must also export
+     * `sessionHeaders` as `headers` (see `sessionHeaders`), or React Router drops the no-cache
+     * headers. So does every route with an `ErrorBoundary` (at least the root route): when a session
+     * route throws the response, React Router takes the headers from the boundary route.
+     */
+    session(request: Request): Promise<{
+        session: RequestSession;
+        headers(): Headers;
+    } | {
+        response: Response;
+    }>;
+}
+/** The arguments React Router passes to a route's `headers` function. */
+export interface RouteHeadersArgs {
+    loaderHeaders: Headers;
+    actionHeaders: Headers;
+    parentHeaders: Headers;
+    errorHeaders?: Headers;
+}
+/**
+ * The `headers` function of a route that uses the session, and of every route with an
+ * `ErrorBoundary` (at least the root route). The route re-exports it:
+ * `export { sessionHeaders as headers } from "@iglo.tech/iglo.base/ssr/react-router";`
+ *
+ * React Router builds the headers of a page and of a `.data` response from the route's `headers`
+ * export. A route without one copies only the Set-Cookie lines of its loader's and action's
+ * headers, so the no-cache headers that `headers()` returns would be lost. This function starts
+ * from the parent headers, as React Router does by default, and adds the no-cache headers when the
+ * loader, the action or the error response carries them. Nothing is kept between calls.
+ *
+ * The error headers are the thrown response's headers, passed to the boundary route only. When a
+ * session route throws `data(…, { headers: headers() })`, the boundary route (the root, in the
+ * default template) renders it and gets those headers as `errorHeaders`, not the session route.
+ * A boundary route without this export drops them. On an anonymous request the error headers carry
+ * no no-store, so the page stays cacheable.
+ */
+export declare function sessionHeaders({ loaderHeaders, actionHeaders, parentHeaders, errorHeaders, }: RouteHeadersArgs): Headers;
+/**
+ * The React Router adapter. The options carry the app's session cache and superuser client, which
+ * it creates once; nothing here keeps state between requests.
+ *
+ * @throws {TypeError} without a superuser client and without `readableCookie: true`
+ */
+export declare function createReactRouterAuth(options: AdapterOptions): ReactRouterAuth;

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

@@ -0,0 +1,25 @@
+import type { SuperuserClient } from "./superuser-client.js";
+import type { CreateServerClientOptions, MintBrowserTokenOptions } from "./types.js";
+export interface BrowserTokenRenewOptions extends Omit<CreateServerClientOptions, "cookies" | "request" | "origin">, MintBrowserTokenOptions {
+    /** Origins besides the request's own that may call the route (see `checkOrigin`). */
+    allowedOrigins?: readonly string[];
+    /** Mints with `impersonate`. Without it the server client must be in fallback mode. */
+    superuser?: SuperuserClient;
+}
+/**
+ * The adapter route that renews a browser token: `POST` from the same origin, with the session
+ * cookie. It resumes the session through `createServerClient` and checks it with iglo.base
+ * (`auth.verify()`): a session revoked since its last check is refused here, though the cache
+ * still holds it. On success it answers `200 { token, record, expiresAt, serverTime }` with a
+ * freshly minted token, and the session cookie is rewritten if the session was refreshed.
+ *
+ * Answers: `401` when there is no valid session (the cookie is cleared when iglo.base revoked it,
+ * or when impersonate answers `404`: the user was deleted after the check, so the session is
+ * over), `403` for a foreign origin, `405` for another method, and `503` when iglo.base cannot be
+ * reached, when the session check fails for another reason, or when impersonate answers `401` or
+ * `403` (the superuser credentials were refused: missing, expired, revoked, or not a superuser's)
+ * or fails for another reason. A `503` keeps the session cookie: the user's session is fine, and
+ * an operator's credential problem must not sign every user out. A missing configuration (no
+ * superuser client and no `readableCookie`) throws before any request to iglo.base is made.
+ */
+export declare function handleBrowserTokenRenew(request: Request, { allowedOrigins, superuser, duration, ...options }: BrowserTokenRenewOptions): Promise<Response>;

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

@@ -0,0 +1,83 @@
+import Client from "../Client.js";
+import { type AuthRecord } from "../stores/BaseAuthStore.js";
+import type { SendOptions } from "../tools/options.js";
+import type { Loose } from "../tools/loose.js";
+import type { CookieAdapter, CompleteOAuth2Result, CreateServerClientOptions, StartOAuth2Options } from "./types.js";
+export declare class ServerClient extends Client {
+    readonly cookies: CookieAdapter;
+    private readonly _cookieName;
+    private readonly _isSecure;
+    private readonly _readable;
+    private readonly _options;
+    private readonly _clock;
+    private _clockOffsetMs;
+    private _initialized;
+    private _applying;
+    private _lastToken;
+    readonly auth: {
+        /** Checks the session with iglo.base now, bypassing the cache. Throws when it is not valid. */
+        verify: () => Promise<AuthRecord>;
+    };
+    constructor(options: CreateServerClientOptions);
+    /** Whether the session cookie is readable by page JavaScript (`readableCookie`, the fallback). */
+    get readableCookie(): boolean;
+    /**
+     * iglo.base's clock in milliseconds, as the last response's `Date` header read it (this
+     * process's clock when no response has said yet).
+     */
+    serverNow(): number;
+    /**
+     * Every request goes through here: `cache: "no-store"` is applied at the fetch layer,
+     * and the server's clock and the collection lifetime are read from each response.
+     */
+    send<T = Loose>(path: string, options: SendOptions): Promise<T>;
+    /** Reads the cookie, then checks or refreshes the session. */
+    init(): Promise<this>;
+    /**
+     * OAuth2 redirect flow, step 1 (docs/design/13-ssr.md, "OAuth2"). Reads the provider's
+     * authorization URL, which carries the server's `state` and PKCE challenge, and stores the
+     * state, the PKCE verifier, the provider and `redirectTo` in the temporary cookie (10 minutes).
+     * Returns the URL with `callbackUrl` as its `redirect_uri`. The caller redirects to it and
+     * applies the adapter's cookies to that response.
+     *
+     * @throws {OAuth2Error} `unknown-provider`, `unsupported-provider` (a POST callback, such as
+     *   Sign in with Apple), `invalid-callback` or `no-cookie-writer`
+     * @throws {ClientResponseError} when iglo.base refuses the auth methods
+     */
+    startOAuth2(provider: string, options: StartOAuth2Options): Promise<string>;
+    /**
+     * OAuth2 redirect flow, step 2: the callback route. Reads `code`, `state` and `error` from the
+     * callback URL and checks `state` against the temporary cookie. On success it exchanges the
+     * code, which writes the session cookie as any sign-in does. The temporary cookie is deleted
+     * on every outcome. Failures are returned, not thrown, with `redirectTo` for the caller.
+     *
+     * @throws only for failures that are not about this sign-in (a network error, a bug)
+     */
+    completeOAuth2(input: string | URL | {
+        url: string;
+    }): Promise<CompleteOAuth2Result>;
+    private _readOAuth2Cookie;
+    private _finishOAuth2;
+    /** The cookie rules of this client's session cookie, for the cookies that follow it. */
+    private _cookieSettings;
+    private _loadCookieAndCheck;
+    private _checkSession;
+    /** One `auth-refresh` for the token. Runs once per flight; see `RefreshOutcome`. */
+    private _requestRefresh;
+    private _applyOutcome;
+    /** Sets the auth store without triggering the listener; optionally writes the cookie. */
+    private _setLocalSession;
+    /** A change made by the app on this client: update the cache and the cookie. */
+    private _saveSession;
+    /** Ends the session on this client: the auth store, the cache entry and the cookie. */
+    private _dropSession;
+    private _applyLocally;
+    private _writeCookie;
+    private _writeCookies;
+    /**
+     * Learns the server's clock from every response, and the collection's token lifetime from
+     * a session response (see `SESSION_RESPONSE_PATH`).
+     */
+    private _observeResponse;
+}
+export declare function createServerClient(options: CreateServerClientOptions): Promise<ServerClient>;

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

@@ -0,0 +1,24 @@
+import Client from "../Client.js";
+import type { RecordModel } from "../tools/dtos.js";
+import type { SendOptions } from "../tools/options.js";
+import type { Loose } from "../tools/loose.js";
+import type { CreateSuperuserClientOptions } from "./types.js";
+export declare class SuperuserClient extends Client {
+    private readonly _options;
+    private readonly _clock;
+    private _clockOffsetMs;
+    constructor(options: CreateSuperuserClientOptions);
+    /** iglo.base's clock in milliseconds, as the last response's `Date` header read it. */
+    serverNow(): number;
+    /**
+     * Overriding send ensures cache: 'no-store' and custom fetch stick
+     * even if application code assigns pb.beforeSend.
+     */
+    send<T = Loose>(path: string, options: SendOptions): Promise<T>;
+    init(): Promise<this>;
+    impersonate(collectionOrRecord: string | RecordModel, recordIdOrDuration?: string | number, duration?: number): Promise<{
+        token: string;
+        record: RecordModel;
+    }>;
+}
+export declare function createSuperuserClient(options: CreateSuperuserClientOptions): Promise<SuperuserClient>;

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

@@ -0,0 +1,44 @@
+import { type BrowserToken, type ServerClient } from "./index.js";
+import { type AdapterOptions } from "./adapter.js";
+export interface SvelteKitCookies {
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+    set(name: string, value: string, options: {
+        path: string;
+        httpOnly?: boolean;
+        sameSite?: boolean | "lax" | "strict" | "none";
+        secure?: boolean;
+        maxAge?: number;
+        expires?: Date;
+        domain?: string;
+    }): void;
+}
+export interface SvelteKitEvent {
+    request: Request;
+    url: URL;
+    cookies: SvelteKitCookies;
+    locals: object;
+}
+export interface SvelteKitAuth {
+    /**
+     * Use as `export const handle = auth.handle` (or inside `sequence()`). Resumes the session, sets
+     * `event.locals.pb` and `event.locals.pbBrowserToken`, answers the adapter routes and the CSRF
+     * guard, then calls `resolve(event)`.
+     */
+    handle(input: {
+        event: SvelteKitEvent;
+        resolve(event: SvelteKitEvent): Promise<Response>;
+    }): Promise<Response>;
+}
+/** What the handle hook puts on `event.locals`; the app declares it in its `App.Locals` type. */
+export interface SvelteKitLocals {
+    pb: ServerClient;
+    pbBrowserToken: () => Promise<BrowserToken | null>;
+}
+/**
+ * Creates the SvelteKit auth. Throws a `TypeError` without a superuser client and without
+ * `readableCookie: true` (see `resolveAdapterOptions`).
+ */
+export declare function createSvelteKitAuth(options: AdapterOptions): SvelteKitAuth;

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

@@ -0,0 +1,118 @@
+import type { SerializeOptions } from "../tools/cookie.js";
+import type { AuthRecord } from "../stores/BaseAuthStore.js";
+import type { RecordAuthResponse } from "../services/RecordService.js";
+import type { ClientResponseError } from "../ClientResponseError.js";
+import type { OAuth2Error } from "./oauth2.js";
+export interface Cookie {
+    name: string;
+    value: string;
+}
+export interface CookieToSet {
+    name: string;
+    value: string;
+    options?: SerializeOptions;
+}
+export type CookieValueMap = Record<string, string>;
+export interface CookieAdapter {
+    getAll: () => Cookie[] | Promise<Cookie[]> | CookieValueMap | Promise<CookieValueMap>;
+    setAll?: (cookies: CookieToSet[], headers?: Record<string, string>) => void | Promise<void>;
+    /**
+     * Whether the app's own request is https (set by adapters that know the request).
+     * The session cookie is `Secure` and `__Host-` prefixed unless this is false.
+     */
+    isSecure?: boolean;
+}
+export interface SessionCacheEntry {
+    record: AuthRecord;
+    checkedAt: number;
+}
+export interface SessionCache {
+    get(token: string): Promise<SessionCacheEntry | undefined>;
+    set(token: string, record: AuthRecord, checkedAt?: number): Promise<void>;
+    delete(token: string): Promise<void>;
+    clear(): void;
+    runSingleFlight<T>(token: string, fn: () => Promise<T>): Promise<T>;
+    readonly size: number;
+    readonly ttl: number;
+    readonly maxEntries: number;
+    clockOffsetMs?: number;
+    getCollectionLifetime(collectionId: string): number | undefined;
+    setCollectionLifetime(collectionId: string, lifetimeSec: number): void;
+}
+export interface SessionCacheOptions {
+    ttl?: number;
+    maxEntries?: number;
+    clock?: () => number;
+}
+export interface CreateServerClientOptions {
+    url: string;
+    cookies: CookieAdapter;
+    cookieName?: string;
+    sessionCache?: SessionCache;
+    secure?: boolean;
+    origin?: string;
+    request?: Request;
+    cookieOptions?: Partial<SerializeOptions>;
+    /**
+     * Fallback without superuser credentials (docs/design/13-ssr.md, "Browser client and realtime"):
+     * the session cookie is written without `HttpOnly`, so the browser client can read it. Weaker
+     * against XSS than the default: any script on the page can read the session token.
+     */
+    readableCookie?: boolean;
+    lang?: string;
+    clock?: () => number;
+    fetch?: (url: RequestInfo | URL, config?: RequestInit) => Promise<Response>;
+}
+/** What a page needs to start a browser client: a short-lived token and the user's record. */
+export interface BrowserToken {
+    token: string;
+    record: AuthRecord;
+    /** When the token expires, in milliseconds since the epoch (from its `exp` claim). */
+    expiresAt: number;
+    /**
+     * The server's clock when the token was minted, in milliseconds since the epoch: iglo.base's
+     * `Date` header as the minting client read it. The browser client measures its own clock
+     * against it, so a device clock that is off does not shorten or stretch the token's life.
+     */
+    serverTime: number;
+}
+export interface MintBrowserTokenOptions {
+    /** Lifetime of the minted token in seconds (default 900, 15 minutes). */
+    duration?: number;
+}
+export interface CreateSuperuserClientOptions {
+    url: string;
+    email?: string;
+    password?: string;
+    token?: string;
+    autoRefreshThreshold?: number;
+    lang?: string;
+    fetch?: (url: RequestInfo | URL, config?: RequestInit) => Promise<Response>;
+    /** The clock (default `Date.now`), for tests. */
+    clock?: () => number;
+}
+export interface RequestCookieAdapter extends CookieAdapter {
+    isSecure: boolean;
+    getAll: () => Cookie[];
+    setAll: (cookiesToSet: CookieToSet[], headers?: Record<string, string>) => void;
+    applyToResponse: (response: Response) => Response;
+    readonly queuedCookies: CookieToSet[];
+    readonly queuedHeaders: Record<string, string>;
+}
+export interface StartOAuth2Options {
+    /** The app's callback URL, as registered with the provider (an absolute http(s) URL). */
+    callbackUrl: string;
+    /** Where the user goes after sign-in: a same-origin path. Anything else becomes `/`. */
+    redirectTo?: string;
+    /** The auth collection (default `users`). */
+    collection?: string;
+}
+export type CompleteOAuth2Result = {
+    ok: true;
+    redirectTo: string;
+    auth: RecordAuthResponse;
+} | {
+    ok: false;
+    redirectTo: string;
+    error: OAuth2Error | ClientResponseError;
+};

package/dist/types/src/stores/AsyncAuthStore.d.ts

@@ -0,0 +1,52 @@
+import { BaseAuthStore, type AuthRecord } from "./BaseAuthStore.js";
+export type AsyncSaveFunc = (serializedPayload: string) => Promise<void>;
+export type AsyncClearFunc = () => Promise<void>;
+/**
+ * AsyncAuthStore is a helper auth store implementation
+ * that could be used with any external async persistent layer
+ * (key-value db, local file, etc.).
+ *
+ * Here is an example with the React Native AsyncStorage package:
+ *
+ * ```
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ * import PocketBase, { AsyncAuthStore } from "pocketbase";
+ *
+ * const store = new AsyncAuthStore({
+ *     save:    async (serialized) => AsyncStorage.setItem("pb_auth", serialized),
+ *     initial: AsyncStorage.getItem("pb_auth"),
+ * });
+ *
+ * const pb = new PocketBase("https://example.com", store)
+ * ```
+ */
+export declare class AsyncAuthStore extends BaseAuthStore {
+    private saveFunc;
+    private clearFunc?;
+    private queue;
+    constructor(config: {
+        save: AsyncSaveFunc;
+        clear?: AsyncClearFunc;
+        initial?: string | Promise<unknown>;
+    });
+    /**
+     * @inheritdoc
+     */
+    save(token: string, record?: AuthRecord): void;
+    /**
+     * @inheritdoc
+     */
+    clear(): void;
+    /**
+     * Initializes the auth store state.
+     */
+    private _loadInitial;
+    /**
+     * Appends an async function to the queue.
+     */
+    private _enqueue;
+    /**
+     * Starts the queue processing.
+     */
+    private _dequeue;
+}

package/dist/types/src/stores/BaseAuthStore.d.ts

@@ -0,0 +1,104 @@
+import { type SerializeOptions } from "../tools/cookie.js";
+import { type RecordModel } from "../tools/dtos.js";
+export type AuthRecord = RecordModel | null;
+export type AuthModel = AuthRecord;
+export type OnStoreChangeFunc = (token: string, record: AuthRecord) => void;
+/**
+ * Base AuthStore class that stores the auth state in runtime memory (aka. only for the duration of the store instane).
+ *
+ * Usually you wouldn't use it directly and instead use the builtin LocalAuthStore, AsyncAuthStore
+ * or extend it with your own custom implementation.
+ */
+export declare class BaseAuthStore {
+    protected baseToken: string;
+    protected baseModel: AuthRecord;
+    private _onChangeCallbacks;
+    /**
+     * Retrieves the stored token (if any).
+     */
+    get token(): string;
+    /**
+     * Retrieves the stored model data (if any).
+     */
+    get record(): AuthRecord;
+    /**
+     * @deprecated use `record` instead.
+     */
+    get model(): AuthRecord;
+    /**
+     * Loosely checks if the store has valid token (aka. existing and unexpired exp claim).
+     */
+    get isValid(): boolean;
+    /**
+     * Loosely checks whether the currently loaded store state is for superuser.
+     *
+     * Alternatively you can also compare directly `pb.authStore.record?.collectionName`.
+     */
+    get isSuperuser(): boolean;
+    /**
+     * @deprecated use `isSuperuser` instead or simply check the record.collectionName property.
+     */
+    get isAdmin(): boolean;
+    /**
+     * @deprecated use `!isSuperuser` instead or simply check the record.collectionName property.
+     */
+    get isAuthRecord(): boolean;
+    /**
+     * Saves the provided new token and model data in the auth store.
+     */
+    save(token: string, record?: AuthRecord): void;
+    /**
+     * Removes the stored token and model data form the auth store.
+     */
+    clear(): void;
+    /**
+     * Parses the provided cookie string and updates the store state
+     * with the cookie's token and model data.
+     *
+     * NB! This function doesn't validate the token or its data.
+     * Usually this isn't a concern if you are interacting only with the
+     * PocketBase API because it has the proper server-side security checks in place,
+     * but if you are using the store `isValid` state for permission controls
+     * in a node server (eg. SSR), then it is recommended to call `authRefresh()`
+     * after loading the cookie to ensure an up-to-date token and model state.
+     * For example:
+     *
+     * ```js
+     * pb.authStore.loadFromCookie("cookie string...");
+     *
+     * try {
+     *     // get an up-to-date auth store state by veryfing and refreshing the loaded auth model (if any)
+     *     pb.authStore.isValid && await pb.collection('users').authRefresh();
+     * } catch {
+     *     // clear the auth store on failed refresh
+     *     pb.authStore.clear();
+     * }
+     * ```
+     */
+    loadFromCookie(cookie: string, key?: string): void;
+    /**
+     * Exports the current store state as cookie string.
+     *
+     * By default the following optional attributes are added:
+     * - Secure
+     * - HttpOnly
+     * - SameSite=Strict
+     * - Path=/
+     * - Expires={the token expiration date}
+     *
+     * NB! If the generated cookie exceeds 4096 bytes, this method will
+     * strip the model data to the bare minimum to try to fit within the
+     * recommended size in https://www.rfc-editor.org/rfc/rfc6265#section-6.1.
+     */
+    exportToCookie(options?: SerializeOptions, key?: string): string;
+    /**
+     * Register a callback function that will be called on store change.
+     *
+     * You can set the `fireImmediately` argument to true in order to invoke
+     * the provided callback right after registration.
+     *
+     * Returns a removal function that you could call to "unsubscribe" from the changes.
+     */
+    onChange(callback: OnStoreChangeFunc, fireImmediately?: boolean): () => void;
+    protected triggerChange(): void;
+}

package/dist/types/src/stores/LocalAuthStore.d.ts

@@ -0,0 +1,48 @@
+import { BaseAuthStore, type AuthRecord } from "./BaseAuthStore.js";
+/**
+ * The default token store for browsers with auto fallback
+ * to runtime/memory if local storage is undefined (e.g. in node env).
+ */
+export declare class LocalAuthStore extends BaseAuthStore {
+    private storageFallback;
+    private storageKey;
+    constructor(storageKey?: string);
+    /**
+     * @inheritdoc
+     */
+    get token(): string;
+    /**
+     * @inheritdoc
+     */
+    get record(): AuthRecord;
+    /**
+     * @deprecated use `record` instead.
+     */
+    get model(): AuthRecord;
+    /**
+     * @inheritdoc
+     */
+    save(token: string, record?: AuthRecord): void;
+    /**
+     * @inheritdoc
+     */
+    clear(): void;
+    /**
+     * Retrieves `key` from the browser's local storage
+     * (or runtime/memory if local storage is undefined).
+     */
+    private _storageGet;
+    /**
+     * Stores a new data in the browser's local storage
+     * (or runtime/memory if local storage is undefined).
+     */
+    private _storageSet;
+    /**
+     * Removes `key` from the browser's local storage and the runtime/memory.
+     */
+    private _storageRemove;
+    /**
+     * Updates the current store state on localStorage change.
+     */
+    private _bindStorageEvent;
+}

package/dist/types/src/tools/cookie.d.ts

@@ -0,0 +1,31 @@
+import type { LooseObject } from "./loose.js";
+export interface ParseOptions {
+    decode?: (val: string) => string;
+}
+/**
+ * Parses the given cookie header string into an object
+ * The object has the various cookies as keys(names) => values
+ */
+export declare function cookieParse(str: string, options?: ParseOptions): LooseObject;
+export interface SerializeOptions {
+    encode?: (val: string | number | boolean) => string;
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    priority?: string;
+    sameSite?: boolean | string;
+}
+/**
+ * Serialize data into a cookie header.
+ *
+ * Serialize the a name value pair into a cookie string suitable for
+ * http headers. An optional options object specified cookie parameters.
+ *
+ * ```js
+ * cookieSerialize('foo', 'bar', { httpOnly: true }) // "foo=bar; httpOnly"
+ * ```
+ */
+export declare function cookieSerialize(name: string, val: string, options?: SerializeOptions): string;