# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## Unreleased

### Added
- Published `@grantex/cli` 0.3.0 on 2026-08-10 with one-command Agent Skills installation for Hermes, OpenClaw, portable `.agents/skills` workspaces, and custom skill roots.
- Added the `use-grantex-cli` and `integrate-grantex` skills for safe JSON-first operations and service-boundary implementation guidance.
- Added cross-platform token input from environment variables, files, and stdin, plus non-zero JSON-mode status codes for invalid or denied checks.
- Added `audience` support to TypeScript, Python, and Go authorization requests.
- Added missing TypeScript Vault documentation, package READMEs, JSON-LD contexts, and documentation health checks.
- Added transactional Redis-backed throughput enforcement for developer API-key requests handled by the standard auth plugin, keyed by developer and plan: Free 100, Pro 500, and Enterprise 2,000 requests per 60 seconds. It runs after the active Fastify per-IP policy (the 5,000/min default or a route-specific override); exhaustion returns structured `429` headers, and counter unavailability fails closed with `503`.
  Commerce, SCIM Bearer data-plane, admin, and other custom-auth routes remain outside these plan buckets.

### Changed
- Published TypeScript SDK 0.3.13, Python SDK 0.3.14, and Go SDK v0.1.10 on 2026-07-11; synchronized the public release snapshot across the landing page, README, compatibility matrix, and SDK documentation.

### Fixed
- Corrected the Go SDK source contract across Agent and Audit reads/writes: `agentId` mapping, optional registration fields, status updates, explicit scope clearing, required audit-write fields, `developerId` reads, and list envelopes.
  Removed unsupported audit filters and URL-encoded query values, with API-shaped regression tests.
  These fixes are not part of the currently published `v0.1.10` module.
- Corrected SDK quick starts, audit payloads, verification examples, endpoint paths, usage semantics, package metadata, and OpenAPI coverage.
- Fixed production issuer alias handling across offline verifiers and tightened Go grant-claim verification.
- Hardened JWKS key selection and caching, LDAP bind framing and DN escaping, and production deployment-secret validation.
- Secured Trust Registry DNS ownership verification, removed unsupported seeded claims, and fixed filtered cursor pagination.
- Prevented duplicate active MCP certification applications and persisted their pending state in the portal.
- Reconciled landing-page examples and product claims with the implemented APIs and supported verification workflows.

### Documentation
- Added dedicated Hermes, OpenClaw, and generic agent-CLI guides and made the support visible on the landing page, integration index, README, and machine-readable LLM guides.
- Expanded the core OpenAPI description and aligned landing pages, SDK guides, compatibility data, deployment guidance, and release metadata.
- Replaced unsupported certification, compliance, latency, cache, and automatic-audit claims with implementation-backed behavior.

## v0.3.12 / Integration SDK verification releases (2026-06-20)

### Added
- Added `@grantex/strands` 0.1.0, a TypeScript Strands Agents SDK integration with JWKS-backed grant verification, optional `client.enforce()` mode, and 9 Vitest coverage cases.

### Security
- Python SDK `grantex` 0.3.12 tightens published dependency floors for token verification libraries.
- A2A, AutoGen, LangChain, Vercel AI, CrewAI, Google ADK, OpenAI Agents, and Strands integrations now verify grant tokens against JWKS before enforcing scopes.

### Releases
- Publishable patch releases prepared: `@grantex/a2a` 0.1.3, `grantex-a2a` 0.1.3, `@grantex/autogen` 0.1.6, `@grantex/langchain` 0.1.7, `@grantex/vercel-ai` 0.1.6, `@grantex/strands` 0.1.0, `grantex-crewai` 0.1.6, `grantex-adk` 0.1.5, and `grantex-openai-agents` 0.1.5.
- `grantex-strands` 0.1.1 prepared as the corrected PyPI release with verification docs and project metadata.

## v0.3.11 (2026-06-14)

### Fixes
- TypeScript, Python, and Go SDKs trim API key input before constructing `Authorization` headers.
- TypeScript SDK package version advanced to `0.3.11` for the publishable Commerce V1/OACP npm release.
- Python SDK package version advanced to `0.3.11` after the `0.3.10` Commerce upload.

## v0.3.10 (2026-06-14)

### Added
- Python SDK: `client.commerce.*` Commerce V1/OACP client for merchant discovery, catalog grounding, MCP tool calls, carts, consent, Commerce Passport, payment intents, checkout links, provider credentials, webhook sources, and operator health.
- Go SDK: `client.Commerce.*` Commerce V1/OACP client with matching discovery, catalog, idempotent write, MCP, provider webhook, and ops helpers.
- Python and Go Commerce V1 SDK docs.

### Fixes
- Python and Go SDK HTTP clients now support per-call headers for idempotency keys and provider webhook handling.
- Python and Go SDK error handling now parses nested Commerce/Fastify error envelopes.
- Python and Go SDK user-agent versions updated to `0.3.10`.

## v0.3.9 (2026-06-14)

### Added
- TypeScript SDK: `grantex.commerce.*` Commerce V1/OACP client for merchant discovery, catalog grounding, MCP tool calls, carts, consent, Commerce Passport, payment intents, checkout links, provider credentials, webhook sources, and operator health.
- TypeScript SDK docs: Commerce V1 guide published under the TypeScript SDK resources.

### Fixes
- TypeScript SDK HTTP client now supports per-call headers for idempotency keys and provider webhook handling.
- TypeScript SDK error handling now parses nested Commerce/Fastify error envelopes.
- TypeScript SDK user-agent version updated to `@grantex/sdk/0.3.9`.

### Verification
- SDK typecheck, tests, build, Commerce hardening validator, pilot-readiness validator, and live production read-path SDK probe passed.
- Live probe covered the Shopify merchant profile, authenticated catalog search, MCP catalog search, ops health, and Plural webhook signature fail-closed behavior.

## v0.3.8 / @grantex/mcp 0.1.9 (2026-04-08)

### Security
- `@grantex/mcp` 0.1.8 → 0.1.9: include `server.json` in npm tarball so MCP registry can index the manifest
- `@grantex/mcp` 0.1.8: shipped hono >=4.12.12 override + @hono/node-server 1.19.13 (6 CVEs)

### Fixes
- Python SDK 0.3.8: fixed `dict` type annotation for mypy `--strict` compatibility
- MCP registry re-published at 0.1.9 (0.1.7 and 0.1.8 tarballs lacked `server.json`)

### CI
- Expanded CI from 5 to 22 tested packages across 10 jobs (all green)
- Fixed Vitest 4 constructor mock compatibility in auth-service, CLI, and policy tests
- Auth-service: `validateConfig()` now called on startup (was defined but never invoked)
- Added `vitest.config.ts` to adapters, excluded gemma E2E from unit test runs

### Documentation
- Updated test stats: 3,536 tests across 28 packages (was 3,332 / 27)
- CHANGELOG: added v0.3.5, v0.3.6, v0.3.7 entries
- SECURITY.md: updated supported versions (0.1.x → 0.3.x), added gateway/mcp/dpdp to scope
- Python SDK passports page added to docs.json navigation

## v0.3.7 (2026-04-08)

### Added
- **TypeScript SDK: DpdpClient** — 11 methods for DPDP Act 2023 compliance (consent records, notices, grievances, erasure, exports), 14 tests
- **Python SDK: DpdpClient** — full DPDP parity with TypeScript SDK, 13 tests
- **Go SDK: DPDPService** — full DPDP parity, 12 tests
- **CLI: `grantex dpdp`** — 11 subcommands for DPDP operations (consent CRUD, notices, grievances, erasure, exports, principal records), 42 tests
- Auth service: 11 DPDP endpoints with Ed25519 consent proofs, access tracking, 7-day grievance SLA, retention policies
- Auth service: auto-revoke on consent withdrawal, data deletion enforcement
- Auth service: CSP header enforcement

### Security
- Upgraded `hono` to 4.12.12 — resolved 5 CVEs (cookie bypass, IPv6 matching, path traversal, serveStatic bypass, setCookie validation)
- Upgraded `@hono/node-server` to 1.19.13 — resolved CVE-2026-39406 (middleware bypass)
- Fixed SSRF vulnerability in CLI `dpdp` command (CodeQL js/file-access-to-http)
- Resolved all 21 Dependabot vite alerts across packages

### Documentation
- README: DPDP CLI commands, SDK usage examples, API endpoint table
- Landing page: version badges updated, DPDP feature card
- Mintlify docs: CLI DPDP section, SDK overview pages (TS/Py/Go) updated
- llms.txt: updated SDK versions and resource count

### Fixes
- Fixed E2E health check (`"healthy"` vs `"ok"` mismatch)
- Regenerated root package-lock.json to sync with updated deps
- Updated stale version references across DEPLOYMENT.md, requirements.txt, llms.txt

## v0.3.6 (2026-04-06)

### Security
- Resolved all npm vulnerabilities across all packages
- Upgraded brace-expansion to fix CVE (moderate severity)
- Bumped Go SDK to go 1.26.1 (fixes 3 stdlib CVEs)
- Tightened dependency version minimums (grantex-fastapi 0.1.4)

### Documentation
- Added comprehensive DEPLOYMENT.md with production deployment guide
- Added requirements.txt for Python projects
- Expanded .env.example to all 30 environment variables

## v0.3.5 (2026-04-06)

### Added
- Enterprise hardening: Fastify per-IP rate limiting with endpoint overrides (JWKS exempt), HTTP security headers (HSTS, CSP, X-Frame-Options), SDK retry with exponential backoff, structured JSON logging via pino, database connection pools, graceful shutdown
- Landing page: test coverage trust card, enterprise hardening features section
- OWASP ZAP CI integration for security scanning

### Fixes
- Added vitest.config.ts to 6 packages with undiscoverable tests
- Windows compatibility for CLI tests (shell:true)
- SEO improvements: twitter:site meta tags, crawlability updates
- Resolved 3 Codex review comments on enterprise hardening PR

## v0.3.4 (2026-04-05)

### SDK Parity
- Python SDK: Added PassportsClient (issue, get, revoke, list)
- Python SDK: Added EventsClient.subscribe() with Subscription class
- Python SDK: Fixed usage.history() and budgets.transactions() optional parameters
- Go SDK: Added PassportsService and VaultService (20/20 service parity)
- TypeScript SDK: Added AuthorizationRequest optional fields (sandbox, policyEnforced, effect)
- Python SDK: Added SSO type aliases (SsoConnectionListResponse, SsoSessionListResponse)

### Documentation
- 35 new API reference pages (budgets, domains, usage, vault, events, tokens, signup, policies, anomalies)
- Custom Manifests dedicated guide page
- Manifest messaging reframed: "bring your own manifest" as primary story

### Testing
- 315+ new tests across all SDKs and packages
- Auth service passport endpoint tests (25)
- Anomalies endpoint tests expanded (15 new)
- MCP server tests expanded (43 new, all 17 tools covered)
- Gemma module tests (78), DPDP module tests (66), JWT tests (44)

### Fixes
- Fixed mcp-auth peer dep constraint (^0.1.8 → >=0.1.8)
- Fixed manifest count: 53 connectors / 339 tools (was incorrectly 54/340)
- Dropped orphaned signing_keys table (migration 030)
- Tightened SDK version constraints across 13 integration packages
- Corrected README badges: 3,900+ tests, 27 packages

## [2.5.0] — April 2026

### Added

#### Anomaly Detection Dashboard & Custom Rules
- Anomaly detection dashboard with severity overview, activity chart, and alert management
- Alert detail page with timeline, context viewer, and resolution notes
- Rule builder page: view built-in rules, create custom rules, toggle enable/disable
- Anomaly detection landing page (`/anomaly`) with built-in rules table, integration logos, custom rule DSL example
- Mintlify docs: `features/anomaly-detection.mdx` (full reference) and `guides/anomaly-detection-setup.mdx` (setup guide)
- Expanded portal API client: alert CRUD, metrics, rules, channels
- 10 built-in anomaly detection rules: velocity spike, scope escalation, unknown agent, token replay, off-hours activity, high failure rate, concurrent sessions, delegation depth, budget overspend, geographic anomaly
- Alert lifecycle: open, acknowledged, resolved with audit trail
- Multi-channel notifications: Slack, PagerDuty, Datadog, email, webhook
- Custom rule DSL with agent filters, scope filters, time windows, and thresholds

#### Trust Registry Portal & Documentation
- Trust Registry portal screens (search, org detail, registration wizard) in developer portal
- `src/api/registry.ts` — API client for registry endpoints
- `RegistrySearch` page — filterable org card grid with verification badges and stats
- `RegistryOrgDetail` page — org profile with compliance grid, agent table, public keys, and DNS verify
- `RegisterOrgForm` page — 4-step wizard (details, contact, verification method, review)
- Trust Registry sidebar link in portal navigation
- `web/registry.html` — landing page with live search, featured orgs, verification methods, embeddable trust badge demo
- `docs/features/trust-registry.mdx` — feature documentation (data model, API endpoints, SDK usage, embeddable widget)
- `docs/guides/trust-registry-setup.mdx` — step-by-step registration and verification guide

#### @grantex/dpdp — DPDP Act 2023 & EU AI Act Compliance
- `@grantex/dpdp` package — DPDP Act 2023, GDPR, and EU AI Act compliance module for AI agent deployments
- `DPDPConsentRecord` — structured consent records with purpose mapping, retention periods, and DPDP section references
- `DPDPClient.createConsentRecord()` — create DPDP-compliant consent records linked to Grantex grants
- `DPDPClient.withdrawConsent()` — one-click consent withdrawal with instant grant revocation and cascade
- `DPDPClient.checkPurposeAdherence()` — verify agents stay within declared processing purposes
- `DPDPClient.exportAudit()` — generate framework-specific audit exports (DPDP, GDPR, EU AI Act)
- `DPDPClient.submitGrievance()` — data principal grievance mechanism with SLA tracking
- `DPDPClient.exportPrincipalData()` — data principal data export (DPDP S.11 / GDPR Art.20)
- Data principal portal with consent management, activity history, and grievance submission
- Compliance dashboard with consent status, purpose adherence, and withdrawal metrics
- DPDP Act 2023 section-by-section compliance mapping documentation
- EU AI Act article-by-article compliance mapping documentation
- DPDP compliance landing page at `grantex.dev/dpdp`
- Blog post: "DPDP Act 2023 and AI Agents: What Your Engineering Team Must Know"

#### @grantex/gemma — Offline Authorization for Gemma 4
- `createConsentBundle()`: Issue offline-capable consent bundles (online, once)
- `createOfflineVerifier()`: < 5ms JWT verification with zero network calls
- `createOfflineAuditLog()`: Ed25519-signed, hash-chained local audit log
- `auditLog.sync()`: Batch sync offline entries when connectivity restores
- `withGrantexAuth()` adapter for Google ADK tool wrapping
- LangChain adapter
- New backend endpoints: POST /v1/consent-bundles, POST /v1/audit/offline-sync,
  GET /v1/consent-bundles/:bundleId/revocation-status
- Examples: Android (Kotlin), Raspberry Pi (Python), iOS (Swift bridging)
- `grantex init gemma` CLI scaffold command

#### grantex verify CLI enhancement
- Full token inspection: scopes, expiry, delegation chain, signature
- `--check-revocation`: live revocation status check
- `--json`: machine-readable JSON output for scripting
- `--verbose`: full JWT header and claims display
- `--jwks-file`: offline verification from local JWKS file
- `--stdin`: pipe token from stdin
- `grantex decode`: decode without verify (jwt.io equivalent)
- `grantex audit inspect`: local audit log viewer
- `grantex audit verify`: hash chain integrity check
- `grantex registry lookup`: registry DID lookup from CLI
- `grantex registry verify-dns`: DNS verification from CLI

#### @grantex/mcp-auth GA — OAuth 2.1 + PKCE for MCP Servers
- `@grantex/mcp-auth` GA release — OAuth 2.1 + PKCE authorization server for any MCP server
- `createMcpAuthServer()` — single function call to register six RFC-compliant endpoints
- OAuth 2.1 authorization endpoint with mandatory PKCE S256 (no `plain`, no implicit grant)
- Dynamic Client Registration (RFC 7591) at `/register`
- Server metadata discovery (RFC 8414) at `/.well-known/oauth-authorization-server`
- Token introspection (RFC 7662) at `/introspect` with Grantex-specific claims
- Token revocation (RFC 7009) at `/revoke` with per-RFC 200 OK semantics
- Express.js middleware (`requireMcpAuth`) for JWT validation with scope enforcement
- Hono middleware (`requireMcpAuth`) with the same API surface
- `McpGrant` decoded token type with `sub`, `agentDid`, `scopes`, `grantId`, `delegationDepth`
- Custom `ClientStore` interface for persistent client registrations (Postgres, Redis, etc.)
- Consent UI customization (`appName`, `appLogo`, `privacyUrl`, `termsUrl`)
- Lifecycle hooks (`onTokenIssued`, `onRevocation`) for audit logging
- Per-endpoint rate limiting (10/min authorize, 20/min token, 30/min introspect)
- MCP Server Certification program — Bronze, Silver, and Gold tiers
- MCP Server Registry with certification badges and scope listings
- 13 automated conformance checks for MCP auth compliance
- Landing page at `grantex.dev/mcp`
- Mintlify docs: `features/mcp-auth-server` and `guides/mcp-certification`

### Changed
- Dashboard: New Bundles section for consent bundle management
- API: `POST /v1/authorize` accepts optional `offlineTTL` parameter

### Security
- Offline verifier: algorithm confusion attack (alg:none, HS256) blocked
- PKCE code_verifier comparison: timing-safe across all runtimes

## [0.2.4-mpp] - 2026-03-20

### Added
- `@grantex/mpp` package — agent identity and delegation for MPP (Machine Payments Protocol)
- `AgentPassportCredential` — W3C VC 2.0 credential type for MPP agent identity
- `POST /v1/passport/issue` — issue an agent passport credential
- `GET /v1/passport/:id` — retrieve a passport
- `POST /v1/passport/:id/revoke` — revoke a passport (flips StatusList2021 bit)
- `GET /v1/trust-registry/:orgDID` — public org trust record lookup
- `verifyPassport()` — merchant-side offline passport verification (<50ms on warm cache)
- `requireAgentPassport()` — Express middleware for passport verification
- `createMppPassportMiddleware()` — fetch middleware to attach passport headers
- `lookupOrgTrust()` — trust registry client with in-memory caching
- `grantex.passports` namespace in `@grantex/sdk` (issue, get, revoke, list)
- `agent-passport` as a valid `credentialFormat` in `POST /v1/token`
- MPP Payment Scopes (`payments:mpp:*`) in SPEC.md §4.2
- SPEC.md §15 — MPP Agent Passport specification
- Trust registry database table with 5 seeded demo orgs
- MPP demo service (`apps/mpp-demo-service/`) — MPP 402 flow simulator
- MPP demo UI (`apps/mpp-demo/`) — 3-screen interactive demo (issue, flow, verify)
- W3C JSON-LD context document at `grantex.dev/contexts/mpp/v1`
- E2E test for full MPP passport lifecycle

## [0.1.5] - 2026-03-01

### Added
- Principal sessions — `POST /v1/principal-sessions` creates short-lived session JWTs for end-users
- End-user permissions dashboard — `GET /permissions` serves HTML self-service UI
- Three principal endpoints: `GET /v1/principal/grants`, `GET /v1/principal/audit`, `DELETE /v1/principal/grants/:id`
- Express middleware (`@grantex/express`) — drop-in Grantex token verification for Node.js APIs
- FastAPI middleware (`grantex-fastapi`) — drop-in Grantex token verification for Python APIs
- Go SDK (`github.com/mishrasanjeev/grantex-go`) v0.1.0 — 12 resource services, offline JWT verification, PKCE, webhook HMAC-SHA256
- Service provider adapters (`@grantex/adapters`) — Google Calendar, Gmail, Stripe, Slack
- Reverse-proxy gateway (`@grantex/gateway`) — YAML-configured, Fastify-based token verification proxy
- `principalSessions.create()` in TypeScript and Python SDKs
- Conformance suite: principal-sessions test suite

### Changed
- Bumped `@grantex/sdk` to 0.1.5 and `grantex` (Python) to 0.1.5
- Bumped `@grantex/conformance` to 0.1.2

## [0.1.4] - 2026-02-28

### Added
- Token refresh — `POST /v1/token/refresh` with single-use rotation per SPEC §7.4
- `tokens.refresh()` method in TypeScript and Python SDKs
- Conformance suite: token refresh tests
- Troubleshooting guide in docs

### Changed
- Bumped `@grantex/sdk` to 0.1.4 and `grantex` (Python) to 0.1.4

## [0.1.3] - 2026-02-28

### Added
- PKCE (S256) support in authorization and token exchange flows
- `generatePkce()` helper in TypeScript SDK
- `generate_pkce()` helper in Python SDK
- Rate limiting on auth-service (100/min global, 20/min token, 10/min authorize)
- CHANGELOG.md, CODE_OF_CONDUCT.md, issue templates, PR template

### Changed
- Bumped `@grantex/sdk` to 0.1.3 and `grantex` (Python) to 0.1.3

### Fixed
- "ML-based detection" copy corrected to "Pattern-based detection" on landing page

## [0.1.2] - 2026-02-27

### Added
- `tokens.exchange()` method to TypeScript and Python SDKs for exchanging authorization codes for grant tokens
- Python examples for the token exchange flow
- OpenAI Agents SDK integration (`grantex-openai-agents`)
- Google ADK integration (`grantex-adk`)
- MCP server package (`@grantex/mcp`) with 13 tools for Claude Desktop / Cursor / Windsurf
- Health endpoint (`GET /health`) in auth-service
- CLI commands for policies, billing, SCIM, and SSO
- Portal webhooks management page
- Webhook retry with exponential backoff (persistent delivery table + background worker)
- Anomaly detection background worker (runs every 60 minutes)
- Plan limit enforcement for grants, audit entries, and policies

### Changed
- Bumped `@grantex/sdk` and `grantex` (Python) to 0.1.2
- Webhook delivery is now persistent with retry instead of fire-and-forget

## [0.1.1] - 2026-02-26

### Added
- CrewAI integration (`grantex-crewai`) published to PyPI
- Vercel AI SDK integration (`@grantex/vercel-ai`)
- AutoGen integration (`@grantex/autogen`)
- CLI tool (`@grantex/cli`) with commands for agents, grants, tokens, audit, and anomalies
- LangChain integration (`@grantex/langchain`)
- Example apps: quickstart-ts, quickstart-py, langchain-agent, crewai-agent, vercel-ai-chatbot
- Developer portal with React dashboard (agents, grants, audit, policies, anomalies, compliance, billing, settings)
- Landing page deployed to Firebase Hosting at grantex.dev
- Comprehensive documentation across all packages

### Changed
- Bumped integration packages to 0.1.1

### Fixed
- Compliance timestamptz cast using null instead of empty string
- Startup migration runner for production DB schema

## [0.1.0] - 2026-02-25

### Added
- Protocol specification v1.0 (SPEC.md)
- Auth service (Fastify + PostgreSQL + Redis) with full API surface:
  - Authorization flow (`POST /v1/authorize`, consent, approve/deny)
  - Token exchange, verification, and revocation
  - Grant management with delegation support
  - Tamper-evident audit log with hash chaining
  - Anomaly detection (rate spikes, high failure rates, new principals, off-hours activity)
  - Policy engine (allow/deny rules with priority, scopes, time-of-day constraints)
  - SCIM provisioning (users + tokens)
  - SSO configuration (OIDC)
  - Billing integration (Stripe)
  - Webhook registration and delivery
  - JWKS endpoint for offline token verification
- TypeScript SDK (`@grantex/sdk`) published to npm
- Python SDK (`grantex`) published to PyPI
- CI/CD pipelines (GitHub Actions): CI, deploy, CodeQL, dependency review
- Cloud Run deployment configuration
- Docker Compose for local development

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).