@appweaver/core 1.2.1 → 1.3.0

package/security/oauth2/oauth2-apple.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2Apple = void 0;
+exports.extractAppleUser = extractAppleUser;
+const common_1 = require("@appweaver/common");
+const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
+exports.oauth2Apple = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Apple, {
+    enabled: common_1.config.SECURITY_OAUTH2_APPLE_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_APPLE_CLIENT_ID,
+    // Resolved lazily so the signing key is only read when the provider is actually enabled.
+    clientSecret: oauth2_util_1.createAppleClientSecret,
+    scope: ['name', 'email'],
+    // Requesting the name or email scope makes Apple post the authorization response as a form body.
+    formPostCallback: true,
+    // Apple's token endpoint rejects HTTP Basic credentials.
+    authorizationMethod: 'body',
+    extractUserInfo: (_accessToken, context) => extractAppleUser(context)
+});
+/**
+ * Builds the user info from Apple's token response. Apple has no user info endpoint: the identity is carried by the
+ * `id_token`, and the display name is posted alongside the authorization code on the very first authorization only.
+ *
+ * @param {OAuth2UserInfoContext} context - The token set and callback request from the authorization code flow.
+ * @return {Promise<UserInfo>} A promise resolving to the extracted user info.
+ */
+async function extractAppleUser({ token, request }) {
+    const claims = (0, oauth2_util_1.decodeJwtPayload)('Apple', token.id_token);
+    const name = parseAppleFormUser(request.body)?.name;
+    return {
+        id: claims.sub,
+        email: (0, oauth2_util_1.requireEmail)('Apple', claims.email),
+        firstName: name?.firstName ?? '',
+        lastName: name?.lastName ?? ''
+    };
+}
+/**
+ * Parses the JSON encoded `user` field Apple posts to the callback on the first authorization. Malformed values are
+ * logged and ignored, since the rest of the identity comes from the identity token.
+ *
+ * @param {unknown} body - The parsed form body of the callback request.
+ * @return {AppleFormUser | undefined} The decoded profile, or `undefined` when it is absent or unreadable.
+ */
+function parseAppleFormUser(body) {
+    const raw = body?.user;
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        common_1.logger.debug({ err: e }, 'Apple OAuth2 user payload is malformed');
+        return undefined;
+    }
+}

package/security/oauth2/oauth2-custom.d.ts

@@ -1,8 +1,10 @@
+import { UserInfo } from '../../types';
 export type OAuth2UserInfo = {
     sub: string;
-    email: string;
-    given_name: string;
-    family_name: string;
+    email?: string;
+    given_name?: string;
+    family_name?: string;
     picture?: string;
 };
-export declare const oauth2Custom: (server: import("../..").Server) => Promise<void>;
+export declare const oauth2Custom: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchCustomUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-custom.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oauth2Custom = void 0;
+exports.fetchCustomUser = fetchCustomUser;
 const common_1 = require("@appweaver/common");
 const context_1 = require("../../context");
 const errors_1 = require("../../errors");
 const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
 exports.oauth2Custom = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Custom, {
     enabled: common_1.config.SECURITY_OAUTH2_CUSTOM_ENABLED,
     clientId: common_1.config.SECURITY_OAUTH2_CUSTOM_CLIENT_ID,
@@ -25,17 +27,13 @@ async function fetchCustomUser(accessToken) {
     }
     else {
         // Fallback to direct API call if the plugin is not initialized
-        const resp = await fetch(`${common_1.config.SECURITY_OAUTH2_CUSTOM_ISSUER}/protocol/openid-connect/userinfo`, { method: 'GET', headers: { authorization: `Bearer ${accessToken}` } });
-        if (!resp.ok) {
-            throw new errors_1.HttpError(`Custom OAuth2 API error: ${resp.status} ${resp.statusText}`, 500);
-        }
-        data = await resp.json();
+        data = await (0, oauth2_util_1.fetchUserInfo)('Custom OAuth2', `${common_1.config.SECURITY_OAUTH2_CUSTOM_ISSUER}/protocol/openid-connect/userinfo`, accessToken);
     }
     return {
         id: data.sub,
-        email: data.email,
-        firstName: data.given_name,
-        lastName: data.family_name,
+        email: (0, oauth2_util_1.requireEmail)('Custom OAuth2', data.email),
+        firstName: data.given_name ?? '',
+        lastName: data.family_name ?? '',
         avatarUrl: data.picture
     };
 }

package/security/oauth2/oauth2-facebook.d.ts

@@ -1 +1,3 @@
-export declare const oauth2Facebook: (server: import("../..").Server) => Promise<void>;
+import { UserInfo } from '../../types';
+export declare const oauth2Facebook: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchFacebookUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-facebook.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oauth2Facebook = void 0;
+exports.fetchFacebookUser = fetchFacebookUser;
 const common_1 = require("@appweaver/common");
-const errors_1 = require("../../errors");
 const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
 exports.oauth2Facebook = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Facebook, {
     enabled: common_1.config.SECURITY_OAUTH2_FACEBOOK_ENABLED,
     clientId: common_1.config.SECURITY_OAUTH2_FACEBOOK_CLIENT_ID,
@@ -14,18 +15,11 @@ exports.oauth2Facebook = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1
 async function fetchFacebookUser(accessToken) {
     const params = new URLSearchParams();
     params.append('fields', 'id,name,email,picture.width(512)');
-    params.append('access_token', accessToken);
-    const resp = await fetch(`${common_1.config.SECURITY_OAUTH2_FACEBOOK_USER_INFO_URL}?${params}`, { method: 'GET' });
-    if (!resp.ok) {
-        throw new errors_1.HttpError(`Facebook Graph API error: ${resp.status} ${resp.statusText}`, 500);
-    }
-    const data = await resp.json();
-    const [firstName, lastName] = data.name.split(' ');
+    const data = await (0, oauth2_util_1.fetchUserInfo)('Facebook Graph', `${common_1.config.SECURITY_OAUTH2_FACEBOOK_USER_INFO_URL}?${params}`, accessToken);
     return {
         id: data.id,
-        email: data.email,
-        firstName,
-        lastName,
+        email: (0, oauth2_util_1.requireEmail)('Facebook', data.email),
+        ...(0, oauth2_util_1.splitFullName)(data.name),
         avatarUrl: data.picture?.data?.url
     };
 }

package/security/oauth2/oauth2-github.d.ts

@@ -0,0 +1,3 @@
+import { UserInfo } from '../../types';
+export declare const oauth2Github: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchGithubUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-github.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2Github = void 0;
+exports.fetchGithubUser = fetchGithubUser;
+const common_1 = require("@appweaver/common");
+const errors_1 = require("../../errors");
+const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
+const GITHUB_HEADERS = {
+    accept: 'application/vnd.github+json',
+    'x-github-api-version': '2022-11-28',
+    'user-agent': 'appweaver'
+};
+exports.oauth2Github = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Github, {
+    enabled: common_1.config.SECURITY_OAUTH2_GITHUB_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_GITHUB_CLIENT_ID,
+    clientSecret: common_1.config.SECURITY_OAUTH2_GITHUB_CLIENT_SECRET,
+    displayName: 'GitHub',
+    scope: ['read:user', 'user:email'],
+    extractUserInfo: (accessToken) => fetchGithubUser(accessToken)
+});
+async function fetchGithubUser(accessToken) {
+    const data = await (0, oauth2_util_1.fetchUserInfo)('GitHub', common_1.config.SECURITY_OAUTH2_GITHUB_USER_INFO_URL, accessToken, GITHUB_HEADERS);
+    return {
+        id: String(data.id),
+        email: data.email ?? (await fetchGithubEmail(accessToken)),
+        ...(0, oauth2_util_1.splitFullName)(data.name ?? data.login),
+        avatarUrl: data.avatar_url
+    };
+}
+/**
+ * Resolves the user's email address from the dedicated emails endpoint, needed because GitHub omits it from the user
+ * profile whenever the address is kept private.
+ *
+ * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @return {Promise<string>} A promise resolving to the primary verified address, or the first verified one.
+ * @throws {HttpError} If the account has no verified email address.
+ */
+async function fetchGithubEmail(accessToken) {
+    const emails = await (0, oauth2_util_1.fetchUserInfo)('GitHub', `${common_1.config.SECURITY_OAUTH2_GITHUB_USER_INFO_URL}/emails`, accessToken, GITHUB_HEADERS);
+    const verified = emails.filter((email) => email.verified);
+    const email = verified.find((email) => email.primary) ?? verified[0];
+    if (!email) {
+        throw new errors_1.HttpError('GitHub account has no verified email address', 403);
+    }
+    return email.email;
+}

package/security/oauth2/oauth2-gitlab.d.ts

@@ -0,0 +1,3 @@
+import { UserInfo } from '../../types';
+export declare const oauth2Gitlab: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchGitlabUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-gitlab.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2Gitlab = void 0;
+exports.fetchGitlabUser = fetchGitlabUser;
+const common_1 = require("@appweaver/common");
+const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
+const baseUrl = common_1.config.SECURITY_OAUTH2_GITLAB_BASE_URL.replace(/\/$/, '');
+exports.oauth2Gitlab = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Gitlab, {
+    enabled: common_1.config.SECURITY_OAUTH2_GITLAB_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_GITLAB_CLIENT_ID,
+    clientSecret: common_1.config.SECURITY_OAUTH2_GITLAB_CLIENT_SECRET,
+    displayName: 'GitLab',
+    scope: ['read_user'],
+    // Built from the base URL rather than the bundled preset, so self-managed instances work too.
+    auth: {
+        authorizeHost: baseUrl,
+        authorizePath: '/oauth/authorize',
+        tokenHost: baseUrl,
+        tokenPath: '/oauth/token',
+        revokePath: '/oauth/revoke'
+    },
+    extractUserInfo: (accessToken) => fetchGitlabUser(accessToken)
+});
+async function fetchGitlabUser(accessToken) {
+    const data = await (0, oauth2_util_1.fetchUserInfo)('GitLab', common_1.config.SECURITY_OAUTH2_GITLAB_USER_INFO_URL, accessToken);
+    return {
+        id: String(data.id),
+        email: (0, oauth2_util_1.requireEmail)('GitLab', data.email),
+        ...(0, oauth2_util_1.splitFullName)(data.name ?? data.username),
+        avatarUrl: data.avatar_url
+    };
+}

package/security/oauth2/oauth2-google.d.ts

@@ -1 +1,3 @@
-export declare const oauth2Google: (server: import("../..").Server) => Promise<void>;
+import { UserInfo } from '../../types';
+export declare const oauth2Google: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchGoogleUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-google.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oauth2Google = void 0;
+exports.fetchGoogleUser = fetchGoogleUser;
 const common_1 = require("@appweaver/common");
-const errors_1 = require("../../errors");
 const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
 exports.oauth2Google = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Google, {
     enabled: common_1.config.SECURITY_OAUTH2_GOOGLE_ENABLED,
     clientId: common_1.config.SECURITY_OAUTH2_GOOGLE_CLIENT_ID,
@@ -12,18 +13,12 @@ exports.oauth2Google = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.A
     extractUserInfo: (accessToken) => fetchGoogleUser(accessToken)
 });
 async function fetchGoogleUser(accessToken) {
-    const params = new URLSearchParams();
-    params.append('access_token', accessToken);
-    const resp = await fetch(`${common_1.config.SECURITY_OAUTH2_GOOGLE_USER_INFO_URL}?${params}`, { method: 'GET' });
-    if (!resp.ok) {
-        throw new errors_1.HttpError(`Google API error: ${resp.status} ${resp.statusText}`, 500);
-    }
-    const data = await resp.json();
+    const data = await (0, oauth2_util_1.fetchUserInfo)('Google', common_1.config.SECURITY_OAUTH2_GOOGLE_USER_INFO_URL, accessToken);
     return {
         id: data.id,
-        email: data.email,
-        firstName: data.given_name,
-        lastName: data.family_name,
+        email: (0, oauth2_util_1.requireEmail)('Google', data.email),
+        firstName: data.given_name ?? '',
+        lastName: data.family_name ?? '',
         avatarUrl: data.picture
     };
 }

package/security/oauth2/oauth2-linkedin.d.ts

@@ -0,0 +1,3 @@
+import { UserInfo } from '../../types';
+export declare const oauth2Linkedin: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchLinkedinUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-linkedin.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2Linkedin = void 0;
+exports.fetchLinkedinUser = fetchLinkedinUser;
+const common_1 = require("@appweaver/common");
+const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
+exports.oauth2Linkedin = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Linkedin, {
+    enabled: common_1.config.SECURITY_OAUTH2_LINKEDIN_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_LINKEDIN_CLIENT_ID,
+    clientSecret: common_1.config.SECURITY_OAUTH2_LINKEDIN_CLIENT_SECRET,
+    displayName: 'LinkedIn',
+    scope: ['openid', 'profile', 'email'],
+    // LinkedIn's token endpoint rejects HTTP Basic credentials.
+    authorizationMethod: 'body',
+    extractUserInfo: (accessToken) => fetchLinkedinUser(accessToken)
+});
+async function fetchLinkedinUser(accessToken) {
+    const data = await (0, oauth2_util_1.fetchUserInfo)('LinkedIn', common_1.config.SECURITY_OAUTH2_LINKEDIN_USER_INFO_URL, accessToken);
+    const { firstName, lastName } = (0, oauth2_util_1.splitFullName)(data.name);
+    return {
+        id: data.sub,
+        email: (0, oauth2_util_1.requireEmail)('LinkedIn', data.email),
+        firstName: data.given_name ?? firstName,
+        lastName: data.family_name ?? lastName,
+        avatarUrl: data.picture
+    };
+}

package/security/oauth2/oauth2-microsoft.d.ts

@@ -0,0 +1,3 @@
+import { UserInfo } from '../../types';
+export declare const oauth2Microsoft: (server: import("../../types").Server) => Promise<void>;
+export declare function fetchMicrosoftUser(accessToken: string): Promise<UserInfo>;

package/security/oauth2/oauth2-microsoft.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2Microsoft = void 0;
+exports.fetchMicrosoftUser = fetchMicrosoftUser;
+const common_1 = require("@appweaver/common");
+const create_oauth2_plugin_1 = require("./create-oauth2-plugin");
+const oauth2_util_1 = require("./oauth2-util");
+const tenant = common_1.config.SECURITY_OAUTH2_MICROSOFT_TENANT;
+exports.oauth2Microsoft = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2Microsoft, {
+    enabled: common_1.config.SECURITY_OAUTH2_MICROSOFT_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_MICROSOFT_CLIENT_ID,
+    clientSecret: common_1.config.SECURITY_OAUTH2_MICROSOFT_CLIENT_SECRET,
+    scope: ['openid', 'profile', 'email', 'User.Read'],
+    // Built from the configured tenant rather than the bundled preset, which is hardcoded to `common`.
+    auth: {
+        authorizeHost: 'https://login.microsoftonline.com',
+        authorizePath: `/${tenant}/oauth2/v2.0/authorize`,
+        tokenHost: 'https://login.microsoftonline.com',
+        tokenPath: `/${tenant}/oauth2/v2.0/token`
+    },
+    extractUserInfo: (accessToken) => fetchMicrosoftUser(accessToken)
+});
+async function fetchMicrosoftUser(accessToken) {
+    const userInfoUrl = common_1.config.SECURITY_OAUTH2_MICROSOFT_USER_INFO_URL;
+    const data = await (0, oauth2_util_1.fetchUserInfo)('Microsoft', userInfoUrl, accessToken);
+    const { firstName, lastName } = (0, oauth2_util_1.splitFullName)(data.displayName);
+    return {
+        id: data.id,
+        // Work accounts expose `mail`, personal ones only the principal name.
+        email: (0, oauth2_util_1.requireEmail)('Microsoft', data.mail ?? data.userPrincipalName),
+        firstName: data.givenName ?? firstName,
+        lastName: data.surname ?? lastName,
+        // Microsoft Graph serves the photo as authenticated binary content, so it has to be downloaded here.
+        avatarFile: await (0, oauth2_util_1.fetchAuthenticatedAvatar)(`${userInfoUrl}/photo/$value`, accessToken, data.id)
+    };
+}

package/security/oauth2/oauth2-schema.d.ts

@@ -2,9 +2,16 @@ import { RouteSchema } from '@appweaver/common';
 export declare const OAuth2RedirectQuery: import("@sinclair/typebox").TObject<{
     redirectToUrl: import("@sinclair/typebox").TString;
 }>;
-export declare const OAuth2CallbackQuery: import("@sinclair/typebox").TObject<{
+export declare const OAuth2CallbackRequest: import("@sinclair/typebox").TObject<{
     code: import("@sinclair/typebox").TString;
     state: import("@sinclair/typebox").TString;
+    id_token: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    user: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 export declare function createOAuth2RedirectSchema(providerName: string): RouteSchema;
-export declare function createOAuth2CallbackSchema(providerName: string): RouteSchema;
+/**
+ * @param {string} providerName - Human-readable provider name used in the summary and description.
+ * @param {boolean} [formPost] - Whether the provider returns the authorization response as a form body
+ * (`response_mode=form_post`) instead of query parameters.
+ */
+export declare function createOAuth2CallbackSchema(providerName: string, formPost?: boolean): RouteSchema;

package/security/oauth2/oauth2-schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAuth2CallbackQuery = exports.OAuth2RedirectQuery = void 0;
+exports.OAuth2CallbackRequest = exports.OAuth2RedirectQuery = void 0;
 exports.createOAuth2RedirectSchema = createOAuth2RedirectSchema;
 exports.createOAuth2CallbackSchema = createOAuth2CallbackSchema;
 const typebox_1 = require("@sinclair/typebox");
@@ -14,7 +14,7 @@ exports.OAuth2RedirectQuery = typebox_1.Type.Object({
         example: 'https://example.com/login/handler'
     })
 });
-exports.OAuth2CallbackQuery = typebox_1.Type.Object({
+exports.OAuth2CallbackRequest = typebox_1.Type.Object({
     code: typebox_1.Type.String({
         description: 'Authorization code from OAuth2 provider',
         example: '3b7bdc9982feac0e20cf4ddc9be52a1a027142e25b4d14c1b5a280595bc20'
@@ -22,8 +22,15 @@ exports.OAuth2CallbackQuery = typebox_1.Type.Object({
     state: typebox_1.Type.String({
         description: 'Authorization state returned from OAuth2 provider',
         example: '89bbb34d76801fcf8251193a02a1d62c7c87a'
-    })
-});
+    }),
+    id_token: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: 'OpenID Connect identity token carrying the user claims'
+    })),
+    user: typebox_1.Type.Optional(typebox_1.Type.String({
+        description: 'JSON encoded user profile, sent by Apple only on the first authorization',
+        example: '{"name":{"firstName":"Ada","lastName":"Lovelace"}}'
+    }))
+}, { additionalProperties: true });
 function createOAuth2RedirectSchema(providerName) {
     return {
         tags: ['Auth'],
@@ -37,12 +44,19 @@ function createOAuth2RedirectSchema(providerName) {
         }
     };
 }
-function createOAuth2CallbackSchema(providerName) {
+/**
+ * @param {string} providerName - Human-readable provider name used in the summary and description.
+ * @param {boolean} [formPost] - Whether the provider returns the authorization response as a form body
+ * (`response_mode=form_post`) instead of query parameters.
+ */
+function createOAuth2CallbackSchema(providerName, formPost = false) {
     return {
         tags: ['Auth'],
         summary: `Authenticate identity from ${providerName} callback`,
         description: `Authenticate identity from ${providerName} callback`,
-        querystring: exports.OAuth2CallbackQuery,
+        ...(formPost
+            ? { body: exports.OAuth2CallbackRequest }
+            : { querystring: exports.OAuth2CallbackRequest }),
         response: {
             302: {
                 description: `Redirect to 'redirectToUrl' provided when initiating OAuth2 authentication`

package/security/oauth2/oauth2-service.d.ts

@@ -0,0 +1,58 @@
+import { AuthSource, AuthUser } from '@appweaver/common';
+import { ConnectedAccount, UserInfo } from '../../types';
+/**
+ * Handles the parts of authentication that only apply to OAuth2 sign-ins: the application's own admission check, the
+ * links between provider accounts and local users, and the rule deciding when a sign-in has to be confirmed with the
+ * account password.
+ */
+export declare class OAuth2Service {
+    /**
+     * Checks whether a user is allowed to be registered and/or authenticated via OAuth2 by invoking the optional
+     * `checkOAuth2User` callback configured on the auth service. When the callback returns nothing, the OAuth2 flow
+     * proceeds normally (registration of a new user or login of an existing one). When it returns a string or an error,
+     * the flow is aborted by throwing an `HttpError`.
+     *
+     * @param {AuthSource} source - The OAuth2 authentication source, e.g., oauth2Google, oauth2Facebook, oauth2Custom.
+     * @param {UserInfo} userInfo - The user info extracted from the OAuth2 provider.
+     * @param {AuthUser | null} authUser - The existing authenticated user matched by email, or null when the user does
+     * not exist yet (i.e., a new user would be registered).
+     * @return {Promise<void>} A promise that resolves when the user is allowed to proceed.
+     * @throws {HttpError} If the configured callback returns a string or an error (status 403 unless an `HttpError` is
+     * returned, in which case it is thrown as-is).
+     */
+    checkUser(source: AuthSource, userInfo: UserInfo, authUser: AuthUser | null): Promise<void>;
+    /**
+     * Decides whether an OAuth2 sign-in has to be confirmed with the account password before it is honored. This is the
+     * case the first time a provider account is linked to an existing user that already has a password, since anyone
+     * able to create a provider account carrying that email address could otherwise take the account over. The rule is
+     * not configurable: turning it off would hand over every password-protected account to whoever can present a
+     * matching address.
+     *
+     * @param {AuthUser} authUser - The local user matched by email address.
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @return {Promise<boolean>} A promise resolving to true when the password has to be confirmed.
+     */
+    requiresPasswordConfirmation(authUser: AuthUser, source: AuthSource, providerAccountId: string): Promise<boolean>;
+    /**
+     * Finds the connected account linking an OAuth2 provider account to a local user.
+     *
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @return {Promise<ConnectedAccount | null>} A promise resolving to the link, or null when the provider account is
+     * unknown or connected accounts are not being tracked.
+     */
+    findConnectedAccount(source: AuthSource, providerAccountId: string): Promise<ConnectedAccount | null>;
+    /**
+     * Records a successful OAuth2 sign-in, creating the link on the first one and refreshing it afterward. Does nothing
+     * when connected accounts are not being tracked.
+     *
+     * @param {AuthUser} authUser - The local user the provider account belongs to.
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @param {string} [scope] - The scopes granted by the provider.
+     * @return {Promise<void>} A promise that resolves once the link is stored.
+     * @throws {HttpError} If the provider account is already linked to a different user.
+     */
+    linkConnectedAccount(authUser: AuthUser, source: AuthSource, providerAccountId: string, scope?: string): Promise<void>;
+}

package/security/oauth2/oauth2-service.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuth2Service = void 0;
+const common_1 = require("@appweaver/common");
+const context_1 = require("../../context");
+const errors_1 = require("../../errors");
+const helper_1 = require("../helper");
+/**
+ * Handles the parts of authentication that only apply to OAuth2 sign-ins: the application's own admission check, the
+ * links between provider accounts and local users, and the rule deciding when a sign-in has to be confirmed with the
+ * account password.
+ */
+class OAuth2Service {
+    /** @internal */
+    _authUserService = (0, helper_1.resourceAuthService)();
+    /** Optional, since an application with no OAuth2 provider never registers it.
+     * @internal */
+    _connectedAccountService = (0, context_1.injectService)('ConnectedAccount', false);
+    /**
+     * Checks whether a user is allowed to be registered and/or authenticated via OAuth2 by invoking the optional
+     * `checkOAuth2User` callback configured on the auth service. When the callback returns nothing, the OAuth2 flow
+     * proceeds normally (registration of a new user or login of an existing one). When it returns a string or an error,
+     * the flow is aborted by throwing an `HttpError`.
+     *
+     * @param {AuthSource} source - The OAuth2 authentication source, e.g., oauth2Google, oauth2Facebook, oauth2Custom.
+     * @param {UserInfo} userInfo - The user info extracted from the OAuth2 provider.
+     * @param {AuthUser | null} authUser - The existing authenticated user matched by email, or null when the user does
+     * not exist yet (i.e., a new user would be registered).
+     * @return {Promise<void>} A promise that resolves when the user is allowed to proceed.
+     * @throws {HttpError} If the configured callback returns a string or an error (status 403 unless an `HttpError` is
+     * returned, in which case it is thrown as-is).
+     */
+    async checkUser(source, userInfo, authUser) {
+        const serviceConfig = this._authUserService[common_1.CONFIG];
+        if (!serviceConfig.checkOAuth2User) {
+            return;
+        }
+        const result = await serviceConfig.checkOAuth2User(source, userInfo, authUser);
+        if (!result) {
+            return;
+        }
+        if (result instanceof errors_1.HttpError) {
+            throw result;
+        }
+        throw new errors_1.HttpError(result instanceof Error ? result.message : result, 403, result instanceof Error ? result : undefined);
+    }
+    /**
+     * Decides whether an OAuth2 sign-in has to be confirmed with the account password before it is honored. This is the
+     * case the first time a provider account is linked to an existing user that already has a password, since anyone
+     * able to create a provider account carrying that email address could otherwise take the account over. The rule is
+     * not configurable: turning it off would hand over every password-protected account to whoever can present a
+     * matching address.
+     *
+     * @param {AuthUser} authUser - The local user matched by email address.
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @return {Promise<boolean>} A promise resolving to true when the password has to be confirmed.
+     */
+    async requiresPasswordConfirmation(authUser, source, providerAccountId) {
+        if (!authUser.passwordHash) {
+            return false;
+        }
+        // Without the link table there is nothing to remember a previous confirmation, so asking every time is the only
+        // way to keep the guarantee.
+        if (!this._connectedAccountService) {
+            return true;
+        }
+        const account = await this.findConnectedAccount(source, providerAccountId);
+        return !account || this.connectedAccountOwnerId(account) !== authUser.id;
+    }
+    /**
+     * Finds the connected account linking an OAuth2 provider account to a local user.
+     *
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @return {Promise<ConnectedAccount | null>} A promise resolving to the link, or null when the provider account is
+     * unknown or connected accounts are not being tracked.
+     */
+    async findConnectedAccount(source, providerAccountId) {
+        const service = this._connectedAccountService;
+        if (!service) {
+            return null;
+        }
+        try {
+            const result = await service.query({
+                provider: source,
+                providerAccountId
+            });
+            return result.items[0] ?? null;
+        }
+        catch (e) {
+            throw new errors_1.HttpError('Connected account find error', 500, e);
+        }
+    }
+    /**
+     * Records a successful OAuth2 sign-in, creating the link on the first one and refreshing it afterward. Does nothing
+     * when connected accounts are not being tracked.
+     *
+     * @param {AuthUser} authUser - The local user the provider account belongs to.
+     * @param {AuthSource} source - The OAuth2 authentication source.
+     * @param {string} providerAccountId - The user identifier reported by the provider.
+     * @param {string} [scope] - The scopes granted by the provider.
+     * @return {Promise<void>} A promise that resolves once the link is stored.
+     * @throws {HttpError} If the provider account is already linked to a different user.
+     */
+    async linkConnectedAccount(authUser, source, providerAccountId, scope) {
+        const service = this._connectedAccountService;
+        if (!service) {
+            return;
+        }
+        const account = await this.findConnectedAccount(source, providerAccountId);
+        if (account && this.connectedAccountOwnerId(account) !== authUser.id) {
+            throw new errors_1.HttpError('This provider account is already linked to another user', 403);
+        }
+        try {
+            if (account) {
+                await service.update(account.id, { scope, lastLoginAt: new Date() });
+                return;
+            }
+            await service.create({
+                provider: source,
+                providerAccountId,
+                scope,
+                lastLoginAt: new Date(),
+                [(0, common_1.uncapitalize)(this._authUserService.modelName)]: { id: authUser.id }
+            });
+            common_1.logger.debug({ id: authUser.id, source }, 'OAuth2 provider account linked');
+        }
+        catch (e) {
+            throw new errors_1.HttpError('Connected account link error', 500, e);
+        }
+    }
+    /**
+     * Reads the owning user id off a link, which the generated model exposes as a `<authModel>Id` foreign key.
+     *
+     * @internal
+     */
+    connectedAccountOwnerId(account) {
+        return account[`${(0, common_1.uncapitalize)(this._authUserService.modelName)}Id`];
+    }
+}
+exports.OAuth2Service = OAuth2Service;