Security Documentation

Deep dive into PN Web OS security architecture, encryption model, and account recovery implementation.

1. Security Overview

PN Web OS implements a client-side, zero-knowledge security architecture where all encryption and decryption operations happen in your browser. Your data is encrypted before it's stored, and we never have access to your passwords or unencrypted data.

Client-Side Encryption

All encryption happens in your browser using Web Crypto API

Zero-Knowledge

We never see your password or unencrypted data

AES-256-GCM

Military-grade encryption for all stored data

Core Security Principles

End-to-End Encryption: Data encrypted on your device, decrypted only on your device
Local-First Architecture: All data stored in browser IndexedDB, no server storage
Password-Based Key Derivation: Your password derives encryption keys using PBKDF2
Recovery Phrase System: BIP39 12-word mnemonic for account recovery
No Server Keys: We cannot decrypt your data, even if we wanted to

2. Encryption Model

How Your Data is Protected

PN Web OS uses a layered encryption approach with three key components:

Three-Layer Key Architecture

1. Master Key (AES-256)
A randomly generated 256-bit key that encrypts all your files and data. This key never changes unless you create a new account. It's encrypted and stored, never exposed in plaintext except during active encryption/decryption operations in browser memory.
2. Password-Derived Key (PBKDF2)
Derived from your password using PBKDF2 with 600,000 iterations. This key encrypts your master key. When you change your password, we re-encrypt the master key with a new password-derived key, but your underlying data encryption remains unchanged.
3. Recovery Key (from Recovery Phrase)
Derived from your 12-word BIP39 recovery phrase. This provides an alternative way to decrypt your master key if you forget your password. The master key is encrypted twice: once with your password-derived key, and once with your recovery key.

Encryption Flow

Your Password → PBKDF2 (600,000 iterations) → Password-Derived Key

↓

Password-Derived Key + Master Key → Encrypted Master Key (stored in IndexedDB)

↓

Master Key + Your File → Encrypted File (stored in IndexedDB)

Why This Matters

This architecture allows you to change your password without re-encrypting all your files. Only the master key needs to be re-encrypted, which is fast and efficient.

3. Account Recovery Process

When you create an account, you receive a 12-word recovery phrase (BIP39 standard). This phrase is your ultimate backup and the only way to recover your account if you forget your password.

Recovery Flow Step-by-Step

Enter Recovery Phrase

You provide your 12-word recovery phrase on the recovery page. The phrase is validated against the BIP39 wordlist to ensure it's properly formatted.

Derive Recovery Key

Your recovery phrase is converted into a cryptographic key using PBKDF2 key derivation (same algorithm used for password-derived keys).

Decrypt Master Key

The recovery key decrypts your encrypted master key from IndexedDB. If decryption succeeds, you've proven ownership of the account. The master key is now available in browser memory.

Set New Password

You create a new password. A new password-derived key is generated from this password.

Re-encrypt Master Key

Your master key is re-encrypted using the new password-derived key and stored back in IndexedDB. Your files remain encrypted with the same master key - they don't need to be touched.

Generate New Backup

A new encrypted backup file is generated containing your account data, encrypted with your new password. You're prompted to download it for safekeeping.

4. Master Key Architecture

Understanding the master key is crucial to understanding PN Web OS security.

Master Key Properties

Algorithm

AES-256-GCM (Advanced Encryption Standard with Galois/Counter Mode)

Key Length

256 bits (32 bytes) - highest commercial-grade security

Generation

Generated using crypto.getRandomValues() - cryptographically secure random number generator

Persistence

Never changes for the lifetime of your account (unless you create a new account)

Master Key States

The master key exists in different states depending on the operation:

Extractable (Temporary)

When: During registration and account recovery
Why: The key must be encrypted with your password before storage
Duration: Only during the active session, immediately re-encrypted

Non-Extractable (Default)

When: During normal login and file operations
Why: Security best practice - prevents key export attacks
Benefit: Even if malicious code runs, it cannot extract your master key

Important Security Note

The master key is ONLY extractable when you need to change your password (during registration or recovery). During normal use, it's non-extractable, providing maximum security. This is intentional and follows cryptographic best practices.

5. Password Reset Flow

This section explains the technical process of resetting your password during account recovery, including why the master key must be temporarily extractable.

The Challenge

When you reset your password, we face a cryptographic challenge:

Problem

Your master key is encrypted with your OLD password. You want to encrypt it with your NEW password. But you can't encrypt a CryptoKey object directly - you must export it to raw bytes first, then re-encrypt those bytes with the new password-derived key.

The Solution

Technical Implementation

// Step 1: Recover master key from recovery phrase
const masterKey = await crypto.subtle.importKey(
  'raw', masterKeyRaw,
  { name: 'AES-GCM', length: 256 },
  true, // ← Extractable: true (REQUIRED for password change)
  ['encrypt', 'decrypt']
)

When recovering your account, the master key is imported as extractable because we know you'll need to change your password immediately.

// Step 2: Export master key to raw bytes
const masterKeyRaw = await crypto.subtle.exportKey('raw', masterKey)
// ✅ This succeeds because extractable = true

The master key is exported from the CryptoKey object to raw bytes (ArrayBuffer).

// Step 3: Derive new key from new password
const newPasswordKey = await deriveKeyFromPassword(newPassword)

// Step 4: Encrypt master key with new password key
const encryptedMasterKey = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv: newIv },
  newPasswordKey,
  masterKeyRaw
)

The raw master key bytes are encrypted with your new password-derived key.

// Step 5: Store re-encrypted master key
await indexedDB.put('accounts', {
  username,
  encryptedMasterKey, // ← Encrypted with NEW password
  // ...
})

The newly encrypted master key is stored in IndexedDB, replacing the old one.

Result

Your password has been changed. The same master key now unlocks with your new password. All your files remain encrypted and unchanged. The master key was only extractable temporarily during this re-encryption process and is immediately discarded from memory.

6. Technical Implementation

For security researchers, developers, and advanced users who want to understand the exact cryptographic implementation.

Cryptographic Specifications

Component	Specification
Master Key Algorithm	AES-256-GCM
Key Derivation Function	PBKDF2-SHA256
PBKDF2 Iterations	600,000
Recovery Phrase Standard	BIP39 (12 words)
Random Number Generator	crypto.getRandomValues()
Storage	IndexedDB (browser-local)
API	Web Crypto API (SubtleCrypto)
IV/Nonce Generation	crypto.getRandomValues() (12 bytes for GCM)

Key Files and Functions

/lib/webos/services/auth-service.ts

• register() - Account creation with master key generation
• login() - Password verification and master key decryption
• recoverAccount() - Recovery phrase validation and master key recovery
• changePassword() - Master key re-encryption with new password

/lib/webos/services/crypto-service.ts

• encrypt() - AES-256-GCM encryption
• decrypt() - AES-256-GCM decryption
• deriveKey() - PBKDF2 key derivation

/lib/webos/services/indexeddb-service.ts

• Encrypted account storage
• Encrypted file storage
• Browser-local persistence

7. Security Guarantees

What we guarantee about your security and privacy:

We Never See Your Password

Your password is never transmitted to any server. It exists only in your browser during login/registration and is used immediately to derive encryption keys, then discarded from memory.

We Cannot Decrypt Your Data

All data is encrypted client-side before storage. We don't have your password, recovery phrase, or master key. Even if compelled by law enforcement, we cannot decrypt your data because we don't have the keys.

Your Data Never Leaves Your Browser

All encryption, decryption, and storage happens locally in IndexedDB. Your data is never uploaded to our servers. The only exception is if you explicitly use cloud sync features (coming in future tiers), and even then, only encrypted data is transmitted.

Recovery is Secure and User-Controlled

Only you have your 12-word recovery phrase. We cannot reset your password for you. If you lose both your password AND recovery phrase, your data is permanently inaccessible - even to us.

Master Key Extractability is Minimal and Controlled

Your master key is only extractable during registration and account recovery, and only for the purpose of encrypting it with your password. During normal use, it's non-extractable, preventing key export attacks even if malicious JavaScript somehow runs in your browser.

8. Account ID & Multi-Account Isolation

PN Web OS uses a privacy-first account architecture that allows multiple users to safely share the same device while maintaining complete data isolation between accounts.

Account ID (UUID) Architecture

Every account in PN Web OS is identified by a unique Account ID (UUID) that is generated when you create your account. This ID is separate from your username and provides several important security and privacy benefits:

Privacy Through Uniqueness

Your Account ID is a randomly generated UUID (e.g., dbbf7f66-2e28-4385-9f2a-a9ad69fc1f0d). This unique identifier ensures your account is globally unique without revealing your identity through your username.

Username as Display Label Only

Your username is a display label that you see in the interface. Multiple accounts can have the same username (e.g., "test", "admin", "user") because the Account ID provides the actual uniqueness. This enhances privacy when sharing devices or importing backups.

Complete Data Isolation

All your files, vault entries, settings, and encrypted data are linked to your Account ID. This ensures complete isolation between accounts, even if they share the same username on the same device.

Multi-Account Support on Shared Devices

PN Web OS is designed to support multiple users on the same device while maintaining privacy and security:

Example: Shared Computer Scenario

Step 1: Alice imports her backup file (username: "test", password: "AlicePass123!")
→ Account ID: dbbf7f66-2e28-4385-9f2a-a9ad69fc1f0d

Step 2: Bob imports his backup file (username: "test", password: "BobPass456!")
→ Account ID: c24e305d-8b9a-4a2f-b3c1-7d8e9f0a1b2c

Step 3: Login screen shows username: "test"

Step 4a: Alice enters password "AlicePass123!"
→ System tries ALL accounts with username="test"
→ Password matches Account ID dbbf7f66... → Logs in to Alice's account

Step 4b: Bob enters password "BobPass456!"
→ System tries ALL accounts with username="test"
→ Password matches Account ID c24e305d... → Logs in to Bob's account

Password Disambiguation

When multiple accounts share the same username, PN Web OS uses your password to automatically determine which account you're logging into. This happens transparently - you don't need to manually select which account you want. The password acts as the disambiguator.

Security Benefits of Account ID Architecture

Prevents Username Enumeration: Attackers cannot determine which usernames exist on the system because multiple accounts can share the same username

Enhanced Privacy on Shared Devices: Multiple family members or colleagues can use simple usernames like "user" or "admin" without revealing their real identities

Backup File Privacy: When you share your backup file with someone or store it in cloud storage, the username doesn't reveal your identity

Complete Data Segregation: Each account's encryption keys, vault data, files, and settings are completely isolated by Account ID, preventing any cross-account data leakage

Scalable Architecture: Supports unlimited accounts on the same device without performance degradation or architectural limitations

Zero-Knowledge Maintained

Your Account ID is stored locally in your browser and is never transmitted to PN servers. All encryption, decryption, and account operations happen client-side. The Account ID architecture does not compromise the zero-knowledge security model.

9. Threat Model

Understanding what PN Web OS protects against and what it doesn't:

What We Protect Against ✅

Server Breaches: Even if our servers were compromised, attackers would only find encrypted data they cannot decrypt

Network Interception: Data transmitted (if any) is already encrypted client-side

Unauthorized Password Resets: Cannot reset password without recovery phrase

Brute Force Attacks: PBKDF2 with 600,000 iterations makes brute forcing computationally expensive

Key Export Attacks: Master key is non-extractable during normal use

What We Don't Protect Against ⚠️

Compromised Browser: If your browser or OS is compromised with keyloggers/malware, attackers could capture your password

Physical Access Attacks: If someone has physical access to your unlocked computer while you're logged in, they can access your data

Weak Passwords: If you choose a weak password, it can be brute forced faster (use strong passwords 12+ characters)

Lost Recovery Phrase: If you lose both password and recovery phrase, your data is permanently inaccessible

Browser Vulnerabilities: We rely on Web Crypto API implementation in your browser; if it has vulnerabilities, we inherit them

Security Best Practices

• Use a strong, unique password (12+ characters)
• Store your recovery phrase offline in a secure location
• Keep your browser and OS updated
• Use antivirus/antimalware software
• Lock your computer when stepping away
• Download and store encrypted backups regularly

Back to Documentation Report Security Issue

Have questions about our security model? Contact our security team