Security

This page explains how Qoni uses OAuth / OIDC token authorization and the Web Agent browser sandbox to let Agents perform Web tasks without receiving user passwords or crossing the user's permission boundary.

Security Model

Qoni's security model has two layers:

1. Authorization layer: GenAuth issues short-lived authority based on the user identity, Agent identity, and task scope, so the Agent can access resources only within explicit scopes.
2. Execution layer: Web Agent performs browser actions inside a controlled browser sandbox, isolating sign-in state, page data, and task context.

Together, these layers let an Agent act for a user without bypassing consent, taking user passwords, or spreading sensitive data from one task into another task.

OAuth / OIDC Token-Based Authorization

Qoni does not recommend giving long-lived user credentials to an Agent. The recommended path is:

1. The user signs in through GenAuth, your login system, or an enterprise OIDC Provider.
2. Your backend verifies the user identity and requests limited authority for a specific Agent and task.
3. GenAuth returns a short-lived delegation token with allowed scopes, expiration, and audit data.
4. Web Agent uses the delegation token to run the task instead of using the user's password or a long-lived refresh token.

The delegation token should cover only the minimum authority needed for the current task. For example, an Email Assistant Agent may read visible emails, create drafts, and research public webpages, but it should not be able to send email, delete email, or change mailbox settings.

const { data } = await qoni.delegateToken({
  mode: 'interactive',
  agent: 'email-assistant',
  scopes: ['webagent.web_search:manage', 'webagent.web_search:read'],
  redirectUri: 'http://localhost:3000/qoni/callback',
  state: 'task-001',
  user: { id: 'user_123' },
  expiresIn: 900, // seconds; size it to the task
})

Scopes are declared positively

There is no "deny list" field in the real contract — least privilege comes from requesting only the scopes you need, not from enumerating what to forbid. The allowedScopes / allowedAgents whitelists on the access key are the second gate. Full semantics: Delegate Token and attenuation.

Agent Grants and Permission Boundaries

An Agent grant is the boundary that turns user consent into executable Agent authority. In production, each grant should include at least:

Field	Purpose
userId	Who authorized the task.
agentKey or Agent Profile	Which Agent can use the authority.
scopes	Actions the Agent is allowed to perform.
expiresIn	How long the grant stays valid (seconds, 60-86400). Prefer short.
auditId	The record used for audit, debugging, and user review.

If a task needs new authority, ask the user to confirm and issue a new grant. Do not reuse a broad grant across unrelated tasks.

Browser Sandbox Security

Web Agent runs Web tasks inside a controlled browser sandbox. The most sensitive parts of the sandbox are the password path and the private data path: a user may type a password into a cloud browser, and after sign-in the cloud browser may see mailbox, admin console, or SaaS data. The goal of the sandbox is not to give the Agent full browser control, but to constrain password entry, sign-in state, page data, and video streams to the task boundary.

The browser sandbox should follow these principles:

• Sign-in state is used only within the controlled session or profile boundary.
• Page scripts, page content, and downloads should not flow directly into long-term application storage.
• The Agent reads only the page regions and fields needed for the task.
• Temporary page state is cleared or isolated according to your retention policy after the task.
• When the task requires user sign-in, MFA, or OAuth consent, the user completes it through the actionUrl.

After the user completes sign-in, Web Agent can continue the task, but its authority is still constrained by the delegation token and task policy.

Password Entry and Sign-In State Safety

The recommended Qoni integration does not require the Agent to receive user passwords. When the user must sign in to a third-party webpage, Web Agent should provide an actionUrl; the user completes sign-in, MFA, or OAuth consent inside the controlled browser session on the target site or identity provider page.

Handle the password path as follows:

• The actionUrl should be a short-lived HTTPS link bound to the current task and user action.
• After the user opens the actionUrl, password entry happens inside the controlled browser sign-in page, not in a prompt, task parameter, or backend API request.
• The user-to-Qoni controlled browser entry point and the controlled browser-to-target-site path should both use HTTPS / TLS.
• Qoni does not persist user passwords. Passwords should not be written to task results, ReAct traces, GUMem, audit body text, callback events, or application logs.
• The Agent should only know that the user completed sign-in, MFA, or consent. It should not read the password as visible text, a tool parameter, or Memory.
• Cookies, session storage, or OAuth sign-in state created after sign-in stay within the controlled session or profile boundary and should not be exported to unrelated tasks.

This is why OAuth / OIDC is preferred. When the target system supports authorization code, consent, and short-lived access tokens, the Agent does not need to touch account passwords; it only uses task capability within the delegation-token boundary.

If you must integrate with a legacy username/password system, keep password entry inside the controlled sign-in page and avoid writing passwords to logs, Memory, callback events, or task results.

Do not pass user passwords in prompts, task parameters, callback URLs, logs, or long-term configuration.

Data and Video Stream Return Safety

After sign-in, Web Agent may see private page data. Qoni can return task results, ReAct traces, browser video frames, or screenshots to your application through SDK streams, SSE, callbacks, or temporary resource URLs. Treat this return path as sensitive data.

The return path should use these boundaries:

• Results, events, and video frames should be transported over HTTPS / TLS, preventing public network eavesdropping.
• SDK streams and API calls require project-level authentication, such as an API key, Bearer token, or backend service identity.
• callbackUrl must use HTTPS and should point to your backend endpoint, not a public third-party write target.
• Video frames, screenshots, and extracted results should be bound to a specific taskId, project, and user session. Before showing them in the frontend, your backend should verify that the current user can view that task.
• If frames or files are returned through temporary resource URLs, those URLs should be short-lived and should not be stored as long-term public links.
• Qoni does not publish browser video as a public resource. Your application should also avoid writing video frames, screenshots, or private page body text to public logs, analytics systems, or long-term Memory.
• Internal traces that are not user-facing should not contain hidden chain-of-thought. User-facing traces should contain only explainable summaries, actions, and observations.

Other parties cannot directly read this data because three controls work together: HTTPS / TLS protects the transport path from network eavesdropping; API keys, Bearer tokens, project checks, and task ownership checks restrict who can request the stream; short-lived URLs, task binding, and non-public publishing rules limit how video frames, screenshots, and extracted results can spread.

Data Minimization

When an Agent handles webpages and private application data, use data minimization:

• Extract only the fields needed for the task instead of storing full page snapshots.
• Do not write full emails, verification codes, temporary tokens, cookies, passwords, or one-time links into GUMem.
• Audit records should preserve the task, scopes, sources, and key actions, not unbounded sensitive body text.
• Frontend pages should show only the drafts, sources, and risk notices the user needs to review.
• Public web research tasks should not carry private email body text, internal document content, or user sign-in state.

If a field is only an intermediate result for the current task, keep it in task state instead of long-term Memory.

Developer Checklist

Before production, check that:

• Every Agent has a stable agentKey or Agent Profile.
• Every task uses a short-lived grant instead of a long-lived broad token.
• scopes contains only the minimum set the task needs.
• User sign-in, MFA, and OAuth consent happen through an actionUrl.
• actionUrl, SDK streams, SSE, callbacks, and temporary resource URLs all use HTTPS.
• Backend logs do not record passwords, cookies, verification codes, access tokens, or refresh tokens.
• Video frames, screenshots, and extracted results are available only to users authorized to view the task.
• GUMem stores durable preferences and rules, not sensitive credentials.
• Audit records can answer who authorized the task, which Agent acted, what it did, and which authority it used.

Next Steps

Continue with Quickstart to see how grant, Web Agent, and GUMem work together in a minimal Agent service.