@lenne.tech/ng-base 18.1.3 → 22.0.0

package/types/lenne.tech-ng-base-auth-provide.d.ts

@@ -0,0 +1,603 @@
+import { CanActivateChildFn, CanActivateFn } from "@angular/router";
+import { HttpInterceptorFn } from "@angular/common/http";
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+/**
+ * Requires a signed-in user (auth-state cookie; on the server the request cookie). Otherwise redirects to
+ * `loginPath?redirect=<url>`. UI gating only: the backend authorises every request itself.
+ */
+export declare const ltAuthGuard: CanActivateFn & CanActivateChildFn;
+/** Only for signed-out users (login, register…); a signed-in user is redirected to `redirectTo` (default `/app`). */
+export declare function ltGuestGuard(redirectTo?: string): CanActivateFn & CanActivateChildFn;
+/** Requires one of the roles (`role` or `roles`); signed-out → login, missing role → `redirectTo` (default `/`). */
+export declare function ltRoleGuard(roles: string | string[], redirectTo?: string): CanActivateFn & CanActivateChildFn;
+/**
+ * First-admin setup redirect (enable with `provideLtAuth({ systemSetup: { enabled: true } })`), put it on the root
+ * route as `canActivateChild`. `needsSetup && httpInitEnabled !== false` → setup page; setup done but on the setup
+ * page → login page; errors never redirect.
+ */
+export declare const ltSystemSetupGuard: CanActivateFn & CanActivateChildFn;
+/**
+ * Session-loss detection shared by `ltAuthInterceptor` (HttpClient) and the auth-aware `LT_FETCH` (fetch, SSE, sync).
+ *
+ * On a 401 outside the auth endpoints and public pages while the state says signed in, it probes
+ * `GET /iam/get-session` (positive verdict cached 1 s): dead → `clearUser()` and a redirect to
+ * `loginPath?redirect=<current url>` (guard held 1 s), alive → nothing (in JWT mode the JWT is re-minted).
+ * A probe without verdict (network error, 429, 5xx) never logs out. Server: no-op.
+ */
+export declare class LtUnauthorizedHandler {
+  private readonly auth;
+  /** Handle a 401 for `url`. Resolves to `true` when the session was found dead and the user was redirected. */
+  handle(url?: string): Promise<boolean>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<LtUnauthorizedHandler, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * `HttpClient` interceptor for API requests (URLs under the configured API base):
+ * sends credentials, adds `Authorization: Bearer` in JWT mode (refreshed first when it is about to expire), retries once after a cookie → JWT switch or a JWT
+ * refresh, and hands an unrecoverable 401 to {@link LtUnauthorizedHandler}. A request that brings its own
+ * `Authorization` header keeps it and is not retried. Other URLs and server-side requests pass through unchanged.
+ *
+ * @example provideHttpClient(withInterceptors([ltAuthInterceptor]))
+ */
+export declare const ltAuthInterceptor: HttpInterceptorFn;
+/** Cookie names (exact names win over the `NG_PUBLIC_COOKIE_PREFIX` derived ones). */
+interface LtAuthCookieNamesOptions {
+  /** Auth-state cookie (default `lt-auth-state`, or `<prefix>-auth-state`). */
+  state?: string;
+  /** JWT cookie (default `lt-jwt-token`, or `<prefix>-jwt-token`). */
+  token?: string;
+}
+/** Options of `provideLtAuth()`; runtime overrides via `NG_PUBLIC_LT_AUTH_*`. */
+interface LtAuthOptions {
+  /** Better Auth base path, must equal nest-server `betterAuth.basePath` (default `/iam`). */
+  basePath?: string;
+  /** Cookie names. */
+  cookieNames?: LtAuthCookieNamesOptions;
+  /**
+   * Register Better Auth's `adminClient()` plugin (default **`false`**). nest-server does not serve the admin plugin
+   * today (routes 404), and its methods are not hashed. Enable only together with a backend that registers `admin()`.
+   */
+  enableAdmin?: boolean;
+  /**
+   * Offer passkeys (default `true`); `false` makes `passkeySupported()` false. The passkey flows call
+   * `/iam/passkey/*` directly, so `@better-auth/passkey` is not needed (add `passkeyClient()` via `plugins` if wanted).
+   */
+  enablePasskey?: boolean;
+  /** Register the two-factor plugin (default `true`). */
+  enableTwoFactor?: boolean;
+  /** 401 handling. */
+  interceptor?: {
+    /** Detect session loss on 401 and redirect to the login page (default `true`). */
+    enabled?: boolean;
+    /** Extra route prefixes on which a 401 never logs out (merged with the built-in auth pages). */
+    publicPaths?: string[];
+  };
+  /** Login page (default `/auth/login`). */
+  loginPath?: string;
+  /** Extra Better Auth client plugins (same as `registerLtAuthPlugins()`). */
+  plugins?: unknown[];
+  /** First-admin setup flow. */
+  systemSetup?: {
+    /** Enable the setup redirect of `ltSystemSetupGuard` (default `false`). */
+    enabled?: boolean;
+    /** Setup page (default `/auth/setup`). */
+    setupPath?: string;
+  };
+  /** Where a sign-in that needs a second factor redirects (default `/auth/2fa`). */
+  twoFactorRedirectPath?: string;
+}
+/** Fully resolved auth options. */
+interface LtResolvedAuthOptions {
+  basePath: string;
+  cookieNames: Required<LtAuthCookieNamesOptions>;
+  enableAdmin: boolean;
+  enablePasskey: boolean;
+  enableTwoFactor: boolean;
+  interceptor: {
+    enabled: boolean;
+    publicPaths: string[];
+  };
+  loginPath: string;
+  plugins: unknown[];
+  systemSetup: {
+    enabled: boolean;
+    setupPath: string;
+  };
+  twoFactorRedirectPath: string;
+}
+/** Default name of the auth-state cookie. */
+export declare const LT_AUTH_STATE_COOKIE_DEFAULT = "lt-auth-state";
+/** Default name of the JWT cookie. */
+export declare const LT_JWT_TOKEN_COOKIE_DEFAULT = "lt-jwt-token";
+/** Defaults of {@link LtAuthOptions}. */
+export declare const LT_AUTH_DEFAULTS: LtResolvedAuthOptions;
+/** Options passed to `provideLtAuth()` (raw). */
+export declare const LT_AUTH_INPUT_OPTIONS: InjectionToken<LtAuthOptions>;
+/**
+ * Resolved auth options: defaults ← `provideLtAuth(options)` ← runtime `NG_PUBLIC_LT_AUTH_*`; cookie names derived
+ * from `NG_PUBLIC_COOKIE_PREFIX` unless set explicitly.
+ */
+export declare const LT_AUTH_OPTIONS: InjectionToken<LtResolvedAuthOptions>;
+/** Sanitise a cookie prefix to RFC 6265 token characters (`[A-Za-z0-9._-]`). */
+export declare function resolveLtCookiePrefix(raw: unknown): string;
+/**
+ * Cookie names: an explicit non-default name wins, else `<prefix>-auth-state` / `<prefix>-jwt-token`, else the defaults.
+ * Mirror the prefix on the backend (`COOKIE_PREFIX`) so both sides agree.
+ */
+export declare function resolveLtAuthCookieNames(configured: LtAuthCookieNamesOptions | undefined, cookiePrefix?: unknown): Required<LtAuthCookieNamesOptions>;
+/** User as delivered by nest-server's Better Auth integration (`/iam`). Additional fields are kept. */
+interface LtUser {
+  banExpires?: Date | string;
+  banned?: boolean;
+  banReason?: string;
+  email: string;
+  emailVerified?: boolean;
+  id: string;
+  image?: string;
+  name?: string;
+  role?: string;
+  roles?: string[];
+  twoFactorEnabled?: boolean;
+  [key: string]: unknown;
+}
+/** User input of `setUser()`; `image: null` (Better Auth) is normalised to `undefined`. */
+type LtUserInput = Omit<LtUser, 'image'> & {
+  image?: null | string;
+};
+/** Auth transport: session cookie (default) or JWT Bearer token (fallback when cookies do not work). */
+type LtAuthMode = 'cookie' | 'jwt';
+/** Content of the client-readable auth-state cookie (`lt-auth-state`). A UI cache, never a security boundary. */
+interface LtAuthState {
+  authMode: LtAuthMode;
+  user: LtUser | null;
+}
+/** Feature flags of nest-server (`GET /iam/features`), e.g. `emailVerification`, `passkey`, `signUpChecks`. */
+type LtAuthFeatures = Record<string, boolean | number | string | string[]>;
+/** Result envelope of the Better Auth client (`{ data, error }`). */
+interface LtAuthResponse<T = LtAuthResponseData> {
+  data?: T | null;
+  error?: LtAuthError | null;
+}
+/** Data of a sign-in/sign-up response (Better Auth's native fields plus nest-server's own). */
+interface LtAuthResponseData {
+  /** nest-server, sign-up: the email must be verified first; the session was revoked, nobody is signed in. */
+  emailVerificationRequired?: boolean;
+  redirect?: boolean;
+  /** nest-server, sign-in: a second factor is required (navigate to the 2FA page; no user is set). */
+  requiresTwoFactor?: boolean;
+  /** nest-server: whether the call succeeded (`false` together with `requiresTwoFactor`). */
+  success?: boolean;
+  /**
+   * nest-server with `cookies: false` (or `exposeTokenInBody`): the JWT for the Bearer header. Better Auth's native
+   * answers carry the opaque session token here, which is never used as JWT.
+   */
+  token?: string | null;
+  /** Set together with `twoFactorRedirect` when the account needs a second factor. */
+  twoFactorRedirect?: boolean;
+  url?: string;
+  user?: LtUser;
+  [key: string]: unknown;
+}
+/** Better Auth error (`{ code, message, status }`); nest-server messages may carry a `#LTNS_xxxx:` marker. */
+interface LtAuthError {
+  code?: string;
+  message?: string;
+  status?: number;
+  statusText?: string;
+}
+/** Result of `LtAuthService.authenticateWithPasskey()`. */
+interface LtPasskeyAuthResult {
+  error?: string;
+  session?: {
+    token: string;
+  };
+  success: boolean;
+  user?: LtUser;
+}
+/** Result of `LtAuthService.registerPasskey()`. */
+interface LtPasskeyRegisterResult {
+  error?: string;
+  passkey?: unknown;
+  success: boolean;
+}
+/** A registered passkey (`passkey.listUserPasskeys()`). */
+interface LtPasskey {
+  backedUp?: boolean;
+  createdAt?: Date | string;
+  deviceType?: string;
+  id: string;
+  name?: string | null;
+  [key: string]: unknown;
+}
+/** Result of `twoFactor.enable()`: TOTP URI for the QR code plus the backup codes. */
+interface LtTwoFactorEnableResult {
+  backupCodes: string[];
+  totpURI: string;
+}
+/**
+ * Blocks stray plaintext credential keys at compile time: a param object may only carry the credential fields its
+ * method hashes. `{ ...form }` with an extra `password` on `requestPasswordReset` is a type error instead of a leak.
+ */
+type LtNoStrayCredential<T, Own extends string> = Omit<{
+  currentPassword?: never;
+  newPassword?: never;
+  password?: never;
+}, Own> & T;
+/** Per-call fetch options forwarded to Better Auth (`fetchOptions`). */
+interface LtAuthCallOptions {
+  /** Abort the request. */
+  signal?: AbortSignal;
+  /** Extra headers. */
+  headers?: Record<string, string>;
+  [key: string]: unknown;
+}
+/** Response of `GET /system-setup/status`. */
+interface LtSystemSetupStatus {
+  httpInitEnabled?: boolean;
+  httpInitTokenRequired?: boolean;
+  needsSetup: boolean;
+}
+/** Body of `initSetup()`; the password is hashed, the token is sent as `X-System-Setup-Token`. */
+interface LtSystemSetupInput {
+  email: string;
+  name: string;
+  password: string;
+  token?: string;
+}
+/** Lifetime of the auth-state and JWT cookies (7 days). */
+export declare const LT_AUTH_COOKIE_MAX_AGE: number;
+/**
+ * Resolve the auth state from a raw cookie string, tolerating several cookies of the same name.
+ *
+ * A host-only cookie and a domain-scoped twin can coexist and disagree; the one carrying a `user` wins. Preferring the
+ * user-less twin caused random logouts in the Nuxt stack. `lt-auth-state` is a UI cache, the session itself is the
+ * httpOnly `iam.session_token`, so a forged cookie yields at most a UI that looks signed in while every API call 401s.
+ */
+export declare function resolveLtAuthState(cookieString: string, stateCookieName: string): LtAuthState | null;
+/**
+ * Read/write access to the auth cookies (`lt-auth-state`, `lt-jwt-token`) with the duplicate-tolerant read and the
+ * SSR no-write rule. The server reads the request cookies and never writes.
+ */
+export declare class LtAuthStateService {
+  private readonly cookies;
+  private readonly options;
+  private readonly document;
+  private readonly isServer;
+  /** Cookie names in use. */
+  get cookieNames(): {
+    state: string;
+    token: string;
+  };
+  /** Current auth state from the cookies (`null` when none). */
+  readState(): LtAuthState | null;
+  /** Write the auth state (browser only; never writes a user-less state during SSR). */
+  writeState(state: LtAuthState): void;
+  /** Auth mode from the state cookie; `cookie` when unknown. */
+  getAuthMode(): LtAuthMode;
+  /** Merge `authMode` into the state cookie (keeps the user). */
+  setAuthMode(mode: LtAuthMode): void;
+  /**
+   * First JWT of the token cookie(s), or `null`. Browser only. A value that is not JWT-shaped (e.g. an opaque Better Auth
+   * session token an older version stored) is never returned and is deleted.
+   */
+  getJwtToken(): string | null;
+  /**
+   * Store or clear the JWT (7 days). Browser only. Only JWT-shaped values are accepted: the token cookie is readable by
+   * scripts, so an opaque session token (the body of `two-factor/*` or `passkey/*` answers) must never land there.
+   * Returns whether the value was stored.
+   */
+  setJwtToken(token: string | null): boolean;
+  /**
+   * Delete a stored token that is not JWT-shaped and fall back to cookie mode (run at startup in the browser). Returns
+   * whether something was purged.
+   */
+  purgeInvalidJwt(): boolean;
+  /** Whether any state cookie carries a user. */
+  isAuthenticated(): boolean;
+  /** The user from the state cookie. */
+  readUser(): LtUser | null;
+  /**
+   * Delete the auth-state and JWT cookies on the host-only and the `domain=<host>` slot, and best-effort the Better Auth
+   * cookies on the usual paths. Browser only.
+   */
+  clearAuthCookies(): void;
+  private deleteEverywhere;
+  static ɵfac: i0.ɵɵFactoryDeclaration<LtAuthStateService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Hooks around `signOut()`. `provideLtSync()` registers one that flushes the offline outbox before the session ends and
+ * deletes the IndexedDB afterwards; projects can add their own (multi provider).
+ */
+interface LtAuthSignOutHook {
+  /** Runs before `POST /iam/sign-out` with the id of the signed-in user (errors are logged, never block sign-out). */
+  beforeSignOut?(userId: string | null): Promise<void> | void;
+  /** Runs after the local state was cleared. */
+  afterSignOut?(): Promise<void> | void;
+}
+/** Sign-out hooks (multi). */
+export declare const LT_AUTH_SIGN_OUT_HOOKS: InjectionToken<LtAuthSignOutHook[]>;
+/** TransferState key of the feature flags fetched during SSR. */
+export declare const LT_AUTH_FEATURES_STATE_KEY: import("@angular/core").StateKey<LtAuthFeatures>;
+/** Upper bound for `validateSession()` waiting on `GET /iam/get-session`. */
+export declare const LT_VALIDATE_SESSION_TIMEOUT_MS = 10000;
+/** What a sign-in / sign-up answer says (nest-server's own shape and Better Auth's native one). */
+interface LtAuthAnswer {
+  /** Sign-up with email verification: nest-server revoked the session, nobody is signed in yet. */
+  emailVerificationRequired: boolean;
+  /** A JWT the server put into the body on purpose (`cookies: false` or `exposeTokenInBody` with the JWT plugin). */
+  jwt: string | null;
+  /** The answer proves a session (`success: true`, a token or a session object) and reports no failure. */
+  session: boolean;
+  /** A second factor is required (`requiresTwoFactor` from nest-server, `twoFactorRedirect` from Better Auth). */
+  twoFactor: boolean;
+  user: LtUserInput | null;
+}
+/**
+ * Read a sign-in / sign-up answer, either the Better Auth client envelope (`{ data, error }`) or a raw body.
+ *
+ * nest-server answers `{ requiresTwoFactor, success, user }` (the token is removed from the body while cookies are on),
+ * `{ requiresTwoFactor: true, success: false }` when 2FA is required and `{ emailVerificationRequired: true, user }`
+ * after a sign-up whose session it revoked. Better Auth's native answers carry `twoFactorRedirect` or
+ * `{ token: <opaque session token>, user }`. Only a JWT-shaped body token counts as JWT: an opaque session token never
+ * becomes a bearer kept in a script-readable cookie.
+ */
+export declare function readLtAuthAnswer(result: unknown): LtAuthAnswer;
+/**
+ * The light half of authentication: session state, transport and session validation, without Better Auth.
+ *
+ * Guards, `ltAuthInterceptor`, `provideLtAuth()` (and through it `LT_FETCH`) and offline sync use this store, so an
+ * app's initial bundle carries no passkey, 2FA or Better Auth code. `LtAuthService` (`@lenne.tech/ng-base/auth`)
+ * exposes the same state and methods and adds the Better Auth flows; both read and write the same signals.
+ *
+ * State is signal-based and backed by the client-readable `lt-auth-state` cookie, so SSR renders the signed-in shell
+ * from the request cookie (UI gating only; the session itself is the httpOnly `iam.session_token`). Transport: session
+ * cookie first; when cookies do not work (401 while the state says signed in) the store switches to JWT mode
+ * (`GET /iam/token`, Bearer header) and refreshes a stale JWT once per burst. nest-server with `cookies: false` answers
+ * every sign-in with a JWT, which puts the store into JWT mode directly; session checks never change the mode, and a
+ * JWT close to its expiry is refreshed with itself as bearer before it is sent.
+ */
+export declare class LtAuthStore {
+  private readonly api;
+  private readonly authState;
+  private readonly options;
+  private readonly runtimeConfig;
+  private readonly transferState;
+  private readonly injector;
+  private readonly document;
+  private readonly signOutHooks;
+  private readonly isServer;
+  /** A non-JWT value in the JWT cookie (opaque session token from an older version) is deleted before anything reads it. */
+  private readonly purgedInvalidJwt;
+  private readonly initialState;
+  private readonly transferredFeatures;
+  private readonly userState;
+  private readonly modeState;
+  private readonly loadingState;
+  private readonly featuresState;
+  private featuresLoaded;
+  private featuresRequest;
+  /** In-flight `GET /token` shared by every 401 of a burst (cookie → JWT switch and stale-JWT refresh alike). */
+  private jwtMint;
+  private readonly sessionLoss;
+  /** Signed-in user (from the auth-state cookie, refreshed by `validateSession()` and every sign-in). */
+  readonly user: Signal<LtUser | null>;
+  /** Whether a user is signed in (UI gating; the backend decides). */
+  readonly isAuthenticated: Signal<boolean>;
+  /** Current transport. */
+  readonly authMode: Signal<LtAuthMode>;
+  /** Whether the JWT fallback is active. */
+  readonly isJwtMode: Signal<boolean>;
+  /** Whether a sign-in/up/out or passkey flow is running. */
+  readonly isLoading: Signal<boolean>;
+  /** Whether the user has the `admin` role (UX gate only). */
+  readonly isAdmin: Signal<boolean>;
+  /** Whether two-factor authentication is enabled for the user. */
+  readonly is2FAEnabled: Signal<boolean>;
+  /** nest-server feature flags (`GET /iam/features`); fetched on the server and transferred to the browser. */
+  readonly features: Signal<LtAuthFeatures>;
+  /** Whether passkeys can be used: enabled in the options, backend feature on and WebAuthn available in this browser. */
+  readonly passkeySupported: Signal<boolean>;
+  /** The current JWT (JWT mode only), or `null`. */
+  jwtToken(): string | null;
+  /** `user.role === role` or `user.roles` contains it (case-sensitive). */
+  hasRole(role: string): boolean;
+  /** Whether the user has any of the roles. */
+  hasAnyRole(...roles: string[]): boolean;
+  /**
+   * Fetch the feature flags (`GET /iam/features`, anonymous). One request in flight at a time; errors keep the last
+   * known flags. On the server the result is put into `TransferState` for the browser. SSR without API URL: no fetch.
+   */
+  fetchFeatures(): Promise<LtAuthFeatures>;
+  /** The feature flags, fetched at most once (transferred from SSR, or fetched on first call). */
+  ensureFeatures(): Promise<LtAuthFeatures>;
+  /** Store the user in state and cookie (browser always; SSR never writes). `image: null` becomes `undefined`. */
+  setUser(user: LtUserInput | null, mode?: LtAuthMode): void;
+  /** Clear local auth state and cookies (browser). Does not delete offline data (use `signOut()` for that). */
+  clearUser(): void;
+  /**
+   * Sign out: sign-out hooks (offline sync flush), `POST /iam/sign-out`, local state cleared, after-hooks (sync wipe).
+   * The request is a plain {@link fetchWithAuth} call, so signing out never loads Better Auth. The local state is
+   * cleared even when the request fails (offline device): the failure is logged, not thrown.
+   */
+  signOut(options?: LtAuthCallOptions): Promise<void>;
+  /**
+   * Validate the session (app start / hard reload). Server: answers from the cookie, no backend call. Browser:
+   * `GET /iam/get-session` (≤ 10 s, plain {@link fetchWithAuth}); a user is merged with the cached one
+   * (nest-server-only fields kept, authz keys fail-closed); no user but a cached one → `true` (e.g. right after 2FA);
+   * else `false`.
+   */
+  validateSession(): Promise<boolean>;
+  /**
+   * The auth-aware fetch (also provided as `LT_FETCH` by `provideLtAuth()` and used by the Better Auth client).
+   *
+   * For API URLs (see {@link isLtApiRequest}): cookie mode sends `credentials: 'include'`; JWT mode adds
+   * `Authorization: Bearer` and omits cookies except for passkey/2FA/`get-session` (an explicit `init.credentials`
+   * wins). On a 401 while signed in: cookie mode → switch to JWT and retry once; JWT mode → one shared refresh per
+   * burst and retry once. A 401 that survives is handed to the session-loss detection. Auth-flow endpoints
+   * (sign-in, 2FA, …) are never retried: their 401 is the flow's verdict. Other URLs are fetched unchanged (no token).
+   */
+  fetchWithAuth(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  /**
+   * Token to retry a request with after a 401, or `null` when no retry makes sense (server, auth-flow endpoint, not
+   * signed in, cookie-bound path in JWT mode, no token obtainable). `sentToken` is the bearer the request carried
+   * (`null` in cookie mode). Used by {@link fetchWithAuth} and `ltAuthInterceptor`.
+   */
+  recoverFrom401(url: string, sentToken: string | null): Promise<string | null>;
+  /** Session-loss handling for a 401 from `url` (see `LtUnauthorizedHandler`). */
+  handleUnauthorized(url?: string): Promise<boolean>;
+  /** `GET /iam/token` → store the JWT and switch to JWT mode. One request per burst. Browser only. */
+  switchToJwtMode(): Promise<boolean>;
+  /** Re-mint the JWT (JWT mode only). */
+  refreshJwtToken(): Promise<boolean>;
+  /**
+   * Build an absolute app URL from `NG_PUBLIC_SITE_URL` (or the browser origin), for `redirectTo` / `callbackURL`.
+   * Never derived from the request: on the server without a site URL it throws. Absolute input is returned unchanged.
+   */
+  absoluteAppUrl(path: string): string;
+  /** Full URL of a Better Auth route (`/get-session` → `<api>/iam/get-session`). */
+  authUrl(path: string): string;
+  /** Run `task` with `isLoading()` set. */
+  withLoading<T>(task: () => Promise<T>): Promise<T>;
+  /**
+   * Apply a sign-in / sign-up answer (see {@link readLtAuthAnswer}). No user is set when a second factor or an email
+   * verification is pending, or when the answer proves no session. A JWT-shaped body token → JWT mode; otherwise
+   * cookie mode plus a background JWT from `GET /iam/token` (cookie stays primary). `true` when a user was set.
+   */
+  applyAuthResult(result: unknown): boolean;
+  /**
+   * Take a session another flow already proved (2FA verification, passkey sign-in), as after a password sign-in:
+   * a JWT-shaped `token` in the answer (nest-server with `cookies: false` or `exposeTokenInBody`) → JWT mode; otherwise
+   * cookie mode plus a background JWT. Any other token is Better Auth's opaque session token and is never kept. An
+   * answer without user loads it from `GET /iam/get-session` (with the bearer in JWT mode). Resolves to the user, or
+   * `undefined` when no session could be loaded (local state then stays signed out).
+   */
+  adoptVerifiedSession(result: unknown): Promise<LtUser | undefined>;
+  /**
+   * Load the user via `GET /iam/get-session`, merge it with the cached one and store it, in `mode` (default: the
+   * current mode; the session answer proves the session, not the transport).
+   */
+  loadSessionUser(mode?: LtAuthMode): Promise<LtUser | undefined>;
+  /**
+   * The JWT to send (JWT mode only, else `null`), refreshed first when it expires within
+   * {@link LT_JWT_REFRESH_MARGIN_MS} (one refresh per burst; the old token is kept when the refresh fails).
+   */
+  currentJwt(): Promise<string | null>;
+  /** Whether the JWT of JWT mode expires within {@link LT_JWT_REFRESH_MARGIN_MS} (browser only). */
+  jwtNeedsRefresh(): boolean;
+  /**
+   * Navigate to `path` and keep the `redirect` query parameter of the current URL (login → 2FA must not lose where the
+   * user wanted to go). A `redirect` already in `path` wins; only app-relative targets (`/…`, not `//…`) are kept.
+   */
+  navigateKeepingRedirect(path: string): void;
+  /** Navigate within the app (Router when available, else a full page load in the browser). */
+  navigate(url: string): void;
+  /**
+   * Merge a session user onto the cached user of the SAME identity: nest-server-only fields survive, authorization
+   * keys always reflect the session. A different / absent / id-less identity yields the session user verbatim.
+   */
+  private mergeSessionUser;
+  /** Cached user: the duplicate-tolerant cookie view, else the in-memory state. */
+  private cachedUser;
+  /** `GET /iam/get-session` with the session cookie (bearer too in JWT mode); `null` without a session. */
+  private fetchSession;
+  /** Mint a JWT and switch to JWT mode; one `GET /token` per burst. */
+  private mintJwt;
+  /** Fetch a JWT in the background so it is ready as fallback; keeps the current mode (cookie stays primary). */
+  private prefetchJwt;
+  /**
+   * `GET <auth>/token` with the session cookie and, in JWT mode, the current JWT as bearer while it is still valid
+   * (with `cookies: false` the bearer is the only proof of the session); the token or `null`.
+   */
+  private requestJwt;
+  private loadFeatures;
+  private send;
+  private persistState;
+  private currentUrl;
+  static ɵfac: i0.ɵɵFactoryDeclaration<LtAuthStore, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** `user.role === role` or `user.roles` (array) contains it; malformed shapes → `false`. */
+export declare function hasLtRole(user: LtUser | null | undefined, role: string): boolean;
+/** Built-in route prefixes on which a 401 never logs out (auth pages). Extend via `provideLtAuth({ interceptor: { publicPaths } })`. */
+export declare const LT_AUTH_PUBLIC_PATHS: readonly string[];
+/** API path fragments whose 401 is part of a normal auth flow (never treated as session loss). */
+export declare const LT_AUTH_ENDPOINT_FRAGMENTS: readonly string[];
+/**
+ * Paths that need the session cookie even in JWT mode: passkey and 2FA challenges are bound to cookies, and
+ * `/get-session` resolves the session from the cookie only (a bearer-only request gets `200 null`, which the session
+ * probe would read as "dead" for every user in JWT mode).
+ */
+export declare const LT_AUTH_COOKIE_PATHS: readonly string[];
+/** Whether a 401 from `url` belongs to an auth flow (wrong password, wrong code, probe) rather than a lost session. */
+export declare function isLtAuthEndpoint(url: string): boolean;
+/**
+ * Whether `url` goes to the API, so it may carry credentials and the Bearer token:
+ *
+ * - it starts with the API base URL at a path boundary (`https://api.example.com` matches `https://api.example.com/x`,
+ *   never `https://api.example.com.evil.test`);
+ * - or it is same-origin and starts with `/api` (dev proxy);
+ * - or no API URL is configured and it is same-origin (same-origin reverse proxy).
+ *
+ * Absolute URLs on `origin` are compared by their path. Foreign hosts never get the token.
+ */
+export declare function isLtApiRequest(url: string, baseUrl: string, origin?: string | null): boolean;
+/**
+ * Auth providers: options, the auth-aware `LT_FETCH` (Bearer in JWT mode, JWT switch/refresh, session-loss handling)
+ * used by error translation, AI, sync and the Better Auth client, session validation and feature flags at startup
+ * (features fetched on the server and transferred), and the user restored from the auth-state cookie.
+ *
+ * Startup: the server fetches the feature flags (bounded, anonymous) before rendering and transfers them; the browser
+ * takes them from `TransferState` (fetching only when nothing was transferred) and validates the session in the
+ * background, so the first render is never held up by the backend.
+ *
+ * Add `ltAuthInterceptor` to `provideHttpClient(withInterceptors([...]))` for `HttpClient` calls (generated API client).
+ */
+export declare function provideLtAuth(options?: LtAuthOptions): EnvironmentProviders;
+/** TransferState key of the setup status read during SSR. */
+export declare const LT_SYSTEM_SETUP_STATE_KEY: import("@angular/core").StateKey<LtSystemSetupStatus>;
+/** Header that carries the setup token. Sent unhashed and never in the body (the server compares it as given). */
+export declare const LT_SYSTEM_SETUP_TOKEN_HEADER = "X-System-Setup-Token";
+/**
+ * Error thrown by `initSetup()` for a non-2xx answer. `data` is the response body, so
+ * `LtErrorTranslationService.translateError(error)` reads its `#LTNS_xxxx` code (`LTNS_0053` HTTP setup disabled,
+ * `LTNS_0054` wrong token).
+ */
+interface LtSystemSetupError extends Error {
+  data: unknown;
+  status: number;
+  statusCode: number;
+}
+/**
+ * First-admin setup of nest-server (`/system-setup/*`), the counterpart of `useSystemSetup()`.
+ * Status is fetched once and transferred SSR → browser.
+ */
+export declare class LtSystemSetupService {
+  private readonly api;
+  private readonly fetch;
+  private readonly transferState;
+  private readonly isServer;
+  private readonly transferred;
+  private readonly needsSetupState;
+  private readonly httpInitEnabledState;
+  private readonly httpInitTokenRequiredState;
+  private statusRequest;
+  /** `true` when no admin exists yet; `null` until checked. */
+  readonly needsSetup: import("@angular/core").Signal<boolean | null>;
+  /** Whether HTTP init is open (nest-server ≥ 12.4; `true` for older APIs); `null` until checked. */
+  readonly httpInitEnabled: import("@angular/core").Signal<boolean | null>;
+  /** Whether HTTP init requires `X-System-Setup-Token`; `null` until checked. */
+  readonly httpInitTokenRequired: import("@angular/core").Signal<boolean | null>;
+  /** `GET /system-setup/status`. Errors/404 → `needsSetup = false`. SSR without API URL → `false` without fetching. */
+  checkSetupStatus(): Promise<LtSystemSetupStatus>;
+  /**
+   * `POST /system-setup/init` with `{ email, password: sha256, name }`; the token (trimmed, unhashed) goes into
+   * `X-System-Setup-Token`. On 403 the status is re-read and the error rethrown (`LTNS_0053` disabled, `LTNS_0054` wrong token).
+   */
+  initSetup(input: LtSystemSetupInput): Promise<void>;
+  private loadStatus;
+  static ɵfac: i0.ɵɵFactoryDeclaration<LtSystemSetupService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export type { LtAuthAnswer, LtAuthCallOptions, LtAuthCookieNamesOptions, LtAuthError, LtAuthFeatures, LtAuthMode, LtAuthOptions, LtAuthResponse, LtAuthResponseData, LtAuthSignOutHook, LtAuthState, LtNoStrayCredential, LtPasskey, LtPasskeyAuthResult, LtPasskeyRegisterResult, LtResolvedAuthOptions, LtSystemSetupError, LtSystemSetupInput, LtSystemSetupStatus, LtTwoFactorEnableResult, LtUser, LtUserInput };