diff --git a/.babelrc b/.babelrc deleted file mode 100644 index 6e6720bbf11..00000000000 --- a/.babelrc +++ /dev/null @@ -1,22 +0,0 @@ -{ - "sourceMaps": true, - "presets": [ - [ - "@babel/preset-env", - { - "targets": { - "node": 10 - }, - "modules": "commonjs" - } - ], - "@babel/preset-typescript" - ], - "plugins": [ - "@babel/plugin-proposal-numeric-separator", - "@babel/plugin-proposal-class-properties", - "@babel/plugin-proposal-object-rest-spread", - "@babel/plugin-syntax-dynamic-import", - "@babel/plugin-transform-runtime" - ] -} diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 00000000000..a40510e62c7 --- /dev/null +++ b/.eslintignore @@ -0,0 +1 @@ +_docs diff --git a/.eslintrc.js b/.eslintrc.cjs similarity index 80% rename from .eslintrc.js rename to .eslintrc.cjs index e0150cca7d1..7bad5c8177a 100644 --- a/.eslintrc.js +++ b/.eslintrc.cjs @@ -1,5 +1,5 @@ module.exports = { - plugins: ["matrix-org", "import", "jsdoc"], + plugins: ["matrix-org", "import", "jsdoc", "n"], extends: ["plugin:matrix-org/babel", "plugin:matrix-org/jest", "plugin:import/typescript"], parserOptions: { project: ["./tsconfig.json"], @@ -49,6 +49,26 @@ module.exports = { }, ], + "no-restricted-properties": [ + "error", + { + object: "window", + property: "setImmediate", + message: "Use setTimeout instead.", + }, + ], + "no-restricted-globals": [ + "error", + { + name: "setImmediate", + message: "Use setTimeout instead.", + }, + { + name: "global", + message: "Use globalThis instead.", + }, + ], + "import/no-restricted-paths": [ "error", { @@ -92,10 +112,8 @@ module.exports = { "@typescript-eslint/ban-ts-comment": "off", // We're okay with assertion errors when we ask for them "@typescript-eslint/no-non-null-assertion": "off", - - // The non-TypeScript rule produces false positives - "func-call-spacing": "off", - "@typescript-eslint/func-call-spacing": ["error"], + // We do this sometimes to brand interfaces + "@typescript-eslint/no-empty-object-type": "off", "quotes": "off", // We use a `logger` intermediary module @@ -103,11 +121,8 @@ module.exports = { }, }, { - // We don't need amazing docs in our spec files files: ["src/**/*.ts"], rules: { - "tsdoc/syntax": "error", - // We use some select jsdoc rules as the tsdoc linter has only one rule "jsdoc/no-types": "error", "jsdoc/empty-tags": "error", "jsdoc/check-property-names": "error", @@ -115,6 +130,15 @@ module.exports = { // These need a bit more work before we can enable // "jsdoc/check-param-names": "error", // "jsdoc/check-indentation": "error", + // Ensure .ts extension on imports outside of tests + "n/file-extension-in-import": [ + "error", + "always", + { + tryExtensions: [".ts"], + }, + ], + "no-extra-boolean-cast": "error", }, }, { diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 10870d97175..2c2f2441388 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,11 +2,13 @@ /.github/workflows/** @matrix-org/element-web-team /package.json @matrix-org/element-web-team /yarn.lock @matrix-org/element-web-team +/scripts/** @matrix-org/element-web-team /src/webrtc @matrix-org/element-call-reviewers /src/matrixrtc @matrix-org/element-call-reviewers /spec/*/webrtc @matrix-org/element-call-reviewers /spec/*/matrixrtc @matrix-org/element-call-reviewers +/src/crypto-api @matrix-org/element-crypto-web-reviewers /src/crypto @matrix-org/element-crypto-web-reviewers /src/rust-crypto @matrix-org/element-crypto-web-reviewers /spec/integ/crypto @matrix-org/element-crypto-web-reviewers diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index bbaaa050791..9bab56710bd 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,12 +2,7 @@ ## Checklist -- [ ] Tests written for new code (and old code if feasible) -- [ ] Linter and other CI checks pass -- [ ] Sign-off given on the changes (see [CONTRIBUTING.md](https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md)) - - +- [ ] Tests written for new code (and old code if feasible). +- [ ] New or updated `public`/`exported` symbols have accurate [TSDoc](https://tsdoc.org/) documentation. +- [ ] Linter and other CI checks pass. +- [ ] Sign-off given on the changes (see [CONTRIBUTING.md](https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md)). diff --git a/.github/actions/sign-release-tarball/action.yml b/.github/actions/sign-release-tarball/action.yml index cd663cd873c..c081c80a0e2 100644 --- a/.github/actions/sign-release-tarball/action.yml +++ b/.github/actions/sign-release-tarball/action.yml @@ -22,7 +22,7 @@ runs: - name: Upload tarball signature if: ${{ inputs.upload-url }} - uses: shogo82148/actions-upload-release-asset@dccd6d23e64fd6a746dce6814c0bde0a04886085 # v1 + uses: shogo82148/actions-upload-release-asset@8482bd769644976d847e96fb4b9354228885e7b4 # v1 with: upload_url: ${{ inputs.upload-url }} asset_path: ${{ env.VERSION }}.tar.gz.asc diff --git a/.github/actions/upload-release-assets/action.yml b/.github/actions/upload-release-assets/action.yml index 25eb7f03940..4371ed41b7c 100644 --- a/.github/actions/upload-release-assets/action.yml +++ b/.github/actions/upload-release-assets/action.yml @@ -29,13 +29,13 @@ runs: - name: Upload asset signatures if: inputs.gpg-fingerprint - uses: shogo82148/actions-upload-release-asset@dccd6d23e64fd6a746dce6814c0bde0a04886085 # v1 + uses: shogo82148/actions-upload-release-asset@8482bd769644976d847e96fb4b9354228885e7b4 # v1 with: upload_url: ${{ inputs.upload-url }} asset_path: ${{ inputs.asset-path }}.asc - name: Upload assets - uses: shogo82148/actions-upload-release-asset@dccd6d23e64fd6a746dce6814c0bde0a04886085 # v1 + uses: shogo82148/actions-upload-release-asset@8482bd769644976d847e96fb4b9354228885e7b4 # v1 with: upload_url: ${{ inputs.upload-url }} asset_path: ${{ inputs.asset-path }} diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 00000000000..88fecb62ea6 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,43 @@ +- name: "A-Element-R" + description: "Issues affecting the port of Element's crypto layer to Rust" + color: "bfd4f2" +- name: "A-Packaging" + description: "Packaging, signing, releasing" + color: "bfd4f2" +- name: "A-Technical-Debt" + color: "bfd4f2" +- name: "A-Testing" + description: "Testing, code coverage, etc." + color: "bfd4f2" +- name: "backport staging" + description: "Label to automatically backport PR to staging branch" + color: "B60205" +- name: "Dependencies" + description: "Pull requests that update a dependency file" + color: "0366d6" +- name: "Easy" + color: "5dc9f7" +- name: "Sponsored" + color: "ffc8f4" +- name: "T-Deprecation" + description: "A pull request that makes something deprecated" + color: "98e6ae" +- name: "T-Other" + description: "Questions, user support, anything else" + color: "98e6ae" +- name: "X-Blocked" + color: "ff7979" +- name: "X-Breaking-Change" + color: "ff7979" +- name: "X-Reverted" + description: "PR has been reverted" + color: "F68AA3" +- name: "X-Upcoming-Release-Blocker" + description: "This does not affect the current release cycle but will affect the next one" + color: "e99695" +- name: "Z-Community-PR" + description: "Issue is solved by a community member's PR" + color: "ededed" +- name: "Z-Flaky-Test" + description: "A test is raising false alarms" + color: "ededed" diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 102313bdde8..5775641786b 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -22,10 +22,14 @@ version-resolver: exclude-labels: - "T-Task" - "X-Reverted" + - "backport staging" exclude-contributors: - "RiotRobot" template: | $CHANGES +#no-changes-template: "" prerelease: true prerelease-identifier: rc include-pre-releases: false +stable-ref: master +staging-ref: staging diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index dd793898eca..5a11ad5bbd5 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -7,10 +7,12 @@ on: branches: - develop +permissions: {} # We use ELEMENT_BOT_TOKEN instead + jobs: backport: name: Backport - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 # Only react to merged PRs for security reasons. # See https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target. if: > diff --git a/.github/workflows/docs-pr-netlify.yaml b/.github/workflows/docs-pr-netlify.yaml index c6183467681..27c3045c4df 100644 --- a/.github/workflows/docs-pr-netlify.yaml +++ b/.github/workflows/docs-pr-netlify.yaml @@ -5,16 +5,19 @@ on: workflows: ["Static Analysis"] types: - completed - +permissions: {} jobs: netlify: if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request' - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + permissions: + actions: read + deployments: write steps: - name: 📥 Download artifact uses: actions/download-artifact@v4 with: - github-token: ${{ secrets.ELEMENT_BOT_TOKEN }} + github-token: ${{ secrets.GITHUB_TOKEN }} run-id: ${{ github.event.workflow_run.id }} name: docs path: docs diff --git a/.github/workflows/downstream-artifacts.yml b/.github/workflows/downstream-artifacts.yml deleted file mode 100644 index f49d5df25d3..00000000000 --- a/.github/workflows/downstream-artifacts.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: Build downstream artifacts -on: - merge_group: - types: [checks_requested] - - pull_request: {} - - # For now at least, we don't run this or the downstream-end-to-end-tests against pushes - # to develop or master. - # - #push: - # branches: [develop, master] -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true -jobs: - build-element-web: - name: Build element-web - uses: matrix-org/matrix-react-sdk/.github/workflows/element-web.yaml@v3.88.0 - with: - matrix-js-sdk-sha: ${{ github.sha }} - react-sdk-repository: matrix-org/matrix-react-sdk diff --git a/.github/workflows/downstream-end-to-end-tests.yml b/.github/workflows/downstream-end-to-end-tests.yml index 41ea7850961..449491ef805 100644 --- a/.github/workflows/downstream-end-to-end-tests.yml +++ b/.github/workflows/downstream-end-to-end-tests.yml @@ -3,11 +3,17 @@ name: matrix-react-sdk End to End Tests on: - workflow_run: - workflows: ["Build downstream artifacts"] - types: - - completed + merge_group: + types: [checks_requested] + pull_request: {} + + # For now at least, we don't run this or the downstream-end-to-end-tests against pushes + # to develop or master. + # + #push: + # branches: [develop, master] +permissions: {} # No permissions required concurrency: group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.run_id }} cancel-in-progress: ${{ github.event.workflow_run.event == 'pull_request' }} @@ -15,44 +21,13 @@ concurrency: jobs: playwright: name: Playwright - # We only want to run the playwright tests on merge queue to prevent regressions - # from creeping in. They take a long time to run and consume multiple concurrent runners. - if: github.event.workflow_run.event == 'merge_group' - uses: matrix-org/matrix-react-sdk/.github/workflows/end-to-end-tests.yaml@develop + uses: element-hq/element-web/.github/workflows/end-to-end-tests.yaml@develop permissions: actions: read issues: read - statuses: write pull-requests: read - deployments: write with: - react-sdk-repository: matrix-org/matrix-react-sdk - secrets: - ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }} - - # We want to make the Playwright tests a required check for the merge queue. - # - # Unfortunately, GitHub doesn't distinguish between "checks needed for branch - # protection" (ie, the things that must pass before the PR will even be added - # to the merge queue) and "checks needed in the merge queue". We just have to add - # the check to the branch protection list. - # - # Ergo, if we know we're not going to run the Playwright tests, we need to add a - # passing status check manually. - mark_skipped: - if: github.event.workflow_run.event != 'merge_group' - permissions: - statuses: write - runs-on: ubuntu-latest - steps: - - uses: Sibz/github-status-action@071b5370da85afbb16637d6eed8524a06bc2053e # v1 - with: - authToken: "${{ secrets.GITHUB_TOKEN }}" - state: success - description: Playwright skipped - - # Keep in step with the `context` that is updated by `Sibz/github-status-action` - # in matrix-org/matrix-react-sdk/.github/workflows/end-to-end-tests.yaml. - context: "${{ github.workflow }} / end-to-end-tests" - - sha: "${{ github.event.workflow_run.head_sha }}" + matrix-js-sdk-sha: ${{ github.sha }} + # We only want to run the playwright tests on merge queue to prevent regressions + # from creeping in. They take a long time to run and consume multiple concurrent runners. + skip: ${{ github.event_name != 'merge_group' }} diff --git a/.github/workflows/notify-downstream.yaml b/.github/workflows/notify-downstream.yaml index 375764dcb0d..7139b90e601 100644 --- a/.github/workflows/notify-downstream.yaml +++ b/.github/workflows/notify-downstream.yaml @@ -3,6 +3,7 @@ on: push: branches: [develop] concurrency: ${{ github.workflow }}-${{ github.ref }} +permissions: {} # We use ELEMENT_BOT_TOKEN instead jobs: notify-downstream: # Only respect triggers from our develop branch, ignore that of forks @@ -12,15 +13,13 @@ jobs: fail-fast: false matrix: include: - - repo: vector-im/element-web + - repo: element-hq/element-web event: element-web-notify - - repo: matrix-org/matrix-react-sdk - event: upstream-sdk-notify - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - name: Notify matrix-react-sdk repo that a new SDK build is on develop so it can CI against it - uses: peter-evans/repository-dispatch@bf47d102fdb849e755b0b0023ea3e81a44b6f570 # v2 + uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3 with: token: ${{ secrets.ELEMENT_BOT_TOKEN }} repository: ${{ matrix.repo }} diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml index 743526a8df9..98572ff6a11 100644 --- a/.github/workflows/pull_request.yaml +++ b/.github/workflows/pull_request.yaml @@ -9,20 +9,28 @@ on: ELEMENT_BOT_TOKEN: required: true concurrency: ${{ github.workflow }}-${{ github.event.pull_request.head.ref || github.head_ref || github.ref }} +permissions: {} # We use ELEMENT_BOT_TOKEN instead jobs: changelog: name: Preview Changelog - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - - uses: matrix-org/allchange@main + - uses: mheap/github-action-required-labels@388fd6af37b34cdfe5a23b37060e763217e58b03 # v5 if: github.event_name != 'merge_group' with: - ghToken: ${{ secrets.GITHUB_TOKEN }} - requireLabel: true + labels: | + X-Breaking-Change + T-Deprecation + T-Enhancement + T-Defect + T-Task + Dependencies + mode: minimum + count: 1 prevent-blocked: name: Prevent Blocked - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 permissions: pull-requests: read steps: @@ -35,11 +43,14 @@ jobs: community-prs: name: Label Community PRs - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 if: github.event.action == 'opened' + permissions: + pull-requests: write steps: - name: Check membership - uses: tspascoal/get-user-teams-membership@ba78054988f58bea69b7c6136d563236f8ed2fc0 # v3 + if: github.event.pull_request.user.login != 'renovate[bot]' + uses: tspascoal/get-user-teams-membership@57e9f42acd78f4d0f496b3be4368fc5f62696662 # v3 id: teams with: username: ${{ github.event.pull_request.user.login }} @@ -48,7 +59,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }} - name: Add label - if: ${{ steps.teams.outputs.isTeamMember == 'false' }} + if: steps.teams.outputs.isTeamMember == 'false' uses: actions/github-script@v7 with: script: | @@ -61,7 +72,7 @@ jobs: close-if-fork-develop: name: Forbid develop branch fork contributions - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 if: > github.event.action == 'opened' && github.event.pull_request.head.ref == 'develop' && diff --git a/.github/workflows/release-checks.yml b/.github/workflows/release-checks.yml new file mode 100644 index 00000000000..b83b4dd1ce8 --- /dev/null +++ b/.github/workflows/release-checks.yml @@ -0,0 +1,38 @@ +name: Release Sanity checks +on: + workflow_call: + secrets: + ELEMENT_BOT_TOKEN: + required: false + inputs: + repository: + type: string + required: false + default: ${{ github.repository }} + description: "The repository (in form owner/repo) to check for release blockers" + +permissions: {} +jobs: + checks: + name: Sanity checks + runs-on: ubuntu-24.04 + steps: + - name: Check for X-Release-Blocker label on any open issues or PRs + uses: actions/github-script@v7 + env: + REPO: ${{ inputs.repository }} + with: + github-token: ${{ secrets.ELEMENT_BOT_TOKEN || secrets.GITHUB_TOKEN }} + script: | + const { REPO } = process.env; + const { data } = await github.rest.search.issuesAndPullRequests({ + q: `repo:${REPO} label:X-Release-Blocker is:open`, + per_page: 50, + }); + + if (data.total_count) { + data.items.forEach(item => { + core.error(`Release blocker: ${item.html_url}`); + }); + core.setFailed(`Found release blockers!`); + } diff --git a/.github/workflows/release-drafter-workflow.yml b/.github/workflows/release-drafter-workflow.yml new file mode 100644 index 00000000000..239ad8144f4 --- /dev/null +++ b/.github/workflows/release-drafter-workflow.yml @@ -0,0 +1,92 @@ +# Workflow used by other workflows to generate draft releases. +name: Release Drafter Reusable +on: + workflow_call: + inputs: + include-changes: + description: Project to include changelog entries from in this release. + type: string + required: false +concurrency: release-drafter-action +permissions: {} +jobs: + draft: + runs-on: ubuntu-24.04 + permissions: + contents: write + steps: + - name: 🧮 Checkout code + uses: actions/checkout@v4 + with: + ref: staging + fetch-depth: 0 + + - uses: actions/setup-node@v4 + with: + node-version-file: package.json + cache: "yarn" + + - name: Install Deps + run: "yarn install --frozen-lockfile" + + - uses: t3chguy/release-drafter@105e541c2c3d857f032bd522c0764694758fabad + id: draft-release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + disable-autolabeler: true + + - name: Get actions scripts + uses: actions/checkout@v4 + with: + repository: matrix-org/matrix-js-sdk + persist-credentials: false + path: .action-repo + sparse-checkout: | + .github/actions + scripts/release + + - name: Ingest upstream changes + if: inputs.include-changes + uses: actions/github-script@v7 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + RELEASE_ID: ${{ steps.draft-release.outputs.id }} + DEPENDENCY: ${{ inputs.include-changes }} + VERSION: ${{ steps.draft-release.outputs.tag_name }} + with: + retries: 3 + script: | + const { RELEASE_ID: releaseId, DEPENDENCY, VERSION } = process.env; + const { owner, repo } = context.repo; + const script = require("./.action-repo/scripts/release/merge-release-notes.cjs"); + + let deps = []; + if (DEPENDENCY.includes("/")) { + deps.push(DEPENDENCY.replace("$VERSION", VERSION)) + } else { + const fromVersion = JSON.parse((await github.request(`https://raw.githubusercontent.com/${owner}/${repo}/master/package.json`)).data).dependencies[DEPENDENCY]; + const toVersion = require("./package.json").dependencies[DEPENDENCY]; + + if (toVersion.endsWith("#develop")) { + core.warning(`${DEPENDENCY} will be kept at ${fromVersion}`, { title: "Develop dependency found" }); + } else { + deps.push([DEPENDENCY, fromVersion, toVersion]); + } + } + + if (deps.length) { + const notes = await script({ + github, + releaseId, + dependencies: deps, + }); + + await github.rest.repos.updateRelease({ + owner, + repo, + release_id: releaseId, + body: notes, + tag_name: VERSION, + }); + } diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml index 4d889f45614..d54453df833 100644 --- a/.github/workflows/release-drafter.yml +++ b/.github/workflows/release-drafter.yml @@ -1,21 +1,16 @@ +# Generates the draft release for the js-sdk +# Normally triggered whenever anything is merged to the staging branch, but +# also has a workflow dispatch trigger in case it needs running manually due +# to failures / workflow updates etc. name: Release Drafter on: push: branches: [staging] - workflow_dispatch: - inputs: - previous-version: - description: What release to use as a base for release note purposes - required: false - type: string + workflow_dispatch: {} concurrency: ${{ github.workflow }} +permissions: {} jobs: draft: - runs-on: ubuntu-latest - steps: - - uses: release-drafter/release-drafter@e64b19c4c46173209ed9f2e5a2f4ca7de89a0e86 # v5 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - disable-autolabeler: true - previous-version: ${{ inputs.previous-version }} + permissions: + contents: write + uses: matrix-org/matrix-js-sdk/.github/workflows/release-drafter-workflow.yml@develop diff --git a/.github/workflows/release-gitflow.yml b/.github/workflows/release-gitflow.yml index b82c61aec3c..ff6a2ec33b1 100644 --- a/.github/workflows/release-gitflow.yml +++ b/.github/workflows/release-gitflow.yml @@ -13,12 +13,14 @@ on: type: string required: false concurrency: ${{ github.workflow }} +permissions: {} # Uses ELEMENT_BOT_TOKEN jobs: merge: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 with: + # We will be pushing to this branch and want the CI to run after we do so we cannot use the GITHUB_TOKEN token: ${{ secrets.ELEMENT_BOT_TOKEN }} fetch-depth: 0 @@ -34,6 +36,7 @@ jobs: - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install Deps run: "yarn install --frozen-lockfile" @@ -48,9 +51,6 @@ jobs: git checkout develop git merge -X ours master - - name: Run post-merge-master script to revert package.json fields - run: ./.action-repo/scripts/release/post-merge-master.sh - - name: Reset dependencies if: inputs.dependencies run: | @@ -60,26 +60,25 @@ jobs: CURRENT_VERSION=$(cat package.json | jq -r .dependencies[\"$PACKAGE\"]) echo "Current $PACKAGE version is $CURRENT_VERSION" - if [ "$CURRENT_VERSION" == "null" ] + if [[ "$CURRENT_VERSION" == "null" ]] then echo "Unable to find $PACKAGE in package.json" exit 1 fi - if [ "$CURRENT_VERSION" == "develop" ] + if [[ "$CURRENT_VERSION" == *"#develop" ]] then echo "Not updating dependency $PACKAGE" continue fi - echo "Resetting $1 to develop branch..." + echo "Resetting $PACKAGE to develop branch..." yarn add "github:matrix-org/$PACKAGE#develop" git add -u git commit -m "Reset $PACKAGE back to develop branch" done <<< "$DEPENDENCIES" env: DEPENDENCIES: ${{ inputs.dependencies }} - FINAL: ${{ inputs.final }} - name: Push changes run: git push origin develop diff --git a/.github/workflows/release-make.yml b/.github/workflows/release-make.yml index b299f9db6cc..421115e68f1 100644 --- a/.github/workflows/release-make.yml +++ b/.github/workflows/release-make.yml @@ -20,16 +20,6 @@ on: description: Publish to npm type: boolean default: false - dependencies: - description: | - List of dependencies to update in `npm-dep=version` format. - `version` can be `"current"` to leave it at the current version. - type: string - required: false - include-changes: - description: Project to include changelog entries from in this release. - type: string - required: false gpg-fingerprint: description: Fingerprint of the GPG key to use for signing the git tag and assets, if any. type: string @@ -44,24 +34,39 @@ on: description: The number of expected assets, including signatures, excluding generated zip & tarball. type: number required: false + outputs: + npm-id: + description: "The npm package@version string we published" + value: ${{ jobs.npm.outputs.id }} +permissions: {} jobs: + checks: + name: Sanity checks + permissions: + issues: read + pull-requests: read + uses: matrix-org/matrix-js-sdk/.github/workflows/release-checks.yml@develop + release: name: Release - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 environment: Release + needs: checks + permissions: + contents: write steps: - name: Load GPG key id: gpg if: inputs.gpg-fingerprint - uses: crazy-max/ghaction-import-gpg@01dd5d3ca463c7f10f7f4f7b4f177225ac661ee4 # v6 + uses: crazy-max/ghaction-import-gpg@cb9bde2e2525e640591a934b1fd28eef1dcaf5e5 # v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.GPG_PASSPHRASE }} fingerprint: ${{ inputs.gpg-fingerprint }} - name: Get draft release - id: release - uses: cardinalby/git-get-release-action@cedef2faf69cb7c55b285bad07688d04430b7ada # v1 + id: draft-release + uses: cardinalby/git-get-release-action@5172c3a026600b1d459b117738c605fabc9e4e44 # v1 env: GITHUB_TOKEN: ${{ github.token }} with: @@ -71,6 +76,7 @@ jobs: - uses: actions/checkout@v4 with: ref: staging + # We will be pushing to this branch and want the CI to run after we do so we cannot use the GITHUB_TOKEN token: ${{ secrets.ELEMENT_BOT_TOKEN }} fetch-depth: 0 @@ -88,18 +94,12 @@ jobs: id: prepare run: | echo "VERSION=$VERSION" >> $GITHUB_ENV - { - echo "RELEASE_NOTES<> $GITHUB_ENV HAS_DIST=0 jq -e .scripts.dist package.json >/dev/null 2>&1 && HAS_DIST=1 echo "has-dist-script=$HAS_DIST" >> $GITHUB_OUTPUT env: - BODY: ${{ steps.release.outputs.body }} - VERSION: ${{ steps.release.outputs.tag_name }} + VERSION: ${{ steps.draft-release.outputs.tag_name }} - name: Finalise version if: inputs.final @@ -128,79 +128,29 @@ jobs: - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install dependencies run: "yarn install --frozen-lockfile" - - name: Update dependencies - id: update-dependencies - if: inputs.dependencies - run: | - UPDATED=() - while IFS= read -r DEPENDENCY; do - [ -z "$DEPENDENCY" ] && continue - IFS="=" read -r PACKAGE UPDATE_VERSION <<< "$DEPENDENCY" - - CURRENT_VERSION=$(cat package.json | jq -r .dependencies[\"$PACKAGE\"]) - echo "Current $PACKAGE version is $CURRENT_VERSION" - - if [ "$CURRENT_VERSION" == "null" ] - then - echo "Unable to find $PACKAGE in package.json" - exit 1 - fi - - if [ "$UPDATE_VERSION" == "current" ] || [ "$UPDATE_VERSION" == "$CURRENT_VERSION" ] - then - echo "Not updating dependency $PACKAGE" - continue - fi - - echo "Upgrading $PACKAGE to $UPDATE_VERSION..." - yarn upgrade "$PACKAGE@$UPDATE_VERSION" --exact - git add -u - git commit -m "Upgrade $PACKAGE to $UPDATE_VERSION" - UPDATED+=("$PACKAGE") - done <<< "$DEPENDENCIES" - - JSON=$(jq --compact-output --null-input '$ARGS.positional' --args -- "${UPDATED[@]}") - echo "updated=$JSON" >> $GITHUB_OUTPUT - env: - DEPENDENCIES: ${{ inputs.dependencies }} - - - name: Prevent develop dependencies - if: inputs.dependencies + - name: Handle develop dependencies run: | ret=0 - cat package.json | jq '.dependencies[]' | grep -q '#develop' || ret=$? - if [ "$ret" -eq 0 ]; then - echo "package.json contains develop dependencies. Refusing to release." - exit - fi + cat package.json | jq -r '.dependencies | to_entries | .[] | "\(.key) \(.value)"' | grep '#develop$' | while read -r dep ; do + IFS=" " + PACKAGE=${dep[0]} + VERSION=${dep[1]} - - name: Bump package.json version - run: yarn version --no-git-tag-version --new-version "${VERSION#v}" + echo "::warning title=Develop dependency found::$DEPENDENCY will be kept at $VERSION" + yarn upgrade "$PACKAGE@$VERSION" --exact + git add -u + git commit -m "Keep $PACKAGE at $VERSION" + done - - name: Ingest upstream changes - if: | - inputs.include-changes && - (!inputs.dependencies || contains(fromJSON(steps.update-dependencies.outputs.updated), inputs.include-changes)) - uses: actions/github-script@v7 - env: - RELEASE_ID: ${{ steps.release.outputs.id }} - DEPENDENCY: ${{ inputs.include-changes }} - with: - retries: 3 - script: | - const { RELEASE_ID: releaseId, DEPENDENCY, VERSION } = process.env; - const { owner, repo } = context.repo; - const script = require("./.action-repo/scripts/release/merge-release-notes.js"); - const notes = await script({ - github, - releaseId, - dependencies: [DEPENDENCY.replace("$VERSION", VERSION)], - }); - core.exportVariable("RELEASE_NOTES", notes); + - name: Bump package.json version + run: | + yarn version --no-git-tag-version --new-version "${VERSION#v}" + git add package.json - name: Add to CHANGELOG.md if: inputs.final @@ -219,11 +169,8 @@ jobs: cat CHANGELOG.md.old >> CHANGELOG.md rm CHANGELOG.md.old git add CHANGELOG.md - - - name: Run pre-release script to update package.json fields - run: | - ./.action-repo/scripts/release/pre-release.sh - git add package.json + env: + RELEASE_NOTES: ${{ steps.draft-release.outputs.body }} - name: Commit changes run: git commit -m "$VERSION" @@ -237,7 +184,7 @@ jobs: uses: ./.action-repo/.github/actions/upload-release-assets with: gpg-fingerprint: ${{ inputs.gpg-fingerprint }} - upload-url: ${{ steps.release.outputs.upload_url }} + upload-url: ${{ steps.draft-release.outputs.upload_url }} asset-path: ${{ inputs.asset-path }} - name: Create signed tag @@ -252,7 +199,7 @@ jobs: uses: ./.action-repo/.github/actions/sign-release-tarball with: gpg-fingerprint: ${{ inputs.gpg-fingerprint }} - upload-url: ${{ steps.release.outputs.upload_url }} + upload-url: ${{ steps.draft-release.outputs.upload_url }} # We defer pushing changes until after the release assets are built, # signed & uploaded to improve the atomicity of this action. @@ -273,7 +220,7 @@ jobs: if: inputs.expected-asset-count uses: actions/github-script@v7 env: - RELEASE_ID: ${{ steps.release.outputs.id }} + RELEASE_ID: ${{ steps.draft-release.outputs.id }} EXPECTED_ASSET_COUNT: ${{ inputs.expected-asset-count }} with: retries: 3 @@ -301,7 +248,7 @@ jobs: - name: Publish release uses: actions/github-script@v7 env: - RELEASE_ID: ${{ steps.release.outputs.id }} + RELEASE_ID: ${{ steps.draft-release.outputs.id }} FINAL: ${{ inputs.final }} with: retries: 3 @@ -335,15 +282,18 @@ jobs: secrets: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - update-labels: - name: Advance release blocker labels + post-release: + name: Post release steps needs: release - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + permissions: + issues: write steps: - id: repository run: echo "REPO=${GITHUB_REPOSITORY#*/}" >> $GITHUB_OUTPUT - - uses: garganshu/github-label-updater@3770d15ebfed2fe2cb06a241047bc340f774a7d1 # v1.0.0 + - name: Advance release blocker labels + uses: garganshu/github-label-updater@3770d15ebfed2fe2cb06a241047bc340f774a7d1 # v1.0.0 with: owner: ${{ github.repository_owner }} repo: ${{ steps.repository.outputs.REPO }} @@ -351,3 +301,13 @@ jobs: filter-labels: X-Upcoming-Release-Blocker remove-labels: X-Upcoming-Release-Blocker add-labels: X-Release-Blocker + + # - name: Wait for master->develop gitflow merge + # if: inputs.final + # uses: t3chguy/wait-on-check-action@18541021811b56544d90e0f073401c2b99e249d6 # fork + # with: + # ref: master + # repo-token: ${{ secrets.GITHUB_TOKEN }} + # wait-interval: 10 + # check-name: merge + # allowed-conclusions: success diff --git a/.github/workflows/release-npm.yml b/.github/workflows/release-npm.yml index efba1d96774..4d7b892832c 100644 --- a/.github/workflows/release-npm.yml +++ b/.github/workflows/release-npm.yml @@ -4,10 +4,17 @@ on: secrets: NPM_TOKEN: required: true + outputs: + id: + description: "The npm package@version string we published" + value: ${{ jobs.npm.outputs.id }} +permissions: {} # No permissions required jobs: npm: name: Publish to npm - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + outputs: + id: ${{ steps.npm-publish.outputs.id }} steps: - name: 🧮 Checkout code uses: actions/checkout@v4 @@ -19,19 +26,24 @@ jobs: with: cache: "yarn" registry-url: "https://registry.npmjs.org" + node-version-file: package.json - name: 🔨 Install dependencies run: "yarn install --frozen-lockfile" - name: 🚀 Publish to npm id: npm-publish - uses: JS-DevTools/npm-publish@4b07b26a2f6e0a51846e1870223e545bae91c552 # v3.0.1 + uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1 with: token: ${{ secrets.NPM_TOKEN }} access: public tag: next ignore-scripts: false + - name: Check npm package was published + if: steps.npm-publish.outputs.id == '' + run: exit 1 + - name: 🎖️ Add `latest` dist-tag to final releases if: steps.npm-publish.outputs.id && !contains(steps.npm-publish.outputs.id, '-rc.') run: npm dist-tag add "$release" latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fccff0d61dc..ca5e9fa5592 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -21,56 +21,88 @@ on: type: boolean default: true concurrency: ${{ github.workflow }} +permissions: {} # No permissions required jobs: release: uses: matrix-org/matrix-js-sdk/.github/workflows/release-make.yml@develop + permissions: + contents: write + issues: write + pull-requests: read secrets: inherit with: final: ${{ inputs.mode == 'final' }} npm: ${{ inputs.npm }} + bump-downstreams: + name: Update npm dependency in downstream projects + needs: release + runs-on: ubuntu-24.04 + strategy: + matrix: + repo: + - element-hq/element-web + steps: + - uses: actions/checkout@v4 + with: + repository: ${{ matrix.repo }} + ref: staging + token: ${{ secrets.ELEMENT_BOT_TOKEN }} + + - uses: actions/setup-node@v4 + with: + cache: "yarn" + node-version: "lts/*" + + - name: Bump dependency + env: + DEPENDENCY: ${{ needs.release.outputs.npm-id }} + run: | + git config --global user.email "releases@riot.im" + git config --global user.name "RiotRobot" + yarn upgrade "$DEPENDENCY" --exact + git add package.json yarn.lock + git commit -am"Upgrade dependency to $DEPENDENCY" + git push origin staging + docs: name: Publish Documentation needs: release if: inputs.docs - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - name: 🧮 Checkout code uses: actions/checkout@v4 - - name: 🧮 Checkout gh-pages - uses: actions/checkout@v4 - with: - ref: gh-pages - path: _docs - - name: 🔧 Yarn cache uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: 🔨 Install dependencies run: "yarn install --frozen-lockfile" - - name: 🔨 Install symlinks - run: | - sudo apt-get update - sudo apt-get install -y symlinks - - name: 📖 Generate docs - run: | - yarn tpv purge --yes --out _docs --stale --major 10 - yarn gendoc - symlinks -rc _docs + run: yarn gendoc - - name: 🔨 Set up git - run: | - git config --global user.email "releases@riot.im" - git config --global user.name "RiotRobot" + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _docs - - name: 🚀 Deploy - run: | - git add . --all - git commit -m "Update docs" - git push - working-directory: _docs + docs-deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-24.04 + needs: docs + # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages + permissions: + contents: read + pages: write + id-token: write + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml index 1ee2475ae1e..aea6aec5665 100644 --- a/.github/workflows/sonarcloud.yml +++ b/.github/workflows/sonarcloud.yml @@ -5,27 +5,29 @@ on: secrets: SONAR_TOKEN: required: true + # No longer used ELEMENT_BOT_TOKEN: - required: true + required: false inputs: sharded: type: boolean required: false description: "Whether to combine multiple LCOV and jest-sonar-report files in coverage artifact" - extra_args: - type: string - required: false - description: "Extra args to pass to SonarCloud" +permissions: {} jobs: sonarqube: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 if: | github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event != 'merge_group' + permissions: + actions: read + statuses: write + id-token: write # sonar steps: # We create the status here and then update it to success/failure in the `report` stage # This provides an easy link to this workflow_run from the PR before Sonarcloud is done. - - uses: Sibz/github-status-action@071b5370da85afbb16637d6eed8524a06bc2053e # v1 + - uses: guibranco/github-status-action-v2@d469d49426f5a7b8a1fbcac20ad274d3e4892321 with: authToken: ${{ secrets.GITHUB_TOKEN }} state: pending @@ -34,7 +36,7 @@ jobs: target_url: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} - name: "🧮 Checkout code" - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 with: repository: ${{ github.event.workflow_run.head_repository.full_name }} ref: ${{ github.event.workflow_run.head_branch }} # checkout commit that triggered this workflow @@ -44,7 +46,7 @@ jobs: uses: actions/download-artifact@v4 if: ${{ !inputs.sharded }} with: - github-token: ${{ secrets.ELEMENT_BOT_TOKEN }} + github-token: ${{ secrets.GITHUB_TOKEN }} run-id: ${{ github.event.workflow_run.id }} name: coverage path: coverage @@ -52,22 +54,28 @@ jobs: uses: actions/download-artifact@v4 if: inputs.sharded with: - github-token: ${{ secrets.ELEMENT_BOT_TOKEN }} + github-token: ${{ secrets.GITHUB_TOKEN }} run-id: ${{ github.event.workflow_run.id }} pattern: coverage-* path: coverage merge-multiple: true + - name: Check coverage artifact + run: | + if [ ! -d coverage ]; then + echo "Coverage not found. Exiting with failure." + exit 1 + fi - id: extra_args run: | - coverage=$(find coverage -type f -name '*lcov.info' | tr '\n' ',' | sed 's/,$//g') - echo "reportPaths=$coverage" >> $GITHUB_OUTPUT - reports=$(find coverage -type f -name 'jest-sonar-report*.xml' | tr '\n' ',' | sed 's/,$//g') - echo "testExecutionReportPaths=$reports" >> $GITHUB_OUTPUT + coverage=$(find coverage -type f -name '*lcov.info' -printf '%h/%f,' | tr -d '\r\n' | sed 's/,$//g') + echo "sonar.javascript.lcov.reportPaths=$coverage" >> sonar-project.properties + reports=$(find coverage -type f -name 'jest-sonar-report*.xml' -printf '%h/%f,' | tr -d '\r\n' | sed 's/,$//g') + echo "sonar.testExecutionReportPaths=$reports" >> sonar-project.properties - name: "🩻 SonarCloud Scan" id: sonarcloud - uses: matrix-org/sonarcloud-workflow-action@v2.7 + uses: matrix-org/sonarcloud-workflow-action@v3.3 # workflow_run fails report against the develop commit always, we don't want that for PRs continue-on-error: ${{ github.event.workflow_run.head_branch != 'develop' }} with: @@ -78,12 +86,8 @@ jobs: branch: ${{ github.event.workflow_run.head_branch }} revision: ${{ github.event.workflow_run.head_sha }} token: ${{ secrets.SONAR_TOKEN }} - extra_args: | - ${{ inputs.extra_args }} - -Dsonar.javascript.lcov.reportPaths=${{ steps.extra_args.outputs.reportPaths }} - -Dsonar.testExecutionReportPaths=${{ steps.extra_args.outputs.testExecutionReportPaths }} - - uses: Sibz/github-status-action@071b5370da85afbb16637d6eed8524a06bc2053e # v1 + - uses: guibranco/github-status-action-v2@d469d49426f5a7b8a1fbcac20ad274d3e4892321 if: always() with: authToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/sonarqube.yml b/.github/workflows/sonarqube.yml index d9b26c78e87..0b11be815ed 100644 --- a/.github/workflows/sonarqube.yml +++ b/.github/workflows/sonarqube.yml @@ -7,10 +7,15 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch }} cancel-in-progress: true +permissions: {} jobs: sonarqube: name: 🩻 SonarQube if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event != 'merge_group' + permissions: + actions: read + statuses: write + id-token: write # sonar uses: matrix-org/matrix-js-sdk/.github/workflows/sonarcloud.yml@develop secrets: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml index 4e1070d1c96..c81583f05ab 100644 --- a/.github/workflows/static_analysis.yml +++ b/.github/workflows/static_analysis.yml @@ -8,16 +8,18 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +permissions: {} # No permissions needed jobs: ts_lint: name: "Typescript Syntax Check" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install Deps run: "yarn install" @@ -25,25 +27,16 @@ jobs: - name: Typecheck run: "yarn run lint:types" - - name: Switch js-sdk to release mode - run: | - scripts/switch_package_to_release.js - yarn install - yarn run build:compile - yarn run build:types - - - name: Typecheck (release mode) - run: "yarn run lint:types" - js_lint: name: "ESLint" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install Deps run: "yarn install" @@ -53,13 +46,14 @@ jobs: workflow_lint: name: "Workflow Lint" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install Deps run: "yarn install --frozen-lockfile" @@ -69,26 +63,20 @@ jobs: docs: name: "JSDoc Checker" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: cache: "yarn" + node-version-file: package.json - name: Install Deps run: "yarn install" - name: Generate Docs - run: "yarn run gendoc --treatWarningsAsErrors" - - # Upload artifact duplicates symlink contents so we do this to save 75% space - - name: Flatten symlink and write _redirects - run: | - find _docs -mindepth 1 -maxdepth 1 ! -type f ! -name stable -printf '/%f/* /stable/:splat\n' > _docs/_redirects - find _docs -mindepth 1 -maxdepth 1 -type l -delete - find _docs -mindepth 1 -maxdepth 1 -type d -execdir mv {} stable \; -quit + run: "yarn run gendoc --treatWarningsAsErrors --suppressCommentWarningsInDeclarationFiles" - name: Upload Artifact uses: actions/upload-artifact@v4 @@ -97,3 +85,54 @@ jobs: path: _docs # We'll only use this in a workflow_run, then we're done with it retention-days: 1 + + analyse_dead_code: + name: "Analyse Dead Code" + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + cache: "yarn" + node-version-file: package.json + + - name: Install Deps + run: "yarn install --frozen-lockfile" + + - name: Run linter + run: "yarn run lint:knip" + + element-web: + name: Downstream tsc element-web + if: github.event_name == 'merge_group' + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + with: + repository: element-hq/element-web + + - uses: actions/setup-node@v4 + with: + cache: "yarn" + node-version: "lts/*" + + - name: Install Dependencies + run: "./scripts/layered.sh" + env: + # tell layered.sh to check out the right sha of the JS-SDK + JS_SDK_GITHUB_BASE_REF: ${{ github.sha }} + + - name: Typecheck + run: "yarn run lint:types" + + # Hook for branch protection to skip downstream typechecking outside of merge queues + downstream: + name: Downstream Typescript Syntax Check + runs-on: ubuntu-24.04 + if: always() + needs: + - element-web + steps: + - if: needs.element-web.result != 'skipped' && needs.element-web.result != 'success' + run: exit 1 diff --git a/.github/workflows/sync-labels.yml b/.github/workflows/sync-labels.yml new file mode 100644 index 00000000000..97f250f4352 --- /dev/null +++ b/.github/workflows/sync-labels.yml @@ -0,0 +1,22 @@ +name: Sync labels +on: + workflow_dispatch: {} + schedule: + - cron: "0 1 * * *" # 1am every day + push: + branches: + - develop + paths: + - .github/labels.yml +permissions: {} # We use ELEMENT_BOT_TOKEN instead +jobs: + sync-labels: + uses: element-hq/element-meta/.github/workflows/sync-labels.yml@develop + with: + LABELS: | + element-hq/element-meta + .github/labels.yml + DELETE: true + WET: true + secrets: + ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 3c2241e1cf9..29393c9352f 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -10,15 +10,16 @@ concurrency: cancel-in-progress: true env: ENABLE_COVERAGE: ${{ github.event_name != 'merge_group' }} +permissions: {} # No permissions required jobs: jest: name: "Jest [${{ matrix.specs }}] (Node ${{ matrix.node == '*' && 'latest' || matrix.node }})" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 10 strategy: matrix: specs: [integ, unit] - node: [18, "lts/*", 21] + node: ["lts/*", 22] steps: - name: Checkout code uses: actions/checkout@v4 @@ -63,26 +64,59 @@ jobs: coverage !coverage/lcov-report - matrix-react-sdk: - name: Downstream test matrix-react-sdk + # Dummy completion job to simplify branch protections + jest-complete: + name: Jest tests + needs: jest + if: always() + runs-on: ubuntu-24.04 + steps: + - if: needs.jest.result != 'skipped' && needs.jest.result != 'success' + run: exit 1 + + element-web: + name: Downstream test element-web if: github.event_name == 'merge_group' - uses: matrix-org/matrix-react-sdk/.github/workflows/tests.yml@develop + uses: element-hq/element-web/.github/workflows/tests.yml@develop + permissions: + statuses: write with: disable_coverage: true matrix-js-sdk-sha: ${{ github.sha }} + complement-crypto: + name: "Run Complement Crypto tests" + if: github.event_name == 'merge_group' + permissions: read-all + uses: matrix-org/complement-crypto/.github/workflows/single_sdk_tests.yml@main + with: + use_js_sdk: "." + + # we need this so the job is reported properly when run in a merge queue + downstream-complement-crypto: + name: Downstream Complement Crypto tests + runs-on: ubuntu-24.04 + if: always() + needs: + - complement-crypto + steps: + - if: needs.complement-crypto.result != 'skipped' && needs.complement-crypto.result != 'success' + run: exit 1 + # Hook for branch protection to skip downstream testing outside of merge queues # and skip sonarcloud coverage within merge queues downstream: name: Downstream tests - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 if: always() needs: - - matrix-react-sdk + - element-web + permissions: + statuses: write steps: - name: Skip SonarCloud on merge queues if: env.ENABLE_COVERAGE == 'false' - uses: Sibz/github-status-action@071b5370da85afbb16637d6eed8524a06bc2053e # v1 + uses: guibranco/github-status-action-v2@d469d49426f5a7b8a1fbcac20ad274d3e4892321 with: authToken: ${{ secrets.GITHUB_TOKEN }} state: success @@ -91,5 +125,5 @@ jobs: sha: ${{ github.sha }} target_url: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} - - if: needs.matrix-react-sdk.result != 'skipped' && needs.matrix-react-sdk.result != 'success' + - if: needs.element-web.result != 'skipped' && needs.element-web.result != 'success' run: exit 1 diff --git a/.github/workflows/triage-incoming.yml b/.github/workflows/triage-incoming.yml new file mode 100644 index 00000000000..887f37defeb --- /dev/null +++ b/.github/workflows/triage-incoming.yml @@ -0,0 +1,14 @@ +name: Move new issues into Issue triage board + +on: + issues: + types: [opened] +permissions: {} # We use ELEMENT_BOT_TOKEN instead +jobs: + automate-project-columns-next: + runs-on: ubuntu-24.04 + steps: + - uses: actions/add-to-project@main + with: + project-url: https://github.com/orgs/element-hq/projects/120 + github-token: ${{ secrets.ELEMENT_BOT_TOKEN }} diff --git a/.github/workflows/triage-labelled.yml b/.github/workflows/triage-labelled.yml index cb013753c56..3809d30e2d6 100644 --- a/.github/workflows/triage-labelled.yml +++ b/.github/workflows/triage-labelled.yml @@ -3,9 +3,9 @@ name: Move labelled issues to correct projects on: issues: types: [labeled] - +permissions: {} # We use ELEMENT_BOT_TOKEN instead jobs: call-triage-labelled: - uses: vector-im/element-web/.github/workflows/triage-labelled.yml@develop + uses: element-hq/element-web/.github/workflows/triage-labelled.yml@develop secrets: ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }} diff --git a/.husky/pre-commit b/.husky/pre-commit index a16d8b1d555..083cf3f3ca5 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,4 +1,3 @@ #!/usr/bin/env sh -. "$(dirname "$0")/_/husky.sh" npx lint-staged diff --git a/.prettierrc.js b/.prettierrc.cjs similarity index 100% rename from .prettierrc.js rename to .prettierrc.cjs diff --git a/CHANGELOG.md b/CHANGELOG.md index aff0c3582c9..fedadb80fe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,453 @@ +Changes in [35.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v35.1.0) (2024-12-18) +================================================================================================== +This release updates matrix-sdk-crypto-wasm to fix a bug which could prevent loading stored crypto state from storage. + +## 🐛 Bug Fixes + +* Upgrade matrix-sdk-crypto-wasm to 1.11.0 ([#4593](https://github.com/matrix-org/matrix-js-sdk/pull/4593)). + + +Changes in [35.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v35.0.0) (2024-12-17) +================================================================================================== +## 🚨 BREAKING CHANGES + +This release contains several breaking changes which will need code changes in your app. Most notably, `initCrypto()` +no longer exists and has been moved to `initLegacyCrypto()` in preparation for the eventual removal of Olm. You can +continue to use legacy Olm crypto for now by calling `initLegacyCrypto()` instead. + +You may also need to make further changes if you use more advanced APIs. See the individual PRs (listed in order of size of change) for specific APIs changed and how to migrate. + +* Rename `MatrixClient.initCrypto` into `MatrixClient.initLegacyCrypto` ([#4567](https://github.com/matrix-org/matrix-js-sdk/pull/4567)). Contributed by @florianduros. +* Support MSC4222 `state_after` ([#4487](https://github.com/matrix-org/matrix-js-sdk/pull/4487)). Contributed by @dbkr. +* Avoid use of Buffer as it does not exist in the Web natively ([#4569](https://github.com/matrix-org/matrix-js-sdk/pull/4569)). Contributed by @t3chguy. + +## 🦖 Deprecations + +* Deprecate remaining legacy functions and move `CryptoEvent.LegacyCryptoStoreMigrationProgress` handler ([#4560](https://github.com/matrix-org/matrix-js-sdk/pull/4560)). Contributed by @florianduros. + +## ✨ Features + +* Rename `MatrixClient.initCrypto` into `MatrixClient.initLegacyCrypto` ([#4567](https://github.com/matrix-org/matrix-js-sdk/pull/4567)). Contributed by @florianduros. +* Avoid use of Buffer as it does not exist in the Web natively ([#4569](https://github.com/matrix-org/matrix-js-sdk/pull/4569)). Contributed by @t3chguy. +* Re-send MatrixRTC media encryption keys for a new joiner even if a rotation is in progress ([#4561](https://github.com/matrix-org/matrix-js-sdk/pull/4561)). Contributed by @hughns. +* Support MSC4222 `state_after` ([#4487](https://github.com/matrix-org/matrix-js-sdk/pull/4487)). Contributed by @dbkr. +* Revert "Fix room state being updated with old (now overwritten) state and emitting for those updates. (#4242)" ([#4532](https://github.com/matrix-org/matrix-js-sdk/pull/4532)). Contributed by @toger5. + +## 🐛 Bug Fixes + +* Fix age field check in event echo processing ([#3635](https://github.com/matrix-org/matrix-js-sdk/pull/3635)). Contributed by @stas-demydiuk. + + +Changes in [34.13.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.13.0) (2024-12-03) +==================================================================================================== +## 🦖 Deprecations + +* Deprecate `MatrixClient.isEventSenderVerified` ([#4527](https://github.com/matrix-org/matrix-js-sdk/pull/4527)). Contributed by @florianduros. +* Add `restoreKeybackup` to `CryptoApi`. ([#4476](https://github.com/matrix-org/matrix-js-sdk/pull/4476)). Contributed by @florianduros. + +## ✨ Features + +* Ensure we disambiguate display names which look like MXIDs ([#4540](https://github.com/matrix-org/matrix-js-sdk/pull/4540)). Contributed by @t3chguy. +* Add `CryptoApi.getBackupInfo` ([#4512](https://github.com/matrix-org/matrix-js-sdk/pull/4512)). Contributed by @florianduros. +* Fix local echo in embedded mode ([#4498](https://github.com/matrix-org/matrix-js-sdk/pull/4498)). Contributed by @toger5. +* Add `restoreKeybackup` to `CryptoApi`. ([#4476](https://github.com/matrix-org/matrix-js-sdk/pull/4476)). Contributed by @florianduros. + +## 🐛 Bug Fixes + +* Fix `RustBackupManager` remaining values after current backup removal ([#4537](https://github.com/matrix-org/matrix-js-sdk/pull/4537)). Contributed by @florianduros. + + +Changes in [34.12.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.12.0) (2024-11-19) +==================================================================================================== +## 🦖 Deprecations + +* Deprecate `MatrixClient.getKeyBackupVersion` ([#4505](https://github.com/matrix-org/matrix-js-sdk/pull/4505)). Contributed by @florianduros. +* Deprecate unused callbacks in `CryptoCallbacks` ([#4501](https://github.com/matrix-org/matrix-js-sdk/pull/4501)). Contributed by @florianduros. + +## ✨ Features + +* Handle M\_MAX\_DELAY\_EXCEEDED errors ([#4511](https://github.com/matrix-org/matrix-js-sdk/pull/4511)). Contributed by @AndrewFerr. +* Allow configuration of MatrixRTC timers when calling joinRoomSession() ([#4510](https://github.com/matrix-org/matrix-js-sdk/pull/4510)). Contributed by @hughns. +* When state says you've left ongoing call, rejoin ([#4342](https://github.com/matrix-org/matrix-js-sdk/pull/4342)). Contributed by @AndrewFerr. +* Remove redundant type arguments in function call ([#4507](https://github.com/matrix-org/matrix-js-sdk/pull/4507)). Contributed by @AndrewFerr. +* MatrixRTCSession: handle rate limit errors ([#4494](https://github.com/matrix-org/matrix-js-sdk/pull/4494)). Contributed by @AndrewFerr. +* Send/receive error details with widgets ([#4492](https://github.com/matrix-org/matrix-js-sdk/pull/4492)). Contributed by @AndrewFerr. +* Capture HTTP error response headers \& handle Retry-After header (MSC4041) ([#4471](https://github.com/matrix-org/matrix-js-sdk/pull/4471)). Contributed by @AndrewFerr. +* Add RoomWidgetClient.sendToDeviceViaWidgetApi() ([#4475](https://github.com/matrix-org/matrix-js-sdk/pull/4475)). Contributed by @hughns. + + +Changes in [34.11.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.11.1) (2024-11-12) +==================================================================================================== +# Security +- Fixes for [CVE-2024-50336](https://nvd.nist.gov/vuln/detail/CVE-2024-50336) / [GHSA-xvg8-m4x3-w6xr](https://github.com/matrix-org/matrix-js-sdk/security/advisories/GHSA-xvg8-m4x3-w6xr). + +Changes in [34.11.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.11.0) (2024-11-12) +==================================================================================================== +# Security +- Fixes for [CVE-2024-50336](https://nvd.nist.gov/vuln/detail/CVE-2024-50336) / [GHSA-xvg8-m4x3-w6xr](https://github.com/matrix-org/matrix-js-sdk/security/advisories/GHSA-xvg8-m4x3-w6xr). + +Changes in [34.10.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.10.0) (2024-11-05) +==================================================================================================== +## 🦖 Deprecations + +* Deprecate `CreateSecretStorageOpts.keyBackupInfo` used in `CryptoApi.bootstrapSecretStorage.` ([#4474](https://github.com/matrix-org/matrix-js-sdk/pull/4474)). Contributed by @florianduros. +* Add CryptoApi.encryptToDeviceMessages() and deprecate Crypto.encryptAndSendToDevices() ([#4380](https://github.com/matrix-org/matrix-js-sdk/pull/4380)). Contributed by @hughns. +* Remove abandoned MSC3886, MSC3903, MSC3906 experimental implementations ([#4469](https://github.com/matrix-org/matrix-js-sdk/pull/4469)). Contributed by @t3chguy. +* Deprecate `MatrixClient.getDehydratedDevice` ([#4467](https://github.com/matrix-org/matrix-js-sdk/pull/4467)). Contributed by @florianduros. +* Deprecate top level crypto events re-export ([#4444](https://github.com/matrix-org/matrix-js-sdk/pull/4444)). Contributed by @florianduros. + +## ✨ Features + +* Add CryptoApi.encryptToDeviceMessages() and deprecate Crypto.encryptAndSendToDevices() ([#4380](https://github.com/matrix-org/matrix-js-sdk/pull/4380)). Contributed by @hughns. +* Do not rotate MatrixRTC media encryption key when a new member joins a session ([#4472](https://github.com/matrix-org/matrix-js-sdk/pull/4472)). Contributed by @hughns. +* Avoid `|` notation in log messages ([#4473](https://github.com/matrix-org/matrix-js-sdk/pull/4473)). Contributed by @richvdh. +* Refactor/simplify Promises in MatrixRTCSession ([#4466](https://github.com/matrix-org/matrix-js-sdk/pull/4466)). Contributed by @AndrewFerr. +* Prepare delayed call leave events more reliably ([#4447](https://github.com/matrix-org/matrix-js-sdk/pull/4447)). Contributed by @AndrewFerr. + +## 🐛 Bug Fixes + +* Fix DelayedEventInfo type ([#4446](https://github.com/matrix-org/matrix-js-sdk/pull/4446)). Contributed by @AndrewFerr. + + +Changes in [34.9.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.9.0) (2024-10-22) +================================================================================================== +## 🦖 Deprecations + +* Deprecate the crypto events which are not used by the rust-crypto ([#4442](https://github.com/matrix-org/matrix-js-sdk/pull/4442)). Contributed by @florianduros. + +## 🐛 Bug Fixes + +* Fix the rust crypto import in esm environments. ([#4445](https://github.com/matrix-org/matrix-js-sdk/pull/4445)). Contributed by @saul-jb. +* Fix MatrixRTC sender key wrapping ([#4441](https://github.com/matrix-org/matrix-js-sdk/pull/4441)). Contributed by @hughns. + + +Changes in [34.8.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.8.0) (2024-10-15) +================================================================================================== +This release removes insecure functionality, resolving CVE-2024-47080 / GHSA-4jf8-g8wp-cx7c. + +Changes in [34.7.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.7.0) (2024-10-08) +================================================================================================== +## 🦖 Deprecations + +* RTCSession cleanup: deprecate getKeysForParticipant() and getEncryption(); add emitEncryptionKeys() ([#4427](https://github.com/matrix-org/matrix-js-sdk/pull/4427)). Contributed by @hughns. + +## ✨ Features + +* Bump matrix-rust-sdk to 9.1.0 ([#4435](https://github.com/matrix-org/matrix-js-sdk/pull/4435)). Contributed by @richvdh. +* Rotate Matrix RTC media encryption key when a new member joins a call for Post Compromise Security ([#4422](https://github.com/matrix-org/matrix-js-sdk/pull/4422)). Contributed by @hughns. +* Update media event content types to include captions ([#4403](https://github.com/matrix-org/matrix-js-sdk/pull/4403)). Contributed by @tulir. +* Update OIDC registration types to match latest MSC2966 state ([#4432](https://github.com/matrix-org/matrix-js-sdk/pull/4432)). Contributed by @t3chguy. +* Add `CryptoApi.pinCurrentUserIdentity` and `UserIdentity.needsUserApproval` ([#4415](https://github.com/matrix-org/matrix-js-sdk/pull/4415)). Contributed by @richvdh. + + +Changes in [34.6.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.6.0) (2024-09-24) +================================================================================================== +## 🦖 Deprecations + +* Element-R: Mark unsupported MatrixClient methods as deprecated ([#4389](https://github.com/matrix-org/matrix-js-sdk/pull/4389)). Contributed by @richvdh. + +## ✨ Features + +* Add crypto mode setting for invisible crypto, and apply it to decrypting events ([#4407](https://github.com/matrix-org/matrix-js-sdk/pull/4407)). Contributed by @uhoreg. +* Don't share full key history for RTC per-participant encryption ([#4406](https://github.com/matrix-org/matrix-js-sdk/pull/4406)). Contributed by @hughns. +* Export membership types ([#4405](https://github.com/matrix-org/matrix-js-sdk/pull/4405)). Contributed by @Johennes. +* Fix sending redacts in embedded (widget) mode ([#4398](https://github.com/matrix-org/matrix-js-sdk/pull/4398)). Contributed by @toger5. +* Expose the event ID of a call membership ([#4395](https://github.com/matrix-org/matrix-js-sdk/pull/4395)). Contributed by @robintown. +* MSC4133 - Extended profiles ([#4391](https://github.com/matrix-org/matrix-js-sdk/pull/4391)). Contributed by @Half-Shot. + + +Changes in [34.5.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.5.0) (2024-09-10) +================================================================================================== +## 🦖 Deprecations + +* Deprecate unused callback hooks `CryptoCallbacks.onSecretRequested` and `CryptoCallbacks.getDehydrationKey` ([#4376](https://github.com/matrix-org/matrix-js-sdk/pull/4376)). Contributed by @richvdh. + + +Changes in [34.4.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.4.0) (2024-08-27) +================================================================================================== +## ✨ Features + +* Use non-legacy calls if any are found ([#4337](https://github.com/matrix-org/matrix-js-sdk/pull/4337)). Contributed by @AndrewFerr. + +## 🐛 Bug Fixes + +* Retry event decryption failures on first failure ([#4346](https://github.com/matrix-org/matrix-js-sdk/pull/4346)). Contributed by @hughns. +* Ensure "type" = "module" ES declaration in pre-release.sh ([#4350](https://github.com/matrix-org/matrix-js-sdk/pull/4350)). Contributed by @BLCK-B. +* Handle MatrixRTC encryption keys arriving out of order ([#4345](https://github.com/matrix-org/matrix-js-sdk/pull/4345)). Contributed by @hughns. +* Resend MatrixRTC encryption keys if a membership has changed ([#4343](https://github.com/matrix-org/matrix-js-sdk/pull/4343)). Contributed by @hughns. + + +Changes in [34.3.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.3.1) (2024-08-20) +================================================================================================== +# Security +- Fixes for [CVE-2024-42369](https://nvd.nist.gov/vuln/detail/CVE-2024-42369) / [GHSA-vhr5-g3pm-49fm](https://github.com/matrix-org/matrix-js-sdk/security/advisories/GHSA-vhr5-g3pm-49fm). + +Changes in [34.3.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.3.0) (2024-08-13) +================================================================================================== +## ✨ Features + +* Bump matrix-widget-api ([#4336](https://github.com/matrix-org/matrix-js-sdk/pull/4336)). Contributed by @AndrewFerr. +* Also check for MSC3757 for session state keys ([#4334](https://github.com/matrix-org/matrix-js-sdk/pull/4334)). Contributed by @AndrewFerr. +* Support Futures via widgets ([#4311](https://github.com/matrix-org/matrix-js-sdk/pull/4311)). Contributed by @AndrewFerr. +* Support MSC4140: Delayed events (Futures) ([#4294](https://github.com/matrix-org/matrix-js-sdk/pull/4294)). Contributed by @AndrewFerr. +* Handle late-arriving `m.room_key.withheld` messages ([#4310](https://github.com/matrix-org/matrix-js-sdk/pull/4310)). Contributed by @richvdh. +* Be specific about what is considered a MSC4143 call member event. ([#4328](https://github.com/matrix-org/matrix-js-sdk/pull/4328)). Contributed by @toger5. +* Add index.ts for matrixrtc module ([#4314](https://github.com/matrix-org/matrix-js-sdk/pull/4314)). Contributed by @toger5. + +## 🐛 Bug Fixes + +* Fix hashed ID server lookups with no Olm ([#4333](https://github.com/matrix-org/matrix-js-sdk/pull/4333)). Contributed by @dbkr. + + +Changes in [34.2.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.2.0) (2024-07-30) +================================================================================================== +## 🐛 Bug Fixes + +* Element-R: detect "withheld key" UTD errors, and mark them as such ([#4302](https://github.com/matrix-org/matrix-js-sdk/pull/4302)). Contributed by @richvdh. + + +Changes in [34.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.1.0) (2024-07-16) +================================================================================================== +## ✨ Features + +* Add ability to choose how many timeline events to sync when peeking ([#4300](https://github.com/matrix-org/matrix-js-sdk/pull/4300)). Contributed by @jgarplind. +* Remove redundant hack for using the old pickle key in rust crypto ([#4282](https://github.com/matrix-org/matrix-js-sdk/pull/4282)). Contributed by @richvdh. +* Add fetching the well known in embedded mode. ([#4259](https://github.com/matrix-org/matrix-js-sdk/pull/4259)). Contributed by @toger5. + +## 🐛 Bug Fixes + +* Fix room state being updated with old (now overwritten) state and emitting for those updates. ([#4242](https://github.com/matrix-org/matrix-js-sdk/pull/4242)). Contributed by @toger5. +* Fix incorrect "Olm is not available" errors ([#4301](https://github.com/matrix-org/matrix-js-sdk/pull/4301)). Contributed by @richvdh. +* Fix build for example script ([#4286](https://github.com/matrix-org/matrix-js-sdk/pull/4286)). Contributed by @richvdh. +* Declare matrix-js-sdk as an ES module ([#4285](https://github.com/matrix-org/matrix-js-sdk/pull/4285)). Contributed by @richvdh. + + +Changes in [34.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v34.0.0) (2024-07-08) +================================================================================================== +## 🚨 BREAKING CHANGES + +* Fetch capabilities in the background ([#4246](https://github.com/matrix-org/matrix-js-sdk/pull/4246)). Contributed by @dbkr. + +## ✨ Features + +* Prefix the user+device state key if needed ([#4262](https://github.com/matrix-org/matrix-js-sdk/pull/4262)). Contributed by @AndrewFerr. +* Use legacy call membership if anyone else is ([#4260](https://github.com/matrix-org/matrix-js-sdk/pull/4260)). Contributed by @AndrewFerr. +* Fetch capabilities in the background ([#4246](https://github.com/matrix-org/matrix-js-sdk/pull/4246)). Contributed by @dbkr. +* Use server name instead of homeserver url to allow well-known lookups during QR OIDC reciprocation ([#4233](https://github.com/matrix-org/matrix-js-sdk/pull/4233)). Contributed by @t3chguy. +* Add via parameter for MSC4156 ([#4247](https://github.com/matrix-org/matrix-js-sdk/pull/4247)). Contributed by @Johennes. +* Make the js-sdk compatible with MSC preferred foci and active focus. ([#4195](https://github.com/matrix-org/matrix-js-sdk/pull/4195)). Contributed by @toger5. +* Replace usages of setImmediate with setTimeout for wider compatibility ([#4240](https://github.com/matrix-org/matrix-js-sdk/pull/4240)). Contributed by @t3chguy. + +## 🐛 Bug Fixes + +* [Backport staging] Fix "Unable to restore session" error ([#4299](https://github.com/matrix-org/matrix-js-sdk/pull/4299)). Contributed by @RiotRobot. +* [Backport staging] Fix error when sending encrypted messages in large rooms ([#4297](https://github.com/matrix-org/matrix-js-sdk/pull/4297)). Contributed by @RiotRobot. +* Element-R: Fix resource leaks in verification logic ([#4263](https://github.com/matrix-org/matrix-js-sdk/pull/4263)). Contributed by @richvdh. +* Upgrade Rust Crypto SDK to 6.1.0 ([#4261](https://github.com/matrix-org/matrix-js-sdk/pull/4261)). Contributed by @richvdh. +* Correctly transform base64 with multiple instances of + or / ([#4252](https://github.com/matrix-org/matrix-js-sdk/pull/4252)). Contributed by @robintown. +* Work around spec bug for m.room.avatar state event content type ([#4245](https://github.com/matrix-org/matrix-js-sdk/pull/4245)). Contributed by @t3chguy. + + +Changes in [33.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v33.1.0) (2024-06-18) +================================================================================================== +## ✨ Features + +* MSC4108 support OIDC QR code login ([#4134](https://github.com/matrix-org/matrix-js-sdk/pull/4134)). Contributed by @t3chguy. +* Add crypto methods for export and import of secrets bundle ([#4227](https://github.com/matrix-org/matrix-js-sdk/pull/4227)). Contributed by @t3chguy. + +## 🐛 Bug Fixes + +* Fix screen sharing in recent Chrome ([#4243](https://github.com/matrix-org/matrix-js-sdk/pull/4243)). Contributed by @RiotRobot. +* Fix incorrect assumptions about required fields in /search response ([#4228](https://github.com/matrix-org/matrix-js-sdk/pull/4228)). Contributed by @t3chguy. +* Fix the queueToDevice tests for the new fakeindexeddb ([#4225](https://github.com/matrix-org/matrix-js-sdk/pull/4225)). Contributed by @dbkr. + + +Changes in [33.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v33.0.0) (2024-06-04) +================================================================================================== +## 🚨 BREAKING CHANGES + +* Remove more deprecated methods, fields, and exports ([#4217](https://github.com/matrix-org/matrix-js-sdk/pull/4217)). Contributed by @t3chguy. +* Remove deprecated methods and fields ([#4201](https://github.com/matrix-org/matrix-js-sdk/pull/4201)). Contributed by @t3chguy. + +## 🦖 Deprecations + +* Remove more deprecated methods, fields, and exports ([#4217](https://github.com/matrix-org/matrix-js-sdk/pull/4217)). Contributed by @t3chguy. +* Remove deprecated methods and fields ([#4201](https://github.com/matrix-org/matrix-js-sdk/pull/4201)). Contributed by @t3chguy. + +## ✨ Features + +* `initRustCrypto`: allow app to pass in the store key directly ([#4210](https://github.com/matrix-org/matrix-js-sdk/pull/4210)). Contributed by @richvdh. +* Preserve ESM for async imports to work correctly ([#4187](https://github.com/matrix-org/matrix-js-sdk/pull/4187)). Contributed by @ms-dosx86. + +## 🐛 Bug Fixes + +* Don't run migration for Rust crypto if the legacy store is empty ([#4218](https://github.com/matrix-org/matrix-js-sdk/pull/4218)). Contributed by @andybalaam. +* Bump matrix-sdk-crypto-wasm to 5.0.0 ([#4216](https://github.com/matrix-org/matrix-js-sdk/pull/4216)). Contributed by @richvdh. +* Wire up verification cancel \& mismatch for rust crypto ([#4202](https://github.com/matrix-org/matrix-js-sdk/pull/4202)). Contributed by @t3chguy. +* Only pass id\_server if we had one to begin with ([#4200](https://github.com/matrix-org/matrix-js-sdk/pull/4200)). Contributed by @t3chguy. + + +Changes in [32.4.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v32.4.0) (2024-05-22) +================================================================================================== +* No changes + + +Changes in [32.3.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v32.3.0) (2024-05-21) +================================================================================================== +## ✨ Features + +* Simplify OIDC types \& export `decodeIdToken` ([#4193](https://github.com/matrix-org/matrix-js-sdk/pull/4193)). Contributed by @t3chguy. +* Add helpers for authenticated media, and associated documentation ([#4185](https://github.com/matrix-org/matrix-js-sdk/pull/4185)). Contributed by @turt2live. + +## 🐛 Bug Fixes + +* Fix state\_events.ts types ([#4196](https://github.com/matrix-org/matrix-js-sdk/pull/4196)). Contributed by @t3chguy. +* Fix sendEventHttpRequest for `m.room.redaction` events without `redacts` ([#4192](https://github.com/matrix-org/matrix-js-sdk/pull/4192)). Contributed by @t3chguy. + + +Changes in [32.2.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v32.2.0) (2024-05-07) +================================================================================================== +## ✨ Features + +* Use a different error code for UTDs when user was not in the room ([#4172](https://github.com/matrix-org/matrix-js-sdk/pull/4172)). Contributed by @uhoreg. +* Modernize window.crypto access constants ([#4169](https://github.com/matrix-org/matrix-js-sdk/pull/4169)). Contributed by @turt2live. +* Improve compliance with MSC3266 ([#4155](https://github.com/matrix-org/matrix-js-sdk/pull/4155)). Contributed by @AndrewFerr. +* Add comment to make clear that RoomStateEvent.Events does not update related objects in the js-sdk ([#4152](https://github.com/matrix-org/matrix-js-sdk/pull/4152)). Contributed by @toger5. +* Crypto: use a new error code for UTDs from device-relative historical events ([#4139](https://github.com/matrix-org/matrix-js-sdk/pull/4139)). Contributed by @richvdh. + +## 🐛 Bug Fixes + +* Element-R: Fix rust migration when ssss secret are stored not encryted in cache (old legacy behavior) ([#4168](https://github.com/matrix-org/matrix-js-sdk/pull/4168)). Contributed by @BillCarsonFr. + + +Changes in [32.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v32.1.0) (2024-04-23) +================================================================================================== +## ✨ Features + +* Add support for device dehydration v2 (Element R) ([#4062](https://github.com/matrix-org/matrix-js-sdk/pull/4062)). Contributed by @uhoreg. +* OIDC improvements in prep of OIDC-QR reciprocation ([#4149](https://github.com/matrix-org/matrix-js-sdk/pull/4149)). Contributed by @t3chguy. + +## 🐛 Bug Fixes + +* Validate backup private key before migrating it ([#4114](https://github.com/matrix-org/matrix-js-sdk/pull/4114)). Contributed by @BillCarsonFr. +* ElementR| Retry query backup until it works during migration to avoid spurious correption error popup ([#4113](https://github.com/matrix-org/matrix-js-sdk/pull/4113)). Contributed by @BillCarsonFr. + + +Changes in [32.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v32.0.0) (2024-04-09) +================================================================================================== +## 🚨 BREAKING CHANGES + +* Remove various deprecated methods \& re-exports ([#4125](https://github.com/matrix-org/matrix-js-sdk/pull/4125)). Contributed by @t3chguy. +* Remove the logic that throws when the lazy loading options has changed. ([#4124](https://github.com/matrix-org/matrix-js-sdk/pull/4124)). Contributed by @langleyd. +* Fix highlights from threads disappearing on new messages ([#4106](https://github.com/matrix-org/matrix-js-sdk/pull/4106)). Contributed by @dbkr. + +## ✨ Features + +* Add new `decryptExistingEvent` test helper ([#4133](https://github.com/matrix-org/matrix-js-sdk/pull/4133)). Contributed by @richvdh. +* Improve types for `sendEvent` ([#4108](https://github.com/matrix-org/matrix-js-sdk/pull/4108)). Contributed by @t3chguy. +* Remove various deprecated methods \& re-exports ([#4125](https://github.com/matrix-org/matrix-js-sdk/pull/4125)). Contributed by @t3chguy. +* Add new enum for verification methods. ([#4129](https://github.com/matrix-org/matrix-js-sdk/pull/4129)). Contributed by @richvdh. +* Add some test utils in a new entrypoint ([#4127](https://github.com/matrix-org/matrix-js-sdk/pull/4127)). Contributed by @richvdh. +* Improve types for `sendStateEvent` ([#4105](https://github.com/matrix-org/matrix-js-sdk/pull/4105)). Contributed by @t3chguy. + +## 🐛 Bug Fixes + +* Improve types for `IPowerLevelsContent` and `hasSufficientPowerLevelFor` ([#4128](https://github.com/matrix-org/matrix-js-sdk/pull/4128)). Contributed by @galash13. +* Remove the logic that throws when the lazy loading options has changed. ([#4124](https://github.com/matrix-org/matrix-js-sdk/pull/4124)). Contributed by @langleyd. +* Fix highlights from threads disappearing on new messages ([#4106](https://github.com/matrix-org/matrix-js-sdk/pull/4106)). Contributed by @dbkr. +* Extend logic for local notification processing to threads ([#4111](https://github.com/matrix-org/matrix-js-sdk/pull/4111)). Contributed by @dbkr. +* Fix public rooms post request search params and body ([#4110](https://github.com/matrix-org/matrix-js-sdk/pull/4110)). Contributed by @ajbura. +* Fix bugs with the first reply to a thread ([#4104](https://github.com/matrix-org/matrix-js-sdk/pull/4104)). Contributed by @dbkr. + + +Changes in [31.6.1](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.6.1) (2024-03-28) +================================================================================================== +## 🐛 Bug Fixes + +* Fix merging of default push rules ([#4136](https://github.com/matrix-org/matrix-js-sdk/pull/4136)). + + +Changes in [31.6.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.6.0) (2024-03-26) +================================================================================================== +## ✨ Features + +* Introduce Membership TS type (take 2) ([#4107](https://github.com/matrix-org/matrix-js-sdk/pull/4107)). Contributed by @andybalaam. +* fix automatic DM avatar with functional members ([#4017](https://github.com/matrix-org/matrix-js-sdk/pull/4017)). Contributed by @HarHarLinks. +* Export types describing all specced media event formats ([#4092](https://github.com/matrix-org/matrix-js-sdk/pull/4092)). Contributed by @t3chguy. +* Add `.m.rule.is_room_mention` push rule to DEFAULT\_OVERRIDE\_RULES ([#4100](https://github.com/matrix-org/matrix-js-sdk/pull/4100)). Contributed by @t3chguy. +* Make sending ContentLoaded optional for a widgetClient ([#4086](https://github.com/matrix-org/matrix-js-sdk/pull/4086)). Contributed by @toger5. + +## 🐛 Bug Fixes + +* Migrate own identity local trust to rust crypto ([#4090](https://github.com/matrix-org/matrix-js-sdk/pull/4090)). Contributed by @BillCarsonFr. +* Fix race condition with sliding sync extensions ([#4089](https://github.com/matrix-org/matrix-js-sdk/pull/4089)). Contributed by @zzorba. + + +Changes in [31.5.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.5.0) (2024-03-12) +================================================================================================== +## ✨ Features + +* Update MSC2965 OIDC Discovery implementation ([#4064](https://github.com/matrix-org/matrix-js-sdk/pull/4064)). Contributed by @t3chguy. + +## 🐛 Bug Fixes + +* Add basic retry for rust crypto outgoing requests ([#4061](https://github.com/matrix-org/matrix-js-sdk/pull/4061)). Contributed by @BillCarsonFr. + + +Changes in [31.4.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.4.0) (2024-02-27) +================================================================================================== +## ✨ Features + +* Validate `account_management_uri` and `account_management_actions_supported` from OIDC Issuer well-known ([#4074](https://github.com/matrix-org/matrix-js-sdk/pull/4074)). Contributed by @t3chguy. +* Allow specifying OIDC url state parameter for passing data to callback ([#4068](https://github.com/matrix-org/matrix-js-sdk/pull/4068)). Contributed by @t3chguy. +* Add getAuthIssuer method for MSC2965 ([#4071](https://github.com/matrix-org/matrix-js-sdk/pull/4071)). Contributed by @t3chguy. +* Allow specifying more OIDC client metadata for dynamic registration ([#4070](https://github.com/matrix-org/matrix-js-sdk/pull/4070)). Contributed by @t3chguy. +* Add unread marker event type ([#4069](https://github.com/matrix-org/matrix-js-sdk/pull/4069)). Contributed by @dbkr. +* Add "AsJson" forms of the key import/export methods ([#4057](https://github.com/matrix-org/matrix-js-sdk/pull/4057)). Contributed by @andybalaam. + +## 🐛 Bug Fixes + +* Ignore memberships of users that are not in the call ([#4065](https://github.com/matrix-org/matrix-js-sdk/pull/4065)). Contributed by @toger5. +* Await encrypted messages ([#4063](https://github.com/matrix-org/matrix-js-sdk/pull/4063)). Contributed by @toger5. +* ElementR | Ensure own user and device trust are updated after migration before giving back control to the app. ([#4059](https://github.com/matrix-org/matrix-js-sdk/pull/4059)). Contributed by @BillCarsonFr. +* Bump matrix-sdk-crypto-wasm to 4.5.0 ([#4060](https://github.com/matrix-org/matrix-js-sdk/pull/4060)). Contributed by @andybalaam. + + +Changes in [31.3.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.3.0) (2024-02-13) +================================================================================================== +## ✨ Features + +* Add expire\_ts compatibility to matrixRTC ([#4032](https://github.com/matrix-org/matrix-js-sdk/pull/4032)). Contributed by @toger5. +* Element-R: support for migration of the room list from legacy crypto ([#4036](https://github.com/matrix-org/matrix-js-sdk/pull/4036)). Contributed by @richvdh. +* Element-R: check persistent room list for encryption config ([#4035](https://github.com/matrix-org/matrix-js-sdk/pull/4035)). Contributed by @richvdh. +* Support optional MSC3860 redirects ([#4007](https://github.com/matrix-org/matrix-js-sdk/pull/4007)). Contributed by @turt2live. + +## 🐛 Bug Fixes + +* WebR: migrate the megolm session imported flag ([#4037](https://github.com/matrix-org/matrix-js-sdk/pull/4037)). Contributed by @BillCarsonFr. +* ElementR: fix emoji verification stalling when both ends hit start at the same time ([#4004](https://github.com/matrix-org/matrix-js-sdk/pull/4004)). Contributed by @uhoreg. +* Dependencies: Bump wasm bindings version to 4.3.0 ([#4042](https://github.com/matrix-org/matrix-js-sdk/pull/4042)). Contributed by @BillCarsonFr. +* Element R: emit events when devices have changed ([#4019](https://github.com/matrix-org/matrix-js-sdk/pull/4019)). Contributed by @uhoreg. +* ElementR: report invalid keys rather than failing to restore from backup ([#4006](https://github.com/matrix-org/matrix-js-sdk/pull/4006)). Contributed by @uhoreg. +* Make `timeline` a getter ([#4022](https://github.com/matrix-org/matrix-js-sdk/pull/4022)). Contributed by @florianduros. +* Implement getting verification cancellation info in Rust crypto ([#3947](https://github.com/matrix-org/matrix-js-sdk/pull/3947)). Contributed by @uhoreg. +* Fix crypto migration for megolm sessions with no sender key ([#4024](https://github.com/matrix-org/matrix-js-sdk/pull/4024)). Contributed by @richvdh. + + +Changes in [31.2.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.2.0) (2024-01-31) +================================================================================================== +## ✨ Features + +* Emit events during migration from libolm ([#3982](https://github.com/matrix-org/matrix-js-sdk/pull/3982)). Contributed by @richvdh. +* Support for migration from from libolm ([#3978](https://github.com/matrix-org/matrix-js-sdk/pull/3978)). Contributed by @richvdh. + +## 🐛 Bug Fixes + +* ElementR | backup: call expensive `roomKeyCounts` less often ([#4015](https://github.com/matrix-org/matrix-js-sdk/pull/4015)). Contributed by @BillCarsonFr. +* Decrypt and Import full backups in chunk with progress ([#4005](https://github.com/matrix-org/matrix-js-sdk/pull/4005)). Contributed by @BillCarsonFr. +* Fix new threads not appearing. ([#4009](https://github.com/matrix-org/matrix-js-sdk/pull/4009)). Contributed by @dbkr. + + Changes in [31.1.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v31.1.0) (2024-01-19) ================================================================================================== ## ✨ Features @@ -76,6 +526,7 @@ Changes in [30.0.0](https://github.com/matrix-org/matrix-js-sdk/releases/tag/v30 ## 🚨 BREAKING CHANGES * Refactor & make base64 functions browser-safe ([\#3818](https://github.com/matrix-org/matrix-js-sdk/pull/3818)). + * `IndexedDBStore.startup()` must be called after using it on `sdk.createClient` now. ## 🦖 Deprecations * Deprecate `MatrixEvent.toJSON` ([\#3801](https://github.com/matrix-org/matrix-js-sdk/pull/3801)). diff --git a/README.md b/README.md index f194a72715e..e3bf79204a0 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,9 @@ endpoints from before Matrix 1.1, for example. # Quickstart -## In a browser - -### Note, the browserify build has been removed. Please use a bundler like webpack or vite instead. - -## In Node.js - -Ensure you have the latest LTS version of Node.js installed. -This library relies on `fetch` which is available in Node from v18.0.0 - it should work fine also with polyfills. -If you wish to use a ponyfill or adapter of some sort then pass it as `fetchFn` to the MatrixClient constructor options. +> [!IMPORTANT] +> Servers may require or use authenticated endpoints for media (images, files, avatars, etc). See the +> [Authenticated Media](#authenticated-media) section for information on how to enable support for this. Using `yarn` instead of `npm` is recommended. Please see the Yarn [install guide](https://classic.yarnpkg.com/en/docs/install) if you do not have it already. @@ -44,10 +38,8 @@ client.publicRooms(function (err, data) { }); ``` -See below for how to include libolm to enable end-to-end-encryption. Please check -[the Node.js terminal app](examples/node) for a more complex example. - -You can also use the sdk with [Deno](https://deno.land/) (`import npm:matrix-js-sdk`) but its not officialy supported. +See [below](#end-to-end-encryption-support) for how to enable end-to-end-encryption, or check +[the Node.js terminal app](https://github.com/matrix-org/matrix-js-sdk/tree/develop/examples/node) for a more complex example. To start the client: @@ -101,46 +93,74 @@ Object.keys(client.store.rooms).forEach((roomId) => { }); ``` +## Authenticated media + +Servers supporting [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916) (Matrix 1.11) will require clients, like +yours, to include an `Authorization` header when `/download`ing or `/thumbnail`ing media. For NodeJS environments this +may be as easy as the following code snippet, though web browsers may need to use [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) +to append the header when using the endpoints in `` elements and similar. + +```javascript +const downloadUrl = client.mxcUrlToHttp( + /*mxcUrl=*/ "mxc://example.org/abc123", // the MXC URI to download/thumbnail, typically from an event or profile + /*width=*/ undefined, // part of the thumbnail API. Use as required. + /*height=*/ undefined, // part of the thumbnail API. Use as required. + /*resizeMethod=*/ undefined, // part of the thumbnail API. Use as required. + /*allowDirectLinks=*/ false, // should generally be left `false`. + /*allowRedirects=*/ true, // implied supported with authentication + /*useAuthentication=*/ true, // the flag we're after in this example +); +const img = await fetch(downloadUrl, { + headers: { + Authorization: `Bearer ${client.getAccessToken()}`, + }, +}); +// Do something with `img`. +``` + +> [!WARNING] +> In future the js-sdk will _only_ return authentication-required URLs, mandating population of the `Authorization` header. + ## What does this SDK do? This SDK provides a full object model around the Matrix Client-Server API and emits events for incoming data and state changes. Aside from wrapping the HTTP API, it: -- Handles syncing (via `/initialSync` and `/events`) -- Handles the generation of "friendly" room and member names. -- Handles historical `RoomMember` information (e.g. display names). -- Manages room member state across multiple events (e.g. it handles typing, power - levels and membership changes). -- Exposes high-level objects like `Rooms`, `RoomState`, `RoomMembers` and `Users` - which can be listened to for things like name changes, new messages, membership - changes, presence changes, and more. -- Handle "local echo" of messages sent using the SDK. This means that messages - that have just been sent will appear in the timeline as 'sending', until it - completes. This is beneficial because it prevents there being a gap between - hitting the send button and having the "remote echo" arrive. -- Mark messages which failed to send as not sent. -- Automatically retry requests to send messages due to network errors. -- Automatically retry requests to send messages due to rate limiting errors. -- Handle queueing of messages. -- Handles pagination. -- Handle assigning push actions for events. -- Handles room initial sync on accepting invites. -- Handles WebRTC calling. - -Later versions of the SDK will: - -- Expose a `RoomSummary` which would be suitable for a recents page. -- Provide different pluggable storage layers (e.g. local storage, database-backed) +- Handles syncing (via `/sync`) +- Handles the generation of "friendly" room and member names. +- Handles historical `RoomMember` information (e.g. display names). +- Manages room member state across multiple events (e.g. it handles typing, power + levels and membership changes). +- Exposes high-level objects like `Rooms`, `RoomState`, `RoomMembers` and `Users` + which can be listened to for things like name changes, new messages, membership + changes, presence changes, and more. +- Handle "local echo" of messages sent using the SDK. This means that messages + that have just been sent will appear in the timeline as 'sending', until it + completes. This is beneficial because it prevents there being a gap between + hitting the send button and having the "remote echo" arrive. +- Mark messages which failed to send as not sent. +- Automatically retry requests to send messages due to network errors. +- Automatically retry requests to send messages due to rate limiting errors. +- Handle queueing of messages. +- Handles pagination. +- Handle assigning push actions for events. +- Handles room initial sync on accepting invites. +- Handles WebRTC calling. # Usage -## Conventions +## Supported platforms + +`matrix-js-sdk` can be used in either Node.js applications (ensure you have the latest LTS version of Node.js installed), +or in browser applications, via a bundler such as Webpack or Vite. + +You can also use the sdk with [Deno](https://deno.land/) (`import npm:matrix-js-sdk`) but its not officialy supported. -### Emitted events +## Emitted events -The SDK will emit events using an `EventEmitter`. It also -emits object models (e.g. `Rooms`, `RoomMembers`) when they -are updated. +The SDK raises notifications to the application using +[`EventEmitter`s](https://nodejs.org/api/events.html#class-eventemitter). The `MatrixClient` itself +implements `EventEmitter`, as do many of the high-level abstractions such as `Room` and `RoomMember`. ```javascript // Listen for low-level MatrixEvents @@ -161,41 +181,22 @@ client.on(RoomMemberEvent.Typing, function (event, member) { client.startClient(); ``` -### Promises and Callbacks +## Entry points -Most of the methods in the SDK are asynchronous: they do not directly return a -result, but instead return a [Promise](http://documentup.com/kriskowal/q/) -which will be fulfilled in the future. - -The typical usage is something like: - -```javascript - matrixClient.someMethod(arg1, arg2).then(function(result) { - ... - }); -``` +As well as the primary entry point (`matrix-js-sdk`), there are several other entry points which may be useful: -Alternatively, if you have a Node.js-style `callback(err, result)` function, -you can pass the result of the promise into it with something like: - -```javascript -matrixClient.someMethod(arg1, arg2).nodeify(callback); -``` - -The main thing to note is that it is problematic to discard the result of a -promise-returning function, as that will cause exceptions to go unobserved. - -Methods which return a promise show this in their documentation. - -Many methods in the SDK support _both_ Node.js-style callbacks _and_ Promises, -via an optional `callback` argument. The callback support is now deprecated: -new methods do not include a `callback` argument, and in the future it may be -removed from existing methods. +| Entry point | Description | +| ------------------------------ | --------------------------------------------------------------------------------------------------- | +| `matrix-js-sdk` | Primary entry point. High-level functionality, and lots of historical clutter in need of a cleanup. | +| `matrix-js-sdk/lib/crypto-api` | Cryptography functionality. | +| `matrix-js-sdk/lib/types` | Low-level types, reflecting data structures defined in the Matrix spec. | +| `matrix-js-sdk/lib/testing` | Test utilities, which may be useful in test code but should not be used in production code. | +| `matrix-js-sdk/lib/utils/*.js` | A set of modules exporting standalone functions (and their types). | ## Examples This section provides some useful code snippets which demonstrate the -core functionality of the SDK. These examples assume the SDK is setup like this: +core functionality of the SDK. These examples assume the SDK is set up like this: ```javascript import * as sdk from "matrix-js-sdk"; @@ -211,10 +212,10 @@ const matrixClient = sdk.createClient({ ### Automatically join rooms when invited ```javascript -matrixClient.on(RoomMemberEvent.Membership, function (event, member) { - if (member.membership === "invite" && member.userId === myUserId) { - matrixClient.joinRoom(member.roomId).then(function () { - console.log("Auto-joined %s", member.roomId); +matrixClient.on(RoomEvent.MyMembership, function (room, membership, prevMembership) { + if (membership === KnownMembership.Invite) { + matrixClient.joinRoom(room.roomId).then(function () { + console.log("Auto-joined %s", room.roomId); }); } }); @@ -294,7 +295,7 @@ host the API reference from the source files like this: ``` $ yarn gendoc - $ cd _docs + $ cd docs $ python -m http.server 8005 ``` @@ -302,41 +303,131 @@ Then visit `http://localhost:8005` to see the API docs. # End-to-end encryption support -The SDK supports end-to-end encryption via the Olm and Megolm protocols, using -[libolm](https://gitlab.matrix.org/matrix-org/olm). It is left up to the -application to make libolm available, via the `Olm` global. +`matrix-js-sdk`'s end-to-end encryption support is based on the [WebAssembly bindings](https://github.com/matrix-org/matrix-rust-sdk-crypto-wasm) of the Rust [matrix-sdk-crypto](https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto) library. + +## Initialization -It is also necessary to call `await matrixClient.initCrypto()` after creating a new -`MatrixClient` (but **before** calling `matrixClient.startClient()`) to -initialise the crypto layer. +**Do not use `matrixClient.initLegacyCrypto()`. This method is deprecated and no longer maintained.** -If the `Olm` global is not available, the SDK will show a warning, as shown -below; `initCrypto()` will also fail. +To initialize the end-to-end encryption support in the matrix client: +```javascript +// Create a new matrix client +const matrixClient = sdk.createClient({ + baseUrl: "http://localhost:8008", + accessToken: myAccessToken, + userId: myUserId, +}); + +// Initialize to enable end-to-end encryption support. +await matrixClient.initRustCrypto(); ``` -Unable to load crypto module: crypto will be disabled: Error: global.Olm is not defined + +After calling `initRustCrypto`, you can obtain a reference to the [`CryptoApi`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html) interface, which is the main entry point for end-to-end encryption, by calling [`MatrixClient.getCrypto`](https://matrix-org.github.io/matrix-js-sdk/classes/matrix.MatrixClient.html#getCrypto). + +**WARNING**: the cryptography stack is not thread-safe. Having multiple `MatrixClient` instances connected to the same Indexed DB will cause data corruption and decryption failures. The application layer is responsible for ensuring that only one `MatrixClient` issue is instantiated at a time. + +## Secret storage + +You should normally set up [secret storage](https://spec.matrix.org/v1.12/client-server-api/#secret-storage) before using the end-to-end encryption. To do this, call [`CryptoApi.bootstrapSecretStorage`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapSecretStorage). +`bootstrapSecretStorage` can be called unconditionally: it will only set up the secret storage if it is not already set up (unless you use the `setupNewSecretStorage` parameter). + +```javascript +const matrixClient = sdk.createClient({ + ..., + cryptoCallbacks: { + getSecretStorageKey: async (keys) => { + // This function should prompt the user to enter their secret storage key. + return mySecretStorageKeys; + }, + }, +}); + +matrixClient.getCrypto().bootstrapSecretStorage({ + // This function will be called if a new secret storage key (aka recovery key) is needed. + // You should prompt the user to save the key somewhere, because they will need it to unlock secret storage in future. + createSecretStorageKey: async () => { + return mySecretStorageKey; + }, +}); +``` + +The example above will create a new secret storage key if secret storage was not previously set up. +The secret storage data will be encrypted using the secret storage key returned in [`createSecretStorageKey`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CreateSecretStorageOpts.html#createSecretStorageKey). + +We recommend that you prompt the user to re-enter this key when [`CryptoCallbacks.getSecretStorageKey`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) is called (when the secret storage access is needed). + +## Set up cross-signing + +To set up cross-signing to verify devices and other users, call +[`CryptoApi.bootstrapCrossSigning`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#bootstrapCrossSigning): + +```javascript +matrixClient.getCrypto().bootstrapCrossSigning({ + authUploadDeviceSigningKeys: async (makeRequest) => { + return makeRequest(authDict); + }, +}); +``` + +The [`authUploadDeviceSigningKeys`](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.BootstrapCrossSigningOpts.html#authUploadDeviceSigningKeys) +callback is required in order to upload newly-generated public cross-signing keys to the server. + +## Key backup + +If the user doesn't already have a [key backup](https://spec.matrix.org/v1.12/client-server-api/#server-side-key-backups) you should create one: + +```javascript +// Check if we have a key backup. +// If checkKeyBackupAndEnable returns null, there is no key backup. +const hasKeyBackup = (await matrixClient.getCrypto().checkKeyBackupAndEnable()) !== null; + +// Create the key backup +await matrixClient.getCrypto().resetKeyBackup(); ``` -If the crypto layer is not (successfully) initialised, the SDK will continue to -work for unencrypted rooms, but it will not support the E2E parts of the Matrix -specification. +## Verify a new device + +Once the cross-signing is set up on one of your devices, you can verify another device with two methods: + +1. Use `CryptoApi.bootstrapCrossSigning`. + + `bootstrapCrossSigning` will call the [CryptoCallbacks.getSecretStorageKey](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoCallbacks.html#getSecretStorageKey) callback. The device is verified with the private cross-signing keys fetched from the secret storage. + +2. Request an interactive verification against existing devices, by calling [CryptoApi.requestOwnUserVerification](https://matrix-org.github.io/matrix-js-sdk/interfaces/crypto_api.CryptoApi.html#requestOwnUserVerification). -To provide the Olm library in a browser application: +## Migrating from the legacy crypto stack to Rust crypto -- download the transpiled libolm (from https://packages.matrix.org/npm/olm/). -- load `olm.js` as a `