Base32 Laravel Package

Product Decisions This Supports

• Build vs. buy on the TOTP/MFA path. RFC 4648 Base32 is the encoding the otpauth:// provisioning standard and every mainstream authenticator app expects. This package removes a small but genuinely bug-prone piece of hand-rolled code (alphabet, padding, case handling, canonical trailing bits) from an authentication feature. Decision: buy — one Composer line versus a spike-plus-implementation-plus-test-vector workstream.
• Roadmap sequencing for security features. Because the codec layer is effectively solved, product can debate MFA scope on its own merits (SMS vs. TOTP vs. WebAuthn, enrolment UX, recovery-code flow) instead of being blocked on plumbing. Typical effort shifts from "spike + build + validate" to "integrate + test."
• Interoperability commitments. Supports a concrete, sellable promise — "works with Google Authenticator, 1Password, Authy" — because output is RFC-compliant and matches the de facto standard. The bundled Base32Hex class covers the extended-hex alphabet if a partner, DNSSEC-adjacent consumer, or legacy integration demands it.
• Compliance and procurement posture. MIT license, no transitive dependencies, static API, and unit tests against official RFC test vectors. That is a short legal and supply-chain review: relevant when someone asks "what exactly are we shipping into the auth path?" The 2.0 strict decoder also closes a documented security finding (Trail of Bits TOB-WIKI2FA-5 from the Wikimedia 2FA review), which is a useful line item for a security questionnaire.
• Scope clarity / risk framing. It is encoding only — no HMAC, no time step, no hash_equals verification. Making that boundary explicit early prevents the most common scoping error in this area: assuming "Base32 library" means "2FA library." It also makes the follow-on build/buy decision (OTP framework, TOTP verification, drift window) a separate, cleanly-argued call.
• Reuse decision across the codebase. If Base32 shows up in exactly one place, it rides along as a transitive dependency of an OTP library. If it shows up in several (token formats, data exports, partner integrations, backup-code schemes), adopt it directly and wrap it behind an internal interface — that's a product/platform decision about coupling, not just a coding one.

When to Consider This Package

Adopt when:

• You need RFC 4648 Base32 specifically: TOTP/HOTP secret generation, otpauth:// URI construction, or an external system that mandates Base32 (legacy APIs, hex-alphabet consumers).
• You're on PHP 8.1+ and want zero configuration — no service provider, no config file, no facade, no framework coupling. (The 1.x line covers PHP 7.2–8.0 if you're pinned to an older runtime; note the migration boundary.)
• You want a single-responsibility codec rather than pulling an entire OTP framework when encoding is the only need.
• You can pin deliberately. The changelog history is candid about a correctness bug that "could lead to some unwanted results" in early lines, and 2.0 changes decode semantics in a backward-incompatible way. A version pin is a hard requirement, not a nicety.
• Your team can absorb a strict-decoder migration. If you decode user-supplied input (pasted TOTP secrets, often lowercase or space-grouped), 2.0 will now throw instead of silently sanitizing — normalization (strtoupper, strip whitespace) becomes your code's responsibility.

Look elsewhere, or re-scope, when:

• You need OTP verification, not encoding. If the real requirement is "verify a 6-digit code," adopt spomky-labs/otphp or pragmarx/google2fa — they own the time step, HMAC, drift window, and constant-time comparison. This package is already a transitive dependency of that stack, so adding it directly is redundant.
• You need Base64 or URL-safe variants. Wrong tool — use base64_encode or a ULID-style helper.
• Maintenance SLAs are a procurement requirement. Single-maintainer project, small dependent count, no stated security policy in the provided materials. If your org requires an active security-response commitment for auth-path dependencies, either accept the risk explicitly and document it, or route through the OTP framework that vendors this.
• You need convenience features it doesn't ship. No built-in validator (no isBase32()), no padding-preserving output mode, no timing-safe primitives. All are trivial to add locally, but must be scoped as work rather than assumed.
• You need the hex alphabet and standard alphabet interchangeably. They are silently incompatible; mixing them is a data-corruption bug, not an exception.

Rule of thumb for the decision meeting: if Base32 appears in exactly one place and you're already adopting an OTP library, don't add this directly. If it appears in several places, add it and wrap it behind an interface.

How to Pitch It (Stakeholders)

For executives: A zero-cost, MIT-licensed, single-purpose library that lets us ship authenticator-app interoperability and two-factor enrolment on the existing roadmap instead of opening a new engineering workstream. It replaces hand-rolled encoding — a classic source of subtle, hard-to-test security bugs — with an implementation that passes the published RFC test vectors and whose strict decoder was hardened in response to a real audit finding. Integration cost is roughly one Composer line plus a thin wrapper class; ongoing cost is a version pin during routine dependency updates. The risks are narrow and known: it is encoding only (no cryptographic claims), and it is a small single-maintainer project — mitigated by pinning to a maintained release line and confining usage to one service class behind an interface.

For engineering: Drop-in via composer require christian-riesen/base32. Static API (Base32::encode() / Base32::decode()), PSR-4 autoloaded, no container registration, no config, no framework coupling. Three things to build around it: (1) wrap it in a Base32Codec interface so tests and any future swap don't hit static calls directly; (2) if you decode user-supplied input, normalize first — uppercase and strip whitespace — then catch \InvalidArgumentException, because 2.0 is strict and case-sensitive by design; (3) use hash_equals() on decoded bytes for any comparison, since the package exposes no timing-safe primitives. Never use Base32 and Base32Hex interchangeably. If we later need full OTP verification, we adopt an OTP library and this becomes its transitive dependency rather than a direct one — no wasted work either way.