AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Text Encrypt in the alexandrai-tools project.

Project overview

This guide covers src/tools/text-encrypt/index.ts. The tool encrypts text with AES-GCM using a key derived from the password through PBKDF2 with SHA-256 and one hundred thousand iterations, generates a random sixteen-byte salt and twelve-byte IV, returns base64 of salt plus IV plus ciphertext, and returns ok false for any decryption failure.

Primary source files

• src/tools/text-encrypt/index.ts defines meta, EncryptResult, encryptText, and decryptText.
• src/tools/text-encrypt/index.test.ts covers encrypt-decrypt round trips, wrong password failures, random output from salt and IV, empty plaintext, and corrupted payload failures.
• src/tools/text-encrypt/Body.astro owns browser controls.
• src/tools/text-encrypt/i18n.ts owns localized copy.
• src/lib/tools.ts registers metadata.

Setup commands

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

Change rules

• Use globalThis.crypto.getRandomValues for salt and IV.
• Keep salt length at sixteen bytes.
• Keep AES-GCM IV length at twelve bytes.
• Derive an AES-GCM 256-bit key with PBKDF2 SHA-256.
• Keep PBKDF2 iterations at one hundred thousand unless tests and copy change together.
• Encode payload as base64 of salt, IV, and ciphertext in that order.
• Return a generic decrypt failure for wrong passwords or corrupted data.

Testing

Test round trips, wrong passwords, corrupted base64, too-short payloads, empty plaintext, Unicode plaintext, random output across calls, salt and IV lengths, PBKDF2 parameter changes, and browser crypto availability.

PR checklist

• npm test passes for text-encrypt.
• Encoding, decoding, and failure behavior remain documented.
• Browser-local processing and security limits stay clear in UI copy.
• UI labels, metadata, and tests update together for behavior changes.