additionalFields plugin lets you attach typed custom data to users and sessions without writing migrations. Fields are stored in the metadata JSON column of theauth_users and theauth_sessions.
Install
Ships inside@glinr/theauth/auth, no extra packages needed.
Setup
Define a schema once when creating your theAuth instance:Reading and writing user fields
setUserFields merges with existing fields. Previously stored keys not present in the update are preserved. It throws if validation fails or the user does not exist.
Reading and writing session fields
Validation
Validate a field map before writing, or in a request handler:validate() (and automatically on every setUserFields / setSessionFields call):
- Required fields must be present in the map you pass. Because
setUserFieldsandsetSessionFieldsvalidate the update itself (not the merged result), a schema withrequired: truefields means every write must include them. - Field values must match the declared type.
- Fields not in the schema are rejected.
Field types
REST endpoints
GET example
PUT example
422 when validation fails. Returns 404 when the user does not exist. The endpoints require an authenticated user, but they do not check that the userId is the caller’s own, so any signed-in caller can read or write another user’s fields. Put your own ownership or admin check in front of them. GET returns the schema defaults for an unknown user ID rather than a 404.
Validate example
200 when valid and 422 when not. schema must be "user" or "session". Only the user fields have REST read and write endpoints, session fields are read and written through the module (getSessionFields, setSessionFields).
Schema reference
Storage
No database migrations are needed. User fields are stored underuser.metadata.additionalFields and session fields under session.metadata.additionalFields. Other metadata keys written by the core system or other plugins are not modified.
Related
Hooks
Lifecycle hooks you can attach to your instance.
Custom session
Store extra data on a session record.
Database
Supported databases and schema overview for theAuth.
Organizations
Organizations with roles and per-org metadata.