@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/auth/local/index.d.ts

@@ -0,0 +1,285 @@
+import { type SQLWrapper } from 'drizzle-orm';
+import { type AssignedResolver, type AuthStrategy, type LocalAuthPermissions } from '../../asas/actor.ts';
+import type { ResolvedKayan } from '../../mithaq/types.ts';
+import { neverRead, type DerivedShapes, type WriteStep } from '../../asas/runner/steps.ts';
+import type { StandardSchemaV1 } from '../../mithaq/standard-schema.ts';
+type Row = Record<string, unknown>;
+type Selected = {
+    limit(count: number): Promise<Row[]>;
+    where(condition: unknown): {
+        limit(count: number): Promise<Row[]>;
+    };
+};
+type Db = {
+    execute(query: unknown): Promise<unknown>;
+    select(): {
+        from(table: unknown): Selected;
+    };
+    update(table: unknown): {
+        set(values: Row): {
+            where(condition: unknown): {
+                returning(): Promise<Row[]>;
+            };
+        };
+    };
+    transaction<Result>(run: (tx: Db) => Promise<Result>): Promise<Result>;
+};
+/** How long a token and its session live, in seconds. */
+export declare const defaultTokenExpiration = 7200;
+/** Failed logins before the account locks. */
+export declare const defaultMaxLoginAttempts = 5;
+/** How long the lock holds, in milliseconds. */
+export declare const defaultLockTime = 600000;
+export type LocalAuthOptions = {
+    /**
+     * Signs with a random per-process secret when no `secret` is passed, and sends
+     * cookies without `Secure`. Never in production.
+     */
+    development?: boolean;
+    secureCookies?: boolean;
+    /** What every token is signed with, 32 characters at least. Required unless `development` or `withoutSecret` is set. */
+    secret?: string;
+    /**
+     * The project's own words local auth answers every POST with, as a 503, when it has no
+     * `secret` outside development; local auth is then off as a whole. Without it, a missing secret fails the build.
+     */
+    withoutSecret?: string;
+    /** How long a token and its session live, in seconds. */
+    tokenExpiration: number;
+    /** Failed logins before the account locks; 0 turns the lockout off. */
+    maxLoginAttempts: number;
+    /** How long the lock holds, in milliseconds. */
+    lockTime: number;
+    /**
+     * Where the verification and reset tokens go: the project renders and sends the whole mail.
+     * Without it, tokens are printed in development only, and outside development none is minted.
+     */
+    email?: {
+        send: (message: {
+            to: string;
+            kind: 'verification' | 'reset';
+            token: string;
+            user: Row;
+        }) => Promise<void>;
+    };
+    /** The context every step of first registration reads, built by the project's own code from the request. */
+    context?: (request: Request) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * The address a request came from, as the project's server saw it; mithaq reads no header for it.
+     * `login`, `forgot-password` and `reset-password` are rate limited by it; `null` leaves a request uncounted.
+     */
+    ip: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+};
+/** The store local auth reads its kayan through: the drizzle adapter, which declares `sql`. */
+export type LocalAuthTarget = {
+    readonly sql: 'drizzle';
+    db: Db;
+    tables: Record<string, Record<string, SQLWrapper>>;
+};
+export declare const isLocalAuthTarget: <T extends {
+    readonly sql?: 'drizzle';
+}>(target: T) => target is T & LocalAuthTarget;
+export type Writes = Record<string, {
+    operations: {
+        create(data: Row): Promise<Row>;
+    };
+}>;
+type PublicLocalUser<User extends Row> = Omit<User, ProtectedLocalField>;
+export type LocalAuthActor<KayanName extends string = string, User extends Row = Row> = PublicLocalUser<User> & {
+    kayan: KayanName;
+    strategy: 'local';
+    collection: KayanName;
+    /** The keys the build's access target resolved for this actor, never a column of this kayan's row. */
+    permissions?: '*' | readonly string[];
+    /** The role slugs the access target resolved in the tenant the actor's row names. */
+    roles?: readonly string[];
+    user: PublicLocalUser<User>;
+};
+declare const verifiedWrite: ({ user, siblingData }: {
+    user?: unknown;
+    siblingData?: Record<string, unknown>;
+}) => boolean;
+/**
+ * The fields a kayan carrying `local()` spreads beside `defaultFields`. Every one but `email`
+ * and `_verified` is closed on read and supplied by the provider alone.
+ */
+export declare const localAuthFields: {
+    readonly email: {
+        readonly kind: 'email';
+        readonly rules: {
+            readonly required: true;
+            readonly unique: true;
+            readonly lowercase: true;
+            readonly trim: true;
+        };
+    };
+    readonly hash: {
+        readonly kind: 'text';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly salt: {
+        readonly kind: 'text';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly sessions: {
+        readonly kind: 'text';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly loginAttempts: {
+        readonly kind: 'number';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly defaultValue: 0;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly lockUntil: {
+        readonly kind: 'datetime';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly resetPasswordToken: {
+        readonly kind: 'text';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly resetPasswordAttempts: {
+        readonly kind: 'number';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly defaultValue: 0;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly resetPasswordExpiration: {
+        readonly kind: 'datetime';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    readonly _verified: {
+        readonly kind: 'checkbox';
+        readonly access: {
+            readonly create: typeof verifiedWrite;
+            readonly update: typeof verifiedWrite;
+        };
+        readonly rules: {
+            readonly defaultValue: false;
+        };
+    };
+    readonly _verificationToken: {
+        readonly kind: 'text';
+        readonly access: {
+            read: typeof neverRead;
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+};
+type Shipped = typeof localAuthFields;
+/** The fields `localAuthFields` closes on read, which a response never carries. */
+export type ProtectedLocalField = {
+    [Name in keyof Shipped]: Shipped[Name] extends {
+        access: {
+            read: unknown;
+        };
+    } ? Name : never;
+}[keyof Shipped];
+export declare const holdsVerificationSteps: (kayan: ResolvedKayan) => boolean;
+/**
+ * The `create` and `update` a kayan carrying `local()` spreads over `defaultOperations`.
+ * A kayan adding a step writes the list around them: `[...localAuthOperations.create.steps, notify]`.
+ */
+export declare const localAuthOperations: {
+    create: {
+        input: ({ create }: DerivedShapes) => StandardSchemaV1<Record<string, unknown> & {
+            password?: string;
+        }>;
+        steps: WriteStep[];
+    };
+    update: {
+        input: ({ update: shape }: DerivedShapes) => StandardSchemaV1<Record<string, unknown> & {
+            password?: string;
+        }>;
+        steps: WriteStep[];
+    };
+};
+/** The local email-and-password strategy: sessions on the user row, and a signed cookie naming one. */
+export declare const localAuthStrategy: <Name extends string = string>({ options, kayan: resolved, target, writes, projectUser, permissions, assigned, onError, }: {
+    options: LocalAuthOptions;
+    kayan: ResolvedKayan;
+    target: LocalAuthTarget;
+    writes: Writes;
+    /** What a response carries of a row this actor reads; required, since an identity would hand every field to every caller. */
+    projectUser: (row: Row, actor: LocalAuthActor<Name>) => Promise<Row>;
+    permissions?: LocalAuthPermissions;
+    assigned?: AssignedResolver;
+    /** Handed an access target that failed to answer, and a reset token `forgot-password` could not hand over. */
+    onError: (error: unknown) => void;
+}) => AuthStrategy<LocalAuthActor<Name>>;
+/** The local email-and-password provider as a kayan declares it: `auth: local({ ... })`. */
+export declare const local: (options: LocalAuthOptions) => {
+    provider: 'local';
+    options: LocalAuthOptions;
+};
+export {};