@karmaniverous/jeeves-server 3.1.2 → 3.1.3

package/CHANGELOG.md

@@ -2,8 +2,10 @@
 
 All notable changes to this project will be documented in this file. Dates are displayed in UTC.
 
-#### [v3.1.2](https://github.com/karmaniverous/jeeves-server/compare/v2.9.3...v3.1.2)
+#### [v3.1.3](https://github.com/karmaniverous/jeeves-server/compare/v2.9.3...v3.1.3)
 
+- docs: document scope override precedence in OpenClaw skill [`#95`](https://github.com/karmaniverous/jeeves-server/pull/95)
+- feat: explicit scope overrides take precedence over named scopes [`#94`](https://github.com/karmaniverous/jeeves-server/pull/94)
 - fix: parse inline tokens in heading renderer [`#93`](https://github.com/karmaniverous/jeeves-server/pull/93)
 - fix: prevent full data reload on tab switch [`#91`](https://github.com/karmaniverous/jeeves-server/pull/91)
 - fix: Rendered tab persists when switching to Raw on watcher-rendered files [`#90`](https://github.com/karmaniverous/jeeves-server/pull/90)
@@ -49,7 +51,6 @@ All notable changes to this project will be documented in this file. Dates are d
 - perf: lazy-load facets only when 'Add filter' is clicked [`d0b111c`](https://github.com/karmaniverous/jeeves-server/commit/d0b111c8cd442a47238ad5e0512576221bac1572)
 - chore: add knip configs, remove dead exports, clean all code quality checks [`2a81072`](https://github.com/karmaniverous/jeeves-server/commit/2a81072cc5341047b2ef40333405a8cc9760dab4)
 - feat: garbage value diagnostics for inference rule debugging [`06e4f82`](https://github.com/karmaniverous/jeeves-server/commit/06e4f823fa87f991ca81c904d2eb55dc7ce59d26)
-- fix: make resetConfig reload runtime config [`79e8602`](https://github.com/karmaniverous/jeeves-server/commit/79e8602b4a8ee13c4de94bb3d262dd8bdb7cd2c8)
 - chore: release @karmaniverous/jeeves-server v3.1.0 [`0688333`](https://github.com/karmaniverous/jeeves-server/commit/0688333e880847fc4c3beb773cdb0a907a3f82e9)
 - updated docs [`075a6f3`](https://github.com/karmaniverous/jeeves-server/commit/075a6f36cee6279c83ba564e6efbde99ebac2f37)
 - chore: release @karmaniverous/jeeves-server v3.1.1 [`736ec35`](https://github.com/karmaniverous/jeeves-server/commit/736ec35c550c0f8da5800413562f10643f9da6db)
@@ -59,6 +60,7 @@ All notable changes to this project will be documented in this file. Dates are d
 - docs: add changelogs as children of package guide indexes [`fd16b5b`](https://github.com/karmaniverous/jeeves-server/commit/fd16b5b7f80ad2b58d883fe3b7cf270668026f8e)
 - lintfix [`38a9376`](https://github.com/karmaniverous/jeeves-server/commit/38a937631ab2ac3c22240857f69b36d5d9570665)
 - fix: text/number facets skip value cleaning, cast values to String [`c9af039`](https://github.com/karmaniverous/jeeves-server/commit/c9af039c2fbdad59a7e9fdedd75f008ab5c1c148)
+- chore: release @karmaniverous/jeeves-server v3.1.2 [`d15fa4c`](https://github.com/karmaniverous/jeeves-server/commit/d15fa4c5d6ca2a31e28b6509d5566569025110ff)
 - chore: release @karmaniverous/jeeves-server v3.0.0-1 [`db96bc1`](https://github.com/karmaniverous/jeeves-server/commit/db96bc140b9cbca7ad52ddd562a805ac74ca67aa)
 - docs: document ?events=N query param on /api/status [`4a25f3b`](https://github.com/karmaniverous/jeeves-server/commit/4a25f3bcf5bf50e688cd7c38e0340a0f24341e96)
 - fix: restore eager facet loading on modal open [`a625bd0`](https://github.com/karmaniverous/jeeves-server/commit/a625bd08e47ab95cd5a05324a0a888bb0bf6fc4f)
@@ -96,6 +98,7 @@ All notable changes to this project will be documented in this file. Dates are d
 - chore: SOLID/DRY/test coverage pass [`e491bfb`](https://github.com/karmaniverous/jeeves-server/commit/e491bfbbce7fef13252c2488378b85e983a2207a)
 - refactor: extract buildRuntimeConfig to resolve.ts (DRY) [`87bd749`](https://github.com/karmaniverous/jeeves-server/commit/87bd749c6827e3c95e2ff9996ab1b781cb316932)
 - fix: address Gemini code review feedback across PRs #65-#76 [`2fef919`](https://github.com/karmaniverous/jeeves-server/commit/2fef9192b00c80605c9cca348ea7feff5af2602a)
+- fix: make resetConfig reload runtime config [`79e8602`](https://github.com/karmaniverous/jeeves-server/commit/79e8602b4a8ee13c4de94bb3d262dd8bdb7cd2c8)
 - refactor: extract shared renderMarkdownContent pipeline [`244dddf`](https://github.com/karmaniverous/jeeves-server/commit/244dddf83da846d2863e776ae78a029610532d2d)
 - feat: schema-driven search facet filters (Step 10) [`c305c2a`](https://github.com/karmaniverous/jeeves-server/commit/c305c2ae261514411b6329bdc84052ee5c189759)
 - feat: add scroll anchoring for async diagram renders [`e4bd972`](https://github.com/karmaniverous/jeeves-server/commit/e4bd97293dbb8a9a63d5cf3bceb6e0cbb7a26916)

package/dist/src/auth/keys.js

@@ -24,9 +24,21 @@ function pathMatchesPatterns(requestPath, patterns) {
 }
 /**
  * Check whether a request path matches normalized scopes (allow/deny).
- * Path must match at least one allow rule AND NOT match any deny rule.
+ *
+ * Evaluation order (explicit overrides take highest precedence):
+ * 1. If explicitDeny matches → DENIED (overrides named allow)
+ * 2. If explicitAllow matches → ALLOWED (overrides named deny)
+ * 3. Path must match at least one allow rule AND NOT match any deny rule.
  */
 function pathMatchesScopes(requestPath, scopes) {
+    // Explicit overrides take precedence over named scope patterns
+    if (scopes.explicitDeny.length > 0 &&
+        pathMatchesPatterns(requestPath, scopes.explicitDeny))
+        return false;
+    if (scopes.explicitAllow.length > 0 &&
+        pathMatchesPatterns(requestPath, scopes.explicitAllow))
+        return true;
+    // Standard evaluation: allow AND NOT deny
     if (!pathMatchesPatterns(requestPath, scopes.allow))
         return false;
     if (scopes.deny.length > 0 && pathMatchesPatterns(requestPath, scopes.deny))

package/dist/src/auth/keys.test.js

@@ -0,0 +1,84 @@
+/**
+ * Tests for scope override precedence in key verification.
+ *
+ * Verifies the three-tier evaluation order:
+ * 1. explicitDeny → DENIED (overrides named allow)
+ * 2. explicitAllow → ALLOWED (overrides named deny)
+ * 3. Standard allow AND NOT deny
+ */
+import { describe, expect, it } from 'vitest';
+import { _pathMatchesScopes as pathMatchesScopes } from './keys.js';
+describe('pathMatchesScopes', () => {
+    it('allows a path matching allow and not deny', () => {
+        expect(pathMatchesScopes('/d/projects/foo', {
+            allow: ['/d/projects/**'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        })).toBe(true);
+    });
+    it('denies a path not matching any allow', () => {
+        expect(pathMatchesScopes('/d/secrets/foo', {
+            allow: ['/d/projects/**'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        })).toBe(false);
+    });
+    it('denies a path matching a deny pattern', () => {
+        expect(pathMatchesScopes('/d/projects/secret/foo', {
+            allow: ['/d/projects/**'],
+            deny: ['/d/projects/secret/**'],
+            explicitAllow: [],
+            explicitDeny: [],
+        })).toBe(false);
+    });
+    it('explicit allow overrides named deny', () => {
+        expect(pathMatchesScopes('/j/domains/projects/jill/doc.md', {
+            allow: ['/j/domains/projects/**'],
+            deny: ['/j/domains/projects/jill/**'],
+            explicitAllow: ['/j/domains/projects/jill/**'],
+            explicitDeny: [],
+        })).toBe(true);
+    });
+    it('explicit deny overrides named allow', () => {
+        expect(pathMatchesScopes('/d/repos/secret/code.ts', {
+            allow: ['/d/repos/**'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: ['/d/repos/secret/**'],
+        })).toBe(false);
+    });
+    it('explicit deny takes precedence over explicit allow', () => {
+        expect(pathMatchesScopes('/d/repos/secret/code.ts', {
+            allow: ['/d/repos/**'],
+            deny: [],
+            explicitAllow: ['/d/repos/secret/**'],
+            explicitDeny: ['/d/repos/secret/**'],
+        })).toBe(false);
+    });
+    it('path not in any scope is denied even with explicit allow on different path', () => {
+        expect(pathMatchesScopes('/totally/elsewhere', {
+            allow: ['/d/projects/**'],
+            deny: [],
+            explicitAllow: ['/j/domains/projects/jill/**'],
+            explicitDeny: [],
+        })).toBe(false);
+    });
+    it('Robert/Jill scenario: projects + no-private + explicit jill allow', () => {
+        // Named scopes: projects (allow /j/domains/projects/**) + no-private (deny /j/domains/projects/jill/**)
+        // Explicit: allow /j/domains/projects/jill/**
+        const scopes = {
+            allow: ['/j/domains/projects/**'],
+            deny: ['/j/domains/projects/jill/**'],
+            explicitAllow: ['/j/domains/projects/jill/**'],
+            explicitDeny: [],
+        };
+        // Jill's project should be accessible (explicit allow overrides named deny)
+        expect(pathMatchesScopes('/j/domains/projects/jill/thesis.md', scopes)).toBe(true);
+        // Other projects should work normally
+        expect(pathMatchesScopes('/j/domains/projects/jeeves-server/readme.md', scopes)).toBe(true);
+        // Other private projects (if they existed) would still be denied
+        // (only jill is explicitly allowed)
+    });
+});

package/dist/src/config/loadConfig.test.js

@@ -117,7 +117,12 @@ describe('loadConfig', () => {
             },
         });
         const config = await loadConfig(configPath);
-        expect(config.resolvedInsiders.find((i) => i.email === 'a@example.com')?.scopes).toEqual({ allow: ['/docs/**'], deny: [] });
+        expect(config.resolvedInsiders.find((i) => i.email === 'a@example.com')?.scopes).toEqual({
+            allow: ['/docs/**'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        });
     });
 });
 describe('config singleton', () => {

package/dist/src/config/resolve.js

@@ -18,14 +18,21 @@ export function normalizeScopes(raw) {
     if (raw === undefined || raw === null)
         return null;
     if (typeof raw === 'string')
-        return { allow: [raw], deny: [] };
+        return { allow: [raw], deny: [], explicitAllow: [], explicitDeny: [] };
     if (Array.isArray(raw))
-        return { allow: raw, deny: [] };
+        return {
+            allow: raw,
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        };
     if (typeof raw === 'object') {
         const obj = raw;
         return {
             allow: obj.allow ?? ['/**'],
             deny: obj.deny ?? [],
+            explicitAllow: [],
+            explicitDeny: [],
         };
     }
     return null;
@@ -43,6 +50,8 @@ export function resolveNamedScopes(named, rawScopes, overrides) {
             return {
                 allow: overrides.allow ?? ['/**'],
                 deny: overrides.deny ?? [],
+                explicitAllow: overrides.allow ?? [],
+                explicitDeny: overrides.deny ?? [],
             };
         }
         return null;
@@ -76,6 +85,8 @@ export function resolveNamedScopes(named, rawScopes, overrides) {
         return {
             allow: allow.length > 0 ? allow : ['/**'],
             deny,
+            explicitAllow: overrides?.allow ?? [],
+            explicitDeny: overrides?.deny ?? [],
         };
     }
     // Legacy inline scopes
@@ -86,6 +97,8 @@ export function resolveNamedScopes(named, rawScopes, overrides) {
         normalized.allow.push(...overrides.allow);
     if (overrides?.deny)
         normalized.deny.push(...overrides.deny);
+    normalized.explicitAllow = overrides?.allow ?? [];
+    normalized.explicitDeny = overrides?.deny ?? [];
     return normalized;
 }
 /**

package/dist/src/config/resolve.test.js

@@ -11,23 +11,36 @@ describe('normalizeScopes', () => {
         expect(normalizeScopes(null)).toBe(null);
     });
     it('wraps a string in allow array', () => {
-        expect(normalizeScopes('/docs')).toEqual({ allow: ['/docs'], deny: [] });
+        expect(normalizeScopes('/docs')).toEqual({
+            allow: ['/docs'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        });
     });
     it('wraps an array as allow', () => {
         expect(normalizeScopes(['/a', '/b'])).toEqual({
             allow: ['/a', '/b'],
             deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
         });
     });
     it('fills defaults for partial object', () => {
         expect(normalizeScopes({ deny: ['/secret'] })).toEqual({
             allow: ['/**'],
             deny: ['/secret'],
+            explicitAllow: [],
+            explicitDeny: [],
         });
     });
     it('passes through complete object', () => {
         const scopes = { allow: ['/a'], deny: ['/b'] };
-        expect(normalizeScopes(scopes)).toEqual(scopes);
+        expect(normalizeScopes(scopes)).toEqual({
+            ...scopes,
+            explicitAllow: [],
+            explicitDeny: [],
+        });
     });
 });
 describe('resolveKeys', () => {
@@ -43,7 +56,12 @@ describe('resolveKeys', () => {
         }, {});
         expect(result[0].name).toBe('scoped');
         expect(result[0].seed).toBe('seed456');
-        expect(result[0].scopes).toEqual({ allow: ['/docs'], deny: [] });
+        expect(result[0].scopes).toEqual({
+            allow: ['/docs'],
+            deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
+        });
     });
     it('handles mixed entries', () => {
         const result = resolveKeys({
@@ -52,7 +70,12 @@ describe('resolveKeys', () => {
         }, {});
         expect(result).toHaveLength(2);
         expect(result[0].scopes).toBe(null);
-        expect(result[1].scopes).toEqual({ allow: ['/x'], deny: ['/y'] });
+        expect(result[1].scopes).toEqual({
+            allow: ['/x'],
+            deny: ['/y'],
+            explicitAllow: [],
+            explicitDeny: [],
+        });
     });
 });
 describe('resolveInsiders', () => {
@@ -92,6 +115,8 @@ describe('resolveNamedScopes', () => {
         expect(resolveNamedScopes(named, 'restricted')).toEqual({
             allow: ['/**'],
             deny: ['/secret'],
+            explicitAllow: [],
+            explicitDeny: [],
         });
     });
     it('unions multiple named scopes and merges overrides', () => {
@@ -105,6 +130,8 @@ describe('resolveNamedScopes', () => {
         })).toEqual({
             allow: ['/**', '/extra'],
             deny: ['/secret', '/vc/**', '/more'],
+            explicitAllow: ['/extra'],
+            explicitDeny: ['/more'],
         });
     });
     it('falls back to legacy inline scope strings', () => {
@@ -112,6 +139,8 @@ describe('resolveNamedScopes', () => {
         expect(resolveNamedScopes(named, '/docs')).toEqual({
             allow: ['/docs'],
             deny: [],
+            explicitAllow: [],
+            explicitDeny: [],
         });
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-server",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Secure file browser, markdown viewer, and webhook gateway with PDF/DOCX export and expiring share links",
   "keywords": [
     "fastify",

package/src/auth/keys.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for scope override precedence in key verification.
+ *
+ * Verifies the three-tier evaluation order:
+ * 1. explicitDeny → DENIED (overrides named allow)
+ * 2. explicitAllow → ALLOWED (overrides named deny)
+ * 3. Standard allow AND NOT deny
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { _pathMatchesScopes as pathMatchesScopes } from './keys.js';
+
+describe('pathMatchesScopes', () => {
+  it('allows a path matching allow and not deny', () => {
+    expect(
+      pathMatchesScopes('/d/projects/foo', {
+        allow: ['/d/projects/**'],
+        deny: [],
+        explicitAllow: [],
+        explicitDeny: [],
+      }),
+    ).toBe(true);
+  });
+
+  it('denies a path not matching any allow', () => {
+    expect(
+      pathMatchesScopes('/d/secrets/foo', {
+        allow: ['/d/projects/**'],
+        deny: [],
+        explicitAllow: [],
+        explicitDeny: [],
+      }),
+    ).toBe(false);
+  });
+
+  it('denies a path matching a deny pattern', () => {
+    expect(
+      pathMatchesScopes('/d/projects/secret/foo', {
+        allow: ['/d/projects/**'],
+        deny: ['/d/projects/secret/**'],
+        explicitAllow: [],
+        explicitDeny: [],
+      }),
+    ).toBe(false);
+  });
+
+  it('explicit allow overrides named deny', () => {
+    expect(
+      pathMatchesScopes('/j/domains/projects/jill/doc.md', {
+        allow: ['/j/domains/projects/**'],
+        deny: ['/j/domains/projects/jill/**'],
+        explicitAllow: ['/j/domains/projects/jill/**'],
+        explicitDeny: [],
+      }),
+    ).toBe(true);
+  });
+
+  it('explicit deny overrides named allow', () => {
+    expect(
+      pathMatchesScopes('/d/repos/secret/code.ts', {
+        allow: ['/d/repos/**'],
+        deny: [],
+        explicitAllow: [],
+        explicitDeny: ['/d/repos/secret/**'],
+      }),
+    ).toBe(false);
+  });
+
+  it('explicit deny takes precedence over explicit allow', () => {
+    expect(
+      pathMatchesScopes('/d/repos/secret/code.ts', {
+        allow: ['/d/repos/**'],
+        deny: [],
+        explicitAllow: ['/d/repos/secret/**'],
+        explicitDeny: ['/d/repos/secret/**'],
+      }),
+    ).toBe(false);
+  });
+
+  it('path not in any scope is denied even with explicit allow on different path', () => {
+    expect(
+      pathMatchesScopes('/totally/elsewhere', {
+        allow: ['/d/projects/**'],
+        deny: [],
+        explicitAllow: ['/j/domains/projects/jill/**'],
+        explicitDeny: [],
+      }),
+    ).toBe(false);
+  });
+
+  it('Robert/Jill scenario: projects + no-private + explicit jill allow', () => {
+    // Named scopes: projects (allow /j/domains/projects/**) + no-private (deny /j/domains/projects/jill/**)
+    // Explicit: allow /j/domains/projects/jill/**
+    const scopes = {
+      allow: ['/j/domains/projects/**'],
+      deny: ['/j/domains/projects/jill/**'],
+      explicitAllow: ['/j/domains/projects/jill/**'],
+      explicitDeny: [],
+    };
+
+    // Jill's project should be accessible (explicit allow overrides named deny)
+    expect(
+      pathMatchesScopes('/j/domains/projects/jill/thesis.md', scopes),
+    ).toBe(true);
+
+    // Other projects should work normally
+    expect(
+      pathMatchesScopes('/j/domains/projects/jeeves-server/readme.md', scopes),
+    ).toBe(true);
+
+    // Other private projects (if they existed) would still be denied
+    // (only jill is explicitly allowed)
+  });
+});

package/src/auth/keys.ts

@@ -44,12 +44,29 @@ function pathMatchesPatterns(requestPath: string, patterns: string[]): boolean {
 
 /**
  * Check whether a request path matches normalized scopes (allow/deny).
- * Path must match at least one allow rule AND NOT match any deny rule.
+ *
+ * Evaluation order (explicit overrides take highest precedence):
+ * 1. If explicitDeny matches → DENIED (overrides named allow)
+ * 2. If explicitAllow matches → ALLOWED (overrides named deny)
+ * 3. Path must match at least one allow rule AND NOT match any deny rule.
  */
 function pathMatchesScopes(
   requestPath: string,
   scopes: NormalizedScopes,
 ): boolean {
+  // Explicit overrides take precedence over named scope patterns
+  if (
+    scopes.explicitDeny.length > 0 &&
+    pathMatchesPatterns(requestPath, scopes.explicitDeny)
+  )
+    return false;
+  if (
+    scopes.explicitAllow.length > 0 &&
+    pathMatchesPatterns(requestPath, scopes.explicitAllow)
+  )
+    return true;
+
+  // Standard evaluation: allow AND NOT deny
   if (!pathMatchesPatterns(requestPath, scopes.allow)) return false;
   if (scopes.deny.length > 0 && pathMatchesPatterns(requestPath, scopes.deny))
     return false;

package/src/config/loadConfig.test.ts

@@ -147,7 +147,12 @@ describe('loadConfig', () => {
     const config = await loadConfig(configPath);
     expect(
       config.resolvedInsiders.find((i) => i.email === 'a@example.com')?.scopes,
-    ).toEqual({ allow: ['/docs/**'], deny: [] });
+    ).toEqual({
+      allow: ['/docs/**'],
+      deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
+    });
   });
 });
 

package/src/config/resolve.test.ts

@@ -25,13 +25,20 @@ describe('normalizeScopes', () => {
   });
 
   it('wraps a string in allow array', () => {
-    expect(normalizeScopes('/docs')).toEqual({ allow: ['/docs'], deny: [] });
+    expect(normalizeScopes('/docs')).toEqual({
+      allow: ['/docs'],
+      deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
+    });
   });
 
   it('wraps an array as allow', () => {
     expect(normalizeScopes(['/a', '/b'])).toEqual({
       allow: ['/a', '/b'],
       deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
     });
   });
 
@@ -39,12 +46,18 @@ describe('normalizeScopes', () => {
     expect(normalizeScopes({ deny: ['/secret'] })).toEqual({
       allow: ['/**'],
       deny: ['/secret'],
+      explicitAllow: [],
+      explicitDeny: [],
     });
   });
 
   it('passes through complete object', () => {
     const scopes = { allow: ['/a'], deny: ['/b'] };
-    expect(normalizeScopes(scopes)).toEqual(scopes);
+    expect(normalizeScopes(scopes)).toEqual({
+      ...scopes,
+      explicitAllow: [],
+      explicitDeny: [],
+    });
   });
 });
 
@@ -65,7 +78,12 @@ describe('resolveKeys', () => {
     );
     expect(result[0].name).toBe('scoped');
     expect(result[0].seed).toBe('seed456');
-    expect(result[0].scopes).toEqual({ allow: ['/docs'], deny: [] });
+    expect(result[0].scopes).toEqual({
+      allow: ['/docs'],
+      deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
+    });
   });
 
   it('handles mixed entries', () => {
@@ -78,7 +96,12 @@ describe('resolveKeys', () => {
     );
     expect(result).toHaveLength(2);
     expect(result[0].scopes).toBe(null);
-    expect(result[1].scopes).toEqual({ allow: ['/x'], deny: ['/y'] });
+    expect(result[1].scopes).toEqual({
+      allow: ['/x'],
+      deny: ['/y'],
+      explicitAllow: [],
+      explicitDeny: [],
+    });
   });
 });
 
@@ -128,6 +151,8 @@ describe('resolveNamedScopes', () => {
     expect(resolveNamedScopes(named, 'restricted')).toEqual({
       allow: ['/**'],
       deny: ['/secret'],
+      explicitAllow: [],
+      explicitDeny: [],
     });
   });
 
@@ -144,6 +169,8 @@ describe('resolveNamedScopes', () => {
     ).toEqual({
       allow: ['/**', '/extra'],
       deny: ['/secret', '/vc/**', '/more'],
+      explicitAllow: ['/extra'],
+      explicitDeny: ['/more'],
     });
   });
 
@@ -152,6 +179,8 @@ describe('resolveNamedScopes', () => {
     expect(resolveNamedScopes(named, '/docs')).toEqual({
       allow: ['/docs'],
       deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
     });
   });
 });

package/src/config/resolve.ts

@@ -27,13 +27,22 @@ import type {
  */
 export function normalizeScopes(raw: unknown): NormalizedScopes | null {
   if (raw === undefined || raw === null) return null;
-  if (typeof raw === 'string') return { allow: [raw], deny: [] };
-  if (Array.isArray(raw)) return { allow: raw as string[], deny: [] };
+  if (typeof raw === 'string')
+    return { allow: [raw], deny: [], explicitAllow: [], explicitDeny: [] };
+  if (Array.isArray(raw))
+    return {
+      allow: raw as string[],
+      deny: [],
+      explicitAllow: [],
+      explicitDeny: [],
+    };
   if (typeof raw === 'object') {
     const obj = raw as { allow?: string[]; deny?: string[] };
     return {
       allow: obj.allow ?? ['/**'],
       deny: obj.deny ?? [],
+      explicitAllow: [],
+      explicitDeny: [],
     };
   }
   return null;
@@ -56,6 +65,8 @@ export function resolveNamedScopes(
       return {
         allow: overrides.allow ?? ['/**'],
         deny: overrides.deny ?? [],
+        explicitAllow: overrides.allow ?? [],
+        explicitDeny: overrides.deny ?? [],
       };
     }
     return null;
@@ -91,6 +102,8 @@ export function resolveNamedScopes(
     return {
       allow: allow.length > 0 ? allow : ['/**'],
       deny,
+      explicitAllow: overrides?.allow ?? [],
+      explicitDeny: overrides?.deny ?? [],
     };
   }
 
@@ -99,6 +112,8 @@ export function resolveNamedScopes(
   if (!normalized) return null;
   if (overrides?.allow) normalized.allow.push(...overrides.allow);
   if (overrides?.deny) normalized.deny.push(...overrides.deny);
+  normalized.explicitAllow = overrides?.allow ?? [];
+  normalized.explicitDeny = overrides?.deny ?? [];
   return normalized;
 }
 

package/src/config/types.ts

@@ -11,10 +11,19 @@ export type { AuthMode, JeevesConfig };
 /**
  * Normalized scopes — always resolved to \{ allow, deny \} form.
  * null = unrestricted access.
+ *
+ * Explicit overrides take precedence over named scope patterns:
+ * 1. If explicitDeny matches → DENIED (overrides named allow)
+ * 2. If explicitAllow matches → ALLOWED (overrides named deny)
+ * 3. Otherwise: normal allow AND NOT deny evaluation
  */
 export interface NormalizedScopes {
   allow: string[];
   deny: string[];
+  /** Explicit allow patterns from the insider/key entry — override named scope denies. */
+  explicitAllow: string[];
+  /** Explicit deny patterns from the insider/key entry — override named scope allows. */
+  explicitDeny: string[];
 }
 
 /**