sec-jwt-verify Edge Function — Security

sec-jwt-verify — Verify JWT token signatures

Validates a JWT's HMAC signature and expiry claim using Web Crypto — never throws, always returns a structured result.

---

API

POST /api/sec-jwt-verify

Request body

Field	Type	Required	Default	Description
token	string	✅	—	The JWT string to verify
secret	string	✅	—	HMAC secret used to sign the token
algorithm	"HS256" | "HS512"	❌	"HS256"	Expected algorithm

Success response (200)

{
  "success": true,
  "data": {
    "valid": true,
    "expired": false,
    "payload": { "sub": "user123", "iat": 1709000000, "exp": 1709003600 }
  }
}

Error responses

Code	HTTP	When
INVALID_INPUT	400	Missing required field
INTERNAL_ERROR	500	Unexpected error

---

Usage

cURL

curl -X POST "$FUNCTION_URL" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ...", "secret": "my-secret"}'

TypeScript / JavaScript (HTTP)

const response = await fetch(FUNCTION_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: req.headers.authorization?.split(' ')[1], secret: JWT_SECRET }),
});
const { data } = await response.json();
if (!data.valid) throw new Error('Unauthorized');
const userId = data.payload.sub;

Direct import (Node / Bun / Deno)

import { jwtVerify } from '@aerostack/functions/sec-jwt-verify';

const { valid, expired, payload } = await jwtVerify({
  token: bearerToken,
  secret: process.env.JWT_SECRET!,
});

---

Use Cases

• Validating Bearer tokens in API route middleware
• Checking session tokens without maintaining server-side session state
• Verifying signed invite or magic-link tokens before granting access
• Inspecting JWT claims to make authorization decisions (roles, scopes)

---

Notes

• Never throws — all failure modes return { valid: false, expired: false, payload: null }
• expired: true means the signature was valid but exp has passed — useful for distinguishing tampering from timeout
• Uses timing-safe crypto.subtle.verify — not vulnerable to timing attacks
• Pair with sec-jwt-sign to create and consume tokens with the same secret