rePASS Security Architecture

1. Design principles

rePASS is a self-hosted enterprise password manager. It is designed around four principles:

• Zero knowledge for secrets. Every vault item is encrypted and decrypted on the user’s device. The server stores ciphertext it has no means to decrypt: the vault password and the keys derived from it never leave the client.
• Your infrastructure, your perimeter. rePASS runs in your datacenter or private cloud. There is no vendor cloud holding your vault, and the product functions fully in air-gapped networks — including breach-database checks (§8).
• Defense in depth. Client-side encryption is the last line, not the only one: identity federation with mandatory MFA, device trust, token binding, anomaly detection and a tamper-evident audit trail operate in front of it.
• Honest boundaries. “Zero knowledge” is a precise claim about secret material, not a slogan. Where the claim stops, this document says so and marks it — that is what the limits index above collects.

2. Threat model

rePASS is designed so that the following adversaries do not obtain vault secrets:

• An attacker with full server access — including a stolen database dump, a compromised host, or backups. Vault items are ciphertext under keys the server never held.
• A malicious or coerced administrator acting through the product. Administrators manage the deployment; the application gives them no way to read vault contents, and organizational recovery requires several recovery admins to approve (§7).
• A network attacker. All transport is TLS; the web vault enforces HSTS and a strict Content Security Policy. Sensitive API routes additionally require signed, single-use request nonces to block replay.
• A token thief. Session tokens are bound to the device identity and IP address they were issued to; reuse elsewhere is rejected and audited. Refresh tokens are stored only as hashes. A stolen session also cannot destroy access: replacing the stored key material requires proving possession of the current private key.
• A phishing site. The browser extension refuses to fill credentials on a hostname they were not saved for, re-validates the destination at fill time, and never runs inside iframes (§9).

Out of scope

3. Cryptographic architecture

All vault cryptography runs on the client — in the browser, the extension, the macOS app, or the CLI — using the platform’s native cryptography APIs. rePASS invents no cryptographic primitives of its own.

The key hierarchy

Each user’s keys form a chain that starts from a secret only the user knows and ends at item ciphertext. Every link is created and used exclusively on the client:

Vault password                      (known only to the user)
  │  PBKDF2-HMAC-SHA256, per-user random salt
  ▼
Master key (AES-256)                (exists only in device memory)
  │  AES-256-GCM
  ▼
User private key (RSA-4096)         (stored server-side — encrypted)
  │  RSA-OAEP unwrap
  ▼
Vault key (AES-256, one per vault)  (stored server-side — wrapped
  │  AES-256-GCM                     for each member individually)
  ▼
Vault items                         (stored server-side — ciphertext)

• The vault password is never transmitted. Authentication (who you are) and decryption (what you can read) are deliberately separate systems — logging in proves identity; only the vault password unlocks data.
• Private keys are imported into the browser’s crypto engine as non-extractable handles: usable for decryption, but not exportable by script — including rePASS’s own code.
• A new device gains access by authenticating, then downloading the encrypted private-key blob and decrypting it locally. There is no key-transport step in which the server could observe key material.

4. What the server can and cannot see

A precise zero-knowledge claim requires stating both sides. Item contents and the keys that open them exist in plaintext only in the memory of an unlocked client — with one documented exception during organizational recovery, described in §7. Everything else the server needs in order to run a multi-user product, it can read:

Why those labels are not encrypted

This is the sharpest trade-off in the design, so it is worth being precise about what buys what. rePASS lets a security administrator ask “which credentials in this organization are weak or breached?” across vaults they are not a member of and therefore cannot decrypt. That report is only possible because the strength rating and the item type sit outside the encrypted blob: there is no key with which the server, or the admin, could compute them otherwise. Encrypting them would not make the report weaker — it would make it impossible, and an on-premise product bought for governance would lose the reason it was bought.

A password manager aimed at individuals faces no such requirement and can encrypt more. We would rather explain the difference than quietly claim their property.

Tags used to be in this list and no longer are. They were plaintext for categorization, but tags are free text people write themselves — customer names, project codenames, “handover-from-departing-admin” — so they leaked more about an organization than the item type ever did, and unlike strength and type, no report or query ever used them. They are now encrypted with the vault key alongside the item’s contents. Items created before the change keep their old plaintext tags until a client next saves them; the server cannot migrate them itself, because it cannot decrypt them.

5. Identity, sessions and device trust

Authentication

• Azure AD / Entra ID single sign-on with mandatory MFA, or local accounts with Argon2id password hashing and mandatory TOTP. System administrators always require a second factor. Repeated failures lock the account.
• Passkeys (WebAuthn) are supported both for unlocking rePASS and as a passkey authenticator for third-party sites via the extension.
• Where an organization requires MFA, rePASS checks the identity provider's assertion that it happened. Azure AD omits that claim unless it is configured, so a policy can additionally require proof rather than accept its absence — see the limit below.

Sessions

• Session tokens are signed with an Ed25519 key held only by the server, so verification never requires a secret capable of minting tokens. Lifetimes are organization-controlled; refresh tokens are stored only as SHA-256 hashes, scoped to a device, and revocable individually or all at once.
• Each token is bound to the device identity and the IP address it was issued to. A token replayed from another device or address is rejected and raises a security event — stolen-token replay is treated as an attack, not a login. (A legitimate network change simply triggers a fresh sign-in.)
• Sensitive operations can be gated behind short-lived re-authentication, and sensitive routes require signed single-use nonces; the per-session request-signing keys derive from the Machine Key, independent of the token-signing key.

Device trust

• Every client registers as a device. Organization policy decides whether new devices activate immediately or wait for administrator approval; platform classes can be allowed or blocked per organization, and per-user device counts are capped.
• Revoking a device cascades: its sessions, refresh tokens and token bindings are invalidated together. Approvals and revocations are audit events — a security decision an auditor can reconstruct.

6. Sharing

• Vault membership. A vault has one AES-256 key, wrapped separately for each member under that member’s RSA-4096 public key. Granting access means the sharer — not the server — re-wraps the vault key for the new member on their own device. The server stores and relays wrapped keys; it can never open them.
• Item-level shares. A single item can be offered to another user, encrypted under the recipient’s public key. Shares expire automatically if not accepted, can be cancelled, and every state change is audited. On acceptance the item is re-encrypted under the destination vault’s key — again, entirely client-side.
• Role-based access. Within a vault, roles determine who may read, edit, share or administer. Access checks are enforced server-side on every request; denied attempts are audit events.

7. Recovery and key escrow

Client-side encryption makes “forgot my password” a genuine data-loss risk. rePASS addresses it twice, without weakening the zero-knowledge property for normal operation:

• Self-service recovery key. At setup, the user receives a random 256-bit recovery key that can decrypt an independent wrapping of their private key. It is displayed once, stored nowhere in usable form on the server, and its verifier is hashed with Argon2id.
• Escrow key rotation. The organization's escrow keypair can be replaced without touching anyone's vault: rotation unwraps and re-wraps only the content key inside each escrow record, so the private-key ciphertext passes through untouched and no user has to act. It is owner-only, audited, and all-or-nothing — a partial rotation would leave records wrapped to a key nobody holds.
• Organizational escrow with multi-admin approval. A separate wrapping of each user’s private key is encrypted to an organizational escrow key. Recovery requires a configurable number of designated recovery administrators to approve before it can proceed, and every step is audited — so no single administrator can complete a recovery through the product.

8. Breach detection without data leaving

rePASS checks passwords against known breach corpora — but its customers include air-gapped environments where calling an external API is impossible, and sending password-derived data to a third party is unacceptable anywhere. So rePASS ships the check as a self-hosted service:

• The breach dataset (HaveIBeenPwned-compatible, ~1 billion entries) is imported into your own installation. Imports are integrity-checked: checksums verified and the checksum manifest itself signature-verified before activation.
• Lookups use the standard k-anonymity range protocol: the client hashes the password locally and sends only the first 5 hex characters of the hash — 20 bits — to its own server; matching happens in the browser. Neither the password nor its full hash ever leaves the device, even toward your own backend.
• Choosing to save a breached password anyway is an explicit, audited decision — visible on the security dashboard.

9. Browser extension security

The extension (Manifest V3) is the most exposed client, so its design is conservative:

• No filling in frames. The content script refuses to run inside iframes at all — the classic hidden-iframe and clickjacking credential-theft vectors are cut off structurally, not heuristically.
• Strict origin matching. Credentials fill only on the hostname they were saved for, or its own subdomains — never the reverse. The destination is re-validated at the moment of filling, and again if the tab navigates between lookup and fill.
• User-initiated fill. Credentials are filled when the user asks — via the field menu, the popup, or a keyboard shortcut — not silently on page load.
• Isolated messaging. The content script runs in the browser’s isolated world; web pages cannot message the extension. Every internal message is checked against the extension’s own identity before it is handled.
• Minimal page bridge. Only the passkey feature touches the page’s world, through a narrow, origin-pinned, request-ID-validated bridge that falls back to the browser’s native WebAuthn on any failure.
• Key and clipboard hygiene. Decrypted keys live in memory for the unlocked session and are cleared on lock, logout or timeout. Copied secrets do not linger: the clipboard is cleared after a short timeout, checking first that it still holds the copied value so it never wipes something the user copied afterwards.

10. Audit trail and monitoring

• Comprehensive coverage. Over 100 distinct action types are recorded — authentication, vault and item lifecycle, sharing, device approvals and revocations, policy changes, recovery steps, security violations — each mapped to a standardized event code for SIEM ingestion.
• Tamper evidence. Every record carries an HMAC-SHA256 integrity code keyed with a server-held key kept in guarded memory — so an attacker with database access cannot alter a record and recompute its code. Records are append-only, and integrity can be re-verified across the whole log.
• Secrets cannot leak into logs. Audit detail payloads pass through an allowlist filter that also pattern-scans every value for secret-like content; anything suspect is stripped before the record is written.
• Anomaly detection. A hybrid rule and ML engine running inside your installation scores logins and access patterns — brute force, impossible travel, session anomalies, bulk access — raises security events, and adaptively tightens rate limits for risky actors.
• Remote Browser Isolation. Sessions are audited end to end — who opened one, against which target, for how long, whether a credential was injected and whether a file left the browser. Never the credential, never the file contents. Section 11 describes how isolation works.

11. Remote Browser Isolation

Some credentials should be usable without being handed over. A contractor needs to work inside a supplier portal; an auditor needs to read a banking dashboard. Sharing the password gives away everything, forever. rePASS lets the owner grant use of an account instead of the account itself: the site opens in a throwaway browser inside your own infrastructure and only a video stream reaches the other person.

• One browser per session, then destroyed. Each session gets its own container — read-only filesystem, all Linux capabilities dropped, no privilege escalation, memory-backed scratch space, CPU and memory capped. Under Kubernetes it is one Pod per session, created through the API with rights limited to creating and deleting those Pods, and nothing else. When the viewer disconnects, the browser is destroyed; the session's cookies and history go with it.
• Where it can go is fixed in advance. The owner lists the domains a share may reach. Under Kubernetes a NetworkPolicy confines the browser to the public internet on ports 80 and 443 and blocks every internal range — other pods, cluster services, the node itself and the cloud metadata endpoint. Compose deployments enforce the same list through an allowlist-only egress proxy.
• Autofill without disclosure. When a share includes credentials, the owner's device re-encrypts them under a dedicated organization key — separate from the recovery escrow key, and protected the same way: HSM-wrapped where an HSM is configured, Machine-Key encrypted otherwise. The recipient clicks Fill; the server decrypts in memory, types into the isolated browser, and clears it. The plaintext is never sent to the recipient's device and never written to disk. To be precise about the trust model: for these items this is a deliberate, per-item exception to zero-knowledge, made by the owner — the same application-enforced trust class as escrow recovery.
• Files stay put unless allowed. Downloads are refused at the browser by default. When a share permits them, the file is bounded by a size limit set by the owner, is taken directly from the page and delivered to the recipient without ever touching the container's filesystem, and the attempt is audited by name and outcome — never contents.
• It behaves like a browser. Sites that open tabs — SSO sign-in windows above all — are followed automatically, and the recipient can switch between tabs, close them, and move back and forward. Dialogs the page raises are shown in the viewer rather than left invisible behind the stream.
• Limits the owner sets. Session length, sessions per day, and an expiry date; access can be revoked at any moment, which also ends any session in progress.

12. Infrastructure and deployment

• rePASS deploys with Docker Compose for evaluation and a turnkey hardened Kubernetes (K3s) installer for production — entirely on infrastructure you control. No component phones home; licensing and updates work offline.
• Transport is TLS 1.2+ (TLS 1.3 preferred) everywhere, including between the application and its database. The web tier ships with HSTS, a strict Content Security Policy, frame denial and modern cipher suites preconfigured.
• Server-side secrets are encrypted at rest with keys that can be wrapped by an HSM; in memory they are held in guarded, non-swappable, core-dump-excluded allocations.
• Rate limiting applies per organization and per route class, with stricter pre-authentication limits and adaptive tightening under anomalous behavior. Organization policy — password complexity, session lifetime, IP allowlists, device approval — is enforced centrally, server-side.
• Supply chain. Every change is scanned in continuous integration for known vulnerabilities — reachable code paths in the Go backend and the JavaScript dependency lockfiles — with a weekly re-scan so newly disclosed CVEs surface even in unchanged code, and a full SPDX SBOM is archived per build. Images are tagged by git commit, and the release tooling includes cosign image signing with verification on the deployment host.

13. Vulnerability disclosure

We welcome security research on rePASS. If you believe you have found a vulnerability, email [email protected] with enough detail to reproduce the issue. We will acknowledge your report promptly, keep you informed as we investigate, and credit you in the fix notes if you wish. Please give us a reasonable window to remediate before public disclosure, and do not test against installations you are not authorized to assess.

Reports that show a gap between this document and the implementation are especially valuable — that gap is the thing we most want to know about.

Appendix B. Changelog

This document is versioned because its claims change as the product does. Entries record what changed in the architecture, not only in the prose.

Appendix C. References

1. OWASP — Password Storage Cheat Sheet (PBKDF2 work-factor guidance)
2. RFC 8018 — PKCS #5: Password-Based Cryptography Specification (PBKDF2)
3. RFC 6238 — TOTP: Time-Based One-Time Password Algorithm
4. RFC 8032 — Edwards-Curve Digital Signature Algorithm (EdDSA)
5. NIST SP 800-38D — Galois/Counter Mode (GCM) and GMAC
6. Ali, J. — Validating Leaked Passwords with k-Anonymity
7. W3C — Web Authentication (WebAuthn) Level 2
8. Knuth, D. E. — The TeXbook (1984), origin of the marked-aside convention used here