@appweaver/cli 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/cli",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Appweaver - the backend framework for AI-first development (@cli)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/skill/GUIDELINES.md

@@ -285,6 +285,13 @@ export async function createAdminUser(): Promise<void> {
 | `weaver update`               | Update all @appweaver/* packages          |
 | `weaver openapi`              | Generate OpenAPI specification            |
 
+## Testing
+
+- Test files must use the **`.test.ts`** extension.
+- Unit tests live in `test/unit/`, end-to-end tests in `test/e2e/`; name each file after the module it covers.
+- Add or update tests whenever a feature is added or existing behaviour changes, and run `npm run test` before
+  considering the task done.
+
 ## References
 
 - Application CLI (weaver): [cli.md](references/cli.md)

package/skill/SKILL.md

@@ -569,6 +569,9 @@ npm run test  # unit tests with coverage
 npm run e2e   # e2e tests
 ```
 
+Test files must use the **`.test.ts`** extension. Place unit tests in `test/unit/` and end-to-end tests in `test/e2e/`,
+naming each file after its module. Add or update tests whenever a feature is added or existing behaviour changes.
+
 ### Format code
 
 ```sh

package/skill/references/configuration.md

@@ -117,7 +117,7 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 | `SERVER_TRUST_PROXY`             | boolean  | `true`       | Trust `X-Forwarded-*` headers from reverse proxies.        |
 | `SERVER_REQUEST_LOGGING_ENABLED` | boolean  | `false`      | Enable HTTP request/response logging.                      |
 
-### Rate limiting (RATE*LIMIT*\*)
+### Rate limiting (RATE_LIMIT_\*)
 
 | Property                | Type      | Default   | Description                                                      |
 |-------------------------|-----------|-----------|------------------------------------------------------------------|
@@ -135,7 +135,7 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 | `SWAGGER_PATH`          | string  | `'/swagger'` | URL path for the Swagger UI.                |
 | `SWAGGER_HIDE_UNTAGGED` | boolean | `false`      | Hide untagged endpoints from documentation. |
 
-### Health check (HEALTH*CHECK*\*)
+### Health check (HEALTH_CHECK_\*)
 
 | Property                      | Type      | Default     | Description                                                   |
 |-------------------------------|-----------|-------------|---------------------------------------------------------------|
@@ -306,13 +306,14 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 
 ### File storage (STORAGE\_\*)
 
-| Property                     | Type    | Default                                        | Description                                   |
-|------------------------------|---------|------------------------------------------------|-----------------------------------------------|
-| `STORAGE_PATH`               | string  | `'./storage'`                                  | Base directory for file storage.              |
-| `STORAGE_NAME_PATTERN`       | string  | `'{name}-{hash}.{extension}'`                  | File naming pattern for stored files.         |
-| `STORAGE_CACHE_TTL`          | integer | `86400000`                                     | File storage cache TTL in milliseconds. (24h) |
-| `STORAGE_FILES_ROUTE_PREFIX` | string  | `/files`                                       | URL prefix for file access routes.            |
-| `STORAGE_PROVIDER`           | string  | `'@appweaver/core/storage/filesystem-storage'` | Storage provider implementation path.         |
+| Property                     | Type    | Default                                        | Description                                                                                                                                                                                                                                                                               |
+|------------------------------|---------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `STORAGE_PATH`               | string  | `'./storage'`                                  | Base directory for file storage.                                                                                                                                                                                                                                                          |
+| `STORAGE_RESERVED_PATHS`     | array   | `['keys']`                                     | Paths inside the storage directory that files can never be stored under. Each entry is a directory or a full file name relative to `STORAGE_PATH`, matched case-insensitively (no wildcards). Violations fail on startup for configured name patterns, and with a `400` error at runtime. |
+| `STORAGE_NAME_PATTERN`       | string  | `'{name}-{hash}.{extension}'`                  | File naming pattern for stored files.                                                                                                                                                                                                                                                     |
+| `STORAGE_CACHE_TTL`          | integer | `86400000`                                     | File storage cache TTL in milliseconds. (24h)                                                                                                                                                                                                                                             |
+| `STORAGE_FILES_ROUTE_PREFIX` | string  | `/files`                                       | URL prefix for file access routes.                                                                                                                                                                                                                                                        |
+| `STORAGE_PROVIDER`           | string  | `'@appweaver/core/storage/filesystem-storage'` | Storage provider implementation path.                                                                                                                                                                                                                                                     |
 
 ### Redis (REDIS\_\*)
 

package/skill/references/security.md

@@ -17,8 +17,8 @@ Appweaver supports four authentication methods that can be used independently or
 | API Key      | `SECURITY_API_KEY_ENABLED` | `x-api-key: <id><delimiter><secret>` |
 | OAuth2       | Per-provider flags         | Browser redirect flow                |
 
-When multiple methods are enabled, the authentication middleware tries each in order. A request is authenticated if
-any one method succeeds. If no credentials are present for any method, a 401 error is returned.
+When multiple methods are enabled, the authentication middleware tries each in order. A request is authenticated if any
+one method succeeds. If no credentials are present for any method, a 401 error is returned.
 
 ### Route authentication configuration
 
@@ -53,9 +53,11 @@ if `SECURITY_JWT_SECRET` is set.
 
 ### Key management
 
-- RSA 2048-bit key pair generated automatically if `SECURITY_JWT_AUTO_GENERATE_KEYS` is `true` and key files are
-  missing
+- RSA 2048-bit key pair generated automatically if `SECURITY_JWT_AUTO_GENERATE_KEYS` is `true` and key files are missing
 - Keys stored at `SECURITY_JWT_PUBLIC_KEY_PATH` and `SECURITY_JWT_PRIVATE_KEY_PATH` (default: `./storage/keys/`)
+- Generated keys are written with owner-only permissions (`0600` for the private key, `0700` for its directory)
+- The default `STORAGE_RESERVED_PATHS` value (`['keys']`) makes the `keys` directory unusable by the file storage layer,
+  so uploads can never overwrite the default key location
 - If `SECURITY_JWT_SECRET` is set, HMAC signing is used instead of RSA
 
 ### Token types and scopes
@@ -121,8 +123,8 @@ When enabled, requests with an `Authorization: Basic` header are authenticated a
 }
 ```
 
-Uses `@fastify/basic-auth` plugin. Extracts Base64-encoded `username:password` from the header and validates against
-the user's stored password hash.
+Uses `@fastify/basic-auth` plugin. Extracts Base64-encoded `username:password` from the header and validates against the
+user's stored password hash.
 
 ---
 
@@ -185,8 +187,8 @@ Default delimiter is `AK`, so a key looks like: `42AKa1b2c3d4e5f6...`
 
 ## OAuth2 authentication
 
-Appweaver supports OAuth2 login with Google, Facebook, and a custom OpenID Connect provider. All OAuth2 providers
-follow the same flow pattern.
+Appweaver supports OAuth2 login with Google, Facebook, and a custom OpenID Connect provider. All OAuth2 providers follow
+the same flow pattern.
 
 ### OAuth2 flow
 
@@ -385,9 +387,9 @@ export default createAuthService({
 });
 ```
 
-**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`
+**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.
 
@@ -716,8 +718,8 @@ Password validation is configurable via `SECURITY_PASSWORD_*` properties:
 
 ### Token invalidation on password change
 
-Both `change-password` and `reset-password` set `logoutAt` to the current timestamp, which invalidates all existing
-JWT tokens across all devices. The `change-password` endpoint returns new tokens so the current session stays active.
+Both `change-password` and `reset-password` set `logoutAt` to the current timestamp, which invalidates all existing JWT
+tokens across all devices. The `change-password` endpoint returns new tokens so the current session stays active.
 
 ---
 

package/skill/references/storage.md

@@ -125,23 +125,42 @@ Available placeholders:
 
 Example: storing `photo.jpg` produces `photo-c7d3a1f2.jpg`.
 
+Only the pattern itself may contain directory separators (e.g. `photos/{resourceId}/{name}.{extension}`). Every value
+substituted into it — including the uploaded file name — is reduced to a single path segment, so an upload can never
+introduce a subdirectory, a `..` traversal or a hidden file.
+
+---
+
+## Reserved paths
+
+`STORAGE_RESERVED_PATHS` (default `['keys']`, protecting the default JWT key location) lists paths inside
+`STORAGE_PATH` that files can never use. An entry is a directory (blocking everything inside it) or a full file name,
+relative to the storage root, and whole segments are matched case-insensitively.
+
+Configured `namePattern`s are validated on startup and abort the start; file paths resolved at upload, stream, or delete
+time are rejected with a `400` error.
+
 ---
 
 ## Configuration
 
-| Key                          | Type     | Default                                        | Description                                           |
-|------------------------------|----------|------------------------------------------------|-------------------------------------------------------|
-| `STORAGE_PATH`               | `string` | `'./storage'`                                  | Root directory where files are stored                 |
-| `STORAGE_NAME_PATTERN`       | `string` | `'{name}-{hash}.{extension}'`                  | Template for deriving the stored file name            |
-| `STORAGE_CACHE_TTL`          | `int`    | `86400000`                                     | Cache TTL for storage responses in milliseconds (24h) |
-| `STORAGE_FILES_ROUTE_PREFIX` | `string` | `/files`                                       | URL prefix for file access routes.                    |
-| `STORAGE_PROVIDER`           | `string` | `'@appweaver/core/storage/filesystem-storage'` | Path to the Storage implementation                    |
+| Key                          | Type       | Default                                        | Description                                           |
+|------------------------------|------------|------------------------------------------------|-------------------------------------------------------|
+| `STORAGE_PATH`               | `string`   | `'./storage'`                                  | Root directory where files are stored                 |
+| `STORAGE_RESERVED_PATHS`     | `string[]` | `['keys']`                                     | Paths inside the storage root that files cannot use   |
+| `STORAGE_NAME_PATTERN`       | `string`   | `'{name}-{hash}.{extension}'`                  | Template for deriving the stored file name            |
+| `STORAGE_CACHE_TTL`          | `int`      | `86400000`                                     | Cache TTL for storage responses in milliseconds (24h) |
+| `STORAGE_FILES_ROUTE_PREFIX` | `string`   | `/files`                                       | URL prefix for file access routes.                    |
+| `STORAGE_PROVIDER`           | `string`   | `'@appweaver/core/storage/filesystem-storage'` | Path to the Storage implementation                    |
 
 **`appweaver.json` example:**
 
 ```json
 {
   "STORAGE_PATH": "./uploads",
+  "STORAGE_RESERVED_PATHS": [
+    "keys"
+  ],
   "STORAGE_NAME_PATTERN": "{name}-{hash}.{extension}"
 }
 ```
@@ -230,8 +249,8 @@ processing), so it can be used at any later point to verify that the file on dis
 
 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:
+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';