# Br Crypto

> Use Better Route 1.1 cryptographic helpers for secure random tokens, Hex/Base64/Base64URL encoding, strict Base64URL decoding, and constant-time secret comparison. Use when implementing nonces, state, PKCE, opaque tokens, or signature comparisons.

- Skill: `lonsdale201/br-crypto` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lonsdale201/br-crypto`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lonsdale201/br-crypto/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: Lonsdale201 (https://skillmd.com/u/lonsdale201)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lonsdale201/br-crypto

---


# Better Route crypto helpers

Use the library helpers instead of reimplementing small security primitives.

```php
use BetterRoute\Support\Crypto;
use BetterRoute\Support\CryptoEncoding;

$state = Crypto::token(32); // Base64URL by default.
$nonce = Crypto::token(32, CryptoEncoding::Base64Url);
$hex = Crypto::tokenHex(32);

$encoded = Crypto::base64UrlEncode($raw);
$decoded = Crypto::base64UrlDecode($encoded);

if (!Crypto::equals($expected, $provided)) {
    throw new \BetterRoute\Http\ApiException('Invalid token.', 401, 'invalid_token');
}
```

## Rules

- Pass entropy in bytes, not output-character count. The default 32 bytes provides 256 bits before encoding.
- `Crypto::token()` uses `random_bytes()` and accepts `CryptoEncoding::Hex`, `Base64`, or `Base64Url`, including their lowercase string values.
- `Crypto::base64UrlDecode()` validates alphabet, padding placement, length, and decoder success; catch `RuntimeException` at an input boundary if malformed input should become a client error.
- Use `Crypto::equals()` only with strings of the expected representation. Decode/normalize representations before comparing, but never perform lossy case normalization on secret material.
- Use `br-single-use-token` when a token must also be consumed atomically, `br-hmac-signature` for request signing, and `br-jwks-jwt-auth` for JWTs.

Do not use these helpers as password hashing, encryption, key derivation, or a substitute for a protocol-specific verifier.

Source references: `src/Support/Crypto.php`, `src/Support/CryptoEncoding.php`.

## References

- Official documentation: <https://lonsdale201.github.io/better-docs/docs/better-route/agents>