@carecard/jwt-read 3.1.14 → 3.1.15

package/.agents/skills/github-pr-merge-cleanup/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: github-pr-merge-cleanup
+description: Use only when the user explicitly asks for remote Git or GitHub PR work: reviewing remote mergeability, validating, merging, closing, deleting, or cleaning up a pull request branch.
+---
+
+# Pull Request Merge Close
+
+## Purpose
+
+Only after the user explicitly asks for remote Git or GitHub PR work, review, validate, merge, close, delete branch, and clean local state for a GitHub pull request targeting origin/development.
+
+## When To Use
+
+- Use only when the user explicitly asks to review mergeability, validate, merge, close, or clean up a GitHub pull request branch.
+
+## When Not To Use
+
+- Do not use for creating a new pull request; use the PR create/update skill.
+- Do not use when the user only asks for local code changes without PR merge work.
+
+## Remote Git Operations Guardrail
+
+Do not run remote Git or GitHub operations unless the current user request explicitly asks for that remote operation. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would be useful but was not requested.
+
+## Relevant Files And Directories
+
+- Git branch state in this repository
+- GitHub pull requests viewed with `gh`
+- repository validation commands and `.husky` scripts
+
+## Coding Principles
+
+- Preserve the repository structure, naming style, module system, and local helper patterns.
+- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
+- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
+
+## Testing Expectations
+
+- Run repository validation before PR creation or merge when code behavior changed.
+- Confirm the branch is clean except intended changes before finishing.
+
+## Safety Constraints
+
+- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task explicitly requires it.
+- Do not revert or overwrite user changes; stage only files related to the requested skill or instruction update.
+- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
+
+## Commit Continuation Rule
+
+Do not amend existing commits unless the user explicitly asks for an amend. If
+hook, formatter, documentation, skill, validation, or review follow-up changes
+appear after a commit, stage only the intended files and make a new commit with
+a clear message.
+
+## Scope
+
+Use this skill from the root of the repository that owns the pull request. The
+repository must use GitHub CLI, have a remote base branch, and have the target
+branch available locally or on `origin`.
+
+Default terms:
+
+- Base branch: `development` when `origin/development` exists, otherwise the
+  repository default branch.
+- Target branch: the current branch unless the user names another branch.
+- Pull request: the open PR whose head is the target branch and whose base is
+  the base branch.
+
+Do not continue automatically when:
+
+- `gh auth status` fails.
+- The target branch is detached or is the base branch.
+- The working tree has uncommitted changes that are not part of the requested
+  PR cleanup.
+- No open PR exists for the target branch.
+- A rebase or validation fix would require behavior changes instead of coding
+  criteria cleanup.
+
+## Workflow
+
+1. Capture the base branch, target branch, PR number, and protection state:
+
+   ```sh
+   gh auth status
+   base="development"
+   git ls-remote --exit-code --heads origin development >/dev/null 2>&1 || \
+     base="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
+   target_branch="$(git branch --show-current)"
+   test -n "$target_branch"
+   test "$target_branch" != "$base"
+   git status --short
+   git fetch origin "$base" --prune
+   pr_number="$(gh pr list --head "$target_branch" --base "$base" --state open --json number --jq '.[0].number // empty')"
+   test -n "$pr_number"
+   protected="$(gh api "repos/{owner}/{repo}/branches/$target_branch" --jq '.protected' 2>/dev/null || echo false)"
+   ```
+
+   If the PR head branch is not local, create a local branch from the remote
+   head before continuing.
+
+2. Check mergeability before changing history:
+
+   ```sh
+   gh pr view "$pr_number" --json mergeStateStatus,mergeable,headRefName,baseRefName
+   if git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-merge-tree.out
+   then
+     merge_conflict_detected=false
+   else
+     merge_conflict_detected=true
+   fi
+   ```
+
+3. If a merge conflict is detected, rebase the target branch on the fresh base
+   branch. Abort and stop if the rebase conflicts:
+
+   ```sh
+   if [ "$merge_conflict_detected" = true ]; then
+     if git rebase "origin/$base"; then
+       git push --force-with-lease -u origin "$target_branch"
+     else
+       git rebase --abort
+       echo "Rebase conflicted; aborted without merging."
+       exit 1
+     fi
+   fi
+   ```
+
+   Do not resolve rebase conflicts unless the user explicitly asks.
+
+4. Load and apply all relevant repository skills before merging:
+   - Read the repository's `.agents/skills/**/SKILL.md` files that apply to the
+     changed code, plus shared workspace standards when present.
+   - Compare the target branch against the base with
+     `git diff --stat "origin/$base...HEAD"` and inspect changed files.
+   - Check whether the target branch satisfies the applicable coding,
+     architecture, validation, security, and style criteria from those skills.
+   - Run the validation commands required by the skills and repository hooks.
+   - If criteria are not met and the fix does not change functionality, make the
+     minimal cleanup, stage only intended files, commit to the target branch,
+     and push the target branch.
+   - If meeting the criteria would change behavior, stop and report the gap.
+
+5. Confirm the PR is still mergeable after validation changes:
+
+   ```sh
+   git fetch origin "$base" --prune
+   git merge-tree --write-tree HEAD "origin/$base" >/tmp/pull-request-merge-close-final-merge-tree.out
+   gh pr checks "$pr_number"
+   ```
+
+6. Merge the PR with GitHub CLI. Delete the remote target branch only when it is
+   not protected:
+
+   ```sh
+   if [ "$protected" = true ]; then
+     gh pr merge "$pr_number" --squash --admin
+   else
+     gh pr merge "$pr_number" --squash --admin --delete-branch
+   fi
+   ```
+
+7. Clean up the local repository after merge:
+
+   ```sh
+   git fetch origin "$base" --prune
+   git switch "$base"
+   git pull --ff-only origin "$base"
+   git branch -d "$target_branch" || git branch -D "$target_branch"
+   git ls-remote --heads origin "$target_branch"
+   ```
+
+8. Final response should include the PR URL, whether a rebase was performed,
+   what validation and skill checks ran, whether any cleanup commit was added,
+   whether the remote target branch was deleted or protected, and whether local
+   development is up to date.

package/.agents/skills/github-pr-merge-cleanup/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: 'GitHub PR Merge And Cleanup'
+  short_description: 'Use only when the user explicitly asks for remote Git or GitHub PR work: merge, close, delete, or clean up a PR branch.'
+  brand_color: '#0F766E'
+  default_prompt: 'Use $github-pr-merge-cleanup when this task matches the skill scope.'

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

@@ -0,0 +1,239 @@
+---
+name: pkg-jwt-read-jwt-middleware-library
+description: Use when changing pkg-jwt-read JWT parsing, middleware, visitor tokens, role checks, auth context, package exports, or tests.
+---
+
+# Package JWT Read
+
+## Purpose
+
+CareCard JWT read package for parsing, request attachment, visitor tokens, role mapping, 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.
+- Pair with `carecard-workspace-standards` when the task affects shared CareCard conventions or cross-repository contracts.
+
+## When Not To Use
+
+- Do not use for service-local behavior that should remain inside one API or app.
+- Do not change package public APIs without updating consumers and compatibility tests.
+
+## Relevant Files And Directories
+
+- package entry files
+- `src` when present
+- `test`
+- `package.json`
+- `package-lock.json`
+- `.husky`
+
+## Coding Principles
+
+- Preserve the repository structure, naming style, module system, and local helper patterns.
+- Prefer readable, maintainable code with meaningful function, variable, file, and test names.
+- Avoid new dependencies unless the existing stack cannot reasonably solve the task and the user confirms the tradeoff.
+- Keep public exports stable and update CommonJS, ESM, TypeScript declaration, and compatibility surfaces together when present.
+
+## Testing Expectations
+
+- Write or update package tests before behavior or public API changes.
+- Include type/export compatibility tests where the package already has them.
+- Run package test, lint, type, and Husky validation commands required by the changed area.
+
+## Safety Constraints
+
+- Do not edit generated output, dependency folders, logs, coverage, dist, or build artifacts unless the task explicitly requires it.
+- Do not revert or overwrite user changes; stage only files related to the requested skill or instruction update.
+- Never suppress errors, lint failures, type failures, security failures, or failing tests; fix the underlying issue or report the blocker.
+- Do not log or expose secrets, JWTs, passwords, credentials, private keys, sensitive personal data, SQL internals, or stack traces.
+
+## Overview
+
+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.
+
+Use `$carecard-workspace-standards` for shared workspace, dependency, package,
+testing, and security rules. Legacy `pkg-jwt-read/.codex` and
+`pkg-jwt-read/.junie` guidance has been migrated into these skills; do not
+depend on those folders being present.
+
+## Non-Negotiable Rules
+
+- Never use TypeScript type `any`. Use specific JWT, Express, request, payload,
+  header, role, generic, or `unknown` types with narrowing.
+- Follow this repository's coding style, naming conventions, and CommonJS
+  project structure.
+- Use Test-Driven Development: add or update relevant Mocha or type tests before
+  changing behavior.
+- Never suppress errors, linter warnings, TypeScript errors, or failing tests.
+  Handle the underlying issue.
+- Do not add dependencies unless absolutely needed. Ask for confirmation first
+  with the reason and tradeoff.
+- Before finalizing work, run every direct script in `.husky` and fix anything
+  they report.
+
+## Package Shape
+
+- Keep `index.js` as the centralized public export surface.
+- Keep TypeScript declarations in `index.d.ts` aligned with every public export
+  in `index.js`.
+- Keep JWT verification and request attachment behavior in `lib/jwtLib.js`.
+- Keep role code/name mapping and JWT context behavior in `lib/jwtRoles.js`.
+- Preserve the package's CommonJS module style unless the repository is
+  intentionally migrated.
+- Keep backward-compatible deprecated exports unless the user explicitly asks to
+  remove them.
+
+## JWT Verification Layer
+
+`lib/jwtLib.js` owns:
+
+- Signature verification using public keys.
+- Middleware-like functions for Express, such as `verifyJwtAndRole`.
+- Service-to-service JWT verification and extraction helpers:
+  `jwtValidateAndExtractService` and `jwtVerifyService`.
+- 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.
+- Integration with `@carecard/common-util` for standardized login and
+  authorization errors.
+
+Use `@carecard/auth-util` for JWT creation, decomposition, and signature
+verification. Do not duplicate cryptographic logic in this package.
+
+JWT creation functions do not belong in this package. Service-to-service token
+creation belongs in `@carecard/auth-util` via `jwtCreateServiceToken` and
+`jwtCreateServiceAuthorizationHeader`.
+
+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.
+Receivers must verify the signature with the sending service public key and
+must check expected issuer, audience, subject, and lifetime. Do not add
+CareCard-specific replacement claims when a registered JWT claim covers the
+same meaning.
+
+## Role Mapping Layer
+
+`lib/jwtRoles.js` owns translation between internal role codes and human-readable
+role names, such as `ad` and `admin`.
+
+- Update `lib/jwtRoles.js` when adding or changing roles.
+- Keep role code, role name, context, and authorization helper behavior covered
+  by focused tests.
+- Preserve existing role semantics unless a task explicitly changes
+  authorization behavior.
+
+## NoThrow And Error Behavior
+
+- Preserve the distinction between throwing APIs and `NoThrow` APIs.
+- `NoThrow` variants should set the attached request property to `null` for
+  invalid tokens without hiding unexpected implementation errors.
+- Use provided `throwError` and `throwUsedTokenError` patterns to keep
+  ecosystem error responses consistent.
+- Use `@carecard/common-util` error helpers for login and authorization
+  failures.
+- Keep user-facing errors safe and avoid exposing token internals or
+  verification details.
+
+## Security Rules
+
+- Treat JWT parsing, signature verification, 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.
+
+## Types And API Contracts
+
+- Model JWT header, payload, 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.
+- When existing declarations are too loose, improve them with specific types as
+  part of the touched change instead of adding new loose types.
+- Keep overloads for context-bound helpers such as `jwtIsExpired` readable and
+  covered by type tests.
+- Update `test/types.test.ts` whenever public types, exports, overloads, or
+  attached request methods change.
+
+## Tests
+
+- Use Mocha for runtime tests under `test`.
+- `lib` modules should have corresponding test files under `test`.
+- `test/attachedMethods.test.js` covers methods attached to objects or used as
+  context.
+- `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.
+- Set `NODE_ENV=test` where tests or scripts require it.
+- Keep tests deterministic and avoid real external services.
+
+## Validation
+
+Useful commands:
+
+- `npm run lint`
+- `npm run lint:fix`
+- `npm run format`
+- `npm run format:check`
+- `npm run test`
+- `npm run test:types`
+- `npm run test:coverage`
+- `npm run test:All`
+
+Before pushing or finalizing, run every direct `.husky` script. The current
+`.husky/pre-commit` runs:
+
+```bash
+npm run lint:fix
+npm run format
+npm run test:All
+```
+
+If any validation command cannot run, report the exact command, failure reason,
+and remaining risk.
+
+## Remote Git Operations Guardrail
+
+Do not run remote Git or GitHub operations unless the current user request explicitly asks for that remote operation. This includes `git fetch`, `git pull`, `git push`, `git push --delete`, remote branch cleanup, GitHub API calls, and any `gh pr` command that creates, updates, readies, merges, closes, or cleans up a pull request. Do not infer permission from branch names, validation needs, prior workflow habits, or convenience; ask first when remote state would be useful but was not requested.
+
+## Agent Guidance Git Workflow
+
+When this skill or any repository-owned `.agents` guidance changes, use the
+repository's agents-only Git workflow:
+
+1. Work from the affected repository root and confirm only intended `.agents`
+   files changed.
+2. Use `development` as the base branch when `origin/development` exists;
+   otherwise use the repository's default base branch, usually `main`.
+3. Create or update `feature/codex` from the updated remote base branch and
+   commit all the changed `.agents` guidance files there.
+4. Push `feature/codex`, create or reuse a pull request into the base branch,
+   and mark the pull request ready for review with `gh pr ready <number>`.
+5. Squash-merge with administrator privileges and delete the remote branch:
+
+   ```sh
+   gh pr merge <number> --squash --admin --delete-branch
+   ```
+
+6. After merge, update the local base branch and remove the local feature
+   branch:
+
+   ```sh
+   git fetch origin <base> --prune
+   git switch <base>
+   git pull --ff-only origin <base>
+   git branch -d feature/codex
+   git ls-remote --heads origin feature/codex
+   ```
+
+Do not commit or push `.agents` guidance changes directly from `development`
+or `main`. Do not stage unrelated files, generated output, dependency folders,
+build artifacts, logs, or `.DS_Store`.

package/.agents/skills/pkg-jwt-read-jwt-middleware-library/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Package JWT Read Middleware Library'
+  short_description: 'Use when changing pkg-jwt-read JWT parsing, middleware, visitor tokens, role checks, auth context, package exports, or tests.'
+  default_prompt: 'Use $pkg-jwt-read-jwt-middleware-library when this task matches the skill scope.'

package/.agents/skills/software-design-patterns-and-clean-code/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: software-design-patterns-and-clean-code
+description: Use every time before coding, refactoring, debugging, or reviewing in this repository, alongside all other applicable skills, to apply pragmatic software design patterns, SOLID, Clean Code, and testable architecture.
+---
+
+# Software Design Patterns And Clean Code
+
+## Purpose
+
+Use this skill with every coding, refactoring, debugging, or review task in
+this repository. It supplements repository-specific skills; follow both, and
+let the more specific skill decide file locations, framework conventions,
+validation commands, and API contracts.
+
+## Core Principles
+
+- Prefer simple, maintainable, readable implementation over clever abstraction.
+- Use Gang of Four design patterns only when they reduce real complexity,
+  improve clarity, or make behavior easier to test.
+- Follow SOLID principles, especially Single Responsibility and Dependency
+  Inversion where they improve maintainability.
+- Keep clear separation of concerns between routing, orchestration, domain
+  logic, persistence, validation, formatting, and side effects.
+- Apply DRY, KISS, and YAGNI. Remove meaningful duplication, keep solutions
+  direct, and avoid speculative generalization.
+- Favor small, composable functions with meaningful names and explicit inputs.
+- Prefer pure functions for calculations, mapping, validation, and transforms
+  when practical.
+- Keep side effects minimal, localized, and easy to identify.
+- Use explicit error handling. Do not swallow failures or hide actionable
+  error context.
+- Design code so behavior can be tested through focused unit, integration, or
+  service tests without fragile setup.
+- Avoid unnecessary dependencies. Use existing language, framework, and local
+  helper capabilities before adding packages.
+
+## Function Comments
+
+For every new or modified function, method, or exported callback, add a short
+comment immediately above it explaining the main pattern or principle being
+applied. Keep the comment accurate and specific to the function.
+
+Use the host language's normal comment syntax. Examples:
+
+```ts
+// Pattern: Single Responsibility - validates user input only.
+function validateUserInput(...) { ... }
+
+// Pattern: Pure Function - deterministic output with no side effects.
+function calculateTotal(...) { ... }
+
+// Pattern: Dependency Inversion - depends on an injected repository contract.
+async function loadProfile(...) { ... }
+```
+
+## Working Rules
+
+- Do not violate these coding principles unless there is no reasonable
+  alternative.
+- If a principle must be violated, include a short explanation in the code
+  review or final summary.
+- Refactor touched existing code to follow these patterns and principles when
+  doing so is safe and related to the requested change.
+- Do not use this skill as a reason for broad unrelated rewrites.
+- Before introducing an abstraction or design pattern, confirm it removes real
+  complexity compared with a straightforward function or module.
+- Prefer dependency inversion at boundaries such as databases, external
+  services, clocks, file systems, queues, and network calls when it improves
+  testability or substitution.
+- Keep interfaces and abstractions narrow. Do not create generic layers that
+  only have one trivial implementation unless they clarify a boundary.
+- Preserve the repository's existing style, naming, module system, and testing
+  approach.

package/.codex/config.toml

@@ -0,0 +1,2 @@
+approval_policy = "never"
+sandbox_mode = "danger-full-access"

package/index.d.ts

@@ -2,7 +2,7 @@
  * Utility functions for authentication and authorization in the CareCard ecosystem.
  */
 
-import {NextFunction, Request, Response} from 'express';
+import { NextFunction, Request, Response } from 'express';
 
 /**
  * Represents the standard JWT header structure.
@@ -178,6 +178,17 @@ export function jwtGetContext(req: any): JwtContext;
  */
 export function jwtValidateAndExtract(req: AuthenticatedRequest, publicKey: string, customErrorFunction?: () => void): void;
 
+/**
+ * Validates a service-to-service JWT from the Authorization header and extracts it into req.jwt.
+ */
+export function jwtValidateAndExtractService(
+  req: AuthenticatedRequest,
+  publicKey: string,
+  expectedIssuer: string,
+  expectedAudience: string,
+  customErrorFunction?: () => void,
+): void;
+
 /**
  * Validates the JWT from a custom header and extracts it into req.jwt.
  */
@@ -203,6 +214,16 @@ export function jwtValidateAndExtractWebTokenNoThrow(req: AuthenticatedRequest,
  */
 export function jwtValidateAndExtractVisitorNoThrow(req: AuthenticatedRequest, publicKey: string): void;
 
+/**
+ * Returns middleware that verifies a service-to-service JWT from one expected sender.
+ */
+export function jwtVerifyService(
+  publicKey: string,
+  expectedIssuer: string,
+  expectedAudience: string,
+  customErrorFunction?: () => void,
+): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+
 /**
  * Returns a middleware that verifies a JWT from the 'Authorization: Bearer <token>' header
  * and extracts it into req.jwt. Throws an error if invalid.

package/index.js

@@ -16,10 +16,12 @@ module.exports = {
   jwtGetRoleCode: jwtRoles.getCodeFromNameOfRole,
   jwtGetContext: jwtRoles.getContext,
   jwtValidateAndExtract: jwtLib.validateAndExtractJwtObject,
+  jwtValidateAndExtractService: jwtLib.validateAndExtractServiceJwtObject,
   jwtValidateAndExtractWebToken: jwtLib.validateAndExtractWebToken,
   jwtValidateAndExtractNoThrow: jwtLib.validateAndExtractJwtObjectNoThrow,
   jwtValidateAndExtractWebTokenNoThrow: jwtLib.validateAndExtractWebTokenObjectNoThrow,
   jwtValidateAndExtractVisitorNoThrow: jwtLib.validateAndExtractVisitorObjectNoThrow,
+  jwtVerifyService: jwtLib.verifyServiceJwt,
 
   /** @deprecated use jwtVerify */
   verifyJwt: jwtLib.verifyJwt,

package/lib/jwtLib.js

@@ -104,6 +104,24 @@ function validateAndExtractJwtObjectNoThrow(req, publicKey) {
   return _validateAndExtractGenericNoThrow(req, publicKey, _validateJwtNoThrow, _extractJwtObjectNoThrow, 'jwt');
 }
 
+function validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+  const jwtString = _validateJwt(req, customErrorFunction);
+  const isJwtSignatureValid = jwtVerifySignedToken(jwtString, publicKey);
+
+  if (jwtString && isJwtSignatureValid) {
+    _extractJwtObject(req, jwtString, customErrorFunction);
+  } else if (req) {
+    req.jwt = null;
+  }
+
+  if (!req?.jwt || !_isServiceJwtFor(req.jwt.payload, expectedIssuer, expectedAudience)) {
+    if (req) req.jwt = null;
+    throwError(customErrorFunction);
+  }
+
+  return req;
+}
+
 function validateAndExtractWebTokenObjectNoThrow(req, publicKey, headerName) {
   return _validateAndExtractGenericNoThrow(req, publicKey, r => _validateWebTokenNoThrow(r, headerName), _extractJwtObjectNoThrow, 'jwt');
 }
@@ -136,6 +154,17 @@ function verifyJwt(publicKey, customErrorFunction) {
   };
 }
 
+function verifyServiceJwt(publicKey, expectedIssuer, expectedAudience, customErrorFunction) {
+  return function (req, res, next) {
+    try {
+      validateAndExtractServiceJwtObject(req, publicKey, expectedIssuer, expectedAudience, customErrorFunction);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
 function verifyWebToken(publicKey, headerName, customErrorFunction) {
   return function (req, res, next) {
     try {
@@ -193,6 +222,48 @@ function _isLoginRequired(hasRequiredRole, customErrorFunction) {
   }
 }
 
+function normalizeSeconds(value) {
+  if (!Number.isFinite(value)) return null;
+  return value > 1000000000000 ? Math.floor(value / 1000) : Math.floor(value);
+}
+
+function _isServiceJwtFor(payload, expectedIssuer, expectedAudience) {
+  if (!payload) return false;
+  if (payload.iss !== expectedIssuer) return false;
+  if (payload.sub !== expectedIssuer) return false;
+  if (!payloadAudienceMatches(payload.aud, expectedAudience)) return false;
+  if (isJwtPayloadIssuedInFuture(payload)) return false;
+  if (isJwtPayloadExpired(payload)) return false;
+  if (isJwtPayloadNotYetValid(payload)) return false;
+  return true;
+}
+
+function payloadAudienceMatches(actualAudience, expectedAudience) {
+  if (Array.isArray(actualAudience)) return actualAudience.includes(expectedAudience);
+  return actualAudience === expectedAudience;
+}
+
+function isJwtPayloadExpired(payload) {
+  if (!payload.exp) return true;
+  const exp = normalizeSeconds(payload.exp);
+  if (!Number.isInteger(exp)) return true;
+  return Math.floor(Date.now() / 1000) >= exp;
+}
+
+function isJwtPayloadIssuedInFuture(payload) {
+  if (!payload.iat) return true;
+  const iat = normalizeSeconds(payload.iat);
+  if (!Number.isInteger(iat)) return true;
+  return Math.floor(Date.now() / 1000) < iat;
+}
+
+function isJwtPayloadNotYetValid(payload) {
+  if (!payload.nbf) return false;
+  const nbf = normalizeSeconds(payload.nbf);
+  if (!Number.isInteger(nbf)) return true;
+  return Math.floor(Date.now() / 1000) < nbf;
+}
+
 function _validateGenericNoThrow(req, headerName, extractor) {
   let jwtRaw = req.get(headerName);
   if (!jwtRaw) return null;
@@ -362,6 +433,7 @@ module.exports = {
   _isJwtSignatureValidNoThrow,
   _extractJwtObject,
   validateAndExtractJwtObject,
+  validateAndExtractServiceJwtObject,
   validateAndExtractWebToken,
   jwtAgeInSeconds,
   isJwtExpired,
@@ -369,6 +441,7 @@ module.exports = {
   jwtClientId,
   visitorClientId,
   verifyJwtAndRole,
+  verifyServiceJwt,
   verifyJwt,
   verifyWebTokenNoThrow,
   verifyWebToken,
@@ -388,6 +461,7 @@ module.exports = {
   _extractVisitorObjectNoThrow,
   _extractWebToken,
   _isLoginRequired,
+  _isServiceJwtFor,
   _attachJwtMethods,
   _attachVisitorMethods,
   _validateWebToken,