AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools JWT Decoder Agent Guide

Agent guide for local JWT header and payload decoding without signature verification.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools JWT Decoder in the alexandrai-tools project.

Project overview

This guide covers src/tools/jwt-decoder/index.ts. The tool trims input, splits a token into dot-separated parts, decodes the header and payload as base64url JSON, pretty-prints both objects, and returns clear errors for malformed segments. It does not verify signatures and must keep that boundary visible.

Primary source files

  • src/tools/jwt-decoder/index.ts defines meta, JwtResult, decodeJwt, base64url JSON decoding, and error message extraction.
  • src/tools/jwt-decoder/index.test.ts covers valid decoding, empty input, bad segment count, invalid header, invalid JSON, and pretty printing.
  • src/tools/jwt-decoder/Body.astro owns the browser input and decoded output panels.
  • src/tools/jwt-decoder/i18n.ts owns localized copy and signature-warning text.
  • src/lib/tools.ts registers metadata for the site.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep empty and whitespace-only input as a non-error blank result so the UI starts clean.
  • Require at least header and payload segments, but do not require verification logic in this decoder.
  • Convert base64url characters and padding before decoding.
  • Decode bytes through TextDecoder before JSON.parse so UTF-8 payloads work.
  • Pretty-print decoded JSON with two-space indentation.
  • Keep the no-signature-verification warning in copy and docs.
  • Do not log, store, transmit, or include real tokens in docs or fixtures.

Testing

Test empty input, whitespace input, valid header and payload, missing segments, bad base64url, non-JSON payloads, UTF-8 payloads, pretty indentation, and UI warning copy. Add separate tests if signature metadata is displayed later.

PR checklist

  • npm test passes for jwt-decoder.
  • Errors identify whether header or payload failed.
  • No code path claims signature verification.
  • Public docs avoid real or complete token examples.