shieldstack-ts 0.1.0

package/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.DS_Store
+.env
+.git
+.gitignore
+coverage
+examples/demo/node_modules
+examples/demo/.next

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+
+  - type: input
+    id: version
+    attributes:
+      label: ShieldStack TS Version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Runtime
+      options:
+        - Node.js
+        - Bun
+        - Cloudflare Workers
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Initialize ShieldStack with config...
+        2. Call evaluateRequest with...
+        3. Observe...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any logs, screenshots, or other context

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature Request
+description: Suggest an idea for ShieldStack TS
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem would this feature solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe how you'd like this to work
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches you have considered
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - Low
+        - Medium
+        - High — blocking production use

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Summary
+
+<!-- Describe your changes clearly and concisely -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] My changes follow the code style of this project
+- [ ] I have run `npm run typecheck` with no errors
+- [ ] I have added tests that prove my fix/feature works
+- [ ] All existing tests pass (`npm run test`)
+- [ ] I have updated the documentation where necessary
+- [ ] I have updated `CHANGELOG.md` with my changes
+
+## Related Issues
+
+<!-- Link related issues: Fixes #123 -->
+
+## Testing
+
+<!-- Describe how you tested your changes -->

package/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x, 24.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build
+        run: npm run build
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: test
+    # Only publish on push to main AND when NPM_TOKEN secret is configured
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push' && secrets.NPM_TOKEN != ''
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        continue-on-error: true

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to ShieldStack TS will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-04-03
+
+### Added
+
+#### Core Engine
+- `ShieldStack` class as the central middleware orchestrator
+- `async evaluateRequest()` pipeline with ordered security checks
+- `validateOutput()` for Zod schema enforcement on LLM responses
+- `createStreamSanitizer()` returning a native `TransformStream<Uint8Array, Uint8Array>`
+
+#### Sanitizers
+- `PIIRedactor` — regex-based detection for emails, phone numbers, credit cards, and SSNs
+- Four configurable policies: `redact`, `hash`, `mask`, `block`
+- `InjectionDetector` — weighted heuristic scoring system to detect prompt injection attempts
+- `SecretsDetector` — high-entropy pattern detection for AWS keys, Slack/GitHub tokens
+
+#### Budgeting
+- `TokenLimiter` — async token bucket with sliding window enforcement
+- `RateLimitStore` interface for pluggable storage backends
+- `InMemoryStore` — default synchronous-equivalent in-process store
+- `RedisStore` — duck-typed Redis adapter compatible with `ioredis`, `@upstash/redis`, `node-redis`
+
+#### Streaming
+- `StreamSanitizer` — real-time chunk-level PII and secrets redaction via `TransformStream`
+
+#### Observability
+- `Logger` — structured JSON audit logging with `info`, `warn`, `error`, `debug` levels
+- Event types: `data_scrubbed`, `injection_detected`, `secrets_detected`, `rate_limit_exceeded`
+
+#### Adapters
+- `expressShield()` — Express.js `req/res/next` middleware
+- `withShield()` — Next.js App Router route handler wrapper
+- `honoShield()` — Hono middleware for Cloudflare Workers
+
+#### Developer Experience
+- Full CJS and ESM dual output via `tsup`
+- TypeScript declaration files (`.d.ts` and `.d.mts`)
+- Vitest test suite: 15 tests across 4 modules (100% pass rate)
+- Multi-stage production `Dockerfile` with non-root user security hardening
+- `docker-compose.yml` with Redis healthcheck and persistent volume
+- Next.js `examples/demo` — live "Trust Terminal" chat UI
+
+---
+
+## Upcoming — [0.2.0]
+
+- ML-based prompt injection classifier (DistilBERT)
+- Custom user-defined PII pattern registration
+- OpenTelemetry metrics export
+- Fastify adapter
+- Cloudflare Durable Objects store

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to ShieldStack TS
+
+## Development Setup
+
+```bash
+git clone https://github.com/ShujaSN/shieldstack-ts.git
+cd shieldstack-ts
+npm install
+npm run build
+npm run test
+```
+
+---
+
+## Development Workflow
+
+```bash
+npm run dev        # Watch mode — rebuilds library on file changes
+npm run test       # Run full Vitest suite
+npm run typecheck  # TypeScript type checking (no emit)
+npm run lint       # ESLint across src/
+npm run format     # Prettier formatting
+```
+
+---
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add Fastify adapter
+fix: correct SSN regex false positive
+docs: update Redis setup guide
+test: add edge case for empty stream chunks
+chore: bump tsup to v9
+```
+
+---
+
+## Branching Strategy
+
+| Branch | Purpose |
+|---|---|
+| `main` | Stable, production releases |
+| `develop` | Integration branch for features |
+| `feat/*` | Individual feature branches |
+| `fix/*` | Bug fix branches |
+
+---
+
+## Pull Request Guidelines
+
+1. All PRs must target `develop`, not `main`
+2. All tests must pass: `npm run test`
+3. TypeScript must compile cleanly: `npm run typecheck`
+4. Update `CHANGELOG.md` under `Upcoming` with your changes
+5. Fill out the PR template completely
+
+---
+
+## Adding a New Adapter
+
+1. Create `src/adapters/yourframework.ts`
+2. Export a function: `export function yourShield(shield: ShieldStack) { ... }`
+3. Re-export from `src/adapters/index.ts`
+4. Add a usage example to `README.md`
+5. Add tests in `tests/`
+
+---
+
+## Code Style
+
+- Functional where practical, class-based for stateful services
+- Async/await everywhere (no raw Promises)
+- No `any` types except where unavoidable in framework adapters
+- Prefer `const` over `let`
+
+---
+
+## Reporting Vulnerabilities
+
+See [SECURITY.md](./SECURITY.md) — do not open public issues for security concerns.

package/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:20-alpine AS lib-builder
+
+WORKDIR /lib
+
+COPY package*.json ./
+RUN npm ci --ignore-scripts
+
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS demo-builder
+
+WORKDIR /demo
+
+COPY examples/demo/package*.json ./
+RUN npm ci --ignore-scripts
+
+# Pull in the compiled library directly instead of relying on the file: link
+COPY --from=lib-builder /lib/dist /demo/node_modules/shieldstack-ts/dist
+COPY --from=lib-builder /lib/package.json /demo/node_modules/shieldstack-ts/package.json
+
+COPY examples/demo .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+COPY --from=demo-builder /demo/public ./public
+COPY --from=demo-builder --chown=nextjs:nodejs /demo/.next/standalone ./
+COPY --from=demo-builder --chown=nextjs:nodejs /demo/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Shuja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+<div align="center">
+
+<h1>🛡️ ShieldStack TS</h1>
+
+<p><strong>Enterprise-grade LLM security middleware for TypeScript applications.</strong><br/>
+Stop PII leaks, jailbreaks, and runaway API bills before they reach your LLM.</p>
+
+[![npm version](https://img.shields.io/npm/v/shieldstack-ts?color=blue&label=npm)](https://www.npmjs.com/package/shieldstack-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Tests](https://img.shields.io/badge/tests-15%20passing-brightgreen)](#testing)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![Edge Compatible](https://img.shields.io/badge/Edge-Compatible-orange?logo=cloudflare)](https://workers.cloudflare.com/)
+
+</div>
+
+---
+
+## Overview
+
+ShieldStack TS is a **framework-agnostic, edge-compatible** middleware layer that sits between your application and any LLM provider — OpenAI, Anthropic, Ollama, and others.
+
+It intercepts every request and response with sub-2ms overhead, enforcing your security policies without changing your application logic.
+
+```
+Your App  ──►  ShieldStack  ──►  LLM Provider
+              ↑  ↑  ↑  ↑
+              │  │  │  └─ Token Budget Enforcement
+              │  │  └──── Secrets Detection
+              │  └─────── Prompt Injection Defense
+              └────────── PII Redaction
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| 🔐 **PII Redaction** | Automatically strips emails, phone numbers, credit cards, and SSNs |
+| 🛡️ **Injection Detection** | Heuristic risk-scoring blocks jailbreak and system-override attempts |
+| 🔑 **Secrets Scanning** | Detects AWS keys, GitHub/Slack tokens, and high-entropy strings |
+| 💰 **Denial-of-Wallet Prevention** | Per-user async token budgets backed by in-memory or Redis storage |
+| 🌊 **Stream Sanitization** | Real-time chunk-level redaction via native `TransformStream` API |
+| 📊 **Audit Logging** | Structured JSON telemetry for every security event |
+| ✅ **Schema Validation** | Enforce structured LLM output contracts with Zod |
+| ⚡ **Edge-First** | Runs on Node.js, Bun, and Cloudflare Workers — zero native dependencies |
+
+---
+
+## Installation
+
+```bash
+npm install shieldstack-ts
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { ShieldStack } from 'shieldstack-ts';
+
+const shield = new ShieldStack({
+  pii: {
+    policy: 'redact',   // 'redact' | 'hash' | 'mask' | 'block'
+    emails: true,
+    creditCards: true,
+    phoneNumbers: true,
+  },
+  injectionDetection: {
+    threshold: 0.8,     // 0.0 (lenient) – 1.0 (strict)
+  },
+  tokenLimiter: {
+    maxTokens: 10000,   // max tokens per user per window
+    windowMs: 3600000,  // 1 hour
+  },
+});
+
+// Evaluate a prompt before sending to your LLM
+// Throws if blocked, returns sanitized text if safe
+const safePrompt = await shield.evaluateRequest(userInput, userId, tokenEstimate);
+
+// Sanitize the LLM's streaming response in real-time
+const sanitizedStream = llmResponse.body.pipeThrough(shield.createStreamSanitizer());
+```
+
+---
+
+## Framework Adapters
+
+### Express.js
+
+```typescript
+import { expressShield } from 'shieldstack-ts';
+
+app.post('/chat', expressShield(shield), (req, res) => {
+  // req.body is already PII-sanitized
+});
+```
+
+### Next.js App Router
+
+```typescript
+import { withShield } from 'shieldstack-ts';
+
+async function chatHandler(req: Request): Promise<Response> {
+  // your handler
+}
+
+export const POST = withShield(shield, chatHandler);
+```
+
+### Hono (Cloudflare Workers)
+
+```typescript
+import { honoShield } from 'shieldstack-ts';
+
+app.use('/chat', honoShield(shield));
+```
+
+---
+
+## Distributed Rate Limiting with Redis
+
+For multi-server deployments, pass a Redis client to share token budgets across all instances:
+
+```typescript
+import { ShieldStack, RedisStore } from 'shieldstack-ts';
+import { Redis } from '@upstash/redis'; // or ioredis, node-redis
+
+const shield = new ShieldStack({
+  tokenLimiter: {
+    maxTokens: 50000,
+    windowMs: 3600000,
+    store: new RedisStore(new Redis({ url: process.env.REDIS_URL })),
+  },
+});
+```
+
+> **Duck-typed client support** — any Redis client implementing `.get()`, `.set()`, and `.del()` works without forced peer dependencies.
+
+---
+
+## Redaction Policies
+
+Configure how PII is handled per field type:
+
+| Policy | Result | Use Case |
+|---|---|---|
+| `redact` | `[REDACTED_EMAIL]` | Maximum privacy |
+| `hash` | `[HASHED_EMAIL]` | Pseudonymous, consistent |
+| `mask` | `***` | Visual concealment |
+| `block` | Throws error | Zero-tolerance compliance |
+
+---
+
+## Structured Output Validation
+
+Enforce a Zod schema on LLM responses to prevent hallucinated shapes:
+
+```typescript
+import { z } from 'zod';
+
+const responseSchema = z.object({
+  answer: z.string(),
+  confidence: z.number().min(0).max(1),
+});
+
+const shield = new ShieldStack({ schema: responseSchema });
+
+// Validates and throws if LLM output doesn't match
+const validatedOutput = shield.validateOutput(llmJsonResponse);
+```
+
+---
+
+## Performance
+
+| Operation | Overhead |
+|---|---|
+| Token limit check (in-memory) | < 0.1ms |
+| Token limit check (Redis) | 1–3ms |
+| Injection detection | < 0.5ms |
+| PII redaction | < 1ms |
+| Stream sanitization per chunk | < 0.2ms |
+| **Total end-to-end** | **< 2ms** |
+
+LLM calls take 500ms–5s. ShieldStack adds less than **0.4%** overhead.
+
+---
+
+## Testing
+
+```bash
+npm run test
+```
+
+```
+✓ tests/pii.test.ts           (3 tests)
+✓ tests/injection.test.ts     (3 tests)
+✓ tests/tokenLimiter.test.ts  (3 tests)
+✓ tests/redisStore.test.ts    (6 tests)
+
+Test Files  4 passed
+Tests      15 passed
+```
+
+---
+
+## Running the Demo
+
+A full Next.js demo app is included to visualize the middleware in real-time:
+
+```bash
+cd examples/demo
+npm install
+npm run dev
+# Open http://localhost:3000
+```
+
+Try sending:
+- A prompt containing a fake email → watch `[REDACTED_EMAIL]` appear in the stream
+- `"Ignore previous instructions"` → watch it get blocked with a 403 error
+
+---
+
+## Docker
+
+Build the production image:
+
+```bash
+docker build -t shieldstack-demo .
+```
+
+Run the full stack (Demo + Redis):
+
+```bash
+docker compose up --build
+```
+
+Uses a **3-stage multi-stage build** for a minimal (`~80MB`), non-root, production-hardened container image.
+
+---
+
+## Compatibility
+
+| Runtime | Supported |
+|---|---|
+| Node.js 18+ | ✅ |
+| Bun 1.x | ✅ |
+| Cloudflare Workers | ✅ |
+| Deno (via npm compat) | ✅ |
+| AWS Lambda | ✅ |
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feat/my-feature`
+3. Commit your changes: `git commit -m 'feat: add my feature'`
+4. Push to the branch: `git push origin feat/my-feature`
+5. Open a Pull Request
+
+---
+
+## Security
+
+To report a vulnerability, see [SECURITY.md](./SECURITY.md). Please do **not** open a public GitHub issue for security concerns.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Ali Shuja