@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/features/social/social-providers.service.d.ts

@@ -0,0 +1,97 @@
+import { AuthOptions } from '../../auth-options.js';
+import { SocialProvider } from '../../database/entities/index.js';
+import { AuthSettings } from '../settings/settings.types.js';
+/** Who the provider says the user is. */
+export interface SocialIdentity {
+    provider: SocialProvider;
+    /** The provider's permanent id for the user ("sub"). Emails can change; this can't. */
+    providerUserId: string;
+    email: string | null;
+    /** True only when the provider itself confirmed the user owns the email. */
+    isEmailVerified: boolean;
+    firstName: string | null;
+    lastName: string | null;
+}
+/** What the app sends after the user signed in with the provider's own SDK or button. */
+export interface SocialCredential {
+    /** Google / Apple: the ID token (a JWT). Facebook: the user access token. */
+    token: string;
+    /**
+     * Optional. If your app put a nonce in the provider request, send the same raw nonce here.
+     * It ties the token to this sign-in so a stolen token can't be replayed. Strongly recommended for Apple.
+     */
+    nonce?: string;
+}
+/**
+ * Checks tokens from Google, Apple and Facebook WITHOUT trusting the app: signatures are verified
+ * against the provider's published keys (Google, Apple) or the token is checked with Facebook's API.
+ */
+export declare class SocialProvidersService {
+    private readonly options;
+    private readonly logger;
+    private readonly googleKeys;
+    private readonly appleKeys;
+    constructor(options: AuthOptions);
+    /**
+     * Checks a provider token and returns who it belongs to.
+     *
+     * @param provider - "google", "apple" or "facebook".
+     * @param credential - The token (and optional nonce) the app got from the provider.
+     * @param settings - The current settings (which providers are on, client ids).
+     * @returns The provider's user id, email and names.
+     * @throws AuthError SIGN_IN_METHOD_DISABLED when the provider is turned off.
+     * @throws AuthError NOT_CONFIGURED when client ids or the Facebook app secret are missing.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    verifyCredential(provider: SocialProvider, credential: SocialCredential, settings: AuthSettings): Promise<SocialIdentity>;
+    /**
+     * @param credential - Google's ID token and optional nonce.
+     * @param clientIds - Your Google OAuth client ids (web, iOS, Android).
+     * @returns The identity from the token.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    private verifyGoogleIdToken;
+    /**
+     * @param credential - Apple's ID token and optional nonce.
+     * @param clientIds - Your Apple Services ID / bundle ids.
+     * @returns The identity from the token (names are always null; Apple sends them to the app only).
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    private verifyAppleIdToken;
+    /**
+     * Shared ID-token checks: signature, issuer, audience, expiry, and the nonce when given.
+     *
+     * @param credential - The ID token and optional nonce.
+     * @param providerKeys - The provider's public keys.
+     * @param issuers - Accepted "iss" values.
+     * @param clientIds - Accepted "aud" values (your client ids).
+     * @returns The token's claims.
+     * @throws AuthError NOT_CONFIGURED when no client ids are set.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when any check fails.
+     */
+    private verifyProviderIdToken;
+    /**
+     * Apple puts sha256(rawNonce) in the token; Google puts the raw nonce. Accept either form.
+     *
+     * @param rawNonce - The nonce the app sent.
+     * @param nonceInToken - The "nonce" claim from the token.
+     * @returns True when they match.
+     */
+    private nonceMatches;
+    /**
+     * Asks Facebook whether the access token is valid and was issued to OUR app, then reads the profile.
+     *
+     * @param accessToken - The user access token from the Facebook SDK.
+     * @param appId - Your Facebook app id.
+     * @returns The identity. The email is never treated as verified.
+     * @throws AuthError NOT_CONFIGURED when the app id or secret is missing.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token is invalid or for another app.
+     */
+    private verifyFacebookAccessToken;
+    /**
+     * @param url - A Facebook Graph API URL.
+     * @returns The JSON response, or null for a non-2xx answer.
+     * @throws AuthError INTERNAL_SERVER_ERROR when Facebook can't be reached.
+     */
+    private fetchFacebookJson;
+}

package/dist/features/social/social-providers.service.js

@@ -0,0 +1,214 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialProvidersService = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const auth_error_1 = require("../../common/auth-error.js");
+const jwt_1 = require("../../common/crypto/jwt.js");
+const remote_public_keys_1 = require("../../common/crypto/remote-public-keys.js");
+const random_secrets_1 = require("../../common/crypto/random-secrets.js");
+const constants_1 = require("../../constants.js");
+/**
+ * Checks tokens from Google, Apple and Facebook WITHOUT trusting the app: signatures are verified
+ * against the provider's published keys (Google, Apple) or the token is checked with Facebook's API.
+ */
+let SocialProvidersService = class SocialProvidersService {
+    options;
+    logger = new common_1.Logger(constants_1.LOG_CONTEXT.socialProviders);
+    googleKeys = new remote_public_keys_1.RemotePublicKeys(constants_1.GOOGLE_PUBLIC_KEYS_URL);
+    appleKeys = new remote_public_keys_1.RemotePublicKeys(constants_1.APPLE_PUBLIC_KEYS_URL);
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Checks a provider token and returns who it belongs to.
+     *
+     * @param provider - "google", "apple" or "facebook".
+     * @param credential - The token (and optional nonce) the app got from the provider.
+     * @param settings - The current settings (which providers are on, client ids).
+     * @returns The provider's user id, email and names.
+     * @throws AuthError SIGN_IN_METHOD_DISABLED when the provider is turned off.
+     * @throws AuthError NOT_CONFIGURED when client ids or the Facebook app secret are missing.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    async verifyCredential(provider, credential, settings) {
+        switch (provider) {
+            case constants_1.SOCIAL_PROVIDER.google:
+                if (!settings.google.enabled)
+                    throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.signInMethodDisabled);
+                return this.verifyGoogleIdToken(credential, settings.google.clientIds);
+            case constants_1.SOCIAL_PROVIDER.apple:
+                if (!settings.apple.enabled)
+                    throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.signInMethodDisabled);
+                return this.verifyAppleIdToken(credential, settings.apple.clientIds);
+            case constants_1.SOCIAL_PROVIDER.facebook:
+                if (!settings.facebook.enabled)
+                    throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.signInMethodDisabled);
+                return this.verifyFacebookAccessToken(credential.token, settings.facebook.appId);
+            default:
+                throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.signInMethodDisabled);
+        }
+    }
+    // -------------------------------------------------------------------------------------------
+    // Google: an RS256 ID token whose "aud" must be one of YOUR client ids.
+    // -------------------------------------------------------------------------------------------
+    /**
+     * @param credential - Google's ID token and optional nonce.
+     * @param clientIds - Your Google OAuth client ids (web, iOS, Android).
+     * @returns The identity from the token.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    async verifyGoogleIdToken(credential, clientIds) {
+        const claims = await this.verifyProviderIdToken(credential, this.googleKeys, constants_1.GOOGLE_TOKEN_ISSUERS, clientIds);
+        return {
+            provider: constants_1.SOCIAL_PROVIDER.google,
+            providerUserId: claims.sub,
+            email: typeof claims.email === 'string' ? claims.email.toLowerCase() : null,
+            isEmailVerified: claims.email_verified === true,
+            firstName: typeof claims.given_name === 'string' ? claims.given_name : null,
+            lastName: typeof claims.family_name === 'string' ? claims.family_name : null,
+        };
+    }
+    // -------------------------------------------------------------------------------------------
+    // Apple: like Google. Apple sends the user's name only to the app, only the first time, so
+    // the app passes it in the sign-up details. The email may be a private relay address.
+    // -------------------------------------------------------------------------------------------
+    /**
+     * @param credential - Apple's ID token and optional nonce.
+     * @param clientIds - Your Apple Services ID / bundle ids.
+     * @returns The identity from the token (names are always null; Apple sends them to the app only).
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token doesn't check out.
+     */
+    async verifyAppleIdToken(credential, clientIds) {
+        const claims = await this.verifyProviderIdToken(credential, this.appleKeys, [constants_1.APPLE_TOKEN_ISSUER], clientIds);
+        return {
+            provider: constants_1.SOCIAL_PROVIDER.apple,
+            providerUserId: claims.sub,
+            email: typeof claims.email === 'string' ? claims.email.toLowerCase() : null,
+            // Apple sends this as a boolean or as the string "true".
+            isEmailVerified: claims.email_verified === true || claims.email_verified === constants_1.APPLE_TRUE_STRING,
+            firstName: null,
+            lastName: null,
+        };
+    }
+    /**
+     * Shared ID-token checks: signature, issuer, audience, expiry, and the nonce when given.
+     *
+     * @param credential - The ID token and optional nonce.
+     * @param providerKeys - The provider's public keys.
+     * @param issuers - Accepted "iss" values.
+     * @param clientIds - Accepted "aud" values (your client ids).
+     * @returns The token's claims.
+     * @throws AuthError NOT_CONFIGURED when no client ids are set.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when any check fails.
+     */
+    async verifyProviderIdToken(credential, providerKeys, issuers, clientIds) {
+        if (clientIds.length === 0)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.notConfigured);
+        await providerKeys.ensureLoaded((0, jwt_1.readJwtKeyId)(credential.token));
+        const claims = (0, jwt_1.verifyJwt)(credential.token, (keyId) => providerKeys.findLoadedKey(keyId), {
+            allowedAlgorithm: constants_1.PROVIDER_ID_TOKEN_ALGORITHM,
+            expectedIssuers: issuers,
+            expectedAudiences: clientIds,
+        });
+        if (!claims || typeof claims.sub !== 'string' || claims.sub.length === 0)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSocialToken);
+        if (credential.nonce !== undefined || claims.nonce !== undefined) {
+            if (!this.nonceMatches(credential.nonce, claims.nonce))
+                throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSocialToken);
+        }
+        return claims;
+    }
+    /**
+     * Apple puts sha256(rawNonce) in the token; Google puts the raw nonce. Accept either form.
+     *
+     * @param rawNonce - The nonce the app sent.
+     * @param nonceInToken - The "nonce" claim from the token.
+     * @returns True when they match.
+     */
+    nonceMatches(rawNonce, nonceInToken) {
+        if (typeof rawNonce !== 'string' || typeof nonceInToken !== 'string')
+            return false;
+        const hashedNonce = (0, node_crypto_1.createHash)(constants_1.HASH_ALGORITHM.sha256).update(rawNonce).digest(constants_1.TEXT_ENCODING.hex);
+        return (0, random_secrets_1.constantTimeEquals)(nonceInToken, rawNonce) || (0, random_secrets_1.constantTimeEquals)(nonceInToken, hashedNonce);
+    }
+    // -------------------------------------------------------------------------------------------
+    // Facebook: no ID token for most apps, so we ask Facebook whether the access token is valid
+    // and was issued to OUR app (otherwise a token from any other app would be accepted).
+    // -------------------------------------------------------------------------------------------
+    /**
+     * Asks Facebook whether the access token is valid and was issued to OUR app, then reads the profile.
+     *
+     * @param accessToken - The user access token from the Facebook SDK.
+     * @param appId - Your Facebook app id.
+     * @returns The identity. The email is never treated as verified.
+     * @throws AuthError NOT_CONFIGURED when the app id or secret is missing.
+     * @throws AuthError INVALID_SOCIAL_TOKEN when the token is invalid or for another app.
+     */
+    async verifyFacebookAccessToken(accessToken, appId) {
+        const appSecret = this.options.facebookAppSecret;
+        if (!appId || !appSecret)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.notConfigured);
+        const tokenCheckUrl = new URL(`${constants_1.FACEBOOK_GRAPH_API_URL}${constants_1.FACEBOOK_API.debugTokenPath}`);
+        tokenCheckUrl.searchParams.set(constants_1.FACEBOOK_API.inputTokenParameter, accessToken);
+        tokenCheckUrl.searchParams.set(constants_1.FACEBOOK_API.accessTokenParameter, constants_1.FACEBOOK_API.appAccessToken(appId, appSecret));
+        const tokenCheck = await this.fetchFacebookJson(tokenCheckUrl);
+        const tokenData = tokenCheck?.data;
+        const tokenIsForOurApp = tokenData?.is_valid === true && String(tokenData.app_id) === appId && typeof tokenData.user_id === 'string';
+        if (!tokenIsForOurApp)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSocialToken);
+        // appsecret_proof proves the call comes from our server, not from someone holding the token.
+        const profileUrl = new URL(`${constants_1.FACEBOOK_GRAPH_API_URL}${constants_1.FACEBOOK_API.profilePath}`);
+        profileUrl.searchParams.set(constants_1.FACEBOOK_API.fieldsParameter, constants_1.FACEBOOK_PROFILE_FIELDS);
+        profileUrl.searchParams.set(constants_1.FACEBOOK_API.accessTokenParameter, accessToken);
+        profileUrl.searchParams.set(constants_1.FACEBOOK_API.appSecretProofParameter, (0, node_crypto_1.createHmac)(constants_1.HASH_ALGORITHM.sha256, appSecret).update(accessToken).digest(constants_1.TEXT_ENCODING.hex));
+        const profile = await this.fetchFacebookJson(profileUrl);
+        if (!profile || profile.id !== tokenData.user_id)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSocialToken);
+        return {
+            provider: constants_1.SOCIAL_PROVIDER.facebook,
+            providerUserId: profile.id,
+            email: typeof profile.email === 'string' ? profile.email.toLowerCase() : null,
+            // Facebook does not say whether the email was confirmed, so we never treat it as proven.
+            isEmailVerified: false,
+            firstName: typeof profile.first_name === 'string' ? profile.first_name : null,
+            lastName: typeof profile.last_name === 'string' ? profile.last_name : null,
+        };
+    }
+    /**
+     * @param url - A Facebook Graph API URL.
+     * @returns The JSON response, or null for a non-2xx answer.
+     * @throws AuthError INTERNAL_SERVER_ERROR when Facebook can't be reached.
+     */
+    async fetchFacebookJson(url) {
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(constants_1.SOCIAL_PROVIDER_TIMEOUT_MS) });
+            if (!response.ok)
+                return null;
+            return (await response.json());
+        }
+        catch (error) {
+            this.logger.warn(`Facebook API call failed: ${error.message}`);
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.internalError);
+        }
+    }
+};
+exports.SocialProvidersService = SocialProvidersService;
+exports.SocialProvidersService = SocialProvidersService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.AUTH_OPTIONS_TOKEN)),
+    __metadata("design:paramtypes", [Object])
+], SocialProvidersService);
+//# sourceMappingURL=social-providers.service.js.map

package/dist/features/social/social-providers.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-providers.service.js","sourceRoot":"","sources":["../../../src/features/social/social-providers.service.ts"],"names":[],"mappings":"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"}

package/dist/features/social/social.controller.d.ts

@@ -0,0 +1,54 @@
+import { RequestContext } from '../../common/request-context.js';
+import { SocialAuthService } from './social-auth.service';
+import { SocialSignInInput } from './social.dto';
+/**
+ * Google, Apple and Facebook.
+ *
+ *   POST   /auth/social/:provider        sign in / sign up with the provider's token
+ *   POST   /auth/social/:provider/link   signed in: connect the provider to this account
+ *   DELETE /auth/social/:provider        signed in: disconnect it
+ *
+ * :provider is "google", "apple" or "facebook".
+ */
+export declare class SocialController {
+    private readonly socialAuth;
+    constructor(socialAuth: SocialAuthService);
+    /**
+     * POST /auth/social/:provider — Signs in or signs up with the provider's token. Public.
+     *
+     * @param provider - From the URL.
+     * @param body - `{ token, nonce? }`, plus sign-up details for new accounts.
+     * @param request - Who is asking.
+     * @returns Tokens, or a 2FA challenge.
+     */
+    signIn(provider: string, body: SocialSignInInput, request: RequestContext): Promise<import("../..").SignInResult>;
+    /**
+     * POST /auth/social/:provider/link — Connects the provider to the signed-in account.
+     *
+     * @param userId - From the access token.
+     * @param provider - From the URL.
+     * @param body - `{ token, nonce? }`.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    link(userId: string, provider: string, body: SocialSignInInput, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * DELETE /auth/social/:provider — Disconnects the provider.
+     *
+     * @param userId - From the access token.
+     * @param provider - From the URL.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    unlink(userId: string, provider: string, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * @param provider - The :provider part of the URL.
+     * @returns The provider name, now known to be supported.
+     * @throws AuthError NOT_FOUND for any other value.
+     */
+    private parseProvider;
+}

package/dist/features/social/social.controller.js

@@ -0,0 +1,124 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialController = void 0;
+const common_1 = require("@nestjs/common");
+const auth_error_1 = require("../../common/auth-error.js");
+const strict_validation_pipe_1 = require("../../common/strict-validation.pipe.js");
+const request_context_1 = require("../../common/request-context.js");
+const constants_1 = require("../../constants.js");
+const auth_decorators_1 = require("../../guards/auth.decorators.js");
+const social_auth_service_1 = require("./social-auth.service");
+const social_dto_1 = require("./social.dto");
+const refresh_token_cookie_1 = require("../../common/refresh-token-cookie.js");
+/**
+ * Google, Apple and Facebook.
+ *
+ *   POST   /auth/social/:provider        sign in / sign up with the provider's token
+ *   POST   /auth/social/:provider/link   signed in: connect the provider to this account
+ *   DELETE /auth/social/:provider        signed in: disconnect it
+ *
+ * :provider is "google", "apple" or "facebook".
+ */
+let SocialController = class SocialController {
+    socialAuth;
+    constructor(socialAuth) {
+        this.socialAuth = socialAuth;
+    }
+    /**
+     * POST /auth/social/:provider — Signs in or signs up with the provider's token. Public.
+     *
+     * @param provider - From the URL.
+     * @param body - `{ token, nonce? }`, plus sign-up details for new accounts.
+     * @param request - Who is asking.
+     * @returns Tokens, or a 2FA challenge.
+     */
+    signIn(provider, body, request) {
+        return this.socialAuth.signInWithProvider(this.parseProvider(provider), body, request);
+    }
+    /**
+     * POST /auth/social/:provider/link — Connects the provider to the signed-in account.
+     *
+     * @param userId - From the access token.
+     * @param provider - From the URL.
+     * @param body - `{ token, nonce? }`.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    link(userId, provider, body, request) {
+        return this.socialAuth.linkProvider(userId, this.parseProvider(provider), body, request);
+    }
+    /**
+     * DELETE /auth/social/:provider — Disconnects the provider.
+     *
+     * @param userId - From the access token.
+     * @param provider - From the URL.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    unlink(userId, provider, request) {
+        return this.socialAuth.unlinkProvider(userId, this.parseProvider(provider), request);
+    }
+    /**
+     * @param provider - The :provider part of the URL.
+     * @returns The provider name, now known to be supported.
+     * @throws AuthError NOT_FOUND for any other value.
+     */
+    parseProvider(provider) {
+        if (!constants_1.SOCIAL_PROVIDERS.includes(provider))
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.notFound);
+        return provider;
+    }
+};
+exports.SocialController = SocialController;
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.social.signIn),
+    (0, auth_decorators_1.Public)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Param)(constants_1.ROUTE_PARAM.provider)),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, social_dto_1.SocialSignInInput, Object]),
+    __metadata("design:returntype", void 0)
+], SocialController.prototype, "signIn", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.social.link),
+    (0, auth_decorators_1.CheckSession)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __param(1, (0, common_1.Param)(constants_1.ROUTE_PARAM.provider)),
+    __param(2, (0, common_1.Body)()),
+    __param(3, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, social_dto_1.SocialSignInInput, Object]),
+    __metadata("design:returntype", void 0)
+], SocialController.prototype, "link", null);
+__decorate([
+    (0, common_1.Delete)(constants_1.ROUTES.social.unlink),
+    (0, auth_decorators_1.CheckSession)(),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __param(1, (0, common_1.Param)(constants_1.ROUTE_PARAM.provider)),
+    __param(2, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", void 0)
+], SocialController.prototype, "unlink", null);
+exports.SocialController = SocialController = __decorate([
+    (0, common_1.Controller)(constants_1.ROUTES.social.prefix),
+    (0, refresh_token_cookie_1.LibraryController)(),
+    (0, common_1.UsePipes)(strict_validation_pipe_1.strictValidationPipe),
+    __metadata("design:paramtypes", [social_auth_service_1.SocialAuthService])
+], SocialController);
+//# sourceMappingURL=social.controller.js.map

package/dist/features/social/social.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social.controller.js","sourceRoot":"","sources":["../../../src/features/social/social.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAuG;AACvG,oDAAgD;AAChD,4EAAuE;AACvE,8DAA0E;AAC1E,2CAAiF;AAEjF,8DAA+E;AAC/E,+DAA0D;AAC1D,6CAAiD;AACjD,wEAAkE;AAElE;;;;;;;;GAQG;AAII,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IACE;IAA7B,YAA6B,UAA6B;QAA7B,eAAU,GAAV,UAAU,CAAmB;IAAG,CAAC;IAE9D;;;;;;;OAOG;IAIH,MAAM,CAA8B,QAAgB,EAAU,IAAuB,EAAoB,OAAuB;QAC9H,OAAO,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;OAQG;IAIH,IAAI,CACe,MAAc,EACF,QAAgB,EACrC,IAAuB,EACb,OAAuB;QAEzC,OAAO,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3F,CAAC;IAED;;;;;;;OAOG;IAGH,MAAM,CAAkB,MAAc,EAA+B,QAAgB,EAAoB,OAAuB;QAC9H,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;IAED;;;;OAIG;IACK,aAAa,CAAC,QAAgB;QACpC,IAAI,CAAE,4BAAsC,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,sBAAS,CAAC,uBAAW,CAAC,QAAQ,CAAC,CAAC;QAC3G,OAAO,QAA0B,CAAC;IACpC,CAAC;CACF,CAAA;AA9DY,4CAAgB;AAc3B;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IAC1B,IAAA,wBAAM,GAAE;IACR,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IAChB,WAAA,IAAA,cAAK,EAAC,uBAAW,CAAC,QAAQ,CAAC,CAAA;IAAoB,WAAA,IAAA,aAAI,GAAE,CAAA;IAA2B,WAAA,IAAA,gCAAc,GAAE,CAAA;;6CAApC,8BAAiB;;8CAEpF;AAcD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IACxB,IAAA,8BAAY,GAAE;IACd,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IAErB,WAAA,IAAA,+BAAa,GAAE,CAAA;IACf,WAAA,IAAA,cAAK,EAAC,uBAAW,CAAC,QAAQ,CAAC,CAAA;IAC3B,WAAA,IAAA,aAAI,GAAE,CAAA;IACN,WAAA,IAAA,gCAAc,GAAE,CAAA;;qDADH,8BAAiB;;4CAIhC;AAYD;IAFC,IAAA,eAAM,EAAC,kBAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,IAAA,8BAAY,GAAE;IACP,WAAA,IAAA,+BAAa,GAAE,CAAA;IAAkB,WAAA,IAAA,cAAK,EAAC,uBAAW,CAAC,QAAQ,CAAC,CAAA;IAAoB,WAAA,IAAA,gCAAc,GAAE,CAAA;;;;8CAEvG;2BAnDU,gBAAgB;IAH5B,IAAA,mBAAU,EAAC,kBAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IAChC,IAAA,wCAAiB,GAAE;IACnB,IAAA,iBAAQ,EAAC,6CAAoB,CAAC;qCAEY,uCAAiB;GAD/C,gBAAgB,CA8D5B"}

package/dist/features/social/social.dto.d.ts

@@ -0,0 +1,11 @@
+import { SignUpDetailsInput } from '../passwordless/passwordless.dto.js';
+/**
+ * POST /auth/social/google | apple | facebook
+ * (and POST /auth/social/:provider/link for a signed-in user)
+ */
+export declare class SocialSignInInput extends SignUpDetailsInput {
+    /** Google / Apple: the ID token. Facebook: the user access token. */
+    token: string;
+    /** The raw nonce your app used in the provider request, if any. */
+    nonce?: string;
+}

package/dist/features/social/social.dto.js

@@ -0,0 +1,38 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialSignInInput = void 0;
+const class_validator_1 = require("class-validator");
+const constants_1 = require("../../constants.js");
+const passwordless_dto_1 = require("../passwordless/passwordless.dto.js");
+/**
+ * POST /auth/social/google | apple | facebook
+ * (and POST /auth/social/:provider/link for a signed-in user)
+ */
+class SocialSignInInput extends passwordless_dto_1.SignUpDetailsInput {
+    /** Google / Apple: the ID token. Facebook: the user access token. */
+    token;
+    /** The raw nonce your app used in the provider request, if any. */
+    nonce;
+}
+exports.SocialSignInInput = SocialSignInInput;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(constants_1.SOCIAL_TOKEN_INPUT_MAX_LENGTH),
+    __metadata("design:type", String)
+], SocialSignInInput.prototype, "token", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(constants_1.NONCE_INPUT_MAX_LENGTH),
+    __metadata("design:type", String)
+], SocialSignInInput.prototype, "nonce", void 0);
+//# sourceMappingURL=social.dto.js.map

package/dist/features/social/social.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social.dto.js","sourceRoot":"","sources":["../../../src/features/social/social.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDAAkE;AAClE,2CAAoF;AACpF,+EAA8E;AAE9E;;;GAGG;AACH,MAAa,iBAAkB,SAAQ,qCAAkB;IACvD,qEAAqE;IAErE,KAAK,CAAS;IAEd,mEAAmE;IAEnE,KAAK,CAAU;CAChB;AARD,8CAQC;AALC;IADC,IAAA,0BAAQ,GAAE;IAAE,IAAA,2BAAS,EAAC,yCAA6B,CAAC;;gDACvC;AAId;IADC,IAAA,4BAAU,GAAE;IAAE,IAAA,0BAAQ,GAAE;IAAE,IAAA,2BAAS,EAAC,kCAAsB,CAAC;;gDAC7C"}

package/dist/features/two-factor/two-factor.controller.d.ts

@@ -0,0 +1,84 @@
+import { RequestContext } from '../../common/request-context.js';
+import { AccessTokenClaims } from '../sessions/session.types.js';
+import { UsersService } from '../users/users.service.js';
+import { TwoFactorCodeInput, VerifyTwoFactorChallengeInput } from './two-factor.dto';
+import { TwoFactorService } from './two-factor.service';
+/**
+ * Two-factor authentication (authenticator app + backup codes).
+ *
+ *   GET  /auth/2fa                 is it on? how many backup codes are left?
+ *   POST /auth/2fa/setup           start: get the secret and QR-code URL
+ *   POST /auth/2fa/enable          finish: first code -> backup codes
+ *   POST /auth/2fa/disable         turn off (needs a code)
+ *   POST /auth/2fa/backup-codes    new backup codes (needs a code)
+ *   POST /auth/2fa/verify          second step of sign-in
+ */
+export declare class TwoFactorController {
+    private readonly twoFactor;
+    private readonly users;
+    constructor(twoFactor: TwoFactorService, users: UsersService);
+    /**
+     * GET /auth/2fa — Is 2FA on for the signed-in user, and how many backup codes are left?
+     *
+     * @param userId - From the access token.
+     * @returns `{ isEnabled, remainingBackupCodes }`.
+     */
+    getStatus(userId: string): Promise<{
+        success: boolean;
+        isEnabled: boolean;
+        remainingBackupCodes: number;
+    }>;
+    /**
+     * POST /auth/2fa/setup — Starts setup and returns the secret and QR-code URL.
+     *
+     * @param userId - From the access token.
+     * @returns See `TwoFactorService.startSetup`.
+     */
+    startSetup(userId: string): Promise<{
+        success: true;
+        secret: string;
+        authenticatorAppUrl: string;
+    }>;
+    /**
+     * POST /auth/2fa/enable — Confirms setup with the first code and returns backup codes.
+     *
+     * @param user - The access token's claims (user id and session id).
+     * @param body - `{ code }`.
+     * @param request - Who is asking.
+     * @returns See `TwoFactorService.confirmSetup`.
+     */
+    enable(user: AccessTokenClaims, body: TwoFactorCodeInput, request: RequestContext): Promise<{
+        success: true;
+        backupCodes: string[];
+    }>;
+    /**
+     * POST /auth/2fa/disable — Turns 2FA off.
+     *
+     * @param userId - From the access token.
+     * @param body - `{ code }`: an authenticator or backup code.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    disable(userId: string, body: TwoFactorCodeInput, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * POST /auth/2fa/backup-codes — Replaces all backup codes.
+     *
+     * @param userId - From the access token.
+     * @param body - `{ code }`: an authenticator or backup code.
+     * @returns The new backup codes.
+     */
+    regenerateBackupCodes(userId: string, body: TwoFactorCodeInput): Promise<{
+        success: true;
+        backupCodes: string[];
+    }>;
+    /**
+     * POST /auth/2fa/verify — The second step of sign-in. Public: the caller has no tokens yet.
+     *
+     * @param body - `{ challengeToken, code }`.
+     * @param request - Who is asking.
+     * @returns Access and refresh tokens.
+     */
+    verify(body: VerifyTwoFactorChallengeInput, request: RequestContext): Promise<import("../..").SignedInResult>;
+}