Prove the migration against live directories and fix what that surfaced

Finishes the unproven half of gap G04. Running the harness against real LLDAP,
OpenLDAP and Keycloak found four defects that the full unit suite passed over.

Every LLDAP user search pointed at a branch that does not exist. Config.userOU()
defaulted to ou=users while LLDAP stores users under ou=people, and nothing set
UserOU. LookupUser, ListUsers and ValidatePassword all derive from it, so all
three silently found nothing against a stock LLDAP -- human login included, not
only the export. Exposed by an export returning zero users while still emitting a
membership referencing uid=admin, a snapshot the repo's own validator rejects.

raw_attributes_well_formed, added one workplan earlier, rejected the LLDAP
adapter's own _validation_warning annotation, so the exporter's output failed its
own validation. Tooling annotations are exempt now, and a test proves the
exemption does not weaken the rule.

Migrated group memberships were dangling: resolveMemberDN passed a source DN
through unchanged while entries were written to the target branch, so groups
named entries the migrated directory does not contain. And empty groups could
not load at all, since groupOfNames makes member a MUST -- they reference a
placeholder entry the LDIF creates, an organizationalRole rather than a person,
emitted only when some group needs it.

The scenario-c compose file could not start: bitnami/openldap:2.6 does not
exist, though it passed docker compose config. Pinned to the image the scenario
was proved against.

Proof: LLDAP -> export -> validate -> LDIF -> ldapadd into OpenLDAP 1.5.0, every
entry added and every member resolving; a realm from the same export imports into
Keycloak and serves discovery. KeyCape passes 5/5 conformance checks, a migrated
Keycloak 4/5.

Relying-party behaviour and MFA against a migrated realm remain unexercised, and
credential/MFA migration is not supplied at all, so no harness can establish it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NV9oijZukGyGbRQGGKnK4P

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 713576@bnt-lap001
Assistant-Session: 384c511d-9bce-4cb8-a676-2aef6c0c8df6

src/internal/adapters/lldap/config.go

@@ -18,7 +18,8 @@ type Config struct {
 	// BaseDN is the search base, e.g. "dc=netkingdom,dc=local".
 	BaseDN string `yaml:"baseDN"`
 
-	// UserOU is the organisational unit for users. Defaults to "ou=users" when empty.
+	// UserOU is the organisational unit for users. Defaults to "ou=people" when
+	// empty, which is where LLDAP stores users -- see userOU.
 	UserOU string `yaml:"userOU,omitempty"`
 
 	// GroupOU is the organisational unit for groups. Defaults to "ou=groups" when empty.
@@ -33,7 +34,14 @@ func (c Config) userOU() string {
 	if c.UserOU != "" {
 		return c.UserOU
 	}
-	return "ou=users"
+	// LLDAP places users under ou=people, not ou=users. The previous "ou=users"
+	// default pointed every user search at a branch LLDAP does not create, so
+	// LookupUser, ListUsers and ValidatePassword all silently found nothing
+	// against a stock LLDAP, and no config in this repository set UserOU to
+	// correct it (KEY-WP-0023). Found by exporting from a live LLDAP: the export
+	// returned zero users while still emitting a membership referencing
+	// uid=admin, a snapshot the repository's own validator rejects.
+	return "ou=people"
 }
 
 // groupOU returns the effective GroupOU, falling back to the default.

src/internal/adapters/lldap/config_internal_test.go

@@ -0,0 +1,28 @@
+package lldap
+
+import "testing"
+
+// KEY-WP-0023. The user search base is not cosmetic: LookupUser, ListUsers and
+// ValidatePassword all derive from it, so a default pointing at a branch LLDAP
+// does not create makes every one of them silently find nothing. That is what
+// "ou=users" did, and no configuration in this repository overrode it.
+func TestUserBaseDNDefaultsToLLDAPsPeopleBranch(t *testing.T) {
+	cfg := Config{BaseDN: "dc=netkingdom,dc=local"}
+	if got, want := cfg.userBaseDN(), "ou=people,dc=netkingdom,dc=local"; got != want {
+		t.Errorf("userBaseDN() = %q, want %q", got, want)
+	}
+	if got, want := cfg.groupBaseDN(), "ou=groups,dc=netkingdom,dc=local"; got != want {
+		t.Errorf("groupBaseDN() = %q, want %q", got, want)
+	}
+}
+
+// An explicit OU still wins, for directories laid out differently.
+func TestExplicitOUOverridesDefaults(t *testing.T) {
+	cfg := Config{BaseDN: "dc=example,dc=com", UserOU: "ou=staff", GroupOU: "ou=teams"}
+	if got, want := cfg.userBaseDN(), "ou=staff,dc=example,dc=com"; got != want {
+		t.Errorf("userBaseDN() = %q, want %q", got, want)
+	}
+	if got, want := cfg.groupBaseDN(), "ou=teams,dc=example,dc=com"; got != want {
+		t.Errorf("groupBaseDN() = %q, want %q", got, want)
+	}
+}

src/internal/migration/toldap/generator.go

@@ -71,6 +71,19 @@ func (g *Generator) Generate(export *lldapexport.ExportResult) (string, error) {
 		"ou: groups",
 	})
 
+	// The placeholder must exist before any group references it: an LDIF is
+	// applied in order, and a forward reference fails on directories that check.
+	needsPlaceholder := false
+	for _, grp := range export.Groups {
+		if len(grp.Members) == 0 {
+			needsPlaceholder = true
+			break
+		}
+	}
+	if needsPlaceholder {
+		g.writePlaceholderMember(&sb)
+	}
+
 	// Write user entries.
 	for _, u := range export.Users {
 		if err := g.writeUser(&sb, u); err != nil {
@@ -155,6 +168,27 @@ func (g *Generator) writeUser(sb *strings.Builder, u domain.User) error {
 	return nil
 }
 
+// placeholderMemberRDN names the entry empty groups point at. See
+// placeholderMemberDN.
+const placeholderMemberRDN = "cn=empty-group-placeholder"
+
+// placeholderMemberDN is the member an otherwise-empty group carries.
+//
+// RFC 4519 makes member a MUST for groupOfNames, so a group with no members is
+// not a valid entry: a real OpenLDAP rejects it with an object class violation
+// and the whole migration stops there. Since KEY-WP-0018 the export deliberately
+// preserves empty groups, so the generator must emit something loadable for them
+// (KEY-WP-0023, found by loading generated LDIF into OpenLDAP 1.5.0).
+//
+// The placeholder is a real entry the same LDIF creates, as an organizationalRole
+// rather than a person: it keeps every member value resolvable, and it cannot be
+// mistaken for a migrated user. Its presence is a deliberate difference from the
+// source directory, not a preserved fact -- see the generator's package
+// documentation.
+func placeholderMemberDN(baseDN string) string {
+	return placeholderMemberRDN + "," + baseDN
+}
+
 func (g *Generator) writeGroup(sb *strings.Builder, grp domain.Group) {
 	dn := "dn: cn=" + grp.Name + ",ou=groups," + g.cfg.BaseDN
 
@@ -166,15 +200,31 @@ func (g *Generator) writeGroup(sb *strings.Builder, grp domain.Group) {
 	}
 
 	for _, memberID := range grp.Members {
-		// If the member ID is already a full DN, use it directly.
-		// Otherwise build a uid=<id>,ou=users,<baseDN> DN.
 		memberDN := resolveMemberDN(memberID, g.cfg.BaseDN, g.cfg.Target)
 		attrs = append(attrs, "member: "+memberDN)
 	}
+	if len(grp.Members) == 0 {
+		attrs = append(attrs, "member: "+placeholderMemberDN(g.cfg.BaseDN))
+	}
 
 	writeEntry(sb, attrs)
 }
 
+// writePlaceholderMember emits the entry empty groups reference. It is written
+// only when some group needs it, so a directory with no empty groups migrates
+// without any synthetic entry at all.
+func (g *Generator) writePlaceholderMember(sb *strings.Builder) {
+	writeEntry(sb, []string{
+		"dn: " + placeholderMemberDN(g.cfg.BaseDN),
+		"objectClass: top",
+		"objectClass: organizationalRole",
+		"cn: empty-group-placeholder",
+		"description: Placeholder member for groups that have no members. " +
+			"groupOfNames requires at least one member; this entry is created by " +
+			"the migration and is not present in the source directory.",
+	})
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -188,22 +238,46 @@ func writeEntry(sb *strings.Builder, lines []string) {
 	sb.WriteByte('\n')
 }
 
-// resolveMemberDN returns the full LDAP DN for a member.
-// If the memberID already contains a comma (i.e. is a DN), it is returned as-is.
-// Otherwise a DN is constructed from the username.
+// resolveMemberDN returns the member's DN in the *target* directory's layout.
+//
+// A member arriving from a real export is already a DN in the source layout
+// (LLDAP writes uid=alice,ou=people,...), while writeUser places the entry at
+// ou=users in the target. Passing the source DN through unchanged, as this did,
+// produced groups whose member: values named entries the migrated directory does
+// not contain — the migration completed and the memberships were dangling
+// (KEY-WP-0023). Found by generating LDIF from a live LLDAP export.
+//
+// Only the naming value is carried across; the branch and naming attribute come
+// from the target. Members are user IDs in the canonical model — no_cyclic_groups
+// rejects group IDs among them — so every member is resolved as a user.
 func resolveMemberDN(memberID, baseDN string, target Target) string {
+	name := memberID
 	if strings.Contains(memberID, ",") {
-		// Already a full DN — return as-is.
-		return memberID
+		name = firstRDNValue(memberID)
 	}
 	switch target {
 	case TargetAD:
-		return "cn=" + memberID + ",ou=users," + baseDN
+		return "cn=" + name + ",ou=users," + baseDN
 	default:
-		return "uid=" + memberID + ",ou=users," + baseDN
+		return "uid=" + name + ",ou=users," + baseDN
 	}
 }
 
+// firstRDNValue returns the value of a DN's leftmost RDN ("uid=alice,ou=people"
+// yields "alice"). A DN whose first component has no "=" is returned unchanged,
+// so a malformed member is carried through visibly rather than silently dropped.
+func firstRDNValue(dn string) string {
+	first := dn
+	if comma := strings.Index(dn, ","); comma >= 0 {
+		first = dn[:comma]
+	}
+	equals := strings.Index(first, "=")
+	if equals < 0 {
+		return dn
+	}
+	return strings.TrimSpace(first[equals+1:])
+}
+
 // splitDisplayName splits a display name at the first space.
 func splitDisplayName(displayName string) (first, last string) {
 	idx := strings.Index(displayName, " ")

src/internal/migration/toldap/generator_test.go

@@ -344,3 +344,98 @@ func TestGenerator_ValidationFailsForInvalidData(t *testing.T) {
 		t.Error("Generate should return error for user with empty username (invalid LDIF)")
 	}
 }
+
+// A member arriving as a source-layout DN must be rewritten into the target
+// layout, or the migrated directory carries groups whose members name entries it
+// does not contain. Found by generating LDIF from a live LLDAP export, where
+// members are uid=...,ou=people,... while entries are written to ou=users
+// (KEY-WP-0023).
+func TestMemberDNsAreRewrittenIntoTheTargetLayout(t *testing.T) {
+	export := &lldapexport.ExportResult{
+		Users:  []domain.User{{ID: "uid=admin,ou=people,dc=netkingdom,dc=local", Username: "admin", DisplayName: "Administrator"}},
+		Groups: []domain.Group{{ID: "cn=admins,ou=groups,dc=netkingdom,dc=local", Name: "admins", Members: []string{"uid=admin,ou=people,dc=netkingdom,dc=local"}}},
+	}
+	ldif, err := toldap.New(toldap.Config{BaseDN: "dc=netkingdom,dc=local", Target: toldap.TargetOpenLDAP}, telemetry.NoopEmitter{}).Generate(export)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(ldif, "member: uid=admin,ou=users,dc=netkingdom,dc=local") {
+		t.Errorf("member not rewritten into the target layout:\n%s", ldif)
+	}
+	if strings.Contains(ldif, "ou=people") {
+		t.Errorf("source layout leaked into the generated LDIF:\n%s", ldif)
+	}
+	// Every member must name an entry the same LDIF creates.
+	for _, line := range strings.Split(ldif, "\n") {
+		if !strings.HasPrefix(line, "member: ") {
+			continue
+		}
+		memberDN := strings.TrimPrefix(line, "member: ")
+		if !strings.Contains(ldif, "dn: "+memberDN) {
+			t.Errorf("member %q has no entry in the generated LDIF", memberDN)
+		}
+	}
+}
+
+// An Active Directory target uses cn= naming, and the rewrite must follow it.
+func TestMemberDNRewriteFollowsTargetNamingAttribute(t *testing.T) {
+	export := &lldapexport.ExportResult{
+		Users:  []domain.User{{ID: "uid=admin,ou=people,dc=x,dc=y", Username: "admin", DisplayName: "Administrator"}},
+		Groups: []domain.Group{{ID: "cn=admins,ou=groups,dc=x,dc=y", Name: "admins", Members: []string{"uid=admin,ou=people,dc=x,dc=y"}}},
+	}
+	ldif, err := toldap.New(toldap.Config{BaseDN: "dc=x,dc=y", Target: toldap.TargetAD}, telemetry.NoopEmitter{}).Generate(export)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(ldif, "member: cn=admin,ou=users,dc=x,dc=y") {
+		t.Errorf("AD member naming not applied:\n%s", ldif)
+	}
+}
+
+// groupOfNames makes member a MUST, so an empty group is not a loadable entry.
+// The export preserves empty groups, so the generator must emit one that loads
+// (KEY-WP-0023, found by loading generated LDIF into a real OpenLDAP).
+func TestEmptyGroupsGetALoadablePlaceholderMember(t *testing.T) {
+	export := &lldapexport.ExportResult{
+		Users:  []domain.User{{ID: "uid=admin,ou=people,dc=x,dc=y", Username: "admin", DisplayName: "Administrator"}},
+		Groups: []domain.Group{{ID: "cn=empty,ou=groups,dc=x,dc=y", Name: "empty"}},
+	}
+	ldif, err := toldap.New(toldap.Config{BaseDN: "dc=x,dc=y", Target: toldap.TargetOpenLDAP}, telemetry.NoopEmitter{}).Generate(export)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(ldif, "dn: cn=empty-group-placeholder,dc=x,dc=y") {
+		t.Errorf("placeholder entry not created:\n%s", ldif)
+	}
+	if !strings.Contains(ldif, "member: cn=empty-group-placeholder,dc=x,dc=y") {
+		t.Errorf("empty group has no member:\n%s", ldif)
+	}
+	// Every group entry must carry at least one member attribute.
+	for _, block := range strings.Split(ldif, "\n\n") {
+		if !strings.Contains(block, "objectClass: groupOfNames") {
+			continue
+		}
+		if !strings.Contains(block, "member: ") {
+			t.Errorf("group entry without a member attribute:\n%s", block)
+		}
+	}
+	// The placeholder must be defined before the group that references it.
+	if strings.Index(ldif, "dn: cn=empty-group-placeholder") > strings.Index(ldif, "dn: cn=empty,ou=groups") {
+		t.Error("placeholder is defined after the group referencing it")
+	}
+}
+
+// A directory with no empty groups migrates without any synthetic entry.
+func TestNoPlaceholderWhenEveryGroupHasMembers(t *testing.T) {
+	export := &lldapexport.ExportResult{
+		Users:  []domain.User{{ID: "uid=admin,ou=people,dc=x,dc=y", Username: "admin", DisplayName: "Administrator"}},
+		Groups: []domain.Group{{ID: "cn=admins,ou=groups,dc=x,dc=y", Name: "admins", Members: []string{"uid=admin,ou=people,dc=x,dc=y"}}},
+	}
+	ldif, err := toldap.New(toldap.Config{BaseDN: "dc=x,dc=y", Target: toldap.TargetOpenLDAP}, telemetry.NoopEmitter{}).Generate(export)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(ldif, "empty-group-placeholder") {
+		t.Errorf("synthetic entry emitted unnecessarily:\n%s", ldif)
+	}
+}

src/internal/validator/validator.go

@@ -117,6 +117,14 @@ func checkRawAttributesWellFormed(snap Snapshot) RuleResult {
 		// only by case are one attribute supplied twice, not two attributes.
 		seen := make(map[string]string, len(u.LDAPAttributes))
 		for key := range u.LDAPAttributes {
+			// Keys beginning with "_" are annotations this tooling writes into
+			// the snapshot itself -- the LLDAP adapter records
+			// "_validation_warning" here, for one. They are not directory
+			// attributes and must not be judged as though they were, or the
+			// exporter's own output fails validation (KEY-WP-0023).
+			if strings.HasPrefix(key, "_") {
+				continue
+			}
 			switch {
 			case strings.TrimSpace(key) == "":
 				r.Passed = false

src/internal/validator/validator_test.go

@@ -371,3 +371,24 @@ func findRule(results []validator.RuleResult, name string) validator.RuleResult
 	}
 	return validator.RuleResult{Rule: name, Passed: false, Message: "rule not found in report"}
 }
+
+// The LLDAP adapter records "_validation_warning" in LDAPAttributes, so the rule
+// must not judge the tooling's own annotations as directory attributes. Found by
+// validating a snapshot exported from a live LLDAP (KEY-WP-0023).
+func TestRawAttributes_IgnoresToolingAnnotations(t *testing.T) {
+	result := attributeRule(t, map[string]string{
+		"_validation_warning": "required_attributes_present: missing displayName",
+		"sn":                  "Example",
+	})
+	if !result.Passed {
+		t.Errorf("tooling annotation rejected: %s", result.Message)
+	}
+}
+
+// The exemption is for annotations only: a real attribute is still judged.
+func TestRawAttributes_ExemptionDoesNotWeakenTheRule(t *testing.T) {
+	result := attributeRule(t, map[string]string{"_note": "fine", "employee_id": "42"})
+	if result.Passed {
+		t.Error("expected the malformed real attribute to still fail")
+	}
+}