Remove `__legacy__` folders from packages & refactor the usage

[brionmario]

Current Limitation

The packages contains __legacy__ folders which holds outdated or deprecated implementation. Keeping legacy code can lead to confusion and maintenance issues.

Suggested Improvement

Remove the entire __legacy__ folder from the packages and refactor any code that references or depends on its contents.

Please select the package issue is related to

@asgardeo/browser, @asgardeo/express, @asgardeo/javascript, @asgardeo/node

Version

N/A

Reporter Checklist

• I have searched the existing issues and this is not a duplicate.
• I have provided all the necessary information.
• I have verified the improvement is not available in the latest version of the package.

[brionmario]

Claude's Plan

---

Plan: Eliminate __legacy__ from packages/javascript, packages/browser, and packages/node

Context

All three SDK packages contain __legacy__ folders holding code that predates the current modular architecture. The goal is consistent across all packages:

• Extract helper-class methods to standalone functions in utils/
• Extract network-calling methods to api/
• Move models to models/
• Move stores to stores/
• Move constants to constants/
• Dissolve helper classes; keep stateful clients as classes
• Delete __legacy__/ from all three packages

---

Package 1: packages/javascript

New files to create

src/models/auth-client-config.ts
Move directly from __legacy__/models/client-config.ts. Pure type definitions, no logic changes.
Exports: DefaultAuthClientConfig, WellKnownAuthClientConfig, BaseURLAuthClientConfig, ExplicitAuthClientConfig, StrictAuthClientConfig, AuthClientConfig.

---

src/utils/resolveEndpoints.ts
Extracted from AuthenticationHelper.resolveEndpoints().

export default async function resolveEndpoints(storageManager, response): Promise<OIDCDiscoveryApiResponse>

src/utils/resolveEndpointsExplicitly.ts
Extracted from AuthenticationHelper.resolveEndpointsExplicitly().

export default async function resolveEndpointsExplicitly(storageManager): Promise<OIDCDiscoveryEndpointsApiResponse>

src/utils/resolveEndpointsByBaseURL.ts
Extracted from AuthenticationHelper.resolveEndpointsByBaseURL().

export default async function resolveEndpointsByBaseURL(storageManager): Promise<OIDCDiscoveryEndpointsApiResponse>

src/utils/getAuthenticatedUserInfo.ts
Extracted from AuthenticationHelper.getAuthenticatedUserInfo(). Uses existing extractUserClaimsFromIdToken util internally.

export default function getAuthenticatedUserInfo(cryptoHelper, idToken): User

src/utils/replaceCustomGrantTemplateTags.ts
Extracted from AuthenticationHelper.replaceCustomGrantTemplateTags().

export default async function replaceCustomGrantTemplateTags(storageManager, cryptoHelper, text, userId?): Promise<string>

src/utils/clearSession.ts
Extracted from AuthenticationHelper.clearSession().

export default async function clearSession(storageManager, userId?): Promise<void>

---

src/api/validateIdToken.ts
Extracted from AuthenticationHelper.validateIdToken(). Fetches JWKS endpoint.

export default async function validateIdToken(storageManager, cryptoHelper, idToken): Promise<boolean>

src/api/handleTokenResponse.ts
Extracted from AuthenticationHelper.handleTokenResponse(). Calls validateIdToken if configured.

export default async function handleTokenResponse(storageManager, cryptoHelper, response, userId?): Promise<TokenResponse>

src/api/loadOpenIDProviderConfiguration.ts
Extracted from AsgardeoAuthClient.loadOpenIDProviderConfiguration(). Calls resolveEndpoints* utils.

export default async function loadOpenIDProviderConfiguration(storageManager, cryptoHelper, forceInit): Promise<void>

src/api/requestAccessToken.ts

export default async function requestAccessToken(storageManager, cryptoHelper, authorizationCode, sessionState, state, userId?, tokenRequestConfig?): Promise<TokenResponse>

src/api/refreshAccessToken.ts

export default async function refreshAccessToken(storageManager, cryptoHelper, userId?): Promise<TokenResponse>

src/api/revokeAccessToken.ts
Calls clearSession util on success.

export default async function revokeAccessToken(storageManager, userId?): Promise<Response>

src/api/exchangeToken.ts
Calls replaceCustomGrantTemplateTags util.

export default async function exchangeToken(storageManager, cryptoHelper, config, userId?): Promise<TokenResponse | Response>

---

src/AsgardeoAuthClient.ts (moved from __legacy__/client.ts)
Refactored class — orchestration only:

• Remove AuthenticationHelper field; call extracted functions directly
• Remove configProvider/oidcProviderMetaDataProvider lambda fields; call storageManager directly
• Replace authHelperInstance FIXME static with static _storageManager set during initialize()
• Import config types from ./models/auth-client-config

Files to modify

src/AsgardeoJavaScriptClient.ts

• from './__legacy__/client' → from './AsgardeoAuthClient'
• from './__legacy__/models/client-config' → from './models/auth-client-config'

src/index.ts

• from './__legacy__/client' → from './AsgardeoAuthClient'
• from './__legacy__/models' → from './models/auth-client-config'

Files to delete

src/__legacy__/ — entire directory

---

Package 2: packages/browser

The browser __legacy__ contains the old SPA SDK: AsgardeoSPAClient, a web worker client, a main-thread client, helper classes, stores, constants, and models. The new client (AsgardeoBrowserClient) already lives outside __legacy__. The approach is to move everything to proper top-level folders while converting helper class methods to standalone functions.

Models → src/models/

Move (no code changes):

• __legacy__/models/client-config.ts → models/spa-client-config.ts
• __legacy__/models/message.ts → models/message.ts
• __legacy__/models/sign-in.ts → models/sign-in.ts
• __legacy__/models/sign-out-error.ts → models/sign-out-error.ts
• __legacy__/models/storage.ts → models/browser-storage.ts
• __legacy__/models/web-worker.ts → models/web-worker.ts
• __legacy__/models/session-management-helper.ts → models/session-management-helper.ts
• __legacy__/models/client.ts → models/thread-client.ts
• __legacy__/models/http-client.ts → models/http-client.ts
• __legacy__/models/request-custom-grant.ts → models/request-custom-grant.ts

Constants → src/constants/

Move (no code changes):

• __legacy__/constants/errors.ts → constants/errors.ts
• __legacy__/constants/hooks.ts → constants/hooks.ts
• __legacy__/constants/messages-types.ts → constants/message-types.ts
• __legacy__/constants/parameters.ts → constants/parameters.ts
• __legacy__/constants/session-management.ts → constants/session-management.ts
• __legacy__/constants/storage.ts → constants/storage.ts

Stores → src/stores/

Move (no code changes):

• __legacy__/stores/local-store.ts → stores/LocalStore.ts
• __legacy__/stores/memory-store.ts → stores/MemoryStore.ts
• __legacy__/stores/session-store.ts → stores/SessionStore.ts

Helper classes → src/utils/ (functional)

Each method in AuthenticationHelper, SPAHelper, SessionManagementHelper becomes a standalone function in utils/.

AuthenticationHelper methods → individual files in utils/:

• checkSession() → utils/checkSession.ts
• getAuthorizationURLFromServer() → utils/getAuthorizationURLFromServer.ts
• handleSignInResponse() → utils/handleSignInResponse.ts
• refreshAccessToken() → utils/browser/refreshAccessToken.ts
• (other methods as appropriate)

SPAHelper methods → individual utils:

• refreshAccessTokenAutomatically() → utils/refreshAccessTokenAutomatically.ts
• getRefreshTimeoutTimer() → utils/getRefreshTimeoutTimer.ts
• clearRefreshTokenTimeout() → utils/clearRefreshTokenTimeout.ts

SessionManagementHelper methods → individual utils.

SPAUtils class → src/utils/ (functional)

Each static method becomes a standalone function:

• SPAUtils.removeAuthorizationCode() → utils/removeAuthorizationCode.ts
• SPAUtils.getPKCE() → utils/getSPAPKCE.ts
• SPAUtils.setPKCE() → utils/setSPAPKCE.ts
• SPAUtils.setSignOutURL() / getSignOutUrl() → utils/spaSignOutUrl.ts
• SPAUtils.removePKCE() → utils/removeSPAPKCE.ts
• SPAUtils.canContinueSignIn() → utils/canContinueSignIn.ts
• SPAUtils.hasAuthSearchParamsInURL() → keep as update/alias of existing utils/hasAuthParamsInUrl.ts
• SPAUtils.hasErrorInURL() → utils/hasErrorInURL.ts
• SPAUtils.isSignOutSuccessful() → utils/isSPASignOutSuccessful.ts
• SPAUtils.didSignOutFail() → utils/didSPASignOutFail.ts
• SPAUtils.canSendPromptNoneRequest() / setPromptNoneRequestSent() → utils/promptNoneRequest.ts
• SPAUtils.waitTillPageRedirect() → utils/waitTillPageRedirect.ts
• SPAUtils.until() → utils/until.ts

MessageUtils class → src/utils/ (functional)

Static methods → standalone functions in utils/.

SPACryptoUtils class → src/DefaultCrypto.ts

Move to root level. This already implements the Crypto interface from @asgardeo/javascript.

Clients → src/clients/

Move (factory function pattern stays):

• __legacy__/clients/main-thread-client.ts → clients/mainThreadClient.ts
• __legacy__/clients/web-worker-client.ts → clients/webWorkerClient.ts

Worker → src/worker/

Move:

• __legacy__/worker/worker-core.ts → worker/workerCore.ts
• __legacy__/worker/worker-receiver.ts → worker/workerReceiver.ts

AsgardeoSPAClient → src/AsgardeoSPAClient.ts

Move from __legacy__/client.ts to root. The class stays as a class (it holds state and implements the Multiton pattern). Update its imports to use the relocated models, constants, stores, clients, and utils.

Files to modify

src/index.ts — update all __legacy__ import paths to new locations.

Files to delete

src/__legacy__/ — entire directory

---

Package 3: packages/node

Models → src/models/

Move (no code changes):

• __legacy__/models/session-data.ts → models/session-data.ts
• __legacy__/models/url-callback.ts → models/url-callback.ts

Constants → src/constants/

Move:

• __legacy__/constants/uuid-config.ts → constants/uuid-config.ts
• __legacy__/constants/logger-config.ts → constants/logger-config.ts

Stores → src/stores/

Move:

• __legacy__/stores/memory-cache-store.ts → stores/MemoryCacheStore.ts

NodeCryptoUtils → src/DefaultCrypto.ts

Move from __legacy__/utils/crypto-utils.ts to root. Implements Crypto interface from @asgardeo/javascript.

SessionUtils class → src/utils/ (functional)

Convert static class methods to standalone functions:

• SessionUtils.createUUID() → utils/createUUID.ts
• SessionUtils.validateUUID() → utils/validateUUID.ts
• SessionUtils.validateSession() → utils/validateSession.ts

Logger class → src/utils/NodeLogger.ts

Move as-is (class with static methods). It is exported as public API, so cannot change method call signature. Note as a future improvement to align with @asgardeo/javascript's logger.

AsgardeoNodeCore → src/AsgardeoNodeCore.ts

Move from __legacy__/core/authentication.ts to root. Update imports to use relocated stores, utils, and models.

Legacy AsgardeoNodeClient → src/LegacyAsgardeoNodeClient.ts

Move from __legacy__/client.ts to root. Exported as LegacyAsgardeoNodeClient in index.ts (already aliased this way).

Files to modify

src/index.ts — update all __legacy__ import paths to new locations.

Files to delete

src/__legacy__/ — entire directory

---

Additional Improvements (all packages)

1. Remove configProvider/oidcProviderMetaDataProvider lambdas in javascript — unnecessary indirection.
2. Remove authHelperInstance FIXME static — replace with static _storageManager.
3. Trim JSDoc comments to match the terse style already used outside __legacy__.
4. No barrel index.ts inside new utils/api/models sub-folders — keep each file importable directly.
5. Logger alignment (node) — future: replace NodeLogger with @asgardeo/javascript logger to reduce duplication.
6. DefaultCrypto alignment (browser/node) — both have local crypto-utils that mirror what @asgardeo/javascript already provides. Move to DefaultCrypto.ts in each package and consider re-exporting from @asgardeo/javascript long-term.

---

Verification

For each package (javascript, browser, node):

1. TypeScript compilation:

   • pnpm --filter @asgardeo/javascript tsc --noEmit
   • pnpm --filter @asgardeo/browser tsc --noEmit
   • pnpm --filter @asgardeo/node tsc --noEmit

2. Tests:

   • pnpm --filter @asgardeo/javascript test
   • pnpm --filter @asgardeo/browser test
   • pnpm --filter @asgardeo/node test

3. No remaining __legacy__ imports:

   • grep -r "__legacy__" packages/javascript/src → no results
   • grep -r "__legacy__" packages/browser/src → no results
   • grep -r "__legacy__" packages/node/src → no results

4. Public exports unchanged: all types/classes currently exported from each package's index.ts remain exported with the same names.

[NethmikaKekuu]

@brionmario please assign this issue to me

[kavix]

Hi @brionmario, could you please assign this issue to me? I’d be happy to work on it. Thanks!