Project KASA

Project KASA

A Sovereign, Local-First Memory Vault for Agentic Browsing on Windows

⚠️ v0.1 — Research Preview / Security Architecture Demo

This is an experimental prototype. Do not use it for production or for sensitive data.

It exists to demonstrate and measure an architecture — permissions, encryption and auditfor local AI agents — not to be a finished product. Run it against throwaway data.

What is actually true today, each item pointing at its evidence rather than asserting aproperty:

Runs entirely locally	vault file, key and permission decisions never leave the machine
Encrypts specific fields	3 columns, AES-256-GCM, AAD-bound — not the whole database
Limits tool authority in ordinary code	deterministic broker; the model is never the boundary
Keeps a hash-chained audit ledger	tamper and deletion detection both measured PASS
233 tests pass	2026-08-03 run, in an isolated copy that imports only from itself

What is NOT claimed — these are open, written down, and some are measured failures:identity binding (agent_id is client-asserted and audit attribution is forgeable),full at-rest encryption, egress control, and independent security audit. The KASA browserships disabled because of a known bridge-isolation defect. The project's own benchmarkcurrently records the verdict not release-ready.

We publish our own negative results. The open findings are inSECURITY.md; the failing measurements are indocs/SECURITY_BENCHMARK.md. Start there, not here.

The Problem

Current agentic browsers store persistent user memory in vendor clouds, posing significant privacy and control issues. Users lack ownership of their browsing data, and the legal implications of granting permissions to AI agents are not clearly defined. This project aims to address these shortcomings by providing a local-first, encrypted, user-owned memory vault that can be accessed by any agent via a permission-brokered MCP (Model Context Protocol) server.

What KASA Does

KASA is designed as a sovereign memory vault for Windows users: the vault file, the encryption key and the permission decisions all stay on the user's machine. Complete control is not claimed — the measured limits (client-asserted agent_id, unobserved egress, plain-text metadata columns) are named under Project Status below. It operates on the principle of "Agents come and go; your memory is yours." The system includes:

• A local Memory Vault that encrypts sensitive cells at rest with per-cell AES-256-GCM. Honest scope: encryption is cell-level over three columns, not whole-database — see Project Status below.
• An MCP Server that exposes this vault to any agent with permission via a brokered protocol.
• Permission calculus ensures that only authorized agents can access the data, maintaining strict control over user information.

Architecture

KASA's architecture comprises five key components:

Design Invariants

1. Thin Edges, Thick Core: The extension must contain no intelligence and no data; all state lives in the helper application.
2. Model is Not the Security Boundary: Authorization decisions are made by the Permission Broker in ordinary code.
3. Page Content is Data, Not Instructions: Any text originating from the web is tagged as quoted data. Goals may be derived only from the user's own commands.

Security

Every security claim in this repository is expected to name the measurement it rests on. The currentevidence report is docs/SECURITY_BENCHMARK.md (21 checks withper-check evidence strings), the per-test detail with explicit limits isSECURITY_TESTS_EN.md, and an independent audit with open findings isdocs/KASA_DENETIM_VE_PROJEKSIYON_2026-08-01.md.

• Red-team findings — what was measured, and what is still open. Each line names its evidence;nothing here claims the class of attack is solved.
  • Indirect prompt injection into the distillation chain — untrusted event text is wrapped inexplicit delimiters and a QC provenance gate rejects facts the model cannot cite. Measured:tests/test_distill_injection.py, tests/test_delimiter_breakout.py,tests/test_semantic_injection.py. Limit: prompt injection is an industry-wide openproblem; the defense here is structural (the model is never the security boundary), not aclaim of immunity.
  • MCP authorization — the allow-list (PUBLIC_TOOLS), reserved-agent block and per-scopedeny-by-default checks pass their measurements (AUTHZ-* checks indocs/SECURITY_BENCHMARK.md; tests/test_agent_gate.py).Still open: agent_id is client-asserted, so a token holder can impersonate anotherprivileged agent id and audit attribution is forgeable — see the F-IMP finding inSECURITY.md anddocs/MCP_CANLI_TEST_EYLEM_PLANI_2026-08-02.md.This is not closed.
  • KASA browser bridge isolation — open, and the reason the browser ships disabled. Thepywebview js_api bridge lives in the visited page's JS context and page scripts areinjected with no origin check, so any visited site can reach window.pywebview.api.*,including set_proxy() and ingest(). open_browser() now refuses to start withoutKASA_ENABLE_BROWSER=1, failing closed before any side effect(tests/test_browser_optin_gate.py, with both a negative and a positive control).Limit: established from code structure and from the ingest feature's own operation;no working exploit was written or run. Full write-up: SECURITY.md,"Known-unsafe surfaces". A smaller defect on the same surface was fixed — the addressbar no longer interpolates the URL into HTML.
  • Automated test→fix loops — a zero-cost local-model loop plus browser health gates run thechecks repeatedly (_orch/loop/, tools/security_bench/). They raise regression coverage;they are not evidence of security by themselves.

Roadmap

Ordered by what blocks the next honest claim, not by effort. Each item closes a gap that iscurrently measured open — the evidence is linked from SECURITY.md.

Install & Run

Requirements

• Windows only. KASA is not cross-platform today: the tray app uses PyQt5 on Windows, and the vault key is protected with the Windows DPAPI. On macOS/Linux the DPAPI layer is a no-op, so the key protection KASA relies on does not exist there (measured limit: docs/SECURITY_BENCHMARK.md → "Bilinen Sınırlar" / Known Limits, non-Windows DPAPI no-op).
• Python 3.12 — always use it. The desktop path is pinned to 3.12: a Nuitka-compiled binary segfaults when opening the pywebview window under Python 3.14. This is measured, not assumed — docs/EXE_PACKAGING_LOG.md, "Spike-2 Py3.14: SEGFAULT (exit 3)", and the build script refuses any other version at build_kasa.ps1:29-32. Honest scope of that measurement: it was observed on the desktop/exe path; the test suite and the security benchmark themselves were last run under 3.14.5 (docs/SECURITY_BENCHMARK.md header). Using 3.12 avoids the question entirely.
• Ollama installed separately. KASA does not ship or install a model runtime. Distillation is optional at runtime; the vault and the dashboard work without it.

Steps

1. Create a virtual environment (recommended, and it keeps the 3.12 pin explicit):

   py -3.12 -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

2. Dependencies: Install required Python packages using the following command:

   pip install -r requirements.txt
   

3. Local Ollama Runtime (optional, needed only for distillation): install Ollama separately from https://ollama.com, then pull the model and make sure it serves at http://localhost:11434:

   ollama pull qwen2.5:7b
   

4. Configuration: Copy kasa.toml.example to kasa.toml and set your desired configurations in it, such as server host/port and vault path. The bearer token is generated on first run.
5. Start the System Tray App: Run the application using:

   python run.py
   

6. Headless Mode for MCP Server Only: For running only the MCP server without the tray icon:

   python run.py --no-tray
   

7. Run One Distillation Pass and Exit: Use the following command to perform one distillation pass and exit:

   python run.py --distill-now
   

8. Encrypted Portable Export: Export your vault as an encrypted file with:

   python run.py export --output my_vault.kasa --verify
   

MCP Tools

KASA exposes the following MCP tools for local use:

• profile_read(scope), profile_write(fact), forget(topic), audit_read(range), event_ingest, prune_expired_events.

Testing

KASA uses pytest for testing. To run the tests, use:

pytest -q

Project Status

Not release-ready — and the project says so itself. The current benchmark stamp reads"NOT READY FOR RELEASE": 21 checks, 18 PASS · 1 FAIL · 2 WARN(docs/SECURITY_BENCHMARK.md, commit 2dfda9e). The house rule is nothing is sealed until it ismeasured, so labels such as "hardened", "enterprise-grade" or "production-ready" are not used here —docs/UI_UX_STANDARD.md §2.6 forbids them until they are empirically measured.

• Implemented and measured green: the MVP-0 security core — vault + MCP server + brokeredpermissions + distillation + audit hash-chain. All 7 AUTHZ-* checks pass (including C5/C7/C8 andthe 127.0.0.1 bind check), the 3 AUDIT-* chain/tamper checks pass, the 5 CRYPTO-* checks pass,both FUZZ-* checks pass, and the dependency audit reports 0 vulnerable dependencies.
• Measured red / amber: SCAN-SECRETS FAIL — the bearer token is stored in plain text inkasa.toml; an owner-only ACL is applied, rotation and DPAPI wrapping are still pending.SCAN-BANDIT WARN (13 medium findings, untriaged) and SCAN-BAK-HYGIENE WARN.
• Named open gaps, measured in docs/KASA_DENETIM_VE_PROJEKSIYON_2026-08-01.md:(a) agent_id is client-asserted and unverified, so the rate limiter can be bypassed and auditattribution is forgeable (§4.1); (b) egress is neither controlled nor observed — the plan indocs/GUVENLIK_CIKIS_PLANI.md is unbuilt (§4.4); (c) at-rest encryption is cell-level over threecolumns, not whole-database — metadata columns remain plain text (§1 anddocs/adr/0003-at-rest-sifreleme-boslugu.md).
• On prompt injection — the honest framing: it remains an industry-wide open problem class.KASA's defense is structural (the model is never the security boundary; the permission gate isordinary deterministic code), not a claim of invulnerability.
• Browser extension, web actions (A1-A3), cloud masking/escalation, and the fingerprint-spoofing layerare deferred / parked (out of MVP-0 scope).

Test-by-test detail, including what each claim does not prove, is inSECURITY_TESTS_EN.md.

Contact

All project contact runs through GitHub. There is deliberately no e-mail address: keeping theconversation on the repository means it stays public, attributable and searchable by the nextperson with the same question, and it does not require the maintainer to publish an address thatwould then be permanently indexed.

Please do not open a public issue, pull request or discussion for a security-relevant findingbefore it has been triaged.

This is a research preview maintained by one person. Expect considered replies rather than fastones, and expect "we measured that and it failed" to be a normal answer.

License

KASA is dual-licensed:

• AGPL-3.0 — free for individual, educational and research use, and for any use that keepsderivative work open under the same terms. The canonical license text is LICENSE.
• Commercial license — for organizations that want to build on KASA without releasing theirderivative work under the AGPL. Terms: COMMERCIAL.md.

Attribution to the author stays with the project under both options.

KASA — a sovereign, local-first memory vault for agentic browsing.Author: @aikadimsoy · Repository: https://github.com/aikadimsoy/kasa-mcp