@grantex/gateway

@grantex/gateway

Zero-code reverse-proxy that enforces Grantex grant tokens in front of any API via YAML config.

Install

npm install @grantex/gateway @grantex/sdk

Quick Start

1. Create gateway.yaml:

upstream: https://api.internal.example.com
jwksUri: https://your-auth-server/.well-known/jwks.json
port: 8080
upstreamHeaders:
  X-Internal-Auth: "secret-key"
routes:
  - path: /calendar/**
    methods: [GET]
    requiredScopes: [calendar:read]
  - path: /calendar/**
    methods: [POST, PUT, PATCH]
    requiredScopes: [calendar:write]
  - path: /payments/**
    methods: [POST]
    requiredScopes: [payments:initiate]

2. Start the gateway:

npx @grantex/gateway --config gateway.yaml

3. Make requests with grant tokens:

curl -H "Authorization: Bearer <grant-token>" \
  http://localhost:8080/calendar/events

How It Works

Client → Gateway (verify token + check scopes) → Upstream API

1. Route matching — finds the first route matching the request method + path
2. Token verification — extracts Bearer token and verifies offline via JWKS
3. Scope checking — ensures the grant includes all required scopes for the route
4. Proxy — strips the Authorization header, adds upstream headers + X-Grantex-* context headers, forwards to upstream
5. Response — returns the upstream response as-is

YAML Config Reference

Field	Type	Required	Description
upstream	string	Yes	Base URL of the upstream API
jwksUri	string	Yes	JWKS endpoint for offline token verification
port	number	No	Listen port (default: 8080)
upstreamHeaders	object	No	Headers added to every upstream request
grantexApiKey	string	No	API key for audit logging
routes	array	Yes	Route definitions (see below)

Route Definition

Field	Type	Description
path	string	URL path pattern (* = single segment, ** = any depth)
methods	string[]	HTTP methods (GET, POST, PUT, PATCH, DELETE)
requiredScopes	string[]	Scopes that must be present in the grant token

Context Headers

The gateway adds these headers to upstream requests:

Header	Value
X-Grantex-Principal	Principal ID from the grant token
X-Grantex-Agent	Agent DID from the grant token
X-Grantex-GrantId	Grant ID from the grant token

Error Responses

Status	Error Code	When
404	ROUTE_NOT_FOUND	No route matches the request
401	TOKEN_MISSING	No Bearer token in Authorization header
401	TOKEN_INVALID	Token signature verification failed
401	TOKEN_EXPIRED	Token has expired
403	SCOPE_INSUFFICIENT	Grant doesn't include required scopes
502	UPSTREAM_ERROR	Upstream API is unreachable

Library API

Use the gateway programmatically:

import { createGatewayServer, loadConfig } from '@grantex/gateway';

const config = loadConfig('./gateway.yaml');
const server = createGatewayServer(config);

await server.listen({ port: config.port });

Docker

docker build -t grantex-gateway packages/gateway/
docker run -p 8080:8080 -v ./gateway.yaml:/etc/grantex/gateway.yaml grantex-gateway

Requirements

• Node.js 18+
• @grantex/sdk >= 0.1.0

License

Apache-2.0