backbone_auth (Better Auth)

Schema dedicato al layer di autenticazione gestito da Better Auth.

Better Auth e una libreria Node.js open source che viene wrappata in un microservizio Express dedicato (auth-service). Gestisce autenticazione e autorizzazione senza dipendere da provider esterni a pagamento.

La separazione in schema dedicato (backbone_auth) mantiene il layer credenziali/sessioni isolato dal layer di mapping e autorizzazioni platform (backbone_identity).

Responsabilita

backbone_auth     = credenziali, sessioni, account OAuth, verifiche
backbone_identity = mapping identita esterne -> applicazioni/tenant, ruoli, audit

backbone_auth e owned esclusivamente dall'auth-service. Nessun altro microservizio accede direttamente a questo schema.

Configurazione Better Auth

Better Auth viene configurato con:

• useSnakeCase: true per allineare i nomi colonne al resto della backbone
• table prefix auth_ per evitare conflitti con keyword riservate PostgreSQL (user, session)
• schema backbone_auth tramite opzione database adapter

Tabelle core

auth_user

Utenti registrati. Source of truth delle credenziali.

Colonna	Tipo	Note
id	text	PK, generato da Better Auth (nanoid)
name	text	Nome visualizzato
email	text	Unico
email_verified	boolean	Default false
image	text	URL avatar
created_at	timestamptz
updated_at	timestamptz

auth_session

Sessioni attive.

Colonna	Tipo	Note
id	text	PK
expires_at	timestamptz
token	text	Unico, token sessione
ip_address	text
user_agent	text
user_id	text	FK -> auth_user
created_at	timestamptz
updated_at	timestamptz

auth_account

Account collegati a provider OAuth o credenziali locali.

Colonna	Tipo	Note
id	text	PK
account_id	text	ID presso il provider
provider_id	text	Es. google, github, credential
user_id	text	FK -> auth_user
access_token	text
refresh_token	text
id_token	text
access_token_expires_at	timestamptz
refresh_token_expires_at	timestamptz
scope	text
password	text	Hash password per credenziali locali
created_at	timestamptz
updated_at	timestamptz

auth_verification

Token temporanei per verifica email, OTP e magic link.

Colonna	Tipo	Note
id	text	PK
identifier	text	Es. email o numero telefono
value	text	Token/hash
expires_at	timestamptz
created_at	timestamptz
updated_at	timestamptz

Tabelle plugin organization

Abilitate tramite il plugin organization di Better Auth. Mappano il concetto di tenant/cliente multi-applicazione.

auth_organization

Organizzazioni (tenant/clienti).

Colonna	Tipo	Note
id	text	PK
name	text
slug	text	Unico, usato nei subdomain/routing
logo	text	URL logo
metadata	text	JSON arbitrario
created_at	timestamptz

auth_member

Membership utente/organizzazione.

Colonna	Tipo	Note
id	text	PK
organization_id	text	FK -> auth_organization
user_id	text	FK -> auth_user
role	text	Default member; valori: owner, admin, member
created_at	timestamptz

auth_invitation

Inviti a organizzazioni.

Colonna	Tipo	Note
id	text	PK
organization_id	text	FK -> auth_organization
email	text	Destinatario
role	text	Ruolo assegnato all'accettazione
status	text	pending, accepted, cancelled
expires_at	timestamptz
inviter_id	text	FK -> auth_user

Relazione con backbone_identity

backbone_auth non sostituisce backbone_identity. I due layer cooperano:

autenticazione:   browser -> auth-service -> backbone_auth
                  auth-service emette token interno

autorizzazione:   microservizio -> data-service -> backbone_identity
                  verifica ruoli/permessi applicativi su external_identity_id

Il collegamento tra i due layer avviene tramite backbone_identity.external_identities, che mappa backbone_auth.auth_user.id come provider_subject con provider_id = backbone_auth.

Tabelle non presenti (gestite da Better Auth)

Le seguenti responsabilita non richiedono tabelle aggiuntive perche gestite internamente da Better Auth o non necessarie con questo setup:

Responsabilita	Motivo
Password reset tokens	Gestiti tramite auth_verification
Refresh token storage	Gestiti in auth_account
Rate limiting	In memoria o Redis, non su DB