Cbor Bundle Laravel Package

Getting Started

This bundle is a thin Symfony integration around web-auth/cbor (CBOR — Concise Binary Object Representation, RFC 8949). It gives you an encoder/decoder service and, as of 3.1.0, a configurable maximum nesting depth for the decoder.

First steps:

1. Install the underlying library and the bundle: composer require spomky-labs/cbor-bundle. Note that the bundle's service wiring is Symfony-oriented; in a Laravel app you will usually get more value by requiring web-auth/cbor directly and binding the encoder/decoder yourself in a service provider. Pull the bundle in only if you're reusing a shared package set or running a Symfony/Laravel hybrid.
2. Look first at the CBOR\Decoder and CBOR\Encoder classes — these are the actual workhorses. The bundle contributes configuration, not codec logic.
3. Publish/register config so you can set the decoder depth limit (see below), then try your first use case: decoding a CBOR payload from an API or a hardware/WebAuthn-style client and turning it into a PHP array.

use CBOR\Decoder;

$decoder = app(Decoder::class);
$data = $decoder->decode($binaryPayload); // CBOR\CBORObject
$plain = $data->normalize();              // array/scalar

First use case: signature verification flows and WebAuthn/CTAP attestation objects, device telemetry frames, or compact binary payloads where JSON is too heavy.

Implementation Patterns

Bind the codec in a service provider. Since the bundle's container extensions won't auto-register in Laravel, create a small provider:

$this->app->singleton(Decoder::class, function ($app) {
    return Decoder::create(); // apply depth limit here, see below
});

$this->app->singleton(Encoder::class, fn () => Encoder::create());

Configure the decoding depth explicitly. The 3.1.0 enhancement exposes the decoder's maximum nesting depth as a configuration option. Nesting depth is a denial-of-service vector — deeply nested CBOR can blow the stack or burn CPU. Set it to the shallowest value your payloads actually need (typically 3–8 for WebAuthn, higher for nested telemetry) rather than accepting the default:

// config/cbor.php
return [
    'decoder' => [
        'max_depth' => 8,
    ],
];

Then hydrate the decoder from config in your provider. If you're using the Symfony bundle directly, the equivalent lives in config/packages/cbor.yaml under the decoder section.

Wrap decoding in a dedicated action or job. CBOR decoding produces CBORObject instances, not arrays — always call ->normalize() before handing data to the rest of your app, and do it behind a boundary so raw objects don't leak into domain code.

Validate before you decode. CBOR is self-describing and tolerant; check payload size and content type at the boundary. A FormRequest or middleware that rejects payloads above a byte budget is cheaper than any decoder-level limit.

Pair with caching for repeated frames. If you're decoding the same attestation blob across retries, cache the normalized result keyed by a hash of the raw bytes — decoding is not free and CBOR payloads are stable.

Use it alongside JSON, not instead of it. Keep CBOR for the machine-facing edge (device ↔ server, credential exchange) and normalize into arrays immediately so Eloquent, validation, and the rest of Laravel keep working unchanged.

Gotchas and Tips

• This is a Symfony bundle. In a pure Laravel app, auto-configuration, the bundle's DI extension, and its YAML config tree do not apply. You are effectively using it as a library plus manual wiring. Budget for this or skip the bundle and use web-auth/cbor directly.
• max_depth semantics changed in 3.1.0 in the sense that it is now settable. If you previously worked around nesting attacks with middleware or a fork, consolidate on the config option — but re-test your limits, since the default may not match your old hand-rolled guard.
• Depth is not size. The new option bounds recursion, not payload bytes or item count. You still need an input size cap.
• normalize() and binary strings. Byte strings may come back as raw PHP strings; make sure downstream code (JSON responses, DB columns) is binary-safe or base64-encode at the boundary.
• Integer width matters. CBOR has explicit int sizes; PHP will happily widen them. Don't assume 64-bit semantics survive a round-trip to a 32-bit target.
• Cache clear after config changes. If you're loading depth from a config file through the container, php artisan config:cache in production can freeze a stale value — verify with config('cbor.decoder.max_depth') after deploy.
• Debugging tip: when a decode fails, dump the first bytes as hex. CBOR major types are encoded in the top 3 bits of the initial byte, which tells you instantly whether you received a map, array, or a truncated payload.
• Extension point: the encoder accepts tag handlers. If you need domain-specific tags (dates, UUIDs, custom objects), register handlers there rather than post-processing normalized arrays — it keeps encode/decode symmetric.