Rationalize criteria and requirements

[glpatcern]

Following recent work on the Code flow (#354) and the discussion at the last OCM meeting, this is a proposal to reword some criteria and requirements, aiming at a more rationalized terminology and reinforcing the fact that criteria are a "must" and act as global requirements.

The currently defined criteria are:

- http-request-signatures
- token-exchange
- denylist
- allowlist
- invite

Where the requirements are:

- must-use-mfa
- must-exchange-token

--

I propose to name the criteria as:

- allowlist
- denylist
- must-exchange-token
- must-invite
- must-use-http-sig
- must-use-mfa

And the requirements as:

- must-exchange-token
- must-use-http-sig
- must-use-mfa

If the proposal is accepted, I can create a PR to adapt the OpenAPI and the I-D.

cc @MahdiBaghbani @mickenordin

[MahdiBaghbani]

Thanks for opening this. I agree the naming around code flow has been confusing for a long time, and cleaner labels help

I wanted to add one constraint from implementation work, because renaming alone does not fully remove the ambiguity that showed up while wiring code flow across Reva and Nextcloud

After OCM-API #354 merged, the distinction that mattered in practice was not only "must" wording, but which artifact carries the rule:

1. discovery versus the Share Creation Notification body

and which server role the text is about

2. Receiving Server inbound admission versus Sending Server outbound share payload

[MahdiBaghbani]

Discovery criteria

today token-exchange, inbound policy

Take provider B. When B publishes token-exchange in discovery criteria, B is describing how B behaves as Receiving Server: B will not accept Share Creation Notifications unless the WebDAV protocol on that notification includes must-exchange-token in protocol.webdav.requirements. In other words, it is an admission rule for incoming shares from remote senders

Share protocol.webdav.requirements

must-exchange-token, per-share contract

When provider A sends a share, A may place must-exchange-token on that share. That is A speaking as Sending Server: whoever consumes the resource as sharee must complete token exchange against A's tokenEndPoint. Legacy direct use of the long-lived sharedSecret for WebDAV access is not enough for that share. The sender is imposing the strict contract on recipients, not describing B's inbound policy

Those two planes are related (the preflight paragraph in #354 ties them together), but they are not the same object. One lives in discovery and gates acceptance of notifications. The other lives on the share payload and gates how access must work for that specific resource

So, discovery criteria is not a global default that fills in protocol.webdav.requirements for shares

Those requirements stay per share on the notification; criteria only states what a receiver will accept inbound and the preflight rules connect the two when both providers can do code flow

[MahdiBaghbani]

I am in favor of the rename direction, sharper must-* labels in discovery will help, my preference would be something different than must-* to distinguish them better both as reader or implementor
The one place I would disagree with the issue text is the idea that criteria "act as global requirements"

[glpatcern]

Thanks for the detailed insights. I must say that I had assumed criteria to also apply the other way around, that is e.g. a Sending Server exposing the token-exchange criteria would only offer shares with must-exchange-token as requirements. But I see your point makes more sense and is less redundant - after all, the contract of a given share lies in the requirements of that share only.

Now to avoid any confusion, I'm also open to not enforce that criteria use the same strings as requirements. I'd still be in favor of using must-* for requirements, no opinion for criteria.

At this point I'm also willing to reconsider or challenge the scope of criteria: is this useful or is it only adding an extra "pre-flight check" that would still be fulfilled by the requirements?

[mickenordin]

I would love to discuss this in the interim meeting, if you feel like making a presentation and bringing up the various points?

[glpatcern]

Yep, this is a perfect topic for the interim meeting! I can prepare something, yes. The agenda is pretty packed though!

[MahdiBaghbani]

I cannot join the interim meeting, this is my substitute, so the thread still gets an answer.
Anyone on the call is welcome to reuse pieces verbatim.

On criteria versus requirements in the wire model

My read is that they are still doing different jobs.

criteria are the discovery time, provider wide way of saying how this instance behaves when it is the Receiving Server.
Share requirements are the per-notification contract for this share. They are clearly related, especially once both sides speak with a must-* vocabulary, but they are not the same slot in the wire model.

If we only had must-exchange-token on the share, a sender could still attach it when it wants a strict share, but we would not have a standard place in /.well-known/ocm that says, "we reject inbound shares that do not commit to code flow".
You can recover that knowledge by trying to create a share and getting rejected, or by local policy, but that is weaker loose coupling than publishing the rule once in discovery.

That is the main thing I tried to do in #354: token-exchange in criteriaas receiver-side strict policy, must-exchange-token on the share as the strict per-share term, and sender pre-flight language as the glue (including the deadlock case where the receiver requires code flow and the sender cannot host tokenEndPoint).

Trade-off if we remove or collapse criteria

There is a real upside to cutting them: smaller surface area, fewer Enums, less mental overhead for someone reading the spec for the first time.

The downside is that receivers lose a stable, peer-wide channel to advertise incoming admission policy.
Without that, senders lean on try-and-fail, unspecified error handling, or configuration that is not part of OCM itself.
That might still be acceptable to some deployments, but it is a conscious interop trade-off, not a free deletion.

I do think the problem they solve is genuine: "what does this peer require in general when it receives?" is not answered by a single share object on its own.

Some other thoughts I had during working with Reva and Nextcloud (especially Nextcloud migration):

Old OCM stacks never parsed criteria or exchange-token and send legacy shares anyway.

That is true, and it stays true. Unknown discovery fields are usually ignored on older parsers; senders that never upgraded still emit legacy-shaped shares. That does not make criteria redundant.

It means strict inbound is a contract between capable peers, while legacy remains the long-tail interop baseline. The receiver that wants strict still needs a standard wire statement of its inbound gate, the capable sender still needs a standard place to read that gate before POSTing.

Parsers that do not understand it simply stay on the legacy path, which is the compatibility story we already live with for every new OCM field.

[MahdiBaghbani]

Implementation reality check (PR heads: Nextcloud + Reva)

Nextcloud outgoing

CloudFederationFactory::getCloudFederationShare() sets $useExchangeToken only from remote discovery capabilities (in_array('exchange-token', ...)). It does not consult peer criteria and does not add must-exchange-token to the payload.
See CloudFederationFactory.php L43-L102.

When $useExchangeToken is true, CloudFederationShare still serializes protocol.webdav with uri, sharedSecret, and permissions only (still no requirements).
See CloudFederationShare.php L72-L81.

Nextcloud receiver (discovery + token endpoint, not share-level strict)

On this PR head, External/Storage constructor still reads remote OCM discovery for exchange-token, then chooses bearer when there is a stored access token or when discovery advertises code flow and the mount token passes shareTokenSupportsExchange (length heuristic so pre-upgrade legacy rows are not pushed onto bearer just because the sender started advertising exchange-token).
SeeStorage.php L82-L107.

Ongoing access uses the DAV token exchange path via refreshBearerToken calling exchangeRefreshTokenResponse (not must-exchange-token on the stored notification).

Earlier iterations on the same PR discuss the failure mode when discovery flips and legacy rows were treated like strict bearer mounts; see the thread on enriquepablo/server#2.

Reva outgoing

ocGraph remote creation passes an empty WebDAV requirements slice into CreateOCMShare:
shares.go L190-L204.

CLI share creation does the same: ocm-share-create.go L193-L201.

The gRPC ocmshareprovider forwards CS3 Requirements as-is and does not add must-exchange-token:
ocmshareprovider.go L183-L197.

My conclusion

both PR heads still ship WebDAV payloads with empty requirements while leaning on capability / discovery and runtime exchange for the modern path.
That matches the optional branch of the post-#354 story, it is not the strict contract that needs must-exchange-token plus honest inbound criteria on the receiver.

[MahdiBaghbani]

BTW I'm trying to add the missing part, outgoing must-exchange-token to both of Reva and Nextcloud, one day it would be finished :-)