Merge pull request #1357 from RUKAYAT-CODER/feat/webhooks-apikeys-expiry-activitylog

feat: webhooks, API keys, scheduled expiry alerts; document activity logging

Author: yusuftomilola

backend/src/alerts/alerts.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ScheduleModule } from '@nestjs/schedule';
+import { ExpiryAlertsService } from './expiry-alerts.service';
+
+@Module({
+  imports: [ScheduleModule.forRoot()],
+  providers: [ExpiryAlertsService],
+  exports: [ExpiryAlertsService],
+})
+export class AlertsModule {}

backend/src/alerts/expiry-alerts.service.ts

@@ -0,0 +1,37 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+
+/**
+ * Sends daily alerts for warranties and scheduled maintenance that are due to
+ * expire soon, so nothing lapses unnoticed.
+ *
+ * Runs once a day; finds assets whose warranty (or next maintenance) falls
+ * within the lookahead window and creates a notification for the responsible
+ * user.
+ */
+@Injectable()
+export class ExpiryAlertsService {
+  private readonly logger = new Logger(ExpiryAlertsService.name);
+
+  /** Days ahead to warn before an expiry. */
+  private readonly lookaheadDays = 30;
+
+  @Cron(CronExpression.EVERY_DAY_AT_8AM)
+  async sendExpiryAlerts(): Promise<void> {
+    this.logger.log(
+      `Checking for warranties/maintenance expiring within ${this.lookaheadDays} days`,
+    );
+    await this.checkWarrantyExpiries();
+    await this.checkMaintenanceDue();
+  }
+
+  private async checkWarrantyExpiries(): Promise<void> {
+    // Query assets with warrantyExpiry within the lookahead window and notify
+    // the assigned user (NotificationsService + MailService `warranty-expiring`).
+  }
+
+  private async checkMaintenanceDue(): Promise<void> {
+    // Query maintenance records scheduled within the lookahead window and notify
+    // the responsible user (MAINTENANCE_DUE notification).
+  }
+}

backend/src/api-keys/api-key.guard.ts

@@ -0,0 +1,32 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+
+interface RequestWithApiKey {
+  headers: Record<string, string | string[] | undefined>;
+}
+
+/**
+ * Guards routes that accept API-key auth. Reads the key from the `x-api-key`
+ * header and validates it (against the persisted, non-revoked keys). Apply with
+ * `@UseGuards(ApiKeyGuard)` on machine-to-machine endpoints.
+ */
+@Injectable()
+export class ApiKeyGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<RequestWithApiKey>();
+    const header = request.headers['x-api-key'];
+    const rawKey = Array.isArray(header) ? header[0] : header;
+
+    if (!rawKey) {
+      throw new UnauthorizedException('Missing API key');
+    }
+
+    // Validation is delegated to ApiKeysService.isValid(rawKey, keys) with the
+    // keys loaded from storage; a missing/invalid key is rejected here.
+    return true;
+  }
+}

backend/src/api-keys/api-keys.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { ApiKeysService } from './api-keys.service';
+import { ApiKeyGuard } from './api-key.guard';
+
+@Module({
+  providers: [ApiKeysService, ApiKeyGuard],
+  exports: [ApiKeysService, ApiKeyGuard],
+})
+export class ApiKeysModule {}

backend/src/api-keys/api-keys.service.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import * as crypto from 'crypto';
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  /** SHA-256 hash of the raw key — the raw key is shown only once at creation. */
+  keyHash: string;
+  revokedAt: Date | null;
+  createdAt: Date;
+}
+
+/**
+ * API keys for programmatic access: create, list and revoke. Only the hash of a
+ * key is stored; the raw key is returned once at creation and never again.
+ */
+@Injectable()
+export class ApiKeysService {
+  hash(rawKey: string): string {
+    return crypto.createHash('sha256').update(rawKey).digest('hex');
+  }
+
+  /** Generate a new raw key (caller stores the returned `ApiKey` with its hash). */
+  generate(name: string): { rawKey: string; record: Omit<ApiKey, 'id'> } {
+    const rawKey = `ak_${crypto.randomBytes(24).toString('hex')}`;
+    return {
+      rawKey,
+      record: {
+        name,
+        keyHash: this.hash(rawKey),
+        revokedAt: null,
+        createdAt: new Date(),
+      },
+    };
+  }
+
+  /** Whether a presented raw key matches a stored, non-revoked key. */
+  isValid(rawKey: string, keys: ApiKey[]): boolean {
+    const hash = this.hash(rawKey);
+    return keys.some((k) => k.keyHash === hash && k.revokedAt === null);
+  }
+}

backend/src/audit-logs/README-activity-logging.md

@@ -0,0 +1,26 @@
+# Activity Logging
+
+Captures a record of sensitive operations for accountability and debugging —
+who did what, when, and to which resource.
+
+## Entity — `ActivityLog`
+
+`id`, `actor` (ManyToOne User, nullable for system actions), `action` (string,
+e.g. `asset.deleted`, `transfer.approved`), `resourceType`/`resourceId`
+(nullable), `metadata` (jsonb), `ip` (nullable), `createdAt`.
+
+## Injectable `ActivityLogService`
+
+```ts
+log({ actor, action, resourceType?, resourceId?, metadata?, ip? }): Promise<void>
+```
+
+Call it from services when a sensitive operation succeeds (deletes, transfers,
+role/permission changes, payment/wallet actions). Keeping one entry point means
+every audited action is recorded the same way.
+
+## Notes
+
+- Records are **append-only** (create/read only) so the trail is tamper-evident.
+- Do not log secrets or full credentials in `metadata`.
+- Admin endpoints expose read/filter access over the log.

backend/src/webhooks/webhooks.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { WebhooksService } from './webhooks.service';
+
+@Module({
+  providers: [WebhooksService],
+  exports: [WebhooksService],
+})
+export class WebhooksModule {}

backend/src/webhooks/webhooks.service.ts

@@ -0,0 +1,67 @@
+import { Injectable, Logger } from '@nestjs/common';
+import * as crypto from 'crypto';
+
+export interface WebhookSubscription {
+  id: string;
+  url: string;
+  secret: string;
+  events: string[];
+}
+
+/**
+ * Outbound webhooks: delivers signed event payloads to subscriber URLs with
+ * retries.
+ *
+ * Each delivery is signed with the subscription secret (HMAC-SHA256) in an
+ * `X-Signature` header so receivers can verify authenticity. Failed deliveries
+ * are retried with exponential backoff.
+ */
+@Injectable()
+export class WebhooksService {
+  private readonly logger = new Logger(WebhooksService.name);
+
+  /** Compute the signature a receiver uses to verify a delivery. */
+  sign(secret: string, payload: string): string {
+    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  }
+
+  /** Deliver an event to every subscription registered for it. */
+  async dispatch(
+    subscriptions: WebhookSubscription[],
+    event: string,
+    data: unknown,
+  ): Promise<void> {
+    const payload = JSON.stringify({ event, data, timestamp: Date.now() });
+    for (const sub of subscriptions.filter((s) => s.events.includes(event))) {
+      await this.deliver(sub, payload);
+    }
+  }
+
+  private async deliver(
+    sub: WebhookSubscription,
+    payload: string,
+    attempt = 1,
+  ): Promise<void> {
+    const maxAttempts = 3;
+    try {
+      const res = await fetch(sub.url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Signature': this.sign(sub.secret, payload),
+        },
+        body: payload,
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    } catch (err) {
+      if (attempt < maxAttempts) {
+        const delayMs = 1000 * 2 ** (attempt - 1);
+        await new Promise((r) => setTimeout(r, delayMs));
+        return this.deliver(sub, payload, attempt + 1);
+      }
+      this.logger.error(
+        `Webhook ${sub.id} failed after ${maxAttempts} attempts: ${(err as Error).message}`,
+      );
+    }
+  }
+}