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

package/dist/kiosk/kiosk.schema.d.ts

@@ -0,0 +1,176 @@
+/** The models the kiosk profile declares, by Better Auth model name. */
+export declare const KIOSK_DEVICE_MODEL = "accessKioskDevice";
+export declare const KIOSK_PIN_MODEL = "accessKioskPin";
+export declare const KIOSK_LOCKOUT_MODEL = "accessKioskLockout";
+export declare const KIOSK_RETIRED_MODEL = "accessKioskRetiredSecret";
+/** The kiosk profile's tables and its session fields, in Better Auth's plugin schema form. */
+export declare const kioskSchema: {
+    readonly accessKioskDevice: {
+        readonly fields: {
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly secretHash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly previousSecretHash: {
+                readonly type: "string";
+                readonly required: false;
+                readonly index: true;
+            };
+            readonly rotatedAt: {
+                readonly type: "date";
+                readonly required: false;
+            };
+            readonly rotations: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly enrolledBy: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+            };
+            readonly triesBackAt: {
+                readonly type: "number";
+                readonly required: true;
+            };
+        };
+    };
+    readonly accessKioskPin: {
+        readonly fields: {
+            readonly userId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+                readonly references: {
+                    readonly model: "user";
+                    readonly field: "id";
+                    readonly onDelete: "cascade";
+                };
+            };
+            readonly pinHash: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly updatedAt: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+    readonly accessKioskLockout: {
+        readonly fields: {
+            readonly key: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly deviceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessKioskDevice";
+                    readonly field: "id";
+                    readonly onDelete: "cascade";
+                };
+            };
+            readonly userId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly failures: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly lastFailureAt: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+    readonly accessKioskRetiredSecret: {
+        readonly fields: {
+            readonly deviceId: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+                readonly references: {
+                    readonly model: "accessKioskDevice";
+                    readonly field: "id";
+                    readonly onDelete: "cascade";
+                };
+            };
+            readonly secretHash: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly retiredAt: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+    readonly session: {
+        readonly fields: {
+            readonly kioskDeviceId: {
+                readonly type: "string";
+                readonly required: false;
+                readonly input: false;
+                readonly index: true;
+            };
+            readonly kioskSeenAt: {
+                readonly type: "date";
+                readonly required: false;
+                readonly input: false;
+            };
+            readonly kioskPin: {
+                readonly type: "boolean";
+                readonly required: false;
+                readonly input: false;
+            };
+        };
+    };
+};
+/** An enrolled device, as its row holds it. */
+export type KioskDeviceRow = {
+    readonly id: string;
+    readonly name: string;
+    readonly secretHash: string;
+    readonly previousSecretHash?: string | null;
+    readonly rotatedAt?: Date | string | null;
+    readonly rotations: number;
+    readonly enrolledBy: string;
+    readonly createdAt: Date | string;
+    /** When every PIN try the device spent is back, in whole seconds after `createdAt`. */
+    readonly triesBackAt: number;
+};
+/** A user's PIN, as its row holds it. */
+export type KioskPinRow = {
+    readonly id: string;
+    readonly userId: string;
+    readonly pinHash: string;
+};
+/** One user's failed PINs on one device, as its row holds it. */
+export type KioskLockoutRow = {
+    readonly id: string;
+    readonly key: string;
+    readonly failures: number;
+    readonly lastFailureAt: Date | string;
+};
+/** A retired device credential, as its row holds it. */
+export type KioskRetiredRow = {
+    readonly id: string;
+    readonly deviceId: string;
+    readonly secretHash: string;
+    readonly retiredAt: Date | string;
+};

package/dist/kiosk/kiosk.schema.js

@@ -0,0 +1,101 @@
+// The kiosk profile's tables, declared through Better Auth's plugin schema as the
+// registry's and the audit log's are: the Access plugin carries them with
+// `profile: { kind: "kiosk" }`, so Better Auth's own migration (or its CLI's
+// `generate` for an ORM's schema) creates them, and they are stored through whatever
+// database adapter the app gave Better Auth.
+//
+// - `accessKioskDevice`: an enrolled device. Its credential is a random secret the
+//   device holds in an HTTP-only cookie; the table keeps its SHA-256 only, and the
+//   one before it (`previousSecretHash`), whose late answer is refused for a moment
+//   after a rotation; `rotations` counts the rotations. `triesBackAt` is when every
+//   PIN try the device spent is back, in seconds after its enrollment (`createdAt`).
+// - `accessKioskRetiredSecret`: the device's token family, every credential a
+//   rotation retired (its SHA-256, and when): any of them brought back is a copy in
+//   use, and revokes the device. Deleted with its device.
+// - `accessKioskPin`: a user's PIN, as an argon2id PHC string. Deleted with its user.
+// - `accessKioskLockout`: failed PINs in a row for one user id on one device (`key`
+//   is `<deviceId>:<userId>`), whether or not that user holds a PIN. Deleted with its
+//   device.
+// - Better Auth's `session` gains `kioskDeviceId`, the enrolled device a session was
+//   opened on and is bound to (a PIN switch's, or any sign-in's there), `kioskSeenAt`,
+//   when it was last used, and `kioskPin`, `true` for a session a PIN opened. A user
+//   cannot set any of them.
+/** The models the kiosk profile declares, by Better Auth model name. */
+export const KIOSK_DEVICE_MODEL = "accessKioskDevice";
+export const KIOSK_PIN_MODEL = "accessKioskPin";
+export const KIOSK_LOCKOUT_MODEL = "accessKioskLockout";
+export const KIOSK_RETIRED_MODEL = "accessKioskRetiredSecret";
+const optionalDate = { type: "date", required: false };
+/** The kiosk profile's tables and its session fields, in Better Auth's plugin schema form. */
+export const kioskSchema = {
+    [KIOSK_DEVICE_MODEL]: {
+        fields: {
+            name: { type: "string", required: true },
+            secretHash: { type: "string", required: true, unique: true },
+            previousSecretHash: { type: "string", required: false, index: true },
+            rotatedAt: optionalDate,
+            rotations: { type: "number", required: true },
+            enrolledBy: { type: "string", required: true },
+            createdAt: { type: "date", required: true },
+            triesBackAt: { type: "number", required: true },
+        },
+    },
+    [KIOSK_PIN_MODEL]: {
+        fields: {
+            userId: {
+                type: "string",
+                required: true,
+                unique: true,
+                references: { model: "user", field: "id", onDelete: "cascade" },
+            },
+            pinHash: { type: "string", required: true },
+            updatedAt: { type: "date", required: true },
+        },
+    },
+    [KIOSK_LOCKOUT_MODEL]: {
+        fields: {
+            key: { type: "string", required: true, unique: true },
+            deviceId: {
+                type: "string",
+                required: true,
+                index: true,
+                references: {
+                    model: KIOSK_DEVICE_MODEL,
+                    field: "id",
+                    onDelete: "cascade",
+                },
+            },
+            userId: { type: "string", required: true, index: true },
+            failures: { type: "number", required: true },
+            lastFailureAt: { type: "date", required: true },
+        },
+    },
+    [KIOSK_RETIRED_MODEL]: {
+        fields: {
+            deviceId: {
+                type: "string",
+                required: true,
+                index: true,
+                references: {
+                    model: KIOSK_DEVICE_MODEL,
+                    field: "id",
+                    onDelete: "cascade",
+                },
+            },
+            secretHash: { type: "string", required: true, unique: true },
+            retiredAt: { type: "date", required: true },
+        },
+    },
+    session: {
+        fields: {
+            kioskDeviceId: {
+                type: "string",
+                required: false,
+                input: false,
+                index: true,
+            },
+            kioskSeenAt: { type: "date", required: false, input: false },
+            kioskPin: { type: "boolean", required: false, input: false },
+        },
+    },
+};

package/dist/kiosk/kiosk.store.d.ts

@@ -0,0 +1,171 @@
+import { type KioskDeviceRow, type KioskPinRow } from "./kiosk.schema.js";
+/**
+ * How long a device keeps its credential cookie, in seconds: 400 days, the most a
+ * browser keeps one. A retired credential older than this is forgotten at the
+ * device's next rotation: no browser still sends it.
+ */
+export declare const DEVICE_COOKIE_MAX_AGE: number;
+type Where = {
+    readonly field: string;
+    readonly value: unknown;
+    readonly operator?: string;
+};
+/** What the kiosk reads of Better Auth's database adapter. */
+export type KioskAdapter = {
+    create(input: {
+        readonly model: string;
+        readonly data: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<unknown>;
+    findOne(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+    }): Promise<unknown>;
+    findMany(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+        readonly limit?: number;
+        readonly offset?: number;
+        readonly sortBy?: {
+            readonly field: string;
+            readonly direction: "asc";
+        };
+    }): Promise<unknown[]>;
+    update(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+        readonly update: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<unknown>;
+    updateMany(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+        readonly update: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<unknown>;
+    delete(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+    }): Promise<unknown>;
+    deleteMany(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+    }): Promise<unknown>;
+    incrementOne(input: {
+        readonly model: string;
+        readonly where: readonly Where[];
+        readonly increment: {
+            readonly [field: string]: number;
+        };
+        readonly set?: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<unknown>;
+};
+/** What the kiosk reads of Better Auth's sessions. */
+type KioskSessions = {
+    deleteSessions(tokens: string[]): Promise<unknown>;
+};
+/** The device a request's credential names. */
+export type DeviceCheck = 
+/** The device's secret now. */
+{
+    readonly kind: "current";
+    readonly device: KioskDeviceRow;
+}
+/** The secret its last rotation retired, less than {@link ROTATION_GRACE} ago: a request that left before the answer. */
+ | {
+    readonly kind: "stale";
+    readonly device: KioskDeviceRow;
+}
+/** Any other secret of its token family: a copy in use. */
+ | {
+    readonly kind: "reused";
+    readonly device: KioskDeviceRow;
+};
+/** An enrolled device, as the operator's API and the `listDevices` verb show it: never a secret. */
+export type AccessKioskDevice = {
+    readonly id: string;
+    readonly name: string;
+    /** The user who enrolled it. */
+    readonly enrolledBy: string;
+    readonly enrolledAt: Date;
+    /** The last PIN switch on it (its credential's last rotation); `null` before the first. */
+    readonly lastSwitchAt: Date | null;
+};
+/** A refusal for now, with the seconds until a try is let through again. */
+type Held = {
+    readonly retryAfter: number;
+};
+/** Why a user's try on a device is not let through: their backoff, or their PIN disabled there. */
+export type PairHeld = {
+    readonly kind: "wait";
+    readonly retryAfter: number;
+} | {
+    readonly kind: "disabled";
+};
+/** The kiosk's store over Better Auth's adapter and sessions. */
+export declare const kioskStore: (adapter: KioskAdapter, sessions: KioskSessions, now?: () => number) => {
+    /** The device a credential names, read from its hash; `undefined` for none. */
+    check: (secret: unknown) => Promise<DeviceCheck | undefined>;
+    /** Enrolls a device: its row, and the secret it is handed (once). */
+    enroll: (input: {
+        readonly name: string;
+        readonly enrolledBy: string;
+    }) => Promise<{
+        readonly device: KioskDeviceRow;
+        readonly secret: string;
+    }>;
+    /**
+     * Gives the device a new secret, in place of the one it brought; `undefined` when
+     * another request rotated it first (that one's secret is the device's now).
+     */
+    rotate: (from: KioskDeviceRow) => Promise<string | undefined>;
+    /** Revokes a device: every session on it ended, its counts and its row deleted. */
+    revoke: (deviceId: string) => Promise<boolean>;
+    sessionsOn: (deviceId: string) => Promise<string[]>;
+    endSessionsOn: (deviceId: string) => Promise<number>;
+    /** Every enrolled device, oldest first, as a manager sees it. */
+    devices: () => Promise<AccessKioskDevice[]>;
+    /** A user's PIN, as its hash; `undefined` when they have none. */
+    pinOf: (userId: string) => Promise<KioskPinRow | undefined>;
+    /** Sets a user's PIN hash, and clears their failed PINs on every device. */
+    setPin: (userId: string, pinHash: string) => Promise<void>;
+    /**
+     * Replaces a user's PIN hash with the same PIN hashed anew, only while the row
+     * still holds `from` (a compare-and-set): a PIN set meanwhile stays. Their failed
+     * PINs are left as they are.
+     */
+    rehashPin: (userId: string, from: string, pinHash: string) => Promise<void>;
+    /** Clears a user's failed PINs on every device (a full sign-in proves who they are). */
+    clearUser: (userId: string) => Promise<void>;
+    /** Whether a user's next try on a device waits, and why; `undefined` when it may go. */
+    pairHeld: (deviceId: string, userId: string) => Promise<PairHeld | undefined>;
+    /**
+     * Counts a try at a user's PIN on a device, before it is checked; held when
+     * the user's backoff on that device has not passed, or their PIN is disabled
+     * there (counted by another request meanwhile).
+     */
+    reservePair: (deviceId: string, userId: string) => Promise<PairHeld | undefined>;
+    /**
+     * Counts a user's first try on a device since their last right PIN there, and
+     * only that one: `false` when they have a failure there already (counted by
+     * another request meanwhile included). What a held device lets through.
+     */
+    reserveFirstPair: (deviceId: string, userId: string) => Promise<boolean>;
+    /** Clears a user's failed PINs on a device: their PIN matched there. */
+    clearPair: (deviceId: string, userId: string) => Promise<void>;
+    /**
+     * Counts a try on a device, before the PIN is checked; held when the device's
+     * tries are spent ({@link KIOSK_DEVICE_FAILURES}): `max` at once, one back every
+     * `window / max` seconds.
+     */
+    reserveDevice: (deviceId: string) => Promise<Held | undefined>;
+    /** Gives back a try counted on a device: its PIN matched. */
+    releaseDevice: (deviceId: string) => Promise<void>;
+};
+export type KioskStore = ReturnType<typeof kioskStore>;
+export {};