feature/controlled_access

[bwalsh]

Adds controlled_access field to DrsObject for Passport-aligned authorization semantics See #422

---

Summary

This PR introduces an optional controlled_access field to DrsObject and DrsObjectCandidate to explicitly represent object-level authorization requirements derived from GA4GH Passport visa claims.

This enables clients to select and persist the intended authorization domain (e.g. dataset, project) when registering objects via /objects/register.

---

Motivation

The current write API allows clients to submit GA4GH Passports, but:

• There is no standard way to indicate which visa applies when multiple are present
• There is no field on DrsObject to persist authorization intent
• Authorization decisions remain implicit and implementation-specific

This creates ambiguity in multi-project scenarios and reduces interoperability across DRS implementations.

---

Proposal

Add a new optional field:

controlled_access:
  type: array
  items:
    type: string

Semantics

• Each entry represents an authorization claim (typically derived from a GA4GH Passport visa)

• Claims SHOULD follow URL-based semantics:
  https://github.com/ga4gh-duri/ga4gh-duri.github.io/blob/master/researcher_ids/ga4gh_passport_v1.md#url-claims

• If controlled_access is:

  • missing or empty → object is open access for read
  • present → access requires a matching claim in the user’s Passport

---

Changes in this PR

Schema updates

• Added controlled_access to:

  • DrsObject
  • DrsObjectCandidate

/objects/register examples

Added examples demonstrating:

• Controlled-access object registration
• Open-access object registration
• Explicit claim assignment during registration

Response examples

Updated 201ObjectsCreated to include:

• Controlled-access object response
• Open-access object response

---

Example

Request

{
  "candidates": [
    {
      "name": "tumor-normal.cram",
      "controlled_access": [
        "https://auth.example.org/datasets/phs000123"
      ]
    }
  ],
  "passports": ["<passport-jwt>"]
}

Response

{
  "objects": [
    {
      "id": "drs_obj_123",
      "controlled_access": [
        "https://auth.example.org/datasets/phs000123"
      ]
    }
  ]
}

---

Use Cases

• Users with multiple visas selecting the correct authorization domain
• Controlled dataset ingestion pipelines
• Federated / bring-your-own-bucket storage scenarios
• Portable authorization semantics across DRS implementations

---

Backward Compatibility

• Field is optional
• Existing implementations remain fully compatible
• Older systems can ignore the field
• New systems can interpret absence as open access

This supports:

• Import of new records by older systems
• Import of legacy records by newer systems
• Incremental adoption in federated environments

---

Design Notes

• This does not store full Passport tokens
• It stores only authorization claims required for access
• Authorization enforcement remains implementation-specific
• Aligns with GA4GH Passport “clearinghouse” model

---

Open Questions

• Should we standardize “any vs all” matching semantics?

---

Addendum: Service Capability Advertisement via /service-info

Motivation

While the controlled_access field enables explicit object-level authorization semantics, clients also need a way to determine:

• Whether a DRS server supports this feature
• What claim format is expected
• What the default access behavior is

Without this, clients must rely on out-of-band knowledge or trial-and-error.

---

Proposal

Extend the DRS-specific portion of /service-info with the following optional fields:

"drs": {
  "controlledAccessSupported": true,
  "controlledAccessClaimFormat": "ga4gh-passport-url-claim",
  "controlledAccessDefault": "open-access-read"
}

---

Field Definitions

controlledAccessSupported (boolean)

• Indicates whether the server supports the controlled_access field
• If true, clients MAY include controlled_access in /objects/register
• If false or missing, clients SHOULD NOT rely on this feature

---

controlledAccessClaimFormat (string)

• Defines the expected format of claims in controlled_access
• Current value:
  • ga4gh-passport-url-claim

This aligns with GA4GH Passport visa claim semantics.

---

controlledAccessDefault (string)

• Defines how the server interprets missing or empty controlled_access

Current value:

• open-access-read
  → Object is treated as open access for read operations

---

Benefits

• Enables feature discovery for clients
• Supports graceful fallback in mixed-version environments
• Makes authorization semantics explicit and portable
• Aligns with GA4GH’s pattern of capability advertisement via /service-info

---

Backward Compatibility

• All fields are optional
• Existing clients and servers remain unaffected
• New clients can conditionally enable behavior based on support

---

Relationship to controlled_access Field

Concern	Addressed by
Object-level authorization	DrsObject.controlled_access
Client discoverability	/service-info fields
Interoperability	Both

---

Closing

This change makes authorization intent explicit, portable, and interoperable, while preserving backward compatibility and aligning with GA4GH Passport semantics. The service-info change complements the controlled_access field by ensuring that clients can reliably detect and correctly use the feature across DRS implementations.

🎯 Feedback very welcome, especially from implementers operating in federated or multi-tenant environments.

[bwalsh]

@grsr One caveat: the checksum parameter file in the feature/issue-416-drs-upload branch currently looks suspicious. The path is objects/checksum/{checksum}, but the referenced parameter text says name: access_id, which looks like a bug?

I've checked in a fix on this branch.