Home / E2EAuth / E2EAuth Specification

E2EAuth

Your Keys. Your Devices. Fully Protected.

Overview

E2EAuth is an open-source, cross-platform authenticator specification designed to provide secure, private, and reliable management of multi-factor authentication credentials across desktop and mobile devices. It supports Time-Based One-Time Passwords (TOTP) and HMAC-Based One-Time Passwords (HOTP), with end-to-end encrypted synchronization, local-first storage, and social recovery through trusted contacts.

E2EAuth is designed around user ownership, zero-knowledge architecture, interoperability, transparent security practices, and freedom from vendor lock-in. Authentication secrets remain under user control, and synchronization or recovery services must not gain independent access to the user’s credential vault.

Core Principles

Security First: Protect authentication secrets throughout storage, synchronization, recovery, and use.
End-to-End Encryption: Ensure that only authorized user devices can decrypt the credential vault.
Local-First Operation: Allow users to generate authentication codes without an internet connection.
User Ownership: Give users control over credentials, devices, encryption keys, backups, and recovery arrangements.
Cross-Platform Compatibility: Support secure access across desktop and mobile environments.
Zero-Knowledge Architecture: Prevent servers, service operators, and recovery contacts from independently reading vault contents.
Open Source Transparency: Enable public review of the specification, implementation, security controls, and changes.
Interoperability: Support established authentication standards and portable credential migration.
Resilient Recovery: Provide secure recovery options without introducing unauthorized access or centralized recovery backdoors.
Auditable Operations: Maintain transparent records of security-relevant actions without unnecessarily exposing authentication secrets.

Core Modules

Authentication Credential Management

Support TOTP credentials in accordance with RFC 6238.
Support HOTP credentials in accordance with RFC 4226.
Allow users to add credentials by scanning compatible QR codes.
Support manual entry of issuer names, account identifiers, shared secrets, algorithms, digit lengths, and other required parameters.
Validate imported credential parameters and identify unsupported configurations.
Generate authentication codes locally using the appropriate algorithm and credential parameters.
Display countdown indicators for time-based codes.
Track HOTP counter state and synchronize counter updates safely across authorized devices.
Support credential names, issuer information, account labels, icons, categories, tags, and notes.
Provide search, sorting, filtering, and favorites.
Display code expiration and regeneration status clearly.
Support secure copying of authentication codes with configurable clipboard-clearing behavior.
Minimize exposure of secrets and codes in application logs, notifications, crash reports, and diagnostic output.
Clearly identify invalid, expired, unsupported, or potentially conflicting credentials.
Preserve credential functionality when the device is offline.

Secure Vault and Local Storage

Store authentication credentials in a protected local vault.
Encrypt sensitive credential data at rest.
Separate vault encryption keys from stored credential data.
Use secure platform facilities for protecting device-specific key material when available.
Support a user-controlled vault unlock mechanism.
Support strong password-based key derivation where passwords are used.
Provide optional biometric unlocking through supported operating-system security facilities.
Apply configurable automatic locking after inactivity or application backgrounding.
Require reauthentication for sensitive operations according to user-defined security policies.
Protect against accidental exposure through application previews, screenshots where supported, clipboard history, and notification content.
Provide secure vault locking and session termination.
Avoid storing plaintext authentication secrets in logs, temporary files, or unprotected backups.
Communicate the limitations of device-level protection and the risks of compromised operating systems.

End-to-End Encryption and Key Management

Encrypt vault contents before they leave the originating device.
Ensure synchronization providers cannot independently decrypt credential data.
Use established, independently reviewed cryptographic algorithms and protocols.
Define authenticated encryption, secure key derivation, nonce handling, and key rotation requirements.
Establish authenticated device identities and secure key exchange for device pairing.
Prevent unauthorized devices from joining a user’s synchronization network.
Protect synchronized data against tampering, replay, and unauthorized modification.
Bind encrypted records to appropriate contextual metadata to prevent unintended substitution between vaults or records.
Separate authentication, encryption, device identity, and recovery responsibilities.
Prevent passwords, encryption keys, recovery shares, and authentication secrets from appearing in telemetry or diagnostic output.
Support revocation of device access and rotation of relevant encryption keys.
Clearly communicate that previously authorized or compromised devices may retain information they have already decrypted.
Document cryptographic assumptions, threat models, key lifecycles, and recovery limitations.

Cross-Device Synchronization

Synchronize credentials between authorized desktop and mobile devices.
Support synchronization through peer-to-peer connections, encrypted cloud services, or user-operated infrastructure.
Preserve end-to-end encryption regardless of the selected synchronization method.
Allow users to choose, change, or disable synchronization providers.
Support secure device pairing with explicit user authorization.
Display paired devices, device identifiers, last synchronization status, and relevant security information.
Notify users about new device enrollment and significant synchronization security events.
Support synchronization recovery after temporary disconnection or extended offline operation.
Detect conflicting changes and provide safe resolution mechanisms.
Preserve credential metadata and configuration during synchronization.
Handle HOTP counter updates carefully to reduce duplicate codes, counter rollback, and inconsistent state across devices.
Prevent stale or replayed synchronization data from silently overwriting newer security-relevant state.
Allow users to revoke lost, stolen, or no longer trusted devices.
Ensure device revocation prevents future authorized synchronization and access to newly protected vault data.
Explain that revocation cannot erase previously downloaded information from a device that is no longer under the user’s control.

Social Recovery and Trusted Contacts

Provide an optional social recovery system for users who lose access to their vault or all previously authorized devices.
Allow users to designate trusted recovery contacts.
Use an established, reviewed threshold secret-sharing scheme to distribute recovery material.
Allow users to configure the minimum number of recovery shares required to complete recovery.
Ensure recovery contacts receive only their designated recovery shares, not copies of the user’s authentication credentials.
Prevent any individual contact, server, or service operator from independently reconstructing the vault key when the configured threshold has not been met.
Require an authenticated recovery request and explicit participation from the required number of authorized contacts.
Clearly explain recovery thresholds, contact responsibilities, and the consequences of losing recovery shares.
Bind recovery requests and approvals to the intended vault, recovery session, and current recovery configuration.
Protect against replayed approvals, duplicate shares, unauthorized recovery attempts, and substitution of recovery sessions.
Notify the user and relevant recovery participants about recovery requests and completed recovery operations where secure communication is available.
Support adding, removing, or replacing recovery contacts through an authenticated management process.
Support recovery-share rotation when the recovery configuration changes.
Explain that removing a contact cannot erase a recovery share the contact has already copied.
Require appropriate post-recovery key rotation, session review, and device reauthorization.
Allow users to disable social recovery and choose alternative recovery methods.
Provide warnings when the configured recovery threshold cannot be met or when recovery material may be insufficient.
Never introduce a centralized recovery backdoor or permit recovery services to bypass the user’s configured threshold.
Clearly communicate that permanent vault loss may occur if all authorized devices and sufficient recovery material are lost.

Encrypted Backup and Restoration

Support creation of encrypted backups of the credential vault.
Ensure backups remain encrypted independently of the storage location.
Allow users to export backups to local storage or a user-selected destination.
Support restoration to a new device through an authenticated process.
Validate backup integrity and compatibility before restoring data.
Protect against corrupted, incomplete, or tampered backup files.
Clearly identify backup creation dates and relevant format versions.
Support backup versioning where practical.
Allow users to verify backup availability without exposing vault contents.
Provide guidance for securely storing backup files and recovery material.
Prevent backups from silently replacing a newer vault without appropriate confirmation.
Document which settings, metadata, device associations, and recovery configurations are included in each backup format.
Warn users when a backup cannot be restored without additional credentials or recovery material.

Device Management and Access Control

Maintain a list of authorized devices associated with each vault.
Require explicit authorization before adding a new device.
Support device naming and identification.
Display device enrollment and last-seen information where available.
Allow users to revoke device access.
Support session termination and reauthentication.
Notify users about security-sensitive enrollment, revocation, and recovery events where possible.
Protect device-management operations against unauthorized changes.
Require appropriate confirmation before destructive or security-sensitive actions.
Support re-enrollment after device replacement or operating-system reinstallation.
Explain the difference between removing a device from synchronization and securely erasing data from that device.
Provide a clear process for responding to lost or stolen devices.

Security, Privacy, and Threat Protection

Define and maintain a documented threat model.
Protect against unauthorized vault access, data theft, synchronization tampering, recovery abuse, and credential disclosure.
Use secure defaults for encryption, locking, device enrollment, and recovery.
Apply rate limiting and appropriate abuse prevention to authentication and recovery operations.
Validate imported data and reject malformed or unsupported credential records safely.
Minimize collection and retention of personal information.
Keep analytics and telemetry disabled by default when they are not essential to security or functionality.
Never transmit authentication secrets or plaintext vault contents for analytics, advertising, or unrelated processing.
Avoid advertising identifiers, unnecessary tracking, and undisclosed third-party data sharing.
Provide a privacy notice describing all collected information and its purpose.
Support independent security review and responsible vulnerability disclosure.
Include automated tests for cryptographic boundaries, access control, synchronization, and recovery behavior.
Document known limitations, security assumptions, and incident response procedures.
Avoid claiming that encryption alone protects against malware, compromised devices, coercion, or physical access to an unlocked application.

Import, Export, and Migration

Support importing compatible TOTP and HOTP credentials from established authenticator export formats where practical.
Support QR-based migration when the source application provides a compatible format.
Validate imported records and report credentials that cannot be transferred.
Preserve issuer names, account identifiers, algorithms, digit counts, and other supported parameters.
Provide encrypted export options for sensitive credential data.
Clearly warn users before producing plaintext exports or displaying sensitive migration QR codes.
Require appropriate authorization before exporting or migrating credentials.
Avoid sending migration data through untrusted intermediaries.
Support documented, versioned migration formats where possible.
Allow users to migrate away from E2EAuth without requiring continued access to a proprietary service.
Provide safe handling guidance for temporary export files and migration sessions.
Ensure imports cannot silently overwrite existing credentials without clear user confirmation.

User Interface and Accessibility

Provide a clear interface for viewing and using authentication codes.
Organize credentials by issuer, account, category, favorites, and search results.
Provide accessible navigation and controls across supported platforms.
Support screen readers, keyboard navigation, scalable text, and appropriate contrast.
Clearly communicate code expiration, synchronization status, device trust, and recovery state.
Distinguish routine status messages from security warnings and recovery confirmations.
Provide understandable explanations of security settings without requiring specialized cryptographic knowledge.
Offer configurable appearance and accessibility preferences.
Avoid displaying sensitive information unnecessarily.
Require clear confirmation for irreversible actions such as credential deletion, recovery reconfiguration, and destructive restoration.
Provide helpful error messages that do not reveal secrets or internal security-sensitive details.

Auditability and Security Event History

Maintain a privacy-conscious history of important security events.
Record relevant events such as device enrollment, revocation, recovery configuration changes, backup restoration, and security-sensitive settings changes.
Avoid recording authentication secrets, generated codes, passwords, recovery shares, or decrypted vault contents.
Protect event records against unauthorized modification where practical.
Clearly distinguish locally recorded events from events received through synchronization.
Preserve timestamps and event context where available.
Allow users to inspect relevant security activity.
Support secure export of event history without exposing credential material.
Document limitations when devices are offline, compromised, or unable to report events.
Never present incomplete local logs as a complete record of all activity across every device.

Optional Plugin Modules

Browser Integration Plugin

Provide optional browser-based access to supported authentication workflows.
Require explicit authorization before browser integration can access credential data.
Restrict access to the minimum information required for the requested operation.
Avoid exposing the entire vault to web pages or unrelated browser extensions.
Provide clear origin verification and safeguards against phishing.
Keep browser integration optional and independently disableable.
Never automatically submit authentication codes to untrusted destinations.

Command-Line Interface Plugin

Provide command-line access to approved vault operations.
Require secure authentication and appropriate authorization.
Avoid exposing secrets through command history, process arguments, terminal logs, or shell output.
Support scripting for non-sensitive administrative tasks.
Require explicit safeguards before displaying or exporting authentication codes.
Respect the same access controls and security policies as the primary application.

Hardware Security Plugin

Support compatible hardware-backed key protection where available.
Allow integration with supported platform security modules or external security devices.
Protect supported key operations from unnecessary exposure to application memory.
Clearly identify which operations are hardware protected and which are not.
Provide graceful fallback behavior when supported hardware is unavailable.
Avoid claiming that hardware-backed protection prevents every form of device compromise.

Self-Hosted Synchronization Plugin

Allow users to operate their own synchronization infrastructure.
Preserve end-to-end encryption and client-side authorization.
Support authenticated connections and integrity-protected synchronization.
Provide configuration and operational guidance for self-hosted deployments.
Prevent server administrators from independently decrypting user vaults.
Allow migration between synchronization providers without requiring credential re-entry.
Document availability, backup, and operational security responsibilities for self-hosted services.

Additional Recovery Plugin

Allow integration of alternative recovery mechanisms, such as offline recovery kits or user-controlled recovery keys.
Keep recovery mechanisms independent of ordinary authentication operations.
Require explicit user setup and clear explanations of recovery consequences.
Support recovery material rotation and revocation where the selected mechanism permits it.
Prevent plugins from bypassing the core recovery threshold or encryption requirements.
Clearly document the security assumptions and limitations of each recovery method.

Policy and Administration Plugin

Provide optional policy controls for managed or organizational deployments.
Support configurable requirements for device enrollment, vault locking, synchronization, and recovery.
Keep administrative policies transparent to affected users.
Prevent administrators from silently accessing plaintext credentials.
Provide auditable policy changes and explicit authorization boundaries.
Preserve user privacy and avoid collecting authentication secrets for compliance reporting.

Testing and Verification

Test TOTP and HOTP behavior against established reference vectors.
Verify encryption, decryption, key derivation, and authentication behavior.
Test secure device enrollment, synchronization, and device revocation.
Test social recovery thresholds, missing shares, invalid approvals, replay attempts, and recovery-share rotation.
Test backup creation, restoration, integrity validation, and compatibility.
Test import and export across supported credential formats.
Verify that logs, crash reports, and diagnostic output do not expose sensitive data.
Test offline operation, interrupted synchronization, and concurrent credential updates.
Perform security-focused code review and independent cryptographic review.
Maintain regression tests for discovered vulnerabilities.
Document test coverage, unresolved security concerns, and known implementation limitations.

Specification Branding License (SBL)

Standard

Fully AGPL-3.0+ compliant system.
Copyleft enforced for network deployments.
Required attribution:
- Roxanne Ardary
- https://www.roxanneardary.com/

Optional

Specification Branding License (SBL)
- Attribution-free commercial deployment.
- Pricing based on scale, usage, and deployment scope.
- https://roxanneardary.com/e2eauth/

License & Notice Requirements

E2EAuth is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

By contributing to any Open Arsenal project, you agree that your contributions will also be released under this license.

Please note the following:

All contributions must comply with the AGPL-3.0+ terms.
Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to Roxanne Ardary and roxanneardary.com.
E2EAuth specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update notice.md.
When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – E2EAuth

Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.

Contributors

This file tracks contributors and their specific contributions to the project.

Roxanne Ardary, roxanneardary.com – October 24, 2026
Created the repository for E2EAuth. Defined the project vision and specification for an open-source, cross-platform authenticator supporting TOTP and HOTP, end-to-end encrypted synchronization, local-first storage, and trusted-contact social recovery.
[Add other contributors here] – [Date]
[Describe contribution in one sentence]

License – E2EAuth

This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

Key Points:

You are free to use, modify, and distribute the code.
All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
The software is provided “as is,” without warranty of any kind.

For the full license text, see GNU AGPL-3.0 License.

Open Arsenal

E2EAuth Specification