first commit

docs/security-stack/crypto/crypto-rsa/src/engine/noble.md

@@ -0,0 +1,90 @@
+# engine/noble
+
+## Purpose
+
+Default `RsaCryptoEngine` backed by the pure-JS noble primitives this
+package ships natively. Provides the `name: "noble"` engine label and
+delegates `sign` / `verify` / `encrypt` / `decrypt` / `modPow` to the
+canonical `rsa*` functions, giving engine-aware consumers identical
+semantics to direct callers.
+
+## Features
+
+- Implements every method on `RsaCryptoEngine`
+- Routes through `rsaSignPkcs1v15`, `rsaSignPss`, `rsaVerifyPkcs1v15`,
+  `rsaVerifyPss`, `rsaEncryptPkcs1v15`, `rsaEncryptOaep`,
+  `rsaDecryptPkcs1v15`, `rsaDecryptOaep`
+- Discriminated `RsaSchemeOptions` union routes per-scheme parameters
+- Rejects scheme/operation mismatches (e.g. `sign({ scheme: "oaep" })`)
+  with `UNSUPPORTED_FORMAT`
+- `modPow` exposed for advanced consumers (e.g. consumer-side
+  signature audit, key-pair sanity checks)
+
+## Usage: Basic Example
+
+```ts
+import { nobleEngine } from "@suaveplan/crypto-rsa/engine";
+
+const sig = await nobleEngine.sign(privateKey, message, {
+    scheme: "pkcs1v15",
+    hash: "SHA-256",
+});
+const ok = await nobleEngine.verify(publicKey, message, sig, {
+    scheme: "pkcs1v15",
+    hash: "SHA-256",
+});
+```
+
+## Usage: Advanced Example
+
+Use the engine surface to abstract over backend selection in higher-
+level code:
+
+```ts
+import {
+    nobleEngine,
+    type RsaCryptoEngine,
+} from "@suaveplan/crypto-rsa/engine";
+
+async function signWithEngine(
+    engine: RsaCryptoEngine,
+    privateKey: RsaPrivateKey,
+    message: Uint8Array
+): Promise<Uint8Array> {
+    return engine.sign(privateKey, message, {
+        scheme: "pss",
+        hash: "SHA-512",
+        saltLength: 64,
+    });
+}
+
+const sig = await signWithEngine(nobleEngine, key, msg);
+```
+
+## API Reference
+
+### `nobleEngine: RsaCryptoEngine`
+
+- `name: "noble"`
+- `sign(privateKey, message, options)` — `RsaSchemeOptions` with
+  `scheme: "pkcs1v15" | "pss"`
+- `verify(publicKey, message, signature, options)` — same scheme set
+- `encrypt(publicKey, plaintext, options)` — `scheme: "pkcs1v15" | "oaep"`
+- `decrypt(privateKey, ciphertext, options)` — same scheme set
+- `modPow(base, exponent, modulus): bigint`
+
+## Implementation Notes
+
+- The engine is a stateless singleton — no construction overhead, no
+  per-call setup.
+- Scheme/operation mismatches throw `UNSUPPORTED_FORMAT` synchronously
+  inside the async wrapper. Defensive by design — the discriminated
+  union forbids the mismatch at the type level, but runtime callers
+  can bypass the type system (`as never`).
+- `modPow` is exposed to give advanced consumers a single uniform
+  modpow surface across engines. The implementation matches
+  `math/modpow` exactly (both delegate to
+  `@noble/curves/abstract/modular.pow`).
+- Sign / verify route through the package's existing functions with
+  blinding enabled by default; the caller cannot disable blinding via
+  the engine surface.