@azlib/identity 0.2.0

package/dist/identity-router-Dib30Waj.d.cts

@@ -0,0 +1,115 @@
+import { F as IdentityLogger } from "./errors-C2xZAatu.cjs";
+import { t as IdentityService } from "./identity-service-CLzKx8Z7.cjs";
+import { Request, Response, Router } from "express";
+
+//#region core/express/identity-router.d.ts
+/** Options for controlling the refresh-token cookie. */
+interface CookieRefreshOptions {
+  /** Cookie name. Default: `"azlib_rt"`. */
+  name?: string;
+  /** Mark the cookie as `HttpOnly`. Default: `true`. */
+  httpOnly?: boolean;
+  /**
+   * Mark the cookie as `Secure`. Defaults to `true` when `NODE_ENV` is `"production"`,
+   * `false` otherwise.
+   */
+  secure?: boolean;
+  /** `SameSite` policy. Default: `"lax"`. */
+  sameSite?: "strict" | "lax" | "none";
+  /** Cookie path. Default: `"/"`. */
+  path?: string;
+  /** Cookie domain. Omit to use the current host. */
+  domain?: string;
+}
+/**
+ * Options for {@link createIdentityRouter}.
+ */
+interface IdentityRouterOptions {
+  /**
+   * Controls how the refresh token is transported between server and client.
+   *
+   * - **`"body"`** (default) — the refresh token is included in the `tokens` object of
+   *   every successful `register`/`login`/`refresh` response. The client must store it
+   *   and send it back via the JSON body on `/refresh` and `/logout`.
+   *
+   * - **`{ cookie: CookieRefreshOptions }`** — the refresh token is sent as an
+   *   `HttpOnly` cookie. `/refresh` and `/logout` read it automatically; the response
+   *   body only includes the access token.
+   */
+  refreshToken?: "body" | {
+    cookie: CookieRefreshOptions;
+  };
+  /**
+   * Base URL under which the OAuth callback routes are hosted.
+   *
+   * Example: `"https://api.example.com/auth"`.
+   *
+   * The callback URI for a provider becomes `{oauthBaseUrl}/{providerName}/callback`.
+   * Required when the identity service has OAuth providers configured.
+   */
+  oauthBaseUrl?: string;
+  /**
+   * URL path prefix prepended to all identity routes.
+   *
+   * Default: `"account"`. Routes are served at `/{prefix}/login`, `/{prefix}/register`, etc.
+   *
+   * Mount the returned router at the application root:
+   * ```ts
+   * app.use(createIdentityRouter(service, { prefix: "auth" }));
+   * // → POST /auth/login, POST /auth/register, …
+   * ```
+   *
+   * Set to `""` to omit the prefix and mount routes directly at the router's mount point.
+   */
+  prefix?: string;
+  /**
+   * Logger for request/response and error diagnostics.
+   *
+   * - Omit — defaults to a `console`-based logger with an `[identity]` prefix.
+   * - Supply your own `IdentityLogger` — route output to Winston, Pino, etc.
+   * - Pass `false` — disable all logging from this router.
+   *
+   * @example
+   * ```ts
+   * import pino from "pino";
+   * app.use(createIdentityRouter(service, { logger: pino() }));
+   * ```
+   */
+  logger?: IdentityLogger | false;
+}
+/**
+ * Creates a pre-wired Express `Router` with all standard identity endpoints.
+ *
+ * Mount it once on your application:
+ * ```ts
+ * import express from "express";
+ * import { createIdentityService } from "@azlib/identity/node";
+ * import { createIdentityRouter, identityErrorHandler } from "@azlib/identity/express";
+ *
+ * const service = createIdentityService(config, store);
+ * const app = express();
+ *
+ * app.use(express.json());
+ * // Routes are served at /account/login, /account/register, etc. (default prefix)
+ * app.use(createIdentityRouter(service));
+ * // Or use a custom prefix:
+ * app.use(createIdentityRouter(service, { prefix: "auth" }));
+ * app.use(identityErrorHandler()); // optional convenience error handler
+ * ```
+ *
+ * Pre-wired routes:
+ *
+ * | Method | Path | Description |
+ * |--------|------|-------------|
+ * | POST | `/register` | Create a new account |
+ * | POST | `/login` | Email + password login |
+ * | POST | `/refresh` | Rotate the refresh token |
+ * | POST | `/logout` | Revoke the current session |
+ * | GET  | `/me` | Return the authenticated principal |
+ * | GET  | `/:provider` | Start an OAuth 2.0 authorisation flow *(optional)* |
+ * | GET  | `/:provider/callback` | Handle an OAuth 2.0 callback *(optional)* |
+ */
+declare function createIdentityRouter(service: IdentityService, options?: IdentityRouterOptions): Router;
+//#endregion
+export { IdentityRouterOptions as n, createIdentityRouter as r, CookieRefreshOptions as t };
+//# sourceMappingURL=identity-router-Dib30Waj.d.cts.map

package/dist/identity-router-Dib30Waj.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-router-Dib30Waj.d.cts","names":[],"sources":["../core/express/identity-router.ts"],"mappings":";;;;;;UAeiB,oBAAA;EAAA;EAEf,IAAA;;EAEA,QAAA;EAFA;;;;EAOA,MAAA;EAMA;EAJA,QAAA;EAIM;EAFN,IAAA;EAQoC;EANpC,MAAA;AAAA;;;;UAMe,qBAAA;EAqCf;;;;AAeuB;AAsIzB;;;;;;EA9KE,YAAA;IAA0B,MAAA,EAAQ,oBAAA;EAAA;EA+KlC;;;;;AAEO;;;EAvKP,YAAA;;;;;;;;;;;;;;EAeA,MAAA;;;;;;;;;;;;;;EAeA,MAAA,GAAS,cAAc;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsIT,oBAAA,CACd,OAAA,EAAS,eAAA,EACT,OAAA,GAAS,qBAAA,GACR,MAAA"}

package/dist/identity-service-B9zrvE9z.d.mts

@@ -0,0 +1,128 @@
+import { T as TotpSetupResult, c as AuthResult, d as AuthenticatedIdentity, r as IdentityStore, v as LoginResult } from "./identity-store-BRRahxcS.mjs";
+import { B as AuthorizationDecision, D as IdentityConfigInput, V as AuthorizationRequirement, a as IdentityError, f as OAuthService, v as OAuthProvider, w as AuditLogger, x as SessionDeps, z as AuthorizationContext } from "./errors-BGMwaW5s.mjs";
+
+//#region core/password-hasher.d.ts
+interface PasswordHasher {
+  hash(password: string): Promise<string>;
+  verify(password: string, storedHash: string): Promise<boolean>;
+}
+/** Creates a scrypt-based {@link PasswordHasher}. */
+declare function createPasswordHasher(cost: number): PasswordHasher;
+//#endregion
+//#region core/login.d.ts
+/** Dependencies for the login flow. */
+interface LoginDeps extends SessionDeps {
+  hasher: PasswordHasher;
+  audit: AuditLogger;
+}
+/** Input for {@link loginUser}. */
+interface LoginInput {
+  email: string;
+  password: string;
+}
+/**
+ * Authenticates a user with email + password. Uses a single generic failure for both
+ * "unknown user" and "wrong password" to avoid account enumeration, and performs a hash
+ * comparison even when the user is unknown to reduce timing side-channels.
+ *
+ * When account lockout is enabled (config.lockout.maxFailedAttempts > 0), consecutive
+ * failures increment a counter and temporarily lock the account.
+ */
+declare function loginUser(deps: LoginDeps, input: LoginInput): Promise<LoginResult>;
+//#endregion
+//#region core/register.d.ts
+/** Dependencies for the register flow. */
+interface RegisterDeps extends SessionDeps {
+  hasher: PasswordHasher;
+  audit: AuditLogger;
+}
+/** Input for {@link registerUser}. */
+interface RegisterInput {
+  email: string;
+  password: string;
+  displayName?: string | null;
+}
+/** Raised when registration input fails validation. */
+declare class RegistrationValidationError extends IdentityError {
+  constructor(message: string);
+}
+/** Normalizes an email for storage and lookup (trim + lowercase). */
+declare function normalizeEmail(email: string): string;
+/**
+ * Registers a new user: validates input, enforces unique email, hashes the password,
+ * persists the user and credential, and returns an authenticated session.
+ */
+declare function registerUser(deps: RegisterDeps, input: RegisterInput): Promise<AuthResult>;
+//#endregion
+//#region core/identity-service.d.ts
+/** The wired runtime API returned by {@link createIdentityService}. */
+interface IdentityService {
+  register(input: RegisterInput): Promise<AuthResult>;
+  /**
+   * Authenticates with email + password. Returns a full {@link AuthResult} normally, or
+   * an {@link MfaRequiredResult} (containing an `mfaToken`) when the account has 2FA
+   * enabled. In the latter case call {@link verifyMfaChallenge} to complete the login.
+   */
+  login(input: LoginInput): Promise<LoginResult>;
+  refresh(refreshToken: string): Promise<AuthResult>;
+  logout(refreshToken: string): Promise<void>;
+  /**
+   * Verifies an access token and hydrates the current principal from the store.
+   * Throws {@link InvalidTokenError} for invalid/stale tokens.
+   */
+  authenticate(accessToken: string): Promise<AuthenticatedIdentity>;
+  authorize<TResource = unknown>(requirement: AuthorizationRequirement<TResource>, context: AuthorizationContext<TResource>): Promise<AuthorizationDecision>;
+  /** Sends (or resends) an email verification link for the given user id. */
+  requestEmailVerification(userId: string): Promise<void>;
+  /** Marks the user's email as verified using the token from the verification link. */
+  verifyEmail(token: string): Promise<void>;
+  /** Sends a password reset link to the given email address. Silent for unknown addresses. */
+  requestPasswordReset(email: string): Promise<void>;
+  /** Resets the password using the token from the reset link. */
+  resetPassword(token: string, newPassword: string): Promise<void>;
+  /**
+   * Begins the 2FA setup flow. Returns the TOTP secret and an OTP Auth URI for QR code
+   * display. Call {@link enable2FA} with a valid code to activate.
+   */
+  setup2FA(userId: string): Promise<TotpSetupResult>;
+  /** Confirms and enables 2FA. Requires a valid TOTP code from the authenticator app. */
+  enable2FA(userId: string, totpCode: string): Promise<void>;
+  /** Disables 2FA. Requires a valid TOTP code as confirmation. */
+  disable2FA(userId: string, totpCode: string): Promise<void>;
+  /**
+   * Completes an MFA challenge. Present the `mfaToken` returned by `login` together
+   * with the TOTP code from the authenticator app.
+   */
+  verifyMfaChallenge(mfaToken: string, totpCode: string): Promise<AuthResult>;
+  /** Locks the account and revokes all active sessions. */
+  lockAccount(userId: string): Promise<void>;
+  /** Unlocks the account and clears lockout state. */
+  unlockAccount(userId: string): Promise<void>;
+  /** Permanently disables the account (requires manual admin unlock). */
+  disableAccount(userId: string): Promise<void>;
+  /**
+   * The OAuth 2.0 / OpenID Connect surface. Present only when at least one provider is
+   * configured via `IdentityConfigInput.oauth.providers`.
+   */
+  oauth?: OAuthService;
+}
+/** Extended config input with optional OAuth provider list. */
+interface IdentityServiceConfig extends IdentityConfigInput {
+  /** Optional OAuth 2.0 / OIDC configuration. */
+  oauth?: {
+    /**
+     * The list of external authentication providers to enable. Each item is an
+     * {@link OAuthProvider} instance, e.g. `createGoogleOAuthProvider(...)` or
+     * `createMicrosoftOAuthProvider(...)`.
+     */
+    providers: OAuthProvider[];
+  };
+}
+/**
+ * Wires the framework-agnostic identity runtime with Node defaults (scrypt hashing,
+ * `jose` HS256 tokens). Express and NestJS adapters build on top of this service.
+ */
+declare function createIdentityService(configInput: IdentityServiceConfig, store: IdentityStore): IdentityService;
+//#endregion
+export { RegisterInput as a, registerUser as c, loginUser as d, PasswordHasher as f, RegisterDeps as i, LoginDeps as l, IdentityServiceConfig as n, RegistrationValidationError as o, createPasswordHasher as p, createIdentityService as r, normalizeEmail as s, IdentityService as t, LoginInput as u };
+//# sourceMappingURL=identity-service-B9zrvE9z.d.mts.map

package/dist/identity-service-B9zrvE9z.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-service-B9zrvE9z.d.mts","names":[],"sources":["../core/password-hasher.ts","../core/login.ts","../core/register.ts","../core/identity-service.ts"],"mappings":";;;;UAuBiB,cAAA;EACf,IAAA,CAAK,QAAA,WAAmB,OAAA;EACxB,MAAA,CAAO,QAAA,UAAkB,UAAA,WAAqB,OAAO;AAAA;AAFvD;AAAA,iBAMgB,oBAAA,CAAqB,IAAA,WAAe,cAAc;;;AANlE;AAAA,UCbiB,SAAA,SAAkB,WAAA;EACjC,MAAA,EAAQ,cAAA;EACR,KAAA,EAAO,WAAA;AAAA;;UAIQ,UAAA;EACf,KAAA;EACA,QAAQ;AAAA;;;ADO6C;AAIvD;;;;AAAkE;iBCA5C,SAAA,CAAU,IAAA,EAAM,SAAA,EAAW,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,WAAA;;;;UCtB5D,YAAA,SAAqB,WAAA;EACpC,MAAA,EAAQ,cAAA;EACR,KAAA,EAAO,WAAA;AAAA;;UAIQ,aAAA;EACf,KAAA;EACA,QAAA;EACA,WAAA;AAAA;AFSqD;AAAA,cEL1C,2BAAA,SAAoC,aAAa;cAChD,OAAA;AAAA;;iBASE,cAAA,CAAe,KAAa;;;;ADpB5C;iBC4BsB,YAAA,CACpB,IAAA,EAAM,YAAA,EACN,KAAA,EAAO,aAAA,GACN,OAAA,CAAQ,UAAA;;;;UCDM,eAAA;EACf,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,UAAA;EHhBxC;;;;;EGsBA,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,WAAA;EAClC,OAAA,CAAQ,YAAA,WAAuB,OAAA,CAAQ,UAAA;EACvC,MAAA,CAAO,YAAA,WAAuB,OAAA;;;AHpBkC;;EGyBhE,YAAA,CAAa,WAAA,WAAsB,OAAA,CAAQ,qBAAA;EAC3C,SAAA,sBACE,WAAA,EAAa,wBAAA,CAAyB,SAAA,GACtC,OAAA,EAAS,oBAAA,CAAqB,SAAA,IAC7B,OAAA,CAAQ,qBAAA;EFhDI;EEoDf,wBAAA,CAAyB,MAAA,WAAiB,OAAA;;EAE1C,WAAA,CAAY,KAAA,WAAgB,OAAA;EFpDrB;EEwDP,oBAAA,CAAqB,KAAA,WAAgB,OAAA;EF1DO;EE4D5C,aAAA,CAAc,KAAA,UAAe,WAAA,WAAsB,OAAA;EF5DlB;;;;EEmEjC,QAAA,CAAS,MAAA,WAAiB,OAAA,CAAQ,eAAA;EFjEhB;EEmElB,SAAA,CAAU,MAAA,UAAgB,QAAA,WAAmB,OAAA;EF/D9B;EEiEf,UAAA,CAAW,MAAA,UAAgB,QAAA,WAAmB,OAAA;;;AF/DtC;AAWV;EEyDE,kBAAA,CAAmB,QAAA,UAAkB,QAAA,WAAmB,OAAA,CAAQ,UAAA;;EAIhE,WAAA,CAAY,MAAA,WAAiB,OAAA;EF7DyB;EE+DtD,aAAA,CAAc,MAAA,WAAiB,OAAA;EF/DoC;EEiEnE,cAAA,CAAe,MAAA,WAAiB,OAAA;EFjE0C;;;;EEuE1E,KAAA,GAAQ,YAAA;AAAA;;UAIO,qBAAA,SAA8B,mBAAmB;EF3EsB;EE6EtF,KAAA;;;ADnGF;;;ICyGI,SAAA,EAAW,aAAA;EAAA;AAAA;;;;;iBAQC,qBAAA,CACd,WAAA,EAAa,qBAAA,EACb,KAAA,EAAO,aAAA,GACN,eAAA"}

package/dist/identity-service-CLzKx8Z7.d.cts

@@ -0,0 +1,128 @@
+import { T as TotpSetupResult, c as AuthResult, d as AuthenticatedIdentity, r as IdentityStore, v as LoginResult } from "./identity-store-BRRahxcS.cjs";
+import { B as AuthorizationDecision, D as IdentityConfigInput, V as AuthorizationRequirement, a as IdentityError, f as OAuthService, v as OAuthProvider, w as AuditLogger, x as SessionDeps, z as AuthorizationContext } from "./errors-C2xZAatu.cjs";
+
+//#region core/password-hasher.d.ts
+interface PasswordHasher {
+  hash(password: string): Promise<string>;
+  verify(password: string, storedHash: string): Promise<boolean>;
+}
+/** Creates a scrypt-based {@link PasswordHasher}. */
+declare function createPasswordHasher(cost: number): PasswordHasher;
+//#endregion
+//#region core/login.d.ts
+/** Dependencies for the login flow. */
+interface LoginDeps extends SessionDeps {
+  hasher: PasswordHasher;
+  audit: AuditLogger;
+}
+/** Input for {@link loginUser}. */
+interface LoginInput {
+  email: string;
+  password: string;
+}
+/**
+ * Authenticates a user with email + password. Uses a single generic failure for both
+ * "unknown user" and "wrong password" to avoid account enumeration, and performs a hash
+ * comparison even when the user is unknown to reduce timing side-channels.
+ *
+ * When account lockout is enabled (config.lockout.maxFailedAttempts > 0), consecutive
+ * failures increment a counter and temporarily lock the account.
+ */
+declare function loginUser(deps: LoginDeps, input: LoginInput): Promise<LoginResult>;
+//#endregion
+//#region core/register.d.ts
+/** Dependencies for the register flow. */
+interface RegisterDeps extends SessionDeps {
+  hasher: PasswordHasher;
+  audit: AuditLogger;
+}
+/** Input for {@link registerUser}. */
+interface RegisterInput {
+  email: string;
+  password: string;
+  displayName?: string | null;
+}
+/** Raised when registration input fails validation. */
+declare class RegistrationValidationError extends IdentityError {
+  constructor(message: string);
+}
+/** Normalizes an email for storage and lookup (trim + lowercase). */
+declare function normalizeEmail(email: string): string;
+/**
+ * Registers a new user: validates input, enforces unique email, hashes the password,
+ * persists the user and credential, and returns an authenticated session.
+ */
+declare function registerUser(deps: RegisterDeps, input: RegisterInput): Promise<AuthResult>;
+//#endregion
+//#region core/identity-service.d.ts
+/** The wired runtime API returned by {@link createIdentityService}. */
+interface IdentityService {
+  register(input: RegisterInput): Promise<AuthResult>;
+  /**
+   * Authenticates with email + password. Returns a full {@link AuthResult} normally, or
+   * an {@link MfaRequiredResult} (containing an `mfaToken`) when the account has 2FA
+   * enabled. In the latter case call {@link verifyMfaChallenge} to complete the login.
+   */
+  login(input: LoginInput): Promise<LoginResult>;
+  refresh(refreshToken: string): Promise<AuthResult>;
+  logout(refreshToken: string): Promise<void>;
+  /**
+   * Verifies an access token and hydrates the current principal from the store.
+   * Throws {@link InvalidTokenError} for invalid/stale tokens.
+   */
+  authenticate(accessToken: string): Promise<AuthenticatedIdentity>;
+  authorize<TResource = unknown>(requirement: AuthorizationRequirement<TResource>, context: AuthorizationContext<TResource>): Promise<AuthorizationDecision>;
+  /** Sends (or resends) an email verification link for the given user id. */
+  requestEmailVerification(userId: string): Promise<void>;
+  /** Marks the user's email as verified using the token from the verification link. */
+  verifyEmail(token: string): Promise<void>;
+  /** Sends a password reset link to the given email address. Silent for unknown addresses. */
+  requestPasswordReset(email: string): Promise<void>;
+  /** Resets the password using the token from the reset link. */
+  resetPassword(token: string, newPassword: string): Promise<void>;
+  /**
+   * Begins the 2FA setup flow. Returns the TOTP secret and an OTP Auth URI for QR code
+   * display. Call {@link enable2FA} with a valid code to activate.
+   */
+  setup2FA(userId: string): Promise<TotpSetupResult>;
+  /** Confirms and enables 2FA. Requires a valid TOTP code from the authenticator app. */
+  enable2FA(userId: string, totpCode: string): Promise<void>;
+  /** Disables 2FA. Requires a valid TOTP code as confirmation. */
+  disable2FA(userId: string, totpCode: string): Promise<void>;
+  /**
+   * Completes an MFA challenge. Present the `mfaToken` returned by `login` together
+   * with the TOTP code from the authenticator app.
+   */
+  verifyMfaChallenge(mfaToken: string, totpCode: string): Promise<AuthResult>;
+  /** Locks the account and revokes all active sessions. */
+  lockAccount(userId: string): Promise<void>;
+  /** Unlocks the account and clears lockout state. */
+  unlockAccount(userId: string): Promise<void>;
+  /** Permanently disables the account (requires manual admin unlock). */
+  disableAccount(userId: string): Promise<void>;
+  /**
+   * The OAuth 2.0 / OpenID Connect surface. Present only when at least one provider is
+   * configured via `IdentityConfigInput.oauth.providers`.
+   */
+  oauth?: OAuthService;
+}
+/** Extended config input with optional OAuth provider list. */
+interface IdentityServiceConfig extends IdentityConfigInput {
+  /** Optional OAuth 2.0 / OIDC configuration. */
+  oauth?: {
+    /**
+     * The list of external authentication providers to enable. Each item is an
+     * {@link OAuthProvider} instance, e.g. `createGoogleOAuthProvider(...)` or
+     * `createMicrosoftOAuthProvider(...)`.
+     */
+    providers: OAuthProvider[];
+  };
+}
+/**
+ * Wires the framework-agnostic identity runtime with Node defaults (scrypt hashing,
+ * `jose` HS256 tokens). Express and NestJS adapters build on top of this service.
+ */
+declare function createIdentityService(configInput: IdentityServiceConfig, store: IdentityStore): IdentityService;
+//#endregion
+export { RegisterInput as a, registerUser as c, loginUser as d, PasswordHasher as f, RegisterDeps as i, LoginDeps as l, IdentityServiceConfig as n, RegistrationValidationError as o, createPasswordHasher as p, createIdentityService as r, normalizeEmail as s, IdentityService as t, LoginInput as u };
+//# sourceMappingURL=identity-service-CLzKx8Z7.d.cts.map

package/dist/identity-service-CLzKx8Z7.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-service-CLzKx8Z7.d.cts","names":[],"sources":["../core/password-hasher.ts","../core/login.ts","../core/register.ts","../core/identity-service.ts"],"mappings":";;;;UAuBiB,cAAA;EACf,IAAA,CAAK,QAAA,WAAmB,OAAA;EACxB,MAAA,CAAO,QAAA,UAAkB,UAAA,WAAqB,OAAO;AAAA;AAFvD;AAAA,iBAMgB,oBAAA,CAAqB,IAAA,WAAe,cAAc;;;AANlE;AAAA,UCbiB,SAAA,SAAkB,WAAA;EACjC,MAAA,EAAQ,cAAA;EACR,KAAA,EAAO,WAAA;AAAA;;UAIQ,UAAA;EACf,KAAA;EACA,QAAQ;AAAA;;;ADO6C;AAIvD;;;;AAAkE;iBCA5C,SAAA,CAAU,IAAA,EAAM,SAAA,EAAW,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,WAAA;;;;UCtB5D,YAAA,SAAqB,WAAA;EACpC,MAAA,EAAQ,cAAA;EACR,KAAA,EAAO,WAAA;AAAA;;UAIQ,aAAA;EACf,KAAA;EACA,QAAA;EACA,WAAA;AAAA;AFSqD;AAAA,cEL1C,2BAAA,SAAoC,aAAa;cAChD,OAAA;AAAA;;iBASE,cAAA,CAAe,KAAa;;;;ADpB5C;iBC4BsB,YAAA,CACpB,IAAA,EAAM,YAAA,EACN,KAAA,EAAO,aAAA,GACN,OAAA,CAAQ,UAAA;;;;UCDM,eAAA;EACf,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,UAAA;EHhBxC;;;;;EGsBA,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,WAAA;EAClC,OAAA,CAAQ,YAAA,WAAuB,OAAA,CAAQ,UAAA;EACvC,MAAA,CAAO,YAAA,WAAuB,OAAA;;;AHpBkC;;EGyBhE,YAAA,CAAa,WAAA,WAAsB,OAAA,CAAQ,qBAAA;EAC3C,SAAA,sBACE,WAAA,EAAa,wBAAA,CAAyB,SAAA,GACtC,OAAA,EAAS,oBAAA,CAAqB,SAAA,IAC7B,OAAA,CAAQ,qBAAA;EFhDI;EEoDf,wBAAA,CAAyB,MAAA,WAAiB,OAAA;;EAE1C,WAAA,CAAY,KAAA,WAAgB,OAAA;EFpDrB;EEwDP,oBAAA,CAAqB,KAAA,WAAgB,OAAA;EF1DO;EE4D5C,aAAA,CAAc,KAAA,UAAe,WAAA,WAAsB,OAAA;EF5DlB;;;;EEmEjC,QAAA,CAAS,MAAA,WAAiB,OAAA,CAAQ,eAAA;EFjEhB;EEmElB,SAAA,CAAU,MAAA,UAAgB,QAAA,WAAmB,OAAA;EF/D9B;EEiEf,UAAA,CAAW,MAAA,UAAgB,QAAA,WAAmB,OAAA;;;AF/DtC;AAWV;EEyDE,kBAAA,CAAmB,QAAA,UAAkB,QAAA,WAAmB,OAAA,CAAQ,UAAA;;EAIhE,WAAA,CAAY,MAAA,WAAiB,OAAA;EF7DyB;EE+DtD,aAAA,CAAc,MAAA,WAAiB,OAAA;EF/DoC;EEiEnE,cAAA,CAAe,MAAA,WAAiB,OAAA;EFjE0C;;;;EEuE1E,KAAA,GAAQ,YAAA;AAAA;;UAIO,qBAAA,SAA8B,mBAAmB;EF3EsB;EE6EtF,KAAA;;;ADnGF;;;ICyGI,SAAA,EAAW,aAAA;EAAA;AAAA;;;;;iBAQC,qBAAA,CACd,WAAA,EAAa,qBAAA,EACb,KAAA,EAAO,aAAA,GACN,eAAA"}

package/dist/identity-store-BRRahxcS.d.cts

@@ -0,0 +1,272 @@
+//#region core/types.d.ts
+/**
+ * Shared, framework-agnostic domain types for `@azlib/identity`.
+ *
+ * These types describe the persistence model and the runtime principal. They do not
+ * depend on Node, Express, or NestJS so they can be imported from any surface.
+ */
+/** Lifecycle status for an identity user. */
+type IdentityUserStatus = "active" | "disabled" | "locked";
+/** A persisted identity user record. */
+interface IdentityUser {
+  userId: string;
+  email: string;
+  displayName: string | null;
+  status: IdentityUserStatus;
+  emailVerifiedAt: Date | null;
+  /**
+   * Whether TOTP-based two-factor authentication is currently active for this account.
+   */
+  twoFactorEnabled: boolean;
+  /**
+   * Incremented to invalidate previously issued access/refresh tokens (for example on
+   * password change or forced logout). Tokens carry this value and are rejected on mismatch.
+   */
+  authVersion: number;
+  /**
+   * Consecutive failed login attempts since the last successful login. Reset to 0 on success.
+   * Used by the account lockout feature.
+   */
+  failedLoginAttempts: number;
+  /**
+   * When set, the account is temporarily locked until this time. The lockout feature sets
+   * this after the configured `maxFailedAttempts` threshold is exceeded.
+   */
+  lockedUntil: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+/** Stored password credential for a user. The plaintext password is never persisted. */
+interface CredentialRecord {
+  userId: string;
+  /** Opaque, algorithm-tagged password hash. */
+  passwordHash: string;
+  updatedAt: Date;
+}
+/**
+ * A server-side refresh session. The raw refresh token is returned to the client once;
+ * only its hash is stored so a database leak does not expose usable tokens.
+ */
+interface AuthSession {
+  sessionId: string;
+  userId: string;
+  /** Hash of the current refresh token. Rotated on every refresh. */
+  refreshTokenHash: string;
+  createdAt: Date;
+  expiresAt: Date;
+  /** Set when the session has been rotated or revoked; such sessions are unusable. */
+  revokedAt: Date | null;
+}
+/** A coarse permission string, e.g. `documents:read`. */
+type Permission = string;
+/** A role groups permissions for assignment to users. */
+interface Role {
+  roleId: string;
+  name: string;
+  description: string | null;
+}
+/** Assignment of a role to a user. */
+interface UserRoleAssignment {
+  userId: string;
+  roleId: string;
+}
+/** Grant of a permission to a role. */
+interface RolePermissionGrant {
+  roleId: string;
+  permission: Permission;
+}
+/** Direct grant of a permission to a user, bypassing roles. */
+interface DirectPermissionGrant {
+  userId: string;
+  permission: Permission;
+}
+/** Names of the supported identity event types for auditing. */
+type IdentityEventType = "user.registered" | "user.login.succeeded" | "user.login.failed" | "user.login.mfa.challenged" | "user.account.locked" | "user.account.unlocked" | "user.email.verification.requested" | "user.email.verified" | "user.password.reset.requested" | "user.password.reset.completed" | "user.2fa.setup.started" | "user.2fa.enabled" | "user.2fa.disabled" | "user.oauth.linked" | "session.refreshed" | "session.revoked" | "authorization.denied";
+/** A linked OAuth / OIDC identity from an external provider (Google, Microsoft, etc.). */
+interface OAuthLinkedAccount {
+  userId: string;
+  /** Provider identifier, e.g. `"google"` or `"microsoft"`. */
+  provider: string;
+  /** The user's stable id on the provider side (`sub` claim). */
+  providerUserId: string;
+  email: string | null;
+  displayName: string | null;
+  linkedAt: Date;
+}
+/** An audit event emitted by identity flows. */
+interface IdentityEvent {
+  type: IdentityEventType;
+  userId: string | null;
+  /** Free-form, non-sensitive metadata. Never include passwords or raw tokens. */
+  metadata: Record<string, string | number | boolean | null>;
+  occurredAt: Date;
+}
+/**
+ * The authenticated principal hydrated from the store after a token is verified.
+ * Attached to the request by the Express middleware / NestJS guard.
+ */
+interface AuthenticatedIdentity {
+  userId: string;
+  email: string;
+  displayName: string | null;
+  status: IdentityUserStatus;
+  emailVerified: boolean;
+  roles: readonly string[];
+  permissions: readonly Permission[];
+}
+/** A successful authentication result containing tokens and the principal. */
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpiresAt: Date;
+  refreshTokenExpiresAt: Date;
+}
+/** Result returned by register/login flows. */
+interface AuthResult {
+  user: AuthenticatedIdentity;
+  tokens: AuthTokens;
+}
+/**
+ * Returned by `login` when the user has 2FA enabled and the TOTP code has not yet
+ * been verified. The client must call `verifyMfaChallenge` to complete the login.
+ */
+interface MfaRequiredResult {
+  kind: "mfa_required";
+  /** Short-lived signed token identifying the pending MFA session. */
+  mfaToken: string;
+}
+/** Union return type for the login flow — either a full session or an MFA challenge. */
+type LoginResult = AuthResult | MfaRequiredResult;
+/** Token type for email verification or password reset links. */
+type VerificationTokenType = "email_verification" | "password_reset";
+/** A short-lived opaque token stored by hash, used for email verification and password reset. */
+interface VerificationToken {
+  /** SHA-256 hash of the raw token (stored; raw token is sent to the user). */
+  tokenHash: string;
+  userId: string;
+  type: VerificationTokenType;
+  expiresAt: Date;
+  /** Set when the token has been consumed; consumed tokens cannot be reused. */
+  usedAt: Date | null;
+}
+/** Persisted TOTP secret for a user. */
+interface TotpSecret {
+  userId: string;
+  /** Base32-encoded TOTP secret key. */
+  secretBase32: string;
+  /** Set once the user has confirmed the TOTP code after setup. */
+  enabledAt: Date | null;
+  createdAt: Date;
+}
+/** Returned by the 2FA setup flow. Display the QR code / secret to the user. */
+interface TotpSetupResult {
+  /** Base32-encoded secret to show to the user (or encode as a QR code). */
+  secret: string;
+  /** OTP Auth URI suitable for QR code display in authenticator apps. */
+  otpAuthUri: string;
+}
+/** Verified access-token claims. */
+interface AccessTokenClaims {
+  /** Subject — the user id. */
+  sub: string;
+  /** Auth version the token was minted against. */
+  authVersion: number;
+  /** Issued-at (seconds since epoch). */
+  iat: number;
+  /** Expiry (seconds since epoch). */
+  exp: number;
+}
+//#endregion
+//#region core/verification-token.d.ts
+/** Input for persisting a new verification token. */
+interface CreateVerificationTokenInput {
+  /** SHA-256 hash of the raw token (never store the raw token). */
+  tokenHash: string;
+  userId: string;
+  type: VerificationTokenType;
+  expiresAt: Date;
+}
+/**
+ * Generates a cryptographically random opaque token and its SHA-256 hash.
+ * Returns both: the raw token is sent to the user; only the hash is persisted.
+ */
+declare function generateVerificationToken(): {
+  token: string;
+  tokenHash: string;
+};
+/** Hashes a token presented by the user for secure lookup against stored hashes. */
+declare function hashVerificationToken(token: string): string;
+//#endregion
+//#region core/identity-store.d.ts
+/** Fields required to create a new user (ids/timestamps are assigned by the service). */
+interface CreateIdentityUserInput {
+  userId: string;
+  email: string;
+  displayName: string | null;
+  status: IdentityUser["status"];
+  authVersion: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+/** Fields required to create a new refresh session. */
+interface CreateAuthSessionInput {
+  sessionId: string;
+  userId: string;
+  refreshTokenHash: string;
+  createdAt: Date;
+  expiresAt: Date;
+}
+/**
+ * Storage contract for `@azlib/identity`. Implement this against your own database
+ * engine (Postgres, MySQL, SQLite, Prisma, etc.). The package ships predefined schema
+ * artifacts under `@azlib/identity/schema/*` you can apply directly.
+ *
+ * Implementations must treat email lookups as case-insensitive and enforce uniqueness
+ * on email. All methods may be async.
+ */
+interface IdentityStore {
+  findUserByEmail(email: string): Promise<IdentityUser | null>;
+  findUserById(userId: string): Promise<IdentityUser | null>;
+  createUser(input: CreateIdentityUserInput): Promise<IdentityUser>;
+  updateUser(userId: string, patch: Partial<Pick<IdentityUser, "displayName" | "status" | "emailVerifiedAt" | "twoFactorEnabled" | "authVersion" | "failedLoginAttempts" | "lockedUntil">>): Promise<IdentityUser>;
+  findCredential(userId: string): Promise<CredentialRecord | null>;
+  upsertCredential(record: CredentialRecord): Promise<void>;
+  createSession(input: CreateAuthSessionInput): Promise<AuthSession>;
+  findSessionById(sessionId: string): Promise<AuthSession | null>;
+  /** Marks a session revoked (used during rotation and logout). */
+  revokeSession(sessionId: string, revokedAt: Date): Promise<void>;
+  /** Replaces the stored refresh-token hash for a session during rotation. */
+  rotateSession(sessionId: string, refreshTokenHash: string, expiresAt: Date): Promise<void>;
+  /** Revokes every active session for a user (e.g. password change / global logout). */
+  revokeAllSessions(userId: string, revokedAt: Date): Promise<void>;
+  listRolesForUser(userId: string): Promise<readonly Role[]>;
+  listPermissionsForUser(userId: string): Promise<readonly Permission[]>;
+  assignRole(assignment: UserRoleAssignment): Promise<void>;
+  grantRolePermission(grant: RolePermissionGrant): Promise<void>;
+  grantDirectPermission(grant: DirectPermissionGrant): Promise<void>;
+  /** Persists a new short-lived verification/reset token (stored as hash). */
+  createVerificationToken?(input: CreateVerificationTokenInput): Promise<void>;
+  /** Looks up a stored token by its SHA-256 hash. */
+  findVerificationToken?(tokenHash: string): Promise<VerificationToken | null>;
+  /** Marks a token as consumed so it cannot be reused. */
+  markVerificationTokenUsed?(tokenHash: string, usedAt: Date): Promise<void>;
+  /** Returns the pending or active TOTP secret for a user, or null if none. */
+  findTotpSecret?(userId: string): Promise<TotpSecret | null>;
+  /** Creates or replaces the TOTP secret for a user. */
+  upsertTotpSecret?(record: TotpSecret): Promise<void>;
+  /** Removes the TOTP secret, effectively disabling 2FA at the storage layer. */
+  deleteTotpSecret?(userId: string): Promise<void>;
+  recordEvent?(event: IdentityEvent): Promise<void>;
+  /**
+   * Finds the local user linked to a provider + provider user id. Returns null when
+   * no OAuth link exists yet.
+   */
+  findUserByOAuthId?(provider: string, providerUserId: string): Promise<IdentityUser | null>;
+  /** Persists a new OAuth link between a local user and their provider identity. */
+  createOAuthLink?(link: OAuthLinkedAccount): Promise<void>;
+  /** Lists all provider links for a user. */
+  listOAuthLinks?(userId: string): Promise<readonly OAuthLinkedAccount[]>;
+}
+//#endregion
+export { RolePermissionGrant as C, VerificationToken as D, UserRoleAssignment as E, VerificationTokenType as O, Role as S, TotpSetupResult as T, IdentityUserStatus as _, generateVerificationToken as a, OAuthLinkedAccount as b, AuthResult as c, AuthenticatedIdentity as d, CredentialRecord as f, IdentityUser as g, IdentityEventType as h, CreateVerificationTokenInput as i, AuthSession as l, IdentityEvent as m, CreateIdentityUserInput as n, hashVerificationToken as o, DirectPermissionGrant as p, IdentityStore as r, AccessTokenClaims as s, CreateAuthSessionInput as t, AuthTokens as u, LoginResult as v, TotpSecret as w, Permission as x, MfaRequiredResult as y };
+//# sourceMappingURL=identity-store-BRRahxcS.d.cts.map

package/dist/identity-store-BRRahxcS.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-store-BRRahxcS.d.cts","names":[],"sources":["../core/types.ts","../core/verification-token.ts","../core/identity-store.ts"],"mappings":"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"}