@sentinel-atl/registry 0.3.0

package/src/server.ts

@@ -0,0 +1,407 @@
+/**
+ * Trust Registry HTTP API — REST endpoints for publishing and querying STCs.
+ *
+ * Endpoints:
+ *   POST   /api/v1/certificates          Register a new STC
+ *   GET    /api/v1/certificates/:id       Get certificate by ID
+ *   GET    /api/v1/certificates           Query certificates
+ *   DELETE /api/v1/certificates/:id       Remove a certificate
+ *
+ *   GET    /api/v1/packages/:name         Get latest certificate for a package
+ *   GET    /api/v1/packages/:name/history Get all certificates for a package
+ *   GET    /api/v1/packages/:name/badge   SVG badge for a package
+ *   GET    /api/v1/packages/:name/badge/score   Score badge
+ *
+ *   GET    /api/v1/stats                  Registry stats
+ *   GET    /health                        Health check
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+import { CertificateStore, type RegistryEntry } from './store.js';
+import { gradeBadge, scoreBadge, verifiedBadge, notFoundBadge, type BadgeStyle } from './badge.js';
+import {
+  authenticate, hasScope, sendUnauthorized, sendForbidden,
+  applyCors, defaultCorsConfig,
+  createSecureServer,
+  applySecurityHeaders,
+  type AuthConfig, type CorsConfig, type TlsConfig,
+} from '@sentinel-atl/hardening';
+import type { SentinelTrustCertificate } from '@sentinel-atl/scanner';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface RegistryServerOptions {
+  /** Port to listen on */
+  port?: number;
+  /** Pre-configured certificate store */
+  store?: CertificateStore;
+  /** API key authentication config */
+  auth?: AuthConfig;
+  /** CORS configuration */
+  cors?: CorsConfig;
+  /** TLS configuration */
+  tls?: TlsConfig;
+}
+
+// ─── Server ──────────────────────────────────────────────────────────
+
+export class RegistryServer {
+  private server: Server | null = null;
+  private store: CertificateStore;
+  private port: number;
+  private authConfig: AuthConfig;
+  private corsConfig: CorsConfig;
+  private tlsConfig?: TlsConfig;
+
+  constructor(options?: RegistryServerOptions) {
+    this.port = options?.port ?? 3200;
+    this.store = options?.store ?? new CertificateStore();
+    this.authConfig = options?.auth ?? { enabled: false, keys: [] };
+    this.corsConfig = options?.cors ?? defaultCorsConfig();
+    this.tlsConfig = options?.tls;
+
+    // Badge endpoints are always public (for README embeds)
+    if (this.authConfig.enabled && !this.authConfig.publicPaths) {
+      this.authConfig.publicPaths = ['/health'];
+    }
+  }
+
+  getStore(): CertificateStore {
+    return this.store;
+  }
+
+  async start(): Promise<{ port: number }> {
+    // Load persisted certificates from backend (no-op if in-memory only)
+    await this.store.load();
+
+    return new Promise((resolve, reject) => {
+      this.server = createSecureServer(
+        (req, res) => this.handleRequest(req, res),
+        this.tlsConfig
+      );
+      this.server.on('error', reject);
+      this.server.listen(this.port, () => {
+        resolve({ port: this.port });
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  isTLS(): boolean {
+    return !!this.tlsConfig?.certPath || !!this.tlsConfig?.cert;
+  }
+
+  // ─── Router ────────────────────────────────────────────────────
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', `http://localhost`);
+    const path = url.pathname;
+    const method = req.method ?? 'GET';
+
+    // CORS (configurable origins)
+    if (applyCors(req, res, this.corsConfig)) return; // preflight handled
+
+    // Security headers
+    applySecurityHeaders(res, { hsts: this.isTLS() });
+
+    // Authentication
+    const authResult = authenticate(req, this.authConfig);
+
+    // Badge endpoints are public even when auth is enabled
+    const isBadgePath = path.includes('/badge');
+    if (!authResult.authenticated && !isBadgePath) {
+      return sendUnauthorized(res, this.authConfig, authResult.error);
+    }
+
+    try {
+      // Health
+      if (path === '/health' && method === 'GET') {
+        return this.sendJson(res, 200, { status: 'ok', certificates: this.store.count() });
+      }
+
+      // Stats
+      if (path === '/api/v1/stats' && method === 'GET') {
+        return this.sendJson(res, 200, this.store.getStats());
+      }
+
+      // POST /api/v1/certificates — register (requires write scope)
+      if (path === '/api/v1/certificates' && method === 'POST') {
+        if (!hasScope(authResult, 'write')) return sendForbidden(res, 'Write scope required');
+        return await this.handleRegister(req, res);
+      }
+
+      // GET /api/v1/certificates — query
+      if (path === '/api/v1/certificates' && method === 'GET') {
+        return this.handleQuery(url, res);
+      }
+
+      // GET/DELETE /api/v1/certificates/:id
+      const certMatch = path.match(/^\/api\/v1\/certificates\/(.+)$/);
+      if (certMatch) {
+        const id = decodeURIComponent(certMatch[1]);
+        if (method === 'GET') return this.handleGetById(id, res);
+        if (method === 'DELETE') {
+          if (!hasScope(authResult, 'admin')) return sendForbidden(res, 'Admin scope required');
+          return this.handleDelete(id, res);
+        }
+      }
+
+      // Package routes: /api/v1/packages/:name[/history|/badge|/badge/score]
+      const pkgMatch = path.match(/^\/api\/v1\/packages\/(@[^/]+\/[^/]+|[^/]+)(\/.*)?$/);
+      if (pkgMatch) {
+        const packageName = decodeURIComponent(pkgMatch[1]);
+        const suffix = pkgMatch[2] ?? '';
+
+        if (suffix === '' && method === 'GET') return this.handleGetPackage(packageName, res);
+        if (suffix === '/history' && method === 'GET') return this.handlePackageHistory(packageName, res);
+        if (suffix === '/badge' && method === 'GET') return this.handleBadge(packageName, url, res);
+        if (suffix === '/badge/score' && method === 'GET') return this.handleScoreBadge(packageName, url, res);
+      }
+
+      this.sendJson(res, 404, { error: 'Not found' });
+    } catch (err) {
+      this.sendJson(res, 500, { error: 'Internal server error' });
+    }
+  }
+
+  // ─── Handlers ──────────────────────────────────────────────────
+
+  private async handleRegister(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    // Content-Type enforcement
+    const contentType = req.headers['content-type'];
+    if (!contentType || !contentType.includes('application/json')) {
+      return this.sendJson(res, 415, { error: 'Content-Type must be application/json' });
+    }
+
+    const body = await readBody(req);
+    let certificate: SentinelTrustCertificate;
+
+    try {
+      certificate = JSON.parse(body);
+    } catch {
+      return this.sendJson(res, 400, { error: 'Invalid JSON' });
+    }
+
+    // Comprehensive STC validation
+    const errors = validateSTC(certificate);
+    if (errors.length > 0) {
+      return this.sendJson(res, 400, { error: 'Invalid STC', details: errors });
+    }
+
+    // Check for duplicates
+    if (this.store.get(certificate.id)) {
+      return this.sendJson(res, 409, { error: 'Certificate already registered', id: certificate.id });
+    }
+
+    const entry = await this.store.register(certificate);
+
+    this.sendJson(res, 201, {
+      id: entry.id,
+      packageName: entry.packageName,
+      trustScore: entry.trustScore,
+      grade: entry.grade,
+      verified: entry.verified,
+      registeredAt: entry.registeredAt,
+    });
+  }
+
+  private handleGetById(id: string, res: ServerResponse): void {
+    const entry = this.store.get(id);
+    if (!entry) {
+      return this.sendJson(res, 404, { error: 'Certificate not found' });
+    }
+    this.sendJson(res, 200, this.formatEntry(entry));
+  }
+
+  private async handleDelete(id: string, res: ServerResponse): Promise<void> {
+    const removed = await this.store.remove(id);
+    if (!removed) {
+      return this.sendJson(res, 404, { error: 'Certificate not found' });
+    }
+    this.sendJson(res, 200, { deleted: true, id });
+  }
+
+  private handleQuery(url: URL, res: ServerResponse): void {
+    const parseIntSafe = (val: string | null): number | undefined => {
+      if (val === null) return undefined;
+      const n = parseInt(val, 10);
+      return Number.isNaN(n) ? undefined : n;
+    };
+
+    const q = {
+      packageName: url.searchParams.get('package') ?? undefined,
+      minScore: parseIntSafe(url.searchParams.get('minScore')),
+      minGrade: url.searchParams.get('minGrade') ?? undefined,
+      verified: url.searchParams.has('verified') ? url.searchParams.get('verified') === 'true' : undefined,
+      limit: parseIntSafe(url.searchParams.get('limit')),
+      offset: parseIntSafe(url.searchParams.get('offset')),
+    };
+
+    const results = this.store.query(q);
+    this.sendJson(res, 200, {
+      total: this.store.count(),
+      count: results.length,
+      certificates: results.map(e => this.formatEntry(e)),
+    });
+  }
+
+  private handleGetPackage(packageName: string, res: ServerResponse): void {
+    const entry = this.store.getLatestForPackage(packageName);
+    if (!entry) {
+      return this.sendJson(res, 404, { error: 'No certificates found for package', packageName });
+    }
+    this.sendJson(res, 200, this.formatEntry(entry));
+  }
+
+  private handlePackageHistory(packageName: string, res: ServerResponse): void {
+    const entries = this.store.getForPackage(packageName);
+    this.sendJson(res, 200, {
+      packageName,
+      count: entries.length,
+      certificates: entries.map(e => this.formatEntry(e)),
+    });
+  }
+
+  private handleBadge(packageName: string, url: URL, res: ServerResponse): void {
+    const style = (url.searchParams.get('style') ?? 'flat') as BadgeStyle;
+    const entry = this.store.getLatestForPackage(packageName);
+
+    let svg: string;
+    if (!entry) {
+      svg = notFoundBadge(style);
+    } else if (entry.verified) {
+      svg = gradeBadge(entry.grade, style);
+    } else {
+      svg = verifiedBadge(false, style);
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'image/svg+xml',
+      'Cache-Control': 'max-age=300',
+    });
+    res.end(svg);
+  }
+
+  private handleScoreBadge(packageName: string, url: URL, res: ServerResponse): void {
+    const style = (url.searchParams.get('style') ?? 'flat') as BadgeStyle;
+    const entry = this.store.getLatestForPackage(packageName);
+
+    let svg: string;
+    if (!entry) {
+      svg = notFoundBadge(style);
+    } else {
+      svg = scoreBadge(entry.trustScore, style);
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'image/svg+xml',
+      'Cache-Control': 'max-age=300',
+    });
+    res.end(svg);
+  }
+
+  // ─── Helpers ───────────────────────────────────────────────────
+
+  private formatEntry(entry: RegistryEntry) {
+    return {
+      id: entry.id,
+      packageName: entry.packageName,
+      packageVersion: entry.packageVersion,
+      trustScore: entry.trustScore,
+      grade: entry.grade,
+      verified: entry.verified,
+      registeredAt: entry.registeredAt,
+      issuerDid: entry.issuerDid,
+      certificate: entry.certificate,
+    };
+  }
+
+  private sendJson(res: ServerResponse, status: number, data: unknown): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+  }
+}
+
+// ─── STC Validation ───────────────────────────────────────────────────
+
+function validateSTC(cert: any): string[] {
+  const errors: string[] = [];
+
+  if (!cert || typeof cert !== 'object') {
+    return ['Certificate must be a JSON object'];
+  }
+
+  // Required fields
+  if (!cert.id || typeof cert.id !== 'string') errors.push('Missing or invalid "id" (string)');
+  if (cert.type !== 'SentinelTrustCertificate') errors.push('"type" must be "SentinelTrustCertificate"');
+  if (cert['@context'] !== 'https://sentinel.trust/stc/v1') errors.push('"@context" must be "https://sentinel.trust/stc/v1"');
+
+  // Timestamps
+  if (!cert.issuedAt || typeof cert.issuedAt !== 'string') errors.push('Missing "issuedAt" (ISO date)');
+  if (!cert.expiresAt || typeof cert.expiresAt !== 'string') errors.push('Missing "expiresAt" (ISO date)');
+
+  // Issuer
+  if (!cert.issuer || typeof cert.issuer !== 'object') {
+    errors.push('Missing "issuer" object');
+  } else {
+    if (!cert.issuer.did || typeof cert.issuer.did !== 'string') errors.push('Missing "issuer.did"');
+  }
+
+  // Subject
+  if (!cert.subject || typeof cert.subject !== 'object') {
+    errors.push('Missing "subject" object');
+  } else {
+    if (!cert.subject.packageName || typeof cert.subject.packageName !== 'string') errors.push('Missing "subject.packageName"');
+    if (!cert.subject.packageVersion || typeof cert.subject.packageVersion !== 'string') errors.push('Missing "subject.packageVersion"');
+  }
+
+  // Trust score
+  if (!cert.trustScore || typeof cert.trustScore !== 'object') {
+    errors.push('Missing "trustScore" object');
+  } else {
+    if (typeof cert.trustScore.overall !== 'number' || cert.trustScore.overall < 0 || cert.trustScore.overall > 100) {
+      errors.push('"trustScore.overall" must be a number 0-100');
+    }
+    if (!cert.trustScore.grade || typeof cert.trustScore.grade !== 'string') {
+      errors.push('Missing "trustScore.grade"');
+    }
+  }
+
+  // Proof
+  if (!cert.proof || typeof cert.proof !== 'object') {
+    errors.push('Missing "proof" object');
+  }
+
+  return errors;
+}
+
+// ─── Body Reader ──────────────────────────────────────────────────────
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const MAX_BODY = 2_097_152; // 2 MB (STC max)
+
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        reject(new Error('Request body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.on('error', reject);
+  });
+}

package/src/store.ts

@@ -0,0 +1,267 @@
+/**
+ * Certificate Store — persistent storage for Sentinel Trust Certificates.
+ *
+ * Backed by SentinelStore interface — supports in-memory, Redis, Postgres, SQLite.
+ * By default uses in-memory Map for zero-config development.
+ */
+
+import { verifySTC, type SentinelTrustCertificate, type STCVerifyResult } from '@sentinel-atl/scanner';
+import type { SentinelStore } from '@sentinel-atl/store';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface RegistryEntry {
+  /** STC ID */
+  id: string;
+  /** Full certificate */
+  certificate: SentinelTrustCertificate;
+  /** Package name (for lookup) */
+  packageName: string;
+  /** Package version */
+  packageVersion: string;
+  /** Trust score */
+  trustScore: number;
+  /** Grade */
+  grade: string;
+  /** Whether signature is verified */
+  verified: boolean;
+  /** When the entry was registered */
+  registeredAt: string;
+  /** Issuer DID */
+  issuerDid: string;
+}
+
+export interface RegistryQuery {
+  /** Filter by package name */
+  packageName?: string;
+  /** Filter by minimum trust score */
+  minScore?: number;
+  /** Filter by minimum grade */
+  minGrade?: string;
+  /** Filter by verified status */
+  verified?: boolean;
+  /** Maximum results */
+  limit?: number;
+  /** Offset for pagination */
+  offset?: number;
+}
+
+export interface RegistryStats {
+  totalCertificates: number;
+  verifiedCertificates: number;
+  uniquePackages: number;
+  averageScore: number;
+  gradeDistribution: Record<string, number>;
+}
+
+// ─── Grade Helpers ───────────────────────────────────────────────────
+
+const GRADE_ORDER: Record<string, number> = { A: 4, B: 3, C: 2, D: 1, F: 0 };
+
+function gradeAtLeast(actual: string, required: string): boolean {
+  return (GRADE_ORDER[actual] ?? 0) >= (GRADE_ORDER[required] ?? 0);
+}
+
+// ─── Store ───────────────────────────────────────────────────────────
+
+/**
+ * Options for creating a CertificateStore.
+ * If `backend` is provided, certificates are persisted via SentinelStore.
+ * Otherwise, an in-memory Map is used (development only).
+ */
+export interface CertificateStoreOptions {
+  /** Persistent backend — data survives restarts */
+  backend?: SentinelStore;
+  /** Key prefix for the backend (default: 'registry:') */
+  prefix?: string;
+}
+
+const KEY_PREFIX_DEFAULT = 'registry:';
+const CERT_PREFIX = 'cert:';
+const PKG_INDEX_PREFIX = 'pkg:';
+
+export class CertificateStore {
+  private cache = new Map<string, RegistryEntry>();
+  /** Index: packageName → entry IDs (newest first) */
+  private pkgIndex = new Map<string, string[]>();
+  private backend?: SentinelStore;
+  private prefix: string;
+  private loaded = false;
+
+  constructor(options?: CertificateStoreOptions) {
+    this.backend = options?.backend;
+    this.prefix = options?.prefix ?? KEY_PREFIX_DEFAULT;
+  }
+
+  /** Load all entries from the backend into the in-memory cache. Call once on startup. */
+  async load(): Promise<void> {
+    if (this.loaded || !this.backend) return;
+    const keys = await this.backend.keys(`${this.prefix}${CERT_PREFIX}`);
+    const values = await this.backend.getMany(keys);
+    for (const [, json] of values) {
+      const entry: RegistryEntry = JSON.parse(json);
+      this.cache.set(entry.id, entry);
+      const existing = this.pkgIndex.get(entry.packageName) ?? [];
+      existing.push(entry.id);
+      this.pkgIndex.set(entry.packageName, existing);
+    }
+    // Sort each package's IDs by registeredAt descending
+    for (const [pkg, ids] of this.pkgIndex) {
+      ids.sort((a, b) => {
+        const ea = this.cache.get(a)!;
+        const eb = this.cache.get(b)!;
+        return eb.registeredAt.localeCompare(ea.registeredAt);
+      });
+    }
+    this.loaded = true;
+  }
+
+  /**
+   * Register a new certificate. Verifies signature before storing.
+   */
+  async register(certificate: SentinelTrustCertificate): Promise<RegistryEntry> {
+    const result: STCVerifyResult = await verifySTC(certificate);
+
+    const entry: RegistryEntry = {
+      id: certificate.id,
+      certificate,
+      packageName: certificate.subject.packageName,
+      packageVersion: certificate.subject.packageVersion,
+      trustScore: certificate.trustScore.overall,
+      grade: certificate.trustScore.grade,
+      verified: result.valid,
+      registeredAt: new Date().toISOString(),
+      issuerDid: certificate.issuer.did,
+    };
+
+    this.cache.set(entry.id, entry);
+
+    // Update package index
+    const existing = this.pkgIndex.get(entry.packageName) ?? [];
+    existing.unshift(entry.id); // newest first
+    this.pkgIndex.set(entry.packageName, existing);
+
+    // Persist to backend
+    if (this.backend) {
+      await this.backend.set(`${this.prefix}${CERT_PREFIX}${entry.id}`, JSON.stringify(entry));
+      await this.backend.set(
+        `${this.prefix}${PKG_INDEX_PREFIX}${entry.packageName}`,
+        JSON.stringify(existing)
+      );
+    }
+
+    return entry;
+  }
+
+  /**
+   * Get a certificate by ID.
+   */
+  get(id: string): RegistryEntry | undefined {
+    return this.cache.get(id);
+  }
+
+  /**
+   * Get the latest certificate for a package.
+   */
+  getLatestForPackage(packageName: string): RegistryEntry | undefined {
+    const ids = this.pkgIndex.get(packageName);
+    if (!ids || ids.length === 0) return undefined;
+    return this.cache.get(ids[0]);
+  }
+
+  /**
+   * Get all certificates for a package.
+   */
+  getForPackage(packageName: string): RegistryEntry[] {
+    const ids = this.pkgIndex.get(packageName) ?? [];
+    return ids.map(id => this.cache.get(id)!).filter(Boolean);
+  }
+
+  /**
+   * Query certificates with filters.
+   */
+  query(q: RegistryQuery): RegistryEntry[] {
+    let results = Array.from(this.cache.values());
+
+    if (q.packageName) {
+      results = results.filter(e => e.packageName === q.packageName);
+    }
+    if (q.minScore !== undefined) {
+      results = results.filter(e => e.trustScore >= q.minScore!);
+    }
+    if (q.minGrade) {
+      results = results.filter(e => gradeAtLeast(e.grade, q.minGrade!));
+    }
+    if (q.verified !== undefined) {
+      results = results.filter(e => e.verified === q.verified);
+    }
+
+    // Sort by registeredAt descending
+    results.sort((a, b) => b.registeredAt.localeCompare(a.registeredAt));
+
+    const offset = q.offset ?? 0;
+    const limit = q.limit ?? 50;
+    return results.slice(offset, offset + limit);
+  }
+
+  /**
+   * Remove a certificate by ID.
+   */
+  async remove(id: string): Promise<boolean> {
+    const entry = this.cache.get(id);
+    if (!entry) return false;
+
+    this.cache.delete(id);
+
+    const ids = this.pkgIndex.get(entry.packageName);
+    if (ids) {
+      const idx = ids.indexOf(id);
+      if (idx !== -1) ids.splice(idx, 1);
+      if (ids.length === 0) this.pkgIndex.delete(entry.packageName);
+    }
+
+    // Persist deletion to backend
+    if (this.backend) {
+      await this.backend.delete(`${this.prefix}${CERT_PREFIX}${id}`);
+      if (ids && ids.length > 0) {
+        await this.backend.set(
+          `${this.prefix}${PKG_INDEX_PREFIX}${entry.packageName}`,
+          JSON.stringify(ids)
+        );
+      } else {
+        await this.backend.delete(`${this.prefix}${PKG_INDEX_PREFIX}${entry.packageName}`);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get registry statistics.
+   */
+  getStats(): RegistryStats {
+    const all = Array.from(this.cache.values());
+    const gradeDistribution: Record<string, number> = { A: 0, B: 0, C: 0, D: 0, F: 0 };
+
+    let totalScore = 0;
+    for (const entry of all) {
+      totalScore += entry.trustScore;
+      gradeDistribution[entry.grade] = (gradeDistribution[entry.grade] ?? 0) + 1;
+    }
+
+    return {
+      totalCertificates: all.length,
+      verifiedCertificates: all.filter(e => e.verified).length,
+      uniquePackages: this.pkgIndex.size,
+      averageScore: all.length > 0 ? Math.round(totalScore / all.length) : 0,
+      gradeDistribution,
+    };
+  }
+
+  /**
+   * Get total count (for pagination).
+   */
+  count(): number {
+    return this.cache.size;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}