Users

​

Why this package

• One identity shape. Every part of the stack — auth, roles, permissions, controllers — speaks the same IUser interface, so a user resolved in one place is usable everywhere.
• Provider-agnostic. The model is independent of how you authenticate. A Clerk, JWT, or credentials backend maps its own user into IUser; downstream code never sees the provider.
• Zero runtime. Pure type/interface/enum definitions. Importing it adds nothing to your bundle and forces no storage decisions.
• Audit-aware. Sessions, accounts, verifications, and profile updates each have a dedicated interface with timestamps and status, so security trails are modeled, not improvised.
• Roles are first-class. roles is a required field of uppercase strings, the same convention roles and route guards expect.

​

How it works

export type ContextType<T extends ContextConfigType = ContextConfigType> = {
  // ...
  user: IUser | null;
  permission?: IPermission;
};

​

The IUser interface

​

Inherited IBase fields

​

Related identity interfaces

• ISession — an authentication session: token, optional refreshToken, device and location metadata (userAgent, ipAddress, deviceType, browser, operatingSystem, location), isActive, expiresAt, and revocation fields (revokedAt, revokedReason). See JWT for how tokens are minted and validated.
• IAccount — a linked credential or provider: type (an EAccountType), a hashed password for credentials accounts, OAuth fields (provider, providerAccountId, accessToken, refreshToken, scope, idToken), and provider profile data.
• IVerification — a verification challenge: token, type (an EVerificationType), optional code, isUsed, expiresAt, and attemptsCount / maxAttempts for rate limiting.

​

Enums

​

Resolving a user in auth middleware

import type { IUser } from "@ooneex/user";

const user: IUser = {
  id: providerUser.privateMetadata?.externalId as string,
  externalId: providerUser.id,
  email: primaryEmail.emailAddress,
  roles: (providerUser.privateMetadata?.roles as Uppercase<string>[]) ?? ["ROLE_USER"],
};

if (providerUser.firstName) user.firstName = providerUser.firstName;
if (providerUser.lastName) user.lastName = providerUser.lastName;
if (providerUser.imageUrl) user.avatar = providerUser.imageUrl;

context.user = user; // resolved once; reused for the rest of the request

​

Using the resolved user

import type { ContextType } from "@ooneex/controller";

public async index(context: ContextType) {
  const user = context.user;

  if (!user) {
    return context.response.exception("Authentication required", { status: 401 });
  }

  return context.response.json({ email: user.email, roles: user.roles });
}

public setUserPermissions(context: ContextType): this {
  const user = context.user;

  if (user?.roles.includes("ROLE_ADMIN")) {
    this.allow().to("manage", "all");
  } else if (user) {
    this.allow().to("read", "Article");
  }

  return this;
}

​

Best practices

• Never store plaintext passwords. IAccount.password is the hashed credential; hash on write and compare hashes on login. Treat twoFactorSecret and recoveryTokens as secrets too — encrypt at rest, never serialize to clients.
• Resolve once, reuse everywhere. Validate the token and build IUser in auth middleware, set context.user, and read it downstream. Don’t re-decode tokens in controllers or permissions.
• Keep the identity model minimal. Populate only the fields you have. Optional fields exist for richer profiles, not as a checklist to fill.
• Always handle null. The context types the user as IUser | null; branch on it explicitly so guest routes are intentional, not accidental.
• Expose a safe view. When returning a user over the wire, project to the public fields — never send credentials, secrets, sessions, or verification tokens.
• Trust roles, not ad-hoc flags. Authorize against the roles array via roles and permissions rather than inventing per-controller checks.