first commit

docs/security-stack/crypto/crypto-rsa/src/math/os2ip.md

@@ -0,0 +1,52 @@
+# `math/os2ip`
+
+## Purpose
+
+Octet-String-to-Integer Primitive (RFC 8017 §4.2). Decodes a big-endian byte string
+into a non-negative `bigint`. Used by every RSA scheme to convert a modulus-sized
+byte payload back into the integer the modular operations expect.
+
+Thin re-export of `@suaveplan/crypto-utils`'s canonical implementation so the
+entire project agrees on encoding semantics.
+
+## Features
+
+- Always returns `bigint`, never `number`, so precision is preserved for any
+  byte length.
+- Pure decoder; never throws.
+
+## Usage: Basic Example
+
+```ts
+import { os2ip } from "@suaveplan/crypto-rsa/math";
+
+const value = os2ip(new Uint8Array([0, 0, 0, 255])); // 255n
+```
+
+## Usage: Advanced Example
+
+```ts
+import { i2osp, modPow, os2ip } from "@suaveplan/crypto-rsa/math";
+
+function privateOpRoundTrip(
+    sigBytes: Uint8Array,
+    e: bigint,
+    n: bigint,
+    modulusByteLength: number
+): Uint8Array {
+    const sigInt = os2ip(sigBytes);
+    const recovered = modPow(sigInt, e, n);
+    return i2osp(recovered, modulusByteLength);
+}
+```
+
+## API Reference
+
+### `os2ip(bytes: Uint8Array): bigint`
+
+Returns the big-endian-decoded `bigint`. Empty input returns `0n`.
+
+## Implementation Notes
+
+The canonical implementation lives in `@suaveplan/crypto-utils/bytes/os2ip/os2ip.ts`.
+This re-export gives RSA consumers a path-local import mirroring RFC 8017 §4.2.