@push.rocks/smartsecret 1.0.2 → 1.2.0

package/ts/smartsecret.keyring.ts

@@ -0,0 +1,955 @@
+import * as plugins from './smartsecret.plugins.js';
+import {
+  SmartSecretKeyringError,
+  createSmartSecretKeyringError,
+} from './smartsecret.keyring.error.js';
+import {
+  SMARTSECRET_KEYRING_MAX_CONTEXT_BYTES,
+  SMARTSECRET_KEYRING_MAX_PAYLOAD_BYTES,
+  SMARTSECRET_KEYRING_MIN_CONTEXT_BYTES,
+  SMARTSECRET_KEYRING_PROFILE,
+  SMARTSECRET_KEYRING_SCHEMA_VERSION,
+  createSmartSecretPayloadDigest,
+  createSmartSecretWrapAad,
+  encodeCanonicalBase64Url,
+  fingerprintToBytes,
+  parseSmartSecretEnvelope,
+  requireEpochMilliseconds,
+  requireFingerprint,
+  requireKekVersion,
+  requireSmartSecretIdentifier,
+  sha256Bytes,
+  timingSafeEqual,
+  wipeCiphertext,
+  type ISmartSecretEnvelopeV1,
+  type IParsedSmartSecretEnvelopeV1,
+} from './smartsecret.keyring.protocol.js';
+
+export type TSmartSecretKekStatus = 'active' | 'retired' | 'revoked';
+
+export interface ISmartSecretKekDescriptor {
+  version: number;
+  status: TSmartSecretKekStatus;
+  credentialPath?: string;
+  expectedFingerprint?: `sha256:${string}`;
+  createdAt: number;
+  activatedAt: number;
+  retiredAt?: number;
+  revokedAt?: number;
+  escrowReference?: string;
+  escrowedAt?: number;
+  recoveryTestedAt?: number;
+}
+
+export interface ISmartSecretKeyringConfig {
+  keyringId: string;
+  keys: readonly ISmartSecretKekDescriptor[];
+}
+
+export interface ISmartSecretKekInspection {
+  version: number;
+  status: TSmartSecretKekStatus;
+  expectedFingerprint?: `sha256:${string}`;
+  createdAt: number;
+  activatedAt: number;
+  retiredAt?: number;
+  revokedAt?: number;
+  escrowReference?: string;
+  escrowedAt?: number;
+  recoveryTestedAt?: number;
+}
+
+export interface ISmartSecretKeyringInspection {
+  keyringId: string;
+  activeVersion: number;
+  keys: ISmartSecretKekInspection[];
+}
+
+export interface IEncryptSmartSecretEnvelopeOptions {
+  envelopeId: string;
+  plaintext: Uint8Array;
+  context: Uint8Array;
+  createdAt?: number;
+}
+
+export interface IDecryptSmartSecretEnvelopeOptions {
+  envelope: unknown;
+  expectedEnvelopeId: string;
+  context: Uint8Array;
+}
+
+export interface IRewrapSmartSecretEnvelopeOptions {
+  envelope: unknown;
+  expectedEnvelopeId: string;
+  context: Uint8Array;
+  targetVersion?: number;
+}
+
+export interface ISmartSecretRecoverySelfTestResult {
+  keyringId: string;
+  version: number;
+  status: 'active' | 'retired';
+  fingerprint: `sha256:${string}`;
+  testedAt: number;
+}
+
+interface INormalizedSmartSecretKekDescriptor extends ISmartSecretKekDescriptor {
+  credentialPath?: string;
+  expectedFingerprint?: `sha256:${string}`;
+}
+
+interface ILoadedSmartSecretKek {
+  descriptor: INormalizedSmartSecretKekDescriptor;
+  key: Uint8Array;
+}
+
+type TBigIntStats = plugins.fs.BigIntStats;
+
+const descriptorKeys = [
+  'version',
+  'status',
+  'credentialPath',
+  'expectedFingerprint',
+  'createdAt',
+  'activatedAt',
+  'retiredAt',
+  'revokedAt',
+  'escrowReference',
+  'escrowedAt',
+  'recoveryTestedAt',
+] as const;
+
+const requireConfigObject = (
+  valueArg: unknown,
+  allowedKeysArg: readonly string[],
+  requiredKeysArg: readonly string[],
+  errorCodeArg: 'CONFIG_INVALID' | 'INVALID_ARGUMENT' = 'CONFIG_INVALID',
+): Record<string, unknown> => {
+  try {
+    if (valueArg === null || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+      throw createSmartSecretKeyringError(errorCodeArg);
+    }
+    const prototype = Object.getPrototypeOf(valueArg);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw createSmartSecretKeyringError(errorCodeArg);
+    }
+    const ownKeys = Reflect.ownKeys(valueArg);
+    if (
+      ownKeys.length < requiredKeysArg.length
+      || ownKeys.length > allowedKeysArg.length
+      || ownKeys.some((keyArg) => typeof keyArg !== 'string')
+    ) {
+      throw createSmartSecretKeyringError(errorCodeArg);
+    }
+    const keys = ownKeys as string[];
+    if (
+      keys.some((keyArg) => !allowedKeysArg.includes(keyArg))
+      || requiredKeysArg.some((keyArg) => !keys.includes(keyArg))
+    ) {
+      throw createSmartSecretKeyringError(errorCodeArg);
+    }
+    const result: Record<string, unknown> = Object.create(null);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw createSmartSecretKeyringError(errorCodeArg);
+      }
+      result[key] = descriptor.value;
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof SmartSecretKeyringError) {
+      throw error;
+    }
+    throw createSmartSecretKeyringError(errorCodeArg);
+  }
+};
+
+const requireDescriptorArray = (valueArg: unknown): readonly unknown[] => {
+  try {
+    if (!Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Array.prototype) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    const ownKeys = Reflect.ownKeys(valueArg);
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(valueArg, 'length');
+    if (
+      !lengthDescriptor
+      || !('value' in lengthDescriptor)
+      || !Number.isSafeInteger(lengthDescriptor.value)
+      || lengthDescriptor.value < 0
+      || ownKeys.length !== lengthDescriptor.value + 1
+    ) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    if (ownKeys.some((keyArg) => typeof keyArg === 'symbol')) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    const result = new Array<unknown>(lengthDescriptor.value);
+    for (let index = 0; index < lengthDescriptor.value; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw createSmartSecretKeyringError('CONFIG_INVALID');
+      }
+      result[index] = descriptor.value;
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof SmartSecretKeyringError) {
+      throw error;
+    }
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+};
+
+const requireOptionalTimestamp = (
+  valueArg: Record<string, unknown>,
+  keyArg: string,
+): number | undefined => {
+  if (!Object.hasOwn(valueArg, keyArg)) {
+    return undefined;
+  }
+  return requireEpochMilliseconds(valueArg[keyArg]);
+};
+
+const normalizeDescriptor = (valueArg: unknown): INormalizedSmartSecretKekDescriptor => {
+  const value = requireConfigObject(valueArg, descriptorKeys, [
+    'version',
+    'status',
+    'createdAt',
+    'activatedAt',
+  ]);
+  const version = requireKekVersion(value.version);
+  if (value.status !== 'active' && value.status !== 'retired' && value.status !== 'revoked') {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  const status = value.status;
+  const createdAt = requireEpochMilliseconds(value.createdAt);
+  const activatedAt = requireEpochMilliseconds(value.activatedAt);
+  const retiredAt = requireOptionalTimestamp(value, 'retiredAt');
+  const revokedAt = requireOptionalTimestamp(value, 'revokedAt');
+  const escrowedAt = requireOptionalTimestamp(value, 'escrowedAt');
+  const recoveryTestedAt = requireOptionalTimestamp(value, 'recoveryTestedAt');
+  if (createdAt > activatedAt) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+
+  if (status === 'active' && (retiredAt !== undefined || revokedAt !== undefined)) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  if (status === 'retired' && (retiredAt === undefined || revokedAt !== undefined)) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  if (status === 'revoked' && revokedAt === undefined) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  if (retiredAt !== undefined && retiredAt < activatedAt) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  if (revokedAt !== undefined && revokedAt < (retiredAt ?? activatedAt)) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+
+  const hasEscrowReference = Object.hasOwn(value, 'escrowReference');
+  const hasEscrowedAt = escrowedAt !== undefined;
+  if (hasEscrowReference !== hasEscrowedAt) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  let escrowReference: string | undefined;
+  if (hasEscrowReference) {
+    escrowReference = requireSmartSecretIdentifier(value.escrowReference);
+  }
+  if (escrowedAt !== undefined && escrowedAt < createdAt) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  if (recoveryTestedAt !== undefined) {
+    if (escrowedAt === undefined || recoveryTestedAt < escrowedAt) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    if (revokedAt !== undefined && recoveryTestedAt > revokedAt) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+  }
+
+  let credentialPath: string | undefined;
+  let expectedFingerprint: `sha256:${string}` | undefined;
+  if (status === 'revoked') {
+    if (Object.hasOwn(value, 'credentialPath') || Object.hasOwn(value, 'expectedFingerprint')) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+  } else {
+    if (typeof value.credentialPath !== 'string') {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    credentialPath = value.credentialPath;
+    if (
+      !plugins.path.isAbsolute(credentialPath)
+      || plugins.path.resolve(credentialPath) !== credentialPath
+    ) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+    expectedFingerprint = requireFingerprint(value.expectedFingerprint);
+  }
+
+  return Object.freeze({
+    version,
+    status,
+    ...(credentialPath === undefined ? {} : { credentialPath }),
+    ...(expectedFingerprint === undefined ? {} : { expectedFingerprint }),
+    createdAt,
+    activatedAt,
+    ...(retiredAt === undefined ? {} : { retiredAt }),
+    ...(revokedAt === undefined ? {} : { revokedAt }),
+    ...(escrowReference === undefined ? {} : { escrowReference }),
+    ...(escrowedAt === undefined ? {} : { escrowedAt }),
+    ...(recoveryTestedAt === undefined ? {} : { recoveryTestedAt }),
+  });
+};
+
+const normalizeConfig = (valueArg: unknown): {
+  keyringId: string;
+  descriptors: readonly INormalizedSmartSecretKekDescriptor[];
+  activeVersion: number;
+} => {
+  const value = requireConfigObject(valueArg, ['keyringId', 'keys'], ['keyringId', 'keys']);
+  const keyringId = requireSmartSecretIdentifier(value.keyringId);
+  const descriptorValues = requireDescriptorArray(value.keys);
+  const descriptors = descriptorValues.map((descriptorArg) => normalizeDescriptor(descriptorArg));
+  if (descriptors.length === 0) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  for (let index = 1; index < descriptors.length; index++) {
+    if (descriptors[index - 1].version >= descriptors[index].version) {
+      throw createSmartSecretKeyringError('CONFIG_INVALID');
+    }
+  }
+  const active = descriptors.filter((descriptorArg) => descriptorArg.status === 'active');
+  if (active.length !== 1) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  return {
+    keyringId,
+    descriptors: Object.freeze(descriptors),
+    activeVersion: active[0].version,
+  };
+};
+
+const statsMatch = (leftArg: TBigIntStats, rightArg: TBigIntStats): boolean =>
+  leftArg.dev === rightArg.dev
+  && leftArg.ino === rightArg.ino
+  && leftArg.mode === rightArg.mode
+  && leftArg.nlink === rightArg.nlink
+  && leftArg.uid === rightArg.uid
+  && leftArg.gid === rightArg.gid
+  && leftArg.rdev === rightArg.rdev
+  && leftArg.size === rightArg.size
+  && leftArg.mtimeNs === rightArg.mtimeNs
+  && leftArg.ctimeNs === rightArg.ctimeNs;
+
+const statsIdentityMatches = (leftArg: TBigIntStats, rightArg: TBigIntStats): boolean =>
+  leftArg.dev === rightArg.dev
+  && leftArg.ino === rightArg.ino
+  && leftArg.mode === rightArg.mode
+  && leftArg.uid === rightArg.uid
+  && leftArg.gid === rightArg.gid;
+
+const lstatPathComponents = async (
+  credentialPathArg: string,
+): Promise<Array<{ path: string; stats: TBigIntStats }>> => {
+  const root = plugins.path.parse(credentialPathArg).root;
+  const relative = plugins.path.relative(root, credentialPathArg);
+  const components = relative.split(plugins.path.sep).filter(Boolean);
+  const result: Array<{ path: string; stats: TBigIntStats }> = [];
+  let currentPath = root;
+  const rootStats = await plugins.fs.promises.lstat(root, { bigint: true });
+  if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+    throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+  }
+  result.push({ path: root, stats: rootStats });
+  for (let index = 0; index < components.length; index++) {
+    currentPath = plugins.path.join(currentPath, components[index]);
+    const stats = await plugins.fs.promises.lstat(currentPath, { bigint: true });
+    const isFinal = index === components.length - 1;
+    if (
+      stats.isSymbolicLink()
+      || (isFinal ? !stats.isFile() : !stats.isDirectory())
+    ) {
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+    result.push({ path: currentPath, stats });
+  }
+  return result;
+};
+
+const loadCredential = async (
+  descriptorArg: INormalizedSmartSecretKekDescriptor,
+): Promise<Uint8Array> => {
+  let handle: plugins.fs.promises.FileHandle | undefined;
+  let key: Uint8Array | undefined;
+  let readBuffer: Buffer | undefined;
+  let didFail = false;
+  try {
+    const credentialPath = descriptorArg.credentialPath!;
+    const beforeComponents = await lstatPathComponents(credentialPath);
+    const beforeFinal = beforeComponents[beforeComponents.length - 1].stats;
+    if (typeof plugins.fs.constants.O_NOFOLLOW !== 'number') {
+      throw createSmartSecretKeyringError('PLATFORM_UNSUPPORTED');
+    }
+    handle = await plugins.fs.promises.open(
+      credentialPath,
+      plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
+    );
+    const beforeFd = await handle.stat({ bigint: true });
+    if (
+      !beforeFd.isFile()
+      || beforeFd.size !== 32n
+      || (beforeFd.mode & 0o022n) !== 0n
+      || !statsMatch(beforeFinal, beforeFd)
+    ) {
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+
+    readBuffer = Buffer.alloc(33);
+    let totalBytesRead = 0;
+    while (totalBytesRead < readBuffer.byteLength) {
+      const { bytesRead } = await handle.read(
+        readBuffer,
+        totalBytesRead,
+        readBuffer.byteLength - totalBytesRead,
+        totalBytesRead,
+      );
+      if (bytesRead === 0) {
+        break;
+      }
+      totalBytesRead += bytesRead;
+    }
+    if (totalBytesRead !== 32) {
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+
+    const afterFd = await handle.stat({ bigint: true });
+    const afterComponents = await lstatPathComponents(credentialPath);
+    if (beforeComponents.length !== afterComponents.length) {
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+    for (let index = 0; index < beforeComponents.length - 1; index++) {
+      if (!statsIdentityMatches(beforeComponents[index].stats, afterComponents[index].stats)) {
+        throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+      }
+    }
+    const afterFinal = afterComponents[afterComponents.length - 1].stats;
+    if (!statsMatch(beforeFd, afterFd) || !statsMatch(afterFd, afterFinal)) {
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+
+    key = new Uint8Array(readBuffer.subarray(0, 32));
+    const actualFingerprint = sha256Bytes(key);
+    const expectedFingerprint = fingerprintToBytes(descriptorArg.expectedFingerprint!);
+    try {
+      if (!timingSafeEqual(actualFingerprint, expectedFingerprint)) {
+        throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+      }
+    } finally {
+      actualFingerprint.fill(0);
+      expectedFingerprint.fill(0);
+    }
+  } catch {
+    didFail = true;
+  } finally {
+    readBuffer?.fill(0);
+    if (handle) {
+      try {
+        await handle.close();
+      } catch {
+        didFail = true;
+      }
+    }
+  }
+  if (didFail || !key) {
+    key?.fill(0);
+    throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+  }
+  return key;
+};
+
+const copyBytes = (
+  valueArg: unknown,
+  minimumBytesArg: number,
+  maximumBytesArg: number,
+): Uint8Array => {
+  if (!(valueArg instanceof Uint8Array)) {
+    throw createSmartSecretKeyringError('INVALID_ARGUMENT');
+  }
+  if (valueArg.byteLength < minimumBytesArg || valueArg.byteLength > maximumBytesArg) {
+    throw createSmartSecretKeyringError('SIZE_LIMIT_EXCEEDED');
+  }
+  return new Uint8Array(valueArg);
+};
+
+const copyIdentifier = (valueArg: unknown): string => {
+  try {
+    return requireSmartSecretIdentifier(valueArg);
+  } catch {
+    throw createSmartSecretKeyringError('INVALID_ARGUMENT');
+  }
+};
+
+const encodeCiphertext = (
+  valueArg: plugins.smartcrypto.IAesGcmCiphertext,
+): { nonce: string; ciphertext: string; tag: string } => ({
+  nonce: encodeCanonicalBase64Url(valueArg.nonce),
+  ciphertext: encodeCanonicalBase64Url(valueArg.ciphertext),
+  tag: encodeCanonicalBase64Url(valueArg.tag),
+});
+
+const wipeParsedEnvelope = (valueArg: IParsedSmartSecretEnvelopeV1): void => {
+  valueArg.contextDigest.fill(0);
+  valueArg.kekFingerprint.fill(0);
+  wipeCiphertext(valueArg.payload);
+  wipeCiphertext(valueArg.wrappedDek);
+};
+
+/**
+ * A Linux-only, immutable KEK snapshot for strict DEK/KEK envelopes.
+ * Envelope persistence and compare-and-swap coordination remain consumer responsibilities.
+ */
+export class SmartSecretKeyring {
+  private destroyed = false;
+
+  private constructor(
+    private readonly keyringId: string,
+    private readonly descriptors: readonly INormalizedSmartSecretKekDescriptor[],
+    private readonly activeVersion: number,
+    private readonly loadedKeys: ReadonlyMap<number, ILoadedSmartSecretKek>,
+  ) {}
+
+  public static async create(configArg: ISmartSecretKeyringConfig): Promise<SmartSecretKeyring> {
+    if (process.platform !== 'linux') {
+      throw createSmartSecretKeyringError('PLATFORM_UNSUPPORTED');
+    }
+    const config = normalizeConfig(configArg);
+    const loadedKeys = new Map<number, ILoadedSmartSecretKek>();
+    try {
+      for (const descriptor of config.descriptors) {
+        if (descriptor.status === 'revoked') {
+          continue;
+        }
+        let key: Uint8Array | undefined;
+        try {
+          key = await loadCredential(descriptor);
+          loadedKeys.set(descriptor.version, { descriptor, key });
+          key = undefined;
+        } finally {
+          key?.fill(0);
+        }
+      }
+      return new SmartSecretKeyring(
+        config.keyringId,
+        config.descriptors,
+        config.activeVersion,
+        loadedKeys,
+      );
+    } catch (error) {
+      for (const loaded of loadedKeys.values()) {
+        loaded.key.fill(0);
+      }
+      if (error instanceof SmartSecretKeyringError) {
+        throw error;
+      }
+      throw createSmartSecretKeyringError('CREDENTIAL_FILE_INVALID');
+    }
+  }
+
+  private requireAlive(): void {
+    if (this.destroyed) {
+      throw createSmartSecretKeyringError('DESTROYED');
+    }
+  }
+
+  private requireEnvelopeKey(
+    envelopeArg: ISmartSecretEnvelopeV1,
+  ): Uint8Array {
+    if (envelopeArg.kek.keyringId !== this.keyringId) {
+      throw createSmartSecretKeyringError('KEK_UNAVAILABLE');
+    }
+    const loaded = this.loadedKeys.get(envelopeArg.kek.version);
+    if (!loaded || loaded.descriptor.status === 'revoked') {
+      throw createSmartSecretKeyringError('KEK_UNAVAILABLE');
+    }
+    if (envelopeArg.kek.fingerprint !== loaded.descriptor.expectedFingerprint) {
+      throw createSmartSecretKeyringError('KEK_FINGERPRINT_MISMATCH');
+    }
+    return new Uint8Array(loaded.key);
+  }
+
+  public inspect(): ISmartSecretKeyringInspection {
+    this.requireAlive();
+    return {
+      keyringId: this.keyringId,
+      activeVersion: this.activeVersion,
+      keys: this.descriptors.map((descriptorArg) => ({
+        version: descriptorArg.version,
+        status: descriptorArg.status,
+        ...(descriptorArg.expectedFingerprint === undefined
+          ? {}
+          : { expectedFingerprint: descriptorArg.expectedFingerprint }),
+        createdAt: descriptorArg.createdAt,
+        activatedAt: descriptorArg.activatedAt,
+        ...(descriptorArg.retiredAt === undefined ? {} : { retiredAt: descriptorArg.retiredAt }),
+        ...(descriptorArg.revokedAt === undefined ? {} : { revokedAt: descriptorArg.revokedAt }),
+        ...(descriptorArg.escrowReference === undefined
+          ? {}
+          : { escrowReference: descriptorArg.escrowReference }),
+        ...(descriptorArg.escrowedAt === undefined ? {} : { escrowedAt: descriptorArg.escrowedAt }),
+        ...(descriptorArg.recoveryTestedAt === undefined
+          ? {}
+          : { recoveryTestedAt: descriptorArg.recoveryTestedAt }),
+      })),
+    };
+  }
+
+  public destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    for (const loaded of this.loadedKeys.values()) {
+      loaded.key.fill(0);
+    }
+  }
+
+  public async encryptEnvelope(
+    optionsArg: IEncryptSmartSecretEnvelopeOptions,
+  ): Promise<ISmartSecretEnvelopeV1> {
+    this.requireAlive();
+    const options = requireConfigObject(
+      optionsArg,
+      ['envelopeId', 'plaintext', 'context', 'createdAt'],
+      ['envelopeId', 'plaintext', 'context'],
+      'INVALID_ARGUMENT',
+    );
+    const envelopeId = copyIdentifier(options.envelopeId);
+    let createdAt: number;
+    try {
+      createdAt = options.createdAt === undefined
+        ? Date.now()
+        : requireEpochMilliseconds(options.createdAt);
+    } catch {
+      throw createSmartSecretKeyringError('INVALID_ARGUMENT');
+    }
+    let plaintext: Uint8Array | undefined;
+    let context: Uint8Array | undefined;
+    let kek: Uint8Array | undefined;
+    let kekFingerprint: Uint8Array | undefined;
+    let contextDigest: Uint8Array | undefined;
+    let dek: Uint8Array | undefined;
+    let payload: plugins.smartcrypto.IAesGcmCiphertext | undefined;
+    let wrappedDek: plugins.smartcrypto.IAesGcmCiphertext | undefined;
+    let payloadDigest: Uint8Array | undefined;
+    let wrapAad: Uint8Array | undefined;
+    try {
+      plaintext = copyBytes(options.plaintext, 0, SMARTSECRET_KEYRING_MAX_PAYLOAD_BYTES);
+      context = copyBytes(
+        options.context,
+        SMARTSECRET_KEYRING_MIN_CONTEXT_BYTES,
+        SMARTSECRET_KEYRING_MAX_CONTEXT_BYTES,
+      );
+      const active = this.loadedKeys.get(this.activeVersion)!;
+      kek = new Uint8Array(active.key);
+      kekFingerprint = fingerprintToBytes(active.descriptor.expectedFingerprint!);
+      contextDigest = sha256Bytes(context);
+      dek = plugins.smartcrypto.generateDek();
+      try {
+        payload = await plugins.smartcrypto.aesGcmEncrypt({
+          key: dek,
+          plaintext,
+          aad: context,
+        });
+        payloadDigest = createSmartSecretPayloadDigest(payload);
+        wrapAad = createSmartSecretWrapAad({
+          envelopeId,
+          createdAt,
+          contextDigest,
+          payloadDigest,
+          keyringId: this.keyringId,
+          kekVersion: active.descriptor.version,
+          kekFingerprint,
+        });
+        wrappedDek = await plugins.smartcrypto.wrapDek({ dek, kek, wrapAad });
+      } catch (error) {
+        if (error instanceof SmartSecretKeyringError) {
+          throw error;
+        }
+        throw createSmartSecretKeyringError('CRYPTO_OPERATION_FAILED');
+      }
+      return {
+        schemaVersion: SMARTSECRET_KEYRING_SCHEMA_VERSION,
+        profile: SMARTSECRET_KEYRING_PROFILE,
+        envelopeId,
+        createdAt,
+        contextDigest: encodeCanonicalBase64Url(contextDigest),
+        kek: {
+          keyringId: this.keyringId,
+          version: active.descriptor.version,
+          fingerprint: active.descriptor.expectedFingerprint!,
+        },
+        payload: encodeCiphertext(payload),
+        wrappedDek: encodeCiphertext(wrappedDek),
+      };
+    } finally {
+      plaintext?.fill(0);
+      context?.fill(0);
+      contextDigest?.fill(0);
+      dek?.fill(0);
+      kek?.fill(0);
+      kekFingerprint?.fill(0);
+      payloadDigest?.fill(0);
+      wrapAad?.fill(0);
+      wipeCiphertext(payload);
+      wipeCiphertext(wrappedDek);
+    }
+  }
+
+  public async decryptEnvelope(
+    optionsArg: IDecryptSmartSecretEnvelopeOptions,
+  ): Promise<Uint8Array> {
+    this.requireAlive();
+    const options = requireConfigObject(
+      optionsArg,
+      ['envelope', 'expectedEnvelopeId', 'context'],
+      ['envelope', 'expectedEnvelopeId', 'context'],
+      'INVALID_ARGUMENT',
+    );
+    const expectedEnvelopeId = copyIdentifier(options.expectedEnvelopeId);
+    const parsed = parseSmartSecretEnvelope(options.envelope);
+    let context: Uint8Array | undefined;
+    let envelopeKey: Uint8Array | undefined;
+    let contextDigest: Uint8Array | undefined;
+    let payloadDigest: Uint8Array | undefined;
+    let wrapAad: Uint8Array | undefined;
+    let dek: Uint8Array | undefined;
+    try {
+      context = copyBytes(
+        options.context,
+        SMARTSECRET_KEYRING_MIN_CONTEXT_BYTES,
+        SMARTSECRET_KEYRING_MAX_CONTEXT_BYTES,
+      );
+      envelopeKey = this.requireEnvelopeKey(parsed.envelope);
+      contextDigest = sha256Bytes(context);
+      payloadDigest = createSmartSecretPayloadDigest(parsed.payload);
+      wrapAad = createSmartSecretWrapAad({
+        envelopeId: parsed.envelope.envelopeId,
+        createdAt: parsed.envelope.createdAt,
+        contextDigest: parsed.contextDigest,
+        payloadDigest,
+        keyringId: parsed.envelope.kek.keyringId,
+        kekVersion: parsed.envelope.kek.version,
+        kekFingerprint: parsed.kekFingerprint,
+      });
+      if (parsed.envelope.envelopeId !== expectedEnvelopeId) {
+        throw createSmartSecretKeyringError('ENVELOPE_ID_MISMATCH');
+      }
+      if (!timingSafeEqual(contextDigest, parsed.contextDigest)) {
+        throw createSmartSecretKeyringError('CONTEXT_MISMATCH');
+      }
+      try {
+        dek = await plugins.smartcrypto.unwrapDek({
+          wrappedDek: parsed.wrappedDek,
+          kek: envelopeKey,
+          wrapAad,
+        });
+        return await plugins.smartcrypto.aesGcmDecrypt({
+          key: dek,
+          encryptedData: parsed.payload,
+          aad: context,
+        });
+      } catch {
+        throw createSmartSecretKeyringError('AUTHENTICATION_FAILED');
+      }
+    } finally {
+      context?.fill(0);
+      contextDigest?.fill(0);
+      payloadDigest?.fill(0);
+      wrapAad?.fill(0);
+      envelopeKey?.fill(0);
+      dek?.fill(0);
+      wipeParsedEnvelope(parsed);
+    }
+  }
+
+  public async rewrapEnvelope(
+    optionsArg: IRewrapSmartSecretEnvelopeOptions,
+  ): Promise<ISmartSecretEnvelopeV1> {
+    this.requireAlive();
+    const options = requireConfigObject(
+      optionsArg,
+      ['envelope', 'expectedEnvelopeId', 'context', 'targetVersion'],
+      ['envelope', 'expectedEnvelopeId', 'context'],
+      'INVALID_ARGUMENT',
+    );
+    const expectedEnvelopeId = copyIdentifier(options.expectedEnvelopeId);
+    const parsed = parseSmartSecretEnvelope(options.envelope);
+    let context: Uint8Array | undefined;
+    let currentKey: Uint8Array | undefined;
+    let targetKey: Uint8Array | undefined;
+    let targetFingerprint: Uint8Array | undefined;
+    let contextDigest: Uint8Array | undefined;
+    let payloadDigest: Uint8Array | undefined;
+    let currentWrapAad: Uint8Array | undefined;
+    let newWrapAad: Uint8Array | undefined;
+    let wrappedDek: plugins.smartcrypto.IAesGcmCiphertext | undefined;
+    try {
+      context = copyBytes(
+        options.context,
+        SMARTSECRET_KEYRING_MIN_CONTEXT_BYTES,
+        SMARTSECRET_KEYRING_MAX_CONTEXT_BYTES,
+      );
+      currentKey = this.requireEnvelopeKey(parsed.envelope);
+      if (options.targetVersion !== undefined) {
+        let targetVersion: number;
+        try {
+          targetVersion = requireKekVersion(options.targetVersion);
+        } catch {
+          throw createSmartSecretKeyringError('TARGET_VERSION_MISMATCH');
+        }
+        if (targetVersion !== this.activeVersion) {
+          throw createSmartSecretKeyringError('TARGET_VERSION_MISMATCH');
+        }
+      }
+      const active = this.loadedKeys.get(this.activeVersion)!;
+      targetKey = new Uint8Array(active.key);
+      targetFingerprint = fingerprintToBytes(active.descriptor.expectedFingerprint!);
+      contextDigest = sha256Bytes(context);
+      payloadDigest = createSmartSecretPayloadDigest(parsed.payload);
+      currentWrapAad = createSmartSecretWrapAad({
+        envelopeId: parsed.envelope.envelopeId,
+        createdAt: parsed.envelope.createdAt,
+        contextDigest: parsed.contextDigest,
+        payloadDigest,
+        keyringId: parsed.envelope.kek.keyringId,
+        kekVersion: parsed.envelope.kek.version,
+        kekFingerprint: parsed.kekFingerprint,
+      });
+      newWrapAad = createSmartSecretWrapAad({
+        envelopeId: parsed.envelope.envelopeId,
+        createdAt: parsed.envelope.createdAt,
+        contextDigest: parsed.contextDigest,
+        payloadDigest,
+        keyringId: this.keyringId,
+        kekVersion: active.descriptor.version,
+        kekFingerprint: targetFingerprint,
+      });
+      if (parsed.envelope.envelopeId !== expectedEnvelopeId) {
+        throw createSmartSecretKeyringError('ENVELOPE_ID_MISMATCH');
+      }
+      if (!timingSafeEqual(contextDigest, parsed.contextDigest)) {
+        throw createSmartSecretKeyringError('CONTEXT_MISMATCH');
+      }
+      try {
+        wrappedDek = await plugins.smartcrypto.rewrapDek({
+          wrappedDek: parsed.wrappedDek,
+          currentKek: currentKey,
+          currentWrapAad,
+          newKek: targetKey,
+          newWrapAad,
+        });
+      } catch {
+        throw createSmartSecretKeyringError('AUTHENTICATION_FAILED');
+      }
+      return {
+        schemaVersion: parsed.envelope.schemaVersion,
+        profile: parsed.envelope.profile,
+        envelopeId: parsed.envelope.envelopeId,
+        createdAt: parsed.envelope.createdAt,
+        contextDigest: parsed.envelope.contextDigest,
+        kek: {
+          keyringId: this.keyringId,
+          version: active.descriptor.version,
+          fingerprint: active.descriptor.expectedFingerprint!,
+        },
+        payload: { ...parsed.envelope.payload },
+        wrappedDek: encodeCiphertext(wrappedDek),
+      };
+    } finally {
+      context?.fill(0);
+      contextDigest?.fill(0);
+      payloadDigest?.fill(0);
+      currentWrapAad?.fill(0);
+      newWrapAad?.fill(0);
+      currentKey?.fill(0);
+      targetKey?.fill(0);
+      targetFingerprint?.fill(0);
+      wipeCiphertext(wrappedDek);
+      wipeParsedEnvelope(parsed);
+    }
+  }
+
+  public async recoverySelfTest(versionArg: number): Promise<ISmartSecretRecoverySelfTestResult> {
+    this.requireAlive();
+    let version: number;
+    try {
+      version = requireKekVersion(versionArg);
+    } catch {
+      throw createSmartSecretKeyringError('INVALID_ARGUMENT');
+    }
+    const loaded = this.loadedKeys.get(version);
+    if (!loaded || loaded.descriptor.status === 'revoked') {
+      throw createSmartSecretKeyringError('KEK_UNAVAILABLE');
+    }
+    let key: Uint8Array | undefined;
+    let fingerprint: Uint8Array | undefined;
+    let dek: Uint8Array | undefined;
+    let keyringId: Buffer | undefined;
+    let length: Buffer | undefined;
+    let versionBytes: Buffer | undefined;
+    let aad: Buffer | undefined;
+    let wrappedDek: plugins.smartcrypto.IAesGcmCiphertext | undefined;
+    let unwrappedDek: Uint8Array | undefined;
+    try {
+      key = new Uint8Array(loaded.key);
+      fingerprint = fingerprintToBytes(loaded.descriptor.expectedFingerprint!);
+      dek = plugins.smartcrypto.generateDek();
+      keyringId = Buffer.from(this.keyringId, 'utf8');
+      length = Buffer.allocUnsafe(4);
+      length.writeUInt32BE(keyringId.byteLength, 0);
+      versionBytes = Buffer.allocUnsafe(8);
+      versionBytes.writeBigUInt64BE(BigInt(version), 0);
+      aad = Buffer.concat([
+        Buffer.from('smartsecret-keyring-recovery-aad-v1', 'ascii'),
+        length,
+        keyringId,
+        versionBytes,
+        fingerprint,
+      ]);
+      try {
+        wrappedDek = await plugins.smartcrypto.wrapDek({ dek, kek: key, wrapAad: aad });
+        unwrappedDek = await plugins.smartcrypto.unwrapDek({
+          wrappedDek,
+          kek: key,
+          wrapAad: aad,
+        });
+      } catch {
+        throw createSmartSecretKeyringError('CRYPTO_OPERATION_FAILED');
+      }
+      if (!timingSafeEqual(dek, unwrappedDek)) {
+        throw createSmartSecretKeyringError('CRYPTO_OPERATION_FAILED');
+      }
+      return {
+        keyringId: this.keyringId,
+        version,
+        status: loaded.descriptor.status,
+        fingerprint: loaded.descriptor.expectedFingerprint!,
+        testedAt: Date.now(),
+      };
+    } finally {
+      key?.fill(0);
+      fingerprint?.fill(0);
+      dek?.fill(0);
+      keyringId?.fill(0);
+      length?.fill(0);
+      versionBytes?.fill(0);
+      aad?.fill(0);
+      wipeCiphertext(wrappedDek);
+      unwrappedDek?.fill(0);
+    }
+  }
+}