Skip to content

chore: 2026 Q4 stack upgrade (EMBED-590) - #474

Open
tuna1207 wants to merge 18 commits into
masterfrom
feat/stack-upgrade
Open

tuna1207 wants to merge 18 commits into
masterfrom
feat/stack-upgrade

Conversation

@tuna1207

@tuna1207 tuna1207 commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Motivation and Context

Modernize CustomAuth to the 2026 Q4 stack policy: Node 24/26, npm 12, LavaMoat harden, TypeScript + Oxlint/Oxfmt via @toruslabs/torus-scripts@9, Changesets release PR, and MetaMask security scanner. Shared acceptance criteria live in EMBED-573.

Jira Link

Description

  • GitHub policy: CODEOWNERS (examples/), PR template Motivation section, Dependabot (npm + github-actions, 3-day cooldown)
  • Tooling: torus-scripts@8 / ESLint / Prettier → Vite+ (vp), @toruslabs/config@5, Oxlint/Oxfmt, @lavamoat/harden moderate
  • Engines: node >=24.22.0, npm >=12, .nvmrc 26, @types/node ^26.6.6
  • Package entries: main/module/unpkg/jsdelivr unchanged; types dist/lib.cjs/types/index.d.ts → dist/lib.cjs/index.d.ts
  • Dropped unused @babel/runtime peer
  • Public types (breaking, surfaced by strict null checks in @toruslabs/config@5): triggerLogin returns Promise<TorusLoginResponse | null> and ILoginHandler.handleLoginWindow returns Promise<LoginWindowResponse | null>. Both already resolved to null in redirect mode; only the types change. Callers must null-check before reading userInfo.
  • @sentry/core optional peer stays ^10.x. DevDependency is ^10.78.0. Stack-upgrade step 7 says to raise peer ranges with the devDependency; this is an exception. The library only type-imports startSpan (Span, StartSpanOptions), which @sentry/core has exported since 10.0.0. Sentry packages pin @sentry/core to their exact version, so a ^10.78.0 peer makes npm install --strict-peer-deps fail for an app on @sentry/browser@10.50.0 that also depends on @sentry/core@10.50.0.
  • CI: validate (Node 24.22.0 + 26), release-pr (Changesets, no publish), security-code-scanner; vue-app S3/CloudFront deploy on master uses STS vars.AWS_ROLE_ARN + Wiz sensor
  • Popup pages (serviceworker/ and every example) load broadcast-channel@14.0.0 from jsDelivr with SRI sha384-xh8PrJAG…
  • Examples: constants/fnd-base 17 in all four, torus.js 18 in nextjs, vite-react, and vue. Only source change: vue and angular type the triggerLogin result as TorusLoginResponse | null.

Majors taken

  • Tooling: @toruslabs/torus-scripts 8 → 9.0.1, @toruslabs/config 4 → 5, Oxlint presets replace ESLint configs, TypeScript 5 → 7, @types/node 25 → 26, vite-plus / Changesets / harden added
  • Runtime (EMBED-588, EMBED-586): torus.js 17 → 18, broadcast-channel 13 → 14, fetch-node-details 16 → 17, session-manager 5 → 6, eccrypto 7 → 8, constants 16 → 17, http-helpers 9 → 10, metadata-helpers 8 → 9. One copy of each in the tree. No src/ changes were needed.
  • Consumers inherit these majors; anyone also importing torus.js 17 or constants 16 directly should move to the matching majors.

Scan / audit

  • harden check: moderate 3/3
  • npm audit: 6 left (1 low / 5 moderate). The low one is the deepmerge prototype advisory, with no in-range fix without an API change. The 5 moderate are one minimatch chain via eslint-plugin-tsdoc, pulled in by the oxlint preset (dev only).
  • CodeQL: default setup (no second workflow). Semgrep via MetaMask security-code-scanner. KICS/Trivy: N/A (library)
  • Oxlint gap recorded: vitest(require-mock-type-parameters) warnings only (0 errors)

Verification

  • Node 24.22.1: ci, harden, check, build, typecheck, tests (46)
  • Node 26.13.0: same — last run had 42 tests, before the null-type commits; re-run
  • Packed tarball: dist/lib.{cjs,esm}/index.{js,d.ts}, serviceworker/
  • require + ESM import of packed build
  • All four examples (angular, nextjs, vite-react, vue) build with their own framework on constants/fnd-base 17 and torus.js 18. All popup pages pin broadcast-channel@14.0.0 with SRI. (vue and angular not rebuilt after the | null type change.)
  • Live node-details check on sapphire_devnet, sapphire_mainnet, and legacy mainnet. The node-details server returns 200, NodeDetailManager uses the server's data rather than the local fallback, and torus.js@18 getPublicAddress succeeds against those nodes.
  • Auth-flow smoke (manual) — not run
  • passwordless-frontend runtime integration — not run

Settings the token could not change

  • Repository setting: allow GitHub Actions to create PRs (needed for release-pr)
  • Create vars.AWS_ROLE_ARN and secrets.WIZ_SENSOR_TOKEN for deploy
  • Secret scanning / push protection / branch protection: confirm in org UI
  • Do not publish; release-packages stays manual after release PR merges

How has this been tested?

See Verification checklist above.

Screenshots (if appropriate)

N/A

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

  • My code follows the code style of this project. (run lint)
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

Note

High Risk
Major release with toolchain, CI, and dependency majors plus breaking public types; consumers must upgrade Node/npm, handle null login results, and align Torus package majors.

Overview
This PR is a 2026 Q4 stack upgrade for @toruslabs/customauth, shipped as a major release via Changesets. It moves the repo onto torus-scripts 9 / Vite+ with Oxlint/Oxfmt (replacing ESLint/Prettier), Node ≥24.22.0 and npm ≥12, and TypeScript 7.

Release & CI: Adds Changesets (config + major bump notes), replaces the old build/release workflow with validate (matrix Node 24.22.0/26, harden, check, build, typecheck, tests, changeset status on PRs), release-pr (Changesets action), security-code-scanner, and Dependabot. Master deploy still builds/packs the vue demo and syncs S3/CloudFront, now using OIDC (vars.AWS_ROLE_ARN) and an optional Wiz sensor instead of long-lived AWS keys.

Package surface: Published types move from dist/lib.cjs/types/index.d.ts to dist/lib.cjs/index.d.ts. The unused @babel/runtime peer is removed. Major runtime bumps: torus.js 18, broadcast-channel 14, fetch-node-details 17, session-manager 6, eccrypto 8, constants 17, http-helpers 10, metadata-helpers 9.

Breaking for consumers: triggerLogin and ILoginHandler.handleLoginWindow are typed as returning Promise<… | null> (redirect mode already returned null). Example apps and serviceworker pages were updated accordingly; popup HTML/CDN pins broadcast-channel@14.0.0 with new SRI hashes.

Reviewed by Cursor Bugbot for commit 8bacb12. Bugbot is set up for automated code reviews on this repo. Configure here.

tuna1207 and others added 5 commits November 9, 2026 21:07
- CODEOWNERS: give examples/ to the product team
- PR template: add Motivation and Context section
- Dependabot: npm and github-actions, weekly, 3-day cooldown

Co-authored-by: Cursor <cursoragent@cursor.com>
- Node >=24.22.0, npm >=12, .nvmrc 26, @types/node ^26
- Replace torus-scripts 8, ESLint and Prettier with vp pack/lint/fmt,
  @toruslabs/oxlint-config-typescript and formatPreset()
- @toruslabs/config 5 (library profile, DOM libs added)
- Add .npmrc policy (min-release-age, allow-scripts-pin) and @lavamoat/harden
- Changesets config (baseBranch master, public access)
- Fix strictNullChecks errors surfaced by config 5
- Remove legacy torus.config.js, eslint/prettier/vitest configs
- Pin vite and vitest overrides to vite-plus 1.5.0

Co-authored-by: Cursor <cursoragent@cursor.com>
…590)

- validate: Node 24.22.0 and 26, npm 12, npm ci, harden check, check,
  build, typecheck, tests, changeset status (PRs), pack dry-run
- release-pr: manual Changesets release PR on master, does not publish
- security-code-scanner: MetaMask reusable scanner pinned to v2.1.1
- vue-app demo deploy moved to validate on master, using STS role
  from vars.AWS_ROLE_ARN plus Wiz sensor; static AWS keys removed

Co-authored-by: Cursor <cursoragent@cursor.com>
- bowser ^2.14.1 -> ^2.15.0
- @sentry/core ^10.45.0 -> ^10.78.0 (dev and optional peer)
- typescript ^7 -> ^7.0.2
- npm audit fix for in-range advisories; remaining advisories are
  transitive or need a major (deepmerge, minimatch via eslint-plugin-tsdoc)

Co-authored-by: Cursor <cursoragent@cursor.com>
- @babel/runtime peer removed: no build step or source import needs it
- Changeset for @toruslabs/customauth (major): Node/npm engines,
  Vite+ build, types path move, babel peer removal

Co-authored-by: Cursor <cursoragent@cursor.com>
@github-advanced-security

Copy link
Copy Markdown

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

  • The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
  • Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
  • You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

Comment thread .github/workflows/validate.yml Fixed
Comment thread .github/workflows/validate.yml Fixed
tuna1207 and others added 5 commits November 9, 2026 21:18
- Replaced the S3 sync action with a direct AWS CLI command for improved reliability and simplicity.
- Removed unnecessary permissions for id-token in the workflow configuration.

Co-authored-by: Cursor <cursoragent@cursor.com>
…ndencies

- Updated @toruslabs/broadcast-channel from 13.3.0 to 14.0.0 in package.json and related files.
- Adjusted dependencies for @toruslabs/eccrypto, @toruslabs/constants, and @toruslabs/metadata-helpers to align with the new broadcast-channel version.
- Added prepack script to package.json for build automation.
- Updated service worker scripts to reference the new broadcast-channel version.

Co-authored-by: Cursor <cursoragent@cursor.com>
…endencies

- Updated @toruslabs/fetch-node-details from 16.1.1 to 17.0.0 in package.json and package-lock.json.
- Adjusted dependencies for @toruslabs/constants and @toruslabs/http-helpers to align with the new fetch-node-details version.
- Updated Node and npm engine requirements to >=24.22.0 and >=12 respectively.

Co-authored-by: Cursor <cursoragent@cursor.com>
- Updated @toruslabs/constants to 17.0.0, @toruslabs/eccrypto to 8.0.0, @toruslabs/http-helpers to 10.0.0, @toruslabs/metadata-helpers to 9.0.0, and @toruslabs/session-manager to 6.0.0 in package.json and package-lock.json.
- Upgraded @toruslabs/torus.js to 18.0.0 to align with the new dependency versions.
- Removed unused node_modules entries for better clarity and maintenance.

Co-authored-by: Cursor <cursoragent@cursor.com>
- Updated @toruslabs/constants to 17.0.0, @toruslabs/fnd-base to 17.0.0, and @toruslabs/torus.js to 18.0.0 in package.json and package-lock.json across multiple examples.
- Upgraded @toruslabs/customauth to version 22.3.3.
- Updated service worker scripts to reference the new @toruslabs/broadcast-channel version 14.0.0.
- Adjusted Node and npm engine requirements to >=24.22.0 and >=12 respectively.

Co-authored-by: Cursor <cursoragent@cursor.com>
@tuna1207
tuna1207 marked this pull request as ready for review November 13, 2026 09:57
@tuna1207
tuna1207 requested a review from a team as a code owner November 13, 2026 09:57
- Changed the peer dependency version of @sentry/core from ^10.78.0 to ^10.x in package.json and package-lock.json across multiple examples for better compatibility.
- Updated userId retrieval in JwtHandler and MockLoginHandler to remove the nullish coalescing operator, ensuring consistent behavior with the isUserIdCaseSensitive parameter.
public nonce: string = randomId();

public finalURL: URL;
public finalURL!: URL;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why non null assertion?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every subclass sets it in its constructor via setFinalUrl(). Calling it from the base constructor would run before subclass field initializers (Telegram's RESPONSE_TYPE/SCOPE/PROMPT would be undefined)

encodeBase64Url(
JSON.stringify({
...(this.params.customState || {}),
...this.params.customState,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

customState can be undefined right?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Object spread of undefined is a no-op ({...undefined} → {}), so behavior is unchanged. Oxlint's unicorn/no-useless-fallback-in-spread flags the || {}.

Comment thread src/handlers/AbstractLoginHandler.ts Outdated
});
}
return null;
return null as unknown as LoginWindowResponse;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we avoid as unknown as?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Previously we keeped the type cast for null to not break client type check but this is a major upgrade so i updated the type to return nullable response.

Comment thread src/handlers/PasskeysHandler.ts Outdated
const { idToken, extraParams } = parameters;

const { sessionId } = JSON.parse(decodeBase64Url(extraParams)) || {};
const { sessionId } = JSON.parse(decodeBase64Url(extraParams || "")) || {};

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

decodeBase64Url('') returns empty string, ''.
JSON.parse('') will throw an error.

Shall we just throw new Error("sessionId not found") if extraParams is empty?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated 1ffebc8

Comment thread src/handlers/TelegramHandler.ts Outdated
async getUserInfo(params: LoginWindowResponse): Promise<TorusConnectionResponse> {
const { idToken } = params;
const userInfo = objectToAuthDataMap(idToken);
const userInfo = objectToAuthDataMap(idToken || "");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here as above, https://github.com/torusresearch/CustomAuth/pull/474/changes#r4563764706

objectToAuthDataMap does JSON.parse under the hood.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated 8c9e3c0

Comment thread src/handlers/TelegramHandler.ts Outdated
...rest,
idToken: encodeBase64Url(JSON.stringify(result)) || "",
state: decodeBase64Url(stateParam) as unknown as { [key: string]: string },
state: decodeBase64Url(stateParam || "") as unknown as { [key: string]: string },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.
Let's throw an informative error rather than uncaught exceptions. 😅

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated 07151c4

- Added a check to throw an error if extraParams is empty or missing in the getUserInfo method.
- Updated unit tests to cover scenarios where extraParams is undefined or an empty string, ensuring robust error handling.
- Added a check in the getUserInfo method to throw an error if idToken is not provided, enhancing robustness.
- Introduced unit tests to validate the new error handling and ensure correct behavior when idToken is missing or invalid.
…meter

- Added a check to throw an error if the state parameter is missing in the handleLoginWindow method, improving robustness.
- Updated unit tests to validate the new error handling for scenarios where the state parameter is not present in the Telegram response.
- Modified the handleLoginWindow method in AbstractLoginHandler and its implementations to return Promise<LoginWindowResponse | null> instead of just LoginWindowResponse.
- Added error handling in CustomAuth to throw an error if the login window returns no response, enhancing robustness.
- Updated related implementations in MockLoginHandler and TelegramHandler to align with the new return type.
- Changed the return type of triggerLogin in CustomAuth and related implementations to Promise<TorusLoginResponse | null> to reflect the new behavior in redirect mode.
- Updated examples in Angular and Vue applications to handle the new null return type, ensuring proper null-checking before accessing user information.
lwin-kyaw
lwin-kyaw previously approved these changes Nov 13, 2026
Comment thread src/utils/helpers.ts Fixed
Build hash and query param objects with Object.fromEntries so keys from
the URL (e.g. __proto__) become own properties instead of dynamic writes.
Resolves CodeQL js/remote-property-injection in src/utils/helpers.ts.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants