first commit

docs/security-stack/crypto/crypto-rsa/src/keys/oid.md

@@ -0,0 +1,53 @@
+# `keys/oid`
+
+## Purpose
+
+Centralised OID constants for the RSA wire formats handled by this package.
+Currently exports `OID_RSA_ENCRYPTION` (`1.2.840.113549.1.1.1`), the algorithm
+identifier RFC 8017 uses for `rsaEncryption` inside `SubjectPublicKeyInfo`
+and `PrivateKeyInfo` `AlgorithmIdentifier` slots. Future stages may extend
+this file with the signature-OID family (`sha256WithRSAEncryption` etc.) once
+the sign/verify modules need them; this Stage-1 file covers the universal
+key-format OID alone.
+
+## Features
+
+- One definition per OID — eliminates copy-paste drift between parsers.
+- String-typed OIDs (`"1.2.840.113549.1.1.1"`) match the dotted-decimal form
+  produced by `DerReader.readObjectIdentifier`.
+
+## Usage: Basic Example
+
+```ts
+import { OID_RSA_ENCRYPTION } from "@suaveplan/crypto-rsa";
+
+if (oid === OID_RSA_ENCRYPTION) {
+    // dispatch to RSA path
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { OID_RSA_ENCRYPTION } from "@suaveplan/crypto-rsa";
+import { encodeNull, encodeObjectIdentifier, encodeSequence } from "@suaveplan/crypto-rsa/asn1";
+
+const algorithmIdentifier = encodeSequence(
+    encodeObjectIdentifier(OID_RSA_ENCRYPTION),
+    encodeNull()
+);
+```
+
+## API Reference
+
+### `OID_RSA_ENCRYPTION: "1.2.840.113549.1.1.1"`
+
+The PKCS #1 `rsaEncryption` algorithm identifier per RFC 3279 §2.3.1, RFC 5280
+Appendix A, and RFC 8017 Appendix A.1.
+
+## Implementation Notes
+
+The constant is exposed as a string rather than a typed brand because
+`DerReader.readObjectIdentifier` returns plain strings, and direct equality
+checks remain trivially constant-time at the byte level. A branded type would
+add complexity without security benefit at this layer.