1. Dependencies Install @hvt/sdk alongside jose for ultra-fast Edge-compatible offline JWT verification:
bash Copy
npm install @hvt/sdk jose2. Environment Variables Add your HVT credentials to .env.local:
env Copy
NEXT_PUBLIC_HVT_API_URL =https://api.hvts.app
NEXT_PUBLIC_HVT_PROJECT_ID =b5540592-38 fd-4 d42-9538 -c125716f31f4
HVT_API_KEY =hvt_live_your_project_api_key3. Edge Middleware Offline Token Verification Intercept incoming requests in middleware.ts. By using jose with createRemoteJWKSet, your Edge Middleware verifies RS256 cryptographic signatures locally with zero outbound HTTP calls:
typescript Copy
import { NextResponse } from 'next/server' ;
import type { NextRequest } from 'next/server' ;
import { createRemoteJWKSet, jwtVerify } from 'jose' ;
const HVT_API_URL = process.env .NEXT_PUBLIC_HVT_API_URL || 'https://api.hvts.app' ;
const PROJECT_ID = process.env .NEXT_PUBLIC_HVT_PROJECT_ID ;
const JWKS = createRemoteJWKSet (
new URL (`${HVT_API_URL} /.well-known/jwks.json` )
);
export async function middleware (request : NextRequest ) {
const token = request.cookies .get ('hvt_access' )?.value ;
if (!token && request.nextUrl .pathname .startsWith ('/dashboard' )) {
return NextResponse .redirect (new URL ('/login' , request.url ));
}
if (token) {
try {
const { payload } = await jwtVerify (token, JWKS , {
issuer : HVT_API_URL ,
audience : PROJECT_ID ,
});
const response = NextResponse .next ();
response.headers .set ('x-user-id' , payload.sub as string );
response.headers .set ('x-user-email' , (payload.email as string ) || '' );
response.headers .set ('x-user-roles' , JSON .stringify (payload.app_roles || []));
response.headers .set ('x-session-id' , (payload.sid as string ) || '' );
return response;
} catch {
return NextResponse .redirect (new URL ('/login' , request.url ));
}
}
return NextResponse .next ();
}
export const config = {
matcher : ['/dashboard/:path*' , '/settings/:path*' , '/api/protected/:path*' ],
};Because JWKS public keys are cached in-memory at the Edge runtime, verification executes in ~0.2ms with no database or network roundtrips.
4. Server Component Session Verification In React Server Components, read the pre-verified user context directly from incoming headers, or initialize HVTClient when backend API mutations are needed:
tsx Copy
import { headers } from 'next/headers' ;
import { HVTClient } from '@hvt/sdk' ;
export default async function DashboardPage ( ) {
const headersList = await headers ();
const userId = headersList.get ('x-user-id' );
const userEmail = headersList.get ('x-user-email' );
const rolesJson = headersList.get ('x-user-roles' );
const roles : string [] = rolesJson ? JSON .parse (rolesJson) : [];
if (!userId) {
return <p > Unauthorized</p > ;
}
return (
<main className ="p-8" >
<h1 className ="text-2xl font-bold" > Welcome, {userEmail}</h1 >
<p className ="text-sm text-zinc-400" > User ID: {userId}</p >
<div className ="mt-4 flex gap-2" >
{roles.map((r) => (
<span key ={r} className ="px-2 py-1 bg-zinc-800 rounded text-xs" > {r}</span >
))}
</div >
</main >
);
}5. Server Actions with Role Checks Protect Next.js 15 Server Actions by decoding claims and verifying permissions:
typescript Copy
'use server' ;
import { cookies } from 'next/headers' ;
import { createRemoteJWKSet, jwtVerify } from 'jose' ;
const JWKS = createRemoteJWKSet (
new URL (`${process.env.NEXT_PUBLIC_HVT_API_URL} /.well-known/jwks.json` )
);
export async function deleteDocument (documentId : string ) {
const cookieStore = await cookies ();
const token = cookieStore.get ('hvt_access' )?.value ;
if (!token) throw new Error ('Unauthenticated' );
const { payload } = await jwtVerify (token, JWKS , {
issuer : process.env .NEXT_PUBLIC_HVT_API_URL ,
audience : process.env .NEXT_PUBLIC_HVT_PROJECT_ID ,
});
const permissions = (payload.app_permissions as string []) || [];
if (!permissions.includes ('documents:delete' )) {
throw new Error ('Forbidden: missing documents:delete permission' );
}
return { success : true };
}