Release v8.0.0: Universal Runtime Support & API Modernization

[nicknisi]

Overview

Version 8 is a major release focused on universal runtime compatibility and API modernization. The SDK now works seamlessly across Node.js, Deno, Bun, and Cloudflare Workers while removing long-deprecated APIs.

---

🔴 BREAKING CHANGES

Runtime & Build System

1. Node.js Version Requirement (BREAKING)

• Changed: Minimum Node.js version: 16 → 20
• Reason: Node 18 reached end-of-life in April 2025
• Files: package.json (engines.node)
• Migration: Update to Node.js 20 or higher

2. Package Type Change to ESM-First (BREAKING)

• Changed: package.json now includes "type": "module"
• Impact: The package is now ESM-first with dual CJS/ESM exports
• Files: package.json
• Migration: Most users won't need changes due to conditional exports, but projects with custom build configurations may need adjustments

3. Build System Migration (Internal)

• Changed: Migrated from tsc to tsup for building
• Added: tsup.config.ts configuration
• Removed: tslint.json
• Impact: Better bundle output, improved tree-shaking, cleaner dist files

Removed Internal Classes (BREAKING)

4. HTTP Client Removal (BREAKING)

• Removed: NodeHttpClient class and createHttpClient() method
• Files: src/common/net/node-client.ts (deleted)
• Impact: Only affects deep imports into internal modules (never part of public API)
• Migration: Use WorkOS instance instead - HTTP is handled automatically

5. Crypto Provider Removal (BREAKING)

• Removed: NodeCryptoProvider, IronSessionProvider, EdgeIronSessionProvider, WebIronSessionProvider
• Changed: Now using iron-session library directly (sealData/unsealData)
• Files: src/common/crypto/node-crypto-provider.ts (deleted), src/common/iron-session/* (deleted)
• Impact: Only affects deep imports into internal modules
• Migration: Use WorkOS instance methods - crypto is handled automatically

Directory Sync (BREAKING)

6. DirectoryUser Interface Changes (BREAKING)

• Removed fields:
  • emails → Use customAttributes.emails
  • username → Use customAttributes.username
  • jobTitle → Use customAttributes.jobTitle
• Removed utility: getPrimaryEmail() function
• Files: src/directory-sync/interfaces/directory-user.interface.ts, src/directory-sync/utils/get-primary-email.ts (deleted)
• Migration:

  // v7
  user.emails
  user.username
  user.jobTitle
  
  // v8
  user.customAttributes?.emails
  user.customAttributes?.username
  user.customAttributes?.jobTitle
  

User Management (BREAKING)

7. AuthorizationURLOptions Changes (BREAKING)

• Removed: context field (no longer supported)
• Files: src/user-management/interfaces/authorization-url-options.interface.ts
• Migration: Remove the context parameter from authorization URL calls

8. Removed Deprecated Methods (BREAKING)

• Removed:
  • sendMagicAuthCode() → Use userManagement.sendMagicCode() instead
  • sendPasswordResetEmail() → Use userManagement.sendPasswordResetEmail() instead
  • refreshAndSealSessionData() → Use new session helper methods instead
• Files: src/user-management/user-management.ts, serializers removed

SSO (BREAKING)

9. SSOAuthorizationURLOptions Type Changes (BREAKING)

• Changed: Converted to discriminated union for type safety
• Removed: domain field (deprecated)
• Files: src/sso/interfaces/authorization-url-options.interface.ts
• Impact: Stricter TypeScript types - must now specify exactly one of: connection, organization, or provider
• Migration:

  // v7 - Multiple options allowed
  { connection: 'conn_123', organization: 'org_456' } // Both accepted
  
  // v8 - Mutually exclusive (enforced by types)
  { connection: 'conn_123' } // OR
  { organization: 'org_456' } // OR
  { provider: 'GoogleOAuth' }
  

10. Connection Interface (BREAKING)

• Removed: Several deprecated internal fields
• Files: src/sso/interfaces/connection.interface.ts
• Migration: Use only documented fields

MFA (BREAKING)

11. Method Removal (BREAKING)

• Removed: verifyFactor() method
• Files: src/mfa/mfa.ts, src/mfa/interfaces/verify-factor-options.ts (deleted)
• Migration: Use verifyChallenge() instead (same functionality)

  // v7
  await workos.mfa.verifyFactor({ authenticationFactorId, code });
  
  // v8
  await workos.mfa.verifyChallenge({ authenticationFactorId, code });
  

Organizations (BREAKING)

12. Organization Options Changes (BREAKING)

• Removed from CreateOrganizationOptions and UpdateOrganizationOptions:
  • allowProfilesOutsideOrganization
  • domains (use domainData instead)
• Files: src/organizations/interfaces/*.interface.ts
• Migration: Remove these fields from organization creation/update calls

13. Organization Domain Enum (BREAKING)

• Removed: LegacyVerified from OrganizationDomainState enum
• Files: src/organizations/interfaces/organization-domain.interface.ts
• Migration: Use Verified instead

Events (BREAKING)

14. Event Type Removals (BREAKING)

• Removed event interfaces:
  • DsyncDeactivatedEvent → Use dsync.deleted instead
  • OrganizationMembershipAdded → Not applicable in v8
  • OrganizationMembershipRemoved → Not applicable in v8
• Files: src/common/interfaces/event.interface.ts
• Migration:

  // v7
  if (event.event === 'dsync.deactivated') { }
  
  // v8
  if (event.event === 'dsync.deleted') { }
  

Vault (BREAKING)

15. Removed Deprecated Method Aliases (BREAKING)

• Removed methods:
  • createSecret() → Use createObject() instead
  • listSecrets() → Use listObjects() instead
  • listSecretVersions() → Use listObjectVersions() instead
  • readSecret() → Use readObject() instead
  • describeSecret() → Use describeObject() instead
  • updateSecret() → Use updateObject() instead
  • deleteSecret() → Use deleteObject() instead
• Files: src/vault/vault.ts
• Migration: Replace all *Secret methods with *Object equivalents

---

✅ NEW FEATURES

16. Client API for PKCE Flows (NON-BREAKING)

• Added: New @workos-inc/node/client export for client-side operations without API key
• Files: src/client/*, src/index.client.ts
• Use case: Browser-based PKCE flows, public client operations
• Example:

  import * as userManagement from '@workos-inc/node/client';
  
  const url = userManagement.getAuthorizationUrl({
    clientId: 'client_123',
    redirectUri: 'https://example.com/callback',
    provider: 'authkit',
  });
  

17. Universal Runtime Support (NON-BREAKING)

• Improved: Better support for Deno, Bun, and Cloudflare Workers
• Added: Conditional exports in package.json for runtime-specific entry points
• Files: package.json (exports), src/index.worker.ts
• Example:

  // Cloudflare Workers
  import { WorkOS } from '@workos-inc/node/worker';
  
  // Deno
  import { WorkOS } from 'npm:@workos-inc/node';
  
  // Bun (same as Node.js)
  import { WorkOS } from '@workos-inc/node';
  

18. Environment Variable Helper (NON-BREAKING)

• Added: Internal getEnv() helper for better cross-runtime environment variable access
• Files: src/common/utils/env.ts
• Benefit: Works consistently across Node.js, Deno, Cloudflare Workers, etc.

19. Pagination Improvements (NON-BREAKING)

• Changed: AutoPaginatable now properly defaults PaginationOptions generic parameter
• Files: src/common/utils/pagination.ts
• Benefit: Better TypeScript inference and type safety

---

🔧 INTERNAL IMPROVEMENTS

20. Linting Migration (Internal)

• Changed: Migrated from TSLint to ESLint with flat config
• Added: eslint.config.mjs
• Removed: tslint.json
• Impact: Better code quality checks, modern linting setup

21. Runtime Testing (Internal)

• Added: New GitHub Actions workflow for testing across multiple runtimes
• Added: Ecosystem check script (scripts/ecosystem-check.ts)
• Files: .github/workflows/runtime-tests.yml
• Benefit: Ensures SDK works correctly in all supported runtimes

22. Dependency Updates (Internal)

• Updated: All dependencies to latest compatible versions
• Updated: Development tooling (Jest 30, TypeScript 5.9, etc.)
• Files: package.json, package-lock.json

23. Test Infrastructure (Internal)

• Updated: Jest configuration migrated to CommonJS
• Added: Jest ESM transform
• Files: jest.config.cjs, jest-transform-esm.cjs
• Updated: Worker test environment with latest Miniflare

---

📋 Files Changed Summary

• 104 files changed: 9,161 insertions, 3,879 deletions
• Major additions: Client API module, runtime-specific exports, environment helper
• Major deletions: Internal HTTP/crypto providers, deprecated methods, legacy event types
• Configuration: New build system (tsup), new linting (ESLint), updated Jest

---

📖 Migration Guide

See V8_MIGRATION_GUIDE.md for detailed migration instructions.

Note: The migration guide needs minor updates for:

• Package type change to ESM-first
• SSO AuthorizationURLOptions discriminated union
• Vault method aliases removal
• Complete refreshAndSealSessionData() examples

---

🧪 Testing

• ✅ All existing tests updated and passing
• ✅ Runtime compatibility tests added
• ✅ Worker environment tests updated
• ✅ Ecosystem check script validates multi-runtime support

[benasher44]

Since you're going for dual ESM/CJS, you might want to check "are the types wrong". For example: https://arethetypeswrong.github.io/?p=%40workos-inc%2Fnode%408.0.0-rc.2

[socket-security[bot]]

[!WARNING] Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		High CVE: npm glob CLI: Command injection via -c/--cmd executes matches with shell:true CVE: GHSA-5j98-mcp5-4vw2 glob CLI: Command injection via -c/--cmd executes matches with shell:true (HIGH) Affected versions: >= 11.0.0 < 11.1.0; >= 10.2.0 < 10.5.0 Patched version: 10.5.0 From: package-lock.json → npm/[email protected] → npm/[email protected] ℹ Read more on: This package | This alert | What is a CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: Remove or replace dependencies that include known high severity CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		High CVE: npm glob CLI: Command injection via -c/--cmd executes matches with shell:true CVE: GHSA-5j98-mcp5-4vw2 glob CLI: Command injection via -c/--cmd executes matches with shell:true (HIGH) Affected versions: >= 11.0.0 < 11.1.0; >= 10.2.0 < 10.5.0 Patched version: 11.1.0 From: package-lock.json → npm/[email protected] ℹ Read more on: This package | This alert | What is a CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: Remove or replace dependencies that include known high severity CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[github-actions[bot]]

Coana detected 1 new reachable vulnerability in this pull request. Please review the vulnerability below and take appropriate action before merging the PR.

---

Vulnerability: CVE-2025-64756 Type: Not previously seen vulnerability Title: glob CLI: Command injection via -c/--cmd executes matches with shell:true Severity: high Package: glob Affected workspace(s): . Affected version(s): >=10.2.0 <10.5.0 || >=11.0.0 <11.1.0 Patched version(s): Installed version(s): 10.4.5 Reachability: Undeterminable reachability Detailed description: The vulnerability is only exposed in the Glob CLI. If you just use Glob programatically as a library, you are not exposed to the vulnerability.

To ignore this vulnerability add a comment with /coana_ignore GHSA-5j98-mcp5-4vw2 and restart the workflow.

This comment was automatically inserted by the Coana Guardrail check (Learn more)