@authup/core-kit

Domain types, enums and validators for every Authup entity, shared by server and clients.
The shapes of users, clients, roles, permissions and realms, and the rules their fields follow.

Installation · Usage · API · Documentation

Where it fits

@authup/core-kit is the domain layer every other Authup workspace builds on: the server validates incoming payloads with its validators, @authup/core-http-kit types its responses with its entities, and the Vue kit renders its forms against the same rules. You install it directly when you write TypeScript against Authup and need the entity types or the permission and scope names, for example to type your own API layer or to check permission.name === PermissionName.USER_UPDATE without a string literal. If you already use @authup/core-http-kit, it is installed with it.

Installation

npm install @authup/core-kit

ESM only. Node.js >=26.0.0, or a browser bundler. There are no peer dependencies.

Usage

Entity types

Every entity is a plain type with camelCase fields:

import type { Role, User } from '@authup/core-kit';

function label(user: User) : string {
    return user.displayName ?? user.name;
}

const role: Pick<Role, 'name' | 'realmId'> = { name: 'editor', realmId: null };

EntityType names every entity (EntityType.USER === 'user', EntityType.ROLE_PERMISSION === 'rolePermission'), and EntityTypeMap maps each name to its type.

Names and enums

import {
    IdentityType,
    PermissionName,
    REALM_MASTER_NAME,
    ROLE_ADMIN_NAME,
    ScopeName,
} from '@authup/core-kit';

PermissionName.USER_UPDATE; // 'user_update'
ScopeName.GLOBAL; // 'global'
IdentityType.CLIENT; // 'client'
REALM_MASTER_NAME; // 'master'
ROLE_ADMIN_NAME; // 'admin'

PermissionName lists the built-in permissions the server provisions; ScopeName the built-in scopes (global, openid, email, roles, identity).

Validators

Each writable entity has a validator, a validup container. run() returns the validated and normalized data, or throws a ValidupError listing the issues:

import { RoleValidator } from '@authup/core-kit';
import { ValidatorGroup } from '@authup/kit';

const validator = new RoleValidator();
const data = await validator.run(
    { name: '  Editor ', description: 'Edits content' },
    { group: ValidatorGroup.CREATE },
);
// data.name === 'editor'

• The group decides which fields are mounted. CREATE mounts identifiers such as name and realmId; UPDATE does not mount realmId, so a realm cannot change after creation. ValidatorGroup comes from @authup/kit.
• Fields a group does not mount are stripped from the output, not rejected.
• Names are canonicalized: name is trimmed and lower-cased before the format check, so mixed case is accepted and stored lower case.

Name checks

import { isNameValid, isUserNameValid } from '@authup/core-kit';

isNameValid('my-app_1'); // true
isNameValid('My App'); // false
isNameValid('My App', { throwOnFailure: true }); // throws
isUserNameValid('alice');

isNameValid accepts [a-z0-9-_.] only. Each entity adds its own variant (isRoleNameValid, isClientNameValid, isRealmNameValid, ...) with its own reserved names and length bounds.

API

The barrel exports one family per entity. Each family carries the entity type and, where the entity is writable, a validator, a name check and its constants.

The full reference is at authup.org.

Notes

• Types describe the API shape, not the database. Fields the server never returns (a password, a secret in hashed mode) may still appear on the type as optional or nullable.
• EntityTypeMap is not every EntityType. A few types (the identity-provider attribute and permission mappings, the user authenticator) have no entry, since no flat entity API serves them.

License

Made with 💚

Published under the Apache 2.0 License.