refactor(security): migrate handleSecurity admin gate to shouldDenyAnonymous (#2567 follow-up) (#2997)

The /security/suggested-bindings admin surface was the last HTTP seam still
hand-rolling the anonymous check. It now delegates to the shared
shouldDenyAnonymous decision with requireAuth:true hardcoded, preserving its
UNCONDITIONAL semantics (an admin surface denies anonymous even on a
requireAuth:false deployment — pinned by the existing test that constructs the
dispatcher with no options and still expects 401). The 401 body adopts the
shared shape (code: 'unauthenticated'), asserted in the test.

Deliberately NOT migrated: handleNotification's !userId check — a "needs a user
identity" predicate (inbox is keyed by userId; a system context has no inbox),
not an anonymous-posture decision.

Verified: http-dispatcher + http-dispatcher.requireauth suites 185/185, lint
clean, check-single-authz-resolver intact.


Claude-Session: https://claude.ai/code/session_01ShknNUYoSTspJLBiqorD8V

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/authz-2567-handlesecurity-seam.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/runtime': patch
+---
+
+refactor(security): migrate the handleSecurity admin gate to shouldDenyAnonymous (#2567 follow-up)
+
+The dispatcher's `/security/suggested-bindings` admin surface was the last HTTP
+seam still hand-rolling the `!userId && !isSystem → 401` check. It now delegates
+to the shared `shouldDenyAnonymous` decision like every other seam — with
+`requireAuth: true` hardcoded, preserving its UNCONDITIONAL semantics (an admin
+surface denies anonymous callers even on a `requireAuth: false` demo deployment).
+The 401 body adopts the shared shape (`code: 'unauthenticated'`).
+
+Deliberately NOT migrated: `handleNotification`'s `!userId` check — that is a
+"needs a user identity" predicate (the inbox is keyed by userId; a system
+context has no inbox), not an anonymous-posture decision; migrating it would
+change semantics.

packages/runtime/src/http-dispatcher.test.ts

@@ -558,10 +558,15 @@ describe('HttpDispatcher', () => {
 
             it('401s an anonymous request without touching the service', async () => {
                 const service = makeService();
+                // NOTE: no options — requireAuth defaults false, yet the admin
+                // surface still denies anonymous (the gate is UNCONDITIONAL,
+                // hardcoded requireAuth:true into shouldDenyAnonymous — #2567).
                 const d = new HttpDispatcher(secKernel(service));
                 const result = await d.handleSecurity('/suggested-bindings', 'GET', undefined, {}, ctx());
                 expect(result.handled).toBe(true);
                 expect(result.response?.status).toBe(401);
+                // Shared anonymous-deny body shape (locks the seam migration).
+                expect(result.response?.body?.error?.details?.code).toBe('unauthenticated');
                 expect(service.listAudienceBindingSuggestions).not.toHaveBeenCalled();
             });
 

packages/runtime/src/http-dispatcher.ts

@@ -2337,8 +2337,16 @@ export class HttpDispatcher {
         }
 
         const ec = context.executionContext;
-        if (!ec?.userId && !ec?.isSystem) {
-            return { handled: true, response: this.error('Authentication required', 401) };
+        // Admin surface — anonymous is denied UNCONDITIONALLY (`requireAuth:
+        // true` hardcoded), independent of the deployment posture: even a
+        // `requireAuth: false` demo must not let anonymous callers list or
+        // confirm audience bindings. Shares the decision + body with every
+        // other HTTP seam (#2567).
+        if (shouldDenyAnonymous({ requireAuth: true, userId: ec?.userId, isSystem: ec?.isSystem })) {
+            return {
+                handled: true,
+                response: this.error(ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, { code: ANONYMOUS_DENY_CODE }),
+            };
         }
 
         const m = method.toUpperCase();