@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/kiosk/kiosk.plugin.d.ts

@@ -0,0 +1,217 @@
+import type { KioskSettings } from "../access/profile.policy.js";
+import type { AuditLog } from "../audit/audit.log.js";
+import { type PasswordHook } from "../passwords/argon2id.hasher.js";
+import { type AccessKioskDevice, type KioskAdapter } from "./kiosk.store.js";
+import { SESSION_USE } from "./session-use.marker.js";
+export type { AccessKioskDevice };
+/** A session row, as Better Auth's internal adapter answers it. */
+type SessionRow = {
+    readonly token: string;
+    readonly userId: string;
+    readonly createdAt: Date | string;
+    readonly kioskDeviceId?: string | null;
+    readonly kioskSeenAt?: Date | string | null;
+    readonly kioskPin?: boolean | null;
+};
+type UserRow = {
+    readonly id: string;
+    readonly emailVerified?: boolean;
+    readonly [field: string]: unknown;
+};
+type CookieAttributes = {
+    readonly [attribute: string]: unknown;
+};
+/** What the kiosk reads of Better Auth's context. */
+export type KioskAuthContext = {
+    readonly adapter: KioskAdapter;
+    readonly internalAdapter: {
+        findSession(token: string): Promise<{
+            readonly session: SessionRow;
+            readonly user: UserRow;
+        } | null>;
+        createSession(userId: string, dontRememberMe: boolean, override: {
+            readonly [field: string]: unknown;
+        }, overrideAll: boolean): Promise<SessionRow | null>;
+        deleteSession(token: string): Promise<unknown>;
+        deleteSessions(tokens: string[]): Promise<unknown>;
+        updateSession(token: string, data: {
+            readonly [field: string]: unknown;
+        }): Promise<unknown>;
+        findUserById(userId: string): Promise<UserRow | null>;
+    };
+    readonly secret: string;
+    readonly authCookies: {
+        readonly sessionToken: {
+            readonly name: string;
+        };
+    };
+    createAuthCookie(name: string, overrides?: CookieAttributes): {
+        readonly name: string;
+        readonly attributes: CookieAttributes;
+    };
+    readonly sessionConfig: {
+        readonly freshAge: number;
+    };
+    readonly options: {
+        readonly emailAndPassword?: {
+            readonly requireEmailVerification?: unknown;
+        };
+    };
+    readonly logger: {
+        error(message: string): void;
+    };
+    /** What the endpoint answered, for an after hook. */
+    readonly returned?: unknown;
+    /** The headers the answer goes out with, for an after hook. */
+    readonly responseHeaders?: Headers;
+};
+/** A kiosk endpoint's (or a hook's) context, as Better Auth hands it over. */
+type KioskContext = {
+    readonly [SESSION_USE]?: unknown;
+    readonly method?: unknown;
+    readonly body?: unknown;
+    readonly headers?: Headers;
+    readonly request?: unknown;
+    readonly path?: unknown;
+    readonly context: KioskAuthContext;
+    json(value: unknown): unknown;
+    setCookie(name: string, value: string, attributes?: CookieAttributes): unknown;
+    /** A request header, from `headers`, or from `request` when the call passed no `headers`. */
+    getHeader(name: string): string | null;
+    getCookie(name: string): string | null;
+    getSignedCookie(name: string, secret: string): Promise<string | false | null>;
+};
+type KioskHandler = (context: KioskContext) => Promise<unknown>;
+/** Better Auth's `createAuthEndpoint`, as the kiosk calls it. */
+export type KioskEndpointFactory = (path: string, options: {
+    readonly method: "GET" | "POST";
+}, handler: KioskHandler) => unknown;
+/** Better Auth's `createAuthEndpoint.serverOnly`: an endpoint its router never serves. */
+export type KioskServerOnlyFactory = (options: {
+    readonly method: "POST";
+}, handler: KioskHandler) => unknown;
+/** Better Auth's `APIError`, as the kiosk throws it. */
+type Refusal = new (status: string, body?: {
+    readonly message?: string;
+    readonly code?: string;
+}, headers?: {
+    readonly [name: string]: string;
+}) => Error;
+/** What the kiosk takes from Better Auth and from the rest of Access. */
+export type KioskInput = {
+    readonly settings: KioskSettings;
+    readonly endpoint: KioskEndpointFactory;
+    readonly serverOnly: KioskServerOnlyFactory;
+    readonly middleware: (handler: KioskHandler) => unknown;
+    readonly refusal: Refusal;
+    readonly getSessionFromCtx: (context: KioskContext, config?: {
+        readonly disableCookieCache?: boolean;
+    }) => Promise<{
+        readonly session: SessionRow;
+        readonly user: UserRow;
+    } | null>;
+    /**
+     * Better Auth's `getOAuthState`: on a social sign-in's callback, the state it
+     * parsed, whose `serverContext` the OAuth provider fills with an authorization
+     * request to resume (`query`) when the sign-in began with one.
+     */
+    readonly oauthState: () => Promise<{
+        readonly serverContext?: {
+            readonly [key: string]: unknown;
+        };
+    } | null>;
+    readonly cookies: {
+        setSessionCookie(context: KioskContext, session: {
+            readonly session: SessionRow;
+            readonly user: UserRow;
+        }, dontRememberMe: boolean): Promise<void>;
+        deleteSessionCookie(context: KioskContext): void;
+    };
+    /** The PIN hasher: argon2id, at the `passwords` profile. */
+    readonly pins: PasswordHook;
+    /** A user's claims, as their token would carry them: what `canEnrollDevice` is asked with. */
+    readonly claimsFor: (source: {
+        readonly user: UserRow;
+        readonly session: SessionRow;
+    }) => Promise<{
+        readonly [claim: string]: unknown;
+    }>;
+    readonly auditLog: AuditLog | undefined;
+    /**
+     * Whether the app's base URL is https: the device's credential is then a
+     * `__Host-` cookie, `Secure`, on the host alone, whatever Better Auth's cookie
+     * options say.
+     */
+    readonly secureDevice: boolean;
+};
+/**
+ * `access.kiosk`: the operator's API on the kiosk profile, for the app's own server
+ * (no route opens it). A manager's browser reaches the same through the
+ * `listDevices` and `revokeDevice` verbs.
+ */
+export type AccessKiosk = {
+    /** Every enrolled device, oldest first: its id, name, who enrolled it and when, and its last PIN switch. Never a credential. */
+    listDevices(): Promise<readonly AccessKioskDevice[]>;
+    /** Revokes a device, ending every session on it; `false` when there is no such device. */
+    revokeDevice(deviceId: string): Promise<boolean>;
+};
+/** The kiosk's members of the Access plugin: its routes, its hooks and its operator API. */
+export declare const kioskPlugin: (input: KioskInput) => {
+    endpoints: {
+        kioskSwitchUser: unknown;
+        kioskLock: unknown;
+        kioskSetPin: unknown;
+        kioskSetUserPin: unknown;
+        kioskEnrollDevice: unknown;
+        kioskRevokeDevice: unknown;
+        kioskListDevices: unknown;
+    };
+    hooks: {
+        before: ({
+            matcher: (context: {
+                readonly headers?: unknown;
+                readonly request?: unknown;
+            } | undefined) => boolean;
+            handler: unknown;
+        } | {
+            matcher: (context: {
+                readonly body?: unknown;
+            } | undefined) => boolean;
+            handler: unknown;
+        })[];
+        after: {
+            matcher: (context: {
+                readonly path?: unknown;
+            } | undefined) => boolean;
+            handler: unknown;
+        }[];
+    };
+    /**
+     * Before a session is created: one opened on an enrolled device (the request
+     * brings its current credential) is bound to it, whatever signed in, unless the
+     * sign-in carries an authorization request the OAuth provider would resume for
+     * it (refused: a bound session gets no grant). The credential its last rotation
+     * retired, inside the grace, is refused as every kiosk route refuses it (`409
+     * KIOSK_DEVICE_BUSY`); any other retired credential brought back revokes the
+     * device. Either way no session is created.
+     */
+    sessionCreating: (session: {
+        readonly kioskDeviceId?: unknown;
+    } | null | undefined, context: unknown) => Promise<false | {
+        readonly data: object;
+    } | undefined>;
+    /**
+     * A session opened with full credentials (any sign-in but a PIN, and never an
+     * admin's impersonation, which proves nothing of the user) clears its user's
+     * failed PINs on every device.
+     */
+    sessionCreated: (session: {
+        readonly userId?: unknown;
+        readonly impersonatedBy?: unknown;
+    } | null | undefined, context: {
+        readonly path?: unknown;
+        readonly context?: unknown;
+    } | null | undefined) => Promise<void>;
+    /** `access.kiosk`, over Better Auth's context once it is built. */
+    operator: (context: () => Promise<KioskAuthContext>) => AccessKiosk;
+};