feat(16-01): tracer — select and import AD groups end-to-end

Task 1 checkpoint resolved: approve-both, granted 2026-08-06 by the project owner (D-04 one-way schema extension: Group.internalName + Group.ldapObjectGuid, both nullable, one versioned migration). Adds the Phase 16 tracer slice through every layer: - Prisma schema: Group.internalName, Group.ldapObjectGuid, @@unique([tenantId, ldapObjectGuid]) (Prisma client regenerated; the versioned migration itself is Task 3, separately blocking). - LdapService: listGroups() now reads objectGUID via explicitBufferAttributes and flags alreadyImported per tenant; new importGroupsByDn() creates a Group per checked DN with name/ldapDn/ldapObjectGuid, reject-with-report on name collision (P2002 on name -> nameCollisions, P2002 on ldapObjectGuid -> skipped), never aborts the batch on one DN's error; new static escapeLdapFilterBuffer() for Plan 16-03's later existence sweep. - DTO/controller: ImportGroupsDto, POST /ldap/groups/import (ADMIN/SUPER_ADMIN), listGroups route now tenant-scoped. - Frontend: new "AD-Gruppen importieren" section in /admin/ldap, own discovery/import handlers with a visible error state (Owner decision 2026-08-06 — no silent catch{} for these two handlers), i18n keys in de.json/en.json. - Tests: 8 new cases covering the full <behavior> list plus listGroups sort order and alreadyImported. Flagged assumption (RESEARCH.md A1/A2): objectGUID rename-stability and the binary filter syntax are unverified against a real AD — this plan only WRITES the GUID, Plan 16-03 reads it back live.
2026-08-06 15:09:35 +02:00
parent c4a25511f3
commit 3523e43a13
8 changed files with 767 additions and 31 deletions
@@ -112,3 +112,15 @@ export class ImportUsersDto {
  @IsString({ each: true })
  dns!: string[];
 }
+
+/**
+ * DTO for POST /ldap/groups/import — the DNs of AD groups to import as
+ * Tessera groups (SC-1/SC-2). ArrayNotEmpty rejects an empty selection with
+ * HTTP 400 — an admin can never trigger a zero-DN import request.
+ */
+export class ImportGroupsDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsString({ each: true })
+  dns!: string[];
+}
@@ -16,6 +16,7 @@ import { Roles } from '../auth/decorators/roles.decorator';
 import {
  CreateFieldMappingDto,
  CreateLdapConfigDto,
+  ImportGroupsDto,
  ImportUsersDto,
  TestConnectionDto,
  UpdateLdapConfigDto,
@@ -168,13 +169,54 @@ export class LdapController {
      throw new NotFoundException('No LDAP config found for this tenant');
    }

-    return this.ldapService.listGroups({
-      serverUrl: config.serverUrl,
-      baseDn: config.baseDn,
-      bindDn: config.bindDn,
-      bindPassword: config.bindPassword,
-      tlsRejectUnauthorized: config.tlsRejectUnauthorized,
-    });
+    return this.ldapService.listGroups(
+      {
+        serverUrl: config.serverUrl,
+        baseDn: config.baseDn,
+        bindDn: config.bindDn,
+        bindPassword: config.bindPassword,
+        tlsRejectUnauthorized: config.tlsRejectUnauthorized,
+      },
+      tenantId,
+    );
+  }
+
+  /**
+   * POST /ldap/groups/import - Import specific AD groups by DN (from the
+   * group discovery list, filtered to type: 'group') as Tessera groups
+   * (SC-1/SC-2, D-01/D-02). Static route, placed before any future dynamic
+   * `:id`-style route on this controller (project route-order convention).
+   */
+  @Post('groups/import')
+  @Roles(Role.ADMIN, Role.SUPER_ADMIN)
+  async importGroups(@Req() req: any, @Body() dto: ImportGroupsDto) {
+    const tenantId = req.tenantId;
+    if (!tenantId) {
+      throw new BadRequestException('No tenant context');
+    }
+
+    const config = await this.ldapConfigService.getConfig(tenantId);
+    if (!config) {
+      throw new NotFoundException('No LDAP config found for this tenant');
+    }
+
+    return this.ldapService.importGroupsByDn(
+      {
+        id: config.id,
+        tenantId: config.tenantId,
+        serverUrl: config.serverUrl,
+        baseDn: config.baseDn,
+        bindDn: config.bindDn,
+        bindPassword: config.bindPassword,
+        tlsRejectUnauthorized: config.tlsRejectUnauthorized,
+        searchFilter: config.searchFilter,
+        groupFilterDns: config.groupFilterDns,
+        userExcludeList: config.userExcludeList,
+        fieldMappings: config.fieldMappings,
+      },
+      tenantId,
+      dto.dns,
+    );
  }

  /**
@@ -874,3 +874,230 @@ describe('LdapService.syncUsersForTenant — AD-bound group membership sync (D-1
    );
  });
 });
+
+describe('LdapService — AD group import (SC-1/SC-2, D-01/D-02)', () => {
+  let service: LdapService;
+  let prisma: any;
+  let userService: any;
+
+  const cfg = {
+    id: 'cfg1',
+    tenantId: 't1',
+    serverUrl: 'ldap://example',
+    baseDn: 'dc=example,dc=com',
+    searchFilter: '(objectClass=person)',
+    groupFilterDns: [] as string[],
+    userExcludeList: [] as string[],
+    fieldMappings: [{ ldapField: 'sAMAccountName', tesseraField: 'username' }],
+  };
+
+  // 16 raw bytes, hex-decodable to a stable 32-char lowercase string —
+  // stands in for a real AD objectGUID.
+  const guidBuffer = Buffer.from('0123456789abcdef0123456789abcde', 'hex');
+  const guidHex = guidBuffer.toString('hex');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockBind.mockResolvedValue(undefined);
+    mockUnbind.mockResolvedValue(undefined);
+    prisma = {
+      group: {
+        findFirst: vi.fn().mockResolvedValue(null),
+        findMany: vi.fn().mockResolvedValue([]),
+        create: vi.fn().mockResolvedValue({}),
+      },
+    };
+    userService = { create: vi.fn().mockResolvedValue({}) };
+    service = new LdapService(prisma, userService);
+  });
+
+  it('importGroupsByDn creates a Group with name/ldapDn/ldapObjectGuid and counts imported', async () => {
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        {
+          dn: 'cn=Sales,ou=groups,dc=example,dc=com',
+          cn: 'Sales',
+          objectGUID: guidBuffer,
+        },
+      ],
+    });
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=Sales,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.imported).toBe(1);
+    expect(res.skipped).toBe(0);
+    expect(res.errors).toEqual([]);
+    expect(res.nameCollisions).toEqual([]);
+    expect(prisma.group.create).toHaveBeenCalledWith({
+      data: {
+        tenantId: 't1',
+        name: 'Sales',
+        ldapDn: 'cn=Sales,ou=groups,dc=example,dc=com',
+        ldapObjectGuid: guidHex,
+      },
+    });
+  });
+
+  it('importGroupsByDn skips a DN whose ldapObjectGuid already exists for this tenant (no duplicate row)', async () => {
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        {
+          dn: 'cn=Sales,ou=groups,dc=example,dc=com',
+          cn: 'Sales',
+          objectGUID: guidBuffer,
+        },
+      ],
+    });
+    prisma.group.findFirst.mockResolvedValue({ id: 'g1', ldapObjectGuid: guidHex });
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=Sales,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.imported).toBe(0);
+    expect(res.skipped).toBe(1);
+    expect(prisma.group.create).not.toHaveBeenCalled();
+  });
+
+  it('importGroupsByDn records a DN with no AD hit as an error line, not a Group row', async () => {
+    mockSearch.mockResolvedValue({ searchEntries: [] });
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=Ghost,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.imported).toBe(0);
+    expect(res.errors).toEqual([
+      'cn=Ghost,ou=groups,dc=example,dc=com: not found',
+    ]);
+    expect(prisma.group.create).not.toHaveBeenCalled();
+  });
+
+  it('importGroupsByDn reports a name collision (P2002 on tenantId,name) without aborting the remaining DNs', async () => {
+    mockSearch.mockImplementation((dn: string) => {
+      if (dn === 'cn=Collide,ou=groups,dc=example,dc=com') {
+        return Promise.resolve({
+          searchEntries: [
+            { dn, cn: 'Collide', objectGUID: guidBuffer },
+          ],
+        });
+      }
+      return Promise.resolve({
+        searchEntries: [
+          {
+            dn,
+            cn: 'Second',
+            objectGUID: Buffer.from(
+              'ffffffffffffffffffffffffffffffff',
+              'hex',
+            ),
+          },
+        ],
+      });
+    });
+    const nameCollisionError = Object.assign(new Error('Unique constraint'), {
+      code: 'P2002',
+      meta: { target: ['tenantId', 'name'] },
+    });
+    prisma.group.create
+      .mockRejectedValueOnce(nameCollisionError)
+      .mockResolvedValueOnce({});
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=Collide,ou=groups,dc=example,dc=com',
+      'cn=Second,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.nameCollisions).toEqual(['Collide']);
+    expect(res.imported).toBe(1);
+    expect(res.errors).toEqual([]);
+    expect(prisma.group.create).toHaveBeenCalledTimes(2);
+  });
+
+  it('importGroupsByDn treats a P2002 on (tenantId, ldapObjectGuid) like skipped, not an error', async () => {
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        {
+          dn: 'cn=Sales,ou=groups,dc=example,dc=com',
+          cn: 'Sales',
+          objectGUID: guidBuffer,
+        },
+      ],
+    });
+    const raceLossError = Object.assign(new Error('Unique constraint'), {
+      code: 'P2002',
+      meta: { target: ['tenantId', 'ldapObjectGuid'] },
+    });
+    prisma.group.create.mockRejectedValue(raceLossError);
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=Sales,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.skipped).toBe(1);
+    expect(res.imported).toBe(0);
+    expect(res.nameCollisions).toEqual([]);
+    expect(res.errors).toEqual([]);
+  });
+
+  it('importGroupsByDn records an entry with no readable objectGUID buffer as an error, never a mis-stringified value', async () => {
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        {
+          dn: 'cn=NoBuffer,ou=groups,dc=example,dc=com',
+          cn: 'NoBuffer',
+          // Missing/absent objectGUID, exactly as ldapts represents it.
+          objectGUID: [],
+        },
+      ],
+    });
+
+    const res = await service.importGroupsByDn(cfg as any, 't1', [
+      'cn=NoBuffer,ou=groups,dc=example,dc=com',
+    ]);
+
+    expect(res.imported).toBe(0);
+    expect(res.errors).toEqual([
+      'cn=NoBuffer,ou=groups,dc=example,dc=com: objectGUID not readable',
+    ]);
+    expect(prisma.group.create).not.toHaveBeenCalled();
+  });
+
+  it('listGroups marks entries as alreadyImported by matching hex ldapObjectGuid for this tenant', async () => {
+    const otherGuid = Buffer.from('11'.repeat(16), 'hex');
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        { dn: 'cn=Sales,ou=groups,dc=example,dc=com', cn: 'Sales', objectGUID: guidBuffer },
+        { dn: 'cn=IT,ou=groups,dc=example,dc=com', cn: 'IT', objectGUID: otherGuid },
+        { dn: 'ou=groups,dc=example,dc=com', ou: 'groups' },
+      ],
+    });
+    prisma.group.findMany.mockResolvedValue([{ ldapObjectGuid: guidHex }]);
+
+    const res = await service.listGroups(cfg as any, 't1');
+
+    expect(res.find((e) => e.name === 'Sales')?.alreadyImported).toBe(true);
+    expect(res.find((e) => e.name === 'IT')?.alreadyImported).toBe(false);
+    expect(res.find((e) => e.type === 'ou')?.alreadyImported).toBe(false);
+  });
+
+  it('listGroups sorts results by name (localeCompare), then dn on a tie', async () => {
+    mockSearch.mockResolvedValue({
+      searchEntries: [
+        { dn: 'cn=Zebra,ou=groups,dc=example,dc=com', cn: 'Zebra', objectGUID: [] },
+        { dn: 'cn=Apple,ou=b,dc=example,dc=com', cn: 'Apple', objectGUID: [] },
+        { dn: 'cn=Apple,ou=a,dc=example,dc=com', cn: 'Apple', objectGUID: [] },
+      ],
+    });
+
+    const res = await service.listGroups(cfg as any, 't1');
+
+    expect(res.map((e) => e.dn)).toEqual([
+      'cn=Apple,ou=a,dc=example,dc=com',
+      'cn=Apple,ou=b,dc=example,dc=com',
+      'cn=Zebra,ou=groups,dc=example,dc=com',
+    ]);
+  });
+});
@@ -43,12 +43,32 @@ interface LdapConfigData {

 /**
 * A discovered AD group or organizational unit, returned by listGroups()
- * for the admin to pick from when building a selective import filter.
+ * for the admin to pick from when building a selective import filter (D-18)
+ * or, filtered to type: 'group', when picking AD groups to import as
+ * Tessera groups (SC-1/SC-2, D-01/D-02). `alreadyImported` is only ever
+ * true for type: 'group' entries whose objectGUID already matches a
+ * Group.ldapObjectGuid of the requesting tenant — OUs are never importable
+ * and always report false.
 */
 export interface LdapDirectoryEntry {
  dn: string;
  name: string;
  type: 'group' | 'ou';
+  alreadyImported?: boolean;
+}
+
+/**
+ * Result of importGroupsByDn() — a manual, selective AD-group-to-Tessera-group
+ * import (SC-1/SC-2, D-01/D-02). Name collisions are reported separately from
+ * generic errors so the frontend can translate the collision message
+ * (admin.ldap.groupImport.nameCollisionError) instead of rendering a raw
+ * German backend string.
+ */
+export interface LdapGroupImportResult {
+  imported: number;
+  skipped: number;
+  nameCollisions: string[];
+  errors: string[];
 }

 /**
@@ -211,17 +231,30 @@ export class LdapService {

  /**
   * Discover groups and organizational units under EVERY configured base DN.
-   * Used by the admin UI to build a selective import filter (groupFilterDns).
-   * Read-only directory query using the service-account bind. Results from
-   * all base DNs are merged and deduped by entry dn.
+   * Used by the admin UI both to build a selective import filter
+   * (groupFilterDns) and — filtered client-side to type: 'group' — to pick
+   * AD groups to import as Tessera groups (D-01: one shared discovery
+   * endpoint, no second one). Read-only directory query using the
+   * service-account bind. Results from all base DNs are merged and deduped
+   * by entry dn.
+   *
+   * objectGUID is requested via explicitBufferAttributes so ldapts returns
+   * it as a Buffer instead of attempting a lossy UTF-8 decode of the raw
+   * 16-byte value (Pitfall 2, RESEARCH.md). It is used ONLY to compute
+   * alreadyImported for group entries against this tenant's
+   * Group.ldapObjectGuid rows — the hex value itself is never returned to
+   * the client (T-16-04, information disclosure).
   */
-  async listGroups(config: {
-    serverUrl: string;
-    baseDn: string;
-    bindDn?: string | null;
-    bindPassword?: string | null;
-    tlsRejectUnauthorized?: boolean | null;
-  }): Promise<LdapDirectoryEntry[]> {
+  async listGroups(
+    config: {
+      serverUrl: string;
+      baseDn: string;
+      bindDn?: string | null;
+      bindPassword?: string | null;
+      tlsRejectUnauthorized?: boolean | null;
+    },
+    tenantId: string,
+  ): Promise<LdapDirectoryEntry[]> {
    const client = new Client(
      this.buildClientOptions(config.serverUrl, config.tlsRejectUnauthorized),
    );
@@ -235,7 +268,8 @@ export class LdapService {
      for (const baseDn of baseDns) {
        const { searchEntries } = await client.search(baseDn, {
          filter: '(|(objectClass=group)(objectClass=organizationalUnit))',
-          attributes: ['cn', 'ou', 'dn'],
+          attributes: ['cn', 'ou', 'dn', 'objectGUID'],
+          explicitBufferAttributes: ['objectGUID'],
          scope: 'sub',
        });
        for (const entry of searchEntries) {
@@ -243,22 +277,54 @@ export class LdapService {
        }
      }

-      return Array.from(entriesByDn.values()).map((entry) => {
+      const mapped = Array.from(entriesByDn.values()).map((entry) => {
        const dn = entry.dn;
        const isOu = /^ou=/i.test(dn);
-        const rawName = isOu ? entry['ou'] : entry['cn'];
+        const record = entry as unknown as Record<string, unknown>;
+        const rawName = isOu ? record['ou'] : record['cn'];
        const name = Array.isArray(rawName)
          ? String(rawName[0])
          : rawName
            ? String(rawName)
            : dn;
+        const guidValue = record['objectGUID'];
+        const guidHex =
+          !isOu && Buffer.isBuffer(guidValue)
+            ? guidValue.toString('hex')
+            : null;

        return {
          dn,
          name,
          type: isOu ? ('ou' as const) : ('group' as const),
+          guidHex,
        };
      });
+
+      const guidHexes = mapped
+        .map((e) => e.guidHex)
+        .filter((h): h is string => !!h);
+      let importedSet = new Set<string>();
+      if (guidHexes.length > 0) {
+        const existing = await this.prisma.group.findMany({
+          where: { tenantId, ldapObjectGuid: { in: guidHexes } },
+          select: { ldapObjectGuid: true },
+        });
+        importedSet = new Set(
+          existing
+            .map((g: { ldapObjectGuid: string | null }) => g.ldapObjectGuid)
+            .filter((g: string | null): g is string => !!g),
+        );
+      }
+
+      return mapped
+        .map(({ guidHex, ...rest }) => ({
+          ...rest,
+          alreadyImported: !!guidHex && importedSet.has(guidHex),
+        }))
+        .sort(
+          (a, b) => a.name.localeCompare(b.name) || a.dn.localeCompare(b.dn),
+        );
    } finally {
      try {
        await client.unbind();
@@ -546,6 +612,125 @@ export class LdapService {
    return result;
  }

+  /**
+   * Import specific AD groups by DN (from listGroups results, filtered to
+   * type: 'group') as Tessera groups (SC-1/SC-2, D-01/D-02). Every DN is a
+   * base-scoped lookup — the admin never bulk-imports an OU or a search
+   * result, only the exact groups they checked. objectGUID is read via
+   * explicitBufferAttributes (same Pitfall-2 requirement as listGroups) and
+   * hex-encoded into Group.ldapObjectGuid, the rename-stable identity key
+   * Plan 16-03's reconciliation depends on. `GroupsService.create()` is
+   * deliberately NOT used here: its ConflictException is built for a single
+   * interactive HTTP request and would abort the whole batch on the first
+   * name collision (Pitfall 4, RESEARCH.md) — this loop instead collects a
+   * per-DN outcome and never stops on one group's error.
+   */
+  async importGroupsByDn(
+    config: LdapConfigData,
+    tenantId: string,
+    dns: string[],
+  ): Promise<LdapGroupImportResult> {
+    const result: LdapGroupImportResult = {
+      imported: 0,
+      skipped: 0,
+      nameCollisions: [],
+      errors: [],
+    };
+
+    const client = new Client(
+      this.buildClientOptions(config.serverUrl, config.tlsRejectUnauthorized),
+    );
+    // Mandantengescopter Schreibpfad (T-16-02): app.current_tenant wird vor
+    // jedem group.create() gesetzt, RLS ist das zweite Netz.
+    const tenantPrisma = forTenant(this.prisma, tenantId) as any;
+
+    try {
+      await this.bind(client, config.bindDn, config.bindPassword);
+
+      for (const dn of dns) {
+        try {
+          // Base-scoped lookup of exactly this DN — the admin-selected DN is
+          // the search BASE, never interpolated into a filter (T-16-01).
+          const { searchEntries } = await client.search(dn, {
+            filter: '(objectClass=group)',
+            attributes: ['cn', 'dn', 'objectGUID'],
+            explicitBufferAttributes: ['objectGUID'],
+            scope: 'base',
+          });
+          if (searchEntries.length === 0) {
+            result.errors.push(`${dn}: not found`);
+            continue;
+          }
+
+          const entry = searchEntries[0];
+          const record = entry as unknown as Record<string, unknown>;
+          const guidValue = record['objectGUID'];
+          if (!Buffer.isBuffer(guidValue)) {
+            result.errors.push(`${dn}: objectGUID not readable`);
+            continue;
+          }
+          const ldapObjectGuid = guidValue.toString('hex');
+
+          const rawName = record['cn'];
+          const name = Array.isArray(rawName)
+            ? String(rawName[0])
+            : rawName
+              ? String(rawName)
+              : dn;
+
+          // Idempotency: a second import of the same AD group is a skip, not
+          // a duplicate row.
+          const existingByGuid = await this.prisma.group.findFirst({
+            where: { tenantId, ldapObjectGuid },
+          });
+          if (existingByGuid) {
+            result.skipped++;
+            continue;
+          }
+
+          try {
+            await tenantPrisma.group.create({
+              data: { tenantId, name, ldapDn: entry.dn, ldapObjectGuid },
+            });
+            result.imported++;
+          } catch (createError: any) {
+            if (createError?.code === 'P2002') {
+              const target = createError?.meta?.target;
+              const targetsGuid = Array.isArray(target)
+                ? target.includes('ldapObjectGuid')
+                : String(target ?? '').includes('ldapObjectGuid');
+              if (targetsGuid) {
+                // Lost a race against a concurrent import of the same AD
+                // group — treat identically to the pre-check skip above.
+                result.skipped++;
+              } else {
+                // @@unique([tenantId, name]) violation: reject-with-report,
+                // never abort the remaining DNs (Pitfall 4).
+                result.nameCollisions.push(name);
+              }
+            } else {
+              throw createError;
+            }
+          }
+        } catch (entryError: unknown) {
+          const msg =
+            entryError instanceof Error
+              ? entryError.message
+              : 'Unknown error importing group';
+          result.errors.push(`${dn}: ${msg}`);
+        }
+      }
+    } finally {
+      try {
+        await client.unbind();
+      } catch {
+        // Ignore unbind errors
+      }
+    }
+
+    return result;
+  }
+
  /**
   * Sync users from LDAP directory for a specific tenant.
   *
@@ -982,4 +1167,19 @@ export class LdapService {
      .replace(/\)/g, '\\29')
      .replace(/\x00/g, '\\00');
  }
+
+  /**
+   * Escape a binary value (e.g. a stored objectGUID) for use in an LDAP
+   * search filter per RFC 4515 — a byte-wise `\XX` hex escape, distinct from
+   * escapeLdapFilterValue() which escapes a STRING value. Not yet called
+   * anywhere in this plan (Plan 16-01 only WRITES ldapObjectGuid); Plan
+   * 16-03's existence sweep is the first caller, reading it back via a
+   * binary (objectGUID=...) filter. [ASSUMED — RFC 4515-Praxis, nicht gegen
+   * ein echtes AD verifiziert, siehe RESEARCH.md Pattern 3/A2.]
+   */
+  static escapeLdapFilterBuffer(buf: Buffer): string {
+    return Array.from(buf)
+      .map((b) => '\\' + b.toString(16).padStart(2, '0'))
+      .join('');
+  }
 }