feat: revocable read-only API keys for machine access

Integrations such as the Wabenhain shop sync no longer need a service
account with a password (and without MFA). An admin creates a key under
Verwaltung > Automatisierung > API-Schlüssel.

- Key format ack_<8>_<43>; only its SHA-256 hash is stored, the key is
  shown exactly once. Optional expiry, "last used" timestamp, revocation
  takes effect immediately; create/revoke are audit-logged without the key.
- A key is not a user: JwtAuthGuard sets request.apiKey, PermissionsGuard
  admits it only to routes whose permission is among its scopes and never
  to user-only routes. Scopes come from a short allowlist (shop-sync:read).
- Managing keys requires the new permission api-keys:manage.
- Keys are excluded from backups on purpose; a restore means issuing a new
  key.

Additive migration (new table).

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

ApiCore-Backend/src/api-keys/api-key-scopes.ts

@@ -0,0 +1,18 @@
+import { PermissionKey } from '../auth/permissions/permission-catalog';
+
+/**
+ * Permissions an API key may carry. Deliberately a short allowlist of
+ * read-only permissions, not the whole catalog: a key is a long-lived secret
+ * stored in another system, so it only ever gets what a machine integration
+ * needs. Removing an entry here also takes it away from existing keys (see
+ * ApiKeysService.authenticate).
+ */
+export const API_KEY_SCOPES = [
+  'shop-sync:read',
+] as const satisfies readonly PermissionKey[];
+
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+
+export function isApiKeyScope(value: string): value is ApiKeyScope {
+  return (API_KEY_SCOPES as readonly string[]).includes(value);
+}

ApiCore-Backend/src/api-keys/api-keys.controller.ts

@@ -0,0 +1,42 @@
+import { Body, Controller, Get, Param, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { RequirePermission } from '../auth/decorators/require-permission.decorator';
+import { CurrentUser } from '../auth/decorators/current-user.decorator';
+import type { AuthenticatedUser } from '../auth/types/authenticated-user';
+import { CreateApiKeyDto } from './dto/create-api-key.dto';
+import {
+  ApiKeySummary,
+  ApiKeysService,
+  CreatedApiKey,
+} from './api-keys.service';
+
+@ApiTags('api-keys')
+@ApiBearerAuth()
+@Controller('api-keys')
+export class ApiKeysController {
+  constructor(private readonly apiKeys: ApiKeysService) {}
+
+  @RequirePermission('api-keys:manage')
+  @Get()
+  findAll(): Promise<ApiKeySummary[]> {
+    return this.apiKeys.findAll();
+  }
+
+  @RequirePermission('api-keys:manage')
+  @Post()
+  create(
+    @Body() dto: CreateApiKeyDto,
+    @CurrentUser() actor: AuthenticatedUser,
+  ): Promise<CreatedApiKey> {
+    return this.apiKeys.create(dto, actor.id);
+  }
+
+  @RequirePermission('api-keys:manage')
+  @Post(':id/revoke')
+  revoke(
+    @Param('id') id: string,
+    @CurrentUser() actor: AuthenticatedUser,
+  ): Promise<ApiKeySummary> {
+    return this.apiKeys.revoke(id, actor.id);
+  }
+}

ApiCore-Backend/src/api-keys/api-keys.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { ApiKeysController } from './api-keys.controller';
+import { ApiKeysService } from './api-keys.service';
+
+// Global: the app-wide auth guards need ApiKeysService to recognise keys.
+@Global()
+@Module({
+  controllers: [ApiKeysController],
+  providers: [ApiKeysService],
+  exports: [ApiKeysService],
+})
+export class ApiKeysModule {}

ApiCore-Backend/src/api-keys/api-keys.service.ts

@@ -0,0 +1,162 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { createHash, randomBytes, randomInt } from 'node:crypto';
+import { PrismaService } from '../prisma/prisma.service';
+import { AuditLogService } from '../audit/audit-log.service';
+import { ApiKey } from '../../generated/prisma';
+import { CreateApiKeyDto } from './dto/create-api-key.dto';
+import { ApiKeyScope, isApiKeyScope } from './api-key-scopes';
+
+// ack_<8 lowercase chars>_<32 random bytes, base64url>
+const TOKEN_PATTERN = /^ack_[a-z0-9]{8}_[A-Za-z0-9_-]{43}$/;
+const PREFIX_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+// lastUsedAt is informational; writing it on every request would turn each
+// read into a write for no benefit.
+const LAST_USED_RESOLUTION_MS = 5 * 60 * 1000;
+
+/** What a request authenticated by an API key may do - it is not a user. */
+export interface ApiKeyPrincipal {
+  id: string;
+  scopes: ApiKeyScope[];
+}
+
+/** An API key as shown in the admin UI - never the hash or the key itself. */
+export type ApiKeySummary = Omit<ApiKey, 'keyHash'>;
+
+export interface CreatedApiKey {
+  apiKey: ApiKeySummary;
+  /** The only time the plain key exists outside the caller's system. */
+  token: string;
+}
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+function randomPrefix(): string {
+  let prefix = '';
+  for (let i = 0; i < 8; i++) {
+    prefix += PREFIX_ALPHABET[randomInt(PREFIX_ALPHABET.length)];
+  }
+  return `ack_${prefix}`;
+}
+
+function toSummary(apiKey: ApiKey): ApiKeySummary {
+  const { keyHash, ...summary } = apiKey;
+  void keyHash;
+  return summary;
+}
+
+@Injectable()
+export class ApiKeysService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly auditLog: AuditLogService,
+  ) {}
+
+  async findAll(): Promise<ApiKeySummary[]> {
+    const keys = await this.prisma.apiKey.findMany({
+      orderBy: { createdAt: 'desc' },
+    });
+    return keys.map(toSummary);
+  }
+
+  async create(
+    dto: CreateApiKeyDto,
+    actingUserId: string,
+  ): Promise<CreatedApiKey> {
+    const prefix = randomPrefix();
+    // 32 random bytes: a plain hash of it is safe to store without a slow
+    // KDF - there is nothing guessable to brute-force.
+    const token = `${prefix}_${randomBytes(32).toString('base64url')}`;
+    const expiresAt =
+      dto.expiresInDays !== undefined
+        ? new Date(Date.now() + dto.expiresInDays * 24 * 60 * 60 * 1000)
+        : null;
+
+    const apiKey = await this.prisma.apiKey.create({
+      data: {
+        name: dto.name.trim(),
+        prefix,
+        keyHash: hashToken(token),
+        scopes: [...new Set(dto.scopes)],
+        expiresAt,
+        createdByUserId: actingUserId,
+      },
+    });
+    const summary = toSummary(apiKey);
+    await this.auditLog.record({
+      entityType: 'ApiKey',
+      entityId: apiKey.id,
+      action: 'CREATE',
+      userId: actingUserId,
+      afterData: summary,
+    });
+    return { apiKey: summary, token };
+  }
+
+  async revoke(id: string, actingUserId: string): Promise<ApiKeySummary> {
+    const before = await this.prisma.apiKey.findUnique({ where: { id } });
+    if (!before) {
+      throw new NotFoundException('API-Schlüssel nicht gefunden');
+    }
+    if (before.revokedAt) {
+      return toSummary(before);
+    }
+    const revoked = await this.prisma.apiKey.update({
+      where: { id },
+      data: { revokedAt: new Date() },
+    });
+    await this.auditLog.record({
+      entityType: 'ApiKey',
+      entityId: id,
+      action: 'DEACTIVATE',
+      userId: actingUserId,
+      beforeData: toSummary(before),
+      afterData: toSummary(revoked),
+    });
+    return toSummary(revoked);
+  }
+
+  /**
+   * Resolves a presented key to what it may do, or null for anything that
+   * must not pass: malformed, unknown, revoked or expired.
+   */
+  async authenticate(token: string): Promise<ApiKeyPrincipal | null> {
+    if (!TOKEN_PATTERN.test(token)) {
+      return null;
+    }
+    const apiKey = await this.prisma.apiKey.findUnique({
+      where: { keyHash: hashToken(token) },
+    });
+    const now = new Date();
+    if (
+      !apiKey ||
+      apiKey.revokedAt ||
+      (apiKey.expiresAt && apiKey.expiresAt <= now)
+    ) {
+      return null;
+    }
+    if (
+      !apiKey.lastUsedAt ||
+      now.getTime() - apiKey.lastUsedAt.getTime() > LAST_USED_RESOLUTION_MS
+    ) {
+      await this.prisma.apiKey.update({
+        where: { id: apiKey.id },
+        data: { lastUsedAt: now },
+      });
+    }
+    // Intersect with today's allowlist: narrowing it later also narrows
+    // keys issued before.
+    return { id: apiKey.id, scopes: apiKey.scopes.filter(isApiKeyScope) };
+  }
+}
+
+/** The key from an `Authorization: Bearer ack_…` header, or null. */
+export function extractApiKeyToken(
+  authorization: string | undefined,
+): string | null {
+  if (!authorization?.startsWith('Bearer ack_')) {
+    return null;
+  }
+  return authorization.slice('Bearer '.length).trim();
+}

ApiCore-Backend/src/api-keys/dto/create-api-key.dto.ts

@@ -0,0 +1,42 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  ArrayMinSize,
+  ArrayUnique,
+  IsArray,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
+} from 'class-validator';
+import { API_KEY_SCOPES } from '../api-key-scopes';
+
+export class CreateApiKeyDto {
+  @ApiProperty({
+    description: 'Wofür der Schlüssel ist, z. B. "Wabenhain-Shop"',
+  })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(80)
+  name!: string;
+
+  @ApiProperty({ enum: API_KEY_SCOPES, isArray: true })
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayUnique()
+  @IsIn(API_KEY_SCOPES, { each: true })
+  scopes!: string[];
+
+  @ApiPropertyOptional({
+    description:
+      'Gültigkeit in Tagen; ohne Angabe gilt der Schlüssel bis zum Widerruf',
+  })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(730)
+  expiresInDays?: number;
+}

ApiCore-Backend/src/app.module.ts

@@ -45,6 +45,7 @@ import { ProfileModule } from './profile/profile.module';
 import { SiteSettingsModule } from './site-settings/site-settings.module';
 import { BackupModule } from './backup/backup.module';
 import { ShopSyncModule } from './shop-sync/shop-sync.module';
+import { ApiKeysModule } from './api-keys/api-keys.module';
 import { JwtAuthGuard } from './auth/guards/jwt-auth.guard';
 import { PermissionsGuard } from './auth/guards/permissions.guard';
 import { PermissionsModule } from './auth/permissions/permissions.module';
@@ -99,6 +100,7 @@ import { IdempotencyCleanupService } from './common/idempotency/idempotency-clea
     SiteSettingsModule,
     BackupModule,
     ShopSyncModule,
+    ApiKeysModule,
   ],
   controllers: [],
   providers: [

ApiCore-Backend/src/auth/guards/jwt-auth.guard.spec.ts

@@ -2,16 +2,19 @@ import { ExecutionContext, UnauthorizedException } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { JwtAuthGuard } from './jwt-auth.guard';
 import { PermissionResolverService } from '../permissions/permission-resolver.service';
+import { ApiKeysService } from '../../api-keys/api-keys.service';
 
 describe('JwtAuthGuard', () => {
   let guard: JwtAuthGuard;
   let reflector: { getAllAndOverride: jest.Mock };
   let permissionResolver: { isTokenValid: jest.Mock };
+  let apiKeys: { authenticate: jest.Mock };
 
   function contextWithUser(
     user: { id: string; tokenIssuedAt?: number } | undefined,
+    authorization?: string,
   ): ExecutionContext {
-    const request = { user };
+    const request = { user, headers: { authorization } };
     return {
       getHandler: () => ({}),
       getClass: () => ({}),
@@ -22,9 +25,11 @@ describe('JwtAuthGuard', () => {
   beforeEach(() => {
     reflector = { getAllAndOverride: jest.fn().mockReturnValue(false) };
     permissionResolver = { isTokenValid: jest.fn() };
+    apiKeys = { authenticate: jest.fn() };
     guard = new JwtAuthGuard(
       reflector as unknown as Reflector,
       permissionResolver as unknown as PermissionResolverService,
+      apiKeys as unknown as ApiKeysService,
     );
   });
 
@@ -72,4 +77,27 @@ describe('JwtAuthGuard', () => {
       UnauthorizedException,
     );
   });
+
+  it('authenticates an API key as a machine principal, not as a user', async () => {
+    const principal = { id: 'key-1', scopes: ['shop-sync:read'] };
+    apiKeys.authenticate.mockResolvedValue(principal);
+    const context = contextWithUser(undefined, 'Bearer ack_abcdefgh_secret');
+
+    await expect(guard.canActivate(context)).resolves.toBe(true);
+    const request = context.switchToHttp().getRequest<{
+      apiKey?: unknown;
+      user?: unknown;
+    }>();
+    expect(request.apiKey).toBe(principal);
+    expect(request.user).toBeUndefined();
+    expect(permissionResolver.isTokenValid).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unknown, revoked or expired API key', async () => {
+    apiKeys.authenticate.mockResolvedValue(null);
+
+    await expect(
+      guard.canActivate(contextWithUser(undefined, 'Bearer ack_abcdefgh_x')),
+    ).rejects.toBeInstanceOf(UnauthorizedException);
+  });
 });

ApiCore-Backend/src/auth/guards/jwt-auth.guard.ts

@@ -8,9 +8,16 @@ import { AuthGuard } from '@nestjs/passport';
 import { IS_PUBLIC_KEY } from '../decorators/public.decorator';
 import { PermissionResolverService } from '../permissions/permission-resolver.service';
 import { AuthenticatedUser } from '../types/authenticated-user';
+import {
+  ApiKeyPrincipal,
+  ApiKeysService,
+  extractApiKeyToken,
+} from '../../api-keys/api-keys.service';
 
 interface RequestWithUser {
+  headers: { authorization?: string };
   user?: AuthenticatedUser;
+  apiKey?: ApiKeyPrincipal;
 }
 
 /**
@@ -28,6 +35,7 @@ export class JwtAuthGuard extends AuthGuard('jwt') {
   constructor(
     private readonly reflector: Reflector,
     private readonly permissionResolver: PermissionResolverService,
+    private readonly apiKeys: ApiKeysService,
   ) {
     super();
   }
@@ -40,11 +48,25 @@ export class JwtAuthGuard extends AuthGuard('jwt') {
     if (isPublic) {
       return true;
     }
+    const request = context.switchToHttp().getRequest<RequestWithUser>();
+
+    // An API key ("Bearer ack_…") authenticates a machine, not a user: no
+    // request.user is set, so it can never pass a user-only route, and
+    // PermissionsGuard checks its scopes instead of a role.
+    const apiKeyToken = extractApiKeyToken(request.headers.authorization);
+    if (apiKeyToken !== null) {
+      const principal = await this.apiKeys.authenticate(apiKeyToken);
+      if (!principal) {
+        throw new UnauthorizedException();
+      }
+      request.apiKey = principal;
+      return true;
+    }
+
     const authenticated = (await super.canActivate(context)) as boolean;
     if (!authenticated) {
       return false;
     }
-    const request = context.switchToHttp().getRequest<RequestWithUser>();
     const user = request.user;
     if (
       !user ||

ApiCore-Backend/src/auth/guards/permissions.guard.ts

@@ -6,9 +6,11 @@ import { REQUIRE_PERMISSION_KEY } from '../decorators/require-permission.decorat
 import { PermissionKey } from '../permissions/permission-catalog';
 import { PermissionResolverService } from '../permissions/permission-resolver.service';
 import { AuthenticatedUser } from '../types/authenticated-user';
+import type { ApiKeyPrincipal } from '../../api-keys/api-keys.service';
 
 interface RequestWithUser {
   user?: AuthenticatedUser;
+  apiKey?: ApiKeyPrincipal;
 }
 
 /**
@@ -47,6 +49,15 @@ export class PermissionsGuard implements CanActivate {
     const request = context.switchToHttp().getRequest<RequestWithUser>();
     const user = request.user;
 
+    // API keys pass only routes that name a permission the key carries -
+    // never @AnyAuthenticatedUser routes, which are meant for people.
+    if (request.apiKey) {
+      const scopes: readonly string[] = request.apiKey.scopes;
+      return Boolean(
+        requiredPermissions?.some((permission) => scopes.includes(permission)),
+      );
+    }
+
     if (requiredPermissions && requiredPermissions.length > 0) {
       if (!user) {
         return false;

ApiCore-Backend/src/auth/permissions/permission-catalog.ts

@@ -315,6 +315,12 @@ export const PERMISSION_CATALOG = [
     [['read', 'Freigegebene Daten für den Shop lesen']],
     3300,
   ),
+  ...group(
+    'API-Schlüssel',
+    'api-keys',
+    [['manage', 'Anlegen, ansehen und widerrufen']],
+    3400,
+  ),
 ] as const satisfies readonly PermissionCatalogEntry[];
 
 export type PermissionKey = (typeof PERMISSION_CATALOG)[number]['key'];