refactor(v6): audit the public API surface and freeze the error taxonomy #1634
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,213 @@ | ||
| import * as path from 'path'; | ||
| import * as ts from 'typescript'; | ||
|
|
||
| /** | ||
| * The frozen public API surface of `src/index.ts`. | ||
| * | ||
| * This list is the stable public contract for v6. Adding an entry is a minor | ||
| * change; **removing or renaming an entry is a breaking change** and must be | ||
| * treated as such (major version, deprecation cycle, changelog entry). | ||
| * | ||
| * If this test fails, do not "fix" it by regenerating the list. Confirm the | ||
| * change to the surface is intentional and versioned appropriately first. | ||
| */ | ||
| const FROZEN_PUBLIC_API = [ | ||
| 'ApiCredentials', | ||
| 'Auth0', | ||
| 'Auth0ContextInterface', | ||
| 'Auth0ErrorCode', | ||
| 'Auth0Options', | ||
| 'Auth0Provider', | ||
| 'AuthError', | ||
| 'AuthState', | ||
| 'AuthenticationMethod', | ||
| 'AuthenticationMethodType', | ||
| 'AuthenticationMethodTypes', | ||
| 'AuthorizeUrlParameters', | ||
| 'BiometricPolicy', | ||
| 'ClearSessionParameters', | ||
| 'ConfirmOTPEnrollmentParameters', | ||
| 'ConfirmPushNotificationEnrollmentParameters', | ||
| 'ConfirmRecoveryCodeEnrollmentParameters', | ||
| 'CreateUserParameters', | ||
| 'Credentials', | ||
| 'CredentialsManagerError', | ||
| 'CredentialsManagerErrorCode', | ||
| 'CredentialsManagerErrorCodes', | ||
| 'CustomTokenExchangeParameters', | ||
| 'DPoPError', | ||
| 'DPoPErrorCode', | ||
| 'DPoPErrorCodes', | ||
| 'DPoPHeadersParameters', | ||
| 'DPoPHeadersParams', | ||
| 'DeleteAuthenticationMethodByIdParameters', | ||
| 'DeliveryMethod', | ||
| 'EnrollEmailParameters', | ||
| 'EnrollPasskeyParameters', | ||
| 'EnrollPhoneParameters', | ||
| 'EnrollPushNotificationParameters', | ||
| 'EnrollRecoveryCodeParameters', | ||
| 'EnrollTOTPParameters', | ||
| 'EnrollmentChallenge', | ||
| 'ExchangeNativeSocialParameters', | ||
| 'ExchangeParameters', | ||
| 'Factor', | ||
| 'GetAuthenticationMethodByIdParameters', | ||
| 'GetAuthenticationMethodsParameters', | ||
| 'GetFactorsParameters', | ||
| 'GetTokenByPasskeyParameters', | ||
| 'IAuth0Client', | ||
| 'IAuthenticationProvider', | ||
| 'ICredentialsManager', | ||
| 'IMfaClient', | ||
| 'IMyAccountClient', | ||
| 'IPasswordlessClient', | ||
| 'IWebAuthProvider', | ||
| 'LocalAuthenticationLevel', | ||
| 'LocalAuthenticationOptions', | ||
| 'LocalAuthenticationStrategy', | ||
| 'LoginEmailParameters', | ||
| 'LoginSmsParameters', | ||
| 'LogoutUrlParameters', | ||
| 'MfaAuthenticator', | ||
| 'MfaChallengeResult', | ||
| 'MfaChallengeWithAuthenticatorParameters', | ||
| 'MfaEnrollEmailParameters', | ||
| 'MfaEnrollOtpParameters', | ||
| 'MfaEnrollParameters', | ||
| 'MfaEnrollPushParameters', | ||
| 'MfaEnrollSmsParameters', | ||
| 'MfaEnrollVoiceParameters', | ||
| 'MfaEnrollmentChallenge', | ||
| 'MfaError', | ||
| 'MfaErrorCode', | ||
| 'MfaErrorCodes', | ||
| 'MfaFactor', | ||
| 'MfaFactorType', | ||
| 'MfaGetAuthenticatorsParameters', | ||
| 'MfaOobEnrollmentChallenge', | ||
| 'MfaPushEnrollmentChallenge', | ||
| 'MfaRecoveryCodeEnrollmentChallenge', | ||
| 'MfaRequiredErrorPayload', | ||
| 'MfaRequirements', | ||
| 'MfaTotpEnrollmentChallenge', | ||
| 'MfaVerifyOobParameters', | ||
| 'MfaVerifyOtpParameters', | ||
| 'MfaVerifyParameters', | ||
| 'MfaVerifyRecoveryCodeParameters', | ||
| 'MyAccountError', | ||
| 'MyAccountErrorCode', | ||
| 'MyAccountErrorCodes', | ||
| 'NativeAuthorizeOptions', | ||
| 'NativeClearSessionOptions', | ||
| 'PasskeyAuthenticationMethod', | ||
| 'PasskeyChallengeResponse', | ||
| 'PasskeyEnrollmentChallengeParameters', | ||
| 'PasskeyEnrollmentChallengeResponse', | ||
| 'PasskeyError', | ||
| 'PasskeyErrorCode', | ||
| 'PasskeyErrorCodes', | ||
| 'PasskeyLoginChallengeParameters', | ||
| 'PasskeySignupChallengeParameters', | ||
| 'PasswordRealmParameters', | ||
| 'PasswordlessChallenge', | ||
| 'PasswordlessChallengeEmailParameters', | ||
| 'PasswordlessChallengePhoneParameters', | ||
| 'PasswordlessDeliveryMethod', | ||
| 'PasswordlessEmailParameters', | ||
| 'PasswordlessLoginOtpParameters', | ||
| 'PasswordlessSmsParameters', | ||
| 'PreferredAuthenticationMethods', | ||
| 'RecoveryCodeEnrollmentChallenge', | ||
| 'RefreshTokenParameters', | ||
| 'ResetPasswordParameters', | ||
| 'RevokeOptions', | ||
| 'SSOExchangeParameters', | ||
| 'SafariViewControllerPresentationStyle', | ||
| 'SessionTransferCredentials', | ||
| 'TOTPEnrollmentChallenge', | ||
| 'TimeoutError', | ||
| 'TokenType', | ||
| 'UpdateAuthenticationMethodByIdParameters', | ||
| 'User', | ||
| 'UserInfoParameters', | ||
| 'WebAuthError', | ||
| 'WebAuthErrorCode', | ||
| 'WebAuthErrorCodes', | ||
| 'WebAuthorizeOptions', | ||
| 'WebAuthorizeParameters', | ||
| 'WebClearSessionOptions', | ||
| 'default', | ||
| 'parseIdToken', | ||
| 'useAuth0', | ||
| ]; | ||
|
|
||
| /** | ||
| * Resolves the actual exports of `src/index.ts` through the TypeScript compiler. | ||
| * | ||
| * A runtime `import * from '../index'` cannot be used here: most of the surface | ||
| * is type-only and erased at runtime, so it would silently miss regressions in | ||
| * the exported types — which are just as breaking as a missing class. | ||
| */ | ||
| function resolvePublicExports(): string[] { | ||
| const projectRoot = path.resolve(__dirname, '..', '..'); | ||
| const configPath = path.join(projectRoot, 'tsconfig.json'); | ||
| const entryPoint = path.join(projectRoot, 'src', 'index.ts'); | ||
|
|
||
| const config = ts.getParsedCommandLineOfConfigFile(configPath, {}, { | ||
| ...ts.sys, | ||
| onUnRecoverableConfigFileDiagnostic: (diagnostic) => { | ||
| throw new Error( | ||
| ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n') | ||
| ); | ||
| }, | ||
| } as ts.ParseConfigFileHost); | ||
|
|
||
| if (!config) { | ||
| throw new Error(`Unable to parse ${configPath}`); | ||
| } | ||
|
|
||
| const program = ts.createProgram([entryPoint], config.options); | ||
| const checker = program.getTypeChecker(); | ||
| const sourceFile = program.getSourceFile(entryPoint); | ||
|
|
||
| if (!sourceFile) { | ||
| throw new Error(`Unable to load ${entryPoint}`); | ||
| } | ||
|
|
||
| const moduleSymbol = checker.getSymbolAtLocation(sourceFile); | ||
|
|
||
| if (!moduleSymbol) { | ||
| throw new Error(`${entryPoint} is not a module`); | ||
| } | ||
|
|
||
| return checker | ||
| .getExportsOfModule(moduleSymbol) | ||
| .map((symbol) => symbol.getName()) | ||
| .sort(); | ||
| } | ||
|
|
||
| describe('public API surface', () => { | ||
| // Building a full TS program is slower than a normal unit test. | ||
| const actual = resolvePublicExports(); | ||
|
|
||
| it('matches the frozen v6 contract exactly', () => { | ||
| expect(actual).toEqual([...FROZEN_PUBLIC_API].sort()); | ||
| }); | ||
|
|
||
| it('exports nothing that has been removed from the contract', () => { | ||
| const frozen = new Set(FROZEN_PUBLIC_API); | ||
| expect(actual.filter((name) => !frozen.has(name))).toEqual([]); | ||
| }); | ||
|
|
||
| it('still exports everything the contract promises', () => { | ||
| const exported = new Set(actual); | ||
| expect(FROZEN_PUBLIC_API.filter((name) => !exported.has(name))).toEqual([]); | ||
| }); | ||
|
|
||
| it('exposes the default export under a named alias', () => { | ||
| // `default` alone is awkward for consumers doing `import { Auth0 }`. | ||
| expect(actual).toContain('default'); | ||
| expect(actual).toContain('Auth0'); | ||
| }); | ||
|
Comment on lines
+208
to
+212
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- target file outline ---'
ast-grep outline src/__tests__/publicApiSurface.spec.ts || true
printf '%s\n' '--- target test context ---'
sed -n '1,250p' src/__tests__/publicApiSurface.spec.ts
printf '%s\n' '--- Auth0 export declarations and related tests ---'
rg -n --glob '!lib/**' --glob '!docs/**' --glob '!coverage/**' \
"export .*Auth0|default as Auth0|class Auth0|const Auth0|interface .*Auth0|publicApiSurface|typeChecker|getAliasedSymbol" \
src package.json tsconfig*.jsonRepository: auth0/react-native-auth0 Length of output: 9982 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- relevant source declarations ---'
sed -n '1,125p' src/index.ts
sed -n '1,55p' src/Auth0.ts
sed -n '205,225p' src/Auth0.ts
printf '%s\n' '--- TypeScript/test configuration ---'
cat package.json
printf '%s\n' '--- tsconfig ---'
cat tsconfig.json
printf '%s\n' '--- compiler API availability ---'
node - <<'JS'
try {
const ts = require('typescript');
console.log(JSON.stringify({ available: true, version: ts.version }));
} catch (error) {
console.log(JSON.stringify({ available: false, message: String(error) }));
}
JSRepository: auth0/react-native-auth0 Length of output: 11914 🏁 Script executed: #!/bin/bash
set -eu
node - <<'JS'
const path = require('path');
const ts = require('typescript');
const projectRoot = process.cwd();
const configPath = path.join(projectRoot, 'tsconfig.json');
const entryPoint = path.join(projectRoot, 'src', 'index.ts');
const config = ts.getParsedCommandLineOfConfigFile(configPath, {}, {
...ts.sys,
onUnRecoverableConfigFileDiagnostic(diagnostic) {
throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
},
});
if (!config) throw new Error(`Unable to parse ${configPath}`);
const program = ts.createProgram([entryPoint], config.options);
const checker = program.getTypeChecker();
const sourceFile = program.getSourceFile(entryPoint);
if (!sourceFile) throw new Error(`Unable to load ${entryPoint}`);
const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
if (!moduleSymbol) throw new Error('Entry point is not a module');
const exports = new Map(
checker.getExportsOfModule(moduleSymbol).map((symbol) => [symbol.getName(), symbol])
);
const defaultExport = exports.get('default');
const namedAuth0Export = exports.get('Auth0');
function describe(symbol) {
if (!symbol) return null;
const aliased = symbol.flags & ts.SymbolFlags.Alias
? checker.getAliasedSymbol(symbol)
: symbol;
return {
name: symbol.getName(),
flags: symbol.flags,
isAlias: Boolean(symbol.flags & ts.SymbolFlags.Alias),
aliasTargetName: aliased.getName(),
aliasTargetId: aliased.id,
declarations: (aliased.declarations ?? []).map((declaration) => ({
file: path.relative(projectRoot, declaration.getSourceFile().fileName),
kind: ts.SyntaxKind[declaration.kind],
text: declaration.getText(),
})),
};
}
console.log(JSON.stringify({
defaultExport: describe(defaultExport),
namedAuth0Export: describe(namedAuth0Export),
resolvedSymbolsIdentical:
defaultExport && namedAuth0Export &&
checker.getAliasedSymbol(defaultExport) === checker.getAliasedSymbol(namedAuth0Export),
}, null, 2));
JSRepository: auth0/react-native-auth0 Length of output: 12684 Assert that The current assertions only check that both names exist. Resolve both symbols with the TypeScript checker and compare their aliased symbols. 🤖 Prompt for AI Agents |
||
| }); | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Align the handler with the documented Custom Token Exchange codes.
This handler checks
unsupported_grant_type. The reference at lines 1209-1226 listsunsupported_token_typeandunauthorized_clientinstead. The documented alerts for unsupported token types and disabled clients will not run for the listed codes.Align the handler and reference with the same emitted code set.
🤖 Prompt for AI Agents