@orangecheck/agent-core 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OC Agent canonical messages, envelope formats (delegation/action/revocation), scope grammar, and verification. See https://github.com/orangecheck/oc-agent-protocol.",
   "keywords": [
     "bitcoin",

package/src/assert-scope.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import { ScopeNotGrantedError, assertScopeGranted } from './assert-scope.js';
+import type { ScopesEncryptedEnvelope } from './types.js';
+
+const SEALED = {
+    v: 1,
+    alg: 'x25519-xchacha20poly1305',
+    recipients: [{ device_id: 'dev1', ct: 'AA' }],
+    ct: 'BB',
+    nonce: 'CC',
+} as unknown as ScopesEncryptedEnvelope;
+
+function reasonOf(fn: () => void): string {
+    try {
+        fn();
+    } catch (e) {
+        return e instanceof ScopeNotGrantedError ? e.reason : `wrong-error:${String(e)}`;
+    }
+    return 'no-throw';
+}
+
+describe('assertScopeGranted', () => {
+    it('permits an exact grant and a sub-scope of one', () => {
+        expect(() =>
+            assertScopeGranted({ scopes: ['mcp:invoke(server=s,tool=t)'] }, 'mcp:invoke(server=s,tool=t)', 'f')
+        ).not.toThrow();
+        expect(() =>
+            assertScopeGranted({ scopes: ['mcp:invoke(server=s)'] }, 'mcp:invoke(server=s,tool=t)', 'f')
+        ).not.toThrow();
+    });
+
+    it('refuses a scope outside the grant', () => {
+        expect(
+            reasonOf(() => assertScopeGranted({ scopes: ['mcp:invoke(server=a)'] }, 'mcp:invoke(server=b)', 'f'))
+        ).toBe('not_subscope');
+    });
+
+    // The whole reason this module exists. Five adapters open-coded
+    // `(scopes ?? []).map(parseScope)`, so a v1.2 private delegation — where
+    // `scopes` is absent BECAUSE it is sealed — reported "not a sub-scope of
+    // any granted scope". The refusal was right; the diagnosis sent the
+    // integrator to audit a scope string that was very possibly correct.
+    it('names encrypted scopes as such rather than blaming the scope string', () => {
+        const d = { scopes_encrypted: SEALED };
+        expect(reasonOf(() => assertScopeGranted(d, 'mcp:invoke(server=s)', 'f'))).toBe('scopes_encrypted');
+        try {
+            assertScopeGranted(d, 'mcp:invoke(server=s)', 'f');
+        } catch (e) {
+            expect((e as Error).message).toMatch(/decryptPrivateScopes/);
+            expect((e as Error).message).not.toMatch(/not a sub-scope/);
+        }
+    });
+
+    it('treats absent and empty scopes as granting nothing, not everything', () => {
+        expect(reasonOf(() => assertScopeGranted({}, 'x:y', 'f'))).toBe('no_scopes');
+        expect(reasonOf(() => assertScopeGranted({ scopes: [] }, 'x:y', 'f'))).toBe('no_scopes');
+    });
+
+    // A sealed delegation that ALSO carries a scopes array must not be
+    // evaluated against that array: the fields are exclusive per the spec, so
+    // a populated `scopes` alongside `scopes_encrypted` is a malformed
+    // envelope and possibly an attempt to present a benign readable grant
+    // while the real one stays hidden.
+    it('refuses on the sealed field even when a scopes array is also present', () => {
+        expect(
+            reasonOf(() =>
+                assertScopeGranted({ scopes: ['x:y'], scopes_encrypted: SEALED }, 'x:y', 'f')
+            )
+        ).toBe('scopes_encrypted');
+    });
+});

package/src/assert-scope.ts

@@ -0,0 +1,80 @@
+import { hasPrivateScopes } from './private-scope.js';
+import { isSubScope, parseScope } from './scope.js';
+import type { ScopesEncryptedEnvelope } from './types.js';
+
+/**
+ * The minimum an adapter needs to make the authorization decision. Kept
+ * structural rather than importing `Delegation` so `stampX` helpers can accept
+ * the narrower shapes they already declare.
+ */
+export interface ScopeBearingDelegation {
+    scopes?: string[];
+    scopes_encrypted?: ScopesEncryptedEnvelope;
+}
+
+/** Distinguishes the three reasons a stamp can be refused. */
+export class ScopeNotGrantedError extends Error {
+    readonly reason: 'not_subscope' | 'scopes_encrypted' | 'no_scopes';
+    constructor(reason: ScopeNotGrantedError['reason'], message: string) {
+        super(message);
+        this.name = 'ScopeNotGrantedError';
+        this.reason = reason;
+    }
+}
+
+/**
+ * Refuse unless `scopeExercised` is a sub-scope of something the delegation
+ * actually grants. Every `agent-*` adapter's pre-flight check routes here.
+ *
+ * The check itself is unchanged and still fails closed. What this adds is
+ * telling the caller WHICH of three things went wrong, because the five
+ * adapters each open-coded `(delegation.scopes ?? []).map(parseScope)` and so
+ * reported all three as the same thing:
+ *
+ * - **not_subscope** — scopes are readable and this one is not among them.
+ *   The integrator's own mistake, and the only case the old message fit.
+ * - **scopes_encrypted** — v1.2 private mode. `scopes` is absent *because it
+ *   is sealed to a device key*, so the adapter cannot evaluate the request at
+ *   all. `?? []` collapsed this into "not a sub-scope of any granted scope",
+ *   which sends the integrator to audit a scope string that may well be
+ *   correct, when what they need is `decryptPrivateScopes` and to pass the
+ *   recovered list. Refusing is right; misnaming why is not.
+ * - **no_scopes** — neither field present. A delegation granting nothing.
+ *
+ * Fail-closed is not a judgement call here: an over-broad stamp is a signed,
+ * content-addressed authorization artifact that a verifier will accept.
+ */
+export function assertScopeGranted(
+    delegation: ScopeBearingDelegation,
+    scopeExercised: string,
+    fnName: string
+): void {
+    if (hasPrivateScopes(delegation)) {
+        throw new ScopeNotGrantedError(
+            'scopes_encrypted',
+            `${fnName}: this delegation uses v1.2 private scopes — \`scopes_encrypted\` is ` +
+                `set and \`scopes\` is absent, so the granted set cannot be read here. ` +
+                `Decrypt it with decryptPrivateScopes() using a matching device key and pass ` +
+                `the recovered scopes as \`delegation.scopes\`. Refusing to stamp ` +
+                `\`${scopeExercised}\` against an unreadable grant.`
+        );
+    }
+
+    const scopes = delegation.scopes;
+    if (scopes === undefined || scopes.length === 0) {
+        throw new ScopeNotGrantedError(
+            'no_scopes',
+            `${fnName}: delegation grants no scopes, so \`${scopeExercised}\` cannot be ` +
+                `exercised. An absent or empty \`scopes\` means nothing is granted, never everything.`
+        );
+    }
+
+    const exercised = parseScope(scopeExercised);
+    if (!scopes.map(parseScope).some((g) => isSubScope(exercised, g))) {
+        throw new ScopeNotGrantedError(
+            'not_subscope',
+            `${fnName}: scope_exercised (${scopeExercised}) is not a sub-scope of any granted ` +
+                `scope (${scopes.join(', ')})`
+        );
+    }
+}

package/src/index.ts

@@ -79,3 +79,6 @@ export type {
     UnsealScopesInput,
     UnsealedScopes,
 } from './private-scope.js';
+
+export { assertScopeGranted, ScopeNotGrantedError } from './assert-scope.js';
+export type { ScopeBearingDelegation } from './assert-scope.js';