@appsemble/node-utils 0.36.10 → 0.37.0

package/README.md

@@ -1,9 +1,9 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.36.10/config/assets/logo.svg) Appsemble Node Utilities
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.37.0/config/assets/logo.svg) Appsemble Node Utilities
 
 > NodeJS utilities used by Appsemble internally.
 
 [![npm](https://img.shields.io/npm/v/@appsemble/node-utils)](https://www.npmjs.com/package/@appsemble/node-utils)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.36.10/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.36.10)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.37.0/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.37.0)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Table of Contents
@@ -26,5 +26,5 @@ compatibility is not guaranteed.
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.36.10/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.37.0/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/index.d.ts

@@ -21,6 +21,7 @@ export * from './render.js';
 export * from './getAppsembleMessages.js';
 export * from './odata.js';
 export * from './resource.js';
+export * from './resourceEtag.js';
 export * from './app.js';
 export * from './uploadValidation.js';
 export * from './mergeMessages.js';
@@ -48,3 +49,4 @@ export * from './createUser.js';
 export * from './deleteUser.js';
 export * from './updateSubscription.js';
 export * from './server/utils/ssrf.js';
+export { appWideGroupId, getSingleGroupId } from './server/utils/resources.js';

package/index.js

@@ -21,6 +21,7 @@ export * from './render.js';
 export * from './getAppsembleMessages.js';
 export * from './odata.js';
 export * from './resource.js';
+export * from './resourceEtag.js';
 export * from './app.js';
 export * from './uploadValidation.js';
 export * from './mergeMessages.js';
@@ -48,4 +49,5 @@ export * from './createUser.js';
 export * from './deleteUser.js';
 export * from './updateSubscription.js';
 export * from './server/utils/ssrf.js';
+export { appWideGroupId, getSingleGroupId } from './server/utils/resources.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/node-utils",
-  "version": "0.36.10",
+  "version": "0.37.0",
   "description": "NodeJS utilities used by Appsemble internally.",
   "keywords": [
     "app",
@@ -40,9 +40,9 @@
     "test": "vitest"
   },
   "dependencies": {
-    "@appsemble/lang-sdk": "0.36.10",
-    "@appsemble/types": "0.36.10",
-    "@appsemble/utils": "0.36.10",
+    "@appsemble/lang-sdk": "0.37.0",
+    "@appsemble/types": "0.37.0",
+    "@appsemble/utils": "0.37.0",
     "@formatjs/fast-memoize": "^2.0.0",
     "@fortawesome/fontawesome-free": "^6.0.0",
     "@inquirer/prompts": "^8.0.0",

package/resource.d.ts

@@ -1,10 +1,10 @@
 import { type AppDefinition, type ResourceDefinition } from '@appsemble/lang-sdk';
-import { type Resource as ResourceType } from '@appsemble/types';
+import { type App, type Resource as ResourceType } from '@appsemble/types';
 import { type PreValidatePropertyFunction } from 'jsonschema';
 import { type Context, type DefaultContext, type DefaultState, type ParameterizedContext } from 'koa';
 import { type JsonValue } from 'type-fest';
-import { type PreparedAsset, TempFile } from './index.js';
-export declare function stripResource({ $author, $created, $editor, $ephemeral, $group, $seed, $updated, ...data }: ResourceType): Record<string, unknown>;
+import { type GetAppResourcesParams, type PreparedAsset, TempFile } from './index.js';
+export declare function stripResource({ $author, $created, $editor, $ephemeral, $etag, $group, $seed, $updated, ...data }: ResourceType): Record<string, unknown>;
 /**
  * Works on a resource, which has been processed on the server by the streamParser
  *
@@ -68,3 +68,19 @@ export declare function processResourceBody(ctx: Context | ParameterizedContext<
     id: string;
     name?: string;
 }[], isPatch?: boolean, resourceBody?: SerializedServerResourceBody): Promise<[Record<string, unknown> | Record<string, unknown>[], PreparedAsset[], string[]]>;
+/**
+ * Validate that the references declared in the resource definition point at existing resources.
+ *
+ * Reference properties which hold no value are skipped. Expired resources are treated as
+ * non-existent. The referenced ids are collected per referenced resource type, so each type is
+ * checked using a single lookup, even when multiple resources are submitted at once.
+ *
+ * If a reference is broken, an HTTP 400 error naming the offending property path is thrown.
+ *
+ * @param ctx The Koa context used to throw back the error response.
+ * @param app The app the resources belong to.
+ * @param definition The definition of the resource type being created or updated.
+ * @param processedBody One or more resources as processed by `processResourceBody`.
+ * @param getAppResources The function used to look up resources of the referenced types.
+ */
+export declare function validateResourceReferences(ctx: Context, app: App, definition: ResourceDefinition, processedBody: Record<string, unknown> | Record<string, unknown>[], getAppResources: (params: GetAppResourcesParams) => Promise<ResourceType[]>): Promise<void>;

package/resource.js

@@ -5,10 +5,10 @@ import { ValidationError, Validator } from 'jsonschema';
 import { partition } from 'lodash-es';
 import parseDuration from 'parse-duration';
 import { preProcessCSV } from './csv.js';
-import { handleValidatorResult, TempFile } from './index.js';
+import { handleValidatorResult, TempFile, } from './index.js';
 import { throwKoaError } from './koa.js';
 import { AssetUploadValidationError, validateUploadedFile } from './uploadValidation.js';
-export function stripResource({ $author, $created, $editor, $ephemeral, $group, $seed, $updated, ...data }) {
+export function stripResource({ $author, $created, $editor, $ephemeral, $etag, $group, $seed, $updated, ...data }) {
     return data;
 }
 /**
@@ -232,9 +232,10 @@ export async function processResourceBody(ctx, definition, knownAssetIds = [], k
         }
         return num >= 0 && num < assets.length;
     };
+    const isPatchRequest = ctx.request?.method === 'PATCH' || isPatch;
     const patchedSchema = {
         ...definition.schema,
-        required: ctx.request?.method === 'PATCH' || isPatch ? [] : definition.schema.required,
+        required: isPatchRequest ? [] : definition.schema.required,
         properties: {
             ...definition.schema.properties,
             id: { type: 'integer' },
@@ -266,7 +267,8 @@ export async function processResourceBody(ctx, definition, knownAssetIds = [], k
         base: '#',
         preValidateProperty,
         nestedErrors: true,
-        rewrite(value, { format, oneOf }, options, { path }) {
+        rewrite(value, propertySchema, options, { path }) {
+            const { format, oneOf } = propertySchema;
             let propertyName;
             if (Array.isArray(resource) && path.length === 2 && typeof path[0] === 'number') {
                 propertyName = path[1];
@@ -302,6 +304,14 @@ export async function processResourceBody(ctx, definition, knownAssetIds = [], k
                 if (propertyName === '$clonable') {
                     return definition.clonable;
                 }
+                // Materialize schema property defaults for missing values. Patch requests skip this,
+                // because a missing property there means the stored value is kept.
+                const defaultValue = propertySchema.default;
+                if (!isPatchRequest && defaultValue !== undefined) {
+                    return typeof defaultValue === 'object' && defaultValue != null
+                        ? structuredClone(defaultValue)
+                        : defaultValue;
+                }
                 return;
             }
             if (format !== 'binary' && !oneOf?.some((s) => s.format === 'binary')) {
@@ -334,4 +344,82 @@ export async function processResourceBody(ctx, definition, knownAssetIds = [], k
     handleValidatorResult(ctx, result, 'Resource validation failed');
     return [resource, preparedAssets, knownAssetIds.filter((id) => !reusedAssets.has(id))];
 }
+/**
+ * Validate that the references declared in the resource definition point at existing resources.
+ *
+ * Reference properties which hold no value are skipped. Expired resources are treated as
+ * non-existent. The referenced ids are collected per referenced resource type, so each type is
+ * checked using a single lookup, even when multiple resources are submitted at once.
+ *
+ * If a reference is broken, an HTTP 400 error naming the offending property path is thrown.
+ *
+ * @param ctx The Koa context used to throw back the error response.
+ * @param app The app the resources belong to.
+ * @param definition The definition of the resource type being created or updated.
+ * @param processedBody One or more resources as processed by `processResourceBody`.
+ * @param getAppResources The function used to look up resources of the referenced types.
+ */
+export async function validateResourceReferences(ctx, app, definition, processedBody, getAppResources) {
+    const references = Object.entries(definition.references ?? {});
+    if (!references.length) {
+        return;
+    }
+    const resources = Array.isArray(processedBody) ? processedBody : [processedBody];
+    const referencedIds = new Map();
+    for (const [propertyName, reference] of references) {
+        for (const resource of resources) {
+            for (const value of [resource[propertyName]].flat()) {
+                if (value == null || value === '') {
+                    continue;
+                }
+                const id = typeof value === 'string' ? Number(value) : value;
+                if (typeof id === 'number' && Number.isInteger(id)) {
+                    if (!referencedIds.has(reference.resource)) {
+                        referencedIds.set(reference.resource, new Set());
+                    }
+                    referencedIds.get(reference.resource).add(id);
+                }
+            }
+        }
+    }
+    const existingIds = new Map();
+    await Promise.all([...referencedIds].map(async ([type, ids]) => {
+        const existing = await getAppResources({
+            app,
+            context: ctx,
+            type,
+            findOptions: {
+                where: {
+                    and: [
+                        { type },
+                        { or: [...ids].map((id) => ({ id })) },
+                        { expires: { or: [{ gt: new Date() }, null] } },
+                    ],
+                },
+            },
+        });
+        existingIds.set(type, new Set(existing.map((resource) => Number(resource.id))));
+    }));
+    const errors = [];
+    for (const [propertyName, reference] of references) {
+        for (const [index, resource] of resources.entries()) {
+            for (const value of [resource[propertyName]].flat()) {
+                if (value == null || value === '') {
+                    continue;
+                }
+                const id = typeof value === 'string' ? Number(value) : value;
+                if (typeof id === 'number' && existingIds.get(reference.resource)?.has(id)) {
+                    continue;
+                }
+                errors.push(new ValidationError(`does not reference an existing resource of type ${reference.resource}`, value, undefined, Array.isArray(processedBody) ? [index, propertyName] : [propertyName]));
+            }
+        }
+    }
+    if (errors.length) {
+        if (ctx.response === undefined) {
+            throw new Error('Resource validation failed', { cause: errors });
+        }
+        throwKoaError(ctx, 400, 'Resource validation failed', { errors });
+    }
+}
 //# sourceMappingURL=resource.js.map

package/resourceEtag.d.ts

@@ -0,0 +1,19 @@
+import { type Context } from 'koa';
+import { AppsembleError } from './AppsembleError.js';
+export declare function createResourceEtag(resource: Record<string, unknown>): string;
+export declare function addResourceEtag<T extends Record<string, unknown>>(resource: T): T & {
+    $etag: string;
+};
+export declare function matchesResourceIfMatch(ifMatch: string | string[] | undefined, currentEtag: string): boolean;
+export declare function setResourceEtagHeader(ctx: Context, resource: Record<string, unknown> | null | undefined): void;
+export declare class ResourcePreconditionFailedError extends AppsembleError {
+    readonly data: {
+        code: 'RESOURCE_PRECONDITION_FAILED';
+        resourceId: number | string;
+        resourceType: string;
+    };
+    readonly error = "Precondition Failed";
+    readonly statusCode = 412;
+    constructor(resourceType: string, resourceId: number | string);
+}
+export declare function throwResourcePreconditionFailedKoaError(ctx: Context, resourceType: string, resourceId: number | string): never;

package/resourceEtag.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import sortKeys from 'sort-keys';
+import { AppsembleError } from './AppsembleError.js';
+import { throwKoaError } from './koa.js';
+// Server-managed metadata keys that are echoed in resource responses but are not
+// part of the resource's identity for ETag purposes. Stripped only at the top
+// level; nested user data may legitimately contain keys with the same names.
+const ignoredEtagFields = new Set(['$author', '$editor', '$etag', '$group', '$seed', '$ephemeral']);
+function canonicalize(value) {
+    if (value instanceof Date) {
+        return value.toJSON();
+    }
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value && typeof value === 'object') {
+        return sortKeys(Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            canonicalize(entry),
+        ])), { deep: true });
+    }
+    return value;
+}
+export function createResourceEtag(resource) {
+    const stripped = {};
+    for (const [key, value] of Object.entries(resource)) {
+        if (!ignoredEtagFields.has(key)) {
+            stripped[key] = value;
+        }
+    }
+    const canonicalResource = JSON.stringify(canonicalize(stripped));
+    const hash = createHash('sha256').update(canonicalResource, 'utf8').digest('base64url');
+    return `"${hash}"`;
+}
+export function addResourceEtag(resource) {
+    return {
+        ...resource,
+        $etag: createResourceEtag(resource),
+    };
+}
+// RFC 7232 §3.1: If-Match uses the strong-comparison function, so weak
+// validators (prefixed with `W/`) must not match. Tokens are split with a
+// quoted-string-aware parser instead of a naive `,` split.
+function parseIfMatchValue(ifMatch) {
+    if (ifMatch === '*') {
+        return ['*'];
+    }
+    const tokens = [];
+    let i = 0;
+    while (i < ifMatch.length) {
+        while (i < ifMatch.length &&
+            (ifMatch[i] === ' ' || ifMatch[i] === ',' || ifMatch[i] === '\t')) {
+            i += 1;
+        }
+        if (i >= ifMatch.length) {
+            break;
+        }
+        // Skip any leading weak prefix; strong comparison rejects it.
+        let weak = false;
+        if (ifMatch[i] === 'W' && ifMatch[i + 1] === '/') {
+            weak = true;
+            i += 2;
+        }
+        if (ifMatch[i] !== '"') {
+            // Malformed token; skip until next comma.
+            while (i < ifMatch.length && ifMatch[i] !== ',') {
+                i += 1;
+            }
+            continue;
+        }
+        const start = i;
+        i += 1;
+        while (i < ifMatch.length && ifMatch[i] !== '"') {
+            i += 1;
+        }
+        if (i >= ifMatch.length) {
+            break;
+        }
+        i += 1;
+        if (!weak) {
+            tokens.push(ifMatch.slice(start, i));
+        }
+    }
+    return tokens;
+}
+export function matchesResourceIfMatch(ifMatch, currentEtag) {
+    if (!ifMatch) {
+        return true;
+    }
+    const values = new Set((Array.isArray(ifMatch) ? ifMatch : [ifMatch]).flatMap(parseIfMatchValue));
+    return values.has('*') || values.has(currentEtag);
+}
+export function setResourceEtagHeader(ctx, resource) {
+    if (!resource) {
+        return;
+    }
+    const etag = typeof resource.$etag === 'string' ? resource.$etag : createResourceEtag(resource);
+    ctx.set('ETag', etag);
+}
+export class ResourcePreconditionFailedError extends AppsembleError {
+    constructor(resourceType, resourceId) {
+        super('This resource has changed since it was loaded. Fetch the latest version and try again.');
+        this.error = 'Precondition Failed';
+        this.statusCode = 412;
+        this.name = 'ResourcePreconditionFailedError';
+        this.data = {
+            code: 'RESOURCE_PRECONDITION_FAILED',
+            resourceId,
+            resourceType,
+        };
+    }
+}
+export function throwResourcePreconditionFailedKoaError(ctx, resourceType, resourceId) {
+    const error = new ResourcePreconditionFailedError(resourceType, resourceId);
+    throwKoaError(ctx, error.statusCode, error.message, error.data);
+}
+//# sourceMappingURL=resourceEtag.js.map

package/server/controllers/common/apps/resources/createCountAppResourcesController.js

@@ -1,20 +1,27 @@
-import { generateResourceQuery } from '../../../../utils/resources.js';
+import { generateResourceQuery, getGroupIdWhere } from '../../../../utils/resources.js';
 export function createCountAppResourcesController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceType }, queryParams: { $own, selectedGroupId }, user: authSubject, } = ctx;
-        const { checkAppPermissions, getApp, getAppResources } = options;
+        const { checkAppPermissions, getAllowedGroups, getApp, getAppResources } = options;
         const app = await getApp({
             context: ctx,
             query: { where: { id: appId }, attributes: ['demoMode', 'id'] },
         });
-        await checkAppPermissions({
+        const permissions = [
+            $own ? `$resource:${resourceType}:own:query` : `$resource:${resourceType}:query`,
+        ];
+        // Across multiple selected groups the permission acts as a filter: only the
+        // groups the subject may query are counted. When no selected group is
+        // queryable, the strict permission check throws its usual 403.
+        const allowedGroups = await getAllowedGroups({
             context: ctx,
-            permissions: [
-                $own ? `$resource:${resourceType}:own:query` : `$resource:${resourceType}:query`,
-            ],
+            permissions,
             app,
             groupId: selectedGroupId,
         });
+        if (!allowedGroups.length) {
+            await checkAppPermissions({ context: ctx, permissions, app, groupId: selectedGroupId });
+        }
         const { where } = generateResourceQuery(ctx, options);
         const findOptions = {
             attributes: ['id'],
@@ -23,7 +30,7 @@ export function createCountAppResourcesController(options) {
                     where || {},
                     {
                         type: resourceType,
-                        GroupId: selectedGroupId ?? null,
+                        GroupId: getGroupIdWhere(allowedGroups.length ? allowedGroups : selectedGroupId),
                         expires: { or: [{ gt: new Date() }, null] },
                         ...(app.demoMode ? { seed: false, ephemeral: true } : {}),
                         ...($own ? { AuthorId: authSubject?.id } : {}),

package/server/controllers/common/apps/resources/createCreateAppResourceController.js

@@ -3,7 +3,7 @@ import { copyFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { getResourceDefinition, processResourceBody, } from '../../../../../index.js';
+import { getResourceDefinition, getSingleGroupId, processResourceBody, setResourceEtagHeader, validateResourceReferences, } from '../../../../../index.js';
 function clonePreparedAssets(preparedAssets) {
     return Promise.all(preparedAssets.map(async (asset) => {
         const path = join(tmpdir(), `${Date.now()}-${randomUUID()}`);
@@ -26,7 +26,8 @@ function clonePreparedAssets(preparedAssets) {
 export function createCreateAppResourceController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceType }, query, queryParams: { selectedGroupId }, } = ctx;
-        const { checkAppPermissions, createAppResourcesWithAssets, getApp, getAppAssets } = options;
+        const groupId = getSingleGroupId(selectedGroupId);
+        const { checkAppPermissions, createAppResourcesWithAssets, getApp, getAppAssets, getAppResources, } = options;
         const app = await getApp({
             context: ctx,
             query: { attributes: ['id', 'demoMode', 'definition'], where: { id: appId } },
@@ -35,7 +36,8 @@ export function createCreateAppResourceController(options) {
             context: ctx,
             permissions: [`$resource:${resourceType}:create`],
             app,
-            groupId: selectedGroupId,
+            // The resource is created in a single group; authorize against that group.
+            groupId,
         });
         const resourceDefinition = getResourceDefinition(app.definition, resourceType, ctx);
         const appAssets = await getAppAssets({ app, context: ctx });
@@ -44,6 +46,7 @@ export function createCreateAppResourceController(options) {
             ctx.body = [];
             return;
         }
+        await validateResourceReferences(ctx, app, resourceDefinition, processedBody, getAppResources);
         const resources = Array.isArray(processedBody) ? processedBody : [processedBody];
         if (!(ctx.client && 'app' in ctx.client) && query?.seed === 'true') {
             const preparedSeedAssets = app.demoMode
@@ -77,7 +80,7 @@ export function createCreateAppResourceController(options) {
             }
             const createdSeedResources = await createAppResourcesWithAssets({
                 app,
-                groupId: selectedGroupId,
+                groupId,
                 context: ctx,
                 resources: preparedSeedResources,
                 preparedAssets: preparedSeedAssets,
@@ -86,12 +89,15 @@ export function createCreateAppResourceController(options) {
             });
             if (!app.demoMode) {
                 ctx.body = Array.isArray(processedBody) ? createdSeedResources : createdSeedResources[0];
+                if (!Array.isArray(ctx.body)) {
+                    setResourceEtagHeader(ctx, ctx.body);
+                }
                 return;
             }
         }
         const createdResources = await createAppResourcesWithAssets({
             app,
-            groupId: selectedGroupId,
+            groupId,
             context: ctx,
             resources: resources.map((resource) => ({
                 ...resource,
@@ -104,6 +110,9 @@ export function createCreateAppResourceController(options) {
             options,
         });
         ctx.body = Array.isArray(processedBody) ? createdResources : createdResources[0];
+        if (!Array.isArray(ctx.body)) {
+            setResourceEtagHeader(ctx, ctx.body);
+        }
     };
 }
 //# sourceMappingURL=createCreateAppResourceController.js.map

package/server/controllers/common/apps/resources/createDeleteAppResourceController.js

@@ -1,4 +1,5 @@
 import { assertKoaCondition } from '@appsemble/node-utils';
+import { appWideGroupId, getGroupIdWhere } from '../../../../utils/resources.js';
 export function createDeleteAppResourceController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceId, resourceType }, queryParams: { selectedGroupId }, user: authSubject, } = ctx;
@@ -11,7 +12,7 @@ export function createDeleteAppResourceController(options) {
             where: {
                 id: resourceId,
                 type: resourceType,
-                GroupId: selectedGroupId ?? null,
+                GroupId: getGroupIdWhere(selectedGroupId),
                 expires: { or: [{ gt: new Date() }, { eq: null }] },
                 ...(app.demoMode ? { seed: false, ephemeral: true } : {}),
             },
@@ -24,6 +25,8 @@ export function createDeleteAppResourceController(options) {
             findOptions,
         });
         assertKoaCondition(resource != null, ctx, 404, 'Resource not found');
+        // The resource is searched across the selected groups; authorization is
+        // then scoped to the group the resource actually belongs to.
         await checkAppPermissions({
             context: ctx,
             permissions: [
@@ -32,7 +35,7 @@ export function createDeleteAppResourceController(options) {
                     : `$resource:${resourceType}:delete`,
             ],
             app,
-            groupId: selectedGroupId,
+            groupId: resource.$group?.id ?? appWideGroupId,
         });
         await deleteAppResource({
             app,
@@ -40,6 +43,8 @@ export function createDeleteAppResourceController(options) {
             id: resourceId,
             type: resourceType,
             options,
+            lockWhere: findOptions.where,
+            ifMatch: ctx.get('If-Match') || undefined,
         });
         ctx.status = 204;
     };

package/server/controllers/common/apps/resources/createGetAppResourceByIdController.js

@@ -1,5 +1,6 @@
 import { defaultLocale, remap } from '@appsemble/lang-sdk';
-import { assertKoaCondition, getRemapperContext, getResourceDefinition, } from '@appsemble/node-utils';
+import { assertKoaCondition, getRemapperContext, getResourceDefinition, setResourceEtagHeader, } from '@appsemble/node-utils';
+import { appWideGroupId, getGroupIdWhere } from '../../../../utils/resources.js';
 export function createGetAppResourceByIdController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceId, resourceType }, queryParams: { selectedGroupId, view }, user: authSubject, } = ctx;
@@ -12,7 +13,7 @@ export function createGetAppResourceByIdController(options) {
             where: {
                 id: resourceId,
                 type: resourceType,
-                GroupId: selectedGroupId ?? null,
+                GroupId: getGroupIdWhere(selectedGroupId),
                 expires: { or: [{ gt: new Date() }, null] },
                 ...(app.demoMode ? { seed: false, ephemeral: true } : {}),
             },
@@ -25,6 +26,8 @@ export function createGetAppResourceByIdController(options) {
             findOptions,
         });
         assertKoaCondition(resource != null, ctx, 404, 'Resource not found');
+        // The resource is searched across the selected groups; authorization is
+        // then scoped to the group the resource actually belongs to.
         await checkAppPermissions({
             context: ctx,
             permissions: [
@@ -35,14 +38,19 @@ export function createGetAppResourceByIdController(options) {
                         : `$resource:${resourceType}:get`,
             ],
             app,
-            groupId: selectedGroupId,
+            groupId: resource.$group?.id ?? appWideGroupId,
         });
         if (view) {
             const context = await getRemapperContext(app, app.definition.defaultLanguage || defaultLocale, options, ctx);
             const resourceDefinition = getResourceDefinition(app.definition, resourceType, ctx, view);
+            // No ETag for view responses: the response body is a remapped projection
+            // that does not uniquely identify the raw resource representation, so a
+            // shared ETag across views would violate RFC 7232's representation-
+            // identity requirement and confuse conditional GETs/caches.
             ctx.body = remap(resourceDefinition.views?.[view].remap ?? null, resource, context);
             return;
         }
+        setResourceEtagHeader(ctx, resource);
         ctx.body = resource;
     };
 }

package/server/controllers/common/apps/resources/createQueryAppResourcesController.js

@@ -1,28 +1,35 @@
 import { defaultLocale, remap } from '@appsemble/lang-sdk';
 import { getRemapperContext, getResourceDefinition, } from '@appsemble/node-utils';
-import { generateResourceQuery } from '../../../../utils/resources.js';
+import { generateResourceQuery, getGroupIdWhere } from '../../../../utils/resources.js';
 export function createQueryAppResourcesController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceType }, queryParams: { $own, $select, $skip, $top, selectedGroupId, view }, user: authSubject, } = ctx;
-        const { checkAppPermissions, getApp, getAppResources } = options;
+        const { checkAppPermissions, getAllowedGroups, getApp, getAppResources } = options;
         const app = await getApp({
             context: ctx,
             query: { attributes: ['definition', 'demoMode', 'id', 'template'], where: { id: appId } },
         });
         const resourceDefinition = getResourceDefinition(app.definition, resourceType, ctx, view);
         const { order, where } = generateResourceQuery(ctx, options, resourceDefinition);
-        await checkAppPermissions({
+        const permissions = [
+            $own
+                ? `$resource:${resourceType}:own:query`
+                : view
+                    ? `$resource:${resourceType}:query:${view}`
+                    : `$resource:${resourceType}:query`,
+        ];
+        // Across multiple selected groups the permission acts as a filter: only the
+        // groups the subject may query are returned. When no selected group is
+        // queryable, the strict permission check throws its usual 403.
+        const allowedGroups = await getAllowedGroups({
             context: ctx,
-            permissions: [
-                $own
-                    ? `$resource:${resourceType}:own:query`
-                    : view
-                        ? `$resource:${resourceType}:query:${view}`
-                        : `$resource:${resourceType}:query`,
-            ],
+            permissions,
             app,
             groupId: selectedGroupId,
         });
+        if (!allowedGroups.length) {
+            await checkAppPermissions({ context: ctx, permissions, app, groupId: selectedGroupId });
+        }
         const isSameOrigin = ctx?.headers?.origin === ctx?.headers?.host;
         const findOptions = {
             limit: $top,
@@ -33,7 +40,7 @@ export function createQueryAppResourcesController(options) {
                     where,
                     {
                         type: resourceType,
-                        GroupId: selectedGroupId ?? null,
+                        GroupId: getGroupIdWhere(allowedGroups.length ? allowedGroups : selectedGroupId),
                         expires: { or: [{ gt: new Date() }, null] },
                         ...(app.demoMode && !isSameOrigin ? { seed: false, ephemeral: true } : {}),
                         ...($own ? { AuthorId: authSubject?.id } : {}),

package/server/controllers/common/apps/resources/createUpdateAppResourceController.js

@@ -1,8 +1,9 @@
-import { assertKoaCondition, getResourceDefinition, processResourceBody, } from '@appsemble/node-utils';
+import { assertKoaCondition, getResourceDefinition, getSingleGroupId, processResourceBody, setResourceEtagHeader, validateResourceReferences, } from '@appsemble/node-utils';
 export function createUpdateAppResourceController(options) {
     return async (ctx) => {
         const { pathParams: { appId, resourceId, resourceType }, queryParams: { selectedGroupId }, user: authSubject, } = ctx;
-        const { checkAppPermissions, getApp, getAppAssets, getAppResource, updateAppResource } = options;
+        const groupId = getSingleGroupId(selectedGroupId);
+        const { checkAppPermissions, getApp, getAppAssets, getAppResource, getAppResources, updateAppResource, } = options;
         const app = await getApp({
             context: ctx,
             query: { attributes: ['id', 'demoMode', 'definition', 'template'], where: { id: appId } },
@@ -11,7 +12,7 @@ export function createUpdateAppResourceController(options) {
             where: {
                 id: resourceId,
                 type: resourceType,
-                GroupId: selectedGroupId ?? null,
+                GroupId: groupId,
                 expires: { or: [{ gt: new Date() }, null] },
                 ...(app.demoMode ? { seed: false, ephemeral: true } : {}),
             },
@@ -32,11 +33,13 @@ export function createUpdateAppResourceController(options) {
                     : `$resource:${resourceType}:update`,
             ],
             app,
-            groupId: selectedGroupId,
+            // The operation acts on a single group; authorize against that group only.
+            groupId,
         });
         const appAssets = await getAppAssets({ context: ctx, app });
         const resourceDefinition = getResourceDefinition(app.definition, resourceType, ctx);
         const [processedBody, preparedAssets, deletedAssetIds] = await processResourceBody(ctx, resourceDefinition, appAssets.filter((asset) => asset.resourceId === resourceId).map((asset) => asset.id), oldResource.expires, appAssets.map((asset) => ({ id: asset.id, name: asset.name })));
+        await validateResourceReferences(ctx, app, resourceDefinition, processedBody, getAppResources);
         const resources = Array.isArray(processedBody) ? processedBody : [processedBody];
         ctx.body = await updateAppResource({
             app,
@@ -48,7 +51,10 @@ export function createUpdateAppResourceController(options) {
             deletedAssetIds,
             resourceDefinition,
             options,
+            lockWhere: findOptions.where,
+            ifMatch: ctx.get('If-Match') || undefined,
         });
+        setResourceEtagHeader(ctx, ctx.body);
     };
 }
 //# sourceMappingURL=createUpdateAppResourceController.js.map

package/server/types.d.ts

@@ -112,7 +112,7 @@ declare module 'koas-parameters' {
         roles?: string;
         includeMessages: boolean;
         demo: boolean;
-        selectedGroupId: number;
+        selectedGroupId: number[];
         $own: boolean;
         delimiter?: string;
         email: string;
@@ -249,13 +249,13 @@ export interface CheckUserOrganizationPermissionsParams {
 export interface CheckAuthSubjectAppPermissionsParams {
     context: ParameterizedContext<DefaultState, DefaultContextInterface, any>;
     app: App;
-    groupId?: number;
+    groupId?: number | number[] | null;
     permissions: CustomAppPermission[];
 }
 export interface CheckAppPermissionsParams {
     context: ParameterizedContext<DefaultState, DefaultContextInterface, any>;
     app: App;
-    groupId?: number;
+    groupId?: number | number[] | null;
     permissions: CustomAppPermission[];
 }
 export interface ReloadUserParams {
@@ -288,7 +288,7 @@ export interface CreateAppResourcesWithAssetsParams extends GetAppSubEntityParam
     preparedAssets: PreparedAsset[];
     resourceType: string;
     options: Options;
-    groupId?: number;
+    groupId?: number | null;
 }
 export interface UpdateAppResourceParams extends GetAppSubEntityParams {
     id: number | string;
@@ -298,12 +298,33 @@ export interface UpdateAppResourceParams extends GetAppSubEntityParams {
     deletedAssetIds: string[];
     type: string;
     options: Options;
+    /**
+     * The same where clause used by the controller's pre-lock fetch. Re-applied
+     * inside the SELECT FOR UPDATE so the lock cannot widen the row set (e.g.
+     * picking up an expired row or one whose GroupId or seed flag changed
+     * between the unlocked read and the lock).
+     */
+    lockWhere: WhereOptions;
+    /**
+     * The `If-Match` header value parsed out of the request, if any.
+     */
+    ifMatch?: string;
 }
 export interface DeleteAppResourceParams extends GetAppSubEntityParams {
     id: number | string;
     type: string;
     whereOptions?: WhereOptions;
     options: Options;
+    /**
+     * Where-clause used by the controller's pre-lock fetch. Re-applied inside
+     * the lock so a concurrent writer cannot widen the row set between the read
+     * and the delete.
+     */
+    lockWhere?: WhereOptions;
+    /**
+     * The `If-Match` header value parsed out of the request, if any.
+     */
+    ifMatch?: string;
 }
 export interface CreateAppAssetParams extends GetAppSubEntityParams {
     payload: {
@@ -412,6 +433,7 @@ export interface Options {
     checkUserOrganizationPermissions: (params: CheckUserOrganizationPermissionsParams) => Promise<void>;
     checkAuthSubjectAppPermissions: (params: CheckAuthSubjectAppPermissionsParams) => Promise<void>;
     checkAppPermissions: (params: CheckAppPermissionsParams) => Promise<void>;
+    getAllowedGroups: (params: CheckAppPermissionsParams) => Promise<number[]>;
     reloadUser: (params: ReloadUserParams) => Promise<Record<string, any>>;
     parseQuery: (params: ParseQueryParams) => ParsedQuery;
     getAppResource: (params: GetAppResourceParams) => Promise<Resource | null>;

package/server/utils/resources.d.ts

@@ -2,6 +2,30 @@ import { type ResourceDefinition } from '@appsemble/lang-sdk';
 import { type App } from '@appsemble/types';
 import { type Context } from 'koa';
 import { type Options, type OrderItem, type WhereOptions } from '../types.js';
+/**
+ * The `selectedGroupId` value representing the app-wide (ungrouped) scope, as
+ * opposed to a concrete group id.
+ */
+export declare const appWideGroupId = -1;
+/**
+ * Collapse a `selectedGroupId` selection to a single group for operations that
+ * are inherently scoped to one group (create, update, reorder).
+ *
+ * @param selectedGroupId The selected group ids from the query parameters.
+ * @returns The first concrete group id, or null for the app-wide scope.
+ */
+export declare function getSingleGroupId(selectedGroupId?: number[]): number | null;
+/**
+ * Build a resource `GroupId` filter for operations that may span multiple
+ * groups (query, delete).
+ *
+ * The app-wide scope (`appWideGroupId`, or an empty selection) matches
+ * resources without a group; concrete ids match resources in those groups.
+ *
+ * @param selectedGroupId The selected group ids from the query parameters.
+ * @returns A value for a resource `GroupId` where clause.
+ */
+export declare function getGroupIdWhere(selectedGroupId?: number[]): WhereOptions[string];
 export declare function generateResourceQuery(ctx: Context, { parseQuery }: Options, resourceDefinition?: ResourceDefinition): {
     order: OrderItem[];
     where: WhereOptions;

package/server/utils/resources.js

@@ -1,5 +1,39 @@
 import { throwKoaError } from '../../koa.js';
 import { logger } from '../../logger.js';
+/**
+ * The `selectedGroupId` value representing the app-wide (ungrouped) scope, as
+ * opposed to a concrete group id.
+ */
+export const appWideGroupId = -1;
+/**
+ * Collapse a `selectedGroupId` selection to a single group for operations that
+ * are inherently scoped to one group (create, update, reorder).
+ *
+ * @param selectedGroupId The selected group ids from the query parameters.
+ * @returns The first concrete group id, or null for the app-wide scope.
+ */
+export function getSingleGroupId(selectedGroupId = []) {
+    const [groupId] = selectedGroupId;
+    return groupId != null && groupId > 0 ? groupId : null;
+}
+/**
+ * Build a resource `GroupId` filter for operations that may span multiple
+ * groups (query, delete).
+ *
+ * The app-wide scope (`appWideGroupId`, or an empty selection) matches
+ * resources without a group; concrete ids match resources in those groups.
+ *
+ * @param selectedGroupId The selected group ids from the query parameters.
+ * @returns A value for a resource `GroupId` where clause.
+ */
+export function getGroupIdWhere(selectedGroupId = []) {
+    const groupIds = selectedGroupId.filter((id) => id > 0);
+    const includeUngrouped = selectedGroupId.length === 0 || selectedGroupId.includes(appWideGroupId);
+    if (!groupIds.length) {
+        return null;
+    }
+    return includeUngrouped ? { or: [{ in: groupIds }, null] } : { in: groupIds };
+}
 export function generateResourceQuery(ctx, { parseQuery }, resourceDefinition) {
     try {
         return parseQuery({