#2325 add namespace support for policies

[hu-ahmed]

Resolves #2325

Add support for namespace-scoped policy entries via a new optional namespaces field on PolicyEntry.

A scoped policy entry only applies to Things whose namespace matches at least one configured pattern.
If namespaces is omitted or empty, the entry remains globally applicable for backward compatibility.

Supported matching semantics:

• com.acme matches only the exact namespace com.acme
• com.acme.* matches nested namespaces such as com.acme.vehicles, but not com.acme itself

[hu-ahmed]

update system test eclipse-ditto/ditto-testing#24

[thjaeckle]

QA Review — Namespace-Scoped Policy Entries

Clean design overall. The opt-in namespaces field on policy entries with backward-compatible empty-list semantics is well chosen. Enforcement, search indexing, event sourcing strategies, and JSON round-tripping all look correct. Good test coverage for the model layer.

Two findings to flag at the PR level:

---

CRITICAL: OpenAPI bundled file ditto-api-2.yml not regenerated

The PR adds documentation/src/main/resources/openapi/sources/schemas/policies/namespaces.yml and modifies policyEntry.yml, but the bundled ditto-api-2.yml is not regenerated. Per project convention, modifications to OpenAPI source files require running:

cd documentation/src/main/resources/openapi/sources && npm install && npm run build

and committing the regenerated output.

---

HIGH: forNamespace() returns unfiltered policy with a filtered enforcer

return new PolicyEnforcer(policy, filteredEnforcer);

After forNamespace(), getEnforcer() sees only entries that match the namespace, but getPolicy() returns the full unfiltered policy (including all scoped entries). Any code path that reads getPolicy() on the filtered enforcer — e.g., to extract subjects, build response headers, or check entry labels — would see entries that the enforcer does NOT enforce.

This is currently safe because the existing code uses getEnforcer() for permission checks, but it's a foot-gun for future callers. Consider either:

• Documenting this invariant explicitly in forNamespace()'s Javadoc ("the returned enforcer's getPolicy() is unfiltered")
• Or building a filtered Policy object alongside the filtered Enforcer

---

System test coverage (ditto-testing PR eclipse-ditto/ditto-testing#24)

The two system tests in PR eclipse-ditto/ditto-testing#24 cover the core positive/negative scenarios well:

• getThingWithNamespaceScopedPolicyEntry — direct policy with scoped entry
• getThingWithNamespaceScopedAuthorizationInImportedPolicy — imported policy with scoped entry

Missing system-level coverage:

• Search visibility: a user granted access via namespace-scoped entry should find the allowed thing via search (/api/2/search/things) but NOT the denied thing. The EvaluatedPolicy.of() change looks correct, but there's no integration test verifying search results respect namespace scoping end-to-end.

[thjaeckle]

In general a thing I encountered: the namespaces parameter should be in every API and example listed directly below subjects and resources.
This defines the "trinity" of "who", "what" and "where" (namespaces is "where") - and should be close together.

I added some inline remarks about that - but as this covers the whole PR, it should be addressed everywhere :)

Also, the recently added allowedImportAdditions should also be extended with namespaces as well.

[thjaeckle]

@hu-ahmed could you please rebase this PR from master now that #2367 was merge?

[thjaeckle]

@hu-ahmed system tests run has 1 error in a CheckPermissionsIT - could you check, please?

https://github.com/eclipse-ditto/ditto/actions/runs/23442796589#user-content-tr-6zeiug-r65

[thjaeckle]

System tests passed: https://github.com/eclipse-ditto/ditto/actions/runs/23442796589