17 - Authentication, Identity & Account Security

Version: 1.0
Status: Future product source of truth
Owner: Product and Technology
Last updated: August 4, 2026

1. Purpose

This specification defines authentication, person identity, account recovery, identity linking, session security and account-security controls for The Design Registry.

It owns the boundary between proving who a person is and deciding what that person may access. Authentication establishes a User identity. Workspace Memberships, Project access grants and permissions authorize actions. Authentication must never independently grant access to a Workspace, Client, Provider, Project or financial record.

Supabase Auth is the intended production identity provider. The application owns the User Profile, Workspace Memberships, invitations, application continuation, security-event projections and the authorized destination after authentication.

2. Outcomes

A user can sign in reliably with email/password and approved OAuth providers.
A new applicant or invited Teammate continues the correct journey after authentication.
Password recovery is secure, non-enumerating, expiring and auditable.
Users can understand and control active sessions, authentication factors and security events.
Duplicate identities are prevented or resolved through explicit account linking.
Authentication works consistently across Admin, Designer, Provider and Client experiences.
Every environment has verified redirect, email, domain and provider configuration.

3. Current-product correction contract

Review finding	Required future correction	Release blocker
Google sign-in is intended but does not complete successfully through Supabase.	Repair provider configuration, authorized origins, callback URLs, identity linking and destination resolution; pass end-to-end tests in every environment before presenting Google as available.	Yes
The unauthenticated sign-in and recovery surfaces have not been fully verified.	Create a testable authentication state matrix covering layout, validation, loading, failure, expired links, responsive behavior and accessibility.	Yes
Account creation, invitation continuation, email verification and application continuation are not proven.	Preserve signed journey context through identity creation, verification, OAuth redirect and session establishment.	Yes
User Profile exposes password reset and support-based email changes but no MFA, device/session list or security events.	Add recent-authentication gates, email-change verification, MFA, active-session management and security-event history.	Yes for production security launch
Recovery email delivery, sender, expiration and session revocation are unverified.	Configure, monitor and test recovery delivery; enforce single-use tokens and the approved post-reset session policy.	Yes

4. Scope

4.1 Included

email and password sign-in;
Google OAuth sign-in;
email verification;
invitation continuation;
Designer, Provider and Client application continuation;
forgot-password and reset-password flows;
password change;
verified email change;
multi-factor authentication;
session, device and sign-out controls;
identity linking and duplicate prevention;
recent-authentication requirements;
account lock, suspension and recovery support;
security events and notifications;
authentication audit and operational monitoring.

4.2 Excluded

Workspace roles and permissions, owned by Spec 08;
Teammates, Memberships and invitations as operating records, owned by Spec 03;
application fields and approval, owned by Spec 05;
connected Gmail, Calendar, Sheets or Drive consent, owned by Spec 18;
User Profile presentation and preferences, owned by Spec 04.

5. Identity model

5.1 User

A User is one person-level account that may belong to multiple Workspaces and participate in multiple Projects. It is not a Designer Studio, Provider, Client, Workspace, Teammate Membership or Entity.

Minimum User identity data:

stable User ID;
Supabase Auth identity ID;
primary verified email;
email verification time;
display name and User Profile reference;
account state;
authentication methods;
last successful authentication;
security-policy version accepted;
created, updated and disabled timestamps.

5.2 Authentication identity

One User may have multiple verified authentication identities, such as password and Google, without creating duplicate Users. Provider subject identifiers, email claims and linking decisions are retained safely for audit but are never used as Workspace authorization.

5.3 Workspace Membership

A Membership connects one User to one Workspace. The same User may have different Role Labels, Teams and permissions in each Workspace. A valid session with no active Membership must not enter a protected Workspace.

5.4 Applicant identity

An applicant may authenticate before approval. Their account state permits only the pending application experience, status, requested information and approved public/help surfaces. Approval later creates or links the proper Entity, Workspace and Membership without replacing the User.

6. Account states

Invited
Verification Required
Active
Applicant Pending
Temporarily Locked
Suspended
Recovery Required
Scheduled for Deletion
Deleted or Anonymized

Account state is distinct from Membership state, Workspace state, application decision, Network Status and Project access.

7.1 Page anatomy

Design Registry identity;
email field using the shared Email Input;
password field with show/hide control;
Sign in action;
Continue with Google action only when the provider is healthy;
Forgot password link;
invitation/application-aware context notice;
safe create-account or application entry;
privacy and terms links;
accessible status/error region.

7.2 Email/password journey

User enters email and password.
Client performs usability validation without revealing account existence.
Supabase verifies credentials.
The server resolves User state and recent security requirements.
The server resolves permitted destinations.
One destination opens directly; multiple Workspaces invoke Workspace selection.
No destination produces a safe pending, support or no-access state.

7.3 Google OAuth journey

User begins Google sign-in.
The application stores signed, expiring continuation context.
Supabase initiates OAuth using the environment-specific callback.
Callback validates state, nonce and provider response.
Existing verified identity is linked or a new User is created according to policy.
The application resolves Membership, invitation or application destination.
The user returns to the intended safe route.

Google authentication consent is separate from consent to access Gmail, Calendar, Sheets or Drive.

7.4 Provider health

An authentication option is visible only when configured and healthy for the active environment. A failed provider shows a recoverable message and email/password alternative. Secrets, provider tokens and callback details never appear in the interface, analytics or Activity.

8. Invitations and journey continuation

Invitation links carry an opaque, signed, expiring token. They resolve the intended Workspace, inviter, Membership invitation and safe post-authentication destination without exposing internal IDs.

Continuation contexts include:

Teammate invitation;
Workspace owner invitation after provisioning;
Designer application;
Provider application and Provider Category;
Client Portal invitation;
Project participant invitation;
password recovery;
verified email change.

Context survives provider redirects and email verification but cannot redirect to an unapproved host or unauthorized record.

9. Email verification

Verification responses do not enumerate unrelated accounts.
Links are expiring and single-use.
Reissue is rate-limited.
Changed primary emails require verification before replacement.
Verification completion writes a security event.
An applicant may preserve a draft while verification is pending.
Invitation acceptance waits for the required verification state.

10. Password recovery and change

10.1 Recovery request

The user enters an email and always receives neutral confirmation. Eligible accounts receive a branded transactional message through the approved delivery configuration.

10.2 Reset link

The link is signed, single-use, expiring and limited to password recovery. Invalid, expired or reused links explain that a new request is required without exposing token details.

10.3 New password

The form shows policy requirements, confirmation, password-manager compatibility and accessible errors. The server validates the policy and prevents known-compromised or recently disallowed values when configured.

10.4 Session effect

Successful recovery revokes other sessions by default. The current recovery session may continue only according to the approved policy and must pass destination authorization again.

10.5 Signed-in change

Changing a password requires recent authentication. The user chooses whether to sign out other sessions when policy permits; security-sensitive or administrator-triggered resets revoke them automatically.

11. Verified email change

Email changes are self-service when account policy permits. The user must recently authenticate, confirm the new address and receive notification at the old address. Conflicts with an existing identity enter a safe account-linking or support workflow. The old email remains active until verification succeeds.

12. Multi-factor authentication

Initial supported factor:

TOTP authenticator application with recovery codes.

Future-capable factors:

WebAuthn/passkeys;
platform security keys;
organization-enforced methods.

MFA setup requires recent authentication, confirmation of the factor and one-time display of recovery codes. Recovery codes are hashed, single-use and regenerating them invalidates the previous set.

Workspace policy may require MFA for owners, financial permissions, administrators or all Members. Enforcement occurs at authentication and before security-sensitive actions.

13. Sessions and devices

User Profile Security shows:

current session;
other active sessions;
approximate device/browser;
approximate location when legally and technically appropriate;
created and last-active time;
authentication method;
revoke action;
sign out all other sessions.

Session identifiers and raw tokens are never shown. Revocation takes effect promptly and is enforced server-side. Suspended Users and removed Memberships lose affected access without deleting historical attribution.

14. Recent-authentication gates

Recent authentication is required for:

password change;
primary email change;
MFA setup or removal;
recovery-code regeneration;
Workspace ownership transfer;
high-risk permission or payout changes;
account deletion;
support-assisted identity linking.

The application returns the user to the initiating action after successful reauthentication and rechecks authorization.

15. Identity linking and duplicates

Matching email text alone is insufficient to link unverified identities.
A verified provider claim may propose linking but the user must prove control according to policy.
One provider identity maps to one User.
Duplicate candidates enter an administrative reconciliation flow without exposing private account data.
Linking and unlinking require recent authentication and a security event.
The last viable sign-in method cannot be removed until another method is verified.

16. User Profile security section

Spec 04 presents the person-owned profile. This specification supplies the Security section contract:

authentication methods;
password change;
verified email change;
MFA and recovery codes;
active sessions;
recent security events;
account state and recovery guidance;
account deletion request where policy permits.

Accessibility, calendar and notification preferences remain User Profile data and are not stored in Supabase Auth metadata as the only source of truth.

17. Security events and notifications

Required security events:

sign-in succeeded;
sign-in failed threshold reached;
new authentication method linked;
authentication method removed;
password changed or recovered;
primary email change requested and completed;
MFA enabled, disabled or recovery codes regenerated;
new session created;
session revoked;
account locked, suspended, restored or deletion requested;
invitation accepted;
suspicious or policy-blocked attempt.

Every user-facing event that may notify a person is registered in Notifications Builder with protected trigger, recipient and security rules. Security templates cannot expose secrets, full tokens or sensitive device detail.

18. Abuse protection

rate limits by identity, IP, device signal and action;
progressive delays and challenge integration where justified;
neutral error messages;
credential-stuffing and anomalous-attempt monitoring;
email-send throttles;
callback-state and replay protection;
open-redirect prevention;
secure, HTTP-only, same-site session cookies;
CSRF protection for state-changing browser actions;
audited administrator recovery with dual control for high-risk cases.

19. Data model

Minimum canonical records or equivalent services:

users
auth_identity_links
user_profiles
workspace_memberships
membership_invitations
auth_continuations
user_mfa_methods
user_recovery_codes
user_sessions
security_events
account_recovery_cases
identity_linking_cases

Supabase owns password hashes, provider credentials and core authentication sessions. Application tables store only the minimum projections required for product behavior, audit and authorization.

20. API and server commands

Representative commands:

POST /auth/password/sign-in
POST /auth/oauth/google/start
GET /auth/callback
POST /auth/email/verify/request
POST /auth/recovery/request
POST /auth/recovery/complete
POST /account/email-change/request
POST /account/mfa/totp/enroll
POST /account/mfa/totp/verify
POST /account/sessions/{id}/revoke
POST /account/sessions/revoke-others
POST /auth/reauthenticate

All state-changing commands use anti-replay protection and write a security event. Authorization is evaluated after identity resolution and again after material changes.

21. Supabase configuration requirements

For every environment:

explicit Site URL;
allowlisted redirect URLs;
Google OAuth client and callback configuration;
verified email sender/domain and branded templates;
password policy;
token and session lifetimes;
refresh-token rotation;
CAPTCHA or challenge policy where enabled;
audit logging and alert ownership;
RLS policies on application-owned User and Membership data;
secrets stored only in approved environment configuration.

Configuration changes require review and an environment-specific smoke test.

22. Accessibility and usability

Complete keyboard operation and logical focus order.
Visible labels; placeholder text is not the only label.
Errors are announced and linked to fields.
Loading prevents duplicate submission and remains announced.
Password managers and browser autofill work correctly.
Reduced-motion and higher-contrast preferences apply as early as technically possible.
Touch targets and responsive layouts support mobile applicant and Client journeys.
Timeout or expired-context messages preserve safe user-entered data where possible.

23. Operational monitoring

Technology and authorized support can monitor provider health, callback failures, email delivery, recovery volume, lockouts, identity-linking exceptions and suspicious patterns without reading passwords, tokens or unrelated private data.

Alerts identify environment, failure class, correlation ID and safe remediation. Raw provider errors are normalized before any user-facing display.

24. Migration

Inventory current Supabase Users, provider identities and Membership links.
Detect duplicate or orphaned identities without automatically merging them.
Verify email/password recovery configuration.
Repair Google OAuth per environment behind a health-controlled flag.
Add continuation records for invitations and applications.
Add security events, sessions and recent-authentication gates.
Add MFA and self-service verified email change.
Reconcile legacy identity labels and support procedures.

Existing Users retain attribution and Membership history throughout migration.

25. Acceptance criteria

Email/password sign-in succeeds and returns only authorized destinations.
Google OAuth passes end-to-end tests in development, preview and production before being shown.
Provider failure never strands the user without a safe alternative.
No authentication error enumerates unrelated accounts.

25.2 Continuation

Invitations and applications survive email verification and OAuth redirects.
Continuation cannot redirect to an unapproved host or unauthorized record.
Pending applicants cannot access active Workspace or network data.

25.3 Recovery

Recovery messages are delivered from the approved sender.
Links expire, are single-use and reject replay.
Password recovery follows the approved session-revocation policy.
Every successful recovery produces a security event and notification.

25.4 Account security

Users can verify a new primary email without support when policy permits.
MFA enrollment, challenge, recovery codes and removal are tested.
Users can view and revoke active sessions.
High-risk actions require recent authentication.

25.5 Authorization boundary

A valid session without an active Membership cannot enter a protected Workspace.
Removing or suspending a Membership blocks that Workspace without destroying the User.
RLS and server authorization protect User, Membership and Workspace data independently of the interface.

25.6 Quality

Idle, submitting, success, invalid, locked, expired, rate-limited, provider-failed and no-destination states exist.
Authentication surfaces pass keyboard, screen-reader, mobile and password-manager tests.
Logs and analytics contain no passwords, tokens, recovery codes or provider secrets.

26. Implementation order

Configuration inventory and environment matrix.
Email/password and destination-resolution hardening.
Recovery and verified transactional email.
Invitation/application continuation.
Google OAuth repair and identity linking.
User Profile Security, sessions and security events.
Recent-authentication gates and verified email change.
MFA and recovery codes.
Monitoring, support tooling and migration reconciliation.

The governing principle is: prove identity once, authorize every destination explicitly, and make recovery and security understandable without exposing sensitive information.

Current-product review gap closure register

Generated: August 4, 2026
Owning future specification: 17
Mapped current-product profiles: 2
Recorded review gaps: 8

This register is part of the release contract. It maps the current-product reverse review into required future behavior. A gap is not closed because a screen exists; closure requires the corrected canonical data, permissions, states, migration, audit and test evidence described below.

Register rules

Every profile in the Current Product Library must resolve to one owning future specification.
Current limitations are evidence, not optional ideas. If a limitation is intentionally retained, the specification must record the decision, risk, owner and review date.
Shared-component defects are corrected through Spec 16 and then consumed here; feature teams may not create local replacement controls.
Permission, contact, financial and visibility defects also require Spec 08 enforcement, even when the functional feature is owned by another specification.
Legacy Proper Gallery, Lead, Partner and implementation-facing labels are migration inputs only and must not return through new UI, APIs, exports or notifications.
Verification must use realistic fixtures for Admin, Designer, Provider and Client audiences where applicable.

Current-product profile: sign-in
Observed route: /sign-in
Evidence confidence: Known limitation

Review gaps

Google sign-in does not currently work through Supabase.
The exact sign-in route, responsive layout, field validation and error copy were not observed in an unauthenticated session.
Account creation, invitation continuation, email verification and duplicate identity linking are not validated as current behavior.
MFA, recent-authentication gates and session management are not yet represented in the current profile.

Required future closure

Repair and test the Supabase Google provider, authorized origins and callback URLs in every environment.
Preserve application or invitation context through authentication and email verification.
Add explicit loading, cancellation, provider failure and no-membership states.
Complete identity linking, session security and account recovery in Spec 17.

Closure evidence required

The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
Automated tests cover the identified defect or missing journey so it cannot silently regress.
Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G02 — Forgot and reset password

Current-product profile: forgot-and-reset-password
Observed route: /forgot-password
Evidence confidence: Partially verified