# 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.