@carecard/jwt-read 3.1.15 → 3.1.16

package/.agents/skills/carecard-workspace-standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: carecard-workspace-standards
-description: Follow the shared SO_CareCardCa/CareCard workspace coding, testing, repository, dependency, shared package, frontend, database, API response, and security standards. Use before modifying, testing, reviewing, or debugging any api-*, pkg-*, app-*, website, dashboard, or other CareCard repository in this workspace, especially when choosing validation commands, package boundaries, TypeScript types, dependencies, API contracts, database logic, service patterns, or frontend architecture.
+description: Follow the shared SO_CareCardCa/CareCard workspace coding, testing, repository, dependency, shared package, frontend, database, API response, and security standards. Use before modifying, testing, reviewing, or debugging any ms-*, pkg-*, app-*, website, dashboard, or other CareCard repository in this workspace, especially when choosing validation commands, package boundaries, TypeScript types, dependencies, API contracts, database logic, service patterns, or frontend architecture.
 ---
 
 # CareCard Workspace Standards
@@ -23,7 +23,7 @@ Use before modifying, testing, reviewing, or debugging any CareCard workspace re
 
 - `.agents/config.toml`
 - `.agents/skills`
-- `api-*` services
+- `ms-*` services
 - `pkg-*` packages
 - `app-*` frontends
 - `.husky` and `.junie` validation guidance
@@ -52,7 +52,7 @@ Use before modifying, testing, reviewing, or debugging any CareCard workspace re
 
 Treat `/Users/pankajpriscilla/SO_CareCardCa` as a collection of independent Git
 repositories, not as one monorepo. Work from the specific child repository
-being changed. Each `api-*`, `pkg-*`, and `app-*` directory has its own package
+being changed. Each `ms-*`, `pkg-*`, and `app-*` directory has its own package
 scripts, Git status, test commands, style, naming, structure, test framework,
 and Husky hooks.
 
@@ -183,11 +183,11 @@ build artifacts, logs, or `.DS_Store`.
   `notFound404`, `appErrorHandler`, error throw helpers, case converters, and
   `ApiErrorType`.
 - Do not create or maintain duplicated common response or error helpers inside
-  each `api-*` service.
+  each `ms-*` service.
 - Keep service-local response code limited to service-specific mapping or
   wiring.
 - Add broadly useful shared functionality to the relevant `pkg-*` package
-  instead of duplicating it locally in an `api-*` or `app-*` project.
+  instead of duplicating it locally in an `ms-*` or `app-*` project.
 - When changing a `pkg-*` package, write package tests first, increase that
   package's minor version in `package.json`, run `npm install` in the package,
   update consuming projects to the new package version, run `npm install` in
@@ -206,10 +206,10 @@ build artifacts, logs, or `.DS_Store`.
 
 ## Backend Microservices
 
-Most JavaScript `api-*` services use CommonJS, Mocha, Supertest, Docker Compose
+Most JavaScript `ms-*` services use CommonJS, Mocha, Supertest, Docker Compose
 database tests, `@carecard/*` packages, and `sub-apps`
-controller/router/model patterns. TypeScript services such as `api-contact-us`
-and `api-template-ts` use Jest or TypeScript tooling and should keep their
+controller/router/model patterns. TypeScript services such as `ms-contact-us`
+and `ms-template-ts` use Jest or TypeScript tooling and should keep their
 existing TypeScript style.
 
 - Keep environment-specific files explicit: `.env.development`, `.env.test`,
@@ -283,9 +283,9 @@ existing TypeScript style.
 - Keep tests readable and domain-specific.
 - Tests must cover desired or happy paths and prevention or rejection of
   undesired behavior.
-- JavaScript `api-*` services usually use Mocha, Supertest,
+- JavaScript `ms-*` services usually use Mocha, Supertest,
   `test/index.test.js`, and Docker-backed PostgreSQL scripts.
-- TypeScript `api-*` services usually use Jest and `tests/index.test.ts`.
+- TypeScript `ms-*` services usually use Jest and `tests/index.test.ts`.
 - `pkg-*` packages usually use Mocha plus TypeScript type tests where present.
 - `app-dashboard` uses Vitest, React Testing Library, mock API tests, and
   Selenium for end-to-end flows.
@@ -306,8 +306,8 @@ existing TypeScript style.
 ## Dashboard Frontend
 
 `app-dashboard` is a Next.js App Router TypeScript app using MUI, React Query,
-`next-intl`, and shared CareCard utilities. It consumes `api-auth`,
-`api-institutions`, `api-contact-us`, and `api-user-profiles` through service
+`next-intl`, and shared CareCard utilities. It consumes `ms-auth`,
+`ms-institutions`, `ms-contact-us`, and `ms-user-profiles` through service
 modules.
 
 - Keep backend URL definitions centralized in `src/services/api.routes.ts`.
@@ -366,12 +366,34 @@ the authenticated dashboard.
 - Keep CareCard package usage consistent with the service or app being changed.
 - When standardizing response or error behavior, prefer `@carecard/common-util`
   `3.1.15` because it contains response and error functions aligned with
-  `api-auth`.
+  `ms-auth`.
 - If package version changes are required, update lockfiles and verify affected
   services or apps.
 - Avoid broad dependency upgrades as part of feature or refactor work unless
   the task is specifically about dependencies.
 
+## Auth Service RLS Contract
+
+- `ms-auth` follows the shared PostgreSQL/RLS pattern from `ms-template-js`: auth tables live in the `carecard` schema, RLS is enabled and forced on every auth table, and application runtime queries use the unprivileged database role.
+- Auth table policies allow normal JWT or server-auth users to access only
+  self-owned rows. Do not add redundant `user_id = <jwt sub>` SQL predicates to
+  duplicate self-row checks when RLS owns the authorization decision.
+- A JWT or server-auth payload containing `roles: ["ad"]` is the auth-service
+  super-admin signal and can perform any action on auth tables. Dashboard code
+  may map that role to `super_admin`, but backend auth RLS must not require a
+  separate database role row for that bypass.
+- Public auth flows such as registration, login, server-auth session create and
+  introspection, confirmation, recovery, visitor creation, and service user
+  lookup must use narrow system contexts (`system_create`, `system_login`,
+  `system_confirm`, `system_recovery`, `system_visitor`, `system_service`)
+  instead of privileged runtime queries.
+
+- `ms-auth` controller exports use concise action names such as `loginUser`,
+  `registerUser`, `getUserDetail`, and `renewJwt`; route middleware and router
+  placement express whether a flow is public, authenticated, admin-only, or
+  service-only, so avoid `public`, `protected`, `admin`, or `Handler` suffixes
+  in new controller names.
+
 ## Security Requirements
 
 - Treat authentication, authorization, JWT, password, email confirmation,

package/.agents/skills/pkg-jwt-read-jwt-middleware-library/SKILL.md

@@ -7,11 +7,13 @@ description: Use when changing pkg-jwt-read JWT parsing, middleware, visitor tok
 
 ## Purpose
 
-CareCard JWT read package for parsing, request attachment, visitor tokens, role mapping, authorization middleware, exports, and tests.
+CareCard JWT read package for parsing, request attachment, visitor tokens, role mapping, JWT-or-server-auth authorization middleware, exports, and tests.
 
 ## When To Use
 
-- Use when changing pkg-jwt-read JWT parsing, middleware, visitor tokens, role checks, auth context, package exports, or tests.
+- Use when changing pkg-jwt-read JWT parsing, server-auth introspection
+  middleware, visitor tokens, role checks, auth context, package exports, or
+  tests.
 - Pair with `carecard-workspace-standards` when the task affects shared CareCard conventions or cross-repository contracts.
 
 ## When Not To Use
@@ -53,7 +55,9 @@ CareCard JWT read package for parsing, request attachment, visitor tokens, role
 Use this skill when working inside `pkg-jwt-read`, the `@carecard/jwt-read`
 package. It provides utilities for reading, parsing, verifying, and attaching
 JWT data in the CareCard ecosystem. It depends on `@carecard/auth-util` for
-low-level cryptographic operations.
+low-level cryptographic operations. It also exposes middleware helpers that
+allow `ms-*` services to accept either an `ms-auth` JWT or an opaque server-auth
+token introspected by `ms-auth`.
 
 Use `$carecard-workspace-standards` for shared workspace, dependency, package,
 testing, and security rules. Legacy `pkg-jwt-read/.codex` and
@@ -95,9 +99,14 @@ depend on those folders being present.
 - Middleware-like functions for Express, such as `verifyJwtAndRole`.
 - Service-to-service JWT verification and extraction helpers:
   `jwtValidateAndExtractService` and `jwtVerifyService`.
+- JWT-or-server-auth helpers: `jwtValidateAndExtractOrServerAuth`,
+  `jwtVerifyOrServerAuth`, and `jwtVerifyOrServerAuthAndHasRole`.
 - Extraction of `sub`/clientId and other claims from JWT objects.
 - Expiration checks and TTL calculations.
 - Request attachment behavior for authenticated JWT objects and visitor tokens.
+- Server-auth request attachment behavior that normalizes introspected claims
+  into `req.jwt.payload` with `authMode: "server-auth"` and
+  `auth_mode: "server-auth"`.
 - Integration with `@carecard/common-util` for standardized login and
   authorization errors.
 
@@ -108,6 +117,11 @@ JWT creation functions do not belong in this package. Service-to-service token
 creation belongs in `@carecard/auth-util` via `jwtCreateServiceToken` and
 `jwtCreateServiceAuthorizationHeader`.
 
+Opaque server-auth token creation, hashing, persistence, and introspection
+belong in `ms-auth`. This package only accepts a caller-provided introspector
+function and normalizes valid introspection claims into the existing request
+JWT context.
+
 Service JWTs must follow standard JWT claim semantics. They use `iss` for the
 sending service, `sub` for the sending service identity, `aud` for the
 receiving service, and NumericDate `iat`, `exp`, and optional `nbf` claims.
@@ -126,6 +140,10 @@ role names, such as `ad` and `admin`.
   by focused tests.
 - Preserve existing role semantics unless a task explicitly changes
   authorization behavior.
+- Preserve the original JWT `roles` array on request context. `ms-auth` RLS
+  treats a payload containing `ad` as the auth-service super-admin signal;
+  dashboard code may map that to `super_admin`, but middleware must not hide,
+  rename, or drop the raw role payload needed by backend database contexts.
 
 ## NoThrow And Error Behavior
 
@@ -141,17 +159,20 @@ role names, such as `ad` and `admin`.
 
 ## Security Rules
 
-- Treat JWT parsing, signature verification, visitor tokens, authorization
-  roles, and request context as security-sensitive.
+- Treat JWT parsing, signature verification, server-auth introspection,
+  visitor tokens, authorization roles, and request context as
+  security-sensitive.
 - Do not log JWTs, token fragments, public/private keys, decoded payloads,
   authorization headers, visitor headers, or sensitive request data.
-- Keep missing headers, invalid signatures, expired tokens, role failures, and
-  used-token errors behaviorally distinct where existing APIs do so.
+- Keep missing headers, invalid signatures, expired tokens, revoked or invalid
+  server-auth tokens, role failures, and used-token errors behaviorally
+  distinct where existing APIs do so.
 
 ## Types And API Contracts
 
-- Model JWT header, payload, request attachment, visitor attachment, role, and
-  context shapes explicitly in `index.d.ts`.
+- Model JWT header, payload, server-auth introspection claims, request
+  attachment, visitor attachment, role, and context shapes explicitly in
+  `index.d.ts`.
 - Prefer `AuthenticatedRequest`, `JwtHeader`, `JwtPayload`, `JwtParts`,
   `JwtRequestObject`, `VisitorRequestObject`, and `JwtContext` over loose
   request objects.
@@ -171,7 +192,8 @@ role names, such as `ad` and `admin`.
 - `test/types.test.ts` verifies TypeScript declarations with `tsc`.
 - Add focused tests for valid JWTs, invalid JWTs, missing headers, role checks,
   visitor token extraction, expiration behavior, request attachment behavior,
-  NoThrow behavior, and context-bound helpers when those areas change.
+  server-auth introspection success/failure, NoThrow behavior, and
+  context-bound helpers when those areas change.
 - Set `NODE_ENV=test` where tests or scripts require it.
 - Keep tests deterministic and avoid real external services.
 

package/index.d.ts

@@ -32,6 +32,10 @@ export interface JwtPayload {
   sub?: string;
   /** Roles assigned to the user. */
   roles?: string[];
+  /** Authentication mode used by app-facing services. */
+  authMode?: 'jwt' | 'server-auth' | string;
+  /** Server-auth session identifier when an opaque server-auth token was used. */
+  sessionId?: string;
   /** Any other custom payload fields. */
   [key: string]: any;
 }
@@ -76,6 +80,30 @@ export interface AuthenticatedRequest extends Request {
   visitor?: VisitorRequestObject | null;
 }
 
+export interface ServerAuthIntrospectionClaims {
+  valid?: boolean;
+  sub?: string;
+  userId?: string;
+  user_id?: string;
+  email?: string;
+  emailVerified?: boolean;
+  email_verified?: boolean;
+  emailConfirmed?: boolean;
+  email_confirmed?: boolean;
+  roles?: string[];
+  sessionId?: string;
+  session_id?: string;
+  exp?: number | string;
+  expiresAt?: string;
+  expires_at?: string;
+  [key: string]: any;
+}
+
+export type ServerAuthIntrospector = (
+  token: string,
+  req: AuthenticatedRequest,
+) => Promise<ServerAuthIntrospectionClaims> | ServerAuthIntrospectionClaims;
+
 /**
  * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
  * and extracts it into req.jwt. Throws an error if invalid.
@@ -147,6 +175,27 @@ export function jwtVerifyAndHasRole(
   customErrorFunction?: () => void,
 ): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
 
+/**
+ * Returns middleware that accepts either an ms-auth JWT or an opaque server-auth token.
+ * Server-auth tokens are validated by the supplied introspector on every request.
+ */
+export function jwtVerifyOrServerAuth(
+  publicKey: string,
+  serverAuthIntrospector: ServerAuthIntrospector,
+  customErrorFunction?: () => void,
+): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
+/**
+ * Returns middleware that accepts either an ms-auth JWT or server-auth token and
+ * then checks that the authenticated user has the required role.
+ */
+export function jwtVerifyOrServerAuthAndHasRole(
+  userRole: string,
+  publicKey: string,
+  serverAuthIntrospector: ServerAuthIntrospector,
+  customErrorFunction?: () => void,
+): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
 /**
  * Gets the full name of a role from its code (e.g., 'ad' -> 'admin').
  */
@@ -189,6 +238,17 @@ export function jwtValidateAndExtractService(
   customErrorFunction?: () => void,
 ): void;
 
+/**
+ * Validates the Authorization header as either an ms-auth JWT or an opaque
+ * server-auth token and extracts the result into req.jwt.
+ */
+export function jwtValidateAndExtractOrServerAuth(
+  req: AuthenticatedRequest,
+  publicKey: string,
+  serverAuthIntrospector: ServerAuthIntrospector,
+  customErrorFunction?: () => void,
+): Promise<void>;
+
 /**
  * Validates the JWT from a custom header and extracts it into req.jwt.
  */

package/index.js

@@ -17,11 +17,14 @@ module.exports = {
   jwtGetContext: jwtRoles.getContext,
   jwtValidateAndExtract: jwtLib.validateAndExtractJwtObject,
   jwtValidateAndExtractService: jwtLib.validateAndExtractServiceJwtObject,
+  jwtValidateAndExtractOrServerAuth: jwtLib.validateAndExtractJwtOrServerAuthObject,
   jwtValidateAndExtractWebToken: jwtLib.validateAndExtractWebToken,
   jwtValidateAndExtractNoThrow: jwtLib.validateAndExtractJwtObjectNoThrow,
   jwtValidateAndExtractWebTokenNoThrow: jwtLib.validateAndExtractWebTokenObjectNoThrow,
   jwtValidateAndExtractVisitorNoThrow: jwtLib.validateAndExtractVisitorObjectNoThrow,
   jwtVerifyService: jwtLib.verifyServiceJwt,
+  jwtVerifyOrServerAuth: jwtLib.verifyJwtOrServerAuth,
+  jwtVerifyOrServerAuthAndHasRole: jwtLib.verifyJwtOrServerAuthAndHasRole,
 
   /** @deprecated use jwtVerify */
   verifyJwt: jwtLib.verifyJwt,

package/lib/jwtLib.js

@@ -122,6 +122,15 @@ function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expe
   return req;
 }
 
+async function validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction) {
+  if (tryValidateAndExtractJwtObject(req, publicKey)) return req;
+
+  const serverAuthToken = _validateServerAuthToken(req, customErrorFunction);
+  const claims = await introspectServerAuthToken(serverAuthIntrospector, serverAuthToken, req, customErrorFunction);
+  attachServerAuthClaims(req, claims, customErrorFunction);
+  return req;
+}
+
 function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName) {
   return _validateAndExtractGenericNoThrow(req, publicKey, r => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, 'jwt');
 }
@@ -165,6 +174,30 @@ function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErr
   };
 }
 
+function verifyJwtOrServerAuth(publicKey, serverAuthIntrospector, customErrorFunction) {
+  return async function (req, res, next) {
+    try {
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+function verifyJwtOrServerAuthAndHasRole(role, publicKey, serverAuthIntrospector, customErrorFunction) {
+  return async function (req, res, next) {
+    try {
+      await validateAndExtractJwtOrServerAuthObject(req, publicKey, serverAuthIntrospector, customErrorFunction);
+      const isRoleExist = doesJwtUserHasRole(req, role);
+      _isLoginRequired(isRoleExist, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
 function verifyWebToken(publicKey, headerName, customErrorFunction) {
   return function (req, res, next) {
     try {
@@ -222,6 +255,80 @@ function _isLoginRequired(hasRequiredRole, customErrorFunction) {
   }
 }
 
+function tryValidateAndExtractJwtObject(req, publicKey) {
+  const jwtString = _validateJwtNoThrow(req);
+  if (!jwtString || !isJwtString(jwtString)) return false;
+
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+  if (!isJwtSignatureValid) {
+    if (req) req.jwt = null;
+    return false;
+  }
+
+  _extractJwtObjectNoThrow(req, jwtString);
+  return Boolean(req?.jwt);
+}
+
+function _validateServerAuthToken(req, customErrorFunction) {
+  const authorizationHeader = req?.get?.('Authorization') || req?.get?.('authorization');
+  const token = _extractJwtNoThrow(authorizationHeader);
+  if (token) return token;
+
+  throwError(customErrorFunction);
+  return null;
+}
+
+async function introspectServerAuthToken(serverAuthIntrospector, token, req, customErrorFunction) {
+  if (typeof serverAuthIntrospector !== 'function') {
+    throwError(customErrorFunction);
+  }
+
+  const claims = await serverAuthIntrospector(token, req);
+  if (!claims || claims.valid === false) {
+    throwError(customErrorFunction);
+  }
+
+  return claims;
+}
+
+function attachServerAuthClaims(req, claims, customErrorFunction) {
+  const payload = createServerAuthPayload(claims);
+  if (!payload.sub) {
+    if (req) req.jwt = null;
+    throwError(customErrorFunction);
+  }
+
+  req.jwt = {
+    header: {
+      alg: 'opaque',
+      typ: 'ServerAuth',
+    },
+    payload,
+  };
+  _attachJwtMethods(req.jwt);
+}
+
+function createServerAuthPayload(claims) {
+  return {
+    sub: claims.sub || claims.userId || claims.user_id,
+    email: claims.email || '',
+    email_verified: claims.emailVerified || claims.email_verified || claims.emailConfirmed || claims.email_confirmed || false,
+    roles: Array.isArray(claims.roles) ? claims.roles : [],
+    authMode: 'server-auth',
+    auth_mode: 'server-auth',
+    sessionId: claims.sessionId || claims.session_id,
+    session_id: claims.session_id || claims.sessionId,
+    exp: readEpochSeconds(claims.exp || claims.expiresAt || claims.expires_at),
+  };
+}
+
+function readEpochSeconds(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value === 'number') return normalizeSeconds(value);
+  const millis = Date.parse(value);
+  return Number.isFinite(millis) ? Math.floor(millis / 1000) : undefined;
+}
+
 function normalizeSeconds(value) {
   if (!Number.isFinite(value)) return null;
   return value > 1000000000000 ? Math.floor(value / 1000) : Math.floor(value);
@@ -434,6 +541,7 @@ module.exports = {
   _extractJwtObject,
   validateAndExtractJwtObject,
   validateAndExtractServiceJwtObject,
+  validateAndExtractJwtOrServerAuthObject,
   validateAndExtractWebToken,
   jwtAgeInSeconds,
   isJwtExpired,
@@ -442,6 +550,8 @@ module.exports = {
   visitorClientId,
   verifyJwtAndRole,
   verifyServiceJwt,
+  verifyJwtOrServerAuth,
+  verifyJwtOrServerAuthAndHasRole,
   verifyJwt,
   verifyWebTokenNoThrow,
   verifyWebToken,
@@ -461,6 +571,9 @@ module.exports = {
   _extractVisitorObjectNoThrow,
   _extractWebToken,
   _isLoginRequired,
+  tryValidateAndExtractJwtObject,
+  attachServerAuthClaims,
+  createServerAuthPayload,
   _isServiceJwtFor,
   _attachJwtMethods,
   _attachVisitorMethods,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/jwt-read",
-  "version": "3.1.15",
+  "version": "3.1.16",
   "repository": {
     "type": "git",
     "url": "https://github.com/CareCard-ca/pkg-jwt-read.git"

package/readme.md

@@ -3,7 +3,10 @@
 ![Tests Passing](https://github.com/CareCard-ca/pkg-jwt-read/actions/workflows/ci.yml/badge.svg)
 ![Coverage](https://img.shields.io/badge/Coverage-80%25-orange)
 
-Utility package for reading, parsing, and verifying JWTs in the CareCard ecosystem.
+Utility package for reading, parsing, and verifying JWTs in the CareCard
+ecosystem. It also provides the shared request middleware used by `ms-*`
+services to accept either an `ms-auth` JWT or an opaque server-auth token
+introspected by `ms-auth`.
 
 ## Features
 
@@ -13,6 +16,8 @@ Utility package for reading, parsing, and verifying JWTs in the CareCard ecosyst
 - **Claims Extraction**: Easy extraction of `sub` (clientId) and other JWT payload claims.
 - **Expiration Management**: Helpers to check if a JWT is expired and calculate its remaining TTL.
 - **Service JWTs**: Helpers for verifying and extracting microservice-to-microservice JWTs with standard `iss`, `sub`, `aud`, `iat`, and `exp` claims.
+- **JWT or Server Auth**: Middleware helpers that verify normal JWTs locally and
+  call a service-provided introspector for opaque server-auth tokens.
 
 ## Installation
 
@@ -60,6 +65,19 @@ console.log(getNameOfRole('ad')); // Result: 'admin'
 console.log(getCodeOfRole('super_admin')); // Result: 'su'
 ```
 
+### Auth RLS Role Semantics
+
+`ms-auth` treats a JWT or server-auth payload containing `roles: ["ad"]` as the
+auth-service super-admin signal for its RLS policies. Consumers may map `ad` to
+UI/domain names such as `super_admin`, but middleware should preserve the
+original roles array on the request context so services can make
+database-context decisions consistently.
+
+Docs that mention `ms-auth` controller internals should use concise action
+names such as `loginUser`, `registerUser`, `getUserDetail`, and `renewJwt`.
+Access level is conveyed by route middleware and endpoint placement, not by
+`public`/`protected`/`admin`/`Handler` suffixes.
+
 ### Service-To-Service JWTs
 
 Use service JWT verification helpers for backend service calls. The sending
@@ -88,6 +106,33 @@ Service JWT payloads follow standard JWT semantics:
 - `iat`: issued-at NumericDate
 - `exp`: expiration NumericDate
 
+### JWT Or Server-Auth Middleware
+
+Use the `OrServerAuth` helpers on app-facing `ms-*` routes that should accept
+both current authentication modes. The JWT path verifies locally with the
+`ms-auth` public key. The server-auth path calls the provided introspector,
+which should send the opaque token to
+`POST /api/v1/ms-auth/server-auth/introspect` with the receiving service's
+service JWT.
+
+```javascript
+const { jwtGetRoleCode, jwtVerifyOrServerAuth, jwtVerifyOrServerAuthAndHasRole } = require('@carecard/jwt-read');
+
+const verifyUser = jwtVerifyOrServerAuth(msAuthPublicKey, token => introspectServerAuthTokenWithMsAuth(token), throwNotAuthorizedError);
+
+const verifyAdmin = jwtVerifyOrServerAuthAndHasRole(
+  jwtGetRoleCode('admin'),
+  msAuthPublicKey,
+  token => introspectServerAuthTokenWithMsAuth(token),
+  throwNotAuthorizedError,
+);
+```
+
+The introspector must return claims for valid tokens. This package normalizes
+those claims onto `req.jwt.payload` with `authMode: "server-auth"` and
+`auth_mode: "server-auth"` so services can keep their existing JWT-backed
+database context and role checks.
+
 ## Testing
 
 Run tests using: