@grantex/sdk 0.6.0 → 0.7.0

package/dist/client.js

@@ -21,15 +21,67 @@ import { CredentialsClient } from './resources/credentials.js';
 import { PassportsClient } from './resources/passports.js';
 import { DpdpClient } from './resources/dpdp.js';
 import { CommerceClient } from './resources/commerce.js';
-import { ToolManifest, permissionCovers } from './manifest.js';
+import { CapSubReason, DenialReason, RevocationSubReason, ManifestSubReason, PurposeSubReason, TokenSubReason, ToolSubReason, } from './denials.js';
+import { AuthorizationDetailsError, parseDecisionReferences, parseToolsAuthorization, toolsAuthorizationAllows, } from './authorization-details.js';
+import { isKnownPurpose, matchPurpose } from './purpose.js';
+import { CAPS_MODES, CapExceededError, CapsConfigurationError, MeterUnavailableError, } from './caps/meter.js';
+import { MALFORMED_GRANT_CAPS, buildCapLimits } from './caps/limits.js';
+import { ToolManifest, parseManifestJson, permissionCovers } from './manifest.js';
 import { verifyGrantToken } from './verify.js';
+import { RevocationFeed, isRevocationCheckMode, } from './revocations/index.js';
+import { DecisionSubReason } from './denials.js';
+import { ActionValidationError, computeActionHash, decisionActionFromToolCall, parseDecisionAction } from './decisions/action.js';
+import { DecisionGrantError, verifyDecisionGrants } from './decisions/verify.js';
+import { DecisionsClient } from './resources/decisions.js';
 const DEFAULT_BASE_URL = 'https://api.grantex.dev';
+function checkDecisionsMode(mode) {
+    if (mode !== 'enforce' && mode !== 'warn') {
+        throw new Error(`decisionsMode must be one of enforce, warn, not ${JSON.stringify(mode)}`);
+    }
+    return mode;
+}
+function checkRevocationCheck(mode) {
+    if (!isRevocationCheckMode(mode)) {
+        throw new Error(`revocationCheck must be offline, online or feed, not ${JSON.stringify(mode)}`);
+    }
+    return mode;
+}
+function checkCapsMode(mode) {
+    if (!CAPS_MODES.includes(mode)) {
+        throw new Error(`capsMode must be one of ${CAPS_MODES.join(', ')}, not ${JSON.stringify(mode)}`);
+    }
+    return mode;
+}
+/**
+ * Throw CapExceededError if reserving `limits` now would exceed a cap. A
+ * point-in-time check that consumes nothing: a concurrent call can still take
+ * the last unit before the reservation is made.
+ */
+async function checkCaps(meter, tenantId, limits) {
+    for (const usage of await meter.usage(tenantId, limits)) {
+        const limit = usage.limit;
+        if (limit.units > 0 && (limit.limit === 0 || usage.used + limit.units > limit.limit)) {
+            throw new CapExceededError({
+                limit: limit.limit, window: limit.window, used: usage.used, requested: limit.units, scope: limit.scope, kind: limit.kind,
+            });
+        }
+    }
+}
 export class Grantex {
     #http;
     #manifests = new Map();
     #jwksUri;
     #issuer;
+    #legacyClaims;
     #enforceMode;
+    #capsMeter;
+    #capsMode;
+    #revocationCheck;
+    #revocationFeed;
+    #revocationFeedOptions;
+    #decisionsMode;
+    #decisionConsumer;
+    #decisionAlgorithms;
     agents;
     grants;
     tokens;
@@ -52,6 +104,7 @@ export class Grantex {
     passports;
     dpdp;
     commerce;
+    decisions;
     get lastRateLimit() {
         return this.#http.lastRateLimit;
     }
@@ -92,7 +145,25 @@ export class Grantex {
         this.commerce = new CommerceClient(this.#http);
         this.#jwksUri = options.jwksUri ?? `${normalizedBaseUrl}/.well-known/jwks.json`;
         this.#issuer = options.issuer;
+        this.#legacyClaims = options.legacyClaims;
         this.#enforceMode = options['enforceMode'] ?? 'strict';
+        this.#capsMeter = options.capsMeter;
+        this.#capsMode = checkCapsMode(options.capsMode ?? 'enforce');
+        this.#revocationCheck = checkRevocationCheck(options.revocationCheck ?? 'offline');
+        this.#revocationFeedOptions = options.revocationFeed ?? {};
+        if (this.#revocationCheck === 'feed')
+            this.#feed().start();
+        this.#decisionsMode = checkDecisionsMode(options.decisionsMode ?? 'enforce');
+        const algorithms = [...(options.decisionAlgorithms ?? ['RS256', 'ES256'])];
+        if (algorithms.length === 0 || algorithms.some((a) => a !== 'RS256' && a !== 'ES256')) {
+            throw new Error('decisionAlgorithms must be a non-empty subset of RS256, ES256');
+        }
+        this.#decisionAlgorithms = algorithms;
+        this.decisions = new DecisionsClient(this.#http);
+        const decisions = this.decisions;
+        this.#decisionConsumer = options.decisionConsumer ?? {
+            consume: (grants, consumeOptions) => decisions.consume(grants, consumeOptions ?? {}),
+        };
     }
     /**
      * Create a new developer account without an API key.
@@ -165,7 +236,10 @@ export class Grantex {
         const files = fs.readdirSync(dirPath).filter((f) => f.endsWith('.json'));
         for (const file of files) {
             const content = fs.readFileSync(path.join(dirPath, file), 'utf-8');
-            const data = JSON.parse(content);
+            const data = parseManifestJson(content);
+            if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+                throw new Error(`ToolManifest: a manifest must be a JSON object (${file})`);
+            }
             this.loadManifest(ToolManifest.fromJSON(data));
         }
     }
@@ -188,8 +262,97 @@ export class Grantex {
      * if (!result.allowed) throw new Error(result.reason);
      * ```
      */
+    /**
+     * The revocation feed this client uses for `revocationCheck: 'feed'`,
+     * started on first use. Call `stopRevocationFeed()` to close it.
+     */
+    revocationFeed() {
+        return this.#feed();
+    }
+    /** What the revocation feed knows, and whether it is fresh enough to be trusted. */
+    revocationFeedState() {
+        return this.#revocationFeed?.state();
+    }
+    /** Stop following the revocation feed and release its connection. */
+    async stopRevocationFeed() {
+        await this.#revocationFeed?.stop();
+    }
+    #feed() {
+        if (!this.#revocationFeed) {
+            this.#revocationFeed = new RevocationFeed(this.#http, this.#revocationFeedOptions);
+        }
+        return this.#revocationFeed;
+    }
+    /**
+     * Why this grant must not be used, or undefined. `enforce()` calls this
+     * before any other check, because a revoked grant is not a question of
+     * scopes.
+     */
+    async #revocationDenial(mode, ref) {
+        if (mode === 'feed') {
+            const feed = this.#feed();
+            if (!await feed.ready()) {
+                const unavailable = feed.state().unavailable;
+                return unavailable === null
+                    ? {
+                        reason: `The revocation feed has not been reachable for more than ${feed.staleAfterMs} ms, `
+                            + 'so revocations may not be known; denying rather than authorising on stale information.',
+                        subReason: RevocationSubReason.FEED_STALE,
+                    }
+                    : {
+                        reason: `The revocation feed is not usable (${unavailable}); denying rather than authorising `
+                            + 'without a way to learn about revocations.',
+                        subReason: RevocationSubReason.FEED_UNAVAILABLE,
+                    };
+            }
+            const match = feed.match(ref);
+            if (!match)
+                return undefined;
+            const subReason = match.kind === 'parent_grant'
+                ? RevocationSubReason.PARENT_REVOKED
+                : match.action === 'suspended' ? RevocationSubReason.SUSPENDED : RevocationSubReason.REVOKED;
+            return { reason: `Grant ${match.id} is ${match.action === 'suspended' ? 'suspended' : 'revoked'}.`, subReason };
+        }
+        const query = new URLSearchParams();
+        if (ref.grantId !== undefined)
+            query.set('grantId', ref.grantId);
+        if (ref.tokenId !== undefined)
+            query.set('jti', ref.tokenId);
+        let status;
+        try {
+            status = await this.#http.get(`/v1/revocations/status?${query.toString()}`);
+        }
+        catch (err) {
+            return {
+                reason: `The revocation status of this grant could not be checked (${err instanceof Error ? err.message : String(err)}); `
+                    + 'denying rather than authorising without it.',
+                subReason: RevocationSubReason.STATUS_UNAVAILABLE,
+            };
+        }
+        if (typeof status !== 'object' || status === null || typeof status.revoked !== 'boolean') {
+            return {
+                reason: 'The revocation status endpoint returned something this client cannot read; '
+                    + 'denying rather than assuming the grant is live.',
+                subReason: RevocationSubReason.STATUS_UNAVAILABLE,
+            };
+        }
+        if (!status.revoked)
+            return undefined;
+        if (status.status === 'suspended') {
+            return { reason: 'This grant is suspended.', subReason: RevocationSubReason.SUSPENDED };
+        }
+        if (status.status === 'unknown') {
+            return {
+                reason: 'The auth service does not recognise this grant; denying rather than assuming it is live.',
+                subReason: RevocationSubReason.STATUS_UNAVAILABLE,
+            };
+        }
+        return { reason: `This grant is ${status.status}.`, subReason: RevocationSubReason.REVOKED };
+    }
     async enforce(options) {
-        const { grantToken, connector, tool, amount } = options;
+        const { grantToken, connector, tool, amount, caseId, costComponents, reserve = true, capsTenantId } = options;
+        const capsMode = options.capsMode === undefined ? this.#capsMode : checkCapsMode(options.capsMode);
+        const decisionsMode = options.decisionsMode === undefined ? this.#decisionsMode : checkDecisionsMode(options.decisionsMode);
         const base = {
             grantId: '',
             agentDid: '',
@@ -198,72 +361,332 @@ export class Grantex {
             connector,
             tool,
         };
+        let resultPurpose;
+        const denied = (reason, reasonCode, subReason, details) => this.#applyEnforceMode({
+            ...base,
+            allowed: false,
+            reason,
+            reasonCode,
+            ...(subReason !== undefined ? { subReason } : {}),
+            ...(details !== undefined ? { details } : {}),
+            ...(resultPurpose !== undefined ? { purpose: resultPurpose } : {}),
+        });
         // 1. Verify the token locally using JWKS retrieved from the configured URI
         let grant;
         try {
             grant = await verifyGrantToken(grantToken, {
                 jwksUri: this.#jwksUri,
                 ...(this.#issuer !== undefined ? { issuer: this.#issuer } : {}),
+                ...(this.#legacyClaims !== undefined ? { legacyClaims: this.#legacyClaims } : {}),
             });
         }
         catch (err) {
-            return this.#applyEnforceMode({
-                ...base,
-                allowed: false,
-                reason: `Token verification failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
+            return denied(`Token verification failed: ${err instanceof Error ? err.message : String(err)}`, DenialReason.TOKEN_INVALID);
         }
         base.grantId = grant.grantId;
         base.agentDid = grant.agentDid;
         base.scopes = grant.scopes;
-        // 2. Look up manifest for the connector
+        // 1b. Revocation. The token verifies offline whether or not the grant
+        //     still stands, so this is the only place a revocation can be seen.
+        const revocationCheck = options.revocationCheck === undefined
+            ? this.#revocationCheck
+            : checkRevocationCheck(options.revocationCheck);
+        if (revocationCheck !== 'offline') {
+            const denial = await this.#revocationDenial(revocationCheck, {
+                grantId: grant.grantId,
+                tokenId: grant.tokenId,
+                parentGrantId: grant.parentGrantId,
+            });
+            if (denial)
+                return denied(denial.reason, DenialReason.GRANT_REVOKED, denial.subReason);
+        }
+        // 2. Read the grant's tools authorization for this connector. A claim that
+        //    cannot be read unambiguously denies every call.
+        let entry;
+        let decisionReference;
+        try {
+            entry = parseToolsAuthorization(grant.authorizationDetails).get(connector);
+            decisionReference = parseDecisionReferences(grant.authorizationDetails).get(connector);
+        }
+        catch (err) {
+            if (!(err instanceof AuthorizationDetailsError))
+                throw err;
+            return denied(`Grant token authorization_details cannot be used: ${err.message}.`, DenialReason.TOKEN_INVALID, TokenSubReason.MALFORMED_AUTHORIZATION_DETAILS);
+        }
+        const purpose = entry?.purpose;
+        resultPurpose = purpose;
+        // 3. Look up manifest for the connector
         const manifest = this.#manifests.get(connector);
         if (!manifest) {
-            return this.#applyEnforceMode({
-                ...base,
-                allowed: false,
-                reason: `No manifest loaded for connector '${connector}'. Load a manifest first.`,
-            });
+            return denied(`No manifest loaded for connector '${connector}'. Load a manifest first.`, DenialReason.MANIFEST_UNKNOWN_TOOL, ManifestSubReason.UNKNOWN_CONNECTOR);
         }
-        // 3. Look up tool permission from manifest
+        // 4. Look up tool permission from manifest
         const requiredPermission = manifest.getPermission(tool);
         if (!requiredPermission) {
-            return this.#applyEnforceMode({
-                ...base,
-                allowed: false,
-                reason: `Unknown tool '${tool}' on connector '${connector}'. Tool not found in manifest.`,
-            });
+            return denied(`Unknown tool '${tool}' on connector '${connector}'. Tool not found in manifest.`, DenialReason.MANIFEST_UNKNOWN_TOOL, ManifestSubReason.UNKNOWN_TOOL);
         }
         base.permission = requiredPermission;
-        // 4. Find the best matching scope for this connector
+        let spec;
+        try {
+            spec = manifest.getToolSpec(tool);
+        }
+        catch (err) {
+            return denied(`Tool '${tool}' on connector '${connector}' has an invalid declaration: ${err instanceof Error ? err.message : String(err)}`, DenialReason.MANIFEST_UNKNOWN_TOOL, ManifestSubReason.INVALID_DECLARATION);
+        }
+        if (spec === undefined) {
+            return denied(`Unknown tool '${tool}' on connector '${connector}'. Tool not found in manifest.`, DenialReason.MANIFEST_UNKNOWN_TOOL, ManifestSubReason.UNKNOWN_TOOL);
+        }
+        // 5. Find the best matching scope for this connector
         const grantedPermission = this.#resolveGrantedPermission(grant.scopes, connector);
         if (!grantedPermission) {
-            return this.#applyEnforceMode({
-                ...base,
-                allowed: false,
-                reason: `No scope grants access to connector '${connector}'.`,
-            });
+            return denied(`No scope grants access to connector '${connector}'.`, DenialReason.TOOL_NOT_GRANTED);
         }
-        // 5. Check permission hierarchy
+        // 6. Check permission hierarchy
         if (!permissionCovers(grantedPermission, requiredPermission)) {
-            return this.#applyEnforceMode({
-                ...base,
-                allowed: false,
-                reason: `${grantedPermission} scope does not permit ${requiredPermission} operations on ${connector}.`,
-            });
+            return denied(`${grantedPermission} scope does not permit ${requiredPermission} operations on ${connector}.`, DenialReason.PERMISSION_INSUFFICIENT);
+        }
+        // 7. The grant's tools list, when it has one, must name the tool.
+        if (entry !== undefined && !toolsAuthorizationAllows(entry, tool)) {
+            return denied(`Grant does not list tool '${tool}' on connector '${connector}'.`, DenialReason.TOOL_NOT_GRANTED, ToolSubReason.NOT_IN_AUTHORIZATION_DETAILS);
+        }
+        // 8. Purpose. A tool that declares allowed_purposes needs a grant whose
+        //    purpose is known and matches one of them.
+        if (spec.allowedPurposes !== undefined) {
+            const allowedPurposes = [...spec.allowedPurposes];
+            if (purpose === undefined) {
+                return denied(`Tool '${tool}' on ${connector} is restricted to purposes ${allowedPurposes.join(', ')}; the grant carries no purpose.`, DenialReason.PURPOSE_NOT_ALLOWED, PurposeSubReason.MISSING, { allowed_purposes: allowedPurposes });
+            }
+            if (!isKnownPurpose(purpose)) {
+                return denied(`Grant purpose ${JSON.stringify(purpose)} is not in the purpose vocabulary.`, DenialReason.PURPOSE_NOT_ALLOWED, PurposeSubReason.UNKNOWN_PURPOSE, { allowed_purposes: allowedPurposes, purpose });
+            }
+            if (matchPurpose(allowedPurposes, purpose) === undefined) {
+                return denied(`Grant purpose '${purpose}' is not allowed for tool '${tool}' on ${connector}; allowed purposes: ${allowedPurposes.join(', ')}.`, DenialReason.PURPOSE_NOT_ALLOWED, PurposeSubReason.NOT_MATCHED, { allowed_purposes: allowedPurposes, purpose });
+            }
+        }
+        // 9. Decision. A tool that requires a decision, in the manifest or in the
+        //    grant's decision references, needs decision grants that verify
+        //    offline for this exact action; they are consumed at the issuer as the
+        //    last step, after caps are reserved. A decision needs two approvers if
+        //    either the manifest or the grant says so.
+        let decisionSet;
+        let wouldDeny;
+        if (spec.requiresDecision || decisionReference?.tools.includes(tool)) {
+            const fourEyesOn = [...new Set([...spec.fourEyesOn, ...(decisionReference?.fourEyesOn[tool] ?? [])])];
+            const requirement = { decision_required: `${connector}:${tool}` };
+            let decisionDenial;
+            try {
+                decisionSet = await this.#verifyDecision(grant, connector, tool, fourEyesOn, spec.decisionFields ?? [], options);
+            }
+            catch (err) {
+                if (!(err instanceof DecisionGrantError))
+                    throw err;
+                decisionDenial = err.subReason === DecisionSubReason.ABSENT
+                    ? { reason_code: DenialReason.DECISION_REQUIRED, sub_reason: '', reason: `Tool '${tool}' on ${connector} requires a decision grant.`, details: requirement }
+                    : { reason_code: DenialReason.DECISION_INVALID, sub_reason: err.subReason, reason: `The decision grant for tool '${tool}' on ${connector} is not valid: ${err.message}`, details: requirement };
+            }
+            if (decisionDenial !== undefined) {
+                if (decisionsMode !== 'warn') {
+                    return denied(decisionDenial.reason, decisionDenial.reason_code, decisionDenial.sub_reason === '' ? undefined : decisionDenial.sub_reason, decisionDenial.details);
+                }
+                wouldDeny = decisionDenial;
+            }
         }
-        // 6. Check capped amount if provided
+        // 10. Check capped amount if provided
         if (amount !== undefined) {
+            if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+                return denied(`Amount must be a finite number to enforce a budget cap on ${connector}.`, DenialReason.CAP_EXCEEDED, CapSubReason.INVALID_AMOUNT);
+            }
             const cap = this.#extractCap(grant.scopes, connector);
+            if (cap === 'invalid') {
+                return denied(`A capped scope on ${connector} carries a malformed cap; refusing to authorize amount ${amount}.`, DenialReason.CAP_EXCEEDED, CapSubReason.MALFORMED_CAP);
+            }
             if (cap !== undefined && amount > cap) {
-                return this.#applyEnforceMode({
-                    ...base,
-                    allowed: false,
-                    reason: `Amount ${amount} exceeds budget cap of ${cap} on ${connector}.`,
-                });
+                return denied(`Amount ${amount} exceeds budget cap of ${cap} on ${connector}.`, DenialReason.CAP_EXCEEDED, CapSubReason.AMOUNT_CAP, { limit: cap, amount });
+            }
+        }
+        // 11. Call caps and cost units (declared by the manifest or by the grant).
+        //     Reserving is the last step, so a denied call never consumes a cap;
+        //     without a meter the call is denied.
+        const grantCaps = entry?.caps;
+        const grantCapsApply = grantCaps !== undefined
+            && (Object.prototype.hasOwnProperty.call(grantCaps, tool)
+                || (spec.costUnits !== undefined && Object.prototype.hasOwnProperty.call(grantCaps, 'cost_units')));
+        let reservation;
+        let capLimits = [];
+        const capsTenant = capsTenantId ?? grant.developerId;
+        if ((spec.caps !== undefined || spec.costUnits !== undefined || grantCapsApply) && capsMode !== 'off') {
+            let capDenial;
+            const meter = this.#capsMeter;
+            if (meter === undefined) {
+                capDenial = {
+                    reason_code: DenialReason.CAP_EXCEEDED,
+                    sub_reason: CapSubReason.METER_UNAVAILABLE,
+                    reason: `Tool '${tool}' on ${connector} declares caps or cost units and no caps meter is configured.`,
+                    details: {},
+                };
+            }
+            else {
+                try {
+                    const buildOptions = {
+                        connector,
+                        tool,
+                        spec,
+                        grantId: grant.grantId,
+                        ...(grantCaps !== undefined ? { grantCaps } : {}),
+                        ...(caseId !== undefined ? { caseId } : {}),
+                        ...(costComponents !== undefined ? { costComponents } : {}),
+                    };
+                    capLimits = buildCapLimits(buildOptions);
+                }
+                catch (err) {
+                    if (!(err instanceof CapsConfigurationError))
+                        throw err;
+                    if (err.subReason === MALFORMED_GRANT_CAPS) {
+                        // A token problem, not a cap decision: denied in every mode.
+                        return denied(`Grant token authorization_details cannot be used: ${err.message}.`, DenialReason.TOKEN_INVALID, TokenSubReason.MALFORMED_AUTHORIZATION_DETAILS);
+                    }
+                    capDenial = {
+                        reason_code: DenialReason.CAP_EXCEEDED,
+                        sub_reason: err.subReason,
+                        reason: `Cannot meter tool '${tool}' on ${connector}: ${err.message}.`,
+                        details: {},
+                    };
+                }
+                if (capDenial === undefined) {
+                    try {
+                        if (reserve) {
+                            reservation = await meter.reserve(capsTenant, capLimits);
+                        }
+                        else {
+                            await checkCaps(meter, capsTenant, capLimits);
+                        }
+                    }
+                    catch (err) {
+                        if (err instanceof CapExceededError) {
+                            capDenial = {
+                                reason_code: DenialReason.CAP_EXCEEDED,
+                                sub_reason: CapSubReason.LIMIT_REACHED,
+                                reason: `${err.message} on ${connector}.${tool}.`,
+                                details: {
+                                    code: err.code,
+                                    limit: err.limit,
+                                    window: err.window,
+                                    used: err.used,
+                                    requested: err.requested,
+                                    scope: err.scope,
+                                    kind: err.kind,
+                                },
+                            };
+                        }
+                        else {
+                            // Any other failure, including an invalid tenant, leaves the call unmetered.
+                            const message = err instanceof MeterUnavailableError || err instanceof CapsConfigurationError
+                                ? err.message
+                                : 'caps meter failed';
+                            capDenial = {
+                                reason_code: DenialReason.CAP_EXCEEDED,
+                                sub_reason: CapSubReason.METER_UNAVAILABLE,
+                                reason: `Caps meter could not evaluate tool '${tool}' on ${connector}: ${message}.`,
+                                details: {},
+                            };
+                        }
+                    }
+                }
+            }
+            if (capDenial !== undefined) {
+                if (capsMode !== 'warn') {
+                    return denied(capDenial.reason, capDenial.reason_code, capDenial.sub_reason, capDenial.details);
+                }
+                wouldDeny ??= capDenial;
+            }
+        }
+        // 12. Consume the decision grants at the issuer. Offline verification
+        //     alone never allows a call: one grant authorises one call.
+        let decision;
+        if (decisionSet !== undefined) {
+            try {
+                decision = await this.#decisionConsumer.consume(decisionSet, grant.grantId ? { grantId: grant.grantId } : {});
+            }
+            catch (err) {
+                const subReason = err instanceof DecisionGrantError ? err.subReason : DecisionSubReason.CONSUME_UNAVAILABLE;
+                if (reservation !== undefined && this.#capsMeter !== undefined) {
+                    await this.#capsMeter.refundUnsent(reservation).catch(() => undefined);
+                    reservation = undefined;
+                }
+                const message = `The decision grant for tool '${tool}' on ${connector} was not consumed: ${err instanceof Error ? err.message : 'consumption failed'}`;
+                const details = { decision_required: `${connector}:${tool}` };
+                if (decisionsMode !== 'warn')
+                    return denied(message, DenialReason.DECISION_INVALID, subReason, details);
+                wouldDeny ??= { reason_code: DenialReason.DECISION_INVALID, sub_reason: subReason, reason: message, details };
             }
         }
-        return { ...base, allowed: true, reason: '' };
+        return {
+            ...base,
+            allowed: true,
+            reason: '',
+            ...(purpose !== undefined ? { purpose } : {}),
+            ...(reservation !== undefined ? { reservation } : {}),
+            ...(capLimits.length > 0 ? { capLimits, capsTenantId: capsTenant } : {}),
+            ...(wouldDeny !== undefined ? { wouldDeny } : {}),
+            ...(decision !== undefined ? { decision } : {}),
+        };
+    }
+    /** Offline checks of the decision grants for one call (see `enforce`). */
+    async #verifyDecision(grant, connector, tool, fourEyesOn, decisionFields, options) {
+        const tokens = options.decisionGrants;
+        if (tokens === undefined || tokens.length === 0) {
+            throw new DecisionGrantError(DecisionSubReason.ABSENT, 'no decision grant was presented');
+        }
+        let given;
+        let fromArguments;
+        try {
+            if (options.decisionAction !== undefined)
+                given = parseDecisionAction(options.decisionAction);
+            if (options.arguments !== undefined)
+                fromArguments = decisionActionFromToolCall(tool, options.arguments, decisionFields);
+        }
+        catch (err) {
+            if (err instanceof ActionValidationError) {
+                throw new DecisionGrantError(DecisionSubReason.MALFORMED, `the call's action is invalid: ${err.message}`);
+            }
+            throw err;
+        }
+        if (given !== undefined && fromArguments !== undefined && computeActionHash(given) !== computeActionHash(fromArguments)) {
+            // The call would do something other than what the caller says it approves.
+            throw new DecisionGrantError(DecisionSubReason.ACTION_MISMATCH, 'decisionAction does not match the action derived from the call arguments');
+        }
+        const action = given ?? fromArguments;
+        if (action === undefined) {
+            throw new DecisionGrantError(DecisionSubReason.MALFORMED, 'enforce() needs decisionAction or arguments to compare the decision grant with');
+        }
+        const missingFields = decisionFields.filter((name) => action.extra === undefined || !Object.prototype.hasOwnProperty.call(action.extra, name));
+        if (missingFields.length > 0) {
+            throw new DecisionGrantError(DecisionSubReason.MALFORMED, `the action does not bind the declared decision fields: ${missingFields.join(', ')}`);
+        }
+        if (action.action !== tool) {
+            throw new DecisionGrantError(DecisionSubReason.ACTION_MISMATCH, 'the decision action names another tool');
+        }
+        if (typeof options.caseVersion !== 'string' || options.caseVersion.length === 0) {
+            throw new DecisionGrantError(DecisionSubReason.MALFORMED, 'enforce() needs caseVersion for a decision');
+        }
+        return verifyDecisionGrants(tokens, action, options.caseVersion, {
+            issuer: this.#decisionIssuer(),
+            jwksUri: this.#jwksUri,
+            developerId: grant.developerId,
+            connector,
+            approvalsRequired: fourEyesOn.includes(action.decision) ? 2 : 1,
+            algorithms: this.#decisionAlgorithms,
+        });
+    }
+    #decisionIssuer() {
+        if (this.#issuer !== undefined)
+            return this.#issuer;
+        const url = new URL(this.#jwksUri);
+        if (url.href.replace(/\/$/, '') === 'https://api.grantex.dev/.well-known/jwks.json')
+            return 'https://grantex.dev';
+        return url.pathname.endsWith('/.well-known/jwks.json')
+            ? `${url.origin}${url.pathname.slice(0, -'/.well-known/jwks.json'.length)}`
+            : `${url.origin}${url.pathname.replace(/\/$/, '')}`;
     }
     /**
      * Resolve the highest granted permission level for a connector from scope strings.
@@ -299,16 +722,25 @@ export class Grantex {
      * Scope format: `tool:{connector}:{permission}:{resource}:capped:{N}`
      */
     #extractCap(scopes, connector) {
+        // The tightest cap on the connector wins. Returning the first capped scope
+        // encountered let `tool:x:read:capped:1000` shadow `tool:x:write:capped:10`
+        // purely by ordering, and a malformed cap (`capped:abc` → NaN) disabled the
+        // check entirely because `amount > NaN` is always false.
+        let cap;
         for (const scope of scopes) {
             const parts = scope.split(':');
-            if (parts[0] === 'tool' && parts[1] === connector) {
-                const cappedIdx = parts.indexOf('capped');
-                if (cappedIdx !== -1 && parts[cappedIdx + 1]) {
-                    return Number(parts[cappedIdx + 1]);
-                }
-            }
+            if ((parts[0] !== 'tool' && parts[0] !== 'agenticorg') || parts[1] !== connector)
+                continue;
+            const cappedIdx = parts.indexOf('capped');
+            if (cappedIdx === -1)
+                continue;
+            const raw = parts[cappedIdx + 1];
+            const value = raw !== undefined && /^\d+(\.\d+)?$/.test(raw) ? Number(raw) : Number.NaN;
+            if (!Number.isFinite(value) || value < 0)
+                return 'invalid';
+            cap = cap === undefined ? value : Math.min(cap, value);
         }
-        return undefined;
+        return cap;
     }
     #applyEnforceMode(result) {
         if (!result.allowed && this.#enforceMode === 'permissive') {
@@ -342,18 +774,25 @@ export class Grantex {
         const wrapped = Object.create(tool);
         wrapped.invoke = async function (...args) {
             const getToken = () => typeof options.grantToken === 'function' ? options.grantToken() : options.grantToken;
-            let result = await self.enforce({
-                grantToken: getToken(),
+            const caseId = typeof options.caseId === 'function' ? options.caseId() : options.caseId;
+            const costComponents = typeof options.costComponents === 'function' ? options.costComponents() : options.costComponents;
+            const decisionGrants = typeof options.decisionGrants === 'function' ? options.decisionGrants() : options.decisionGrants;
+            const caseVersion = typeof options.caseVersion === 'function' ? options.caseVersion() : options.caseVersion;
+            const input = args[0];
+            const callOptions = {
                 connector: options.connector,
                 tool: options.tool,
-            });
-            // Retry once with refreshed token if expired and grantToken is a getter
+                ...(caseId !== undefined ? { caseId } : {}),
+                ...(costComponents !== undefined ? { costComponents } : {}),
+                ...(decisionGrants !== undefined ? { decisionGrants } : {}),
+                ...(caseVersion !== undefined ? { caseVersion } : {}),
+                ...(typeof input === 'object' && input !== null && !Array.isArray(input) ? { arguments: input } : {}),
+            };
+            let result = await self.enforce({ grantToken: getToken(), ...callOptions });
+            // Retry once with refreshed token if expired and grantToken is a getter. An
+            // expired token is denied before caps are reserved, so this cannot reserve twice.
             if (!result.allowed && result.reason.includes('expired') && typeof options.grantToken === 'function') {
-                result = await self.enforce({
-                    grantToken: getToken(),
-                    connector: options.connector,
-                    tool: options.tool,
-                });
+                result = await self.enforce({ grantToken: getToken(), ...callOptions });
             }
             if (!result.allowed) {
                 throw new Error(`Grantex scope denied: ${result.reason}`);
@@ -389,13 +828,34 @@ export class Grantex {
                 jsonFn.call(statusFn.call(response, 401), { error: { code: 'UNAUTHORIZED', message: 'Missing grant token' } });
                 return;
             }
-            self.enforce({ grantToken: token, connector, tool })
+            const caseId = options.extractCaseId?.(request);
+            const costComponents = options.extractCostComponents?.(request);
+            const decisionGrants = options.extractDecisionGrants?.(request);
+            const callArguments = options.extractArguments?.(request);
+            const caseVersion = options.extractCaseVersion?.(request);
+            self.enforce({
+                grantToken: token,
+                connector,
+                tool,
+                ...(caseId !== undefined ? { caseId } : {}),
+                ...(costComponents !== undefined ? { costComponents } : {}),
+                ...(decisionGrants !== undefined ? { decisionGrants } : {}),
+                ...(callArguments !== undefined ? { arguments: callArguments } : {}),
+                ...(caseVersion !== undefined ? { caseVersion } : {}),
+            })
                 .then((result) => {
                 if (!result.allowed) {
                     const statusFn = response['status'];
                     const jsonFn = statusFn.call(response, 403)['json'];
                     jsonFn.call(statusFn.call(response, 403), {
-                        error: { code: 'SCOPE_DENIED', message: result.reason, connector, tool },
+                        error: {
+                            code: 'SCOPE_DENIED',
+                            message: result.reason,
+                            connector,
+                            tool,
+                            ...(result.reasonCode !== undefined ? { reason: result.reasonCode } : {}),
+                            ...(result.subReason !== undefined ? { subReason: result.subReason } : {}),
+                        },
                     });
                     return;
                 }