@robota-sdk/agent-keyring 0.0.0-stage → 3.1.1

package/src/runtime-certificate.ts

@@ -0,0 +1,129 @@
+/**
+ * What a runtime is, as its owner vouches for it: an instance key bound to one runtime start.
+ *
+ * A runtime cannot prove it belongs to the owner by anything it can show on its own, because every
+ * same-user program can show the same things: a file, a socket path, a registration. So the owner
+ * signs, with the attach key only the passphrase reaches, the runtime's memory-only instance key
+ * together with the start it belongs to (the binding). A client that later checks this certificate
+ * under the attach key it derived itself knows the runtime is one its owner certified, for exactly
+ * this start; a certificate made by any other keyring, or for any other instance or start, fails.
+ */
+import { Buffer } from 'node:buffer';
+
+import { concatLengthPrefixed, isBytes, utf8 } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { KEY_BYTES } from './kdf.js';
+import { SIGNATURE_BYTES, verifyEd25519 } from './signatures.js';
+
+/** The runtime start a link and a certificate are bound to. Public values. */
+export interface ILinkBinding {
+  readonly runtimeId: string;
+  readonly generation: string;
+}
+
+/**
+ * What a runtime is told about its owner by its spawner: the owner's attach public key and the
+ * certificate of the runtime's own instance key. Public values, held only in runtime memory: a
+ * same-user-writable file is never a trust anchor.
+ */
+export interface ITrustRoot {
+  readonly attachPublicKey: Uint8Array;
+  /** Ed25519 under the attach key over the certificate message (see {@link runtimeCertificateMessage}). */
+  readonly certificate: Uint8Array;
+}
+
+/** Versioned like every derivation label: a certificate of one version never verifies as another. */
+export const RUNTIME_CERTIFICATE_LABEL = 'robota/link/v1/runtime-cert';
+
+/** The longest runtime id or generation a binding carries. */
+export const MAX_BINDING_PART_LENGTH = 128;
+
+// Printable ASCII without separators: what a registration's ids are made of, and nothing a
+// terminal, a log line or a length prefix could read twice.
+const BINDING_PART_PATTERN = /^[A-Za-z0-9._:-]+$/u;
+const BINDING_KEYS = ['generation', 'runtimeId'];
+
+function isBindingPart(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_BINDING_PART_LENGTH &&
+    BINDING_PART_PATTERN.test(value)
+  );
+}
+
+/**
+ * A fresh binding built from `value`, or `invalid-argument`. Exactly the two fields, each 1 to
+ * {@link MAX_BINDING_PART_LENGTH} characters of `[A-Za-z0-9._:-]`, so every binding has one byte
+ * spelling and a decoder never meets a value it would have to reinterpret.
+ */
+export function checkLinkBinding(value: unknown): ILinkBinding {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new KeyringError('invalid-argument', 'A link binding is a runtime id and a generation.');
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  if (
+    keys.length !== BINDING_KEYS.length ||
+    keys.some((key, index) => key !== BINDING_KEYS[index]) ||
+    !isBindingPart(record['runtimeId']) ||
+    !isBindingPart(record['generation'])
+  ) {
+    throw new KeyringError(
+      'invalid-argument',
+      `A link binding's runtime id and generation are 1-${MAX_BINDING_PART_LENGTH} characters of [A-Za-z0-9._:-].`,
+    );
+  }
+  return { runtimeId: record['runtimeId'], generation: record['generation'] };
+}
+
+/** The bytes of a binding part as it is decoded from the wire, or `undefined` when it is not one. */
+export function decodeBindingPart(bytes: Uint8Array): string | undefined {
+  if (bytes.length === 0 || bytes.length > MAX_BINDING_PART_LENGTH) return undefined;
+  // ASCII only, so latin1 maps each byte to exactly the character the pattern then checks.
+  const text = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('latin1');
+  return isBindingPart(text) ? text : undefined;
+}
+
+export function requireInstanceKey(value: unknown): Uint8Array {
+  if (!isBytes(value) || value.length !== KEY_BYTES) {
+    throw new KeyringError('invalid-argument', 'An instance public key is exactly 32 bytes.');
+  }
+  return value;
+}
+
+/** `label | instance key | runtime id | generation`, each part length-prefixed. */
+export function runtimeCertificateMessage(
+  instancePublicKey: Uint8Array,
+  binding: ILinkBinding,
+): Buffer {
+  const instance = requireInstanceKey(instancePublicKey);
+  const checked = checkLinkBinding(binding);
+  return concatLengthPrefixed([
+    utf8(RUNTIME_CERTIFICATE_LABEL),
+    instance,
+    utf8(checked.runtimeId),
+    utf8(checked.generation),
+  ]);
+}
+
+/** Whether `root` certifies `instancePublicKey` for `binding` under the attach key `root` names. */
+export function certifies(
+  root: ITrustRoot,
+  instancePublicKey: Uint8Array,
+  binding: ILinkBinding,
+): boolean {
+  if (
+    !isBytes(root.attachPublicKey) ||
+    root.attachPublicKey.length !== KEY_BYTES ||
+    !isBytes(root.certificate) ||
+    root.certificate.length !== SIGNATURE_BYTES
+  ) {
+    return false;
+  }
+  return verifyEd25519(
+    root.attachPublicKey,
+    runtimeCertificateMessage(instancePublicKey, binding),
+    root.certificate,
+  );
+}

package/src/runtime-identity.ts

@@ -0,0 +1,166 @@
+/**
+ * A runtime's identity on the owner link: the crypto state a served runtime holds, and nothing else.
+ *
+ * - An Ed25519 instance key made at start, in memory only, so no file or other process can stand in
+ *   for this runtime; its public half is what the owner certifies.
+ * - The spawner key from the one exchange over the inherited pair: spawner standing, until the trust
+ *   root is installed.
+ * - The trust root, once its spawner installed it: the owner's attach public key and the certificate
+ *   of this instance for this runtime start. From then on spawner standing is gone for good, and only
+ *   a client that proves the attach key is admitted.
+ *
+ * Installing a root checks that it certifies this instance for the given binding, under the attach
+ * key it names; which link may install it, and when, is the runtime custody's decision.
+ */
+import type { Buffer } from 'node:buffer';
+
+import { isBytes, wipe } from './bytes.js';
+import { KeyringError, LinkRefusedError } from './errors.js';
+import { ed25519KeyPairFromSeed, type IKeyPair } from './key-pairs.js';
+import { KEY_BYTES } from './kdf.js';
+import { SYSTEM_LINK_ENTROPY, type ILinkEntropy } from './link-entropy.js';
+import {
+  certifies,
+  checkLinkBinding,
+  type ILinkBinding,
+  type ITrustRoot,
+} from './runtime-certificate.js';
+import { SIGNATURE_BYTES } from './signatures.js';
+import { answerSpawnerExchange } from './spawner-exchange.js';
+
+export interface IRuntimeIdentity {
+  /** The instance public key, the value the owner certifies. */
+  readonly instancePublicKey: Uint8Array;
+  /** Whether the spawner exchange ran and its key is still held. */
+  readonly spawnerKeyHeld: boolean;
+  /** Whether a trust root is installed. */
+  readonly certified: boolean;
+  /**
+   * Answers the spawner's first message with this runtime's ephemeral and instance public key, and
+   * keeps the spawner key. Once: a second call is refused, even after a refused first one.
+   */
+  answerSpawnerExchange(message: Uint8Array): Uint8Array;
+  /**
+   * Keeps `root` when it certifies this instance for `binding`, and forgets the spawner key. Once,
+   * and only while the spawner key is held. A refused root changes nothing.
+   */
+  installTrustRoot(root: ITrustRoot, binding: ILinkBinding): void;
+}
+
+/** The root a runtime was certified with, and the binding it certifies. */
+export interface IRuntimeTrust {
+  readonly root: ITrustRoot;
+  readonly binding: ILinkBinding;
+}
+
+/** What only the link responder reaches. */
+export interface IRuntimeIdentitySecrets {
+  readonly instance: IKeyPair;
+  /** Where the responder draws its ephemerals and nonces: the identity's own source. */
+  readonly entropy: ILinkEntropy;
+  spawnerKey(): Buffer | undefined;
+  trust(): IRuntimeTrust | undefined;
+}
+
+const SECRETS = new WeakMap<IRuntimeIdentity, IRuntimeIdentitySecrets>();
+
+function checkTrustRoot(value: unknown): ITrustRoot {
+  const root = value as Partial<ITrustRoot> | null;
+  if (
+    typeof root !== 'object' ||
+    root === null ||
+    !isBytes(root.attachPublicKey) ||
+    root.attachPublicKey.length !== KEY_BYTES ||
+    !isBytes(root.certificate) ||
+    root.certificate.length !== SIGNATURE_BYTES
+  ) {
+    throw new KeyringError(
+      'invalid-argument',
+      'A trust root is a 32-byte attach public key and a 64-byte certificate.',
+    );
+  }
+  return {
+    attachPublicKey: Uint8Array.from(root.attachPublicKey),
+    certificate: Uint8Array.from(root.certificate),
+  };
+}
+
+class RuntimeIdentity implements IRuntimeIdentity {
+  readonly #instance: IKeyPair;
+  readonly #entropy: ILinkEntropy;
+  #exchanged = false;
+  #spawnerKey: Buffer | undefined;
+  #trust: IRuntimeTrust | undefined;
+
+  constructor(entropy: ILinkEntropy) {
+    this.#entropy = entropy;
+    const seed = entropy.seed();
+    try {
+      this.#instance = ed25519KeyPairFromSeed(seed);
+    } finally {
+      wipe(seed);
+    }
+    SECRETS.set(this, {
+      instance: this.#instance,
+      entropy,
+      spawnerKey: () => this.#spawnerKey,
+      trust: () => this.#trust,
+    });
+  }
+
+  get instancePublicKey(): Uint8Array {
+    return Uint8Array.from(this.#instance.publicKey);
+  }
+
+  get spawnerKeyHeld(): boolean {
+    return this.#spawnerKey !== undefined;
+  }
+
+  get certified(): boolean {
+    return this.#trust !== undefined;
+  }
+
+  answerSpawnerExchange(message: Uint8Array): Uint8Array {
+    if (this.#exchanged) throw new LinkRefusedError('out-of-order');
+    this.#exchanged = true;
+    const { reply, spawnerKey } = answerSpawnerExchange(
+      message,
+      this.#instance.publicKey,
+      this.#entropy,
+    );
+    this.#spawnerKey = spawnerKey;
+    return reply;
+  }
+
+  installTrustRoot(root: ITrustRoot, binding: ILinkBinding): void {
+    const checkedRoot = checkTrustRoot(root);
+    const checkedBinding = checkLinkBinding(binding);
+    if (this.#trust !== undefined) throw new LinkRefusedError('already-certified');
+    if (this.#spawnerKey === undefined) throw new LinkRefusedError('spawner-unavailable');
+    if (!certifies(checkedRoot, this.#instance.publicKey, checkedBinding)) {
+      throw new LinkRefusedError('certificate-mismatch');
+    }
+    this.#trust = { root: checkedRoot, binding: checkedBinding };
+    wipe(this.#spawnerKey);
+    this.#spawnerKey = undefined;
+  }
+}
+
+/** {@link createRuntimeIdentity} drawing from `entropy`; the package's own tests pass fixed values. */
+export function createRuntimeIdentityWith(entropy: ILinkEntropy): IRuntimeIdentity {
+  return new RuntimeIdentity(entropy);
+}
+
+/** A new runtime identity with a fresh instance key, uncertified and before its spawner exchange. */
+export function createRuntimeIdentity(): IRuntimeIdentity {
+  return createRuntimeIdentityWith(SYSTEM_LINK_ENTROPY);
+}
+
+/** Package-private: what the link responder needs of an identity this package made. */
+export function runtimeIdentitySecrets(identity: IRuntimeIdentity): IRuntimeIdentitySecrets {
+  const secrets = SECRETS.get(identity);
+  if (secrets === undefined) {
+    throw new KeyringError('invalid-argument', 'This is not a runtime identity this package made.');
+  }
+  return secrets;
+}

package/src/sealing.ts

@@ -0,0 +1,281 @@
+import { Buffer } from 'node:buffer';
+import { diffieHellman, generateKeyPairSync, randomBytes, type KeyObject } from 'node:crypto';
+
+import { gcmDecrypt, gcmEncrypt, GCM_IV_BYTES, GCM_TAG_BYTES } from './aead.js';
+import { concatLengthPrefixed, isBytes, wipe } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { rawPublicKey, x25519PublicKeyFromRaw } from './key-pairs.js';
+import { hkdf32, KEY_BYTES } from './kdf.js';
+
+/** The first byte of every sealed key, record and blob. Authenticated, so it cannot be downgraded. */
+export const SEALED_FORMAT_VERSION = 1;
+
+/** `info` of the HKDF that turns the ECDH secret into the key that wraps an artifact key. */
+export const ARTIFACT_KEY_WRAP_LABEL = 'robota/keyring/v1/dek-wrap';
+
+const VERSION_BYTES = 1;
+/** version | ephemeral X25519 public key | IV | wrapped key + tag */
+export const SEALED_KEY_BYTES =
+  VERSION_BYTES + KEY_BYTES + GCM_IV_BYTES + KEY_BYTES + GCM_TAG_BYTES;
+/** version | nonce | tag, around the ciphertext */
+export const RECORD_OVERHEAD_BYTES = VERSION_BYTES + GCM_IV_BYTES + GCM_TAG_BYTES;
+
+function requireBytes(value: unknown, what: string, length?: number): Uint8Array {
+  if (!isBytes(value) || (length !== undefined && value.length !== length)) {
+    throw new KeyringError(
+      'invalid-argument',
+      length === undefined
+        ? `The ${what} must be a Uint8Array.`
+        : `The ${what} must be a Uint8Array of exactly ${length} bytes.`,
+    );
+  }
+  return value;
+}
+
+function requireSealingPrivateKey(value: unknown): KeyObject {
+  const key = value as KeyObject | undefined;
+  if (
+    typeof key !== 'object' ||
+    key === null ||
+    key.type !== 'private' ||
+    key.asymmetricKeyType !== 'x25519'
+  ) {
+    throw new KeyringError(
+      'invalid-argument',
+      'The sealing private key must be an X25519 private KeyObject.',
+    );
+  }
+  return key;
+}
+
+/** The AAD the AEAD actually authenticates: the format version plus the caller's context. */
+function boundAad(callerAad: unknown): Buffer {
+  return concatLengthPrefixed([
+    Buffer.from([SEALED_FORMAT_VERSION]),
+    requireBytes(callerAad, 'aad'),
+  ]);
+}
+
+/**
+ * Both ends of the ECDH mix both public keys into the HKDF salt, so the wrapping key is bound to
+ * this exact sender/recipient pair and not only to the shared secret.
+ */
+function deriveWrapKey(
+  sharedSecret: Buffer,
+  ephemeralPublicKey: Uint8Array,
+  recipientPublicKey: Uint8Array,
+): Buffer {
+  const salt = Buffer.concat([ephemeralPublicKey, recipientPublicKey]);
+  try {
+    return hkdf32(sharedSecret, ARTIFACT_KEY_WRAP_LABEL, salt);
+  } finally {
+    wipe(sharedSecret);
+  }
+}
+
+/** A fresh ephemeral X25519 keypair; a host that cannot make one fails as `kdf-failed`. */
+function generateEphemeralKeyPair(): {
+  readonly privateKey: KeyObject;
+  readonly publicKey: Buffer;
+} {
+  try {
+    const ephemeral = generateKeyPairSync('x25519');
+    return { privateKey: ephemeral.privateKey, publicKey: rawPublicKey(ephemeral.publicKey) };
+  } catch {
+    throw new KeyringError('kdf-failed', 'The key derivation could not run on this host.');
+  }
+}
+
+/** A fresh random 256-bit data-encryption key (DEK) for one artifact. The caller wipes it after use. */
+export function generateArtifactKey(): Buffer {
+  return randomBytes(KEY_BYTES);
+}
+
+/**
+ * Seals `artifactKey` to the sealing PUBLIC key (ECIES: fresh ephemeral X25519 key, ECDH, HKDF-SHA256,
+ * AES-256-GCM). Only the public key is needed, so a process that never unlocked the keyring can
+ * still produce artifacts that only the owner can open. Every call uses a new ephemeral key and IV,
+ * so sealing the same key twice yields different bytes.
+ *
+ * `aad` is authenticated, not stored: the caller must present the same bytes to open it. Put the
+ * artifact id in it, so a sealed key cannot be moved to another artifact.
+ */
+export function sealArtifactKey(
+  sealingPublicKey: Uint8Array,
+  artifactKey: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  const recipientRaw = requireBytes(sealingPublicKey, 'sealing public key', KEY_BYTES);
+  requireBytes(artifactKey, 'artifact key', KEY_BYTES);
+  const bound = boundAad(aad);
+  const recipient = x25519PublicKeyFromRaw(recipientRaw);
+  const ephemeral = generateEphemeralKeyPair();
+  const ephemeralPublic = ephemeral.publicKey;
+  let sharedSecret: Buffer;
+  try {
+    sharedSecret = diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipient });
+  } catch {
+    // A low-order point (for example an all-zero key written into the file) has no usable secret.
+    throw new KeyringError(
+      'invalid-argument',
+      'The sealing public key cannot be used for key agreement.',
+    );
+  }
+  const wrapKey = deriveWrapKey(sharedSecret, ephemeralPublic, recipientRaw);
+  try {
+    const iv = randomBytes(GCM_IV_BYTES);
+    const wrapped = gcmEncrypt(wrapKey, iv, artifactKey, bound);
+    return Buffer.concat([Buffer.from([SEALED_FORMAT_VERSION]), ephemeralPublic, iv, wrapped]);
+  } finally {
+    wipe(wrapKey);
+  }
+}
+
+function requireSealedVersion(bytes: Uint8Array): void {
+  if (bytes.length === 0) {
+    throw new KeyringError('malformed-ciphertext', 'The sealed data is empty.');
+  }
+  if (bytes[0] !== SEALED_FORMAT_VERSION) {
+    throw new KeyringError(
+      'unsupported-version',
+      'The sealed data uses a format this build does not support.',
+    );
+  }
+}
+
+/**
+ * Opens a key produced by {@link sealArtifactKey}. Needs the unlocked sealing private key. The
+ * caller owns and wipes the returned key.
+ */
+export function openArtifactKey(
+  sealingPrivateKey: KeyObject,
+  sealed: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  const privateKey = requireSealingPrivateKey(sealingPrivateKey);
+  requireBytes(sealed, 'sealed key');
+  const bound = boundAad(aad);
+  requireSealedVersion(sealed);
+  if (sealed.length !== SEALED_KEY_BYTES) {
+    throw new KeyringError('malformed-ciphertext', 'The sealed key has the wrong length.');
+  }
+  const ephemeralPublic = sealed.subarray(VERSION_BYTES, VERSION_BYTES + KEY_BYTES);
+  const ivStart = VERSION_BYTES + KEY_BYTES;
+  const iv = sealed.subarray(ivStart, ivStart + GCM_IV_BYTES);
+  const wrapped = sealed.subarray(ivStart + GCM_IV_BYTES);
+  let sharedSecret: Buffer;
+  try {
+    sharedSecret = diffieHellman({
+      privateKey,
+      publicKey: x25519PublicKeyFromRaw(ephemeralPublic),
+    });
+  } catch {
+    throw new KeyringError('decryption-failed', 'Authentication of the ciphertext failed.');
+  }
+  const wrapKey = deriveWrapKey(sharedSecret, ephemeralPublic, rawPublicKey(privateKey));
+  try {
+    return gcmDecrypt(wrapKey, iv, wrapped, bound);
+  } finally {
+    wipe(wrapKey);
+  }
+}
+
+/**
+ * One content record: `version | 12-byte random nonce | ciphertext | 16-byte tag`, AES-256-GCM
+ * under the artifact key. Use it as often as needed with one key — a JSONL log appends one record
+ * per batch of lines, a whole-file blob is one record — but keep a key's record count far below
+ * 2^32, the safe limit for random 96-bit nonces.
+ *
+ * `aad` is authenticated, not stored. Put the artifact id and the record's sequence number in it:
+ * that is what stops records from being swapped between files or reordered. Detecting that
+ * TRAILING records were cut off is not something one record can know — a log truncated at a record
+ * boundary is a valid log — so the caller must keep the expected record count (or a final marker
+ * record) somewhere it trusts.
+ */
+export function encryptRecord(
+  artifactKey: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  requireBytes(artifactKey, 'artifact key', KEY_BYTES);
+  requireBytes(plaintext, 'plaintext');
+  const bound = boundAad(aad);
+  const nonce = randomBytes(GCM_IV_BYTES);
+  const sealed = gcmEncrypt(artifactKey, nonce, plaintext, bound);
+  return Buffer.concat([Buffer.from([SEALED_FORMAT_VERSION]), nonce, sealed]);
+}
+
+/** Opens a record from {@link encryptRecord}; returns plaintext only if the whole record authenticates. */
+export function decryptRecord(
+  artifactKey: Uint8Array,
+  record: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  requireBytes(artifactKey, 'artifact key', KEY_BYTES);
+  requireBytes(record, 'record');
+  const bound = boundAad(aad);
+  requireSealedVersion(record);
+  if (record.length < RECORD_OVERHEAD_BYTES) {
+    throw new KeyringError(
+      'malformed-ciphertext',
+      'The record is shorter than its fixed overhead.',
+    );
+  }
+  const nonceEnd = VERSION_BYTES + GCM_IV_BYTES;
+  return gcmDecrypt(
+    artifactKey,
+    record.subarray(VERSION_BYTES, nonceEnd),
+    record.subarray(nonceEnd),
+    bound,
+  );
+}
+
+/**
+ * Seals a whole value in one step: a sealed key header followed by one record under that key.
+ * Like {@link sealArtifactKey} it needs only the sealing public key.
+ */
+export function sealBlob(
+  sealingPublicKey: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Buffer {
+  const artifactKey = generateArtifactKey();
+  try {
+    return Buffer.concat([
+      sealArtifactKey(sealingPublicKey, artifactKey, aad),
+      encryptRecord(artifactKey, plaintext, aad),
+    ]);
+  } finally {
+    wipe(artifactKey);
+  }
+}
+
+/**
+ * The two halves of a blob from {@link sealBlob}: the sealed key and the one record under it, as
+ * views into `blob`. A holder that keeps opened keys by sealed key splits with this, so the blob
+ * layout stays in this package. Checks the layout only; nothing is authenticated until each half is
+ * opened.
+ */
+export function splitSealedBlob(blob: Uint8Array): {
+  readonly sealedKey: Uint8Array;
+  readonly record: Uint8Array;
+} {
+  requireBytes(blob, 'blob');
+  requireSealedVersion(blob);
+  if (blob.length < SEALED_KEY_BYTES + RECORD_OVERHEAD_BYTES) {
+    throw new KeyringError('malformed-ciphertext', 'The blob is shorter than its fixed overhead.');
+  }
+  return { sealedKey: blob.subarray(0, SEALED_KEY_BYTES), record: blob.subarray(SEALED_KEY_BYTES) };
+}
+
+/** Opens a blob from {@link sealBlob}; any truncation, extension or edit fails as a whole. */
+export function openBlob(sealingPrivateKey: KeyObject, blob: Uint8Array, aad: Uint8Array): Buffer {
+  requireSealingPrivateKey(sealingPrivateKey);
+  const { sealedKey, record } = splitSealedBlob(blob);
+  const artifactKey = openArtifactKey(sealingPrivateKey, sealedKey, aad);
+  try {
+    return decryptRecord(artifactKey, record, aad);
+  } finally {
+    wipe(artifactKey);
+  }
+}

package/src/signatures.ts

@@ -0,0 +1,45 @@
+/**
+ * Ed25519 signing and checking, in the one form every link check uses: a check answers yes or no and
+ * never throws, so a malformed signature or key from the other end is just a refusal, and a failed
+ * signature surfaces as a fixed error that says nothing about the key.
+ */
+import type { Buffer } from 'node:buffer';
+import { sign, verify, type KeyObject } from 'node:crypto';
+
+import { isBytes } from './bytes.js';
+import { KeyringError } from './errors.js';
+import { ed25519PublicKeyFromRaw } from './key-pairs.js';
+
+/** An Ed25519 signature. */
+export const SIGNATURE_BYTES = 64;
+
+/**
+ * Ed25519 over `message` (pure Ed25519: the message is signed as it is, with no pre-hash). A host
+ * that cannot sign fails as `kdf-failed`, whatever it threw, so nothing about the key surfaces.
+ */
+export function signEd25519(privateKey: KeyObject, message: Uint8Array): Buffer {
+  try {
+    return sign(null, message, privateKey);
+  } catch {
+    throw new KeyringError('kdf-failed', 'The key operation could not run on this host.');
+  }
+}
+
+/**
+ * Whether `signature` is the Ed25519 signature of `message` under the raw 32-byte `publicKey`. A
+ * signature of another length, a public key that is not one, or a host that refuses the check are
+ * all simply "not a valid signature": a verifier decides on this answer alone.
+ */
+export function verifyEd25519(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+): boolean {
+  if (!isBytes(signature) || signature.length !== SIGNATURE_BYTES || !isBytes(message))
+    return false;
+  try {
+    return verify(null, message, ed25519PublicKeyFromRaw(publicKey), signature);
+  } catch {
+    return false;
+  }
+}