@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/features/admin/admin.controller.d.ts

@@ -0,0 +1,382 @@
+import { RequestContext } from '../../common/request-context.js';
+import { ApiKeysService } from '../api-keys/api-keys.service.js';
+import { DataRetentionService } from '../maintenance/data-retention.service.js';
+import { SessionService } from '../sessions/session.service.js';
+import { SettingsService } from '../settings/settings.service.js';
+import { SettingsChanges } from '../settings/settings.types.js';
+import { SigningKeysService } from '../signing-keys/signing-keys.service.js';
+import { TwoFactorService } from '../two-factor/two-factor.service.js';
+import { UsersService } from '../users/users.service.js';
+import { WebhooksService } from '../webhooks/webhooks.service.js';
+import { AdminUpdateUserInput, CreateApiKeyInput, CreateWebhookInput, PageQuery, SearchAuditLogQuery, SearchUsersQuery, SetRolesInput, SuspendUserInput, UpdateWebhookInput } from './admin.dto';
+import { AdminService } from './admin.service';
+/**
+ * Admin API. Every route needs a user with one of settings.admin.adminRoles, and checks the
+ * session live, so a demoted or signed-out admin loses access at once.
+ *
+ * Users
+ *   GET    /auth/admin/users                      search (?search=&status=&role=&page=&pageSize=)
+ *   GET    /auth/admin/users/:id                  details, sign-in methods, devices
+ *   PATCH  /auth/admin/users/:id                  change name / app fields
+ *   PUT    /auth/admin/users/:id/roles            replace roles
+ *   POST   /auth/admin/users/:id/suspend          suspend with a reason (signs out everywhere)
+ *   POST   /auth/admin/users/:id/unsuspend        lift a suspension
+ *   POST   /auth/admin/users/:id/verify-email     mark email verified (support case)
+ *   POST   /auth/admin/users/:id/reset-2fa        turn off 2FA (lost phone)
+ *   POST   /auth/admin/users/:id/logout-all       sign out every device
+ *   DELETE /auth/admin/users/:id                  delete account (permanent)
+ * Settings
+ *   GET    /auth/admin/settings                   settings in force
+ *   PATCH  /auth/admin/settings                   change some settings at runtime
+ *   DELETE /auth/admin/settings                   back to the settings in code
+ * Security and operations
+ *   GET    /auth/admin/audit-log                  security history (?userId=&eventName=)
+ *   GET    /auth/admin/stats                      accounts by status, devices, last 24 hours
+ *   POST   /auth/admin/maintenance/cleanup        delete old rows now (also runs hourly)
+ *   POST   /auth/admin/signing-keys/rotate        new token signing key
+ * API keys and webhooks
+ *   GET/POST /auth/admin/api-keys, DELETE /auth/admin/api-keys/:id
+ *   GET/POST /auth/admin/webhooks, PATCH/DELETE /auth/admin/webhooks/:id,
+ *   POST /auth/admin/webhooks/:id/rotate-secret, POST /auth/admin/webhooks/:id/test,
+ *   GET /auth/admin/webhooks/:id/deliveries, POST /auth/admin/webhooks/:id/deliveries/:deliveryId/retry
+ */
+export declare class AdminController {
+    private readonly admin;
+    private readonly settingsService;
+    private readonly users;
+    private readonly sessions;
+    private readonly twoFactor;
+    private readonly signingKeys;
+    private readonly apiKeys;
+    private readonly webhooks;
+    private readonly dataRetention;
+    constructor(admin: AdminService, settingsService: SettingsService, users: UsersService, sessions: SessionService, twoFactor: TwoFactorService, signingKeys: SigningKeysService, apiKeys: ApiKeysService, webhooks: WebhooksService, dataRetention: DataRetentionService);
+    /**
+     * GET /auth/admin/users — Searches users.
+     *
+     * @param query - `?search=&status=&role=&page=&pageSize=`.
+     * @returns One page of users.
+     */
+    searchUsers(query: SearchUsersQuery): Promise<{
+        success: true;
+        users: import("../..").PublicUserProfile[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    /**
+     * GET /auth/admin/users/:id — Details, sign-in methods and devices of one user.
+     *
+     * @param userId - The user to act on (from the URL).
+     * @returns See `AdminService.getUserDetails`.
+     */
+    getUser(userId: string): Promise<{
+        success: true;
+        user: import("../..").PublicUserProfile;
+        suspensionReason: string | null;
+        statusChangedAt: string | null;
+        termsAcceptedAt: string | null;
+        privacyPolicyAcceptedAt: string | null;
+        signInMethods: import("../users/sign-in-methods.service").UserSignInMethods;
+        sessions: {
+            id: string;
+            signInMethod: string;
+            ipAddress: string | null;
+            userAgent: string | null;
+            createdAt: string;
+            lastUsedAt: string;
+        }[];
+    }>;
+    /**
+     * PATCH /auth/admin/users/:id — Changes the user's names or app fields.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param body - The fields to change.
+     * @param request - Who is asking.
+     * @returns The user's updated public profile.
+     */
+    updateUser(adminUserId: string, userId: string, body: AdminUpdateUserInput, request: RequestContext): Promise<{
+        success: boolean;
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * PUT /auth/admin/users/:id/roles — Replaces the user's roles.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param body - `{ roles }`: the full new list.
+     * @param request - Who is asking.
+     * @returns The user's updated public profile.
+     */
+    setRoles(adminUserId: string, userId: string, body: SetRolesInput, request: RequestContext): Promise<{
+        success: boolean;
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * POST /auth/admin/users/:id/suspend — Suspends the account and signs the user out everywhere.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param body - `{ reason }`.
+     * @param request - Who is asking.
+     * @returns The user's updated public profile.
+     */
+    suspendUser(adminUserId: string, userId: string, body: SuspendUserInput, request: RequestContext): Promise<{
+        success: boolean;
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * POST /auth/admin/users/:id/unsuspend — Lifts a suspension.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param request - Who is asking.
+     * @returns The user's updated public profile.
+     */
+    unsuspendUser(adminUserId: string, userId: string, request: RequestContext): Promise<{
+        success: boolean;
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * POST /auth/admin/users/:id/verify-email — Marks the email verified (support case).
+     *
+     * @param userId - The user to act on (from the URL).
+     * @param request - Who is asking.
+     * @returns The user's updated public profile.
+     */
+    verifyEmail(userId: string, request: RequestContext): Promise<{
+        success: boolean;
+        user: import("../..").PublicUserProfile;
+    }>;
+    /**
+     * POST /auth/admin/users/:id/reset-2fa — Turns off 2FA for a user who lost their phone.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    resetTwoFactor(adminUserId: string, userId: string, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * POST /auth/admin/users/:id/logout-all — Signs the user out on every device.
+     *
+     * @param userId - The user to act on (from the URL).
+     * @returns How many sessions were ended.
+     */
+    signOutUserEverywhere(userId: string): Promise<{
+        success: boolean;
+        endedSessions: number;
+    }>;
+    /**
+     * DELETE /auth/admin/users/:id — Deletes the account. This cannot be undone.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param userId - The user to act on (from the URL).
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    deleteUser(adminUserId: string, userId: string, request: RequestContext): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * GET /auth/admin/settings — The settings in force.
+     *
+     * @returns The full settings.
+     */
+    getSettings(): Promise<{
+        success: true;
+        settings: import("../settings/settings.types.js").AuthSettings;
+    }>;
+    /**
+     * PATCH /auth/admin/settings — Changes some settings at runtime.
+     * The body is checked against the settings rules by SettingsService (unknown fields are refused there).
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param body - Only the sections and fields to change.
+     * @param request - Who is asking.
+     * @returns The settings now in force.
+     */
+    changeSettings(adminUserId: string, body: SettingsChanges, request: RequestContext): Promise<{
+        success: true;
+        settings: import("../settings/settings.types.js").AuthSettings;
+    }>;
+    /**
+     * DELETE /auth/admin/settings — Discards admin changes, back to the settings in code.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param request - Who is asking.
+     * @returns The settings now in force.
+     */
+    resetSettings(adminUserId: string, request: RequestContext): Promise<{
+        success: true;
+        settings: import("../settings/settings.types.js").AuthSettings;
+    }>;
+    /**
+     * GET /auth/admin/audit-log — Security history, newest first.
+     *
+     * @param query - `?userId=&eventName=&page=&pageSize=`.
+     * @returns One page of entries.
+     */
+    searchAuditLog(query: SearchAuditLogQuery): Promise<{
+        success: true;
+        entries: import("../..").AuditLogEntity[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    /**
+     * GET /auth/admin/stats — Accounts by status, signed-in devices, last 24 hours.
+     *
+     * @returns See `AdminService.getStats`.
+     */
+    getStats(): Promise<{
+        success: true;
+        usersByStatus: {
+            [k: string]: number;
+        };
+        activeSessions: number;
+        last24Hours: {
+            [k: string]: number;
+        };
+        pendingWebhookDeliveries: number;
+        generatedAt: string;
+    }>;
+    /**
+     * POST /auth/admin/maintenance/cleanup — Runs the data-retention cleanup now
+     * (it also runs every hour by itself).
+     *
+     * @returns How many rows were removed from each table.
+     */
+    runCleanup(): Promise<{
+        success: boolean;
+        removed: import("../maintenance/data-retention.service.js").DataRetentionReport;
+    }>;
+    /**
+     * POST /auth/admin/signing-keys/rotate — Creates a new token signing key.
+     * Tokens signed with the old key keep working until they expire.
+     *
+     * @returns `{ success: true }`.
+     */
+    rotateSigningKey(): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * GET /auth/admin/api-keys — Lists API keys (never the secret part).
+     *
+     * @returns The API keys.
+     */
+    listApiKeys(): Promise<{
+        success: boolean;
+        apiKeys: import("../api-keys/api-keys.service.js").ApiKeySummary[];
+    }>;
+    /**
+     * POST /auth/admin/api-keys — Creates an API key. The key itself is shown only in this response.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param body - Name, scopes and optional expiry date.
+     * @param request - Who is asking.
+     * @returns The new key's details and the plain key.
+     */
+    createApiKey(adminUserId: string, body: CreateApiKeyInput, request: RequestContext): Promise<{
+        apiKey: string;
+        details: import("../api-keys/api-keys.service.js").ApiKeySummary;
+        success: boolean;
+    }>;
+    /**
+     * DELETE /auth/admin/api-keys/:id — Revokes an API key; it stops working at once.
+     *
+     * @param adminUserId - The signed-in admin (for the audit log).
+     * @param apiKeyId - The key (from the URL).
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    revokeApiKey(adminUserId: string, apiKeyId: string, request: RequestContext): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * GET /auth/admin/webhooks — Lists webhooks.
+     *
+     * @returns The webhooks.
+     */
+    listWebhooks(): Promise<{
+        success: boolean;
+        webhooks: import("../webhooks/webhooks.service.js").WebhookSummary[];
+    }>;
+    /**
+     * POST /auth/admin/webhooks — Adds a webhook. The signing secret is shown only in this response.
+     *
+     * @param body - URL, events, description and whether it is on.
+     * @returns The webhook and its signing secret.
+     */
+    createWebhook(body: CreateWebhookInput): Promise<{
+        success: true;
+        webhook: import("../webhooks/webhooks.service.js").WebhookSummary;
+        signingSecret: string;
+    }>;
+    /**
+     * PATCH /auth/admin/webhooks/:id — Changes a webhook's URL, events, description or on/off state.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @param body - The fields to change.
+     * @returns The updated webhook.
+     */
+    updateWebhook(webhookId: string, body: UpdateWebhookInput): Promise<{
+        success: true;
+        webhook: import("../webhooks/webhooks.service.js").WebhookSummary;
+    }>;
+    /**
+     * DELETE /auth/admin/webhooks/:id — Deletes a webhook and its delivery history.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @returns `{ success: true }`.
+     */
+    deleteWebhook(webhookId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * POST /auth/admin/webhooks/:id/rotate-secret — Replaces the signing secret.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @returns The new signing secret (shown only once).
+     */
+    rotateWebhookSecret(webhookId: string): Promise<{
+        success: true;
+        signingSecret: string;
+    }>;
+    /**
+     * POST /auth/admin/webhooks/:id/test — Sends a test event to the webhook.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @returns `{ success: true }`; the worker sends it within seconds.
+     */
+    sendTestDelivery(webhookId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * GET /auth/admin/webhooks/:id/deliveries — Delivery history, newest first.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @param query - `?page=&pageSize=`.
+     * @returns One page of deliveries.
+     */
+    listDeliveries(webhookId: string, query: PageQuery): Promise<{
+        success: true;
+        deliveries: import("../..").WebhookDeliveryEntity[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    /**
+     * POST /auth/admin/webhooks/:id/deliveries/:deliveryId/retry — Sends a failed delivery again.
+     *
+     * @param webhookId - The webhook (from the URL).
+     * @param deliveryId - The delivery (from the URL).
+     * @returns `{ success: true }`; the worker sends it within seconds.
+     */
+    retryDelivery(webhookId: string, deliveryId: string): Promise<{
+        success: true;
+    }>;
+}