Security Overview

Security-first design backed by transparent engineering practices. This page documents the controls that ship with Keythings Wallet and how to audit them effectively.

Executive summary

Keythings Wallet is designed as a non-custodial, security-focused browser extension for the Keeta network. At a high level:

• Local, device-bound keys: Keys are generated and encrypted locally; the network only sees public keys and signatures.
• Origin & capability isolation: Each site has its own approval, capability set, and tokens, so dApps cannot silently escalate privileges.
• Per-RPC checks: Sensitive RPCs require approved origins, appropriate capabilities, capability tokens, and explicit user approvals.
• Defense-in-depth testing: Cryptographic, fuzzing, and UI security suites run alongside linting and type checks to catch regressions early.

Security Philosophy

Keythings Wallet is architected as a non-custodial wallet. Secrets never leave the user’s device, operations are explicit, and every security-relevant subsystem is covered by automated tests. The following sections capture the protections in place today and highlight where to inspect the implementation inside thekeythings-extension-wallet codebase.

Key Lifecycle

Understanding how secrets are generated, stored, and destroyed is central to any audit. The wallet’s key lifecycle follows the sequence below.

1. Generation: A 256-bit entropy buffer produced via crypto.getRandomValues is mapped to a BIP-39 mnemonic. Optional imports validate checksum and wordlist membership.
2. Derivation: User-provided passwords are stretched with Argon2id (64 MiB memory, 6 iterations, parallelism 2) to yield an encryption key.
3. Encryption at Rest: The mnemonic/seed is wrapped with AES-GCM (96-bit nonce, 256-bit key) and persisted to extension storage alongside metadata (salt, iterations, version).
4. Unlock: On unlock, the encrypted blob is decrypted inside the service worker and loaded into volatile memory that is cleared on lock, timeout, or process exit.
5. Derivation for Use: Child keys follow hardened derivation paths (BIP-32/BIP-44) scoped to the active network.
6. Lock/Destroy: Secrets are wiped from memory using explicit zeroisation before the vault is considered locked.

// Key lifecycle (conceptual excerpt)
async function createVault(password: string, mnemonic = generateMnemonic(256)) {
  const salt = crypto.getRandomValues(new Uint8Array(16))
  const masterKey = await argon2id(password, { salt, memoryMiB: 64, iterations: 6, parallelism: 2 })
  const encrypted = await aesGcmEncrypt(masterKey, mnemonic)
  await storage.set({ encrypted, salt, version: VAULT_VERSION })
  return unlock(password)
}

async function unlock(password: string) {
  const vault = await storage.get()
  const masterKey = await argon2id(password, vault.kdf)
  const mnemonic = await aesGcmDecrypt(masterKey, vault.encrypted)
  memory.load(bip39.mnemonicToSeed(mnemonic))
}

function lock() {
  memory.zero() // explicit zeroisation of seeds & derived keys
}

Audit checklist: verify Argon2id parameters, nonce uniqueness, mnemonic checksum validation, and zeroisation routines. Confirm unit tests fail on parameter regression.

Defense-in-Depth Controls

Cryptography

• AES-GCM sealed storage: Encrypted vault payloads include authentication tags to detect tampering.
• Argon2id key stretching: Memory-hard derivation mitigates GPU/ASIC brute force attacks.
• HD Wallet derivation: Hardened derivation paths isolate accounts; account discovery obeys BIP-44 gap limits.
• Entropy hygiene: All randomness is sourced from the Web Crypto API; no deterministic PRNGs are used.

Origin isolation & dApp safety

• The inpage provider is injected only on allowlisted HTTPS origins plus a small set of localhost development URLs.
• The background service verifies that messages come from the extension's own content script running in a top-level tab, with sender.origin matched against tab URLs and runtime contexts.
• Extension pages cannot impersonate dApps; all dApp flows originate from real browser tabs.

Capability-Based Authorization

The wallet mediates dApp access through per-origin capability grants. Requests enumerate capabilities (for example read, sign, transact, network) and receive expiring capability tokens bound to origin and capability. Revocation is origin-scoped and propagates to content scripts and inpage contexts.

// Capability grant outline
const capability = {
  origin,
  scopes,
  issuedAt: Date.now(),
  expiresAt: Date.now() + resolveTtl(scopes),
}
registry.set(origin, capability)

if (!rateLimiter.allow(origin)) {
  throw new Error('RATE_LIMITED')
}

Context Isolation

• Content scripts validate sender.origin, enforce top-level frame execution, and use structured cloning to avoid prototype pollution.
• Inpage provider messages pass through schema validation (Zod) before reaching the service worker.
• Service worker ports authenticate the extension ID to mitigate spoofed messages.

Runtime Guardrails

• Approval workflow: Each signing or transaction request requires explicit confirmation via modal with human-readable payloads and risk scoring.
• Session hygiene: Auto-lock defaults to 5 minutes of inactivity; unlock attempts incur exponential backoff with progressive delays.
• Input validation: Addresses, chain IDs, amounts, and message lengths undergo strict validation before being forwarded to signing routines.
• Rate limiting: Origin-scoped token buckets cap JSON-RPC throughput and pending approval counts.

Network Security

• HTTPS-only RPC endpoints with certificate pinning/allowlisting per network configuration.
• WebSocket subscriptions verify TLS state and origin allowlists.
• Build pipelines lint manifests to ensure no extra host permissions are shipped.

Validation, logging & testing

• Untrusted inputs (RPC params, external data, messages) are validated with Zod schemas before they reach signing or transaction routines.
• Logging utilities are designed to avoid writing secrets while still providing enough context for debugging and incident response.
• Security-focused commands (such as bun run security:all) complement the regular test, lint, and build pipelines.

Audit Readiness

The documentation below is intended to make third-party audits efficient once the repository is open sourced.

• Threat model: Review the architecture and threat model documents under docs/ in the wallet repository. They outline trust boundaries, attacker assumptions, and mitigations.
• Test evidence: Automated suites cover crypto helpers, permission guards, and session policies. Runpnpm test (or pnpm test --filter extension) to view coverage reports.
• Static analysis: ESLint security rules and TypeScript strict mode execute via pnpm lint. Review CI logs for enforcement details.
• Configuration review: Inspect Manifest V3 permissions, CSP, and host allowlists in the build output directory before releasing.
• Logging: Sensitive data is redacted before writing to diagnostic logs; redaction helpers include unit tests that fail if new fields bypass scrubbing.

Compliance & Standards Alignment

Keythings Wallet targets alignment with industry standards to simplify organisational governance.

• OWASP MASVS: Architecture (MASVS-ARCH), authentication (MASVS-AUTH), and cryptography (MASVS-CRYPTO) requirements are mapped to wallet controls such as isolated execution contexts, unlock gating, and audited encryption routines.
• OWASP ASVS: Level 2 controls are used as a benchmark for secure storage (V7), communication (V10), and error handling (V9). Documentation annotates which modules satisfy each control.
• SOC 2 readiness: CI/CD hardening, dependency review, and access controls support eventual SOC 2 Type 1/Type 2 assessments.
• Privacy obligations: The wallet collects no personal data or telemetry by default, aligning with GDPR data minimisation principles.

User & Developer Best Practices

For Users

Seed Phrase Security

• Never share your seed phrase with anyone.
• Store mnemonics offline in tamper-evident, redundant locations.
• Perform recovery drills on a secondary device in a safe environment.
• Use hardware signing for large balances or institutional custody requirements.

Password & Biometric Hygiene

• Use strong, unique passwords (12+ characters, varied character classes).
• Enable biometric unlock where available.
• Configure auto-lock timers to match personal or organisational risk tolerance.
• Protect password managers with MFA.

Browser Security

• Keep the browser and Keythings extension patched.
• Only interact with trusted networks and verified URLs.
• Beware of screen-sharing or remote-assistance attacks during signing.

For Developers

Secure Integration

• Validate all inputs before sending requests to window.keeta.
• Display complete transaction payloads to users to maintain transparency.
• Leverage keeta_simulateTransaction to preflight complex interactions.
• Keep dependencies patched and monitor upstream advisories.

Security Reviews

• Perform peer review on wallet integration code paths.
• Use static analysis tooling and run pnpm lint before release.
• Document assumptions and edge cases in the integration runbooks.
• Engage with the Keythings security team for coordinated audits.

Incident Response

Security Contact

If you discover a potential security issue, contact the Keythings Wallet security team:

• Email: mow@keythings.xyz
• PGP: Public key fingerprint published in SECURITY.md (rotate annually).
• Response target: Initial acknowledgment within 24 hours, mitigation updates within 72 hours.

Disclosure Policy

• Responsible disclosure is encouraged; coordinated releases minimise end-user risk.
• Severity scoring follows CVSS v3.1 and drives remediation SLAs.
• Researchers are credited in advisories and other public acknowledgements, where appropriate.
• Impacted users receive notification via in-app banners, RSS feeds, and mailing lists.

Continuous Improvement

Security is never “done”. Regression tests, dependency audits, and manual reviews run before each release cycle. The team tracks industry developments (OWASP, NIST, browser security updates) and iterates on mitigations accordingly.