@owasp-webshield/core

v2.0.0

Published

18 days ago

OWL (OWASP Webshield Library): practical OWASP Top 10 mitigation helpers for JavaScript apps

OWL is a production-focused JavaScript security toolkit that maps security controls directly to OWASP Top 10 categories (A01–A10). It ships a framework-agnostic core package, full React and Vue adapters, a Next.js adapter, and Node/Express server support — making security primitives as easy to use as any other NPM library.

📖 Full documentation and usage guide: shimmering-parfait-3d0863.netlify.app

🚀 Try the live Todo app demo: owl-todo-demo.netlify.app

Why OWL

| Problem | OWL Solution | |---|---| | Security scattered across ad-hoc snippets | Category-aligned modules A01–A10 | | No shared language between dev and security teams | OWASP-numbered APIs and typed errors | | Inconsistent deny/allow logic | Deterministic deny-overrides policy engine | | Risky outbound requests | SSRF guard wired directly into HTTPClient | | Secrets leaking through logs | Redaction-first SecurityLogger | | React apps with no auth or permission guard | AuthGate, PermissionGate, and provider hooks | | Vue apps rendering user HTML with v-html | v-safe-html, a sanitizing drop-in replacement, plus guards and composables | | Next.js route handlers each re-implementing auth, CSRF and validation | withOwl(), one wrapper that runs every check and maps failures to safe JSON errors |

Installation

npm install

Quick Start

import { createOwlClient, PermissionChecker } from "@owasp-webshield/core";

const owl = createOwlClient({
  roles: { admin: { permissions: ["read:invoice", "update:invoice"] } },
  acl: [{ resource: "invoice", action: "delete", effect: "deny" }]
});

owl.tokenManager.setTokens({ accessToken: "jwt", expiresAt: Date.now() + 3600000 });
owl.authManager.setSession({ userId: "u1", roles: ["admin"] });

const permissions = new PermissionChecker({ rbacManager: owl.rbacManager, aclManager: owl.aclManager });
console.log(permissions.check({ role: "admin", action: "read", resource: "invoice" }));

createOwlClient wires TokenManager, AuthManager, RBACManager, and ACLManager (plus a logger and event emitter) from one config object — construct them individually instead if you need finer control (see docs/api-reference.md).

Module Map by OWASP Number

| # | OWASP Category | Core Module | Key Exports | |---|---|---|---| | A01 | Broken Access Control | a01-access-control | RBACManager, ACLManager, PermissionChecker | | A02 | Crypto Failures | a02-crypto-integrity | CryptoManager, PBKDF2Adapter, Argon2Adapter, SecretPolicy | | A03 | Injection | a03-injection-defense | InputSanitizer, InputValidator | | A04 | Insecure Design | a04-insecure-design-guard | ThreatModelGuard, DesignChecklist | | A05 | Security Misconfiguration | a05-security-misconfiguration | SecurityConfigManager, HardeningReporter | | A06 | Vulnerable Components | a06-vulnerable-components | DependencyRiskScanner, ComponentPolicy | | A07 | Auth & Session Failures | a07-auth-session | AuthManager, TokenManager | | A08 | Data Integrity Failures | a08-data-integrity | CSRFTokenManager, HTTPClient | | A09 | Security Logging Failures | a09-logging-monitoring | SecurityLogger, EventEmitter | | A10 | SSRF | a10-ssrf-defense | SSRFGuard, SafeFetcher |

HTTPClient (A08) natively accepts an outboundRequestPolicy from SSRFGuard (A10), composing transport hardening and SSRF defense in one client.

Core Usage

import { InputSanitizer, InputValidator } from "@owasp-webshield/core";

const sanitizer = new InputSanitizer("strict");
const clean = sanitizer.sanitizeHTML('<img src=x onerror=alert(1)>safe');

const validator = new InputValidator();
const result = validator.validateSchema(
  { email: "[email protected]" },
  { email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ } }
);

React Adapter Usage

import { createOwlClient } from "@owasp-webshield/core";
import { AuthGate, OwlProvider, PermissionGate } from "@owasp-webshield/react";

const owl = createOwlClient({
  roles: { viewer: { permissions: ["read:reports"] } }
});
owl.authManager.setSession({ userId: "u1", roles: ["viewer"] });

export function App() {
  return (
    <OwlProvider client={owl}>
      <AuthGate fallback={<div>Please sign in</div>}>
        <PermissionGate action="read" resource="reports" fallback={<div>Forbidden</div>}>
          <div>Secure Content</div>
        </PermissionGate>
      </AuthGate>
    </OwlProvider>
  );
}

OwlProvider composes SecurityProvider/AuthProvider/ACLProvider/RBACProvider for you — see docs/react-adapter-usage.md if you need to wire those managers individually instead.

Vue Adapter Usage

// main.js
import { createApp } from "vue";
import { createOwlClient } from "@owasp-webshield/core";
import { createOwl, vSafeHtml } from "@owasp-webshield/vue";

const owl = createOwl({
  client: createOwlClient({ roles: { viewer: { permissions: ["read:reports"] } } })
});
createApp(App).use(owl).directive("safe-html", vSafeHtml).mount("#app");

<AuthGate>
  <PermissionGate action="read" resource="reports">
    <div v-safe-html="report.summary"></div>
    <template #fallback>Forbidden</template>
  </PermissionGate>
  <template #fallback>Please sign in</template>
</AuthGate>

See docs/vue-adapter-usage.md for the composables, v-safe-html and the Vue Router guard.

Next.js Adapter Usage

// app/api/reports/route.js
import { withOwl } from "@owasp-webshield/next";

export const POST = withOwl(
  async (request, context, { session, body }) => Response.json(await reports.create(session.userId, body), { status: 201 }),
  {
    auth: { verifyToken: (token) => sessionStore.lookup(token) },
    csrf: true,
    permission: { action: "write", resource: "reports", checker: owl },
    body: { schema: { title: { required: true, type: "string", maxLength: 120 } }, allowUnknownFields: false }
  }
);

@owasp-webshield/next/server reads the session in Server Components and Server Actions, and @owasp-webshield/next/client is the React adapter marked "use client". See docs/nextjs-integration.md for middleware, security headers and the full setup.

Integration Examples

| Example | Description | |---|---| | Core JS usage | Full composition guide for @owasp-webshield/core | | React adapter usage | Provider + hook composition for @owasp-webshield/react | | Vue adapter usage | Plugin, composables, v-safe-html and router guard for @owasp-webshield/vue | | OWL Enabled Node Secrets App ▶ | Team credential vault on @owasp-webshield/core with a plain-Node API on @owasp-webshield/node — every OWASP category (A01–A10), plus real AES-256-GCM encryption (CryptoManager) and a real npm audit | | OWL Enabled Vue + Express Incident Desk ▶ | Full-stack reference app: Vue 3 on @owasp-webshield/vue and an Express 5 API on @owasp-webshield/express, with every category (A01–A10) enforced end to end and covered by tests | | OWL Enabled Next.js Expense Portal ▶ | Expense claims on the Next.js App Router with @owasp-webshield/next: IDOR-safe claim scopes, segregation of duties and approval limits, login CSRF, session-bound CSRF tokens, Server Actions that check their caller, encrypted IBANs and an SSRF-guarded receipt import, with HTTP tests against the production build | | OWL Enabled React Todo App ▶ (live demo) | Full-featured Todo app on the React adapter — every OWASP category (A01–A10) doing real work in one product instead of ten tutorial pages | | Next.js integration | Route handler guards, middleware CSRF, next.config.js security headers, Server Component/Action sessions and client components for @owasp-webshield/next | | Node & Express integration | Express middleware (@owasp-webshield/express) and plain-Node functions (@owasp-webshield/node) for auth, access control, CSRF, validation, headers and SSRF checks |

Scripts

npm run build    # Build ESM and CJS outputs
npm run test     # Run Jest unit tests
npm run lint     # Run ESLint
npm run check    # lint + test (full quality gate)

Project Docs

| Document | Purpose | |---|---| | docs/api-reference.md | Full API reference with copyable examples | | docs/architecture.md | Architecture, module layout, and adoption guide | | docs/troubleshooting.md | Common issues and fixes | | CONTRIBUTING.md | Contribution guidelines | | SECURITY.md | Vulnerability disclosure policy | | SUPPORT.md | Getting help | | GOVERNANCE.md | Project governance | | CHANGELOG.md | Release history | | CODE_OF_CONDUCT.md | Community standards |

Contributing

Pull requests, bug reports, and feedback are welcome. See CONTRIBUTING.md for how to get started.

Before submitting a PR:

npm run check   # must pass

Tests must cover security-relevant success and failure paths.

Security

Do not open public issues for security vulnerabilities. Follow the private reporting process in SECURITY.md.

Star History

If OWL is useful to you, a star helps others discover it. ⭐

License

Apache 2.0 — see LICENSE.md.