TriFrost 0.18.0 - FrostBite

This update brings subtle but powerful improvements across TriFrost’s core — from smarter, cross-runtime environment handling to brand-new HMAC cookie signing, verification, and robust, production-ready authentication middleware.

Added

• feat: The Cookies module now supports built-in HMAC signing and verification using Web Crypto (supported across Node, Bun and Workerd). It provides .sign() to generate an HMAC-signed value and .verify() to check integrity. Supported algorithms: SHA-256, SHA-384, SHA-512.

/* Basic Usage */
const signed = await ctx.cookies.sign('userId42', ctx.env.MY_COOKIE_SECRET);
ctx.cookies.set('session', signed);

...

const rawCookie = ctx.cookies.get('session');
const verified = await ctx.cookies.verify(rawCookie, ctx.env.MY_COOKIE_SECRET);

if (verified) console.log('Untampered value:', verified);
else console.log('Signature invalid or tampered!');

/* Using secret rotation (multi-key check) */
const signed = await ctx.cookies.sign('orderToken', 'newSecret', {algorithm: 'SHA-512'});

const verified = await ctx.cookies.verify(signed, [
    {val: 'newSecret', algorithm: 'SHA-512'}, /* current */
    {val: 'oldSecret', algorithm: 'SHA-256'}, /* legacy fallback */
]);

if (verified) console.log('Valid order token:', verified);
else console.log('Invalid or outdated token');

• feat: New BasicAuth middleware — HTTP Basic Authentication via the Authorization header

import {BasicAuth} from '@trifrost/core';

router
  .use(BasicAuth({
    validate: (ctx, {user, pass}) => user === 'admin' && pass === ctx.env.ADMIN_SECRET
  }))
  .get('/basic-protected', ctx => {
    return ctx.json({message: `Welcome, ${ctx.state.$auth.user}`});
  });

• feat: New BearerAuth middleware — HTTP Bearer Token Authentication via the Authorization header

import {BearerAuth} from '@trifrost/core';

router
  .use(BearerAuth({validate: (ctx, token) => token === ctx.env.API_TOKEN}))
  .get('/bearer-protected', ctx => {
    const auth = ctx.state.$auth; /* { token: 'actual-token' } */
    return ctx.json({message: 'Bearer token validated'});
  });

• feat: New ApiKeyAuth middleware — API key validation using configurable headers or query params

import {ApiKeyAuth} from '@trifrost/core';

router
  .use(ApiKeyAuth({
    header: 'x-api-key',
    validate: (ctx, key) => key === ctx.env.MY_API_KEY
  }))
  .get('/api-key-protected', ctx => {
    const auth = ctx.state.$auth; /* { key: 'actual-key' } */
    return ctx.json({message: 'API key validated'});
  });

• feat: New SessionCookieAuth middleware - HMAC-signed cookie validation (integrated with the new cookie signing)

import {SessionCookieAuth} from '@trifrost/core';

router
  .use(SessionCookieAuth({
    cookie: 'session_id',
    secret: {val: ctx => ctx.env.SESSION_SECRET, algorithm: 'SHA-256'},
    validate: (ctx, session) => {
      /* Optionally enrich $auth with custom object */
      const user = lookupSession(session);
      return user ? {id: user.id, role: user.role} : false;
    }
  }))
  .get('/session-protected', ctx => {
    const auth = ctx.state.$auth; /* {id: '123', role: 'admin'} */
    return ctx.json({message: `Hello, user ${auth.id} with role ${auth.role}`});
  });

Improved

• qol: All runtimes now expose a consistent .env getter, so both runtime internals and app code can reliably access environment variables — even when no explicit env was passed. This also means you are no longer required to pass process.env when setting up an app on Node or Bun. For Workerd, the runtime’s env getter is hydrated automatically upon the first incoming request.

import {App} from '@trifrost/core';
import {type Env} from './types';

/* This one and the one below will now yield the same effective env */
const app = new App<Env>({env: process.env});
const app = new App<Env>({});

• qol: You can still provide a user-defined env object in AppOptions, this will now be automatically merged with the runtime-provided environment (such as process.env in Node/Bun) at boot time.
• qol: The uWSRuntime has improved version detection — it now properly reports bun:<version> when running under Bun, or node:<version> when under Node.js, falling back to N/A if unknown. Important to note that these runtime properties are also part of telemetry traces.

Notes on Auth Middleware

• Each middleware exposes a type-safe, ergonomic API with built-in $auth state injection for downstream handlers.
• When validate() returns an object, that object becomes the $auth state; if it returns true, a fallback object is injected (e.g., {user}, {token}, {key}, or {cookie}), and if it returns false, the request is rejected with a 401 Unauthorized.

✨ Bottom line: With FrostBite (0.18.0), TriFrost takes its first big leap into the world of built-in authentication — delivering fresh, modular, production-ready middleware to guard your routes, secure your sessions, and validate your keys.

But this is just the start: more auth flavors, integrations, and sugar are coming in future releases (or contribute your own?).

Stay frosty — the adventure has only begun. ❄️🔐🌟