fix(rest): pass through explicit 4xx status+code in mapDataError (#2926 ⑦)

Record-scope authorization denials (plugin-sharing throws status=403,
code=FORBIDDEN) degraded to a bare 400 with no code because the generic data
routes call mapDataError directly, bypassing sendError's status passthrough.
Add a guarded 4xx passthrough after the structured-code branches (409
envelopes keep their rich fields; 5xx still goes through the sanitizing
heuristics; oversized messages fall back to generic text), and stop logging
expected statuses as unhandled on the list route.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017bJWtKmZ2mFpRFAmmmoeqe

Author: claude

.changeset/rest-2926-status-passthrough.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): mapDataError now honors an explicit 4xx `error.status`/`error.code` carried by domain errors (#2926 ⑦). Record-scope authorization denials from plugin-sharing (status 403, code FORBIDDEN) previously degraded to a bare 400 with no machine-readable code because the generic data routes bypass sendError's status passthrough. Structured 409 envelopes (CONCURRENT_UPDATE, DELETE_RESTRICTED) keep their dedicated branches; 5xx statuses still go through the message-sanitizing heuristics.

packages/rest/src/rest-server.ts

@@ -157,6 +157,27 @@ export function mapDataError(error: any, object?: string): { status: number; bod
             },
         };
     }
+    // Generic passthrough for domain errors that already carry an explicit
+    // HTTP status (e.g. plugin-sharing's record-scope denial: status 403 +
+    // code FORBIDDEN) — mirrors sendError's `.status` handling, which the
+    // generic data routes bypass by calling mapDataError directly (#2926 ⑦).
+    // Placed AFTER the structured-code branches above (409s carry rich
+    // fields this envelope would drop) and deliberately limited to 4xx:
+    // 5xx messages keep going through the sanitizing heuristics below so
+    // internal/SQL details never reach the client verbatim.
+    if (typeof error?.status === 'number' && error.status >= 400 && error.status < 500) {
+        const msg = typeof error?.message === 'string' && error.message.length > 0 && error.message.length < 500
+            ? error.message
+            : 'Request failed';
+        return {
+            status: error.status,
+            body: {
+                error: msg,
+                ...(typeof error?.code === 'string' && error.code ? { code: error.code } : {}),
+                ...(object ? { object } : {}),
+            },
+        };
+    }
 
     const raw = String(error?.message ?? error ?? '');
     const lower = raw.toLowerCase();
@@ -3259,7 +3280,7 @@ export class RestServer {
                         res.json(result);
                     } catch (error: any) {
                         const mapped = mapDataError(error, req.params?.object);
-                        if (mapped.status === 404 || mapped.status === 503 || mapped.status === 502) {
+                        if (isExpectedDataStatus(mapped.status) || mapped.body?.code === 'UNSUPPORTED_QUERY_PARAM') {
                             res.status(mapped.status).json(mapped.body);
                         } else {
                             logError("[REST] Unhandled error:", error);

packages/rest/src/rest.test.ts

@@ -2140,6 +2140,70 @@ describe('mapDataError — schema/constraint envelopes', () => {
     expect(r.body.object).toBe('crm_lead');
   });
 
+  // #2926 ⑦: plugin-sharing's record-scope denial throws with an explicit
+  // status 403 + code FORBIDDEN, but the generic data routes bypass
+  // sendError's `.status` passthrough — mapDataError must honor the
+  // explicit status itself or the 403 degrades to the catch-all 400.
+  it('passes through an explicit 4xx status + code (sharing FORBIDDEN → 403)', () => {
+    const r = mapDataError(
+      Object.assign(new Error('FORBIDDEN: insufficient privileges to update showcase_inquiry rec1'), {
+        code: 'FORBIDDEN',
+        status: 403,
+      }),
+      'showcase_inquiry',
+    );
+    expect(r.status).toBe(403);
+    expect(r.body.code).toBe('FORBIDDEN');
+    expect(r.body.object).toBe('showcase_inquiry');
+    expect(r.body.error).toContain('insufficient privileges');
+  });
+
+  it('does NOT pass through an explicit 5xx status (message stays sanitized)', () => {
+    const r = mapDataError(
+      Object.assign(new Error('connect ECONNREFUSED 10.0.0.5:5432 (internal pool)'), { status: 502 }),
+    );
+    // 5xx bypasses the passthrough and falls into the sanitizing heuristics.
+    expect(r.status).not.toBe(502);
+    expect(r.body.code).not.toBe('FORBIDDEN');
+  });
+
+  it('guards the passthrough message length (oversized → generic text)', () => {
+    const r = mapDataError(Object.assign(new Error('x'.repeat(600)), { status: 403, code: 'FORBIDDEN' }));
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe('Request failed');
+  });
+
+  it('keeps CONCURRENT_UPDATE 409 structured fields despite its own status property', () => {
+    const r = mapDataError(
+      Object.assign(new Error('Record was modified'), {
+        code: 'CONCURRENT_UPDATE',
+        status: 409,
+        currentVersion: 7,
+        currentRecord: { id: 'r1' },
+      }),
+      'sys_task',
+    );
+    expect(r.status).toBe(409);
+    expect(r.body.code).toBe('CONCURRENT_UPDATE');
+    expect(r.body.currentVersion).toBe(7);
+    expect(r.body.currentRecord).toEqual({ id: 'r1' });
+  });
+
+  it('keeps DELETE_RESTRICTED 409 structured fields despite its own status property', () => {
+    const r = mapDataError(
+      Object.assign(new Error('Cannot delete sys_position (p1): 1 dependent record'), {
+        code: 'DELETE_RESTRICTED',
+        status: 409,
+        dependentObject: 'sys_position_permission_set',
+        dependentCount: 1,
+      }),
+      'sys_position',
+    );
+    expect(r.status).toBe(409);
+    expect(r.body.code).toBe('DELETE_RESTRICTED');
+    expect(r.body.dependentCount).toBe(1);
+  });
+
   it('maps SQLite "has no column named" → 400 INVALID_FIELD with the field', () => {
     const r = mapDataError(
       sqliteError(