api-keys.controller.ts

import {
  Body,
  Controller,
  Delete,
  Get,
  HttpCode,
  Param,
  Post,
  HttpStatus,
  Query,
  UseGuards,
  ForbiddenException,
  BadRequestException,
} from "@nestjs/common";
import {
  ApiBearerAuth,
  ApiExcludeEndpoint,
  ApiParam,
  ApiTags,
  ApiOperation,
  ApiResponse,
} from "@nestjs/swagger";
import { ApiKeyScope } from "@prisma/client";
import { AuthGuard } from "../common/guards/auth.guard";
import { CurrentUser } from "../common/decorators/current-user.decorator";
import { AuthenticatedUser } from "../auth/auth.types";
import { ApiErrorDto } from "../common/dto/api-error.dto";
import { SESSION_AUTH_SCHEME } from "../common/swagger/security-schemes";
import { ApiKeyService } from "./api-key.service";
import { PrismaService } from "../database/prisma.service";
import {
  CreateApiKeyDto,
  OrganizationApiKeysQueryDto,
} from "./dto/api-key-request.dto";

/**
 * API Keys Controller - Machine-to-machine integration credential management.
 *
 * Access control:
 * - All endpoints require wallet authentication (AuthGuard) + organization admin role
 * - Organization isolation enforced at query level (cannot manage other orgs' keys)
 * - Organization admin currently means global ADMIN or organization creator.
 *   Multi-admin memberships require a future OrganizationMember model.
 *
 * Response behavior:
 * - Creation: returns raw secret EXACTLY ONCE (never retrievable again)
 * - Listing: returns metadata only (id, prefix, name, status, scopes, dates)
 * - Rotation: returns new raw secret EXACTLY ONCE, invalidates old secret immediately
 * - Revocation: marks key REVOKED, takes effect immediately (no cache window)
 *
 * One-time secret display:
 * - Clients must save the returned secret immediately
 * - No code path allows retrieving or reconstructing the secret later
 * - If secret is lost, client must rotate the key to get a new one
 */
@ApiBearerAuth(SESSION_AUTH_SCHEME)
@ApiTags("api-keys")
@UseGuards(AuthGuard)
@Controller("api-keys")
export class ApiKeysController {
  constructor(
    private readonly apiKeyService: ApiKeyService,
    private readonly prisma: PrismaService,
  ) {}

  /**
   * Create a new API key for an organization.
   *
   * Authorization: Organization admin only
   * Returns: Raw secret (display ONCE), key metadata
   * Note: Secret is never stored again; must be saved by client
   */
  @Post()
  @ApiOperation({
    summary: "Create a new API key",
    description:
      "Generate a new API key for machine-to-machine integrations. The raw secret is returned exactly once and cannot be retrieved later.",
  })
  @ApiResponse({
    status: 201,
    description: "API key created successfully",
    schema: {
      example: {
        secret: "dGVzdGtleTAx_[...base64url encrypted key...]",
        apiKey: {
          id: "key_abc123",
          prefix: "dGVzdGtl",
          name: "GitHub CI",
          status: "ACTIVE",
          scopes: ["PROOF_VERIFY", "PAYMENT_READ"],
          createdAt: "2026-08-24T12:00:00Z",
          expiresAt: null,
        },
      },
    },
  })
  @ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: "Session token is missing, malformed, invalid, or expired.",
    type: ApiErrorDto,
  })
  @ApiResponse({
    status: HttpStatus.FORBIDDEN,
    description:
      "The caller is not an administrator of the organization named in the request.",
    type: ApiErrorDto,
  })
  @ApiResponse({
    status: HttpStatus.BAD_REQUEST,
    description:
      "`expiresAt` is not in the future, or `scopes` names a scope that does not exist.",
    type: ApiErrorDto,
  })
  async createKey(
    @CurrentUser() user: AuthenticatedUser,
    @Body()
    body: CreateApiKeyDto,
  ) {
    // Authorization: User must be organization admin
    const organizationId = await this.getAuthorizedOrganizationId(
      user,
      body.organizationId,
    );
    if (!organizationId) {
      throw new ForbiddenException(
        "Only organization admins can create API keys. You must be the organization creator or an admin member.",
      );
    }

    const expiresAt = body.expiresAt ? new Date(body.expiresAt) : undefined;
    if (expiresAt && expiresAt <= new Date()) {
      throw new BadRequestException("expiresAt must be in the future");
    }

    // Validate scopes if provided
    if (body.scopes) {
      const validScopes = Object.values(ApiKeyScope);
      for (const scope of body.scopes) {
        if (!validScopes.includes(scope)) {
          throw new BadRequestException(`Invalid scope: ${scope}`);
        }
      }
    }

    const result = await this.apiKeyService.createKey({
      organizationId,
      createdBy: user.id,
      name: body.name,
      scopes: body.scopes,
      expiresAt,
    });

    // Important: return includes the raw secret exactly once
    return {
      secret: result.secret,
      apiKey: result.apiKey,
    };
  }

  /**
   * List API keys for user's organization.
   *
   * Authorization: Organization admin only
   * Returns: Metadata only (never includes secrets or hashes)
   */
  @Get()
  @ApiOperation({
    summary: "List API keys for your organization",
    description: "List all API keys for your organization (metadata only, no secrets).",
  })
  @ApiResponse({
    status: 200,
    description: "List of API keys",
    schema: {
      example: [
        {
          id: "key_abc123",
          prefix: "dGVzdGtl",
          name: "GitHub CI",
          status: "ACTIVE",
          scopes: ["PROOF_VERIFY", "PAYMENT_READ"],
          createdAt: "2026-08-24T12:00:00Z",
          rotatedAt: null,
          revokedAt: null,
          expiresAt: null,
          lastUsedAt: "2026-08-24T13:30:00Z",
        },
      ],
    },
  })
  @ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: "Session token is missing, malformed, invalid, or expired.",
    type: ApiErrorDto,
  })
  @ApiResponse({
    status: HttpStatus.FORBIDDEN,
    description:
      "The caller is not an administrator of the organization named in the request.",
    type: ApiErrorDto,
  })
  async listKeys(
    @CurrentUser() user: AuthenticatedUser,
    @Query() query: OrganizationApiKeysQueryDto = {},
  ) {
    // Authorization: User must be organization admin
    const organizationId = await this.getAuthorizedOrganizationId(
      user,
      query.organizationId,
    );
    if (!organizationId) {
      throw new ForbiddenException(
        "Only organization admins can list API keys. You must be the organization creator or an admin member.",
      );
    }

    const keys = await this.apiKeyService.listKeysForOrganization(
      organizationId,
    );

    return keys.map((key) => ({
      id: key.id,
      prefix: key.prefix,
      name: key.name,
      status: key.status,
      scopes: key.scopeAssignments.map((sa) => sa.scope),
      createdAt: key.createdAt,
      rotatedAt: key.rotatedAt,
      revokedAt: key.revokedAt,
      expiresAt: key.expiresAt,
      lastUsedAt: key.lastUsedAt,
    }));
  }

  /**
   * Rotate an API key: generate new secret, invalidate old immediately.
   *
   * Authorization: Organization admin only
   * Returns: New raw secret (display ONCE), updated key metadata
   * Effect: Old secret stops working immediately
   */
  @Post(":id/rotate")
  @ApiOperation({
    summary: "Rotate an API key",
    description:
      "Generate a new secret for an existing API key. The old secret is invalidated immediately and can never be used again.",
  })
  @ApiResponse({
    status: 200,
    description: "API key rotated successfully",
    schema: {
      example: {
        secret: "bmV3c2VjcmV0MDEy_[...base64url encrypted key...]",
        apiKey: {
          id: "key_abc123",
          prefix: "bmV3c2Vj",
          name: "GitHub CI",
          status: "ACTIVE",
          scopes: ["PROOF_VERIFY", "PAYMENT_READ"],
          rotatedAt: "2026-08-24T14:00:00Z",
        },
      },
    },
  })
  @ApiParam({
    name: "id",
    description: "API key to rotate.",
    example: "ckv8v6h2b0000qzrmn831i7rn",
  })
  @ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: "Session token is missing, malformed, invalid, or expired.",
    type: ApiErrorDto,
  })
  @ApiResponse({
    status: HttpStatus.FORBIDDEN,
    description:
      "The caller is not an administrator of the organization, or the key belongs " +
      "to another organization. The two answer alike so the response cannot be " +
      "used to discover which key identifiers exist.",
    type: ApiErrorDto,
  })
  async rotateKey(
    @CurrentUser() user: AuthenticatedUser,
    @Param("id") keyId: string,
    @Query() query: OrganizationApiKeysQueryDto = {},
  ) {
    // Authorization: User must be organization admin
    const organizationId = await this.getAuthorizedOrganizationId(
      user,
      query.organizationId,
    );
    if (!organizationId) {
      throw new ForbiddenException(
        "Only organization admins can rotate API keys. You must be the organization creator or an admin member.",
      );
    }

    // Verify the key belongs to this organization (enforced by service)
    try {
      const result = await this.apiKeyService.rotateKey(
        keyId,
        organizationId,
        user.id, // Pass actor for audit logging
      );

      // Important: return includes the new raw secret exactly once
      return {
        secret: result.secret,
        apiKey: result.apiKey,
      };
    } catch (error) {
      if (
        error instanceof Error &&
        error.message.includes("does not belong to this organization")
      ) {
        throw new ForbiddenException(
          "API key does not belong to your organization",
        );
      }
      throw error;
    }
  }

  /**
   * Revoke an API key: mark as revoked, take effect immediately.
   *
   * Authorization: Organization admin only
   * Returns: 204 No Content
   * Effect: Revoked key is rejected by auth guard immediately
   */
  @Delete(":id")
  @HttpCode(HttpStatus.NO_CONTENT)
  @ApiOperation({
    summary: "Revoke an API key",
    description:
      "Revoke an API key. The key is immediately rejected by the authentication system.",
  })
  @ApiResponse({
    status: HttpStatus.NO_CONTENT,
    description: "API key revoked successfully",
  })
  @ApiParam({
    name: "id",
    description: "API key to revoke.",
    example: "ckv8v6h2b0000qzrmn831i7rn",
  })
  @ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: "Session token is missing, malformed, invalid, or expired.",
    type: ApiErrorDto,
  })
  @ApiResponse({
    status: HttpStatus.FORBIDDEN,
    description:
      "The caller is not an administrator of the organization, the key belongs to " +
      "another organization, or no such key exists.",
    type: ApiErrorDto,
  })
  async revokeKey(
    @CurrentUser() user: AuthenticatedUser,
    @Param("id") keyId: string,
    @Query() query: OrganizationApiKeysQueryDto = {},
  ) {
    await this.revokeAuthorizedKey(user, keyId, query);
  }

  @Delete(":id/revoke")
  @HttpCode(HttpStatus.NO_CONTENT)
  @ApiExcludeEndpoint()
  async revokeKeyLegacy(
    @CurrentUser() user: AuthenticatedUser,
    @Param("id") keyId: string,
    @Query() query: OrganizationApiKeysQueryDto = {},
  ) {
    await this.revokeAuthorizedKey(user, keyId, query);
  }

  private async revokeAuthorizedKey(
    user: AuthenticatedUser,
    keyId: string,
    query: OrganizationApiKeysQueryDto,
  ) {
    // Authorization: User must be organization admin
    const organizationId = await this.getAuthorizedOrganizationId(
      user,
      query.organizationId,
    );
    if (!organizationId) {
      throw new ForbiddenException(
        "Only organization admins can revoke API keys. You must be the organization creator or an admin member.",
      );
    }

    // Verify the key belongs to this organization (enforced by service)
    try {
      await this.apiKeyService.revokeKey(
        keyId,
        organizationId,
        user.id, // Pass actor for audit logging
      );
    } catch (error) {
      if (error instanceof Error && error.message.includes("Key not found")) {
        throw new ForbiddenException("API key not found");
      }
      if (
        error instanceof Error &&
        error.message.includes("does not belong to this organization")
      ) {
        throw new ForbiddenException(
          "API key does not belong to your organization",
        );
      }
      throw error;
    }
  }

  /**
   * Helper: Get user's primary organization ID and verify admin access.
   *
   * Returns the organization ID if the user is an admin of the requested
   * organization. If no organization was requested, it only infers one when
   * exactly one manageable organization exists.
   * In this codebase, organization admin is determined by:
   * - User created the organization (createdById == userId), OR
   * - User has ADMIN role (global admin has access to all orgs)
   *
   * @returns organizationId if authorized as admin, null otherwise
   */
  private async getAuthorizedOrganizationId(
    user: AuthenticatedUser,
    requestedOrganizationId?: string,
  ): Promise<string | null> {
    const accessWhere =
      user.role === "ADMIN" ? {} : { createdById: user.id };

    if (requestedOrganizationId) {
      const org = await this.prisma.organization.findFirst({
        where: {
          id: requestedOrganizationId,
          ...accessWhere,
        },
        select: {
          id: true,
        },
      });

      return org?.id || null;
    }

    const organizations = await this.prisma.organization.findMany({
      where: accessWhere,
      select: {
        id: true,
      },
      orderBy: {
        createdAt: "asc",
      },
      take: 2,
    });

    if (organizations.length === 0) return null;
    if (organizations.length === 1) return organizations[0]?.id ?? null;

    throw new BadRequestException(
      "organizationId is required when you can manage more than one organization",
    );
  }
}