@appweaver/core 1.3.1 → 1.4.0

package/resource/utils/cursor-util.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryFingerprint = queryFingerprint;
+exports.encodeCursor = encodeCursor;
+exports.pageCursors = pageCursors;
+exports.decodeCursor = decodeCursor;
+const common_1 = require("@appweaver/common");
+const errors_1 = require("../../errors");
+/**
+ * Builds the fingerprint identifying the query a cursor belongs to. A cursor
+ * only yields the intended records while the resource, the query, and the order
+ * stay the same, so it carries the fingerprint and is rejected on mismatch.
+ *
+ * @param {string} resourceName - The name of the queried model.
+ * @param {Object} query - The mapped database query the cursor was issued for.
+ * @param {Object[]} orderBy - The mapped order entries the cursor was issued for.
+ * @return {string} The fingerprint of the query.
+ */
+function queryFingerprint(resourceName, query, orderBy) {
+    const serialized = stableStringify([resourceName, query ?? {}, orderBy]);
+    return (0, common_1.makeHash)(serialized, 'sha256', 'base64url').slice(0, 16);
+}
+/**
+ * Encodes the cursor of a page adjacent to a query result. The direction belongs
+ * to the cursor rather than to the request, so a caller cannot pair one with a
+ * direction it was not issued for.
+ *
+ * @param {ResourceId} id - The primary key of the record the page continues from.
+ * @param {string} fingerprint - The fingerprint of the query, as built by
+ * {@link queryFingerprint}.
+ * @param {boolean} [backward] - Whether the cursor pages towards the preceding
+ * records.
+ * @return {string} The encoded cursor.
+ */
+function encodeCursor(id, fingerprint, backward = false) {
+    const payload = { i: id, f: fingerprint };
+    if (backward) {
+        payload.b = true;
+    }
+    return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+}
+/**
+ * Builds the cursors of the pages adjacent to a returned page, each addressing
+ * the record of this page it continues from. A page that has no neighbour in a
+ * direction, and an empty page, yield null rather than an absent cursor.
+ *
+ * @param {Object[]} resources - The records of the returned page, in the order
+ * they were queried in.
+ * @param {string} fingerprint - The fingerprint of the query the page belongs to.
+ * @param {boolean} hasNext - Whether a page follows the returned one.
+ * @param {boolean} hasPrev - Whether a page precedes the returned one.
+ * @return {PageCursors} The cursors of the existing adjacent pages.
+ */
+function pageCursors(resources, fingerprint, hasNext, hasPrev) {
+    // A queried record always carries its primary key, which a model type need
+    // not declare
+    const first = resources[0];
+    const last = resources[resources.length - 1];
+    if (!first || !last) {
+        return { nextCursor: null, prevCursor: null };
+    }
+    return {
+        nextCursor: hasNext ? encodeCursor(last.id, fingerprint) : null,
+        prevCursor: hasPrev ? encodeCursor(first.id, fingerprint, true) : null
+    };
+}
+/**
+ * Decodes the cursor a query request carries, resolving the record the page
+ * continues from and the direction it runs in.
+ *
+ * @param {string} [cursor] - The cursor of the request, which may be the null
+ * one of a page that does not exist.
+ * @param {string} fingerprint - The fingerprint of the query the cursor is used
+ * on, as built by {@link queryFingerprint}.
+ * @return {DecodedCursor | undefined} The decoded cursor, or `undefined` when the
+ * request carries none.
+ * @throws {HttpError} 400 if the cursor is malformed, or was issued for another
+ * resource, filter, or sort order.
+ */
+function decodeCursor(cursor, fingerprint) {
+    if (!cursor) {
+        return undefined;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new errors_1.HttpError('Invalid pagination cursor', 400, e);
+    }
+    if (!(0, common_1.isPlainObject)(payload) || payload.i === undefined) {
+        throw new errors_1.HttpError('Invalid pagination cursor', 400);
+    }
+    if (payload.f !== fingerprint) {
+        throw new errors_1.HttpError('Pagination cursor does not match the filter and sort of this query', 400);
+    }
+    return { id: payload.i, backward: payload.b === true };
+}
+/**
+ * Serializes a value with its object keys in a stable order, so two equal
+ * queries fingerprint identically whatever order their properties arrived in.
+ *
+ * @param {any} value - The value to serialize.
+ * @return {string} The serialized value.
+ */
+function stableStringify(value) {
+    if ((0, common_1.isArray)(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if ((0, common_1.isPlainObject)(value)) {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}

package/resource/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './aggregate-util';
+export * from './cursor-util';
 export * from './filter-util';
 export * from './relation-util';
 export * from './sort-util';

package/resource/utils/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./aggregate-util"), exports);
+__exportStar(require("./cursor-util"), exports);
 __exportStar(require("./filter-util"), exports);
 __exportStar(require("./relation-util"), exports);
 __exportStar(require("./sort-util"), exports);

package/resource/utils/relation-util.d.ts

@@ -1,4 +1,4 @@
-import { ActionType } from '@appweaver/common';
+import { ActionType, ResourceId } from '@appweaver/common';
 /** The nested write actions a single relation field can be mapped to. */
 export type RelationActions = Record<string, Partial<{
     connect: any;
@@ -74,11 +74,11 @@ export declare function missingRelationFields(resourceName: string | undefined,
  * user. Returns undefined when the model does not audit the `createdById` field or when no user is authenticated.
  *
  * @param {string} resourceName - The name of the model the audit relation is built for.
- * @return {{connect: {id: number}}|undefined} The connect action pointing at the id of the currently authenticated
+ * @return {{connect: {id: ResourceId}}|undefined} The connect action pointing at the id of the currently authenticated
  * user, or undefined if the model does not audit the `createdById` field or no user is authenticated.
  */
 export declare function createdByConnect(resourceName: string): {
     connect: {
-        id: number;
+        id: ResourceId;
     };
 } | undefined;

package/resource/utils/relation-util.js

@@ -276,7 +276,7 @@ function missingRelationFields(resourceName, data) {
  * user. Returns undefined when the model does not audit the `createdById` field or when no user is authenticated.
  *
  * @param {string} resourceName - The name of the model the audit relation is built for.
- * @return {{connect: {id: number}}|undefined} The connect action pointing at the id of the currently authenticated
+ * @return {{connect: {id: ResourceId}}|undefined} The connect action pointing at the id of the currently authenticated
  * user, or undefined if the model does not audit the `createdById` field or no user is authenticated.
  */
 function createdByConnect(resourceName) {

package/resource/utils/sort-util.d.ts

@@ -18,3 +18,14 @@ import { ActionType, QuerySort } from '@appweaver/common';
  * direction, or targets a relation that the action does not include in its response.
  */
 export declare function mapSortValues(sort: QuerySort, resourceName: string, action?: ActionType): any[];
+/**
+ * Maps a sort input the same way {@link mapSortValues} does, and terminates it with the primary key when no entry
+ * orders by it. Without a total order, records sharing every sort value can be skipped or repeated across pages.
+ *
+ * @param {QuerySort} sort - The sort input to map, as a comma-separated field list or a sort object.
+ * @param {string} resourceName - The name of the model the sort is applied on.
+ * @param {ActionType} [action] - The action the sort is applied on. Defaults to the query action.
+ * @return {Object[]} The `orderBy` entries, ending in a unique one.
+ * @throws {HttpError} 400 under the same conditions as {@link mapSortValues}.
+ */
+export declare function mapStableSortValues(sort: QuerySort, resourceName: string, action?: ActionType): any[];

package/resource/utils/sort-util.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapSortValues = mapSortValues;
+exports.mapStableSortValues = mapStableSortValues;
 const common_1 = require("@appweaver/common");
 const context_1 = require("../../context");
 const errors_1 = require("../../errors");
@@ -46,6 +47,23 @@ function mapSortValues(sort, resourceName, action = 'query') {
     }
     return orderBy;
 }
+/**
+ * Maps a sort input the same way {@link mapSortValues} does, and terminates it with the primary key when no entry
+ * orders by it. Without a total order, records sharing every sort value can be skipped or repeated across pages.
+ *
+ * @param {QuerySort} sort - The sort input to map, as a comma-separated field list or a sort object.
+ * @param {string} resourceName - The name of the model the sort is applied on.
+ * @param {ActionType} [action] - The action the sort is applied on. Defaults to the query action.
+ * @return {Object[]} The `orderBy` entries, ending in a unique one.
+ * @throws {HttpError} 400 under the same conditions as {@link mapSortValues}.
+ */
+function mapStableSortValues(sort, resourceName, action = 'query') {
+    const orderBy = mapSortValues(sort, resourceName, action);
+    if (!orderBy.some((entry) => 'id' in entry)) {
+        orderBy.push({ id: 'asc' });
+    }
+    return orderBy;
+}
 /**
  * Flattens a sort input into the list of its field paths and directions, keeping the order the fields were declared
  * in. String inputs are split on commas, with a `-` or `+` prefix selecting the direction, and object inputs are

package/security/api-key/api-key-auth.js

@@ -26,7 +26,9 @@ exports.apiKeyAuth = (0, fastify_plugin_1.default)(async (server) => {
         // Use configured delimiter to split an API key and separate ID from the
         // rest of the key value
         const apiKeyParts = sanitizedApiKey.split(common_1.config.SECURITY_API_KEY_DELIMITER);
-        const apiKeyId = parseInt(apiKeyParts.shift() ?? '', 10);
+        // The id prefix is read back in the primary key type of the ApiKey model,
+        // which can be configured as a string like on any other model
+        const apiKeyId = (0, common_1.toResourceId)(apiKeyParts.shift() ?? '', (0, context_1.injectModel)('ApiKey', false)?.config?.id);
         const apiKeyValue = apiKeyParts.join(common_1.config.SECURITY_API_KEY_DELIMITER);
         const cacheKey = cacheService.buildCacheKey({
             baseKey: `apikey:${apiKeyId}`,
@@ -35,6 +37,7 @@ exports.apiKeyAuth = (0, fastify_plugin_1.default)(async (server) => {
         let apiKey = await cacheService.getCachedValue(cacheKey);
         if (!apiKey) {
             try {
+                // The generated client types the id after the configured primary key
                 apiKey = await db
                     .client()
                     .apiKey.findFirst({ where: { id: apiKeyId } });

package/security/auth-service.d.ts

@@ -1,14 +1,14 @@
-import { AuthScope, AuthSource, AuthUser, RouteConfig } from '@appweaver/common';
+import { AuthScope, AuthSource, AuthUser, ResourceId, RouteConfig } from '@appweaver/common';
 import { AuthTokens, JwtPayload, UserAdditionalData } from '../types';
 export declare class AuthService {
     /**
      * Finds an authenticated user by their unique identifier.
      *
-     * @param {number} id - The unique identifier of the authenticated user to find.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to find.
      * @return {Promise<AuthUser | null>} A promise that resolves to the authenticated user object if found, otherwise
      * null.
      */
-    findById(id: number): Promise<AuthUser | null>;
+    findById(id: ResourceId): Promise<AuthUser | null>;
     /**
      * Retrieves a user by their username.
      *
@@ -19,12 +19,12 @@ export declare class AuthService {
     /**
      * Updates an authenticated user's information in the system.
      *
-     * @param {number} id - The unique identifier of the authenticated user to be updated.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to be updated.
      * @param {Partial<AuthUser> & { password?: string }} data - The partial user data to update, optionally including a
      * password.
      * @return {Promise<AuthUser>} A promise that resolves to the updated authenticated user object.
      */
-    updateAuthUser(id: number, data: Partial<AuthUser> & {
+    updateAuthUser(id: ResourceId, data: Partial<AuthUser> & {
         password?: string;
     }): Promise<AuthUser>;
     /**
@@ -112,9 +112,9 @@ export declare class AuthService {
     /**
      * Logs out a user by updating their authentication information with a logout timestamp.
      *
-     * @param {number} id - The unique identifier of the user to be logged out.
+     * @param {ResourceId} id - The unique identifier of the user to be logged out.
      * @return {Promise<boolean>} A promise that resolves to a boolean indicating whether the logout operation was
      * successful.
      */
-    logout(id: number): Promise<boolean>;
+    logout(id: ResourceId): Promise<boolean>;
 }

package/security/auth-service.js

@@ -6,6 +6,7 @@ const helper_1 = require("./helper");
 const oauth2_service_1 = require("./oauth2/oauth2-service");
 const context_1 = require("../context");
 const cache_1 = require("../cache");
+const storage_1 = require("../storage");
 const errors_1 = require("../errors");
 const AUTH_KEY = 'auth';
 class AuthService {
@@ -21,7 +22,7 @@ class AuthService {
     /**
      * Finds an authenticated user by their unique identifier.
      *
-     * @param {number} id - The unique identifier of the authenticated user to find.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to find.
      * @return {Promise<AuthUser | null>} A promise that resolves to the authenticated user object if found, otherwise
      * null.
      */
@@ -80,7 +81,7 @@ class AuthService {
     /**
      * Updates an authenticated user's information in the system.
      *
-     * @param {number} id - The unique identifier of the authenticated user to be updated.
+     * @param {ResourceId} id - The unique identifier of the authenticated user to be updated.
      * @param {Partial<AuthUser> & { password?: string }} data - The partial user data to update, optionally including a
      * password.
      * @return {Promise<AuthUser>} A promise that resolves to the updated authenticated user object.
@@ -106,10 +107,11 @@ class AuthService {
      * @throws {HttpError} Throws an error if the registration process fails.
      */
     async registerAuthUser(source, email, password, data) {
+        let authUser;
         try {
             const serviceConfig = this._authUserService[common_1.CONFIG];
-            const registrationData = serviceConfig.registrationData(source, email, password, data);
-            return this._authUserService.create({
+            const registrationData = await serviceConfig.registrationData(source, email, password, data);
+            authUser = await this._authUserService.create({
                 ...registrationData,
                 verifiedEmail: source !== common_1.AuthSource.Password
             });
@@ -117,6 +119,42 @@ class AuthService {
         catch (e) {
             throw new errors_1.HttpError('Auth user registration error', 500, e);
         }
+        await this.saveRegistrationFiles(authUser, source, data);
+        return authUser;
+    }
+    /**
+     * Saves the files the `registrationFiles` service configuration selects for a newly registered user, each one to the
+     * file field of the auth model it is keyed by. The files are stored only after the user exists, since a file record
+     * is linked to the resource that owns it. Storing a file is best-effort, so a rejected file, such as an avatar the
+     * provider served in an unsupported format, is logged and never fails the registration.
+     *
+     * @internal
+     */
+    async saveRegistrationFiles(authUser, source, data) {
+        const serviceConfig = this._authUserService[common_1.CONFIG];
+        if (!serviceConfig.registrationFiles) {
+            return;
+        }
+        let files;
+        try {
+            files = (await serviceConfig.registrationFiles(source, data)) ?? {};
+        }
+        catch (e) {
+            common_1.logger.error({ id: authUser.id, err: e }, 'Registration files selection error');
+            return;
+        }
+        const fileService = (0, context_1.inject)(storage_1.FileService);
+        for (const [field, file] of Object.entries(files)) {
+            if (!file) {
+                continue;
+            }
+            try {
+                await fileService.saveBuffer(field, file, authUser, this._authUserService.client);
+            }
+            catch (e) {
+                common_1.logger.error({ id: authUser.id, field, err: e }, 'Registration file save error');
+            }
+        }
     }
     /**
      * Changes the password for the authenticated user.
@@ -292,7 +330,7 @@ class AuthService {
     /**
      * Logs out a user by updating their authentication information with a logout timestamp.
      *
-     * @param {number} id - The unique identifier of the user to be logged out.
+     * @param {ResourceId} id - The unique identifier of the user to be logged out.
      * @return {Promise<boolean>} A promise that resolves to a boolean indicating whether the logout operation was
      * successful.
      */

package/security/create-auth-resources.d.ts

@@ -1,7 +1,8 @@
 import { Ctor, IResourceService, ResourceModel, ResourceModelConfig, ResourceServiceConfig } from '@appweaver/common';
-import { CheckOAuth2UserFn, RegistrationDataFn } from '../types';
+import { CheckOAuth2UserFn, RegistrationDataFn, RegistrationFilesFn } from '../types';
 export declare function createAuthModel(config: ResourceModelConfig): ResourceModel;
 export declare function createAuthService<T = any, C = any, U = any>(config: ResourceServiceConfig<T, C, U> & {
     registrationData?: RegistrationDataFn<T>;
+    registrationFiles?: RegistrationFilesFn;
     checkOAuth2User?: CheckOAuth2UserFn;
 }): Ctor<IResourceService<T, T, C, U>>;

package/security/oauth2/create-oauth2-plugin.js

@@ -13,6 +13,7 @@ const auth_service_1 = require("../auth-service");
 const oauth2_service_1 = require("./oauth2-service");
 const helper_1 = require("../helper");
 const oauth2_schema_1 = require("./oauth2-schema");
+const oauth2_util_1 = require("./oauth2-util");
 function createOAuth2Plugin(authSource, oAuth2Config) {
     const name = authSource.replace('oauth2', '');
     const upperName = name.toUpperCase();
@@ -100,7 +101,8 @@ function createOAuth2Plugin(authSource, oAuth2Config) {
                 }
                 authUser = await authService.registerAuthUser(authSource, userInfo.email, undefined, {
                     ...(0, common_1.pickProperties)(userInfo, ['firstName', 'lastName', 'avatarUrl']),
-                    avatarFile: userInfo.avatarFile ?? (await fetchAvatarFile(userInfo))
+                    avatarFile: userInfo.avatarFile ??
+                        (await (0, oauth2_util_1.fetchAvatarFile)(userInfo.avatarUrl, userInfo.id))
                 });
             }
             const stateData = request.oauth2State;
@@ -137,36 +139,3 @@ function createOAuth2Plugin(authSource, oAuth2Config) {
         });
     });
 }
-/**
- * Downloads the user's avatar image from the OAuth2 provider so it can be passed to the `registrationData` callback.
- * Fetching is best-effort: any failure is logged and `undefined` is returned so the registration flow is not blocked.
- *
- * @param {UserInfo} userInfo - The user info extracted from the OAuth2 provider, including the optional avatar URL.
- * @return {Promise<AvatarFile | undefined>} A promise resolving to the downloaded avatar file, or `undefined` when
- * avatar fetching is disabled, no avatar URL is available, or the download fails.
- */
-async function fetchAvatarFile(userInfo) {
-    if (!common_1.config.SECURITY_OAUTH2_FETCH_AVATAR_ENABLED || !userInfo.avatarUrl) {
-        return undefined;
-    }
-    try {
-        const resp = await fetch(userInfo.avatarUrl, { method: 'GET' });
-        if (!resp.ok) {
-            common_1.logger.debug({ url: userInfo.avatarUrl, status: resp.status }, 'OAuth2 avatar fetch failed');
-            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-${userInfo.id}.${extension}`,
-            mimeType,
-            size: data.length,
-            data
-        };
-    }
-    catch (e) {
-        common_1.logger.debug({ url: userInfo.avatarUrl, err: e }, 'OAuth2 avatar fetch error');
-        return undefined;
-    }
-}

package/security/oauth2/oauth2-microsoft.js

@@ -31,6 +31,6 @@ async function fetchMicrosoftUser(accessToken) {
         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)
+        avatarFile: await (0, oauth2_util_1.fetchAvatarFile)(`${userInfoUrl}/photo/$value`, data.id, accessToken)
     };
 }

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

@@ -6,20 +6,22 @@ import { AvatarFile } from '../../types';
  * @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.
+ * @return {Promise<Object>} 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.
+ * Downloads the user's avatar image so it can be passed to the `registrationData` and `registrationFiles` callbacks as
+ * `avatarFile`. Fetching is opt-in through `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED` and best-effort: every reason the
+ * image does not arrive is logged and `undefined` is returned, so the registration flow is never blocked by it.
  *
- * @param {string} url - The avatar endpoint to call.
- * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {string | undefined} url - The avatar endpoint to call.
  * @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`.
+ * @param {string} [accessToken] - Access token, for providers whose avatar endpoint requires authentication.
+ * @return {Promise<AvatarFile | undefined>} A promise resolving to the downloaded avatar, or `undefined` when
+ * fetching is disabled, no avatar URL is available, or the download fails.
  */
-export declare function fetchAuthenticatedAvatar(url: string, accessToken: string, id: string): Promise<AvatarFile | undefined>;
+export declare function fetchAvatarFile(url: string | undefined, id: string, accessToken?: 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.

package/security/oauth2/oauth2-util.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchUserInfo = fetchUserInfo;
-exports.fetchAuthenticatedAvatar = fetchAuthenticatedAvatar;
+exports.fetchAvatarFile = fetchAvatarFile;
 exports.splitFullName = splitFullName;
 exports.requireEmail = requireEmail;
 exports.decodeJwtPayload = decodeJwtPayload;
@@ -51,7 +51,7 @@ const APPLE_TOKEN_AUDIENCE = 'https://appleid.apple.com';
  * @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.
+ * @return {Promise<Object>} 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 = {}) {
@@ -65,24 +65,30 @@ async function fetchUserInfo(providerName, url, accessToken, headers = {}) {
     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.
+ * Downloads the user's avatar image so it can be passed to the `registrationData` and `registrationFiles` callbacks as
+ * `avatarFile`. Fetching is opt-in through `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED` and best-effort: every reason the
+ * image does not arrive is logged and `undefined` is returned, so the registration flow is never blocked by it.
  *
- * @param {string} url - The avatar endpoint to call.
- * @param {string} accessToken - The access token obtained from the authorization code flow.
+ * @param {string | undefined} url - The avatar endpoint to call.
  * @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`.
+ * @param {string} [accessToken] - Access token, for providers whose avatar endpoint requires authentication.
+ * @return {Promise<AvatarFile | undefined>} A promise resolving to the downloaded avatar, or `undefined` when
+ * fetching is disabled, no avatar URL is available, or the download fails.
  */
-async function fetchAuthenticatedAvatar(url, accessToken, id) {
+async function fetchAvatarFile(url, id, accessToken) {
     if (!common_1.config.SECURITY_OAUTH2_FETCH_AVATAR_ENABLED) {
         return undefined;
     }
+    if (!url) {
+        return undefined;
+    }
     try {
         const resp = await fetch(url, {
             method: 'GET',
-            headers: { authorization: `Bearer ${accessToken}` }
+            headers: accessToken ? { authorization: `Bearer ${accessToken}` } : {}
         });
         if (!resp.ok) {
+            common_1.logger.error({ url, status: resp.status }, 'OAuth2 avatar fetch failed');
             return undefined;
         }
         const mimeType = resp.headers.get('content-type') ?? 'image/jpeg';
@@ -95,7 +101,8 @@ async function fetchAuthenticatedAvatar(url, accessToken, id) {
             data
         };
     }
-    catch {
+    catch (e) {
+        common_1.logger.error({ url, err: e }, 'OAuth2 avatar fetch error');
         return undefined;
     }
 }

package/security/resources/api-key/model.js

@@ -44,6 +44,8 @@ exports.default = shouldCreateModel
                         type: 'oneToMany',
                         mappedBy: 'apiKeys',
                         owner: true,
+                        // API keys are meaningless without their user
+                        onDelete: 'cascade',
                         input: {
                             type: 'none'
                         },

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

@@ -37,6 +37,8 @@ exports.default = shouldCreateModel
                         type: 'oneToMany',
                         mappedBy: 'connectedAccounts',
                         owner: true,
+                        // Connected accounts are meaningless without their user
+                        onDelete: 'cascade',
                         input: {
                             type: 'none'
                         },

package/security/store/database-security-store.js

@@ -45,7 +45,8 @@ class DatabaseSecurityStore extends common_1.SecurityStore {
     }
     /** @internal */
     async removeOneTimeToken(id) {
-        await this._db.client().oneTimeToken.delete({ where: { id } });
+        // The generated client types the id after the configured primary key
+        await this._db.client().oneTimeToken.delete({ where: { id: id } });
     }
 }
 exports.DatabaseSecurityStore = DatabaseSecurityStore;

package/storage/file-service.d.ts

@@ -1,6 +1,6 @@
 import { Multipart, MultipartFile } from '@fastify/multipart';
-import { ContentStream, Resource, ResourceClient } from '@appweaver/common';
-import { File } from '../types';
+import { ContentStream, Resource, ResourceClient, ResourceId } from '@appweaver/common';
+import { File, FileBuffer } from '../types';
 export type FileStream = {
     content: ContentStream;
     fileName: string;
@@ -41,6 +41,21 @@ export declare class FileService {
      * @throws {HttpError} Throws an error if file validation, storage, or resource association fails.
      */
     saveFile(data: MultipartFile, resource: Resource, client: ResourceClient): Promise<File>;
+    /**
+     * Saves an in-memory file to storage and associates it with a file field of a specific resource. Behaves exactly like
+     * {@link saveFile}, except the content is taken from a buffer instead of a multipart upload, which makes it usable
+     * outside a file upload request, for an avatar downloaded from an OAuth2 provider or an image the application
+     * generates itself.
+     *
+     * @param {string} fieldName The file field of the resource the file is saved to.
+     * @param {FileBuffer} file The file content, along with its original name and media type.
+     * @param {Resource} resource The resource object with which the file is being associated.
+     * @param {ResourceClient} client The database client responsible for handling the resource.
+     * @return {Promise<File>} A promise that resolves to the saved file object or rejects with an error if the operation
+     * fails.
+     * @throws {HttpError} Throws an error if file validation, storage, or resource association fails.
+     */
+    saveBuffer(fieldName: string, file: FileBuffer, resource: Resource, client: ResourceClient): Promise<File>;
     /**
      * Saves files received as an asynchronous iterable of multipart data.
      *
@@ -85,8 +100,8 @@ export declare class FileService {
      * setting (or set to `'keep'`) are left untouched.
      *
      * @param {string} resourceName - The resource model name.
-     * @param {number} resourceId - The ID of the deleted resource.
+     * @param {ResourceId} id - The ID of the deleted resource.
      * @return {Promise<File[]>} A promise that resolves to the list of successfully deleted files.
      */
-    deleteResourceFiles(resourceName: string, resourceId: number): Promise<File[]>;
+    deleteResourceFiles(resourceName: string, id: ResourceId): Promise<File[]>;
 }