Initial Commit

packages/security-stack/security/x509/src/asn1/oid.md

@@ -0,0 +1,52 @@
+# `asn1/oid` — OBJECT IDENTIFIER encode / decode
+
+## Purpose
+
+Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensions, key purposes, name attributes, and policies — every dispatch site in this package keys on a dotted-decimal string returned by `decodeOid`. The encoder is needed only for synthesising test fixtures since `parseCertificate` never re-emits OIDs onto the wire.
+
+## Features
+
+- Folded first-arc decoding (X.690 paragraph 8.19.4): the leading sub-identifier splits into two arcs by the `value < 80` / `value >= 80` rule.
+- Minimal sub-identifier check — leading `0x80` byte on a sub-identifier is rejected as non-minimal.
+- Truncation guard — a sub-identifier that ends mid-byte (high-bit set on final byte) is rejected.
+- Symmetric encoder — produces the same byte sequence the decoder would consume.
+
+## Usage: Basic Example
+
+```ts
+import { decodeOid, encodeOid } from "@suaveplan/x509/asn1";
+
+const dotted = decodeOid(new Uint8Array([0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x0b]));
+// "1.2.840.113549.1.1.11" (sha256WithRSAEncryption)
+
+const back = encodeOid("1.2.840.113549.1.1.11");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { decodeOid, encodeOid } from "@suaveplan/x509/asn1";
+
+// Round-trip every OID in a recognised set:
+const OIDS = [
+    "2.5.29.17",       // subjectAltName
+    "2.5.29.19",       // basicConstraints
+    "1.3.101.112",     // id-Ed25519
+];
+for (const o of OIDS) {
+    const body = encodeOid(o);
+    const back = decodeOid(body);
+    if (back !== o) throw new Error("round-trip mismatch");
+}
+```
+
+## API Reference
+
+- `decodeOid(body: Uint8Array): string` — OID body (without outer tag-length) into dotted-decimal string. Throws `X509Error(ASN1_MALFORMED)` on empty body, non-minimal sub-id, or truncation.
+- `encodeOid(dotted: string): Uint8Array` — dotted-decimal into OID body. Throws on negative or non-decimal arcs, or invalid first two arcs.
+
+## Implementation Notes
+
+- Decoder uses `bigint` arithmetic for sub-identifiers — production OIDs occasionally exceed 32 bits (e.g. some experimental private-enterprise IDs).
+- `arc1 ∈ {0, 1, 2}`; `arc2 < 40` when `arc1 < 2`. The encoder validates this constraint and folds correctly.
+- Empty OIDs are rejected — every X.509 production that carries an OID requires at least two arcs.