Add general_access field on sharing doc to store a single access level for general access

[cwperks]

Description

Replaces the previous convention of using a "*" wildcard in recipient lists to represent publicly shared resources with a dedicated general_access field on the ShareWith object.

This field stores a single access level string (for example, "read_only") at which the resource is accessible to everyone, mirroring the Google Docs model where a document has one public access level while named recipients can independently hold higher levels.

Category

Refactoring, Enhancement

Why these changes are required

The wildcard approach was semantically ambiguous. "*" in a users list looked like just another principal value, required special-case parsing logic in Recipients.fromXContent, and made it impossible to express "publicly readable but only Alice can write" without conflating the two concerns.

The new field makes public sharing a first-class concept that is orthogonal to named-recipient sharing.

What is the old behavior before these changes?

Public sharing was represented by placing "*" in a recipient list, for example:

"users": ["*"]

isPublic() scanned all recipient sets for the wildcard. Only one blanket public state was possible, with no access-level granularity.

What is the new behavior after these changes?

A dedicated general_access field on share_with stores the single access level granted to everyone:

"general_access": "<access_level>"

Named recipients at other access levels are unaffected. isPublic() becomes a direct field read. The "*" sentinel is also replaced by "public" in the all_shared_principals index field used for query matching.

Note: general_access cannot be set to a share-capable level — the API rejects with 400 BAD_REQUEST any payload where general_access resolves to include cluster:admin/security/resource/share. Enforced in ShareRequest.Builder.rejectSharePermissionOnGeneralAccess.

API Examples

Set general access (PUT) — everyone can read, Alice can write:

PUT /_plugins/_security/api/resource/share
{
  "resource_id": "<resource_id>",
  "resource_type": "<resource_type>",
  "share_with": {
    "general_access": "read_only",
    "read_write": {
      "users": ["alice"]
    }
  }
}

Set general access only (PUT) — everyone can read:

PUT /_plugins/_security/api/resource/share
{
  "resource_id": "<resource_id>",
  "resource_type": "<resource_type>",
  "share_with": {
    "general_access": "read_only"
  }
}

Upgrade general access level (PUT) — replace read with read_write:

PUT /_plugins/_security/api/resource/share
{
  "resource_id": "<resource_id>",
  "resource_type": "<resource_type>",
  "share_with": {
    "general_access": "read_write"
  }
}

Set general access (PATCH) — set or upgrade the public access level:

PATCH /_plugins/_security/api/resource/share
{
  "resource_id": "<resource_id>",
  "resource_type": "<resource_type>",
  "general_access": "read_write"
}

Revoke general access (PATCH) — remove public access by setting to null:

PATCH /_plugins/_security/api/resource/share
{
  "resource_id": "<resource_id>",
  "resource_type": "<resource_type>",
  "general_access": null
}

GET sharing info response shape (after setting general access):

{
  "sharing_info": {
    "resource_id": "<resource_id>",
    "resource_type": "<resource_type>",
    "created_by": { "user": "admin" },
    "share_with": {
      "general_access": "read_only",
      "read_write": {
        "users": ["alice"]
      }
    }
  }
}

Issues Resolved

N/A

Do these changes introduce new permission(s) to be displayed in the static dropdown on the front-end?

No.

Testing

Unit tests in ShareWithTests and ResourceSharingTests were updated to reflect the new field.

Integration tests in PubliclySharedDocTests were fully rewritten to cover:

• General read access grants everyone read but not write
• General full access grants everyone full content access
• General read + named recipient write (the mixed access scenario)
• Revoking general access removes public access
• Users with only general access cannot modify sharing info
• Setting general access to a share-capable level is rejected (400)
• Upgrading general access level replaces the previous value
• General access makes resource appear in list and search results
• GET sharing info response correctly serializes general_access

Check List

• New functionality includes testing
• New functionality has been documented
• New Roles/Permissions have a corresponding security dashboards plugin PR
• API changes companion pull request created
• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[codecov]

Codecov Report

❌ Patch coverage is 77.27273% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.84%. Comparing base (adf4a40) to head (752e4cb).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...rch/security/resources/api/share/ShareRequest.java	63.63%	5 Missing and 3 partials ⚠️
...ensearch/security/resources/sharing/ShareWith.java	75.00%	2 Missing and 5 partials ⚠️
...arch/security/resources/ResourceAccessHandler.java	60.00%	4 Missing ⚠️
...ecurity/resources/ResourceSharingIndexHandler.java	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6033      +/-   ##
==========================================
+ Coverage   73.79%   73.84%   +0.04%     
==========================================
  Files         440      440              
  Lines       27259    27371     +112     
  Branches     4052     4083      +31     
==========================================
+ Hits        20117    20213      +96     
- Misses       5227     5234       +7     
- Partials     1915     1924       +9     

Files with missing lines	Coverage Δ
...ch/security/resources/ResourceSharingDlsUtils.java	73.91% <100.00%> (ø)
...rity/resources/api/share/ShareTransportAction.java	94.73% <100.00%> (+0.61%)	⬆️
...nsearch/security/resources/sharing/Recipients.java	73.68% <100.00%> (-1.73%)	⬇️
...ch/security/resources/sharing/ResourceSharing.java	80.23% <100.00%> (-1.65%)	⬇️
...ecurity/resources/ResourceSharingIndexHandler.java	67.59% <85.71%> (+0.46%)	⬆️
...arch/security/resources/ResourceAccessHandler.java	73.28% <60.00%> (-0.48%)	⬇️
...ensearch/security/resources/sharing/ShareWith.java	75.78% <75.00%> (-0.47%)	⬇️
...rch/security/resources/api/share/ShareRequest.java	67.25% <63.63%> (+0.58%)	⬆️

... and 9 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.