@awesome-lang-auth/node 1.10.1

package/dist/router/admin.router.d.ts

@@ -0,0 +1,188 @@
+import { Router, RequestHandler } from 'express';
+import { IUserStore } from '../interfaces/user-store.interface';
+import { ISessionStore } from '../interfaces/session-store.interface';
+import { IRolesPermissionsStore } from '../interfaces/roles-permissions-store.interface';
+import { ITenantStore } from '../interfaces/tenant-store.interface';
+import { IUserMetadataStore } from '../interfaces/user-metadata-store.interface';
+import { ISettingsStore } from '../interfaces/settings-store.interface';
+import { ILinkedAccountsStore } from '../interfaces/linked-accounts-store.interface';
+import { IApiKeyStore } from '../interfaces/api-key-store.interface';
+import { IWebhookStore } from '../interfaces/webhook-store.interface';
+import { ITemplateStore } from '../interfaces/template-store.interface';
+import { BaseUser } from '../models/user.model';
+import { AuthEventBus } from '../events/auth-event-bus';
+export type AuthorizedAdminUser = BaseUser & {
+    roles: string[];
+};
+/**
+ * Policy that controls who may access the Admin UI and REST API.
+ *
+ * | Value | Description |
+ * |-------|-------------|
+ * | `'first-user'` | Only the first registered user (lowest-ID) is granted access. Ideal for single-owner setups. |
+ * | `'is-admin-flag'` | Only users with `BaseUser.isAdmin === true` are granted access. |
+ * | `'open'` | No restriction — all authenticated users are granted access.  Use only behind a VPN or IP allow-list. |
+ * | `(user, rbacStore?) => Promise<boolean>` | Custom async predicate.  Return `true` to grant access. |
+ *
+ * When `accessPolicy` is set the guard validates the request JWT (using
+ * `jwtSecret`).  Unauthenticated requests get `401`, except a browser request
+ * for the HTML panel, which is redirected to `loginPath` when it is set and
+ * otherwise shows the panel's built-in sign-in form.
+ *
+ * @since 1.8.0
+ */
+export type AdminAccessPolicy = 'first-user' | 'is-admin-flag' | 'open' | ((user: AuthorizedAdminUser, rbacStore?: IRolesPermissionsStore) => boolean | Promise<boolean>);
+export interface AdminOptions {
+    /**
+     * Secret token required to access all admin endpoints.
+     * Pass as a Bearer token: `Authorization: Bearer <adminSecret>`
+     * The HTML UI presents a login form that stores the token in sessionStorage.
+     *
+     * Must be non-empty: without `accessPolicy`, `createAdminRouter` throws when
+     * `adminSecret` is present but empty (`''`, or `undefined` from an unset
+     * environment variable).  With `accessPolicy` it is only the bootstrap
+     * credential of `POST /login`, and an empty value disables it.
+     *
+     * @deprecated Use `accessPolicy` + `jwtSecret` instead (v1.8.0+).
+     *   `adminSecret` will be removed in a future major version.
+     *   It is still fully functional for backward compatibility.
+     */
+    adminSecret?: string;
+    /**
+     * Access control policy that governs who may use the Admin UI and API.
+     *
+     * When set, the guard validates the request JWT (`Authorization: Bearer <token>`
+     * or the `accessToken` cookie).  A request without a valid session gets
+     * `401`, except a browser request for the HTML panel (`GET <adminPath>/`),
+     * which is redirected to `loginPath` when it is set and otherwise shows the
+     * panel's built-in sign-in form.
+     *
+     * Requires `jwtSecret` to be set when using any policy other than `'open'`.
+     *
+     * @since 1.8.0
+     */
+    accessPolicy?: AdminAccessPolicy;
+    /**
+     * JWT secret used to verify the access token when `accessPolicy` is set.
+     *
+     * Must match `AuthConfig.accessTokenSecret` (the same secret used to sign
+     * tokens during login).  Not required when `accessPolicy` is `'open'`.
+     *
+     * @since 1.8.0
+     */
+    jwtSecret?: string;
+    /** Optional session store — enables the Sessions tab in the admin UI. */
+    sessionStore?: ISessionStore;
+    /** Optional RBAC store — enables the Roles & Permissions tab and user-role assignment. */
+    rbacStore?: IRolesPermissionsStore;
+    /** Optional tenant store — enables the Tenants tab and user-tenant assignment. */
+    tenantStore?: ITenantStore;
+    /**
+     * Optional user-metadata store — enables the Metadata section in the user detail
+     * panel (view and edit arbitrary per-user key/value data).
+     */
+    userMetadataStore?: IUserMetadataStore;
+    /** Optional settings store — enables the ⚙️ Control tab in the admin UI. */
+    settingsStore?: ISettingsStore;
+    /**
+     * Optional linked-accounts store — enables the Linked Accounts column in the
+     * users table and the Linked Accounts section in the user detail panel.
+     */
+    linkedAccountsStore?: ILinkedAccountsStore;
+    /**
+     * Optional prefix for the authentication cookies (e.g. `__Host-` or `__Secure-`).
+     * If provided, the guard will look for `${cookiePrefix}accessToken`.
+     * If not provided, it will try the default variants.
+     *
+     * @since 1.8.1
+     */
+    cookiePrefix?: string;
+    /**
+     * Optional root user for the Admin UI.
+     * Useful for bootstrapping or in environments without local users.
+     *
+     * @since 1.8.1
+     */
+    rootUser?: {
+        email: string;
+        /** Bcrypt-hashed password. */
+        passwordHash: string;
+    };
+    /**
+     * Optional API Key store — enables the 🔑 API Keys tab in the admin UI.
+     * Requires `IApiKeyStore.listAll` for listing and optionally `delete` for hard deletion.
+     */
+    apiKeyStore?: IApiKeyStore;
+    /**
+     * Optional webhook store — enables the 🔗 Webhooks tab in the admin UI.
+     * Requires `IWebhookStore.listAll` for listing and optionally `add`/`remove`/`update`
+     * for full management.
+     */
+    webhookStore?: IWebhookStore;
+    /** Optional template store — enables the Email & UI tab in the admin UI. */
+    templateStore?: ITemplateStore;
+    /** Optional directory for uploaded assets (e.g. logos). */
+    uploadDir?: string;
+    /**
+     * Public base URL where uploaded assets (stored in `uploadDir`) are served
+     * by the UI router.  This must match where `buildUiRouter` is mounted plus
+     * `/assets/uploads`, e.g. `'/auth/ui/assets/uploads'` when the UI router is
+     * mounted at `'/auth/ui'`.
+     *
+     * When set, the upload endpoints return a ready-to-use browser URL:
+     *   `<uploadBaseUrl>/<filename>`
+     *
+     * When omitted the endpoints still return the filename so callers can
+     * construct the URL themselves.
+     *
+     * @example '/auth/ui/assets/uploads'
+     */
+    uploadBaseUrl?: string;
+    /**
+     * Optional auth event bus. When provided, admin-side auth and RBAC events are
+     * published automatically.
+     */
+    eventBus?: AuthEventBus;
+    /**
+     * The base path where the main auth router is mounted.
+     * Used to automatically compute uploadBaseUrl if not provided.
+     * @default '/auth'
+     */
+    apiPrefix?: string;
+    /**
+     * Enable Swagger UI (`GET /api/openapi.json`, `GET /api/docs`) on the admin router.
+     *
+     * - `true`   — always enabled
+     * - `false`  — always disabled
+     * - `'auto'` (default) — enabled when `NODE_ENV` is **not** `'production'`
+     *
+     * @default 'auto'
+     */
+    swagger?: boolean | 'auto';
+    /**
+     * Base path where the admin router is mounted.
+     * Used to build accurate path entries in the OpenAPI spec.
+     *
+     * @default '/admin'
+     */
+    swaggerBasePath?: string;
+    /**
+     * Optional custom login path to redirect unauthenticated browser requests
+     * for the HTML panel to.  If not provided, the panel serves its own internal
+     * login form as a fallback.  The REST API answers `401` either way.
+     *
+     * @example '/login'
+     * @since 1.8.0
+     */
+    loginPath?: string;
+    /**
+     * Suppress startup logs from the admin router.
+     */
+    silent?: boolean;
+    /**
+     * Optional rate limiter middleware applied to sensitive admin mutations.
+     */
+    rateLimiter?: RequestHandler;
+}
+export declare function createAdminRouter(userStore: IUserStore, options: AdminOptions): Router;
+//# sourceMappingURL=admin.router.d.ts.map

package/dist/router/admin.router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.router.d.ts","sourceRoot":"","sources":["../../src/router/admin.router.ts"],"names":[],"mappings":"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"}