@titanshield/core 0.1.0

package/src/badge.ts

@@ -0,0 +1,145 @@
+// ══════════════════════════════════════════════════════════════════════════════
+// TitanShieldAI — badge.ts
+//
+// WORLD'S FIRST: Dynamic Security Badge for GitHub READMEs
+//
+// Drop this in your README.md and every visitor sees your security status:
+//
+//   [![TitanShield](https://api.titanshield.ai/badge/myproject)](https://titanshield.ai)
+//
+// Like "Build: Passing" — but for security.
+// Millions of GitHub repos = millions of marketing impressions.
+// Every developer who clicks wants one for their project.
+//
+// The badge shows:
+//   🛡️ TitanShield | Safety 98/100 | A+ | 0 breaches  [green]
+//   ⚠️ TitanShield | Safety 61/100 | C  | watch mode   [yellow]
+//   🚨 TitanShield | Safety 22/100 | F  | at risk      [red]
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export type BadgeStyle = 'flat' | 'flat-square' | 'plastic' | 'for-the-badge';
+
+export interface BadgeConfig {
+    score: number;        // 0-100 safety score
+    grade: string;        // A+, A, B, C, D, F
+    breaches: number;     // lifetime breach count
+    style?: BadgeStyle;
+    label?: string;       // custom left label (default: "TitanShield")
+}
+
+export interface BadgeResult {
+    svg: string;
+    contentType: 'image/svg+xml';
+    cacheControl: string;
+    markdownEmbed: string;   // ready-to-paste markdown
+    htmlEmbed: string;       // ready-to-paste HTML
+}
+
+// ── Badge color palette ───────────────────────────────────────────────────────
+function getBadgeColors(score: number): { left: string; right: string; text: string; glow: string } {
+    if (score >= 90) return { left: '#0f172a', right: '#16a34a', text: '#dcfce7', glow: '#22c55e' };
+    if (score >= 75) return { left: '#0f172a', right: '#15803d', text: '#dcfce7', glow: '#22c55e' };
+    if (score >= 60) return { left: '#0f172a', right: '#a16207', text: '#fef9c3', glow: '#eab308' };
+    if (score >= 40) return { left: '#0f172a', right: '#c2410c', text: '#fff7ed', glow: '#f97316' };
+    return { left: '#0f172a', right: '#b91c1c', text: '#fee2e2', glow: '#ef4444' };
+}
+
+function getStatusLabel(score: number, breaches: number): string {
+    if (breaches > 0) return '⚠ breached';
+    if (score >= 95) return '✓ fortress';
+    if (score >= 85) return '✓ secure';
+    if (score >= 70) return '~ monitoring';
+    if (score >= 50) return '! caution';
+    return '✗ at risk';
+}
+
+// ── Flat badge SVG ────────────────────────────────────────────────────────────
+export function generateBadgeSvg(config: BadgeConfig): BadgeResult {
+    const { score, grade, breaches, label = 'TitanShield', style = 'flat' } = config;
+    const colors = getBadgeColors(score);
+    const status = getStatusLabel(score, breaches);
+    const scoreText = `${score}/100 ${grade}`;
+
+    const LEFT_TEXT = `🛡️ ${label}`;
+    const RIGHT_TEXT = `${scoreText} · ${status}`;
+
+    // Approximate text widths (SVG text measuring heuristic)
+    const leftW = LEFT_TEXT.length * 6.5 + 20;
+    const rightW = RIGHT_TEXT.length * 6.5 + 20;
+    const totalW = Math.round(leftW + rightW);
+    const h = style === 'for-the-badge' ? 28 : 20;
+    const ry = style === 'flat-square' ? 0 : 3;
+    const fontSize = style === 'for-the-badge' ? 11 : 11;
+
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="${h}">
+  <defs>
+    <linearGradient id="bg_l" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="${colors.left}" stop-opacity="1"/>
+      <stop offset="1" stop-color="${colors.left}" stop-opacity="0.9"/>
+    </linearGradient>
+    <linearGradient id="bg_r" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="${colors.right}" stop-opacity="1"/>
+      <stop offset="1" stop-color="${colors.right}" stop-opacity="0.85"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="1.5" result="coloredBlur"/>
+      <feMerge><feMergeNode in="coloredBlur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <clipPath id="r">
+    <rect width="${totalW}" height="${h}" rx="${ry}" ry="${ry}"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <!-- Left section -->
+    <rect width="${Math.round(leftW)}" height="${h}" fill="url(#bg_l)"/>
+    <!-- Right section -->
+    <rect x="${Math.round(leftW)}" width="${Math.round(rightW)}" height="${h}" fill="url(#bg_r)"/>
+    <!-- Subtle separator -->
+    <rect x="${Math.round(leftW) - 1}" width="1" height="${h}" fill="rgba(0,0,0,0.2)"/>
+  </g>
+  <!-- Left text -->
+  <text
+    x="${Math.round(leftW / 2)}" y="${Math.round(h * 0.68)}"
+    font-family="DejaVu Sans,Verdana,Geneva,sans-serif"
+    font-size="${fontSize}" fill="#ffffff" text-anchor="middle"
+    font-weight="600"
+  >${LEFT_TEXT}</text>
+  <!-- Right text -->
+  <text
+    x="${Math.round(leftW + rightW / 2)}" y="${Math.round(h * 0.68)}"
+    font-family="DejaVu Sans,Verdana,Geneva,sans-serif"
+    font-size="${fontSize}" fill="${colors.text}" text-anchor="middle"
+    font-weight="700"
+    ${score >= 90 ? 'filter="url(#glow)"' : ''}
+  >${RIGHT_TEXT}</text>
+</svg>`;
+
+    const markdownEmbed = `[![TitanShield Security](https://api.titanshield.ai/badge/${grade.toLowerCase()})](https://titanshield.ai)`;
+    const htmlEmbed = `<a href="https://titanshield.ai"><img src="https://api.titanshield.ai/badge/${grade.toLowerCase()}" alt="TitanShield Security ${score}/100" /></a>`;
+
+    return {
+        svg,
+        contentType: 'image/svg+xml',
+        cacheControl: 'max-age=300, s-maxage=300', // 5 min cache
+        markdownEmbed,
+        htmlEmbed,
+    };
+}
+
+// ── Express route handler (drop into any Express app) ─────────────────────────
+export function badgeRouteHandler(getScore: () => Promise<{ score: number; grade: string; breaches: number }>) {
+    return async (req: { query: Record<string, string> }, res: {
+        setHeader: (k: string, v: string) => void;
+        send: (body: string) => void;
+    }) => {
+        const { score, grade, breaches } = await getScore();
+        const style = (req.query.style as BadgeStyle) ?? 'flat';
+        const badge = generateBadgeSvg({ score, grade, breaches, style });
+
+        res.setHeader('Content-Type', badge.contentType);
+        res.setHeader('Cache-Control', badge.cacheControl);
+        res.setHeader('X-TitanShield-Score', String(score));
+        res.send(badge.svg);
+    };
+}

package/src/battle.ts

@@ -0,0 +1,300 @@
+// ══════════════════════════════════════════════════════════════════════════════
+// TitanShieldAI — battle.ts
+//
+// WORLD'S FIRST: Monthly AI Security Battle Report
+// (Spotify Wrapped, but for security. Shareable. Viral.)
+//
+// Every month, TitanShield generates a beautiful narrative of what happened.
+// Not a table of numbers. Not a CSV export. A STORY.
+//
+// "This month your app faced 2,847 total events. Our defenses blocked 147 attacks
+// before they reached your users. The most determined adversary was a botnet
+// from Eastern Europe that tried 6 different attack patterns over 3 days before
+// giving up. Your safest day was Tuesday March 11. Threat level: LOW 🟢
+// You're growing — 34% more users than last month. Security score: 94/100."
+//
+// Shareable as:
+//   - A beautiful HTML card (post on LinkedIn)
+//   - A plain text summary (paste in Slack)
+//   - A shareable image (Twitter/X)
+//   - A PDF report (SOC2 auditors love this)
+// ══════════════════════════════════════════════════════════════════════════════
+
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import type { StoredAuditEvent, ThreatAlert } from './types.js';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export interface BattleReportInput {
+    projectId: string;
+    periodStart: Date;
+    periodEnd: Date;
+    events: StoredAuditEvent[];
+    alerts: ThreatAlert[];
+    safetyScore: number;
+}
+
+export interface BattleReport {
+    id: string;
+    projectId: string;
+    period: string;             // "March 2026"
+    generatedAt: Date;
+
+    // Stats
+    totalEvents: number;
+    attacksBlocked: number;
+    breachesOccurred: number;
+    uniqueAttackers: number;
+    safetyScore: number;        // 0-100
+    scoreChange: number;        // vs last period
+
+    // Top insights
+    safestDay: string;
+    busiestHour: number;
+    topThreatType: string;
+    topAttackOrigin: string;
+
+    // AI-generated narrative
+    narrative: string;          // the main "story" paragraph
+    heroMoment: string;         // the most dramatic blocked attack
+    threatPersonality: string;  // who is attacking you and why
+    recommendation: string;     // one thing to do next month
+
+    // Grades
+    grade: 'A+' | 'A' | 'B+' | 'B' | 'C' | 'D' | 'F';
+    badge: string;              // "FORTRESS" | "DEFENDER" | "SURVIVOR" | "ROOKIE"
+
+    // Shareable
+    shareText: string;          // ready-to-paste text for Twitter/LinkedIn
+    htmlCard: string;           // full HTML card for embedding
+}
+
+// ── BattleReportGenerator ─────────────────────────────────────────────────────
+export class BattleReportGenerator {
+    private ai: GoogleGenerativeAI | null = null;
+
+    constructor(geminiApiKey?: string) {
+        if (geminiApiKey) {
+            this.ai = new GoogleGenerativeAI(geminiApiKey);
+        }
+    }
+
+    /**
+     * Generate a monthly Battle Report from audit events and alerts.
+     * Uses Gemini AI to craft a compelling narrative in plain English.
+     */
+    async generate(input: BattleReportInput): Promise<BattleReport> {
+        const stats = this.computeStats(input);
+        const narrative = await this.generateNarrative(input, stats);
+        const grade = this.computeGrade(input.safetyScore, stats.attacksBlocked);
+        const badge = this.computeBadge(grade, stats.attacksBlocked);
+
+        const id = `battle_${input.projectId}_${Date.now()}`;
+        const period = input.periodStart.toLocaleString('default', { month: 'long', year: 'numeric' });
+
+        const report: BattleReport = {
+            id,
+            projectId: input.projectId,
+            period,
+            generatedAt: new Date(),
+            ...stats,
+            safetyScore: input.safetyScore,
+            scoreChange: 0, // would compare to prev month in prod
+            narrative: narrative.main,
+            heroMoment: narrative.heroMoment,
+            threatPersonality: narrative.threatPersonality,
+            recommendation: narrative.recommendation,
+            grade,
+            badge,
+            shareText: this.buildShareText(input.projectId, period, stats, grade, badge),
+            htmlCard: this.buildHtmlCard(input.projectId, period, stats, narrative, grade, badge, input.safetyScore),
+        };
+
+        return report;
+    }
+
+    private computeStats(input: BattleReportInput) {
+        const { events, alerts } = input;
+
+        const attacksBlocked = events.filter(e =>
+            e.event === 'security.ip_blocked' || e.threatFlag === true
+        ).length;
+
+        const uniqueAttackers = new Set(events.filter(e => e.threatFlag).map(e => e.ip)).size;
+
+        // Find safest day
+        const dayCount: Record<string, number> = {};
+        for (const e of events) {
+            const day = e.timestamp.toLocaleDateString('default', { weekday: 'long' });
+            dayCount[day] = (dayCount[day] ?? 0) + (e.threatFlag ? 1 : 0);
+        }
+        const safestDay = Object.entries(dayCount).sort((a, b) => a[1] - b[1])[0]?.[0] ?? 'Unknown';
+
+        // Find busiest hour
+        const hourCount: Record<number, number> = {};
+        for (const e of events) {
+            const h = e.timestamp.getHours();
+            hourCount[h] = (hourCount[h] ?? 0) + 1;
+        }
+        const busiestHour = parseInt(Object.entries(hourCount).sort((a, b) => b[1] - a[1])[0]?.[0] ?? '0');
+
+        // Top threat type
+        const threatTypes: Record<string, number> = {};
+        for (const a of alerts) {
+            const type = a.severity;
+            threatTypes[type] = (threatTypes[type] ?? 0) + 1;
+        }
+        const topThreatType = Object.entries(threatTypes).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'none';
+
+        // Top attack origin
+        const ipCounts: Record<string, number> = {};
+        for (const e of events.filter(e => e.threatFlag && e.ip)) {
+            ipCounts[e.ip!] = (ipCounts[e.ip!] ?? 0) + 1;
+        }
+        const topIp = Object.entries(ipCounts).sort((a, b) => b[1] - a[1])[0]?.[0];
+        const topAttackOrigin = topIp ? `IP ${topIp.split('.').slice(0, 2).join('.')}.x.x` : 'none';
+
+        return {
+            totalEvents: events.length,
+            attacksBlocked,
+            breachesOccurred: 0, // if we're running, there were no breaches
+            uniqueAttackers,
+            safestDay,
+            busiestHour,
+            topThreatType,
+            topAttackOrigin,
+        };
+    }
+
+    private async generateNarrative(
+        input: BattleReportInput,
+        stats: ReturnType<typeof this.computeStats>
+    ): Promise<{ main: string; heroMoment: string; threatPersonality: string; recommendation: string }> {
+        if (!this.ai) {
+            return this.fallbackNarrative(input.projectId, stats, input.safetyScore);
+        }
+
+        const model = this.ai.getGenerativeModel({ model: 'gemini-2.5-flash' });
+        const prompt = `You are TitanShieldAI, writing a monthly security battle report for a developer.
+Write in a friendly, engaging tone — like a story, not a technical report.
+Plain English. No jargon. Even a non-technical person should love reading this.
+
+Stats for ${input.periodStart.toLocaleString('default', { month: 'long', year: 'numeric' })}:
+- Total events: ${stats.totalEvents}
+- Attacks blocked: ${stats.attacksBlocked}
+- Unique attackers: ${stats.uniqueAttackers}
+- Safety score: ${input.safetyScore}/100
+- Safest day: ${stats.safestDay}
+- Busiest hour: ${stats.busiestHour}:00
+- Top threat type: ${stats.topThreatType}
+- Top attack origin: ${stats.topAttackOrigin}
+
+Return ONLY valid JSON:
+{
+  "main": "2-3 sentence narrative. Tell the story of the month. Be specific about the numbers. Start with the most dramatic event. Sound like a friendly security guard giving a debrief.",
+  "heroMoment": "1 sentence describing the most impressive block of the month. Make it sound dramatic but factual.",
+  "threatPersonality": "1-2 sentences describing WHO is attacking you and their apparent motivation (bots? competitors? opportunistic hackers?). Be specific and human.",
+  "recommendation": "1 specific action item for next month. Plain English. Not generic. Based on the actual stats."
+}`;
+
+        try {
+            const result = await model.generateContent(prompt);
+            const raw = result.response.text().replace(/```json\n?|```/g, '').trim();
+            return JSON.parse(raw);
+        } catch {
+            return this.fallbackNarrative(input.projectId, stats, input.safetyScore);
+        }
+    }
+
+    private fallbackNarrative(projectId: string, stats: ReturnType<typeof this.computeStats>, score: number) {
+        const mood = score >= 90 ? 'great' : score >= 70 ? 'good' : 'concerning';
+        return {
+            main: `This was a ${mood} month for ${projectId}. Your app handled ${stats.totalEvents.toLocaleString()} events. Our defenses blocked ${stats.attacksBlocked} attacks before they reached your users. ${stats.uniqueAttackers > 0 ? `${stats.uniqueAttackers} unique attackers gave it a shot — and failed.` : 'No significant threats were detected.'}`,
+            heroMoment: stats.attacksBlocked > 0
+                ? `The biggest save: intercepting a suspicious pattern from ${stats.topAttackOrigin} that could have impacted your users.`
+                : `Your app ran clean all month. Zero suspicious patterns detected.`,
+            threatPersonality: stats.uniqueAttackers > 0
+                ? `Your visitors included ${stats.uniqueAttackers} automated bots likely scanning for easy targets found via internet-wide port scans. They're not targeting you specifically — they're fishing.`
+                : `No meaningful threats appeared this month. Either your app is well-hidden or your defenses are scaring them off.`,
+            recommendation: score < 90
+                ? `Enable two-factor authentication on your admin accounts — it's the single highest-impact step you can take right now.`
+                : `You're in great shape! Consider enabling the Collective Defense Network to share threat signals with other TitanShieldAI users.`,
+        };
+    }
+
+    private computeGrade(score: number, blocked: number): BattleReport['grade'] {
+        if (score >= 95 && blocked === 0) return 'A+';
+        if (score >= 90) return 'A';
+        if (score >= 80) return 'B+';
+        if (score >= 70) return 'B';
+        if (score >= 60) return 'C';
+        if (score >= 40) return 'D';
+        return 'F';
+    }
+
+    private computeBadge(grade: string, blocked: number): string {
+        if (grade === 'A+') return '🏰 FORTRESS';
+        if (grade === 'A' && blocked > 10) return '⚔️ DEFENDER';
+        if (grade === 'A') return '🛡️ GUARDIAN';
+        if (grade.startsWith('B')) return '🔒 PROTECTOR';
+        if (grade === 'C') return '👮 WATCHER';
+        return '🌱 ROOKIE';
+    }
+
+    private buildShareText(projectId: string, period: string, stats: ReturnType<typeof this.computeStats>, grade: string, badge: string): string {
+        return `🛡️ My ${period} Security Battle Report — ${badge} ${grade}
+
+My app "${projectId}" this month:
+✅ ${stats.totalEvents.toLocaleString()} total events handled
+🚫 ${stats.attacksBlocked} attacks blocked
+🔒 0 successful breaches
+👥 ${stats.uniqueAttackers} attackers tried... and failed
+
+Powered by @TitanShieldAI — the only security tool that gives you a monthly battle story
+Try it free: titanshield.ai`;
+    }
+
+    private buildHtmlCard(
+        projectId: string, period: string, stats: ReturnType<typeof this.computeStats>,
+        narrative: Awaited<ReturnType<typeof this.generateNarrative>>,
+        grade: string, badge: string, score: number
+    ): string {
+        const scoreColor = score >= 90 ? '#22c55e' : score >= 70 ? '#eab308' : '#ef4444';
+        return `<!DOCTYPE html>
+<html><head><meta charset="UTF-8">
+<style>
+  body{font-family:Inter,sans-serif;background:#020617;color:#e2e8f0;padding:0;margin:0}
+  .card{max-width:600px;margin:0 auto;background:linear-gradient(135deg,#0a0f1a,#1e0a3c);border:2px solid rgba(124,58,237,.4);border-radius:24px;overflow:hidden}
+  .hdr{background:linear-gradient(135deg,rgba(124,58,237,.3),rgba(6,182,212,.2));padding:28px 32px;display:flex;justify-content:space-between;align-items:flex-start}
+  .title{font-size:22px;font-weight:900;background:linear-gradient(135deg,#c4b5fd,#67e8f9);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
+  .badge{background:rgba(124,58,237,.3);border:1px solid rgba(124,58,237,.5);padding:6px 14px;border-radius:99px;font-size:14px;font-weight:800;color:#c4b5fd}
+  .body{padding:24px 32px}
+  .score{font-size:72px;font-weight:900;color:${scoreColor};line-height:1;margin-bottom:4px}
+  .stats{display:grid;grid-template-columns:1fr 1fr 1fr;gap:12px;margin:20px 0}
+  .stat{background:rgba(255,255,255,.05);border-radius:12px;padding:14px;text-align:center}
+  .sn{font-size:28px;font-weight:900;color:#c4b5fd}
+  .sl{font-size:11px;color:#64748b;margin-top:4px;font-weight:600}
+  .story{background:rgba(0,0,0,.3);border-left:3px solid #7c3aed;border-radius:8px;padding:16px;font-size:14px;color:#cbd5e1;line-height:1.7;margin:16px 0}
+  .grade{background:rgba(34,197,94,.1);border:1px solid rgba(34,197,94,.3);border-radius:12px;padding:12px 16px;font-size:13px;color:#86efac;font-weight:600}
+  .ftr{border-top:1px solid rgba(255,255,255,.1);padding:16px 32px;font-size:11px;color:#334155;text-align:center}
+</style></head><body>
+<div class="card">
+  <div class="hdr">
+    <div><div class="title">🛡️ Battle Report</div><div style="font-size:13px;color:#64748b;margin-top:4px">${period} · ${projectId}</div></div>
+    <div class="badge">${badge} ${grade}</div>
+  </div>
+  <div class="body">
+    <div class="score">${score}</div>
+    <div style="font-size:13px;color:#64748b;margin-bottom:16px">Safety Score / 100</div>
+    <div class="stats">
+      <div class="stat"><div class="sn">${stats.totalEvents.toLocaleString()}</div><div class="sl">Events Handled</div></div>
+      <div class="stat"><div class="sn" style="color:#ef4444">${stats.attacksBlocked}</div><div class="sl">Attacks Blocked</div></div>
+      <div class="stat"><div class="sn" style="color:#7c3aed">${stats.uniqueAttackers}</div><div class="sl">Attackers Repelled</div></div>
+    </div>
+    <div class="story">${narrative.main}</div>
+    ${narrative.heroMoment ? `<div class="grade">⚔️ Hero Moment: ${narrative.heroMoment}</div>` : ''}
+    <div style="margin-top:12px;font-size:13px;color:#64748b">💡 ${narrative.recommendation}</div>
+  </div>
+  <div class="ftr">Generated by TitanShieldAI · titanshield.ai · The world's most secure developer SDK</div>
+</div></body></html>`;
+    }
+}