TA
v0.1.0TypeScript SDK

Getting Started

Install the QAuth TypeScript SDK and create your first quantum-safe token in under 5 minutes.

Install

npm install @quantumshield/qauth

Requires Node.js 18+. TypeScript 4.7+ recommended.

Quick Start (5 minutes)

Create a token, validate it, and generate a proof of possession — the three core operations.

quick-start.ts
1import { QAuthServer, QAuthClient, QAuthValidator } from '@quantumshield/qauth';
2
3// 1. Create a server instance (generates Ed25519 keys)
4const server = new QAuthServer({
5 issuer: 'https://auth.example.com',
6 audience: 'https://api.example.com',
7});
8
9// 2. Create an access token
10const token = server.createToken({
11 subject: 'user-123',
12 policyRef: 'urn:qauth:policy:default',
13 validitySeconds: 3600,
14 claims: { email: 'user@example.com', roles: ['user'] },
15});
16
17// 3. Validate the token
18const payload = server.validateToken(token);
19console.log('User:', payload.sub); // "user-123"
20console.log('Expires:', payload.exp); // Unix timestamp
21
22// 4. Client-side: Create proof of possession
23const client = new QAuthClient();
24const proof = client.createProof('GET', '/api/resource', token);
25
26// 5. Send both token and proof with requests
27// Authorization: QAuth <token>
28// X-QAuth-Proof: <proof>

Core Concepts

QAuth has four main classes, each handling a different part of the authentication flow.

QAuthServer

Creates and validates tokens. Generates Ed25519 signing keys on construction. Used on your auth server to issue tokens and on API servers to validate them.

QAuthClient

Client-side key management. Generates a keypair for proof-of-possession. Stolen tokens are useless without the client's private key.

QAuthValidator

Standalone token validator. Uses pre-shared public keys to validate tokens without access to the signing private key. Deploy on API servers.

PolicyEngine

Fine-grained authorization. Replace OAuth scopes with policy documents that support RBAC, ABAC, time-based conditions, IP restrictions, and MFA requirements.

Token Lifecycle

How a QAuth token flows through your system.

1

Create

Server generates token with Ed25519 signature

2

Sign

Dual-signed with Ed25519 + ML-DSA-65 keys

3

Send

Client receives token and creates proof

4

Validate

API server verifies signature and expiry

5

Prove

Client proves key ownership per-request

Distributed Validation

Validate tokens on separate API servers using shared public keys. No private key exposure.

validator.ts
1import { QAuthServer, QAuthValidator, ProofValidator } from '@quantumshield/qauth';
2
3// On your auth server:
4const server = new QAuthServer({
5 issuer: 'https://auth.example.com',
6 audience: 'https://api.example.com',
7});
8
9// Share public keys with your API servers
10const publicKeys = server.getPublicKeys();
11// => { keyId, ed25519PublicKey, encryptionKey }
12
13// On your API server:
14const validator = new QAuthValidator(publicKeys, {
15 issuer: 'https://auth.example.com',
16 audience: 'https://api.example.com',
17});
18
19// Validate incoming tokens
20const payload = validator.validate(token);
21
22// Validate proof of possession
23const proofValidator = new ProofValidator(clientPublicKey);
24const isValid = proofValidator.validate(proof, 'GET', '/api/resource', token);

Policy-Based Authorization

Replace OAuth scopes with fine-grained policy documents.

policy.ts
1import { PolicyEngine } from '@quantumshield/qauth';
2
3const engine = new PolicyEngine();
4
5// Load a policy document
6engine.loadPolicy({
7 id: 'urn:qauth:policy:api-access',
8 version: '2026-01-30',
9 issuer: 'https://auth.example.com',
10 rules: [
11 {
12 id: 'read-projects',
13 effect: 'allow',
14 resources: ['projects/*'],
15 actions: ['read', 'list'],
16 },
17 {
18 id: 'admin-only',
19 effect: 'allow',
20 resources: ['admin/**'],
21 actions: ['*'],
22 conditions: {
23 custom: { role: { in: ['admin'] } },
24 },
25 priority: 10,
26 },
27 ],
28});
29
30// Evaluate authorization
31const result = engine.evaluate('urn:qauth:policy:api-access', {
32 subject: { id: 'user-123', attributes: { role: 'user' } },
33 resource: { path: 'projects/456' },
34 request: { action: 'read' },
35});
36// result.effect === 'allow'

Next Steps

Full Auth System Guide

Build a complete auth system with signup, login, sessions, and protected routes.

API Reference

Complete documentation for every class, method, and type in the SDK.

Policy Engine Guide

Deep dive into policy documents, conditions, and real-world authorization patterns.

Interactive Demo

See QAuth token creation, validation, and proofs in action.