grantex enforce

Dry-run scope enforcement from the command line. Test whether a grant token permits a specific tool call before deploying.

Overview

grantex enforce test lets you dry-run scope enforcement against a real grant token without writing any code. Pass a token, connector, and tool name to see whether the call would be allowed or denied, and why.

npm install -g @grantex/cli

Prefer a secret-safe token source for agent automation:

grantex --json enforce test \
  --token-env GRANTEX_GRANT_TOKEN \
  --connector salesforce \
  --tool create_lead

Use --token-file <path> or --token-stdin as alternatives. Allowed decisions exit 0; denied or invalid decisions exit non-zero, including with --json.

---

grantex enforce test

Test whether a grant token permits a specific tool call.

grantex enforce test --token <jwt> --connector <connector> --tool <tool>

Allowed Example

grantex enforce test \
  --token "eyJhbGciOiJSUzI1NiIs..." \
  --connector salesforce \
  --tool create_lead

  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         ALLOWED
  Connector      salesforce
  Tool           create_lead
  Permission     write (from manifest)

  Token Scopes
  └ tool:salesforce:write:*

  Grant ID       grnt_01HXYZ
  Agent DID      did:grantex:ag_01HXYZ

  ─────────────────────────────────────────────

Denied Example

grantex enforce test \
  --token "eyJhbGciOiJSUzI1NiIs..." \
  --connector salesforce \
  --tool delete_contact

  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         DENIED
  Connector      salesforce
  Tool           delete_contact
  Permission     delete (from manifest)

  Token Scopes
  └ tool:salesforce:write:*

  Reason         write scope does not permit delete operations

  Grant ID       grnt_01HXYZ
  Agent DID      did:grantex:ag_01HXYZ

  ─────────────────────────────────────────────

---

Capped Scopes

Use the --amount flag to test enforcement against capped scopes. From the next SDK release, a capped scope denies a test without --amount (amount_missing):

grantex enforce test \
  --token "eyJ..." \
  --connector stripe \
  --tool create_payment_intent \
  --amount 750

  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         DENIED
  Connector      stripe
  Tool           create_payment_intent
  Permission     write (from manifest)

  Token Scopes
  └ tool:stripe:write:*:capped:500

  Reason         amount 750 exceeds cap of 500

  ─────────────────────────────────────────────

When within the cap:

grantex enforce test \
  --token "eyJ..." \
  --connector stripe \
  --tool create_payment_intent \
  --amount 200

  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         ALLOWED
  Connector      stripe
  Tool           create_payment_intent
  Permission     write (from manifest)
  Amount         200 (within cap of 500)

  Token Scopes
  └ tool:stripe:write:*:capped:500

  ─────────────────────────────────────────────

---

Grant Token Audience

Available in @grantex/cli@0.4.0 with SDK 0.8.0. Node.js 22.12+ is required; audience binding and default online revocation are breaking changes.

A grant token requested with an audience carries it in the aud claim, and enforce() denies it unless the relying party expects that audience (see Grant token audience). Pass the audience your service is issued tokens for with --audience:

grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool create_lead \
  --audience https://api.merchant.example

Without --audience, a token that carries aud is reported as denied with token_invalid / audience_unconfigured; a token whose aud does not contain the --audience value is denied with token_invalid / audience_mismatch. --audience-check off ignores aud, as earlier releases did:

grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool create_lead \
  --audience-check off

--audience-check takes on (the default) or off; any other value is refused. --audience cannot be empty or combined with --audience-check off, and both options are refused when the installed @grantex/sdk does not check the audience, instead of being ignored.

---

JSON Output

Use --json for machine-readable output, useful for scripting and CI pipelines:

grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool delete_contact \
  --json

{
  "allowed": false,
  "connector": "salesforce",
  "tool": "delete_contact",
  "permission": "delete",
  "scopes": ["tool:salesforce:write:*"],
  "reason": "write scope does not permit delete operations",
  "grantId": "grnt_01HXYZ",
  "agentDid": "did:grantex:ag_01HXYZ"
}

Allowed result:

{
  "allowed": true,
  "connector": "salesforce",
  "tool": "create_lead",
  "permission": "write",
  "scopes": ["tool:salesforce:write:*"],
  "reason": "",
  "grantId": "grnt_01HXYZ",
  "agentDid": "did:grantex:ag_01HXYZ"
}

---

Options

Flag	Description
--token <jwt>	The grant token to test against (required)
--connector <name>	The connector name (required)
--tool <name>	The tool name (required)
--amount <number>	Amount to test against capped scopes
--audience <audience>	The grant token audience the relying party expects, passed to enforce() for this call. From version 0.4.0.
--audience-check <on|off>	The client’s grant token audience check: on (default) or off, which ignores aud. From version 0.4.0.
--json	Output machine-readable JSON

---

Exit Codes

Code	Meaning
0	Tool call is allowed
1	Tool call is denied
2	Usage error (missing arguments, invalid token)

---

Related Commands

Command	Description
grantex manifest list	Browse pre-built manifests (or load your own)
grantex manifest show <connector>	Inspect tools and permissions for a connector
grantex manifest validate	Validate agent tools against a manifest
grantex verify	Inspect a grant token’s scopes, expiry, and delegation chain

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].