Skip to content

feat(enrollment)!: add human-entered confirmation codes - #37

Merged
Sequela02 merged 1 commit into
mainfrom
release/8.0.0
Sep 13, 2026
Merged

Sequela02 merged 1 commit into
mainfrom
release/8.0.0

Conversation

@Sequela02

Copy link
Copy Markdown
Contributor

Summary

Adds a closed, configuration-owned proof format for contact enrollment:

  • keeps OPAQUE_TOKEN for application-owned verification links;
  • adds uniform eight-digit DECIMAL_CODE proofs for deliberate manual entry;
  • protects the small code space with a dedicated, authority-bound HMAC-SHA-256 key;
  • keeps one enrollment lifecycle, store contract, delivery port, and receipt/recovery path.

The configured format governs both generation and verification. There is no cross-format migration fallback or proof-strategy SPI.

Breaking migration

This prepares Vigil 8.0.0 because the compatibility-only constructors were removed:

  • direct EnrollmentProperties callers must supply proofFormat and codeHmacKey;
  • direct EnrollmentDelivery callers must supply proofFormat.

Changing proof format or the decimal-code key invalidates pending proofs. Resend remains bounded by the existing cooldown, attempt, resend, and total-lifetime policy; duplicate start does not reset the lifecycle.

Security and operations

Decimal codes are exactly eight ASCII digits, use approved secure randomness, have a maximum 15-minute TTL, and allow at most five lifecycle-wide attempts. Attempts remain cumulative across resend. The HMAC binds canonical email, context ID/version, trusted audience, purpose, format, and proof, and the dedicated key is excluded from state and string rendering.

The PostgreSQL contract fixture covers exact expiry, resend rotation, cumulative and concurrent attempt exhaustion, concurrent verification, and resend-versus-verify serialization. Hosts remain responsible for a durable atomic production EnrollmentStore, delivery infrastructure, and abuse controls.

Verification

  • gradlew.bat clean check --no-daemon
  • gradlew.bat qualityCheck build publishToMavenLocal --no-daemon --no-configuration-cache
  • PostgreSQL Testcontainers: 6 tests, 0 skipped, 0 failures, 0 errors
  • local Markdown links and git diff --check
  • generated JARs, POM, Gradle module metadata, and Maven-local coordinates verified as 8.0.0

Closes #36

Add a closed proof-format contract with dedicated HMAC protection for bounded eight-digit codes. Prepare the 8.0.0 release candidate and document migration and operating constraints.

BREAKING CHANGE: EnrollmentProperties and EnrollmentDelivery now expose only their canonical constructors, and verification accepts only the configured proof format.
@Sequela02
Sequela02 merged commit 840cf96 into main Sep 13, 2026
3 of 4 checks passed
@Sequela02
Sequela02 deleted the release/8.0.0 branch September 13, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Explore human-entered email confirmation codes for contact enrollment

1 participant