External Security Audit Guide

This guide is written for independent security reviewers assessing the Keythings Extension Wallet. It maps the codebase to concrete trust boundaries, diagrams the data flows, and provides a practical checklist so audits can focus on real risk, not guesswork.

1. Scope & Threat Model (At a Glance)

Keythings Wallet is a Manifest V3 browser extension with the following major components:

  • Inpage provider & content script: Injects window.keeta into allowlisted origins and forwards requests into the extension runtime.
  • Background service worker: Hosts the wallet provider handler, key lifecycle, capability tokens, origin approvals, and network access.
  • Popup UI: Surfaces balances, approvals, and network state to users and drives all sensitive confirmation flows.
  • Secure storage and session cache: Wraps seeds and secrets using Argon2id and AES-GCM; keeps decrypted material only in memory while unlocked.
  • @keetanetwork/wallet-core: Shared library that wraps Keeta SDK primitives for accounts, transactions, and network integration.

The primary attacker model assumes malicious web content (dApps, injected scripts), potentially malicious browser extensions, and network adversaries trying to tamper with or replay traffic. The wallet is designed so that the compromise or misbehaviour of one origin does not grant global power over user funds.

2. High-Level Data Flow

The diagram below shows how data moves between a dApp, the extension, secure storage, and the Keeta network. Nodes are annotated with the key files and trust boundaries you should review.

Audit tip: Validate that all transitions across the browser/extension boundary go through explicit checks and schemas: inject-provider.ts, runtime-messaging helpers, andwallet-provider-handler.ts.

3. Key Management & Vault Security

Secrets are handled entirely inside the extension's background context. The following diagram summarises the intended key lifecycle.

Audit checklist (keys):

  • Confirm Argon2id parameters in the implementation (memory cost, iterations, parallelism) match documented expectations and cannot be silently weakened.
  • Verify AES-GCM is used with fresh nonces and that salts and KDF parameters are stored alongside ciphertexts.
  • Inspect secure-store-client.ts, secure-store.ts, and unlocked-seed-cache.ts for explicit zeroisation and lock/timeout handling.
  • Validate that no secrets are written to logs, error messages, or browser storage (including crash paths).

4. RPC & Approval Pipeline

The most security-sensitive path is the JSON-RPC pipeline that connects dApps to signing and transaction functionality. The sequence below outlines the expected control points.

Audit checklist (RPC & approvals):

  • Review handleRuntimeMessage and requireTrustedContentSender to ensure non-extension senders and non-top-level frames are rejected.
  • Confirm that ensureOriginIsAllowlisted enforces the documented allowlist (Keeta domains + localhost dev origins) and rejects unknown schemes (file://, chrome-extension://, etc.).
  • Validate that every signing or state-changing RPC path passes through capability checks (ensureCapabilities, requireCapabilityToken) and a user-facing approval flow.
  • Use the RPC Security Matrix doc to cross-check that each method's implementation matches the documented security requirements.

5. Origin & Capability Isolation

The wallet enforces strict origin isolation and capability scoping. Auditors should pay particular attention to these controls when modelling cross-site or malicious-dApp scenarios.

  • Inspect inject-provider.ts to confirm that the provider is only injected on allowlisted origins and never into iframes or extension pages.
  • Review origin permission storage (dapp-request-store.ts, origin permission state) and confirm that approvals are origin-scoped and revocable.
  • Verify capability token structure and storage: tokens should be bound to origin + capability, have explicit TTLs, and be unusable across origins.
  • Ensure network-switching and token/admin operations require more than simple origin approval (e.g., dedicated capabilities and approvals).

6. Logging, Telemetry & Privacy

Observability is important for incident response, but logs must not leak secrets. The wallet uses structured logging via a dedicated secure logger.

  • Review secure-logger.ts and related helpers to confirm that secrets (seeds, private keys, raw mnemonics, capability tokens) are never logged, even on error paths.
  • Validate that logs use opaque identifiers or hashes where necessary instead of raw sensitive values.
  • Check that no third-party telemetry or tracking libraries are present in the extension build.

7. Automated Security Testing

The monorepo ships several security-focused test suites. As an auditor, you can treat these as both evidence and tooling for your own review.

  • From the wallet monorepo root (keythings-monorepo):
    • bun run security:all – runs comprehensive security suites, including fuzzing, cryptographic tests, UI security tests, and property-based checks.
    • bun run test / bun run test:all – run unit, integration, and e2e suites.
    • bun run lint – static analysis for TypeScript/ESLint rules.
    • bun run build – production build validation.
    • bun audit – dependency vulnerability scan.
  • Review the testing/security-report docs page for a narrative summary of recent security test runs and known residual issues.

8. Recommended Audit Process

  1. Establish a clean environment: Clone the monorepo, install dependencies, and runbun run check and bun run security:all to ensure tests pass before changes.
  2. Review manifest & build output: Check MV3 permissions, host allowlists, CSP, and web accessible resources. Confirm that no extraneous permissions are granted.
  3. Deep dive key management: Walk through secure storage, unlocking, and zeroisation logic, ensuring it aligns with the key lifecycle diagram.
  4. Trace RPC paths: For each RPC of interest, start at window.keeta and follow the path intowallet-provider-handler.ts, verifying origin/capability checks against the RPC Security Matrix doc.
  5. Abuse-case testing: Attempt to bypass approvals (e.g., replaying messages, spoofing origins, invoking RPCs from non-allowlisted origins) using your own tooling or automated tests.
  6. Report findings: Use the security contact in SECURITY.md and the primary Security docs page to coordinate responsible disclosure.

With this guide and the diagrams above, external auditors should be able to quickly orient themselves in the codebase, understand the intended security model, and focus their effort on areas that matter most for end-user safety.

14 of 27