Explore human-entered email confirmation codes for contact enrollment

[Sequela02]

Problem

Vigil 7.3.0 provides a route-free contact-enrollment primitive with one canonical proof representation: a 256-bit random value encoded as 43-character Base64URL. That is a strong transport token for a verification link, but it is not suitable for manual entry.

Some host applications may prefer a conventional password sign-up flow in which the person submits an email address and password, then deliberately enters a short code delivered to that address. Today, supporting that presentation would require the host to replace or duplicate proof-generation and validation policy outside Vigil, even though Vigil owns the contact-proof lifecycle.

This issue proposes investigating whether Vigil should support a human-entered email confirmation-code mode. It does not assume that OTP is appropriate for every consumer or that six decimal digits are the final design.

Related: #31.

External evidence

Research checked on 2026-09-12:

• NIST SP 800-63A-4 allows confirmation codes to be presented as manually entered numeric or printable ASCII values, secure links, or machine-readable labels. For its identity-proofing scope, it requires at least six decimal digits or equivalent, approved randomness, invalidation after use, and a maximum 24-hour lifetime for email delivery. This is a useful control baseline, not a universal mandate for all Vigil consumers: https://pages.nist.gov/800-63-4/sp800-63a/ial-general/#requirements-for-confirmation-codes
• Auth0 supports both verification links and emailed OTPs, and notes that OTP entry requires an explicit user action and avoids accidental verification by email scanners: https://auth0.com/docs/manage-users/user-accounts/verify-emails
• Supabase documents that mail-security prefetchers can consume direct confirmation links and suggests either an emailed OTP or an interstitial page with an explicit confirmation action: https://supabase.com/docs/guides/auth/auth-email-templates#email-prefetching
• Clerk's current custom email/password sign-up flow uses an email verification code, while its link mode can require the same browser and device: https://clerk.com/docs/guides/development/custom-flows/authentication/email-password and https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email
• Research presented at USENIX Security 2022 found account pre-hijacking weaknesses in 35 of 75 evaluated services. It supports preserving user intent and careful account-linking boundaries, but does not by itself establish that an email OTP solves every pre-hijacking class: https://www.usenix.org/conference/usenixsecurity22/presentation/sudhodanan

Proposed investigation

Evaluate these alternatives against the existing enrollment boundary:

1. Keep the current opaque link proof as the only Vigil mechanism and document how hosts should handle explicit confirmation and mail-link prefetching.
2. Add an opt-in, human-entered confirmation-code strategy while preserving the current opaque link token as the compatibility default.
3. Expose a constrained proof-generation/presentation SPI so hosts can select a representation without taking ownership of proof validation and lifecycle policy.

The investigation should answer:

• Whether the choice belongs in configuration or in an explicit strategy contract.
• Which code alphabets and lengths provide acceptable usability and online-guessing resistance under bounded attempts.
• Whether code TTL should differ from the existing link-proof TTL.
• How resend rotates the active generation and invalidates earlier codes without extending the total lifecycle.
• How EnrollmentDeliveryPort can identify the presentation mode without owning a mail provider, template, route, or UI.
• Whether the existing store commands can remain stable or need additive versioned data.
• How to preserve generic responses, canonical email binding, audience/purpose/context binding, digest-only storage, recovery behavior, and atomic one-time verification.

Boundary constraints

• Vigil should continue to own only contact-proof generation, validation, throttled lifecycle, and receipt orchestration.
• Host applications continue to own passwords, pending registration state, users/accounts, sessions, routes, UI, email infrastructure, organization membership, authorization, and account linking.
• A confirmation code must not create credentials, sessions, memberships, or authority by itself.
• Existing 7.x consumers should not silently change proof representation or security behavior.

Acceptance criteria for the investigation

• A documented decision compares the three alternatives using security, usability, compatibility, host complexity, and operational recovery.
• The selected direction defines randomness, minimum effective entropy, canonical representation, digesting, expiry, attempt limits, resend rotation, one-time use, concurrency behavior, and log redaction.
• Direct-link prefetching and cross-device behavior are addressed explicitly.
• Pre-account-hijacking and future password/social-account linking are included in the threat analysis without moving those responsibilities into Vigil.
• Any proposed public API or configuration change is additive by default, or includes an explicit migration and versioning decision.
• Observable tests are identified for invalid format, guessing exhaustion, expiry boundaries, resend races, old-generation replay, concurrent verification, delivery ambiguity, and receipt recovery.