context

Purpose

Defines the AuthContext Zod schema representing the authenticated caller's identity as it flows through a request lifecycle. After a server middleware validates the incoming access token, it extracts the user's identifier, email, roles, and optional tenant identifier into an AuthContext object. This schema ensures that the shape of that context is validated on construction and typed consistently across every server plugin, middleware, and service function that consumes it.

Features

AuthContext schema — {userId, email, roles, tenantId?} with strict Zod validation
roles as a typed string[] — supports role-based access control checks without custom parsing
Optional tenantId for multi-tenant deployments — present only when the tenant scope is known
Non-empty validation on all string fields to prevent blank identity tokens
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { AuthContext } from "@suaveplan/api-schemas/auth";

// Validate the decoded JWT claims after signature verification
const ctx = AuthContext.parse({
  userId: "user_01J8ZGCZ7ECTFAKEUID123456",
  email: "alice@example.com",
  roles: ["member"],
});

Usage: Advanced Example

import { AuthContext } from "@suaveplan/api-schemas/auth";

// Middleware that builds the AuthContext from a validated JWT
function buildAuthContext(claims: JwtClaims): AuthContext {
  return AuthContext.parse({
    userId: claims.sub,
    email: claims.email,
    roles: claims.roles ?? [],
    tenantId: claims.tenant_id,
  });
}

// RBAC helper using the context
function requireRole(ctx: AuthContext, role: string): void {
  if (!ctx.roles.includes(role)) {
    throw new Error("Forbidden");
  }
}

API Reference

`AuthContext`

Zod object schema — authenticated request context.

Field	Type	Description
`userId`	`string` (min 1)	Unique identifier of the authenticated user
`email`	`string` (email)	Email address of the authenticated user
`roles`	`string[]`	Role identifiers for RBAC checks
`tenantId`	`string` (optional)	Tenant scope for multi-tenant deployments

Type export: type AuthContext = z.infer<typeof AuthContext>

Implementation Notes

AuthContext does not include the raw token or session identifier intentionally — the context represents decoded, validated identity, not the credential itself. Services that need to revoke or refresh tokens should do so through a separate token store, not through the auth context. The roles array is left as a plain string[] to remain agnostic about whether roles are stored as flat strings, hierarchical paths, or RBAC/ABAC expressions; the data layer is responsible for populating it correctly.

3.0 KiB Raw Permalink Blame History