@sentinel-atl/registry 0.3.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sentinel-atl/registry",
+  "version": "0.3.0",
+  "description": "Trust Registry API — publish, query, and verify Sentinel Trust Certificates",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sentinel-registry": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@sentinel-atl/scanner": "*",
+    "@sentinel-atl/hardening": "*",
+    "@sentinel-atl/store": "*"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4",
+    "typescript": "^5.7.0",
+    "@types/node": "^20.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sentinel-atl/project-sentinel.git",
+    "directory": "packages/registry"
+  },
+  "keywords": [
+    "sentinel",
+    "trust",
+    "registry",
+    "mcp",
+    "certificate",
+    "badge"
+  ]
+}

package/src/__tests__/registry.test.ts

@@ -0,0 +1,304 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { CertificateStore, RegistryServer, gradeBadge, scoreBadge, verifiedBadge, notFoundBadge } from '../index.js';
+import { InMemoryKeyProvider, publicKeyToDid } from '@sentinel-atl/core';
+import { scan, issueSTC, type SentinelTrustCertificate } from '@sentinel-atl/scanner';
+import { mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+async function createTempPackage(files: Record<string, string>): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'sentinel-reg-'));
+  for (const [name, content] of Object.entries(files)) {
+    const dirPath = join(dir, name.split('/').slice(0, -1).join('/'));
+    if (name.includes('/')) await mkdir(dirPath, { recursive: true });
+    await writeFile(join(dir, name), content, 'utf-8');
+  }
+  return dir;
+}
+
+let kp: InMemoryKeyProvider;
+let identity: { keyId: string; did: string };
+
+async function makeTestSTC(pkgName: string, version = '1.0.0'): Promise<SentinelTrustCertificate> {
+  const dir = await createTempPackage({
+    'package.json': JSON.stringify({ name: pkgName, version }),
+    'src/index.ts': 'export function handler() { return "ok"; }\n',
+  });
+  const report = await scan({ packagePath: dir, skipDependencies: true });
+  return issueSTC(kp, {
+    scanReport: report,
+    codeHash: `hash-${pkgName}-${version}`,
+    issuerDid: identity.did,
+    issuerKeyId: identity.keyId,
+  });
+}
+
+beforeEach(async () => {
+  kp = new InMemoryKeyProvider();
+  await kp.generate('test-key');
+  const pubKey = await kp.getPublicKey('test-key');
+  identity = { keyId: 'test-key', did: publicKeyToDid(pubKey) };
+});
+
+// ─── Store Tests ──────────────────────────────────────────────────────
+
+describe('CertificateStore', () => {
+  it('registers and retrieves a certificate', async () => {
+    const store = new CertificateStore();
+    const stc = await makeTestSTC('@test/pkg-a');
+    const entry = await store.register(stc);
+
+    expect(entry.id).toBe(stc.id);
+    expect(entry.verified).toBe(true);
+    expect(entry.packageName).toBe('@test/pkg-a');
+
+    const retrieved = store.get(stc.id);
+    expect(retrieved).toBeDefined();
+    expect(retrieved!.trustScore).toBe(stc.trustScore.overall);
+  });
+
+  it('gets latest for package', async () => {
+    const store = new CertificateStore();
+    const stc1 = await makeTestSTC('@test/pkg-b', '1.0.0');
+    const stc2 = await makeTestSTC('@test/pkg-b', '2.0.0');
+
+    await store.register(stc1);
+    await store.register(stc2);
+
+    const latest = store.getLatestForPackage('@test/pkg-b');
+    expect(latest).toBeDefined();
+    expect(latest!.packageVersion).toBe('2.0.0');
+  });
+
+  it('queries with filters', async () => {
+    const store = new CertificateStore();
+    await store.register(await makeTestSTC('@test/a'));
+    await store.register(await makeTestSTC('@test/b'));
+
+    const all = store.query({});
+    expect(all.length).toBe(2);
+
+    const filtered = store.query({ packageName: '@test/a' });
+    expect(filtered.length).toBe(1);
+    expect(filtered[0].packageName).toBe('@test/a');
+  });
+
+  it('removes a certificate', async () => {
+    const store = new CertificateStore();
+    const stc = await makeTestSTC('@test/removable');
+    await store.register(stc);
+
+    expect(store.count()).toBe(1);
+    const removed = await store.remove(stc.id);
+    expect(removed).toBe(true);
+    expect(store.count()).toBe(0);
+    expect(store.get(stc.id)).toBeUndefined();
+  });
+
+  it('provides stats', async () => {
+    const store = new CertificateStore();
+    await store.register(await makeTestSTC('@test/stats-a'));
+    await store.register(await makeTestSTC('@test/stats-b'));
+
+    const stats = store.getStats();
+    expect(stats.totalCertificates).toBe(2);
+    expect(stats.verifiedCertificates).toBe(2);
+    expect(stats.uniquePackages).toBe(2);
+    expect(stats.averageScore).toBeGreaterThan(0);
+  });
+});
+
+// ─── Badge Tests ──────────────────────────────────────────────────────
+
+describe('Badge SVG', () => {
+  it('generates grade badge', () => {
+    const svg = gradeBadge('A');
+    expect(svg).toContain('<svg');
+    expect(svg).toContain('Grade A');
+    expect(svg).toContain('#4c1'); // green
+  });
+
+  it('generates score badge', () => {
+    const svg = scoreBadge(87);
+    expect(svg).toContain('87/100');
+  });
+
+  it('generates verified badge', () => {
+    const svg = verifiedBadge(true);
+    expect(svg).toContain('Verified');
+  });
+
+  it('generates not-found badge', () => {
+    const svg = notFoundBadge();
+    expect(svg).toContain('Not Found');
+    expect(svg).toContain('#9f9f9f'); // gray
+  });
+
+  it('supports flat-square style', () => {
+    const svg = gradeBadge('B', 'flat-square');
+    expect(svg).toContain('rx="0"'); // no border radius
+  });
+});
+
+// ─── Server Tests ─────────────────────────────────────────────────────
+
+let nextPort = 18200;
+function getPort() { return nextPort++; }
+
+describe('RegistryServer', () => {
+  let server: RegistryServer | null = null;
+
+  afterEach(async () => {
+    if (server) { await server.stop(); server = null; }
+  });
+
+  it('starts and responds to /health', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const res = await fetch(`http://localhost:${port}/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.status).toBe('ok');
+  });
+
+  it('registers and retrieves a certificate via API', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const stc = await makeTestSTC('@test/api-pkg');
+
+    // Register
+    const postRes = await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(stc),
+    });
+    expect(postRes.status).toBe(201);
+    const postBody = await postRes.json() as any;
+    expect(postBody.id).toBe(stc.id);
+    expect(postBody.verified).toBe(true);
+
+    // Get by ID
+    const getRes = await fetch(`http://localhost:${port}/api/v1/certificates/${encodeURIComponent(stc.id)}`);
+    expect(getRes.status).toBe(200);
+    const getBody = await getRes.json() as any;
+    expect(getBody.packageName).toBe('@test/api-pkg');
+  });
+
+  it('rejects duplicate registration', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const stc = await makeTestSTC('@test/dup-pkg');
+
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(stc),
+    });
+
+    const res2 = await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(stc),
+    });
+    expect(res2.status).toBe(409);
+  });
+
+  it('serves grade badge for a package', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const stc = await makeTestSTC('@test/badge-pkg');
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(stc),
+    });
+
+    const badgeRes = await fetch(`http://localhost:${port}/api/v1/packages/${encodeURIComponent('@test/badge-pkg')}/badge`);
+    expect(badgeRes.status).toBe(200);
+    expect(badgeRes.headers.get('content-type')).toBe('image/svg+xml');
+    const svg = await badgeRes.text();
+    expect(svg).toContain('<svg');
+    expect(svg).toContain('Grade');
+  });
+
+  it('serves not-found badge for unknown package', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const badgeRes = await fetch(`http://localhost:${port}/api/v1/packages/${encodeURIComponent('@test/unknown')}/badge`);
+    expect(badgeRes.status).toBe(200);
+    const svg = await badgeRes.text();
+    expect(svg).toContain('Not Found');
+  });
+
+  it('queries certificates with filters', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(await makeTestSTC('@test/q1')),
+    });
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(await makeTestSTC('@test/q2')),
+    });
+
+    const res = await fetch(`http://localhost:${port}/api/v1/certificates?package=@test/q1`);
+    const body = await res.json() as any;
+    expect(body.count).toBe(1);
+    expect(body.certificates[0].packageName).toBe('@test/q1');
+  });
+
+  it('deletes a certificate', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    const stc = await makeTestSTC('@test/del-pkg');
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(stc),
+    });
+
+    const delRes = await fetch(`http://localhost:${port}/api/v1/certificates/${encodeURIComponent(stc.id)}`, {
+      method: 'DELETE',
+    });
+    expect(delRes.status).toBe(200);
+
+    const getRes = await fetch(`http://localhost:${port}/api/v1/certificates/${encodeURIComponent(stc.id)}`);
+    expect(getRes.status).toBe(404);
+  });
+
+  it('returns stats', async () => {
+    const port = getPort();
+    server = new RegistryServer({ port });
+    await server.start();
+
+    await fetch(`http://localhost:${port}/api/v1/certificates`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(await makeTestSTC('@test/stats-pkg')),
+    });
+
+    const res = await fetch(`http://localhost:${port}/api/v1/stats`);
+    const stats = await res.json() as any;
+    expect(stats.totalCertificates).toBe(1);
+    expect(stats.verifiedCertificates).toBe(1);
+  });
+});

package/src/badge.ts

@@ -0,0 +1,139 @@
+/**
+ * Badge SVG generator — produces shields.io-style trust badges.
+ *
+ * Badge formats:
+ *   - Trust grade badge:  "Sentinel | A" (green)
+ *   - Trust score badge:  "Trust Score | 87/100" (green)
+ *   - Verified badge:     "Sentinel Verified | ✓" (green)
+ *   - Not found badge:    "Sentinel | Not Found" (gray)
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type BadgeStyle = 'flat' | 'flat-square';
+
+export interface BadgeOptions {
+  /** Left label text */
+  label?: string;
+  /** Right value text */
+  value: string;
+  /** Color of the right side */
+  color: string;
+  /** Badge style */
+  style?: BadgeStyle;
+}
+
+// ─── Color Mapping ───────────────────────────────────────────────────
+
+const GRADE_COLORS: Record<string, string> = {
+  A: '#4c1',     // bright green
+  B: '#97ca00',  // yellow-green
+  C: '#dfb317',  // yellow
+  D: '#fe7d37',  // orange
+  F: '#e05d44',  // red
+};
+
+function scoreColor(score: number): string {
+  if (score >= 90) return GRADE_COLORS.A;
+  if (score >= 75) return GRADE_COLORS.B;
+  if (score >= 60) return GRADE_COLORS.C;
+  if (score >= 40) return GRADE_COLORS.D;
+  return GRADE_COLORS.F;
+}
+
+// ─── SVG Generator ───────────────────────────────────────────────────
+
+function escapeXml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function textWidth(text: string): number {
+  // Approximate character widths for Verdana 11px
+  return text.length * 6.5 + 10;
+}
+
+function renderBadge(options: BadgeOptions): string {
+  const label = options.label ?? 'Sentinel';
+  const { value, color } = options;
+  const isSquare = options.style === 'flat-square';
+
+  const labelWidth = textWidth(label);
+  const valueWidth = textWidth(value);
+  const totalWidth = labelWidth + valueWidth;
+  const radius = isSquare ? 0 : 3;
+
+  const escapedLabel = escapeXml(label);
+  const escapedValue = escapeXml(value);
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${escapedLabel}: ${escapedValue}">
+  <title>${escapedLabel}: ${escapedValue}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="${totalWidth}" height="20" rx="${radius}" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelWidth}" height="20" fill="#555"/>
+    <rect x="${labelWidth}" width="${valueWidth}" height="20" fill="${color}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
+    <text aria-hidden="true" x="${labelWidth / 2}" y="15" fill="#010101" fill-opacity=".3">${escapedLabel}</text>
+    <text x="${labelWidth / 2}" y="14">${escapedLabel}</text>
+    <text aria-hidden="true" x="${labelWidth + valueWidth / 2}" y="15" fill="#010101" fill-opacity=".3">${escapedValue}</text>
+    <text x="${labelWidth + valueWidth / 2}" y="14">${escapedValue}</text>
+  </g>
+</svg>`;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Generate a trust grade badge SVG.
+ */
+export function gradeBadge(grade: string, style?: BadgeStyle): string {
+  return renderBadge({
+    label: 'Sentinel',
+    value: `Grade ${grade}`,
+    color: GRADE_COLORS[grade] ?? '#9f9f9f',
+    style,
+  });
+}
+
+/**
+ * Generate a trust score badge SVG.
+ */
+export function scoreBadge(score: number, style?: BadgeStyle): string {
+  return renderBadge({
+    label: 'Trust Score',
+    value: `${score}/100`,
+    color: scoreColor(score),
+    style,
+  });
+}
+
+/**
+ * Generate a "Sentinel Verified" badge SVG.
+ */
+export function verifiedBadge(verified: boolean, style?: BadgeStyle): string {
+  return renderBadge({
+    label: 'Sentinel',
+    value: verified ? 'Verified ✓' : 'Unverified',
+    color: verified ? '#4c1' : '#9f9f9f',
+    style,
+  });
+}
+
+/**
+ * Generate a "not found" badge SVG.
+ */
+export function notFoundBadge(style?: BadgeStyle): string {
+  return renderBadge({
+    label: 'Sentinel',
+    value: 'Not Found',
+    color: '#9f9f9f',
+    style,
+  });
+}

package/src/cli.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+process.on('unhandledRejection', (err) => {
+  console.error('Unhandled rejection:', err);
+  process.exit(1);
+});
+process.on('uncaughtException', (err) => {
+  console.error('Uncaught exception:', err);
+  process.exit(1);
+});
+
+/**
+ * sentinel-registry — CLI for running the Trust Registry API server.
+ *
+ * Usage:
+ *   sentinel-registry                    Start on default port 3200
+ *   sentinel-registry --port 8080        Start on custom port
+ */
+
+import { RegistryServer } from './server.js';
+import { authConfigFromEnv, corsConfigFromEnv, tlsConfigFromEnv } from '@sentinel-atl/hardening';
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('🗂️  Sentinel Trust Registry');
+  console.log();
+  console.log('Usage:');
+  console.log('  sentinel-registry                    Start on port 3200');
+  console.log('  sentinel-registry --port <port>      Start on custom port');
+  console.log();
+  console.log('Endpoints:');
+  console.log('  POST   /api/v1/certificates          Register an STC');
+  console.log('  GET    /api/v1/certificates/:id       Get by ID');
+  console.log('  GET    /api/v1/certificates           Query certificates');
+  console.log('  DELETE /api/v1/certificates/:id       Remove');
+  console.log('  GET    /api/v1/packages/:name         Latest cert for package');
+  console.log('  GET    /api/v1/packages/:name/badge   SVG trust badge');
+  console.log('  GET    /api/v1/stats                  Registry stats');
+  console.log('  GET    /health                        Health check');
+  process.exit(0);
+}
+
+const portIdx = args.indexOf('--port');
+const port = portIdx !== -1 ? parseInt(args[portIdx + 1]) : 3200;
+
+const server = new RegistryServer({
+  port,
+  auth: authConfigFromEnv(),
+  cors: corsConfigFromEnv(),
+  tls: tlsConfigFromEnv(),
+});
+
+console.log('🗂️  Sentinel Trust Registry');
+const { port: actualPort } = await server.start();
+const proto = server.isTLS() ? 'https' : 'http';
+console.log(`  Listening on ${proto}://localhost:${actualPort}`);
+console.log();
+console.log('  Endpoints:');
+console.log('    POST   /api/v1/certificates');
+console.log('    GET    /api/v1/certificates/:id');
+console.log('    GET    /api/v1/packages/:name');
+console.log('    GET    /api/v1/packages/:name/badge');
+console.log('    GET    /api/v1/stats');
+console.log('    GET    /health');
+console.log();
+
+const shutdown = async () => {
+  console.log('\n  Shutting down...');
+  await server.stop();
+  process.exit(0);
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @sentinel-atl/registry — Trust Registry API
+ *
+ * Publish, query, and verify Sentinel Trust Certificates.
+ * Serves SVG trust badges for READMEs and dashboards.
+ *
+ * Usage:
+ *   sentinel-registry --port 3200
+ */
+
+export {
+  CertificateStore,
+  type CertificateStoreOptions,
+  type RegistryEntry,
+  type RegistryQuery,
+  type RegistryStats,
+} from './store.js';
+
+export {
+  RegistryServer,
+  type RegistryServerOptions,
+} from './server.js';
+
+export {
+  gradeBadge,
+  scoreBadge,
+  verifiedBadge,
+  notFoundBadge,
+  type BadgeStyle,
+  type BadgeOptions,
+} from './badge.js';