Implement secure invitation token lifecycle

[yacosta738]

Context

Invitation security is central to invite-only onboarding. Tokens must behave like other sensitive one-time credentials: generated securely, persisted only as hashes, consumed once, and never leaked to logs or audit records.

Goal

Implement the secure invitation token lifecycle for issuance, storage, validation, expiration, and single-use consumption.

Scope

• Generate cryptographically secure invitation tokens.
• Persist only token hashes.
• Exclude raw tokens from logs, metrics, and audit events.
• Enforce expiration server-side.
• Enforce concurrency-safe single consumption.

Out of Scope

• Email notification formatting.
• Full invitation admin UI.
• General-purpose token infrastructure redesign beyond what this capability needs.

Domain Rules

• Raw tokens are delivered only to the intended recipient.
• Stored token representation must be non-reversible in normal operation.
• A consumed invitation token must not be reusable.
• Concurrent acceptance attempts must result in exactly one success.

API Contract

• Invitation issuance and acceptance flows depend on this token lifecycle.
• Invalid, expired, revoked, or already-consumed tokens must be rejected safely.

Security

• Cryptographically secure randomness.
• URL-safe token format.
• Hash-only persistence.
• No token leakage in logs, metrics, or audits.

Audit

• Security-sensitive token values must never appear in administrative audit records.

Observability

• Token lifecycle outcomes should be measurable by aggregate counts only.
• Avoid high-cardinality token- or user-derived dimensions.

Acceptance Criteria

1. Invitation tokens are generated with secure randomness and URL-safe encoding.
2. Only token hashes are persisted.
3. Expiration and single consumption are enforced server-side.
4. Concurrent acceptance attempts allow exactly one success.
5. Automated tests verify security and concurrency behavior.

Gherkin

Feature: Invitation token lifecycle

  Scenario: Persist only token hash
    When the system creates an invitation token
    Then only the token hash should be stored

  Scenario: Prevent invitation replay
    Given an invitation token has already been consumed
    When the token is presented again
    Then the request should be rejected

  Scenario: Concurrent acceptance succeeds once
    Given an active invitation token exists
    When two registration requests consume it concurrently
    Then exactly one request should succeed

Testing

• Unit
• Application
• Persistence
• Integration
• Security

Dependencies

• Model invitation as a first-class domain capability #660

References

• RFC sections 12, 14, 40, 43, 44

[linear-code]

DALLAY-566