Enhance policy imports in a way to customise the "subjects" of imported policy entries

[thjaeckle]

Overview

Currently, Policy imports work by effectively "copying" policy entries from an imported policy. There is no possibility to customize an imported policy entry, such as adding subjects or resources specific to the importing policy.

This enhancement proposes entriesAdditions - a way to additively merge subjects and resources into imported policy entries.

Use Case

Template policy (defines the "what" - resources and permissions):

{
  "policyId": "org.eclipse.ditto:vehicle-base-policy",
  "entries": {
    "fleet-manager": {
      "subjects": {},
      "resources": {
        "thing:/": { "grant": ["READ", "WRITE"], "revoke": [] },
        "policy:/": { "grant": ["READ"], "revoke": ["WRITE"] }
      },
      "importable": "implicit"
    },
    "technician": {
      "subjects": {},
      "resources": {
        "thing:/features/diagnostics": { "grant": ["READ"], "revoke": [] }
      },
      "importable": "explicit"
    }
  }
}

Importing policy (defines the "who" - subjects, plus additional resources):

{
  "policyId": "org.eclipse.ditto:truck-42-policy",
  "imports": {
    "org.eclipse.ditto:vehicle-base-policy": {
      "entries": ["technician"],
      "entriesAdditions": {
        "fleet-manager": {
          "subjects": {
            "idp:acme-fleet-managers": { "type": "ACME Fleet Manager Group" }
          }
        },
        "technician": {
          "subjects": {
            "idp:truck-technicians": { "type": "Truck Technician Group" }
          },
          "resources": {
            "thing:/features/engine": { "grant": ["READ"], "revoke": [] }
          }
        }
      }
    }
  }
}

Proposed Solution

Add an optional entriesAdditions object to policy imports with the following structure:

"entriesAdditions": {
  "<entry-label>": {
    "subjects": { ... },
    "resources": { ... }
  }
}

Merge Rules

Subjects:

• Additive only: subjects from entriesAdditions are merged with subjects from the template entry
• Each subject carries its own attributes (type, expiry, announcement)

Resources:

• Additive: new resource paths are added
• Overlapping paths: permission sets are merged (grants combined, revokes combined)
• Security guarantee: a revoke in the template cannot be removed by the importing policy

Example for overlapping resources:

Template:  thing:/ { grant: ["READ"],         revoke: ["WRITE"] }
Addition:  thing:/ { grant: ["READ","WRITE"], revoke: [] }
───────────────────────────────────────────────────────────────
Result:    thing:/ { grant: ["READ","WRITE"], revoke: ["WRITE"] }

Validation Behavior

• References to non-existent entry labels: silently ignored
• References to never-importable entries: silently ignored
• References to explicit entries not in entries array: silently ignored (entry not imported)
• Empty additions "operator": {}: valid, no effect
• Partial additions (only subjects or only resources): valid

Benefits

1. Separation of concerns: Template policies define resource structures, importing policies define who has access
2. Reusability: One template can be imported by many policies with different subjects
3. Flexibility: Importing policies can extend resources for specific use cases
4. Security: Revokes in templates cannot be overridden
5. Backward compatible: Existing imports continue to work unchanged