Merge 70d2005743 into 43c65786eb

Some clarifications to the release process doc, particularly in view of #2275.

.github/workflows/main.yml

@@ -195,6 +195,8 @@ jobs:
     needs: [calculate-baseurl, build-openapi, generate-changelog]
     # run even if generate-changelog was skipped
     if: ${{ always() }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
@@ -217,8 +219,10 @@ jobs:
         with:
           name: changelog-artifact
           path: content/changelog
+
       - name: "⚙️ hugo"
-        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
+        run: hugo --baseURL "${baseURL}" -d "spec${baseURL}"
+
       # We manually unpack the spec OpenAPI definition JSON to the website tree
       # to make it available to the world in a canonical place:
       # https://spec.matrix.org/latest/client-server-api/api.json
@@ -229,10 +233,13 @@ jobs:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec.tar.gz *
+
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4
         with:
@@ -261,14 +268,9 @@ jobs:
           name: spec-artifact
 
       - name: "📝 Unpack the spec"
-        # we have to unpack it into the right path given the baseurl, so that the
-        # links are correct.
-        # eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
         run: |
-          mkdir -p "spec${baseURL}"
+          mkdir spec
-          tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
+          tar -C spec -xvzf spec.tar.gz
-        env:
-          baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
 
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
@@ -278,8 +280,10 @@ jobs:
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest
-    needs: [build-openapi]
+    needs: [calculate-baseurl, build-openapi]
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
@@ -299,9 +303,8 @@ jobs:
       - name: "⚙️ hugo"
         env:
           HUGO_PARAMS_VERSION_STATUS: "historical"
-        # Create a baseURL like `/v1.2` out of the `v1.2` tag
         run: |
-          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
+          hugo --baseURL "${baseURL}" -d "spec${baseURL}"
 
       - name: "📥 Spec definition download"
         uses: actions/download-artifact@v4
@@ -309,10 +312,12 @@ jobs:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec-historical.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec-historical.tar.gz *
 
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4

.github/workflows/netlify.yaml

@@ -45,7 +45,9 @@ jobs:
           name: spec-artifact
 
       - name: "📦 Extract Artifacts"
-        run: tar -xzvf spec.tar.gz && rm spec.tar.gz
+        run: |
+          mkdir spec
+          tar -C spec -xzvf spec.tar.gz && rm spec.tar.gz
         
       - name: "📤 Deploy to Netlify"
         id: netlify

changelogs/client_server/newsfragments/2270.feature

@@ -0,0 +1 @@
+Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).

changelogs/internal/newsfragments/2276.feature

@@ -0,0 +1 @@
+Include the spec release version in the filenames in the tarballs generated by CI.

changelogs/internal/newsfragments/2289.clarification

@@ -0,0 +1 @@
+Updates to the release documentation.

changelogs/server_server/newsfragments/2288.clarification

@@ -0,0 +1 @@
+Specify that callers of `/_matrix/federation/v1/openid/userinfo` must validate the returned user ID.

content/client-server-api/_index.md

@@ -645,7 +645,7 @@ manage their account like [changing their password](#password-management),
 [deactivating their account](#account-deactivation).
 
 With the OAuth 2.0 API, all account management is done via the homeserver's web
-UI.
+UI that can be accessed by users via the [account management URL](#oauth-20-account-management).
 
 ### Legacy API
 
@@ -2271,6 +2271,56 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### Account management {id="oauth-20-account-management"}
+
+{{% added-in v="1.18" %}}
+
+All account management is done via the homeserver’s web UI as all endpoints that
+require User-Interactive Authentication are unsupported by this authentication
+API.
+
+This specification defines extensions to the [OAuth Authorization Server
+Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
+to offer clients a way to deep-link to the account management capabilities of
+the homeserver to allow the user to complete the account management operations
+in a browser.
+
+##### Account management URL discovery
+
+The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
+extended to include the following fields:
+
+| Field                                  | Description                                                                                     |
+|----------------------------------------|-------------------------------------------------------------------------------------------------|
+| `account_management_uri`               | The URL where the user is able to access the account management capabilities of the homeserver. |
+| `account_management_actions_supported` | An array of actions that the account management URL supports, as defined below.                 |
+
+##### Account management URL parameters
+
+The account management URL MAY accept the following query parameters:
+
+| Parameter   | Description                                                                                                                           |
+|-------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| `action`    | **Optional**. The action that the user wishes to take. Must match one of the actions in `account_management_actions_supported` above. |
+| `device_id` | **Optional**. Identifies a particular Matrix device ID for actions that support it.                                                   |
+
+If the `org.matrix.device_view` or `org.matrix.device_delete` actions are
+advertised as supported by the server then the server SHOULD support the
+`device_id` parameter.
+
+##### Account management URL actions
+
+The following account management actions are defined:
+
+| Action                           | Description                                                                                                                                          |
+|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `org.matrix.profile`             | The user wishes to view/edit their profile (name, avatar, contact details).                                                                          |
+| `org.matrix.devices_list`        | The user wishes to view a list of their devices.                                                                                                     |
+| `org.matrix.device_view`         | The user wishes to view the details of a specific device. A `device_id` should be provided.                                                          |
+| `org.matrix.device_delete`       | The user wishes to delete/log out a specific device. A `device_id` should be provided.                                                               |
+| `org.matrix.account_deactivate`  | The user wishes to deactivate their account.                                                                                                         |
+| `org.matrix.cross_signing_reset` | The user wishes to reset their cross-signing identity. Servers SHOULD use this action in the URL of the [`m.oauth`](#oauth-authentication) UIA type. |
+
 ### Account moderation
 
 #### Account locking

data/api/client-server/oauth_server_metadata.yaml

@@ -139,6 +139,32 @@ paths:
                     items:
                       type: string
                       description: A prompt value that the server supports.
+                  account_management_uri:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      The URL where the user is able to access the account management capabilities
+                      of the homeserver.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                  account_management_actions_supported:
+                    x-addedInMatrixVersion: "1.18"
+                    type: array
+                    description: |-
+                      List of actions that the account management URL supports.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                    items:
+                      type: string
+                      enum:
+                        - "org.matrix.profile"
+                        - "org.matrix.devices_list"
+                        - "org.matrix.device_view"
+                        - "org.matrix.device_delete"
+                        - "org.matrix.account_deactivate"
+                        - "org.matrix.cross_signing_reset"
+                      description: An action that the account management URL supports.
                 required:
                   - issuer
                   - authorization_endpoint

data/api/server-server/openid.yaml

@@ -43,7 +43,12 @@ paths:
                 properties:
                   sub:
                     type: string
-                    description: The Matrix User ID who generated the token.
+                    description: |
+                      The Matrix User ID who generated the token.
+
+                      The caller MUST validate that the returned user ID is on the server they
+                      called (i.e. if you make a request to example.com and it returns
+                      `@alice:matrix.org`, the result is invalid).
                     example: "@alice:example.com"
                 required:
                   - sub

meta/releasing.md

@@ -50,11 +50,6 @@ First, can we even release the spec? This stage is mostly preparation work neede
 to ensure a consistent and reliable specification.
 
 1. Ensure `main` is committed with all the spec changes you expect to be there.
-2. Review the changelog to look for typos, wording inconsistencies, or lines which
-   can be merged. For example, "Fix typos" and "Fix spelling" can be condensed to
-   "Fix various typos throughout the specification".
-3. Do a quick skim to ensure changelogs reference the MSCs which brought the changes
-   in. They should be linked to the GitHub MSC PR (not the markdown document).
 
 ## The release
 
@@ -79,20 +74,24 @@ release.
    2. Run `./scripts/generate-changelog.sh v1.2` (using the correct version number).
       The script will use the current date. If that date is wrong, correct the document
       by using the same `YYYY-MM-DD` date format.
-   3. Commit the result.
+   3. Review the changelog to look for typos, wording inconsistencies, or lines which
+      can be merged. For example, "Fix typos" and "Fix spelling" can be condensed to
+      "Fix various typos throughout the specification".
+   4. Do a quick skim to ensure changelogs reference the MSCs which brought the changes
+      in. They should be linked to the GitHub MSC PR (not the markdown document).
+   5. Commit the result.
+   6. Now is a good time to have someone else review the changelog.
 5. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
 6. Push the release branch and the tag.
 7. GitHub Actions will run its build steps. Wait until these are successful. If fixes
    need to be made to repair the pipeline or spec build, delete and re-tag the release.
    You may need to fix up the changelog file by hand in this case.
-8. Check out and fast-forward `main` to the release branch.
+8. GitHub Actions should have drafted a release based on the new tag. Find it
-9. Create a new release on GitHub from the newly created tag.
+   at https://github.com/matrix-org/matrix-spec/releases.
-   * The title should be just "v1.2" (for example).
+   1. Double-check the generated release notes, and check that `spec-artifact.zip` and
-   * The description should be a copy/paste of the changelog. The generated changelog
+      `spec-historical-artifact.zip` are both attached to the draft release.
-     will be at `content/changelog/v1.2.md` - copy/paste verbatim.
+   2. Publish the draft release.
-   * Upload the artifacts of the GitHub Actions build for the release to the GitHub
+9. Check out and fast-forward `main` to the release branch.
-     release as artifacts themselves. This should be the tarball that will be deployed
-     to spec.matrix.org.
 10. Commit a reversion to `params.version` of `./config/_default/hugo.toml` on `main`:
     ```toml
     [params.version]
@@ -103,7 +102,8 @@ release.
     ```
 11. Push pending commits and ensure the unstable spec updates accordingly from the
     GitHub Actions pipeline.
-12. Deploy the release on the webserver. See internal wiki.
+12. Deploy the release on the webserver. See "Spec release process" in the
+    internal handbook.
 
 ## Patching a release