@push.rocks/smartsecret 1.0.2 → 1.2.0

package/ts/smartsecret.keyring.error.ts

@@ -0,0 +1,76 @@
+export type TSmartSecretKeyringErrorCode =
+  | 'AUTHENTICATION_FAILED'
+  | 'CONFIG_INVALID'
+  | 'CONTEXT_MISMATCH'
+  | 'CRYPTO_OPERATION_FAILED'
+  | 'CREDENTIAL_FILE_INVALID'
+  | 'DESTROYED'
+  | 'ENVELOPE_ID_MISMATCH'
+  | 'ENVELOPE_INVALID'
+  | 'KEK_FINGERPRINT_MISMATCH'
+  | 'KEK_UNAVAILABLE'
+  | 'INVALID_ARGUMENT'
+  | 'PLATFORM_UNSUPPORTED'
+  | 'SIZE_LIMIT_EXCEEDED'
+  | 'TARGET_VERSION_MISMATCH';
+
+export interface ISmartSecretKeyringErrorJson {
+  name: 'SmartSecretKeyringError';
+  code: TSmartSecretKeyringErrorCode;
+  message: string;
+}
+
+const inspectSymbol = Symbol.for('nodejs.util.inspect.custom');
+const errorCodes = new Set<TSmartSecretKeyringErrorCode>([
+  'AUTHENTICATION_FAILED',
+  'CONFIG_INVALID',
+  'CONTEXT_MISMATCH',
+  'CRYPTO_OPERATION_FAILED',
+  'CREDENTIAL_FILE_INVALID',
+  'DESTROYED',
+  'ENVELOPE_ID_MISMATCH',
+  'ENVELOPE_INVALID',
+  'KEK_FINGERPRINT_MISMATCH',
+  'KEK_UNAVAILABLE',
+  'INVALID_ARGUMENT',
+  'PLATFORM_UNSUPPORTED',
+  'SIZE_LIMIT_EXCEEDED',
+  'TARGET_VERSION_MISMATCH',
+]);
+
+/** A code-only error that intentionally retains no operation values or causes. */
+export class SmartSecretKeyringError extends Error {
+  public readonly code: TSmartSecretKeyringErrorCode;
+  public readonly cause: undefined;
+
+  constructor(codeArg: TSmartSecretKeyringErrorCode) {
+    const code = errorCodes.has(codeArg) ? codeArg : 'INVALID_ARGUMENT';
+    const message = `SmartSecret keyring operation failed (${code}).`;
+    super(message);
+    this.name = 'SmartSecretKeyringError';
+    this.code = code;
+    this.stack = `${this.name}: ${message}`;
+    Object.defineProperty(this, 'cause', {
+      configurable: false,
+      enumerable: false,
+      value: undefined,
+      writable: false,
+    });
+  }
+
+  public toJSON(): ISmartSecretKeyringErrorJson {
+    return {
+      name: 'SmartSecretKeyringError',
+      code: this.code,
+      message: this.message,
+    };
+  }
+
+  public [inspectSymbol](): ISmartSecretKeyringErrorJson {
+    return this.toJSON();
+  }
+}
+
+export const createSmartSecretKeyringError = (
+  codeArg: TSmartSecretKeyringErrorCode,
+): SmartSecretKeyringError => new SmartSecretKeyringError(codeArg);

package/ts/smartsecret.keyring.protocol.ts

@@ -0,0 +1,377 @@
+import * as plugins from './smartsecret.plugins.js';
+import {
+  SmartSecretKeyringError,
+  createSmartSecretKeyringError,
+} from './smartsecret.keyring.error.js';
+
+export const SMARTSECRET_KEYRING_SCHEMA_VERSION = 1 as const;
+export const SMARTSECRET_KEYRING_PROFILE = 'smartsecret-aes-256-gcm-dek-kek-v1' as const;
+export type TSmartSecretKeyringProfile = typeof SMARTSECRET_KEYRING_PROFILE;
+
+export const SMARTSECRET_KEYRING_MAX_PAYLOAD_BYTES = 524_288;
+export const SMARTSECRET_KEYRING_MIN_CONTEXT_BYTES = 1;
+export const SMARTSECRET_KEYRING_MAX_CONTEXT_BYTES = 65_536;
+export const SMARTSECRET_KEYRING_MAX_IDENTIFIER_BYTES = 200;
+export const SMARTSECRET_KEYRING_MAX_KEK_VERSION = 2_147_483_647;
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const fingerprintPattern = /^sha256:[0-9a-f]{64}$/;
+const base64UrlPattern = /^[A-Za-z0-9_-]*$/;
+const wrapAadMagic = Buffer.from('smartsecret-envelope-wrap-aad-v1', 'ascii');
+const payloadDigestMagic = Buffer.from('smartsecret-envelope-payload-digest-v1', 'ascii');
+
+export interface ISmartSecretEnvelopeCiphertext {
+  nonce: string;
+  ciphertext: string;
+  tag: string;
+}
+
+export interface ISmartSecretEnvelopeV1 {
+  schemaVersion: 1;
+  profile: TSmartSecretKeyringProfile;
+  envelopeId: string;
+  createdAt: number;
+  contextDigest: string;
+  kek: {
+    keyringId: string;
+    version: number;
+    fingerprint: `sha256:${string}`;
+  };
+  payload: ISmartSecretEnvelopeCiphertext;
+  wrappedDek: ISmartSecretEnvelopeCiphertext;
+}
+
+export interface IParsedSmartSecretEnvelopeV1 {
+  envelope: ISmartSecretEnvelopeV1;
+  contextDigest: Uint8Array;
+  kekFingerprint: Uint8Array;
+  payload: plugins.smartcrypto.IAesGcmCiphertext;
+  wrappedDek: plugins.smartcrypto.IAesGcmCiphertext;
+}
+
+export interface ISmartSecretWrapAadFields {
+  envelopeId: string;
+  createdAt: number;
+  contextDigest: Uint8Array;
+  payloadDigest: Uint8Array;
+  keyringId: string;
+  kekVersion: number;
+  kekFingerprint: Uint8Array;
+}
+
+const requirePlainObject = (
+  valueArg: unknown,
+  expectedKeysArg: readonly string[],
+): Record<string, unknown> => {
+  try {
+    if (valueArg === null || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    const prototype = Object.getPrototypeOf(valueArg);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    const ownKeys = Reflect.ownKeys(valueArg);
+    if (
+      ownKeys.length !== expectedKeysArg.length
+      || ownKeys.some((keyArg) => typeof keyArg !== 'string')
+    ) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    const actualKeys = ownKeys as string[];
+    if (expectedKeysArg.some((keyArg) => !actualKeys.includes(keyArg))) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    const result: Record<string, unknown> = Object.create(null);
+    for (const key of actualKeys) {
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+      }
+      result[key] = descriptor.value;
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof SmartSecretKeyringError) {
+      throw error;
+    }
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+};
+
+export const requireSmartSecretIdentifier = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || !identifierPattern.test(valueArg)
+    || Buffer.byteLength(valueArg, 'utf8') < 1
+    || Buffer.byteLength(valueArg, 'utf8') > SMARTSECRET_KEYRING_MAX_IDENTIFIER_BYTES
+  ) {
+    throw createSmartSecretKeyringError('CONFIG_INVALID');
+  }
+  return valueArg;
+};
+
+export const requireEnvelopeIdentifier = (valueArg: unknown): string => {
+  try {
+    return requireSmartSecretIdentifier(valueArg);
+  } catch {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+};
+
+export const requireKekVersion = (valueArg: unknown, envelopeArg = false): number => {
+  if (
+    !Number.isSafeInteger(valueArg)
+    || (valueArg as number) < 1
+    || (valueArg as number) > SMARTSECRET_KEYRING_MAX_KEK_VERSION
+  ) {
+    throw createSmartSecretKeyringError(envelopeArg ? 'ENVELOPE_INVALID' : 'CONFIG_INVALID');
+  }
+  return valueArg as number;
+};
+
+export const requireEpochMilliseconds = (valueArg: unknown, envelopeArg = false): number => {
+  if (!Number.isSafeInteger(valueArg) || (valueArg as number) < 0) {
+    throw createSmartSecretKeyringError(envelopeArg ? 'ENVELOPE_INVALID' : 'CONFIG_INVALID');
+  }
+  return valueArg as number;
+};
+
+export const requireFingerprint = (valueArg: unknown, envelopeArg = false): `sha256:${string}` => {
+  if (typeof valueArg !== 'string' || !fingerprintPattern.test(valueArg)) {
+    throw createSmartSecretKeyringError(envelopeArg ? 'ENVELOPE_INVALID' : 'CONFIG_INVALID');
+  }
+  return valueArg as `sha256:${string}`;
+};
+
+export const fingerprintToBytes = (valueArg: `sha256:${string}`): Uint8Array =>
+  new Uint8Array(Buffer.from(valueArg.slice('sha256:'.length), 'hex'));
+
+export const encodeCanonicalBase64Url = (valueArg: Uint8Array): string =>
+  Buffer.from(valueArg).toString('base64url');
+
+const decodeCanonicalBase64Url = (
+  valueArg: unknown,
+  maximumBytesArg: number,
+  exactBytesArg?: number,
+): Uint8Array => {
+  if (typeof valueArg !== 'string') {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+  const maximumEncodedLength = Math.ceil(maximumBytesArg * 4 / 3);
+  if (valueArg.length > maximumEncodedLength) {
+    throw createSmartSecretKeyringError('SIZE_LIMIT_EXCEEDED');
+  }
+  if (!base64UrlPattern.test(valueArg) || valueArg.length % 4 === 1) {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+  let result: Uint8Array | undefined;
+  let decodedBuffer: Buffer | undefined;
+  let didSucceed = false;
+  try {
+    decodedBuffer = Buffer.from(valueArg, 'base64url');
+    result = new Uint8Array(decodedBuffer);
+    if (result.byteLength > maximumBytesArg) {
+      throw createSmartSecretKeyringError('SIZE_LIMIT_EXCEEDED');
+    }
+    if (exactBytesArg !== undefined && result.byteLength !== exactBytesArg) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    if (encodeCanonicalBase64Url(result) !== valueArg) {
+      throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+    }
+    didSucceed = true;
+    return result;
+  } catch (error) {
+    if (error instanceof SmartSecretKeyringError) {
+      throw error;
+    }
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  } finally {
+    decodedBuffer?.fill(0);
+    if (!didSucceed) {
+      result?.fill(0);
+    }
+  }
+};
+
+const parseCiphertext = (
+  valueArg: unknown,
+  maximumCiphertextBytesArg: number,
+  exactCiphertextBytesArg?: number,
+): { encoded: ISmartSecretEnvelopeCiphertext; raw: plugins.smartcrypto.IAesGcmCiphertext } => {
+  const value = requirePlainObject(valueArg, ['nonce', 'ciphertext', 'tag']);
+  let nonce: Uint8Array | undefined;
+  let ciphertext: Uint8Array | undefined;
+  let tag: Uint8Array | undefined;
+  let didSucceed = false;
+  try {
+    nonce = decodeCanonicalBase64Url(value.nonce, 12, 12);
+    ciphertext = decodeCanonicalBase64Url(
+      value.ciphertext,
+      maximumCiphertextBytesArg,
+      exactCiphertextBytesArg,
+    );
+    tag = decodeCanonicalBase64Url(value.tag, 16, 16);
+    const result = {
+      encoded: {
+        nonce: value.nonce as string,
+        ciphertext: value.ciphertext as string,
+        tag: value.tag as string,
+      },
+      raw: { nonce, ciphertext, tag },
+    };
+    didSucceed = true;
+    return result;
+  } finally {
+    if (!didSucceed) {
+      nonce?.fill(0);
+      ciphertext?.fill(0);
+      tag?.fill(0);
+    }
+  }
+};
+
+export const parseSmartSecretEnvelope = (valueArg: unknown): IParsedSmartSecretEnvelopeV1 => {
+  const value = requirePlainObject(valueArg, [
+    'schemaVersion',
+    'profile',
+    'envelopeId',
+    'createdAt',
+    'contextDigest',
+    'kek',
+    'payload',
+    'wrappedDek',
+  ]);
+  if (value.schemaVersion !== SMARTSECRET_KEYRING_SCHEMA_VERSION) {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+  if (value.profile !== SMARTSECRET_KEYRING_PROFILE) {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+  let contextDigest: Uint8Array | undefined;
+  let kekFingerprint: Uint8Array | undefined;
+  let payload: ReturnType<typeof parseCiphertext> | undefined;
+  let wrappedDek: ReturnType<typeof parseCiphertext> | undefined;
+  let didSucceed = false;
+  try {
+    const envelopeId = requireEnvelopeIdentifier(value.envelopeId);
+    const createdAt = requireEpochMilliseconds(value.createdAt, true);
+    contextDigest = decodeCanonicalBase64Url(value.contextDigest, 32, 32);
+    const kekValue = requirePlainObject(value.kek, ['keyringId', 'version', 'fingerprint']);
+    const keyringId = requireEnvelopeIdentifier(kekValue.keyringId);
+    const version = requireKekVersion(kekValue.version, true);
+    const fingerprint = requireFingerprint(kekValue.fingerprint, true);
+    kekFingerprint = fingerprintToBytes(fingerprint);
+    payload = parseCiphertext(value.payload, SMARTSECRET_KEYRING_MAX_PAYLOAD_BYTES);
+    wrappedDek = parseCiphertext(value.wrappedDek, 32, 32);
+    const result = {
+      envelope: {
+        schemaVersion: SMARTSECRET_KEYRING_SCHEMA_VERSION,
+        profile: SMARTSECRET_KEYRING_PROFILE,
+        envelopeId,
+        createdAt,
+        contextDigest: value.contextDigest as string,
+        kek: { keyringId, version, fingerprint },
+        payload: payload.encoded,
+        wrappedDek: wrappedDek.encoded,
+      },
+      contextDigest,
+      kekFingerprint,
+      payload: payload.raw,
+      wrappedDek: wrappedDek.raw,
+    };
+    didSucceed = true;
+    return result;
+  } finally {
+    if (!didSucceed) {
+      contextDigest?.fill(0);
+      kekFingerprint?.fill(0);
+      wipeCiphertext(payload?.raw);
+      wipeCiphertext(wrappedDek?.raw);
+    }
+  }
+};
+
+export const sha256Bytes = (...valuesArg: Uint8Array[]): Uint8Array => {
+  const hash = plugins.crypto.createHash('sha256');
+  for (const value of valuesArg) {
+    hash.update(value);
+  }
+  return new Uint8Array(hash.digest());
+};
+
+const uint32Bytes = (valueArg: number): Uint8Array => {
+  const result = Buffer.allocUnsafe(4);
+  result.writeUInt32BE(valueArg, 0);
+  return result;
+};
+
+const uint64Bytes = (valueArg: number): Uint8Array => {
+  const result = Buffer.allocUnsafe(8);
+  result.writeBigUInt64BE(BigInt(valueArg), 0);
+  return result;
+};
+
+const lengthPrefixed = (valueArg: Uint8Array): Uint8Array => {
+  if (valueArg.byteLength > 0xffff_ffff) {
+    throw createSmartSecretKeyringError('SIZE_LIMIT_EXCEEDED');
+  }
+  return Buffer.concat([uint32Bytes(valueArg.byteLength), valueArg]);
+};
+
+export const createSmartSecretPayloadDigest = (
+  payloadArg: plugins.smartcrypto.IAesGcmCiphertext,
+): Uint8Array => {
+  const hash = plugins.crypto.createHash('sha256');
+  hash.update(payloadDigestMagic);
+  for (const value of [payloadArg.nonce, payloadArg.ciphertext, payloadArg.tag]) {
+    const length = uint32Bytes(value.byteLength);
+    try {
+      hash.update(length);
+      hash.update(value);
+    } finally {
+      length.fill(0);
+    }
+  }
+  return new Uint8Array(hash.digest());
+};
+
+export const createSmartSecretWrapAad = (
+  fieldsArg: ISmartSecretWrapAadFields,
+): Uint8Array => {
+  if (
+    fieldsArg.contextDigest.byteLength !== 32
+    || fieldsArg.payloadDigest.byteLength !== 32
+    || fieldsArg.kekFingerprint.byteLength !== 32
+  ) {
+    throw createSmartSecretKeyringError('ENVELOPE_INVALID');
+  }
+  const profile = Buffer.from(SMARTSECRET_KEYRING_PROFILE, 'utf8');
+  const envelopeId = Buffer.from(requireEnvelopeIdentifier(fieldsArg.envelopeId), 'utf8');
+  const keyringId = Buffer.from(requireEnvelopeIdentifier(fieldsArg.keyringId), 'utf8');
+  const createdAt = requireEpochMilliseconds(fieldsArg.createdAt, true);
+  const kekVersion = requireKekVersion(fieldsArg.kekVersion, true);
+  return Buffer.concat([
+    wrapAadMagic,
+    uint64Bytes(SMARTSECRET_KEYRING_SCHEMA_VERSION),
+    lengthPrefixed(profile),
+    lengthPrefixed(envelopeId),
+    uint64Bytes(createdAt),
+    fieldsArg.contextDigest,
+    fieldsArg.payloadDigest,
+    lengthPrefixed(keyringId),
+    uint64Bytes(kekVersion),
+    fieldsArg.kekFingerprint,
+  ]);
+};
+
+export const wipeCiphertext = (valueArg: plugins.smartcrypto.IAesGcmCiphertext | undefined): void => {
+  valueArg?.nonce.fill(0);
+  valueArg?.ciphertext.fill(0);
+  valueArg?.tag.fill(0);
+};
+
+export const timingSafeEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean =>
+  leftArg.byteLength === rightArg.byteLength
+  && plugins.crypto.timingSafeEqual(leftArg, rightArg);