@owasp-webshield/vue

@owasp-webshield/vue

Vue 3 adapter for OWL (OWASP Webshield Library). It provides a plugin, category-aligned composables and guard components for @owasp-webshield/core, covering every OWASP Top 10 category (A01–A10). It also adds a sanitizing v-safe-html directive and a Vue Router guard.

Installation

npm install @owasp-webshield/core @owasp-webshield/vue

Requires vue 3.3 or later. vue-router 4 or later is needed only for createOwlRouterGuard().

Quick start

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

const owl = createOwl({
  client: createOwlClient({ roles: { viewer: { permissions: ["read:reports"] } } })
});

createApp(App).use(owl).directive("safe-html", vSafeHtml).mount("#app");

<!-- Reports.vue -->
<script setup>
import { AuthGate, PermissionGate, useAuth } from "@owasp-webshield/vue";
const { session } = useAuth();
defineProps({ report: Object });
</script>

<template>
  <AuthGate>
    <PermissionGate action="read" resource="reports">
      <h1>Reports for {{ session.userId }}</h1>
      <div v-safe-html="report.summary"></div>
      <template #fallback>You can't view reports.</template>
    </PermissionGate>
    <template #fallback>Please sign in.</template>
  </AuthGate>
</template>

Auth state is reactive. Logging in, logging out, a token refresh or a token expiring updates useAuth(), usePermission() and the gates without a reload.

Module map

Composable arguments can be plain values, refs or getters. Composables that build a core object (useSecureHttpClient, useSafeFetcher, useInputSanitizer, ...) return a ComputedRef that is rebuilt when a reactive argument changes.

v-safe-html

A drop-in replacement for v-html, which is Vue's most common XSS sink. The value goes through InputSanitizer before it is inserted:

<div v-safe-html="comment.body"></div>                 <!-- strict: text only -->
<div v-safe-html:moderate="post.body"></div>           <!-- formatting tags, safe links and images -->
<div v-safe-html="{ html: post.body, profile: 'moderate', allowedClasses: ['note'] }"></div>

Turn on eslint-plugin-vue's vue/no-v-html rule so that new v-html uses get flagged. During server-side rendering, the directive needs Vue 3.4.36 or later; older versions render an empty element on the server and fill it in on the client.

Router guard

import { installOwlRouterGuard } from "@owasp-webshield/vue";

const routes = [
  { path: "/account", component: Account, meta: { requiresAuth: true } },
  { path: "/reports/:id", component: Report,
    meta: { permission: { action: "read", resource: (to) => `report:${to.params.id}` } } }
];

installOwlRouterGuard(router, owl, { loginRoute: "/login", forbiddenRoute: "/403" });

installOwlRouterGuard() checks every navigation, and also re-checks the open page when the session changes: a logout or an expired token redirects to the login page, and losing the permission redirects to the forbidden route. Use router.beforeEach(createOwlRouterGuard(owl, options)) if you only want the navigation check.

Security notes

• AuthGate, PermissionGate and the router guard only decide what the UI shows. The server must still authorize every request; see @owasp-webshield/express.
• With server-side rendering (Nuxt, createSSRApp), call createOwl() inside the app factory so every request gets its own managers. A module-level instance would share one user's session with every other request.
• useSecureHttpClient() sends the server's XSRF-TOKEN cookie as X-CSRF-Token, which matches @owasp-webshield/express's defaults. It never makes up a CSRF token in the browser.

Documentation

• Full Vue adapter usage guide
• API reference
• Runnable example (owl-enabled-vue-express-incident-desk)
• FAQ

License

Apache-2.0. See the main repository for the full license text and contribution guidelines.