@kindgi/crypto 0.0.0-bootstrap.0 → 0.1.0

package/dist/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAIvE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,0CAA0C;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAE9C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,EAAE,EAAE,YAAY;IAChB,SAAS,EAAE,mBAAmB;IAC9B,SAAS,EAAE,mBAAmB;CACtB,CAAC;AAEX,gFAAgF;AAChF,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC;AAErD,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,yEAAyE;AACzE,MAAM,UAAU,qBAAqB;IACnC,OAAO,GAAG,qBAAqB,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,wBAAwB,CAAC;AAChE,CAAC;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,sEAAsE,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAC9F,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC,oDAAoD,CAAC,CAAC;QAC5F,UAAU,CAAC,IAAI,CAAC,GAAG,iBAAiB,IAAI,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAC5B,KAAuB;IAEvB,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO;QACL,IAAI,EAAE,IAAI;QACV,KAAK,EAAE;YACL,CAAC,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE;YAC9B,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC;YACpD,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,KAAK;SAC7C;KACF,CAAC;AACJ,CAAC;AA6BD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC;IACzD,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,eAAe,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7E,IAAI,EAAE,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACpF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC1F,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,gBAAgB,IAAI,iCAAiC,CAAC;IAC9E,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAChE,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,SAAS,EAAE,CAAC;QACjD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;IAC/D,CAAC;IACD,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEnE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,iBAAiB;YAAE,SAAS;QACtE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC/E,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,aAAa,CAAC,EAAU,EAAE,SAAiB,EAAE,IAAyB;IAC7E,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,SAAS,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5F,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,IAAI,CAAC,GAAW,EAAE,OAAe;IACxC,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;AAC5D,CAAC;AAED,+EAA+E;AAC/E,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,qBAAqB,CAAC;QACtD,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC;IACX,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED,SAAS,UAAU,CAAC,OAA8B,EAAE,IAAY;IAC9D,IAAI,OAAQ,OAA6B,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAI,OAAgD,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1E,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,CAAC;IACD,MAAM,MAAM,GAAG,OAA2E,CAAC;IAC3F,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI;YAAE,SAAS;QACzC,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7D,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IACvE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,7 +1,51 @@
 {
   "name": "@kindgi/crypto",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Kindgi™ cryptographic primitives. Ed25519 signatures for asymmetric use (signed audit bundles, provenance exports, deployment attestations) and HMAC-SHA256 for symmetric use (webhook payloads). Includes SigningKeyBinding interface + in-memory reference impl, PEM/base64 key format converters, and typed error interfaces. Pure Node built-ins, zero runtime deps. Deployments plug their own key store (KMS, Vault, env-var) via SigningKeyBinding.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/crypto"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/crypto#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/types": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "standardwebhooks": "^1.1.1",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/binding.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `SigningKeyBinding` — the seam between the crypto primitives and a
+ * deployment's key store. The framework does not persist key material;
+ * it never has direct access to a KMS. Instead, callers implement this
+ * binding against whatever store they run (an env-var-backed key for
+ * local dev, a cloud KMS or secrets vault in production, a hardware
+ * token).
+ *
+ * Consumers that need to sign or verify look up a key by `SigningKeyId`
+ * through the binding. The binding returns `null` when a key is not
+ * present — callers translate that to the appropriate domain error
+ * (e.g., "signing key for tenant T is not provisioned").
+ *
+ * Not defined here: rotation, revocation, tenant-scoped key selection.
+ * Those are lifecycle concerns handled outside this package.
+ */
+
+import type { SigningKeyId } from '@kindgi/types';
+
+/** Which signature algorithm the key is for. */
+export type SigningAlgorithm = 'ed25519' | 'hmac-sha256';
+
+/** Metadata about a key registered with a binding. */
+export interface SigningKeyDescriptor {
+  readonly keyId: SigningKeyId;
+  readonly algorithm: SigningAlgorithm;
+  /** ISO-8601 timestamp when the key was first registered with this binding. */
+  readonly createdAt: string;
+}
+
+/**
+ * A caller-provided key store. Deployments plug in KMS, env-var-backed,
+ * or in-memory-for-tests implementations. Framework code never persists
+ * or generates key material through this interface — it only reads.
+ *
+ * Contracts:
+ *   - `getPublicKey` returns raw bytes. For Ed25519, 32 bytes; for
+ *     HMAC-SHA256, the shared secret (the binding does not distinguish
+ *     the "public" side for symmetric algorithms; verifiers hold the
+ *     same secret as signers).
+ *   - `getPrivateKey` returns raw bytes. For Ed25519, 32-byte seed;
+ *     for HMAC-SHA256, the shared secret.
+ *   - `null` return means "no key by that id" — never throw.
+ *   - `listKeys` MUST NOT expose key material, only descriptors.
+ */
+export interface SigningKeyBinding {
+  getPublicKey(keyId: SigningKeyId): Uint8Array | null;
+  getPrivateKey(keyId: SigningKeyId): Uint8Array | null;
+  listKeys(): readonly SigningKeyDescriptor[];
+}
+
+/**
+ * In-memory implementation. Intended for tests and local development —
+ * production deployments implement `SigningKeyBinding` against their own
+ * KMS. Keys are held by strong reference; the binding does not touch
+ * disk or the network.
+ */
+export function createInMemorySigningKeyBinding(
+  entries: readonly {
+    readonly keyId: SigningKeyId;
+    readonly algorithm: SigningAlgorithm;
+    readonly publicKey: Uint8Array;
+    readonly privateKey: Uint8Array;
+    readonly createdAt?: string;
+  }[],
+): SigningKeyBinding {
+  const map = new Map<
+    SigningKeyId,
+    {
+      readonly publicKey: Uint8Array;
+      readonly privateKey: Uint8Array;
+      readonly descriptor: SigningKeyDescriptor;
+    }
+  >();
+  for (const entry of entries) {
+    if (map.has(entry.keyId)) {
+      throw new Error(`Duplicate SigningKeyId in binding: "${entry.keyId}"`);
+    }
+    map.set(entry.keyId, {
+      publicKey: entry.publicKey,
+      privateKey: entry.privateKey,
+      descriptor: {
+        keyId: entry.keyId,
+        algorithm: entry.algorithm,
+        createdAt: entry.createdAt ?? new Date().toISOString(),
+      },
+    });
+  }
+  return {
+    getPublicKey(keyId) {
+      return map.get(keyId)?.publicKey ?? null;
+    },
+    getPrivateKey(keyId) {
+      return map.get(keyId)?.privateKey ?? null;
+    },
+    listKeys() {
+      return Array.from(map.values(), (v) => v.descriptor);
+    },
+  };
+}

package/src/ed25519.ts

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Ed25519 digital signatures. Asymmetric: the signer holds a private key,
+ * verifiers hold only the public key. Used by signed audit-bundle exports,
+ * signed provenance exports, and any consumer that needs "prove this
+ * artifact came from a party holding the private key" without trusting the
+ * verifier.
+ *
+ * All APIs operate on raw 32-byte Uint8Arrays for keys. PEM / Base64
+ * serialization is offered as helpers — the wire encoding is DER SPKI
+ * (public) and DER PKCS8 (private).
+ */
+
+import {
+  type KeyObject,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as nodeSign,
+  verify as nodeVerify,
+} from 'node:crypto';
+
+import type { Result } from '@kindgi/types';
+
+import {
+  ED25519_PKCS8_LENGTH,
+  ED25519_RAW_KEY_BYTES,
+  ED25519_SPKI_LENGTH,
+  fromBase64,
+  fromPem,
+  toBase64,
+  toPem,
+  unwrapPrivateKeyPkcs8,
+  unwrapPublicKeySpki,
+  wrapPrivateKeyPkcs8,
+  wrapPublicKeySpki,
+} from './encoding.js';
+import { malformedKey, malformedSignature } from './errors.js';
+import type { CryptoError, MalformedKeyError } from './errors.js';
+
+/** Byte length of an Ed25519 signature (always 64). */
+export const ED25519_SIGNATURE_BYTES = 64;
+
+/** Raw 32-byte key material — the wire form Ed25519 primitives operate on. */
+export interface Ed25519KeyPair {
+  readonly publicKey: Uint8Array;
+  readonly privateKey: Uint8Array;
+}
+
+/**
+ * Generate a fresh Ed25519 key pair. Intended for tests, local development,
+ * and deployments that provision keys at boot. Production key material
+ * typically lives in a KMS / HSM and is loaded through `SigningKeyBinding`.
+ */
+export function generateEd25519KeyPair(): Ed25519KeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const spki = publicKey.export({ format: 'der', type: 'spki' });
+  const pkcs8 = privateKey.export({ format: 'der', type: 'pkcs8' });
+  const pubUnwrap = unwrapPublicKeySpki(new Uint8Array(spki));
+  const privUnwrap = unwrapPrivateKeyPkcs8(new Uint8Array(pkcs8));
+  if (pubUnwrap.kind === 'err' || privUnwrap.kind === 'err') {
+    throw new Error('generateEd25519KeyPair: unexpected Node key export shape');
+  }
+  return { publicKey: pubUnwrap.value, privateKey: privUnwrap.value };
+}
+
+/**
+ * Sign a message with an Ed25519 private key. Returns the 64-byte signature.
+ * Returns `Result` because the caller-supplied key may be malformed (wrong
+ * length, wrong bytes); underlying primitive errors (system-level) throw.
+ */
+export function signEd25519(
+  privateKey: Uint8Array,
+  message: Uint8Array,
+): Result<Uint8Array, MalformedKeyError> {
+  if (!(privateKey instanceof Uint8Array) || privateKey.length !== ED25519_RAW_KEY_BYTES) {
+    return malformedKey(
+      `Ed25519 private key must be ${ED25519_RAW_KEY_BYTES} raw bytes, got ${privateKey.length}`,
+    );
+  }
+  if (!(message instanceof Uint8Array)) {
+    return malformedKey('Ed25519 message must be a Uint8Array');
+  }
+  let keyObject: KeyObject;
+  try {
+    keyObject = createPrivateKey({
+      key: Buffer.from(wrapPrivateKeyPkcs8(privateKey)),
+      format: 'der',
+      type: 'pkcs8',
+    });
+  } catch (cause) {
+    return malformedKey('Ed25519 private key rejected by underlying primitive', cause);
+  }
+  const signature = nodeSign(null, message, keyObject);
+  return { kind: 'ok', value: new Uint8Array(signature) };
+}
+
+/**
+ * Verify an Ed25519 signature. Returns `true` on cryptographic success,
+ * `false` on cryptographic failure. Malformed key/signature bytes return
+ * a typed error — the caller distinguishes "key/sig shape is wrong"
+ * (an operational bug) from "signature does not match" (an authenticity
+ * failure). Never returns `true` for a shape-error input.
+ */
+export function verifyEd25519(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+): Result<boolean, CryptoError> {
+  if (!(publicKey instanceof Uint8Array) || publicKey.length !== ED25519_RAW_KEY_BYTES) {
+    return malformedKey(
+      `Ed25519 public key must be ${ED25519_RAW_KEY_BYTES} raw bytes, got ${publicKey.length}`,
+    );
+  }
+  if (!(message instanceof Uint8Array)) {
+    return malformedKey('Ed25519 message must be a Uint8Array');
+  }
+  if (!(signature instanceof Uint8Array) || signature.length !== ED25519_SIGNATURE_BYTES) {
+    return malformedSignature(
+      `Ed25519 signature must be ${ED25519_SIGNATURE_BYTES} bytes, got ${signature.length}`,
+    );
+  }
+  let keyObject: KeyObject;
+  try {
+    keyObject = createPublicKey({
+      key: Buffer.from(wrapPublicKeySpki(publicKey)),
+      format: 'der',
+      type: 'spki',
+    });
+  } catch (cause) {
+    return malformedKey('Ed25519 public key rejected by underlying primitive', cause);
+  }
+  const ok = nodeVerify(null, message, keyObject, signature);
+  return { kind: 'ok', value: ok };
+}
+
+// ============ serialization helpers ============
+
+const PEM_PUBLIC_LABEL = 'PUBLIC KEY';
+const PEM_PRIVATE_LABEL = 'PRIVATE KEY';
+
+/**
+ * Serialize a raw Ed25519 public key to PEM (standard "PUBLIC KEY" label
+ * wrapping a DER SPKI envelope). Interoperable with OpenSSL and any
+ * consumer that speaks RFC 5280 SPKI.
+ */
+export function serializePublicKeyPem(publicKey: Uint8Array): string {
+  return toPem(wrapPublicKeySpki(publicKey), PEM_PUBLIC_LABEL);
+}
+
+/**
+ * Parse a PEM "PUBLIC KEY" (DER SPKI Ed25519) into raw 32 bytes.
+ */
+export function parsePublicKeyPem(pem: string): Result<Uint8Array, CryptoError> {
+  const der = fromPem(pem, PEM_PUBLIC_LABEL);
+  if (der.kind === 'err') return der;
+  if (der.value.length !== ED25519_SPKI_LENGTH) {
+    return malformedKey(
+      `PEM decoded to ${der.value.length} bytes; Ed25519 SPKI is ${ED25519_SPKI_LENGTH}`,
+    );
+  }
+  return unwrapPublicKeySpki(der.value);
+}
+
+/**
+ * Serialize a raw Ed25519 private key seed to PEM (standard "PRIVATE KEY"
+ * label wrapping a DER PKCS8 envelope). WARNING: private key material —
+ * never log this, never emit it in journals, never send it over the wire
+ * to a verifier.
+ */
+export function serializePrivateKeyPem(privateKey: Uint8Array): string {
+  return toPem(wrapPrivateKeyPkcs8(privateKey), PEM_PRIVATE_LABEL);
+}
+
+/** Parse a PEM "PRIVATE KEY" (DER PKCS8 Ed25519) into raw 32 bytes. */
+export function parsePrivateKeyPem(pem: string): Result<Uint8Array, CryptoError> {
+  const der = fromPem(pem, PEM_PRIVATE_LABEL);
+  if (der.kind === 'err') return der;
+  if (der.value.length !== ED25519_PKCS8_LENGTH) {
+    return malformedKey(
+      `PEM decoded to ${der.value.length} bytes; Ed25519 PKCS8 is ${ED25519_PKCS8_LENGTH}`,
+    );
+  }
+  return unwrapPrivateKeyPkcs8(der.value);
+}
+
+/**
+ * Serialize a raw Ed25519 public key to base64-encoded DER SPKI. This is
+ * the compact JSON-wire form — smaller than PEM (no header lines) and
+ * still interoperable with OpenSSL by wrapping in PEM downstream.
+ */
+export function serializePublicKeyBase64(publicKey: Uint8Array): string {
+  return toBase64(wrapPublicKeySpki(publicKey));
+}
+
+/** Parse a base64-encoded DER SPKI Ed25519 public key into raw 32 bytes. */
+export function parsePublicKeyBase64(b64: string): Result<Uint8Array, CryptoError> {
+  const der = fromBase64(b64);
+  if (der.kind === 'err') return der;
+  if (der.value.length !== ED25519_SPKI_LENGTH) {
+    return malformedKey(
+      `Base64 decoded to ${der.value.length} bytes; Ed25519 SPKI is ${ED25519_SPKI_LENGTH}`,
+    );
+  }
+  return unwrapPublicKeySpki(der.value);
+}
+
+/**
+ * Serialize a raw Ed25519 private key seed to base64-encoded DER PKCS8.
+ * WARNING: private key material. See `serializePrivateKeyPem` note.
+ */
+export function serializePrivateKeyBase64(privateKey: Uint8Array): string {
+  return toBase64(wrapPrivateKeyPkcs8(privateKey));
+}
+
+/** Parse a base64-encoded DER PKCS8 Ed25519 private key into raw 32 bytes. */
+export function parsePrivateKeyBase64(b64: string): Result<Uint8Array, CryptoError> {
+  const der = fromBase64(b64);
+  if (der.kind === 'err') return der;
+  if (der.value.length !== ED25519_PKCS8_LENGTH) {
+    return malformedKey(
+      `Base64 decoded to ${der.value.length} bytes; Ed25519 PKCS8 is ${ED25519_PKCS8_LENGTH}`,
+    );
+  }
+  return unwrapPrivateKeyPkcs8(der.value);
+}

package/src/encoding.ts

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * DER envelope + PEM wrapping helpers for Ed25519 keys.
+ *
+ * Ed25519 keys have a fixed 32-byte raw form. Interop with Node's
+ * `crypto.createPublicKey` / `createPrivateKey` requires wrapping the raw
+ * bytes in a standard envelope (SPKI for public, PKCS8 for private) —
+ * fixed-prefix DER structures whose only variable part is the 32-byte key
+ * material itself. Doing this by hand keeps the package free of ASN.1
+ * dependencies and portable across Node / Bun / Deno.
+ *
+ * The prefixes below encode the AlgorithmIdentifier for Ed25519
+ * (OID 1.3.101.112, no parameters) plus the outer SEQUENCE / OCTET STRING
+ * wrappers that SPKI (RFC 5280) and PKCS8 (RFC 5958) require. They are
+ * constant for Ed25519.
+ */
+
+import type { Result } from '@kindgi/types';
+
+import { malformedKey, unsupportedFormat } from './errors.js';
+import type { MalformedKeyError, UnsupportedFormatError } from './errors.js';
+
+export const ED25519_RAW_KEY_BYTES = 32;
+
+// SPKI (SubjectPublicKeyInfo) prefix for Ed25519 (12 bytes). Full envelope
+// is 44 bytes: prefix (12) + raw public key (32).
+const ED25519_SPKI_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+export const ED25519_SPKI_LENGTH = ED25519_SPKI_PREFIX.length + ED25519_RAW_KEY_BYTES; // 44
+
+// PKCS8 (PrivateKeyInfo) prefix for Ed25519 (16 bytes). Full envelope is
+// 48 bytes: prefix (16) + raw private key seed (32).
+const ED25519_PKCS8_PREFIX = new Uint8Array([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+export const ED25519_PKCS8_LENGTH = ED25519_PKCS8_PREFIX.length + ED25519_RAW_KEY_BYTES; // 48
+
+/** Wrap a raw 32-byte Ed25519 public key in a DER SPKI envelope. */
+export function wrapPublicKeySpki(rawPublicKey: Uint8Array): Uint8Array {
+  if (rawPublicKey.length !== ED25519_RAW_KEY_BYTES) {
+    throw new Error(
+      `Ed25519 raw public key must be ${ED25519_RAW_KEY_BYTES} bytes, got ${rawPublicKey.length}`,
+    );
+  }
+  const out = new Uint8Array(ED25519_SPKI_LENGTH);
+  out.set(ED25519_SPKI_PREFIX, 0);
+  out.set(rawPublicKey, ED25519_SPKI_PREFIX.length);
+  return out;
+}
+
+/** Wrap a raw 32-byte Ed25519 private key seed in a DER PKCS8 envelope. */
+export function wrapPrivateKeyPkcs8(rawPrivateKey: Uint8Array): Uint8Array {
+  if (rawPrivateKey.length !== ED25519_RAW_KEY_BYTES) {
+    throw new Error(
+      `Ed25519 raw private key must be ${ED25519_RAW_KEY_BYTES} bytes, got ${rawPrivateKey.length}`,
+    );
+  }
+  const out = new Uint8Array(ED25519_PKCS8_LENGTH);
+  out.set(ED25519_PKCS8_PREFIX, 0);
+  out.set(rawPrivateKey, ED25519_PKCS8_PREFIX.length);
+  return out;
+}
+
+/** Strip the DER SPKI envelope off an Ed25519 public key, returning the 32 raw bytes. */
+export function unwrapPublicKeySpki(spki: Uint8Array): Result<Uint8Array, MalformedKeyError> {
+  if (spki.length !== ED25519_SPKI_LENGTH) {
+    return malformedKey(
+      `Ed25519 SPKI envelope must be ${ED25519_SPKI_LENGTH} bytes, got ${spki.length}`,
+    );
+  }
+  for (let i = 0; i < ED25519_SPKI_PREFIX.length; i++) {
+    if (spki[i] !== ED25519_SPKI_PREFIX[i]) {
+      return malformedKey('Ed25519 SPKI prefix mismatch — not an Ed25519 public key envelope');
+    }
+  }
+  return { kind: 'ok', value: spki.slice(ED25519_SPKI_PREFIX.length) };
+}
+
+/** Strip the DER PKCS8 envelope off an Ed25519 private key, returning the 32 raw seed bytes. */
+export function unwrapPrivateKeyPkcs8(pkcs8: Uint8Array): Result<Uint8Array, MalformedKeyError> {
+  if (pkcs8.length !== ED25519_PKCS8_LENGTH) {
+    return malformedKey(
+      `Ed25519 PKCS8 envelope must be ${ED25519_PKCS8_LENGTH} bytes, got ${pkcs8.length}`,
+    );
+  }
+  for (let i = 0; i < ED25519_PKCS8_PREFIX.length; i++) {
+    if (pkcs8[i] !== ED25519_PKCS8_PREFIX[i]) {
+      return malformedKey('Ed25519 PKCS8 prefix mismatch — not an Ed25519 private key envelope');
+    }
+  }
+  return { kind: 'ok', value: pkcs8.slice(ED25519_PKCS8_PREFIX.length) };
+}
+
+// ============ base64 ============
+
+/** Encode bytes as standard base64. */
+export function toBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+/** Decode a base64 string into bytes. Returns a typed error on invalid input. */
+export function fromBase64(b64: string): Result<Uint8Array, MalformedKeyError> {
+  if (typeof b64 !== 'string' || b64.length === 0) {
+    return malformedKey('base64 input must be a non-empty string');
+  }
+  // Buffer.from is lenient about non-base64 characters; validate strictly.
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) {
+    return malformedKey('base64 input contains characters outside the standard alphabet');
+  }
+  try {
+    const buf = Buffer.from(b64, 'base64');
+    // Round-trip to detect padding / silent truncation.
+    if (buf.toString('base64').replace(/=+$/u, '') !== b64.replace(/=+$/u, '')) {
+      return malformedKey('base64 input did not round-trip cleanly');
+    }
+    return { kind: 'ok', value: new Uint8Array(buf) };
+  } catch (cause) {
+    return malformedKey('base64 decode failed', cause);
+  }
+}
+
+// ============ PEM ============
+
+/** Wrap DER bytes in a PEM envelope with the given label. */
+export function toPem(derBytes: Uint8Array, label: string): string {
+  const b64 = toBase64(derBytes);
+  const lines: string[] = [];
+  for (let i = 0; i < b64.length; i += 64) lines.push(b64.slice(i, i + 64));
+  return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----\n`;
+}
+
+/**
+ * Parse a PEM envelope for the given label. Rejects unexpected labels,
+ * missing header/footer, or base64 payload that does not decode cleanly.
+ */
+export function fromPem(
+  pem: string,
+  expectedLabel: string,
+): Result<Uint8Array, MalformedKeyError | UnsupportedFormatError> {
+  if (typeof pem !== 'string' || pem.length === 0) {
+    return malformedKey('PEM input must be a non-empty string');
+  }
+  const trimmed = pem.trim();
+  const header = `-----BEGIN ${expectedLabel}-----`;
+  const footer = `-----END ${expectedLabel}-----`;
+  const startIdx = trimmed.indexOf(header);
+  const endIdx = trimmed.indexOf(footer);
+  if (startIdx === -1 || endIdx === -1) {
+    // Detect a *different* PEM label (e.g., someone passed an RSA key here).
+    const otherLabelMatch = /-----BEGIN ([^-]+)-----/.exec(trimmed);
+    if (otherLabelMatch && otherLabelMatch[1] !== expectedLabel) {
+      return unsupportedFormat(
+        `PEM label mismatch — expected "${expectedLabel}", got "${otherLabelMatch[1]}"`,
+      );
+    }
+    return malformedKey(`PEM envelope missing "${expectedLabel}" header/footer`);
+  }
+  if (endIdx < startIdx) {
+    return malformedKey('PEM footer appears before header');
+  }
+  const body = trimmed.slice(startIdx + header.length, endIdx).replace(/\s+/g, '');
+  return fromBase64(body);
+}

package/src/errors.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Typed errors returned from the crypto primitives. Cryptographic operations
+ * fall into two buckets: (a) caller-recoverable errors — malformed key
+ * material, wrong-shape input, bad PEM headers — and (b) system-level errors
+ * from the underlying primitive that a caller cannot recover from. The
+ * former return as `Result<T, CryptoError>`; the latter throw. This file
+ * declares (a).
+ */
+
+export type CryptoError = MalformedKeyError | MalformedSignatureError | UnsupportedFormatError;
+
+/**
+ * Key material could not be parsed. Covers malformed PEM headers, wrong
+ * base64, DER envelopes with unexpected OIDs, and byte-length mismatches
+ * for the declared algorithm.
+ */
+export interface MalformedKeyError {
+  readonly code: 'malformed-key';
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+/**
+ * Signature bytes are the wrong length or shape for the declared algorithm.
+ * Returned by verify when the caller-supplied signature can be rejected
+ * without invoking the underlying primitive.
+ */
+export interface MalformedSignatureError {
+  readonly code: 'malformed-signature';
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+/**
+ * A serialization format was requested that this package does not support
+ * (e.g., a PEM label the parser does not recognize).
+ */
+export interface UnsupportedFormatError {
+  readonly code: 'unsupported-format';
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+export function malformedKey(
+  message: string,
+  cause?: unknown,
+): { readonly kind: 'err'; readonly error: MalformedKeyError } {
+  return {
+    kind: 'err',
+    error:
+      cause === undefined
+        ? { code: 'malformed-key', message }
+        : { code: 'malformed-key', message, cause },
+  };
+}
+
+export function malformedSignature(
+  message: string,
+  cause?: unknown,
+): { readonly kind: 'err'; readonly error: MalformedSignatureError } {
+  return {
+    kind: 'err',
+    error:
+      cause === undefined
+        ? { code: 'malformed-signature', message }
+        : { code: 'malformed-signature', message, cause },
+  };
+}
+
+export function unsupportedFormat(
+  message: string,
+  cause?: unknown,
+): { readonly kind: 'err'; readonly error: UnsupportedFormatError } {
+  return {
+    kind: 'err',
+    error:
+      cause === undefined
+        ? { code: 'unsupported-format', message }
+        : { code: 'unsupported-format', message, cause },
+  };
+}