@draftlab/auth 0.0.1

package/dist/code-l_uvMR1j.d.ts

@@ -0,0 +1,212 @@
+import { Provider } from "./provider-CwWMG-1l.js";
+
+//#region src/provider/code.d.ts
+
+/**
+ * Configuration options for the PIN code authentication provider.
+ *
+ * @template Claims - Type of claims collected during authentication (email, phone, etc.)
+ */
+interface CodeProviderConfig<Claims extends Record<string, string> = Record<string, string>> {
+  /**
+   * The length of the generated PIN code.
+   * Common values are 4, 6, or 8 digits.
+   *
+   * @default 6
+   *
+   * @example
+   * ```ts
+   * {
+   *   length: 4 // 4-digit PIN for easier entry
+   * }
+   * ```
+   */
+  readonly length?: number;
+  /**
+   * Request handler for rendering the authentication UI.
+   * Handles both the initial claim collection and PIN code entry screens.
+   *
+   * @param req - The HTTP request object
+   * @param state - Current authentication state (start or code verification)
+   * @param form - Form data from POST requests (if any)
+   * @param error - Authentication error to display (if any)
+   * @returns Promise resolving to the authentication page response
+   *
+   * @example
+   * ```ts
+   * request: async (req, state, form, error) => {
+   *   if (state.type === 'start') {
+   *     return new Response(renderClaimForm(form, error))
+   *   } else {
+   *     return new Response(renderCodeForm(state.claims.email, error))
+   *   }
+   * }
+   * ```
+   */
+  request: (req: Request, state: CodeProviderState, form?: FormData, error?: CodeProviderError) => Promise<Response>;
+  /**
+   * Callback for sending PIN codes to users via their preferred method.
+   * Should handle delivery via email, SMS, or other communication channels.
+   *
+   * @param claims - User claims containing contact information
+   * @param code - The generated PIN code to send
+   * @returns Promise resolving to undefined on success, or error object on failure
+   *
+   * @example
+   * ```ts
+   * sendCode: async (claims, code) => {
+   *   try {
+   *     if (claims.email) {
+   *       await emailService.send({
+   *         to: claims.email,
+   *         subject: 'Your verification code',
+   *         text: `Your PIN code is: ${code}`
+   *       })
+   *     } else if (claims.phone) {
+   *       await smsService.send(claims.phone, `PIN: ${code}`)
+   *     } else {
+   *       return {
+   *         type: "invalid_claim",
+   *         key: "contact",
+   *         value: "No email or phone provided"
+   *       }
+   *     }
+   *   } catch (error) {
+   *     return {
+   *       type: "invalid_claim",
+   *       key: "delivery",
+   *       value: "Failed to send code"
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  sendCode: (claims: Claims, code: string) => Promise<CodeProviderError | undefined>;
+}
+/**
+ * Authentication flow states for the PIN code provider.
+ * The provider transitions between these states during authentication.
+ */
+type CodeProviderState = {
+  /** Initial state: user enters their claims (email, phone, etc.) */
+  readonly type: "start";
+} | {
+  /** Code verification state: user enters the PIN code */
+  readonly type: "code";
+  /** Whether this is a code resend request */
+  readonly resend?: boolean;
+  /** The generated PIN code for verification */
+  readonly code: string;
+  /** User claims collected during the start phase */
+  readonly claims: Record<string, string>;
+};
+/**
+ * Possible errors during PIN code authentication.
+ */
+type CodeProviderError = {
+  /** The entered PIN code is incorrect */
+  readonly type: "invalid_code";
+} | {
+  /** A user claim is invalid or missing */
+  readonly type: "invalid_claim";
+  /** The claim field that failed validation */
+  readonly key: string;
+  /** The invalid value or error description */
+  readonly value: string;
+};
+/**
+ * User data returned by successful PIN code authentication.
+ *
+ * @template Claims - Type of claims collected during authentication
+ */
+interface CodeUserData<Claims extends Record<string, string> = Record<string, string>> {
+  /** The verified claims collected during authentication */
+  readonly claims: Claims;
+}
+/**
+ * Creates a PIN code authentication provider.
+ * Implements a flexible claim-based authentication flow with PIN verification.
+ *
+ * @template Claims - Type of claims to collect (email, phone, username, etc.)
+ * @param config - PIN code provider configuration
+ * @returns Provider instance implementing PIN code authentication
+ *
+ * @example
+ * ```ts
+ * // Email-based PIN authentication
+ * const emailCodeProvider = CodeProvider<{ email: string }>({
+ *   length: 6,
+ *   request: async (req, state, form, error) => {
+ *     if (state.type === 'start') {
+ *       return new Response(renderEmailForm(form?.get('email'), error))
+ *     } else {
+ *       return new Response(renderPinForm(state.claims.email, error, state.resend))
+ *     }
+ *   },
+ *   sendCode: async (claims, code) => {
+ *     if (!claims.email || !isValidEmail(claims.email)) {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "email",
+ *         value: "Invalid email address"
+ *       }
+ *     }
+ *
+ *     await emailService.send(claims.email, `Your verification code: ${code}`)
+ *   }
+ * })
+ *
+ * // Multi-channel PIN authentication (email or phone)
+ * const flexibleCodeProvider = CodeProvider<{ email?: string; phone?: string }>({
+ *   length: 4,
+ *   request: async (req, state, form, error) => {
+ *     if (state.type === 'start') {
+ *       return new Response(renderContactForm(form, error))
+ *     } else {
+ *       const contact = state.claims.email || state.claims.phone
+ *       return new Response(renderPinForm(contact, error))
+ *     }
+ *   },
+ *   sendCode: async (claims, code) => {
+ *     if (claims.email) {
+ *       await emailService.send(claims.email, `PIN: ${code}`)
+ *     } else if (claims.phone) {
+ *       await smsService.send(claims.phone, `PIN: ${code}`)
+ *     } else {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "contact",
+ *         value: "Provide either email or phone number"
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Usage in issuer
+ * export default issuer({
+ *   providers: {
+ *     email: emailCodeProvider,
+ *     flexible: flexibleCodeProvider
+ *   },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "code") {
+ *       const email = value.claims.email
+ *       const phone = value.claims.phone
+ *
+ *       // Look up or create user based on verified claims
+ *       const userId = await findOrCreateUser({ email, phone })
+ *
+ *       return ctx.subject("user", { userId, email, phone })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const CodeProvider: <Claims extends Record<string, string> = Record<string, string>>(config: CodeProviderConfig<Claims>) => Provider<CodeUserData<Claims>>;
+/**
+ * Type helper for CodeProvider configuration options.
+ * @internal
+ */
+type CodeProviderOptions = Parameters<typeof CodeProvider>[0];
+//#endregion
+export { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData };

package/dist/core-8WTqfnb4.d.ts

@@ -0,0 +1,129 @@
+import { AllowCheckInput } from "./allow-CixonwTW.js";
+import { UnknownStateError } from "./error-CWAdNAzm.js";
+import { Prettify } from "./util-ChlgVqPN.js";
+import { SubjectPayload, SubjectSchema } from "./subject-DiQdRWGt.js";
+import { StorageAdapter } from "./storage-CxKerLlc.js";
+import { Provider } from "./provider-CwWMG-1l.js";
+import { Theme } from "./theme-C9by7VXf.js";
+import { Router } from "@draftlab/router";
+
+//#region src/core.d.ts
+
+/**
+ * Sets the subject payload in the JWT token and returns the response.
+ */
+interface OnSuccessResponder<T extends {
+  type: string;
+  properties: unknown;
+}> {
+  subject<Type extends T["type"]>(type: Type, properties: Extract<T, {
+    type: Type;
+  }>["properties"], opts?: {
+    ttl?: {
+      access?: number;
+      refresh?: number;
+    };
+    subject?: string;
+  }): Promise<Response>;
+}
+/**
+ * Authorization state for OAuth 2.0 flows.
+ */
+interface AuthorizationState {
+  /** OAuth redirect URI */
+  redirect_uri: string;
+  /** OAuth response type */
+  response_type: string;
+  /** OAuth state parameter for CSRF protection */
+  state: string;
+  /** OAuth client identifier */
+  client_id: string;
+  /** OAuth audience parameter */
+  audience: string;
+  /** PKCE challenge data for code verification */
+  pkce?: {
+    challenge: string;
+    method: "S256";
+  };
+}
+/**
+ * Main issuer input configuration interface.
+ */
+interface IssuerInput<Providers extends Record<string, Provider<unknown>>, Subjects extends SubjectSchema, Result = { [Key in keyof Providers]: Prettify<{
+  provider: Key;
+} & (Providers[Key] extends Provider<infer T> ? T : Record<string, unknown>)> }[keyof Providers]> {
+  /** The storage adapter for persisting tokens and sessions */
+  storage: StorageAdapter;
+  /** Auth providers configuration */
+  providers: Providers;
+  /** Subject schemas for token validation */
+  subjects: Subjects;
+  /** Base path for embedded scenarios */
+  basePath?: string;
+  /** Success callback for completed authentication */
+  success(response: OnSuccessResponder<SubjectPayload<Subjects>>, input: Result, req: Request, clientID: string): Promise<Response>;
+  /** Theme configuration for UI */
+  theme?: Theme;
+  /** TTL configuration for tokens and sessions */
+  ttl?: {
+    access?: number;
+    refresh?: number;
+    reuse?: number;
+    retention?: number;
+  };
+  /** Provider selection UI function */
+  select?(providers: Record<string, string>, req: Request): Promise<Response>;
+  /** Optional start callback */
+  start?(req: Request): Promise<void>;
+  /** Error handling callback */
+  error?(error: UnknownStateError, req: Request): Promise<Response>;
+  /** Client authorization check function */
+  allow?(input: AllowCheckInput, req: Request): Promise<boolean>;
+  /**
+   * Refresh callback for updating user claims.
+   *
+   * @example
+   * ```typescript
+   * refresh: async (payload, req) => {
+   *   const user = await getUserBySubject(payload.subject)
+   *   if (!user || !user.active) {
+   *     return undefined // Revoke the token
+   *   }
+   *
+   *   return {
+   *     type: payload.type,
+   *     properties: {
+   *       userID: user.id,
+   *       role: user.role,
+   *       permissions: user.permissions,
+   *       lastLogin: new Date().toISOString()
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  refresh?(payload: {
+    type: SubjectPayload<Subjects>["type"];
+    properties: SubjectPayload<Subjects>["properties"];
+    subject: string;
+    clientID: string;
+    scopes?: string[];
+  }, req: Request): Promise<{
+    type: SubjectPayload<Subjects>["type"];
+    properties: SubjectPayload<Subjects>["properties"];
+    subject?: string;
+    scopes?: string[];
+  } | undefined>;
+}
+/**
+ * Create an Draft Auth server, a Router app that handles OAuth 2.0 flows.
+ */
+declare const issuer: <Providers extends Record<string, Provider<unknown>>, Subjects extends SubjectSchema, Result = { [key in keyof Providers]: {
+  provider: key;
+} & (Providers[key] extends Provider<infer T> ? T : Record<string, unknown>) }[keyof Providers]>(input: IssuerInput<Providers, Subjects, Result>) => Router<{
+  Variables: {
+    authorization: AuthorizationState;
+  };
+}>;
+//#endregion
+export { AuthorizationState, OnSuccessResponder, issuer };