[susnux]

• closes wip: governance api #65591

Summary

NCU\Governance\ILabelManager reads the labels assigned to resources and assigns or removes them. The labels are managed by the governance app, core checks the access of the actor to the resource before delegating to it and dispatches an event for every label that was assigned or removed.

The access of an actor to resources is available to apps through NCU\Resource\Permission\IAccessManager.

Entities of this API

Apps only see ILabelManager. The core manager is the one bound in the container.
It checks access and dispatches events, and hands everything about labels to the governance app.
There is no registration: core looks up one known class when the app is enabled.

Details

flowchart LR
    A["Any app<br/>e.g. Tables, Mail, Files"] -->|"ILabelManager"| C["Core label manager<br/>OC\Governance\LabelManager"]
    C -->|"getAccess()"| AM["IAccessManager<br/>from #66612"]
    AM --> RT["Resource type of the owning app"]
    C -->|"same ILabelManager interface"| G["Governance app<br/>OCA\Governance\Service\LabelManager"]
    C -->|"LabelAssignedEvent<br/>LabelRemovedEvent"| L["Listeners in any app"]
    G --> S[("Labels, rules and<br/>assignments")]

Loading

Reading labels

One call for the whole list. Resources the actor cannot access never reach the governance app, and they come back with
an empty list, so "no labels" and "no access" look the same to the caller.

Details

sequenceDiagram
    autonumber
    participant T as Tables
    participant C as Core label manager
    participant AM as IAccessManager
    participant G as Governance app

    T->>C: getAssignedLabelsForResources(Alice, [table 1, table 2, table 3])
    C->>AM: getAccess(Alice, [table 1, table 2, table 3])
    AM-->>C: table 1 and table 3, table 2 left out
    C->>G: getAssignedLabelsForResources(Alice, [table 1, table 3])
    G-->>C: table 1: Internal, Audit hold · table 3: none
    C-->>T: table 1: 2 labels · table 2: [] · table 3: []
    Note over T: every requested key is present

Loading

Assigning a label

Core reads the assigned labels before and after the change and dispatches one event per difference.
That is how placed sensitivity label produces a removed event without core knowing the rule "one sensitivity label per resource".

Details

sequenceDiagram
    autonumber
    participant T as Tables
    participant C as Core label manager
    participant AM as IAccessManager
    participant G as Governance app
    participant E as Event dispatcher

    T->>C: assignLabel(Alice, table 1, "Confidential", reason)
    C->>AM: getAccess(Alice, [table 1])
    AM-->>C: entries for table 1
    C->>G: getAssignedLabels(Alice, table 1)
    G-->>C: before: Internal
    C->>G: assignLabel(Alice, table 1, "Confidential", reason)
    Note over G: checks its own rules, replaces Internal,<br/>writes the audit entry
    C->>G: getAssignedLabels(Alice, table 1)
    G-->>C: after: Confidential
    C->>E: LabelRemovedEvent(Alice, table 1, Internal, sensitivity)
    C->>E: LabelAssignedEvent(Alice, table 1, Confidential, sensitivity)
    C-->>T: done

Loading

Potential outcomes

Details

flowchart TD
    W["assignLabel() or removeLabel()"] --> R{"Resource type registered?"}
    R -->|no| X1["InvalidArgumentException"]
    R -->|yes| B{"Governance app enabled?"}
    B -->|no| X2["GovernanceUnavailableException"]
    B -->|yes| AC{"Actor has access to the resource?"}
    AC -->|no| X3["ResourceNotFoundException"]
    AC -->|yes| G["Governance app decides"]
    G -->|"label unknown or does not apply<br/>to this resource"| X4["LabelNotFoundException"]
    G -->|"actor may not change it,<br/>or reason missing"| X5["LabelPermissionException"]
    G -->|ok| D{"Assigned labels changed?"}
    D -->|yes| EV["Events dispatched"]
    D -->|no| NE["No event"]

Loading

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI