OWASP Web Shield Library API Reference

import React from "react";
import {
  ACLManager,
  AuthManager,
  CSRFTokenManager,
  HTTPClient,
  RBACManager,
  SSRFGuard,
  TokenManager
} from "@owasp-webshield/core";
import {
  ACLProvider,
  AuthGate,
  AuthProvider,
  PermissionGate,
  RBACProvider,
  SecurityAlert,
  SecurityProvider,
  useSafeFetcher,
  useSecureHttpClient
} from "@owasp-webshield/react";

const tokenManager = new TokenManager({
  onRefresh: async (refreshToken) => ({
    accessToken: `rotated-${refreshToken}`,
    refreshToken,
    expiresAt: Date.now() + 60_000
  })
});

const authManager = new AuthManager({ tokenManager });
authManager.setSession({ userId: "u1", roles: ["editor"] });

const aclManager = new ACLManager();
const rbacManager = new RBACManager();
rbacManager.defineRole("editor", ["read:articles", "update:articles"]);
aclManager.setPolicy("articles", "delete", "deny");

function SecureArticleList() {
  const client = useSecureHttpClient({
    baseUrl: "https://api.example.com",
    tokenProvider: () => tokenManager.getAccessToken()
  });
  const safeFetcher = useSafeFetcher({ allowProtocols: ["https:"] });

  async function loadArticles() {
    const response = await client.request("/articles", { method: "GET" });
    await safeFetcher.fetch("https://cdn.example.com/articles.json");
    return response.data;
  }

  return <button onClick={loadArticles}>Load articles</button>;
}

export function App() {
  return (
    <SecurityProvider logger={logger} events={events}>
      <AuthProvider authManager={authManager}>
        <ACLProvider aclManager={aclManager}>
          <RBACProvider rbacManager={rbacManager}>
            <AuthGate fallback={<SecurityAlert level="warn" message="Please sign in" />}>
              <PermissionGate
                action="read"
                resource="articles"
                fallback={<SecurityAlert level="error" message="Access denied" />}
              >
                <SecureArticleList />
              </PermissionGate>
            </AuthGate>
          </RBACProvider>
        </ACLProvider>
      </AuthProvider>
    </SecurityProvider>
  );
}

import React from "react";
import {
  ACLProvider,
  AuthContext,
  AuthGate,
  AuthProvider,
  PermissionGate,
  RBACProvider,
  SecurityProvider,
  useAuth,
  useAuthToken
} from "@owasp-webshield/react";

function SessionSummary() {
  const { session, isAuthenticated } = useAuth();
  const accessToken = useAuthToken();
  const authContext = React.useContext(AuthContext);

  return (
    <pre>
      {JSON.stringify({
        isAuthenticated,
        userId: session?.userId,
        tokenPreview: accessToken?.slice(0, 8),
        sameContext: authContext.session?.userId === session?.userId
      })}
    </pre>
  );
}

export function AuthTree({ authManager, aclManager, rbacManager, logger, events }) {
  return (
    <SecurityProvider logger={logger} events={events}>
      <AuthProvider authManager={authManager}>
        <ACLProvider aclManager={aclManager}>
          <RBACProvider rbacManager={rbacManager}>
            <AuthGate fallback={<div>Please sign in</div>}>
              <PermissionGate action="read" resource="reports" fallback={<div>Denied</div>}>
                <SessionSummary />
              </PermissionGate>
            </AuthGate>
          </RBACProvider>
        </ACLProvider>
      </AuthProvider>
    </SecurityProvider>
  );
}

import { AuthGate, OwlProvider, PermissionGate } from "@owasp-webshield/react";
import { owl } from "./security.js"; // owl = createOwlClient({ ... })

export function AuthTree({ children }) {
  return (
    <OwlProvider client={owl}>
      <AuthGate fallback={<div>Please sign in</div>}>
        <PermissionGate action="read" resource="reports" fallback={<div>Denied</div>}>
          {children}
        </PermissionGate>
      </AuthGate>
    </OwlProvider>
  );
}

import React from "react";
import {
  ACLContext,
  ACLProvider,
  PermissionGate,
  RBACContext,
  RBACProvider,
  useACL,
  usePermission
} from "@owasp-webshield/react";

function DeleteButton() {
  const aclManager = useACL();
  const permission = usePermission("delete", "reports");
  const aclContext = React.useContext(ACLContext);
  const rbacContext = React.useContext(RBACContext);

  return (
    <button disabled={!permission.allowed} data-acl={Boolean(aclContext)} data-rbac={Boolean(rbacContext)}>
      {aclManager.evaluate("reports", "delete").effect}
    </button>
  );
}

export function AccessControlExample({ aclManager, rbacManager }) {
  return (
    <ACLProvider aclManager={aclManager}>
      <RBACProvider rbacManager={rbacManager}>
        <PermissionGate action="delete" resource="reports" fallback={<span>Denied</span>}>
          <DeleteButton />
        </PermissionGate>
      </RBACProvider>
    </ACLProvider>
  );
}

import React from "react";
import { useCryptoManager } from "@owasp-webshield/react";

export function PasswordPreview() {
  const crypto = useCryptoManager();

  function handleDerive() {
    const { key, salt } = crypto.deriveKey("correct-horse-battery-staple");
    console.log(key.length, salt.toString("base64"));
  }

  return <button onClick={handleDerive}>Derive key</button>;
}

import React from "react";
import { SanitizedText, useInputSanitizer } from "@owasp-webshield/react";

export function CommentPreview({ rawHtml }) {
  const sanitizer = useInputSanitizer("moderate");
  const clean = sanitizer.sanitizeHTML(rawHtml);

  return (
    <div>
      <div>{clean}</div>
      <SanitizedText profile="strict" html={rawHtml} />
    </div>
  );
}

import React from "react";
import { useThreatModelGuard } from "@owasp-webshield/react";

export function WorkflowActions() {
  const guard = useThreatModelGuard({ transitions: { draft: ["review"], review: ["approved"] } });
  const transition = guard.validateTransition("draft", "review");

  return <button disabled={!transition.valid}>Submit for review</button>;
}

import React from "react";
import { useHardeningReport } from "@owasp-webshield/react";

export function ConfigDashboard({ config }) {
  const findings = useHardeningReport(config);

  return (
    <ul>
      {findings.map((finding) => (
        <li key={finding.id}>{finding.recommendation}</li>
      ))}
    </ul>
  );
}

import React from "react";
import { useDependencyRiskScanner } from "@owasp-webshield/react";

export function DependencyPanel({ provider }) {
  const { loading, results, error, runScan } = useDependencyRiskScanner(provider);

  React.useEffect(() => {
    runScan().catch(() => {});
  }, [runScan]);

  if (loading) return <div>Scanning...</div>;
  if (error) return <div>{error.message}</div>;
  return <pre>{JSON.stringify(results, null, 2)}</pre>;
}

import React from "react";
import { useSecureHttpClient, withSecurityHeaders } from "@owasp-webshield/react";

export function ProfileLoader({ tokenManager }) {
  const client = useSecureHttpClient({
    baseUrl: "https://api.example.com",
    tokenProvider: async () => tokenManager.getAccessToken()
  });

  async function loadProfile() {
    const response = await client.request(
      "/profile",
      withSecurityHeaders({
        method: "GET",
        headers: { "X-Feature": "profile-view" }
      })
    );

    console.log(response.data);
  }

  return <button onClick={loadProfile}>Load profile</button>;
}

import React from "react";
import {
  SecurityAlert,
  SecurityContext,
  SecurityProvider,
  useSecurityMonitoring
} from "@owasp-webshield/react";

function SecurityStatus() {
  const { logger, events } = useSecurityMonitoring();
  const securityContext = React.useContext(SecurityContext);

  React.useEffect(() => {
    logger?.info("security.status.rendered", { hasEvents: Boolean(events) });
  }, [logger, events]);

  return (
    <div>
      <div>{securityContext.logger ? "monitoring-enabled" : "monitoring-disabled"}</div>
      <SecurityAlert level="warn" message="Review recent security events" />
    </div>
  );
}

export function MonitoringExample({ logger, events }) {
  return (
    <SecurityProvider logger={logger} events={events}>
      <SecurityStatus />
    </SecurityProvider>
  );
}

import React from "react";
import { useSafeFetcher } from "@owasp-webshield/react";

export function RemoteConfigLoader() {
  const safeFetcher = useSafeFetcher({ allowProtocols: ["https:"] }, fetch);

  async function loadConfig() {
    const response = await safeFetcher.fetch("https://config.example.com/runtime.json");
    console.log(response.ok);
  }

  return <button onClick={loadConfig}>Load config</button>;
}