first commit

docs/security-stack/crypto/crypto-utils/src/bytes/concat-bytes/concat-bytes.md

@@ -0,0 +1,50 @@
+# concatBytes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Concatenate any number of `Uint8Array` buffers into a single freshly-allocated result. Used extensively by crypto protocols that frame authenticated data by length-prefix or that split a plaintext across record boundaries. This module re-exports `concatUint8Arrays` from `@suaveplan/bytes` under the crypto-friendly name `concatBytes`, centralising the helper so every downstream cipher, MAC, or encoding never has to handwrite the `set`-at-offset loop and all packages share a single, tested implementation.
+
+## Features
+
+- Variadic: accepts any number of parts (including zero).
+- Returns a new `Uint8Array` even for single-arg calls (never aliases an input).
+- Delegates to `@suaveplan/bytes` — one implementation, zero duplication.
+- Zero implementation code in this module — pure delegation.
+
+## Usage: Basic Example
+
+```ts
+import { concatBytes } from "@suaveplan/crypto-utils/bytes";
+
+const frame = concatBytes(header, payload, footer);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { concatBytes } from "@suaveplan/crypto-utils/bytes";
+
+// Build a TLS-style length-prefixed message.
+function frame(...parts: Uint8Array[]): Uint8Array {
+    const body = concatBytes(...parts);
+    const lenPrefix = new Uint8Array([(body.length >> 8) & 0xff, body.length & 0xff]);
+    return concatBytes(lenPrefix, body);
+}
+
+const out = frame(new Uint8Array([0x01]), new Uint8Array([0x02, 0x03]));
+```
+
+## API Reference
+
+- `concatBytes(...parts: Uint8Array[]): Uint8Array` — Returns a new `Uint8Array` whose contents are the concatenation of every `part` in order. Never throws. Alias for `concatUint8Arrays` from `@suaveplan/bytes`.
+
+## Implementation Notes
+
+`concatBytes` is a direct `const` alias for `concatUint8Arrays` from `@suaveplan/bytes`. The underlying implementation uses two passes: the first sums `part.length` to pre-allocate once (no reallocation), the second uses `Uint8Array#set` which hits the fast path in every modern engine. Delegating here removes identical logic that previously lived in both packages and ensures all `@suaveplan/crypto-*` consumers share the same implementation with a single point of maintenance.
+
+### Edge Cases
+
+`concatBytes` preserves exact input order and is safe to call with zero, one, or many arrays. Passing a zero-length array returns a new zero-length `Uint8Array`. Callers relying on fixed output lengths for cryptographic framing should validate each input's length before calling; the function trusts its inputs and performs a single pre-sized allocation.