Master Civil Identity & Multi-Provider Logins

1. Domain Modeling: Subject vs. Identity Provider

The GERCIA Platform decouples who a person is (Master Civil Identity / Subject) from how they authenticate (Identity Provider / IdP).

erDiagram
    USER ||--o{ USER_LOGIN : "has multiple logins (1:N)"
    USER ||--o{ TENANT_USER_ACCESS : "has roles across tenants (1:N)"
    
    USER {
        Guid Id PK "Guid v7 temporal key"
        string FullName "Legal civil name"
        string SocialName "Preferred name"
        DateOnly BirthDate "Date of birth"
        string Cpf "Citizen Tax ID"
        string Email "Primary contact email"
        string NormalizedEmail "Uppercase unique lookup"
        string PhoneNumber "Mobile phone"
        string PasswordHash "Argon2id hash (optional)"
        string SecurityStamp "Session invalidation token"
        bool TwoFactorEnabled "TOTP flag"
        bool IsActive "Account status"
        bool IsAccountClaimed "Account activation flag"
    }

    USER_LOGIN {
        Guid Id PK "Guid v7 key"
        Guid UserId FK "Reference to core.users"
        string LoginProvider "Google, Apple, Microsoft, GovBr"
        string ProviderKey "External subject ID (sub)"
        string ProviderDisplayName "Google Account, Apple ID"
    }

    TENANT_USER_ACCESS {
        Guid Id PK
        Guid UserId FK
        Guid TenantId FK
        Guid BranchId FK "Optional branch scope"
        Guid RoleId FK
        bool IsActive
    }

---

2. Advantages of the 1:N UserLogin Architecture

1. Multi-Platform Single Identity: The same user can log in via Google on Android, Apple ID on iOS, and Email + Password on Web, resolving to the exact same UserId.
2. Future-Proof Extensibility: New login providers (such as Gov.br, Microsoft Entra ID, or SAML SSO) can be added with zero schema migrations or changes to core.users.
3. Clean Account Linking: Users can manage their connected authentication providers directly from their profile (“Connected Accounts: [x] Google, [ ] Apple”).