docs: ADR for universal drive app without user domain by shepilov · Pull Request #4652 · linagora/cozy-stack · GitHub

No description provided.

didn't read all the ADR yet.

if we are doing the old way to share aka duplication, do we have the same sharing-id / file-id on both instances ?

This URL /shares/{sharing-id}/files{file-id} is it the one displayed in the user's browser?

Yes, we have the same sharing_id, but not file_id, and there is nothing in this ADR about "old" shares, there's migration or anything, I assumed that they continue to work as is

Nope, it's API call

Why do we need to define new routes? Why can't we re use all the existing routes?

it's actually "old" routes, but if you use the same cozy-stack and not a new service, we will need to have a new middleware to detect that we are in "universal" mode, resolve an instance, and delegate further

Can't we create a new DNS entry:

universaldrive.twake.app that point to this "service".

So depending on the DNS you're targeting, you arrive or not on this universal mode.

And if you arrive on this new "service", we can accept "", resolve to an instance, and then deletage this "" to the right instance.

Maybe this is what you plan to do, but having listed only these 5 or 6 routes got my confused

Yes, exactly, I thought it was written somewhere there, I'll double-check

is is already the casE?

Nope, I'll check, but I don't think that we have an instance in the share-code right now, I didn't make any sense

Well, it depends of the sharecodes. Long sharecodes are JWT, with the instance URL in a field. But, what we use are shortcodes, and we need an instance to query the database to fetch the permissions document for them.

cc @paultranvan @zatteo @rezk2ll @doubleface since it means that we'll have things to change on cozy-client side.

cozy-client please, cozy-client-js is dead since 8 years :p

How can it be dead, if it's on all our apps?

Nop. https://github.com/cozy/cozy-client-js is deprecated since few years in favor of https://github.com/linagora/cozy-client .

@taratatach Maybe we can archive the cozy-client-js repo? Or at least put a big banner saying deprecated on this repo

To be fair, it was supposed to be dead 8 years ago, but still managed to painfully live until quite recently :)
The deprecated notice sounds good.

Today Drive app generates app as:

https://xxx-drive.twake.app/#/folder/io.cozy.files.root-dir

we'll never have:

https://drive.org.com/files/{file-id}

But I assume it will work with hash navigation too.

yes, it's just an example

No, it won't work with current URLs. For a public sharing, the first request the browser will send is https://drive.org.com/public/ (the sharecode is in the hash), and the html response from the stack must contain in the token of the app, which requires to know the instance, and we don't have any clue for that.

in fact, no, maybe it'll not work with the #hash navigation because server will never see that, and we'll lose the information during the redirection, no?

I think we need to change the way we handle the token from publish shared code too (from the front-end side)

We will authenticate with the external OIDC but we'll have a Lemon between the external OIDC and our app.

Our app will communication with this Lemon OIDC. And Lemon will communicate with the external OIDC. Like that, we can still have workplaceFQDN and everything. So, yes, it kinda a centralized stuff

In the current version, we have both usera.org.com (API calls), and usera-drive.org.com, with the drive assets (html, js, css, favicons, etc.). In the stack, it's two routers called router and appsHandler in web/routing.go.

Using the new domain for both the drive URLs and API calls may be a bit tricky:

looking at assets and then API calls: we don't want to check if an asset is present in Swift for every API call (too slow)
looking at API calls and then at assets: we may have some bad icons (I think both respond to / and /robots.txt

But if I understand correctly, you want to use drive.org.com for the drive assets/URLs, not API calls. Correct?

I don't understand why we are doing something different for realtime websockets and API calls.

Well, it depends of the sharecodes. Long sharecodes are JWT, with the instance URL in a field. But, what we use are shortcodes, and we need an instance to query the database to fetch the permissions document for them.

No, it won't work with current URLs. For a public sharing, the first request the browser will send is https://drive.org.com/public/ (the sharecode is in the hash), and the html response from the stack must contain in the token of the app, which requires to know the instance, and we don't have any clue for that.

We will need to update cozy-drive (or cozy-libs?) to use the new sharing-id encoding in public link: this URL is built on the front side, not on the server.

idem

I think CORS will work with the current code. But, we will need to update the CSP rules for that to work.

Yes, the tricky part is that the token for a user (not for a public link) requires that a cookie is present for a session for that user. It should work as drive.org.com and usera.org.com are both subdomains of .org.com, and that the cookie should be set on .org.com.

docs: ADR for universal drive app without user domain

096a1b0

shepilov requested a review from a team as a code owner January 28, 2026 14:59

Crash-- reviewed Jan 29, 2026

View reviewed changes

Crash-- reviewed Jan 30, 2026

View reviewed changes

nono reviewed Feb 3, 2026

View reviewed changes

docs: ADR for universal drive app without user domain v2

235125f

shepilov force-pushed the adr_universal_drive branch from df91ad6 to 235125f Compare March 13, 2026 16:35

shepilov mentioned this pull request Jul 16, 2026

Universal drive - Private URL for shared ressource linagora/twake-drive#4035

Open

+              | URL Pattern | Description | Routing | Auth Required |
+              |-------------|-------------|---------|---------------|
+              | `/files/{file-id}` | Personal files | Route to authenticated user's instance | Yes |
+              | `/shares/{sharing-id}/files/{file-id}` | Shared drive files | Query user's instance for sharing info | Yes |

+              |-------------|-------------|---------|---------------|
+              | `/files/{file-id}` | Personal files | Route to authenticated user's instance | Yes |
+              | `/shares/{sharing-id}/files/{file-id}` | Shared drive files | Query user's instance for sharing info | Yes |
+              | `/public/{encoded-sharecode}` | Public link files | Decode sharecode to find instance | No |

+              window.cozyData = {
+                "token": "eyJhbG...",
+                "domain": "drive.org.com",           // API calls via Universal Drive
+                "realtimeDomain": "usera.org.com",   // WebSocket direct to user's instance

+              ```
+              ┌──────────────────────────────────────────────────────────────────┐
+              │                        User's Browser                             │
+              │  URL: https://drive.org.com/files/{file-id}                      │

+                     │                                   │                                      │
+                     │  2. 302 Redirect to Registration  │                                      │
+                     │     /auth?client_id=drive&        │                                      │
+                     │     redirect_uri=drive.org/cb     │                                      │

+              The frontend uses `cozyData.domain` for all API calls:
+              ```javascript
+              // cozy-client-js reads domain from cozyData

+              | Component | Changes Needed |
+              |-----------|----------------|
+              | **cozy-drive frontend** | Minor: Support `realtimeDomain` for WebSocket connections |


		Option A: Federated OIDC Authentication

		Allow users to authenticate with their home organization's IdP when accessing another organization's Universal Drive.

+              Current:  usera.org.com/drive  ← UserA's drive
+                        userb.org.com/drive  ← UserB's drive
+              Proposed: drive.org.com        ← Universal Drive for all users in org


		WebSocket connections for realtime events (file changes, notifications) connect directly to the user's instance domain rather than through the Universal Drive domain. This avoids the complexity of WebSocket proxying and provides better performance.

		Approach: Inject a separate `realtimeDomain` in cozyData:

+                Original: sharing-id = "abc123def" owned by usera.org.com
+                Encoded:  sharing-id = "dXNlcmE6YWJjMTIzZGVm" (base64 of "usera:abc123def")
+              URL: /shares/dXNlcmE6YWJjMTIzZGVm/files/{file-id}

+              Example:
+                Original: ?sharecode=abc123 on usera.org.com
+                Encoded:  /public/dXNlcmE6YWJjMTIz (base64 of "usera:abc123")

+              **Required changes:**
+. **cozy-client/cozy-realtime:** Check for `realtimeDomain` in cozyData, use it for WebSocket URL
+. **CORS:** Configure cozy-stack to accept WebSocket connections with Universal Drive origin

docs: ADR for universal drive app without user domain by shepilov · Pull Request #4652 · linagora/cozy-stack · GitHub

Repository navigation

docs: ADR for universal drive app without user domain - #4652

docs: ADR for universal drive app without user domain#4652shepilov wants to merge 2 commits intomasterlinagora/cozy-stack:masterfrom adr_universal_drivelinagora/cozy-stack:adr_universal_driveCopy head branch name to clipboard

Conversation

shepilov commented Jan 28, 2026

Uh oh!

Crash-- left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

docs: ADR for universal drive app without user domain#4652
shepilov wants to merge 2 commits into
masterfrom
adr_universal_drive