@appweaver/create-weaver-app 1.0.25 → 1.1.1

package/create-weaver-app.js

@@ -180,11 +180,10 @@ program
             : `[Appweaver framework guidelines](${guidelinesPath})`;
         const guidelinesContent = `# ${variables.NAME}\n\n` +
             `${description}\n\n` +
-            `This is an [Appweaver](https://github.com/lmatosevic/appweaver) project. ` +
-            `Follow the framework conventions, architecture, and usage documented in the guidelines:\n\n` +
-            `${guidelinesReference}\n\n` +
-            `<!-- Add your own project-specific instructions below this line. ` +
-            `This file is not modified by \`weaver update\`. -->\n`;
+            `This is an [Appweaver](https://github.com/lmatosevic/appweaver) ` +
+            `project. Follow the framework conventions, architecture,\n and ` +
+            `usage documented in the guidelines:\n\n${guidelinesReference}\n\n` +
+            `<!-- Add your own project-specific instructions below this line. -->\n`;
         await promises_1.default.writeFile(guidelinesFilePath, guidelinesContent, {
             encoding: 'utf8'
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/create-weaver-app",
-  "version": "1.0.25",
+  "version": "1.1.1",
   "description": "Appweaver - the backend framework for AI-first development (@create-weaver-app)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/skill/GUIDELINES.md

@@ -141,6 +141,10 @@ Use `createAuthModel` and `createAuthService` for authenticatable users. They mu
 `createAuthModel` adds: `email`, `passwordHash`, `verifiedEmail`, `twoFactorAuth`, `enabled`, `logoutAt` scalars; a
 virtual `password` field; a `roles` relation; and optional `apiKeys` relation.
 
+`createAuthService` supports an optional `registrationData` callback to customize the registration payload and an
+optional `checkOAuth2User` callback to allow or reject OAuth2 registrations/logins (return nothing to proceed, or a
+string/`Error` to abort).
+
 ```ts
 // src/resources/user/model.ts
 import { createAuthModel } from '@appweaver/core';

package/skill/SKILL.md

@@ -78,7 +78,7 @@ create-weaver-app MyBlogAPI "My own CMS for blogging" --database postgresql --no
 ```
 
 This creates a `./my-blog-api` directory, installs all dependencies, and runs the initial schema and type generation.
-Default test runner is `jest` with `swc` transpiler.
+The default test runner is `jest` with `swc` transpiler.
 
 **Example — Bun project with Sqlite:**
 
@@ -86,8 +86,8 @@ Default test runner is `jest` with `swc` transpiler.
 create-weaver-app BunApp "Bun application with simple API" --bun --database sqlite
 ```
 
-This creates a `./bun-app` directory, installs all dependencies using bun package manager, and runs the initial
-schema and type generation. Default test runner is `bun`.
+This creates a `./bun-app` directory, installs all dependencies using bun package manager, and runs the initial schema
+and type generation. The default test runner is `bun`.
 
 After the application is scaffolded, the following commands need to be run to finish the application setup:
 
@@ -314,11 +314,14 @@ Use `createAuthModel` and `createAuthService` instead of `createModel`/`createSe
 authenticatable user. They cannot be used independently! If an auth model is created, then also auth service must exist.
 
 `createAuthModel` extends the config with: `email`, `passwordHash`, `verifiedEmail`, `twoFactorAuth`, `enabled`,
-`logoutAt` scalars; a virtual `password` field (write-only); a `roles` relation; and an optional `apiKeys` relation (
-when `SECURITY_API_KEY_ENABLED` is set).
+`logoutAt` scalars; a virtual `password` field (write-only); a `roles` relation; and an optional `apiKeys` relation
+(when `SECURITY_API_KEY_ENABLED` is set).
 
-`createAuthService` extends the config with automatic password hashing on create/update and an optional
-`registrationData` callback to customize registration payload.
+`createAuthService` extends the config with automatic password hashing on create/update, an optional
+`registrationData` callback to customize registration payload (for OAuth2 logins its `additionalData` argument includes
+`firstName`, `lastName`, `avatarUrl`, and — when `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED` is set — a downloaded
+`avatarFile`), and an optional `checkOAuth2User` callback invoked before a user is registered or authenticated via
+OAuth2 (return nothing to proceed, or a string/`Error`/`HttpError` to abort the login with an error).
 
 ```ts
 // src/resources/user/model.ts
@@ -356,7 +359,9 @@ export default createAuthService({
 
 Use `registerRoute` to register a custom [Fastify route](https://fastify.dev/docs/latest/Reference/Routes/) handler. The
 handler is a Fastify plugin function that defines one or more routes. An optional config object controls authentication,
-caching, and reCAPTCHA behavior.
+caching, and reCAPTCHA behavior. When a custom route's 2xx response schema references resource output models (`<Name>`,
+`<Name>Single` or `<Name>Multiple` — directly or nested inside custom schemas), virtual field values (e.g. `File.url`)
+are projected onto the response payload automatically before serialization.
 
 ```ts
 // src/plugins/custom-route.ts
@@ -422,8 +427,8 @@ registerPlugin('audit-log', async (server) => {
 
 ### Dependency injection
 
-Use `define` to register a value or class in the app context, and `inject` to retrieve it. Class constructors are
-lazily instantiated as singletons on the first injection.
+Use `define` to register a value or class in the app context, and `inject` to retrieve it. Class constructors are lazily
+instantiated as singletons on the first injection.
 
 ```ts
 import { Cache } from '@appweaver/common';

package/skill/references/configuration.md

@@ -256,9 +256,11 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 
 #### OAuth2 general
 
-| Property                    | Type    | Default  | Description                                                  |
-|-----------------------------|---------|----------|--------------------------------------------------------------|
-| `SECURITY_OAUTH2_STATE_TTL` | integer | `600000` | OAuth2 state parameter TTL in milliseconds (default 10 min). |
+| Property                               | Type    | Default  | Description                                                                                                                       |
+|----------------------------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_STATE_TTL`            | integer | `600000` | OAuth2 state parameter TTL in milliseconds (default 10 min).                                                                      |
+| `SECURITY_OAUTH2_REGISTRATION_ENABLED` | boolean | `true`   | Allow registering new users via OAuth2 login. When `false`, only already existing users (matched by email) can log in via OAuth2. |
+| `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED` | boolean | `false`  | Download the user's avatar from the OAuth2 provider during registration and pass it as `avatarFile` to `registrationData`.        |
 
 #### OAuth2 Google
 

package/skill/references/resources.md

@@ -1,9 +1,9 @@
 # Resources
 
-Resources are the core building blocks of an Appweaver application. There are four resource types that form a
-dependency chain: **model** → **service** → **routes** → **policy**. Each resource type is created using a
-corresponding factory function and autoloaded from `src/resources/*/` on application start. Source directory and
-resources pattern could be changed with `APP_SOURCE_PATH` and `RESOURCE_{MODEL,SERVICE,...}_PATTERN` config variables.
+Resources are the core building blocks of an Appweaver application. There are four resource types that form a dependency
+chain: **model** → **service** → **routes** → **policy**. Each resource type is created using a corresponding factory
+function and autoloaded from `src/resources/*/` on application start. Source directory and resources pattern could be
+changed with `APP_SOURCE_PATH` and `RESOURCE_{MODEL,SERVICE,...}_PATTERN` config variables.
 
 - A **model** is always required.
 - A **service** requires a model.
@@ -14,9 +14,9 @@ resources pattern could be changed with `APP_SOURCE_PATH` and `RESOURCE_{MODEL,S
 
 ## createModel
 
-Creates a resource model definition. The model defines database fields, relations, files, virtual fields, DTOs for
-CRUD operations, and index configuration. It is used to generate Prisma schema, TypeScript types, and route
-request/response schemas.
+Creates a resource model definition. The model defines database fields, relations, files, virtual fields, DTOs for CRUD
+operations, and index configuration. It is used to generate Prisma schema, TypeScript types, and route request/response
+schemas.
 
 ```ts
 import { createModel } from '@appweaver/core';
@@ -505,8 +505,8 @@ are passed through unchanged.
 | `maxHeight` | number   | Maximum height. Only downscales if the image exceeds this dimension.                                           |
 | `fit`       | ImageFit | How the image fits the target dimensions: `'inside'` (default), `'contain'`, `'cover'`, `'fill'`, `'outside'`. |
 
-`width`/`height` take precedence over `maxWidth`/`maxHeight`. When using `maxWidth`/`maxHeight`, images smaller than
-the specified dimensions are not enlarged.
+`width`/`height` take precedence over `maxWidth`/`maxHeight`. When using `maxWidth`/`maxHeight`, images smaller than the
+specified dimensions are not enlarged.
 
 ```ts
 // Compress and limit dimensions
@@ -566,6 +566,17 @@ const config = {
 | `output.type`    | `'always'` \| `'single'` \| `'multiple'` \| `'none'` | When the virtual field appears in output.                  |
 | `output.value`   | primitive \| function                                | Computed value or transformer for output.                  |
 
+Virtual output values are applied automatically to responses of resource CRUD routes (including nested relation and file
+objects) and to responses of custom `registerRoute` routes whose 2xx response schemas reference resource output models.
+To apply them manually on a raw resource object (e.g. one fetched directly through a Prisma client), use the
+`projectVirtualFields` helper:
+
+```ts
+import { projectVirtualFields } from '@appweaver/core';
+
+const projected = projectVirtualFields(post, 'Post'); // sets virtual values, recursing into relations and files
+```
+
 ### Operation config (read, create, update)
 
 Control which fields appear in each DTO. Use `pick` for an allowlist or `omit` for a deny-list.
@@ -988,8 +999,8 @@ registerModel(
 
 ## registerPlugin
 
-Registers a custom Fastify plugin. Plugins are wrapped with `fastify-plugin` so their decorators and hooks are scoped
-to the entire server instance.
+Registers a custom Fastify plugin. Plugins are wrapped with `fastify-plugin` so their decorators and hooks are scoped to
+the entire server instance.
 
 ```ts
 import { registerPlugin } from '@appweaver/core';

package/skill/references/security.md

@@ -212,7 +212,9 @@ follow the same flow pattern.
 6. Server verifies the state token (one-time use)
 7. Server exchanges the code for an access token with the provider
 8. Server fetches user info from the provider
-9. Server creates or finds the user by email
+9. Server finds the user by email and invokes the optional checkOAuth2User callback
+   (aborts with an error when the callback returns a string or an Error).
+   New users are registered unless SECURITY_OAUTH2_REGISTRATION_ENABLED=false
 10. Server generates an authentication OTT
 11. Server redirects to the original URL with the token:
     -> https://myapp.com/dashboard?token={ott}
@@ -259,7 +261,7 @@ SECURITY_OAUTH2_GOOGLE_CLIENT_SECRET=your-google-client-secret
 
 **Scopes**: `profile`, `email`
 
-**User info extracted**: `email`, `given_name` (firstName), `family_name` (lastName)
+**User info extracted**: `email`, `given_name` (firstName), `family_name` (lastName), `picture` (avatarUrl)
 
 **Google Cloud Console setup:**
 
@@ -304,7 +306,7 @@ SECURITY_OAUTH2_FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
 
 **Scopes**: `public_profile`, `email`
 
-**User info extracted**: `email`, `name` (split into firstName/lastName)
+**User info extracted**: `email`, `name` (split into firstName/lastName), `picture` (avatarUrl)
 
 **Facebook Developer Console setup:**
 
@@ -346,7 +348,48 @@ For any OpenID Connect-compatible provider (Keycloak, Auth0, etc.).
 
 **User info endpoint**: `{issuer}/protocol/openid-connect/userinfo`
 
-**Standard claims expected**: `sub`, `email`, `given_name`, `family_name`
+**Standard claims expected**: `sub`, `email`, `given_name`, `family_name`, `picture` (optional, avatarUrl)
+
+### OAuth2 registration control and hooks
+
+**Disable OAuth2 registration** — set `SECURITY_OAUTH2_REGISTRATION_ENABLED=false` (JSON:
+`security.oauth2.registrationEnabled`) to prevent new users from being created during OAuth2 login. Only users that
+already exist in the database (matched by email) can then log in via OAuth2; unknown emails receive a 403 error.
+
+**`checkOAuth2User` callback** — an optional callback on `createAuthService` invoked on every OAuth2 login, before a
+user is registered or authenticated. It receives the auth source, the user info extracted from the provider, and the
+existing auth user (or `null` when the user would be newly registered). Return nothing to proceed, or return a string,
+`Error`, or `HttpError` to abort the flow (a 403 error is thrown, or the `HttpError` as-is):
+
+```ts
+// src/resources/user/service.ts
+import { AuthSource } from '@appweaver/common';
+import { createAuthService, HttpError } from '@appweaver/core';
+
+export default createAuthService({
+  modelName: 'User',
+  checkOAuth2User: (source, userInfo, authUser) => {
+    if (!userInfo.email.endsWith('@mycompany.com')) {
+      return new HttpError('Only company accounts are allowed', 403);
+    }
+    if (!authUser && source === AuthSource.OAuth2Facebook) {
+      return 'New accounts cannot be created via Facebook';
+    }
+    // Return nothing to proceed with registration/login
+  },
+  registrationData: (source, email, password, additionalData) => ({
+    email,
+    password,
+    name: `${additionalData?.firstName} ${additionalData?.lastName}`
+  })
+});
+```
+
+**User avatar** — the provider's avatar/picture URL is passed to `registrationData` as `additionalData.avatarUrl`.
+When `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED=true` (JSON: `security.oauth2.fetchAvatarEnabled`), the avatar image is
+also downloaded during registration and passed as `additionalData.avatarFile`
+(`{ name, mimeType, size, data: Buffer }`), so it can be mapped to a model field or stored via the file service. The
+download is best-effort: failures are logged and registration proceeds without the file.
 
 ### Client-side OAuth2 integration example
 

package/skill/references/storage.md

@@ -1,8 +1,8 @@
 # Storage
 
-The storage module handles file persistence: storing, streaming, and deleting binary content. The default
-implementation (`FilesystemStorage`) writes files to a local directory using a configurable name pattern. The module
-supports range-based streaming for efficient large-file delivery (e.g., video, audio).
+The storage module handles file persistence: storing, streaming, and deleting binary content. The default implementation
+(`FilesystemStorage`) writes files to a local directory using a configurable name pattern. The module supports
+range-based streaming for efficient large-file delivery (e.g., video, audio).
 
 ## Injecting Storage
 
@@ -221,6 +221,35 @@ export class PostService {
 }
 ```
 
+### File integrity (checksum)
+
+When a file is uploaded through `FileService.saveFile()` (or the resource file upload routes), a **SHA-256 checksum**
+(hex-encoded) of the stored content is calculated during the upload and persisted on the `File` record in the
+`checksum` field. The checksum is calculated over the exact bytes written to storage (i.e., after any configured image
+processing), so it can be used at any later point to verify that the file on disk has not been modified or corrupted.
+
+The checksum is included in file API responses, so clients can verify downloaded content against it.
+
+To verify a file's integrity, recalculate the checksum with the `makeHash` utility from `@appweaver/common` and
+compare it with the stored value:
+
+```ts
+import { createReadStream } from 'node:fs';
+import { makeHash } from '@appweaver/common';
+
+// From a readable stream (no memory buffering, works for large files) — returns a promise
+const checksum = await makeHash(createReadStream('/path/to/stored/file'));
+
+// Or from a Buffer / string — returns the hash synchronously
+// const checksum = makeHash(downloadedBuffer);
+
+if (checksum !== file.checksum) {
+  throw new Error(`File ${file.name} has been modified or corrupted`);
+}
+```
+
+Stored file checksums always use the defaults: **`sha256` + `hex`**.
+
 ### Streaming a file
 
 `FileService.stream()` handles authorization checks (public, private, or protected) and range-based requests