fix(auth): Address several auth typing inconsistencies

[MathBunny]

During my work for refactoring auth to auto-generate typings I came across several inconsistencies in source and typing files. I'm not sure how to best address them or which require changes, but I did an attempt here.

1. auth.ts

Observation: The tenant field is defined at the root of the object in the source while it's in the firebase scope in the typings.

Source:

firebase-admin-node/src/auth/auth.ts

Lines 88 to 112 in 5e6ebfa

	/** Interface representing a decoded ID token. */
	export interface DecodedIdToken {
	aud: string;
	auth_time: number;
	email?: string;
	email_verified?: boolean;
	exp: number;
	firebase: {
	identities: {
	[key: string]: any;
	};
	sign_in_provider: string;
	sign_in_second_factor?: string;
	second_factor_identifier?: string;
	[key: string]: any;
	};
	iat: number;
	iss: string;
	phone_number?: string;
	picture?: string;
	sub: string;
	tenant?: string;
	uid: string;
	[key: string]: any;
	}

Typing:

firebase-admin-node/src/auth.d.ts

Lines 456 to 491 in e415188

	firebase: {
	/**
	* Provider-specific identity details corresponding
	* to the provider used to sign in the user.
	*/
	identities: {
	[key: string]: any;
	};
	/**
	* The ID of the provider used to sign in the user.
	* One of `"anonymous"`, `"password"`, `"facebook.com"`, `"github.com"`,
	* `"google.com"`, `"twitter.com"`, or `"custom"`.
	*/
	sign_in_provider: string;
	/**
	* The type identifier or `factorId` of the second factor, provided the
	* ID token was obtained from a multi-factor authenticated user.
	* For phone, this is `"phone"`.
	*/
	sign_in_second_factor?: string;
	/**
	* The `uid` of the second factor used to sign in, provided the
	* ID token was obtained from a multi-factor authenticated user.
	*/
	second_factor_identifier?: string;
	/**
	* The ID of the tenant the user belongs to, if available.
	*/
	tenant?: string;
	[key: string]: any;
	};

2. auth-config.ts

Observation: The SAMLAuthProviderConfig contains an enableRequestSigning in the source which is absent in typings.

Source:

firebase-admin-node/src/auth/auth-config.ts

Lines 42 to 50 in 5e6ebfa

	/** The SAML Auth provider configuration interface. */
	export interface SAMLAuthProviderConfig extends AuthProviderConfig {
	idpEntityId: string;
	ssoURL: string;
	x509Certificates: string[];
	rpEntityId: string;
	callbackURL?: string;
	enableRequestSigning?: boolean;
	}

Typing:

firebase-admin-node/src/auth.d.ts

Lines 1139 to 1177 in e415188

	interface SAMLAuthProviderConfig extends admin.auth.AuthProviderConfig {
	/**
	* The SAML IdP entity identifier.
	*/
	idpEntityId: string;
	/**
	* The SAML IdP SSO URL. This must be a valid URL.
	*/
	ssoURL: string;
	/**
	* The list of SAML IdP X.509 certificates issued by CA for this provider.
	* Multiple certificates are accepted to prevent outages during
	* IdP key rotation (for example ADFS rotates every 10 days). When the Auth
	* server receives a SAML response, it will match the SAML response with the
	* certificate on record. Otherwise the response is rejected.
	* Developers are expected to manage the certificate updates as keys are
	* rotated.
	*/
	x509Certificates: string[];
	/**
	* The SAML relying party (service provider) entity ID.
	* This is defined by the developer but needs to be provided to the SAML IdP.
	*/
	rpEntityId: string;
	/**
	* This is fixed and must always be the same as the OAuth redirect URL
	* provisioned by Firebase Auth,
	* `https://project-id.firebaseapp.com/__/auth/handler` unless a custom
	* `authDomain` is used.
	* The callback URL should also be provided to the SAML IdP during
	* configuration.
	*/
	callbackURL?: string;
	}

As an extension, a similar pattern can be found here for SAMLAuthProviderConfig:

firebase-admin-node/src/auth/auth-config.ts

Lines 118 to 128 in 5e6ebfa

	/** The public API request interface for updating a SAML Auth provider. */
	export interface SAMLUpdateAuthProviderRequest {
	idpEntityId?: string;
	ssoURL?: string;
	x509Certificates?: string[];
	rpEntityId?: string;
	callbackURL?: string;
	enableRequestSigning?: boolean;
	enabled?: boolean;
	displayName?: string;
	}

3. user-import-builder.ts

Observation: The tenantId for UserImportRecord is nullable in typings but not source.

Source:

firebase-admin-node/src/auth/user-import-builder.ts

Lines 64 to 82 in 5e6ebfa

	/** User import record as accepted from developer. */
	export interface UserImportRecord {
	uid: string;
	email?: string;
	emailVerified?: boolean;
	displayName?: string;
	phoneNumber?: string;
	photoURL?: string;
	disabled?: boolean;
	metadata?: UserMetadataRequest;
	providerData?: Array<UserProviderRequest>;
	multiFactor?: {
	enrolledFactors: SecondFactor[];
	};
	customClaims?: {[key: string]: any};
	passwordHash?: Buffer;
	passwordSalt?: Buffer;
	tenantId?: string;
	}

Typing:

firebase-admin-node/src/auth.d.ts

Lines 816 to 823 in e415188

	/**
	* The identifier of the tenant where user is to be imported to.
	* When not provided in an `admin.auth.Auth` context, the user is uploaded to
	* the default parent project.
	* When not provided in an `admin.auth.TenantAwareAuth` context, the user is uploaded
	* to the tenant corresponding to that `TenantAwareAuth` instance's tenant ID.
	*/
	tenantId?: string | null;

4. auth-config.ts

Observation: As a consequence from the third point, the tenantId field is nullable in one case so it should be propagated.

Source:

firebase-admin-node/src/auth/user-import-builder.ts

Lines 95 to 118 in 5e6ebfa

	/** UploadAccount endpoint request user interface. */
	interface UploadAccountUser {
	localId: string;
	email?: string;
	emailVerified?: boolean;
	displayName?: string;
	disabled?: boolean;
	photoUrl?: string;
	phoneNumber?: string;
	providerUserInfo?: Array<{
	rawId: string;
	providerId: string;
	email?: string;
	displayName?: string;
	photoUrl?: string;
	}>;
	mfaInfo?: AuthFactorInfo[];
	passwordHash?: string;
	salt?: string;
	lastLoginAt?: number;
	createdAt?: number;
	customAttributes?: string;
	tenantId?: string;
	}

firebase-admin-node/src/auth/user-import-builder.ts

Lines 216 to 229 in 5e6ebfa

	function populateUploadAccountUser(
	user: UserImportRecord, userValidator?: ValidatorFunction): UploadAccountUser {
	const result: UploadAccountUser = {
	localId: user.uid,
	email: user.email,
	emailVerified: user.emailVerified,
	displayName: user.displayName,
	disabled: user.disabled,
	photoUrl: user.photoURL,
	phoneNumber: user.phoneNumber,
	providerUserInfo: [],
	mfaInfo: [],
	tenantId: user.tenantId,
	customAttributes: user.customClaims && JSON.stringify(user.customClaims),

This would be a compilation error:

Type 'string | null | undefined' is not assignable to type 'string | undefined'.
Type 'null' is not assignable to type 'string | undefined'.

5. user-record.ts

The typings have displayName and enrollmentTime as optional while not in the source.

Source:

firebase-admin-node/src/auth/user-record.ts

Lines 149 to 153 in 5e6ebfa

	export abstract class MultiFactorInfo {
	public readonly uid: string;
	public readonly displayName: string;
	public readonly factorId: MultiFactorId;
	public readonly enrollmentTime: string;

Typing:

firebase-admin-node/src/auth.d.ts

Lines 80 to 106 in e415188

	interface MultiFactorInfo {
	/**
	* The ID of the enrolled second factor. This ID is unique to the user.
	*/
	uid: string;
	/**
	* The optional display name of the enrolled second factor.
	*/
	displayName?: string;
	/**
	* The optional date the second factor was enrolled, formatted as a UTC string.
	*/
	enrollmentTime?: string;
	/**
	* The type identifier of the second factor. For SMS second factors, this is `phone`.
	*/
	factorId: string;
	/**
	* @return A JSON-serializable representation of this object.
	*/
	toJSON(): Object;
	}

[hiranya911]

(1) Typings are correct the way this is currently implemented. Perhaps we should just drop that field in the implementation type.
(2) I believe enableRequestSigning is not publicly exposed yet. So typings are correct. Not sure how to handle this case though.
(3), (4) I don't think this field can be nullable. We should probably update the typings.
(5) Typings should be correct.

[bojeil-google]

We don't currently support this. I think we should remove it. I think we need the flexibility to have internal implementations not exposed externally. Many SDKs with auto-generated references already have the ability to set visibility on some APIs and attributes.

[hiranya911]

FWIW, there's no built-in mechanism in TypeScript to hide members of an interface. Any library that's doing so is either using third-party tools or some sort of a hack. So we will have to do the same here (@MathBunny the undocumented --stripInternal flag is probably our best bet here).

[MathBunny]

Thanks, I agree. I verified the @internal option and it worked as intended (updated the respective PR).

[bojeil-google]

Same here

[hiranya911]

LGTM