Repository: vscode
Issue: Proposal: Canonical URI identity provider
Labels: feature-request,api,on-testplan,api-proposal,workspace-trust,continue-working-on

In both edit sessions and workspace trust, we need to solve the problem of disambiguating URIs across filesystems. The approaches currently taken are:

- Edit sessions combines the remote, branch/tag name, and SHA to determine that two workspace snapshots occurring in two different filesystems are equal
    - Edit sessions does not know that repositories cloned with different protocols (HTTPS / SSH) are the same, since the conversion from a HTTPS to SSH URL is not standard across remote git providers
- Workspace trust uses the `getCanonicalUri` APi from the remote proposal to determine that a folder from the local filesystem which is mounted into a remote has already been trusted in the local filesystem
    - Workspace trust does not know that a repository has been trusted in say vscode.dev when it is cloned to the local filesystem and reopened in VS Code desktop
    - Also, it special cases vscode-vfs URIs by manipulating the authority field in order to know that two vscode-vfs URIs pointing to different branches on the same repository are in fact referencing the same repository (since vscode-vfs URIs encode the branch, tag, PR in the authority and do not compare equal when stringified)

This results in friction for users, who must repeatedly trust the same repository across different filesystems, and who are unable to roam workspace state for the same repository across two different filesystems if they have been cloned with different remotes.

To address both these scenarios, we would like to introduce an API proposal for transforming URIs if a URI has one or more alternate identities. This is not an inherently source control-specific concept, since you could have a folder on a local filesystem which is mounted into a container and not backed by source control, and in that scenario it should be possible to say that the local file:// URI is equivalent to the vscode-remote:// URI. It is also not an inherently remote-specific concept, since two file:// URIs for the same repository on two different filesystems should be resolvable to the same identity.

Prior art:
https://github.com/microsoft/vscode/blob/5df31a17c8559bdb61bda296e5e7677c57a5a0e8/src/vscode-dts/vscode.proposed.resolvers.d.ts#L133-L138

https://github.com/microsoft/vscode/blob/5df31a17c8559bdb61bda296e5e7677c57a5a0e8/src/vscode-dts/vscode.proposed.editSessionIdentityProvider.d.ts#L25-L32

Initial proposal:
```ts

declare module 'vscode' {
    export namespace workspace {
        export function registerCanonicalUriIdentityProvider(scheme: string, provider: CanonicalUriIdentityProvider): Disposable; // There can be multiple providers for the same scheme
    }

    export interface CanonicalUriIdentityProvider {
        provideCanonicalUriIdentity(uri: Uri, token: CancellationToken): ProviderResult<CanonicalUriIdentity | CanonicalUriIdentity[]>;
    }

    export interface CanonicalUriIdentity {
        host: string;
        metadata: string;
    }
}

```

Example usage:

| Provider | URI scheme | URI authority | Identity |
| -- | -- | -- | -- |
| Remote extensions | `vscode-remote` | `containers` | `{ host: 'file', metadata: 'filepath' }` |
| Builtin GitHub extension | `file` | `` | `{ host: 'github', metadata: 'microsoft/vscode' }` |
| GitHub Repositories extension | `vscode-vfs` | `github` | `{ host: 'github', metadata: 'owner/repo' }` |
| Azure Repos extension | `vscode-vfs` | `azurerepos` | `{ host: 'azurerepos', metadata: 'org/project/repo' }` |

An alternative solution for workspace trust is to instead leverage https://github.com/microsoft/vscode/issues/179898 and declare that a workspace has been trusted before by storing this information for `StorageScope.Workspace` and `StorageTarget.User`, which will lead to that information roamed via edit sessions. However that won't allow workspace trust to move away from the hack it does for `vscode-vfs` URIs, since edit sessions takes the branch and SHA into account, and `vscode-vfs` URIs bake that information in as well.