Skip to content

Complete KeypointJS Documentation

Jump to bottom
AnasBex edited this page Jan 6, 2026 · 1 revision

KeypointJS v1.2.2 - Complete Documentation

License Version Downloads Node.js TypeScript Protocols Tests

A Modern, Multi-Protocol Authentication & Authorization Framework for Node.js

🎯 What's New in v1.2.2?

KeypointJS evolves from an HTTP-focused library into a complete multi-protocol API gateway and security framework.

🚀 Major Features

  • Multi-Protocol Support: HTTP/HTTPS, WebSocket, gRPC in one framework
  • Unified Authentication: Same keypoints work across all protocols
  • Protocol Engines: Extensible architecture for custom protocols
  • Enterprise Security: TLS/SSL awareness, trusted proxies, protocol validation
  • Zero Dependencies: Core functionality implemented natively

📦 Installation

npm install keypointjs
# or
yarn add keypointjs
# or
pnpm add keypointjs

# specific version
npm install keypointjs@1.2.2

Node.js >= 18 is required.

🚀 Quick Start

Basic HTTP Server

import { KeypointJS } from 'keypointjs';

const app = new KeypointJS();
app.get('/', (ctx) => ctx.json({ message: 'Hello World!' }));
app.listen(3000);

Multi-Protocol Server

const app = new KeypointJS({
  enableWebSocket: true,
  enableGrpc: true,
  enableHttp2: true,
  trustedProxies: ['192.168.1.0/24']
});

app.get('/api/data', (ctx) => {
  return ctx.json({ protocol: ctx.protocol, data: 'Hello!' });
});

app.listen(3000);

With Authentication

const app = new KeypointJS({ requireKeypoint: true });

await app.createKeypoint({
  keyId: 'client_123',
  secret: 'secure_secret',
  scopes: ['api:read', 'api:write'],
  protocols: ['https', 'wss', 'grpc+tls']
});

app.get('/api/secure', (ctx) => {
  if (!ctx.hasScope('api:read')) {
    return ctx.status(403).json({ error: 'Insufficient scope' });
  }
  return ctx.json({ data: 'Protected data' });
});

🏗️ Architecture

Multi-Protocol Engine Architecture

┌─────────────────────────────────────────┐
│         KeypointJS v1.2.2               │
├─────────────────────────────────────────┤
│  HTTP Engine | WebSocket Engine | gRPC │
├─────────────────────────────────────────┤
│ Protocol Adapter & Unified Auth Layer   │
│ Cross-Protocol Policies & Plugins       │
└─────────────────────────────────────────┘

Layered Middleware Pipeline

Layer 0  Pre-processing Hooks
Layer 1  Protocol Engine (Detection & Parsing)
Layer 2  CORS & Transport Guards
Layer 3  Keypoint Authentication
Layer 4  Authorization & Policy Engine
Layer 5  Plugin Processing
Layer 6  Route Execution
Layer 7  Response Normalization

📁 Project Structure

core/        Protocol engines & adapters
keypoint/    Identity, scopes, validation
policy/      Policy rules & engine
plugins/     Built-in and custom plugins

🔧 Configuration

const app = new KeypointJS({
  requireKeypoint: true,
  strictMode: true,
  enableWebSocket: true,
  enableGrpc: false,
  enableHttp2: true,
  trustedProxies: ['192.168.1.0/24', '10.0.0.0/8'],
  validateProtocol: true,
  maxRequestSize: '10mb'
});

🌐 Protocol Support

HTTP / HTTPS

  • HTTP/1.1, HTTP/2 (experimental)
  • TLS metadata extraction
  • Trusted proxy validation

WebSocket

const ws = app.enableWebSocket({ path: '/ws', requireKeypoint: true });
ws.onConnection(conn => console.log(conn.keypointId));

gRPC

  • gRPC over HTTP/2
  • Streaming & unary calls
  • Metadata-based authentication

Custom Protocols

app.registerProtocolEngine('mqtt', {
  detect: req => req.headers['protocol'] === 'mqtt',
  parse: async req => ({ topic: req.topic, payload: req.payload }),
  validate: async ctx => true
});

🔐 Authentication & Authorization

Keypoint Model

  • Protocol-bound identity
  • Scope-based authorization
  • Optional IP, origin, and rate limits

Scope Hierarchy

app.defineScope('admin', 'Administrative access');
app.scopeManager.addInheritance('admin', ['users:read', 'users:write']);

🧠 Policy Engine

Built-in rules:

  • Method
  • IP range
  • Origin
  • Time window
  • Rate limit

Custom policy:

app.addPolicy('premium', async (ctx) => {
  return ctx.getKeypointMetadata().tier === 'premium';
});

🔌 Plugin System

Plugins hook into the request lifecycle.

class CustomPlugin {
  async process(ctx, next) {
    await next(ctx);
  }
}

📡 API Reference (Summary)

  • app.listen()
  • app.get(), post(), put(), delete()
  • app.createKeypoint(), revokeKeypoint()
  • app.enableProtocol(), registerProtocolEngine()
  • app.addPolicy(), registerPlugin()

📊 Monitoring & Health

app.getStats();
app.healthCheck();

🛠️ Examples

  • Real-time chat (WebSocket)
  • API Gateway routing
  • Compliance-ready (HIPAA-style) APIs

🐛 Troubleshooting

  • Disable protocol validation for local testing
  • Reduce payload limits for memory pressure
  • Enable debug middleware for tracing

🔮 Roadmap

  • HTTP/3 (QUIC)
  • MQTT & SSE support
  • GraphQL transport
  • Cloud-native deployment presets

🤝 Contributing

  1. Fork the repo
  2. Create feature branch
  3. Add tests
  4. Open Pull Request

License

Apache-2.0

♥️Support & Links

KeypointJS v1.2.2 — Your multi-protocol API gateway for the modern web

Clone this wiki locally