objectstack-ai
diff --git a/‎.changeset/dispatcher-permission-denied-details-allowlist.md‎
Lines changed: 51 additions & 0 deletions b/‎.changeset/dispatcher-permission-denied-details-allowlist.md‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎packages/runtime/src/domains/data-permission-denied-envelope.test.ts‎
Lines changed: 237 additions & 0 deletions b/‎packages/runtime/src/domains/data-permission-denied-envelope.test.ts‎
Lines changed: 237 additions & 0 deletions
diff --git a/‎packages/runtime/src/http-dispatcher.ts‎
Lines changed: 46 additions & 2 deletions b/‎packages/runtime/src/http-dispatcher.ts‎
Lines changed: 46 additions & 2 deletions
@@ -0,0 +1,51 @@
+---
+"@objectstack/runtime": patch
+---
+
+fix(runtime): stop the dispatcher answering a permission denial's internal authorization payload (#7450)
+
+`plugin-security`'s object gate attaches
+`{ operation, object, positions, permissionSets }` to every
+`PermissionDeniedError`. The two HTTP transports disagreed about what to do with
+it. `@objectstack/rest`'s `mapDataError` never reads `error.details` — its 403
+body is `{ error, code, object? }`, and the `object` on it is the one the ROUTE
+named. The dispatcher's `dispatch()` catch spread the whole payload
+(`{ code: 'PERMISSION_DENIED', ...(e.details ?? {}) }`), and `buildApiError`
+puts everything that is not the `code` on the wire as `error.details`.
+
+Per the maintainer's 2026-08-11 ruling the two transports now agree on REST's
+shape: **message + code + the route-derived object**. `positions` and
+`permissionSets` are server-side diagnostics and are no longer serialized; the
+full withheld payload is written to a server log line instead, so a false
+denial is still diagnosable.
+
+**The object is derived from the request path, not from `error.details`.** This
+is the part an "allowlist `operation` + `object`" reading gets wrong.
+`ObjectQL.cascadeDeleteRelations` re-enters `delete()` for every child of the
+row being deleted, so a child's own trip through the security middleware throws
+with `details.object` set to the CHILD. Forwarding that field would have reached
+the ruled field set and still answered the API name of an object the caller
+never addressed. The dispatcher now reads no field of `error.details` at all:
+`object` comes from `cleanPath`, exactly as REST takes `req.params.object`, and
+a denial on a route whose path names no object carries no `object` — REST's
+`...(object ? { object } : {})` behaviour.
+
+**Also fixed, and required for the above to have any effect on the wire.** The
+domain-registry branch of `dispatch()` returned its handler's promise without
+awaiting it. In an async function a bare `return <promise>` settles outside the
+enclosing `try`, so a domain handler's rejection never reached that method's
+`catch` — and every domain that can raise an object-gate denial (`/data` among
+them) resolves through that branch, which made the `PERMISSION_DENIED` branch
+unreachable in practice. Denials escaped to the Hono catch-all instead, which
+answered `{ error: { message, code: 403 } }`: a numeric `code`, the shape
+`error-envelope.ts` exists to prevent, with no `PERMISSION_DENIED` string for a
+client to branch on. The branch now awaits, so a `/data` denial answers the
+ruled envelope. Non-denial errors are unaffected — the catch rethrows them and
+they reach the adapter exactly as before.
+
+**Wire-visible.** A consumer reading `error.details.positions`,
+`error.details.permissionSets` or `error.details.operation` off a dispatcher 403
+no longer receives them, and `error.details.object` is now the object the
+request addressed rather than whichever object the gate refused. A `/data`
+denial's `error.code` is now the string `PERMISSION_DENIED` rather than the
+number `403`.
@@ -0,0 +1,237 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#7450] A `/data` permission denial must not answer the caller's
+ * authorization topology — nor an object they never addressed.
+ *
+ * `plugin-security`'s CRUD gate attaches
+ * `{ operation, object, positions, permissionSets }` to every
+ * `PermissionDeniedError`. `@objectstack/rest`'s `mapDataError` never reads it
+ * (403 body = `{ error, code, object? }`, the `object` being the one the ROUTE
+ * named). The dispatcher spread it — `{ code: 'PERMISSION_DENIED',
+ * ...(e.details ?? {}) }` — and `buildApiError` puts everything but the `code`
+ * on the wire as `error.details`. `/data` is served by that dispatcher and
+ * `domains/data.ts` has no local catch, so an ordinary CRUD denial disclosed
+ * the caller's position and permission-set names to the browser.
+ *
+ * The 2026-08-11 maintainer ruling on #7450: REST's shape is the contract for
+ * both transports.
+ *
+ * ## The cascade case, which is why the object is route-derived
+ *
+ * `ObjectQL.cascadeDeleteRelations` re-enters `delete()` for every child of the
+ * row being deleted, so a child's own trip through the gate throws with
+ * `details.object === <child>`. An allowlist that forwarded `details.object`
+ * would reach the ruled field set and still answer a third party's API name on
+ * exactly the path the card called the sharpest. The dispatcher therefore takes
+ * `object` from the request path, like REST takes `req.params.object`, and
+ * reads no field of `error.details` at all.
+ *
+ * ⚠️ Fixture discipline: every denial below carries a FULLY populated `details`
+ * — a test whose fixture never had one would pass against the unfixed
+ * dispatcher and prove nothing. Each assertion here fails on `main` before the
+ * fix (mutation table in the PR).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { HttpDispatcher } from '../http-dispatcher.js';
+import { PermissionDeniedError } from '@objectstack/plugin-security';
+
+/** The end-user sentence the CRUD gate renders (#7414) — no API names in it. */
+const USER_MESSAGE = '您没有执行此操作的权限,如需访问请联系管理员。';
+
+/**
+ * REST's answer to the SAME denial, transcribed from the pin PR #7449 added:
+ * `packages/rest/src/rest.test.ts`, "never ships a PERMISSION_DENIED developer
+ * half or its structured details to the client". That test drives the real
+ * `mapDataError` over a fixture identical to {@link cascadeChildDenial} below,
+ * down to the position and permission-set names, and asserts exactly this body.
+ *
+ * Transcribed rather than imported on purpose. `@objectstack/rest`'s public
+ * entry does not re-export `mapDataError`, and reaching into its source from
+ * here drags eleven of that package's modules outside this package's `rootDir`
+ * (TS6059) — the fix for a disclosure card must not widen the reference
+ * package's API surface or its type-check debt to buy itself a test. So parity
+ * is pinned by TWO tests over ONE fixture: REST's asserts the constant below is
+ * what `mapDataError` produces, this file asserts the dispatcher agrees with it.
+ * Change either side's shape and the other side's pin fails.
+ */
+const REST_DENIAL_BODY = {
+    error: USER_MESSAGE,
+    code: 'PERMISSION_DENIED',
+    object: 'app_parent_object',
+} as const;
+
+/**
+ * A denial raised while cascading `DELETE /data/app_parent_object/1` into a
+ * child: the gate's own `object` is the CHILD, which the caller never named.
+ */
+const cascadeChildDenial = () =>
+    new PermissionDeniedError(
+        USER_MESSAGE,
+        {
+            operation: 'delete',
+            object: 'app_child_object',
+            positions: ['org_member', 'everyone'],
+            permissionSets: ['app_reader'],
+        },
+        "[Security] Access denied: operation 'delete' on object 'app_child_object' " +
+            'is not permitted for positions [org_member, everyone]',
+    );
+
+/** An ordinary denial on the object the caller addressed. */
+const directDenial = (object: string) =>
+    new PermissionDeniedError(USER_MESSAGE, {
+        operation: 'update',
+        object,
+        positions: ['org_member', 'everyone'],
+        permissionSets: ['app_reader'],
+    });
+
+const CALLER = () =>
+    ({
+        request: {},
+        executionContext: {
+            userId: 'u_test',
+            isSystem: false,
+            positions: ['org_member', 'everyone'],
+            permissions: ['app_reader'],
+            systemPermissions: [],
+        },
+    }) as any;
+
+describe('/data PERMISSION_DENIED body — #7450', () => {
+    let dispatcher: HttpDispatcher;
+    let mockObjectQL: any;
+    let warn: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        mockObjectQL = {
+            insert: vi.fn(),
+            // The protocol-less `/data` fallback reads the row before writing
+            // it, so the pre-read has to succeed for the WRITE's denial — the
+            // one carrying the cascade payload — to be the error under test.
+            find: vi.fn().mockResolvedValue([{ id: '1' }]),
+            update: vi.fn(),
+            delete: vi.fn(),
+            getObjects: vi.fn().mockReturnValue({}),
+            registry: { getObject: vi.fn().mockReturnValue({ name: 'app_parent_object' }) },
+        };
+        const kernel = {
+            context: {
+                getService: (name: string) => (name === 'objectql' ? mockObjectQL : null),
+            },
+        } as any;
+        dispatcher = new HttpDispatcher(kernel);
+        warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        // Without this the spy stacks across cases and the log assertion below
+        // counts every earlier case's line too.
+        warn.mockRestore();
+    });
+
+    const dispatch = (method: string, path: string, body?: any) =>
+        dispatcher.dispatch(method, path, body, {}, CALLER());
+
+    it('answers 403 PERMISSION_DENIED with the message and no structured details', async () => {
+        mockObjectQL.update.mockRejectedValue(directDenial('app_parent_object'));
+
+        const r = await dispatch('PATCH', '/data/app_parent_object/1', { name: 'x' });
+
+        expect(r.handled).toBe(true);
+        expect(r.response?.status).toBe(403);
+        // Positive identity first — the absence assertions below only mean
+        // something on top of a body that really is the denial.
+        expect(r.response?.body?.error?.code).toBe('PERMISSION_DENIED');
+        expect(r.response?.body?.error?.message).toBe(USER_MESSAGE);
+        // The route's own object still rides: the caller named it themselves.
+        expect(r.response?.body?.error?.details).toEqual({ object: 'app_parent_object' });
+    });
+
+    it('never serialises positions or permissionSets', async () => {
+        mockObjectQL.update.mockRejectedValue(directDenial('app_parent_object'));
+
+        const r = await dispatch('PATCH', '/data/app_parent_object/1', { name: 'x' });
+
+        const wire = JSON.stringify(r.response?.body);
+        expect(wire).not.toContain('positions');
+        expect(wire).not.toContain('permissionSets');
+        expect(wire).not.toContain('org_member');
+        expect(wire).not.toContain('app_reader');
+        // The operator's half of the message is not a details sibling either.
+        expect(wire).not.toContain('developerMessage');
+        expect(wire).not.toContain('[Security]');
+    });
+
+    it('does NOT name a cascade child the caller never addressed', async () => {
+        mockObjectQL.delete.mockRejectedValue(cascadeChildDenial());
+
+        const r = await dispatch('DELETE', '/data/app_parent_object/1');
+
+        expect(r.response?.status).toBe(403);
+        // The whole point: `details.object` said `app_child_object`.
+        expect(JSON.stringify(r.response?.body)).not.toContain('app_child_object');
+        expect(r.response?.body?.error?.details?.object).toBe('app_parent_object');
+    });
+
+    // The mirror case — a denial on a route whose path names no object, where
+    // REST's `...(object ? { object } : {})` omits the field — is pinned at the
+    // builder in `../security/permission-denied-envelope.test.ts`. It is not
+    // reachable end-to-end through `/data`: that domain answers 400 "Object
+    // name required" before any gate runs.
+
+    it('logs the withheld diagnostics server-side rather than dropping them', async () => {
+        mockObjectQL.delete.mockRejectedValue(cascadeChildDenial());
+
+        await dispatch('DELETE', '/data/app_parent_object/1');
+
+        const lines = warn.mock.calls
+            .map((c: unknown[]) => String(c[0]))
+            .filter((l: string) => l.includes('PERMISSION_DENIED'));
+        expect(lines).toHaveLength(1);
+        const line = lines[0]!;
+        expect(line).toContain('DELETE /data/app_parent_object/1');
+        // Everything the wire lost is here — including the cascade child, which
+        // is the field an operator debugging a false denial most needs.
+        expect(line).toContain('object=app_child_object');
+        expect(line).toContain('positions=[org_member, everyone]');
+        expect(line).toContain('permissionSets=[app_reader]');
+    });
+
+    /**
+     * The card's third decision: "either way the two transports should agree on
+     * what a PERMISSION_DENIED body carries".
+     *
+     * The two envelopes NEST differently — REST is flat, the dispatcher wraps in
+     * `success` / `error` — and this card does not change that. What has to
+     * agree is the semantic content, which is what leaked. So the comparison is
+     * field-by-field against {@link REST_DENIAL_BODY}, the body REST's own pin
+     * asserts for this identical error.
+     */
+    it('discloses exactly what @objectstack/rest discloses for the same denial', async () => {
+        mockObjectQL.delete.mockRejectedValue(cascadeChildDenial());
+
+        const runtime = await dispatch('DELETE', '/data/app_parent_object/1');
+        const error = runtime.response?.body?.error;
+
+        expect(runtime.response?.status).toBe(403);
+        expect({
+            error: error?.message,
+            code: error?.code,
+            object: (error?.details as { object?: string } | undefined)?.object,
+        }).toEqual({ ...REST_DENIAL_BODY });
+
+        // Nothing rides beyond those three: `details` holds the object alone,
+        // and no other key was smuggled onto the error member.
+        expect(error?.details).toEqual({ object: REST_DENIAL_BODY.object });
+        expect(Object.keys(error ?? {}).sort()).toEqual(['code', 'details', 'httpStatus', 'message']);
+
+        const wire = JSON.stringify(runtime.response?.body);
+        expect(wire).not.toContain('positions');
+        expect(wire).not.toContain('permissionSets');
+        expect(wire).not.toContain('app_child_object');
+    });
+});
@@ -43,6 +43,10 @@ import {
     resolveExecutionContext,
     isPermissionDeniedError,
 } from './security/resolve-execution-context.js';
+import {
+    permissionDeniedErrorDetails,
+    describeDeniedDiagnostics,
+} from './security/permission-denied-envelope.js';
 import { validationFailureDetails, VALIDATION_FAILED_STATUS } from './validation-failure.js';
 
 // randomUUID moved to ./domains/auth.ts with its only consumer (D11③ PR-7).
@@ -1847,7 +1851,24 @@ export class HttpDispatcher {
         // order-equivalent to their original chain positions.
         const domainRoute = this.domainRegistry.resolve(cleanPath, method);
         if (domainRoute) {
-            return domainRoute.handler({ path: cleanPath, method, body, query }, context);
+            // [#7450] `return await`, not `return`. In an async function a bare
+            // `return <promise>` settles OUTSIDE the enclosing `try`, so a
+            // domain handler's rejection never reached the `catch` at the foot
+            // of this method — and every domain that can raise an object-gate
+            // denial (`/data` first among them) resolves HERE, which made that
+            // catch's `PERMISSION_DENIED` branch unreachable in practice. The
+            // denial escaped to the Hono catch-all instead, which answered
+            // `{ error: { message, code: 403 } }` — a NUMERIC `code`, i.e. the
+            // #3842 shape this package's error envelope exists to prevent, and
+            // no `PERMISSION_DENIED` for a client to branch on.
+            //
+            // Awaiting is what makes the ruled 403 contract actually apply on
+            // this transport; it must land together with the details allowlist
+            // in the catch below, because awaiting ALONE would start shipping
+            // the `positions` / `permissionSets` payload the ruling withholds.
+            // Non-denial errors are unaffected: the catch rethrows them, so
+            // they reach the adapter exactly as before.
+            return await domainRoute.handler({ path: cleanPath, method, body, query }, context);
         }
 
         // 0. Discovery Endpoint (GET /discovery or GET /)
@@ -1943,9 +1964,32 @@ export class HttpDispatcher {
         };
         } catch (e) {
             if (isPermissionDeniedError(e)) {
+                // [#7450] The denial's `details` does NOT reach the wire.
+                //
+                // This used to be `{ code: 'PERMISSION_DENIED', ...(e.details ?? {}) }`,
+                // and `buildApiError` puts everything that is not the `code` on
+                // the wire as `error.details` — so the security gate's
+                // `positions` / `permissionSets` (the caller's authorization
+                // topology) and its `object` (on a cascade delete, a CHILD the
+                // caller never addressed — `cascadeDeleteRelations` re-authorises
+                // each one independently) were answered to the browser, while
+                // `@objectstack/rest`'s `mapDataError` shipped none of it.
+                //
+                // Per the 2026-08-11 ruling on #7450 the two transports agree on
+                // REST's shape — message + code + the ROUTE-derived object. The
+                // object below therefore comes from `cleanPath`, the dispatcher's
+                // equivalent of REST's `req.params.object`, and never from
+                // `e.details.object`: those are different values on exactly the
+                // cascade path that made this a disclosure. See
+                // `./security/permission-denied-envelope.ts`.
+                const withheld = describeDeniedDiagnostics(e.details);
+                if (withheld) {
+                    // Dropped from the response, not from the operator's reach.
+                    console.warn(`[HttpDispatcher] PERMISSION_DENIED on ${method} ${cleanPath} — ${withheld}`);
+                }
                 return {
                     handled: true,
-                    response: this.error(e.message, 403, { code: 'PERMISSION_DENIED', ...(e.details ?? {}) }),
+                    response: this.error(e.message, 403, permissionDeniedErrorDetails(cleanPath)),
                 };
             }
             throw e;