@appweaver/core 1.2.0 → 1.3.0

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

@@ -0,0 +1,60 @@
+import { AvatarFile } from '../../types';
+/**
+ * Calls an OAuth2 provider's user info endpoint with the access token and returns the parsed JSON body.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} url - The user info endpoint to call.
+ * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {Record<string, string>} [headers] - Extra request headers required by the provider.
+ * @return {Promise<T>} A promise resolving to the parsed response body.
+ * @throws {HttpError} If the provider responds with a non-2xx status.
+ */
+export declare function fetchUserInfo<T>(providerName: string, url: string, accessToken: string, headers?: Record<string, string>): Promise<T>;
+/**
+ * Downloads an avatar image that is only reachable with the provider's access token, so it cannot be resolved later
+ * from a plain URL. Fetching is best-effort and returns `undefined` on any failure.
+ *
+ * @param {string} url - The avatar endpoint to call.
+ * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {string} id - The provider's user identifier, used to name the file.
+ * @return {Promise<AvatarFile | undefined>} A promise resolving to the downloaded avatar, or `undefined`.
+ */
+export declare function fetchAuthenticatedAvatar(url: string, accessToken: string, id: string): Promise<AvatarFile | undefined>;
+/**
+ * Splits a provider's single display name field into a first and last name. Everything after the first whitespace
+ * separated word becomes the last name, so multipart surnames are kept intact.
+ *
+ * @param {string} [fullName] - The full name reported by the provider.
+ * @return {{ firstName: string; lastName: string }} The split name parts, empty strings when no name is available.
+ */
+export declare function splitFullName(fullName?: string): {
+    firstName: string;
+    lastName: string;
+};
+/**
+ * Asserts that the provider returned an email address, which the framework needs to match or register the user.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} [email] - The email address reported by the provider.
+ * @return {string} The email address.
+ * @throws {HttpError} If the provider did not return an email address.
+ */
+export declare function requireEmail(providerName: string, email?: string): string;
+/**
+ * Decodes the payload of a JWT without verifying its signature. Only safe for tokens received directly from a
+ * provider's token endpoint over TLS, which OpenID Connect Core 3.1.3.7 explicitly allows.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} [token] - The JWT to decode.
+ * @return {T} The decoded payload.
+ * @throws {HttpError} If the token is missing or is not a well-formed JWT.
+ */
+export declare function decodeJwtPayload<T>(providerName: string, token?: string): T;
+/**
+ * Builds the client secret Apple expects: a short-lived ES256 JWT signed with the team's `.p8` key. A literally
+ * configured `SECURITY_OAUTH2_APPLE_CLIENT_SECRET` is used as-is and takes precedence.
+ *
+ * @return {string} The Apple client secret.
+ * @throws {Error} If neither a literal secret nor a complete signing key configuration is available.
+ */
+export declare function createAppleClientSecret(): string;

package/security/oauth2/oauth2-util.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchUserInfo = fetchUserInfo;
+exports.fetchAuthenticatedAvatar = fetchAuthenticatedAvatar;
+exports.splitFullName = splitFullName;
+exports.requireEmail = requireEmail;
+exports.decodeJwtPayload = decodeJwtPayload;
+exports.createAppleClientSecret = createAppleClientSecret;
+const fs = __importStar(require("node:fs"));
+const crypto = __importStar(require("node:crypto"));
+const common_1 = require("@appweaver/common");
+const errors_1 = require("../../errors");
+const APPLE_TOKEN_AUDIENCE = 'https://appleid.apple.com';
+/**
+ * Calls an OAuth2 provider's user info endpoint with the access token and returns the parsed JSON body.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} url - The user info endpoint to call.
+ * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {Record<string, string>} [headers] - Extra request headers required by the provider.
+ * @return {Promise<T>} A promise resolving to the parsed response body.
+ * @throws {HttpError} If the provider responds with a non-2xx status.
+ */
+async function fetchUserInfo(providerName, url, accessToken, headers = {}) {
+    const resp = await fetch(url, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${accessToken}`, ...headers }
+    });
+    if (!resp.ok) {
+        throw new errors_1.HttpError(`${providerName} API error: ${resp.status} ${resp.statusText}`, 500);
+    }
+    return resp.json();
+}
+/**
+ * Downloads an avatar image that is only reachable with the provider's access token, so it cannot be resolved later
+ * from a plain URL. Fetching is best-effort and returns `undefined` on any failure.
+ *
+ * @param {string} url - The avatar endpoint to call.
+ * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {string} id - The provider's user identifier, used to name the file.
+ * @return {Promise<AvatarFile | undefined>} A promise resolving to the downloaded avatar, or `undefined`.
+ */
+async function fetchAuthenticatedAvatar(url, accessToken, id) {
+    if (!common_1.config.SECURITY_OAUTH2_FETCH_AVATAR_ENABLED) {
+        return undefined;
+    }
+    try {
+        const resp = await fetch(url, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${accessToken}` }
+        });
+        if (!resp.ok) {
+            return undefined;
+        }
+        const mimeType = resp.headers.get('content-type') ?? 'image/jpeg';
+        const data = Buffer.from(await resp.arrayBuffer());
+        const extension = mimeType.split('/')[1]?.split(';')[0] ?? 'jpg';
+        return {
+            name: `avatar-${id}.${extension}`,
+            mimeType,
+            size: data.length,
+            data
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Splits a provider's single display name field into a first and last name. Everything after the first whitespace
+ * separated word becomes the last name, so multipart surnames are kept intact.
+ *
+ * @param {string} [fullName] - The full name reported by the provider.
+ * @return {{ firstName: string; lastName: string }} The split name parts, empty strings when no name is available.
+ */
+function splitFullName(fullName) {
+    const [firstName = '', ...rest] = (fullName ?? '').trim().split(/\s+/);
+    return { firstName, lastName: rest.join(' ') };
+}
+/**
+ * Asserts that the provider returned an email address, which the framework needs to match or register the user.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} [email] - The email address reported by the provider.
+ * @return {string} The email address.
+ * @throws {HttpError} If the provider did not return an email address.
+ */
+function requireEmail(providerName, email) {
+    if (!email) {
+        throw new errors_1.HttpError(`${providerName} account has no email address available`, 403);
+    }
+    return email;
+}
+/**
+ * Decodes the payload of a JWT without verifying its signature. Only safe for tokens received directly from a
+ * provider's token endpoint over TLS, which OpenID Connect Core 3.1.3.7 explicitly allows.
+ *
+ * @param {string} providerName - Provider name used in the error message.
+ * @param {string} [token] - The JWT to decode.
+ * @return {T} The decoded payload.
+ * @throws {HttpError} If the token is missing or is not a well-formed JWT.
+ */
+function decodeJwtPayload(providerName, token) {
+    const payload = token?.split('.')[1];
+    if (!payload) {
+        throw new errors_1.HttpError(`${providerName} identity token is missing`, 500);
+    }
+    try {
+        return JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new errors_1.HttpError(`${providerName} identity token is malformed`, 500, e);
+    }
+}
+/**
+ * Builds the client secret Apple expects: a short-lived ES256 JWT signed with the team's `.p8` key. A literally
+ * configured `SECURITY_OAUTH2_APPLE_CLIENT_SECRET` is used as-is and takes precedence.
+ *
+ * @return {string} The Apple client secret.
+ * @throws {Error} If neither a literal secret nor a complete signing key configuration is available.
+ */
+function createAppleClientSecret() {
+    if (common_1.config.SECURITY_OAUTH2_APPLE_CLIENT_SECRET) {
+        return common_1.config.SECURITY_OAUTH2_APPLE_CLIENT_SECRET;
+    }
+    const clientId = common_1.config.SECURITY_OAUTH2_APPLE_CLIENT_ID;
+    const teamId = common_1.config.SECURITY_OAUTH2_APPLE_TEAM_ID;
+    const keyId = common_1.config.SECURITY_OAUTH2_APPLE_KEY_ID;
+    const privateKey = readApplePrivateKey();
+    if (!clientId || !teamId || !keyId || !privateKey) {
+        throw Error('Apple OAuth2 requires either a client secret, or a client ID, team ID, key ID and private key to generate one');
+    }
+    const issuedAt = Math.floor(Date.now() / 1000);
+    return signES256Jwt({ alg: 'ES256', kid: keyId, typ: 'JWT' }, {
+        iss: teamId,
+        iat: issuedAt,
+        exp: issuedAt + common_1.config.SECURITY_OAUTH2_APPLE_CLIENT_SECRET_EXPIRES_IN,
+        aud: APPLE_TOKEN_AUDIENCE,
+        sub: clientId
+    }, privateKey);
+}
+/**
+ * Reads the Apple `.p8` private key from its inline configuration value or from the configured file path.
+ *
+ * @return {string | undefined} The PEM encoded private key, or `undefined` when none is configured.
+ */
+function readApplePrivateKey() {
+    // Escaped newlines survive the trip through an environment variable, so restore them.
+    const inlineKey = common_1.config.SECURITY_OAUTH2_APPLE_PRIVATE_KEY?.replace(/\\n/g, '\n');
+    if (inlineKey) {
+        return inlineKey;
+    }
+    const keyPath = common_1.config.SECURITY_OAUTH2_APPLE_PRIVATE_KEY_PATH;
+    return keyPath ? fs.readFileSync(keyPath, 'utf8') : undefined;
+}
+/**
+ * Signs a JWT with the ES256 algorithm.
+ *
+ * @param {Record<string, unknown>} header - The JOSE header.
+ * @param {Record<string, unknown>} payload - The token claims.
+ * @param {string} privateKey - The PEM encoded EC private key.
+ * @return {string} The signed compact JWT.
+ */
+function signES256Jwt(header, payload, privateKey) {
+    const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+    const signingInput = `${encode(header)}.${encode(payload)}`;
+    // JOSE expects the raw R||S signature, not the DER encoding Node produces by default.
+    const signature = crypto.sign('sha256', Buffer.from(signingInput), {
+        key: privateKey,
+        dsaEncoding: 'ieee-p1363'
+    });
+    return `${signingInput}.${signature.toString('base64url')}`;
+}

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

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

package/security/oauth2/oauth2-x.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauth2X = void 0;
+exports.fetchXUser = fetchXUser;
+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.oauth2X = (0, create_oauth2_plugin_1.createOAuth2Plugin)(common_1.AuthSource.OAuth2X, {
+    enabled: common_1.config.SECURITY_OAUTH2_X_ENABLED,
+    clientId: common_1.config.SECURITY_OAUTH2_X_CLIENT_ID,
+    clientSecret: common_1.config.SECURITY_OAUTH2_X_CLIENT_SECRET,
+    scope: ['users.read', 'tweet.read'],
+    // X only issues tokens for authorization requests using the PKCE extension.
+    pkce: 'S256',
+    extractUserInfo: (accessToken) => fetchXUser(accessToken)
+});
+async function fetchXUser(accessToken) {
+    const params = new URLSearchParams();
+    params.append('user.fields', 'name,username,profile_image_url,confirmed_email');
+    // Only apps granted the email permission may read `confirmed_email`; for the rest X rejects the request outright.
+    const { data } = await (0, oauth2_util_1.fetchUserInfo)('X', `${common_1.config.SECURITY_OAUTH2_X_USER_INFO_URL}?${params}`, accessToken);
+    if (!data.confirmed_email) {
+        throw new errors_1.HttpError('X did not return an email address. Enable the email permission for the app in the X developer portal', 403);
+    }
+    return {
+        id: data.id,
+        email: data.confirmed_email,
+        ...(0, oauth2_util_1.splitFullName)(data.name),
+        // The profile image URL points at the 48px variant; ask for the largest one X keeps.
+        avatarUrl: data.profile_image_url?.replace('_normal.', '_400x400.')
+    };
+}

package/security/resources/connected-account/model.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@appweaver/common").ResourceModel | undefined;
+export default _default;

package/security/resources/connected-account/model.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const common_1 = require("@appweaver/common");
+const factory_1 = require("../../../factory");
+const helper_1 = require("../../helper");
+const authModel = (0, helper_1.resourceAuthModel)();
+const shouldCreateModel = (0, helper_1.isOAuth2Enabled)() ||
+    common_1.config.SECURITY_OAUTH2_CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE;
+exports.default = shouldCreateModel
+    ? (0, factory_1.createModel)({
+        name: 'ConnectedAccount',
+        audit: {
+            createdById: false
+        },
+        scalars: {
+            provider: {
+                type: 'string',
+                maxLength: 255
+            },
+            providerAccountId: {
+                type: 'string',
+                maxLength: 255
+            },
+            scope: {
+                type: 'string',
+                required: false
+            },
+            lastLoginAt: {
+                type: 'dateTime'
+            }
+        },
+        ...(authModel
+            ? {
+                relations: {
+                    [(0, common_1.uncapitalize)(authModel.name)]: {
+                        model: authModel.name,
+                        type: 'oneToMany',
+                        mappedBy: 'connectedAccounts',
+                        owner: true,
+                        input: {
+                            type: 'none'
+                        },
+                        output: {
+                            type: 'none'
+                        }
+                    }
+                }
+            }
+            : {}),
+        // A provider account may only ever be linked to a single user
+        index: [['provider', 'providerAccountId']]
+    })
+    : undefined;

package/security/resources/connected-account/service.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@appweaver/common").Ctor<import("../../..").ResourceService<any, any, any, any, import("@appweaver/common").QueryFilter<any>>> | undefined;
+export default _default;

package/security/resources/connected-account/service.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const factory_1 = require("../../../factory");
+const helper_1 = require("../../helper");
+exports.default = (0, helper_1.isOAuth2Enabled)()
+    ? (0, factory_1.createService)({ modelName: 'ConnectedAccount' })
+    : undefined;

package/types/auth.d.ts

@@ -1,3 +1,4 @@
+import { FastifyRequest } from 'fastify';
 import { AuthScope, AuthSource, AuthUser } from '@appweaver/common';
 export type JwtPayload = {
     scope: AuthScope;
@@ -15,6 +16,9 @@ export type AuthTokens = {
 export type AuthOTTData = {
     authUserId: number;
     authSource: AuthSource;
+    providerAccountId?: string;
+    scope?: string;
+    passwordRequired?: boolean;
 };
 export type TwoFactorAuthData = {
     authUserId: number;
@@ -24,18 +28,32 @@ export type TwoFactorAuthData = {
 export type OAuth2StateData = {
     redirectToUrl: string;
 };
+export type AvatarFile = {
+    name: string;
+    mimeType: string;
+    size: number;
+    data: Buffer;
+};
 export type UserInfo = {
     id: string;
     email: string;
     firstName: string;
     lastName: string;
     avatarUrl?: string;
+    avatarFile?: AvatarFile;
 };
-export type AvatarFile = {
-    name: string;
-    mimeType: string;
-    size: number;
-    data: Buffer;
+export type OAuth2TokenSet = {
+    access_token: string;
+    token_type?: string;
+    id_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    [key: string]: unknown;
+};
+export type OAuth2UserInfoContext = {
+    token: OAuth2TokenSet;
+    request: FastifyRequest;
 };
 export type UserAdditionalData = {
     firstName: string;

package/types/generated.d.ts

@@ -66,6 +66,68 @@ export type ApiKeyRelationInput = {
 export type ApiKeyQuery = QueryFilter<ApiKey>;
 export type ApiKeySort = QuerySort<ApiKeyMultiple>;
 export type ApiKeyAggregate = AggregateSelect<ApiKey>;
+export type ConnectedAccount = {
+    id: number;
+    provider: string;
+    providerAccountId: string;
+    scope?: string | null;
+    lastLoginAt: Date;
+    updatedAt: Date;
+    createdAt: Date;
+};
+export type ConnectedAccountSingle = {
+    id: number;
+    provider: string;
+    providerAccountId: string;
+    scope?: string | null;
+    lastLoginAt: Date;
+    updatedAt: Date;
+    createdAt: Date;
+};
+export type ConnectedAccountMultiple = {
+    id: number;
+    provider: string;
+    providerAccountId: string;
+    scope?: string | null;
+    lastLoginAt: Date;
+    updatedAt: Date;
+    createdAt: Date;
+};
+export type ConnectedAccountCreate = {
+    provider: string;
+    providerAccountId: string;
+    scope?: string | null;
+    lastLoginAt: Date;
+};
+export type ConnectedAccountUpdate = {
+    provider?: string;
+    providerAccountId?: string;
+    scope?: string | null;
+    lastLoginAt?: Date;
+};
+export type ConnectedAccountRelationCreate = {
+    provider: string;
+    providerAccountId: string;
+    scope?: string | null;
+    lastLoginAt: Date;
+};
+export type ConnectedAccountRelationUpdate = {
+    id: number;
+    provider?: string;
+    providerAccountId?: string;
+    scope?: string | null;
+    lastLoginAt?: Date;
+};
+export type ConnectedAccountRelationInput = {
+    id?: number;
+    provider?: string;
+    providerAccountId?: string;
+    scope?: string | null;
+    lastLoginAt?: Date;
+};
+export type ConnectedAccountQuery = QueryFilter<ConnectedAccount>;
+export type ConnectedAccountSort = QuerySort<ConnectedAccountMultiple>;
+export type ConnectedAccountAggregate = AggregateSelect<ConnectedAccount>;
 export type OneTimeToken = {
     id: number;
     tokenHash: string;