Skip to content

Security model ​

SECURITY.md is the source of truth

This page is a short guide to Portunus's security model. The full threat model, trust boundaries, and a file-by-file audit map live in SECURITY.md. If the two ever disagree, SECURITY.md wins.

Reporting a vulnerability ​

Please don't open a public issue, discussion, or PR for security problems. Use GitHub private vulnerability reporting. See Reporting a vulnerability for what to include, what to expect, and what's in scope.

Not independently audited ​

Portunus has not been independently security-audited, and no third party has formally reviewed its cryptography. Judge it on the basis described in No independent audit: standard primitives, a small security-relevant surface, and a What to audit map you can review yourself. If you need audited software, use an audited password manager.

How the vault is encrypted ​

All encryption and decryption happens in the browser:

txt
vault plaintext ──▶ XChaCha20-Poly1305 (random data key)
                        │
data key ──▶ wrapped by KEK = Argon2id(password ‖ keyfile_bytes)
                        │
envelope (ciphertext + wrapped key + kdf params) ──▶ Google Drive
  • Argon2id parameters follow OWASP guidance (19 MiB, t=2, p=1).
  • Unlock requires both the master password and the keyfile (portunus.key, or its recovery code).
  • Header fields are bound as AEAD additional data, so tampering with the KDF params, the engine id, or the wrapped key fails decryption.
  • Fresh random nonces are used for every wrap and save.

The exact construction is in Zero-knowledge design.

Biometric unlock (optional) ​

With PORTUNUS_BIOMETRIC_UNLOCK=1, a device can keep a copy of the vault's data key, encrypted by a passkey that releases its secret only after the device's fingerprint, face or screen-lock check. The vault file and the master password path are unchanged, and the master password is never stored. On that device, passing the device's check (which also accepts its PIN) unlocks the vault, so treat the device's screen lock as part of your vault's protection there. Changing the master password turns biometric unlock off on every device. Details are in Biometric unlock.

Vault file signatures ​

The server signs every save with Ed25519, bound to the Drive file's id, and refuses to serve a vault file whose signature is missing or wrong. This catches edits to the file made outside Portunus before anything is decrypted. It doesn't protect against a compromised Portunus server, and it doesn't detect an older signed copy of the same file being put back (rollback). See Vault signatures.

Two-factor vault delivery (optional) ​

With 2FA turned on for a vault, the server sends it to a browser only after a fresh authenticator code. This gates the app's delivery path, not Drive: the ciphertext in Drive still needs the password and keyfile, and an offline cache opens without a code. The TOTP secret is server-visible (the server must check codes) and integrity-protected by the file signature. See Two-factor vault delivery.

Vault isolated in a Web Worker ​

The keys and the decrypted vault live in a dedicated Web Worker. The page only holds non-secret fields (names, usernames, URLs) and asks the Worker for a password or TOTP seed only when you reveal, edit or copy it; locking terminates the Worker. Script already running in the page could still ask the Worker for secrets, which is what the Content-Security-Policy prevents.

What the server sees, and what it never sees ​

The Portunus server brokers Google OAuth and proxies Drive calls. It handles OAuth tokens, the opaque ciphertext envelope, Drive file metadata, and your Google account email and name. It never sees vault plaintext, the master password, the keyfile or recovery code, or the encryption keys.

The full lists are in What the server sees and What the server never sees. What each component (browser, server, Google Drive, Google OAuth, Have I Been Pwned) is trusted with is in Trust boundaries.

You must trust the code your browser runs ​

Zero-knowledge storage doesn't protect against a malicious or compromised server operator serving modified JavaScript that exfiltrates secrets at unlock time. SECURITY.md's advice: self-host from a release you have verified (images are signed with cosign), and serve over HTTPS.

Script injection ​

A strict Content-Security-Policy is the primary control. It blocks injected scripts before they run, and limits the page's connections, styles and form targets to its own origin. Every response also carries X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer and a restrictive Permissions-Policy, plus HSTS when AUTH_URL is https://. A runtime script self-check adds best-effort tamper-evidence: it shows a non-blocking banner if a script the build didn't emit appears on the page.

The self-check is not a defense against browser extensions, and it is not proof of a trustworthy server. Malicious extensions and fully compromised client devices are out of scope. See Script injection: CSP first, self-check second.

Keep your keyfile and recovery code safe ​

The keyfile is per-device. Losing all copies and the recovery code means the vault is unrecoverable. Nobody, including the server operator, can get it back. There is no password reset; that's the point.