@yawlabs/session

@yawlabs/session

Sign, verify, and extract the Yaw account session token — the HMAC-signed yaw_team value that yaw.sh issues at sign-in. Any Yaw Labs service holding the shared secret can verify a session offline, with no callback to yaw.sh.

This package is the single source of truth for the token format. Before it, the sign/verify pair was hand-copied across yaw.sh, vew, and vew.sh — and the copies drifted.

Format

token   = base64url(JSON payload) + "." + base64url(HMAC-SHA256(secret, body))
payload = { order_id, email, role, iat, exp (ms since epoch), tier? }

Usage

import {
  verifyYawSession,
  sessionFromHeaders,
  signToken,
  verifyToken,
} from '@yawlabs/session';

// Netlify function / Node handler:
const token = sessionFromHeaders(headersObject);       // Bearer first, cookie fallback
const session = verifyYawSession(token, process.env.ADMIN_SESSION_SECRET);
if (!session) return unauthorized();
// session: { order_id, email, role, iat, exp, tier? }

Two layers:

• signToken / verifyToken — the format: HMAC integrity (constant-time) plus expiry. No claim policy; bring your own (e.g. a dashboard cookie with different claims can share the format).
• signYawSession / verifyYawSession — the yaw_team policy: requires the load-bearing claims (order_id, email, role) on top of the format. Fails closed: any malformed, tampered, expired, or claim-incomplete token returns null.

Helpers: parseCookies, sessionCookieHeader, clearSessionCookieHeader, YAW_SESSION_COOKIE.

Guarantees

• Zero runtime dependencies (node:crypto only).
• Byte-for-byte parity with the historical implementations, locked by a pinned cross-implementation test vector.
• Constant-time signature comparison; verification fails closed.

Release

Tag-push driven: bump package.json, commit, git tag vX.Y.Z, git push --follow-tags. CI publishes to npm.