Security & Human-in-the-Loop (HITL)

Security is a core design principle of OwlLayer. Because AI agents dynamically execute tools that manipulate client interfaces or database states, OwlLayer Server enforces a strict sandboxed safety model called Human-in-the-Loop (HITL).

---

1. What is Human-in-the-Loop?

HITL guarantees that an AI agent cannot execute critical actions (such as placing an order, deleting user data, or transferring funds) without explicit authorization from the human user.

---

2. Tool Risk Levels

When declaring tools using useAgentTool (frontend) or server.tool (backend), you assign a Risk Level representing the potential impact of the action:

The client validates the arguments with the tool's schema before applying the risk level: the user is never asked to approve a call whose arguments are invalid. See Argument Validation.

Risk Level	Impact	User Experience	Use Cases
none	Read-only / Passive	Invisible execution. No user prompt.	Checking product lists, reading weather, looking up tracking IDs.
low	Minor UI change	Lightweight toast/badge notification.	Adding items to shopping carts, opening/closing panels.
medium	Non-destructive update	Auto-closing confirm banner, easy to revert.	Filling text fields, applying discount coupons.
high	Destructive or Financial	Modal pop-up blocking action. Requires explicit click.	Redirecting to checkout, removing profile accounts.
critical	Severe / Financial	Modal pop-up requiring multi-factor or secondary approval.	Confirming transactions, executing payments.

Code Example: Specifying Tool Risks

import { useAgentTool } from '@owllayer/react';
import { z } from 'zod';

useAgentTool({
  name: 'wipe_entire_cart',
  description: 'Remove all products from the current cart',
  schema: z.object({}),
  risk: 'high' // Will block execution until the user clicks confirm
}, async () => {
  cart.clear();
  return { success: true };
});

---

3. Session Authentication & Security Tokens

API Key Restrictions

Browser API keys (pk_...) ship in your site's JavaScript, so treat them as public. OwlLayerServer protects them with:

• Origins per key: server.addApiKey('pk_shop', { allowedOrigins: ['https://shop.example.com'] }). Connections from another origin, or without an Origin header, are rejected.
• Server tools per key: server.tool(name, { description, risk, apiKeys: ['pk_backoffice'] }, handler). The tool is neither offered to nor executed for other keys.
• Size and rate limits: messages, request bodies and user messages are bounded by default (see Server Setup). Set rateLimit.userInputsPerMinutePerKey to cap the LLM cost of each application.
• One LLM turn at a time per session, and approvals or tool results are accepted only from the session that received the request.

What HITL guarantees

HITL protects the user from an action decided by the model, for example after a prompt injection: a high or critical tool waits for the user's approval. It does not protect against a malicious browser, which already controls its own actions. For sensitive server actions (payments, refunds), keep the business checks on the server too, and always declare risk on server tools: a server tool without risk runs without approval, and the server logs a warning. Server tool arguments are validated against their declared parameters before the handler runs.

LineTokens (Authentication Tokens)

When sessions bridge audio streams and tool executions, OwlLayer compiles a lightweight authorization token called a LineToken.

• The client app exchanges credentials (public key + session attributes) for a LineToken via a secure API handshake.
• Every WebSocket frame and WebRTC DataChannel packet includes this token in the header.
• If the token expires or is hijacked, the server immediately severs the active connection and suspends session tools context.