@opentdf/sdk 0.9.0-beta.91 → 0.9.0-beta.93

package/tdf3/src/crypto/declarations.ts

@@ -14,18 +14,152 @@ export type DecryptResult = {
 
 /**
  * PEM formatted keypair.
+ * Used for import/export compatibility. Internal code should use KeyPair (opaque keys).
  */
 export type PemKeyPair = {
   publicKey: string;
   privateKey: string;
 };
 
+/**
+ * Key algorithm identifier combining key type and parameters.
+ */
+export type KeyAlgorithm =
+  | 'rsa:2048'
+  | 'rsa:4096'
+  | 'ec:secp256r1'
+  | 'ec:secp384r1'
+  | 'ec:secp521r1';
+
+/**
+ * Options for key generation and import.
+ */
+export type KeyOptions = {
+  /**
+   * Key usage: 'encrypt' for RSA-OAEP, 'sign' for RSA/ECDSA signing, 'derive' for ECDH.
+   * If not specified, defaults based on the generation method or key type.
+   */
+  usage?: 'encrypt' | 'sign' | 'derive';
+
+  /**
+   * Whether keys can be exported. Defaults to true.
+   * HSM-backed implementations may force false for private keys.
+   */
+  extractable?: boolean;
+
+  /**
+   * Optional algorithm hint for import validation.
+   * Helps disambiguate or validate imported keys.
+   */
+  algorithmHint?: KeyAlgorithm;
+};
+
+/**
+ * Opaque public key - internal representation hidden.
+ * Code outside CryptoService treats this as a token.
+ *
+ * Includes metadata for algorithm selection without needing CryptoService calls.
+ */
+export type PublicKey = {
+  readonly _brand: 'PublicKey';
+  /** Algorithm identifier (e.g., 'rsa:2048', 'ec:secp256r1') */
+  readonly algorithm: KeyAlgorithm;
+  /** RSA modulus bit length (only for RSA keys) */
+  readonly modulusBits?: number;
+  /** EC curve name (only for EC keys) */
+  readonly curve?: ECCurve;
+};
+
+/**
+ * Opaque private key - internal representation hidden.
+ * Code outside CryptoService treats this as a token.
+ *
+ * Includes metadata for algorithm selection without needing CryptoService calls.
+ */
+export type PrivateKey = {
+  readonly _brand: 'PrivateKey';
+  /** Algorithm identifier (e.g., 'rsa:2048', 'ec:secp256r1') */
+  readonly algorithm: KeyAlgorithm;
+  /** RSA modulus bit length (only for RSA keys) */
+  readonly modulusBits?: number;
+  /** EC curve name (only for EC keys) */
+  readonly curve?: ECCurve;
+};
+
+/**
+ * Opaque key pair with matching algorithms.
+ */
+export type KeyPair = {
+  readonly publicKey: PublicKey;
+  readonly privateKey: PrivateKey;
+};
+
 /**
  * The minimum acceptable asymetric key size, currently 2^11.
  */
 export const MIN_ASYMMETRIC_KEY_SIZE_BITS = 2048;
 
-export type AnyKeyPair = PemKeyPair | CryptoKeyPair;
+/**
+ * Opaque symmetric key - internal representation hidden.
+ * Code outside CryptoService treats this as a token.
+ * Used for AES encryption/decryption.
+ *
+ * Includes metadata for key length without needing CryptoService calls.
+ */
+export type SymmetricKey = {
+  readonly _brand: 'SymmetricKey';
+  /** Key length in bits (e.g., 256 for AES-256) */
+  readonly length: number;
+};
+
+/**
+ * Elliptic curves supported for ECDH/ECDSA operations.
+ */
+export type ECCurve = 'P-256' | 'P-384' | 'P-521';
+
+/**
+ * Asymmetric signing algorithms (require PEM keys).
+ */
+export type AsymmetricSigningAlgorithm = 'RS256' | 'ES256' | 'ES384' | 'ES512';
+
+/**
+ * Symmetric signing algorithm (requires raw key bytes).
+ */
+export type SymmetricSigningAlgorithm = 'HS256';
+
+/**
+ * All supported signing algorithms.
+ */
+export type SigningAlgorithm = AsymmetricSigningAlgorithm | SymmetricSigningAlgorithm;
+
+/**
+ * Supported hash algorithms.
+ */
+export type HashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+/**
+ * Parameters for HKDF key derivation.
+ */
+export type HkdfParams = {
+  /** Hash algorithm to use for HKDF. */
+  hash: HashAlgorithm;
+  /** Salt for HKDF (can be empty Uint8Array). */
+  salt: Uint8Array;
+  /** Optional info/context for HKDF. */
+  info?: Uint8Array;
+  /** Desired key length in bits. Defaults to 256. */
+  keyLength?: number;
+};
+
+/**
+ * Public key information returned from parsePublicKeyPem.
+ */
+export type PublicKeyInfo = {
+  /** Detected algorithm of the key. */
+  algorithm: 'rsa:2048' | 'rsa:4096' | 'ec:secp256r1' | 'ec:secp384r1' | 'ec:secp521r1';
+  /** Normalized PEM string. */
+  pem: string;
+};
 
 export type CryptoService = {
   /** Track which crypto implementation we are using */
@@ -34,56 +168,238 @@ export type CryptoService = {
   /** Default algorithm identifier. */
   method: AlgorithmUrn;
 
-  /** Convert or narrow from AnyKeyPair to PemKeyPair */
-  cryptoToPemPair: (keys: AnyKeyPair) => Promise<PemKeyPair>;
-
   /**
    * Try to decrypt content with the default or handed algorithm. Throws on
    * most failure, if auth tagging is implemented for example.
    */
   decrypt: (
     payload: Binary,
-    key: Binary,
+    key: SymmetricKey,
     iv: Binary,
     algorithm?: AlgorithmUrn,
     authTag?: Binary
   ) => Promise<DecryptResult>;
 
-  decryptWithPrivateKey: (encryptedPayload: Binary, privateKey: string) => Promise<Binary>;
+  decryptWithPrivateKey: (encryptedPayload: Binary, privateKey: PrivateKey) => Promise<Binary>;
 
   /**
    * Encrypt content with the default or handed algorithm.
+   * Accepts Binary or SymmetricKey as payload (for key wrapping with symmetric keys).
    */
   encrypt: (
-    payload: Binary,
-    key: Binary,
+    payload: Binary | SymmetricKey,
+    key: SymmetricKey,
     iv: Binary,
     algorithm?: AlgorithmUrn
   ) => Promise<EncryptResult>;
 
-  encryptWithPublicKey: (payload: Binary, publicKey: string) => Promise<Binary>;
-
-  /** Get length random bytes as a hex-encoded string. */
-  generateInitializationVector: (length?: number) => Promise<string>;
+  /**
+   * Encrypt with asymmetric public key (RSA-OAEP).
+   * Accepts Binary or SymmetricKey for key wrapping.
+   */
+  encryptWithPublicKey: (payload: Binary | SymmetricKey, publicKey: PublicKey) => Promise<Binary>;
 
-  /** Get length random bytes as a hex-encoded string. */
-  generateKey: (length?: number) => Promise<string>;
+  /** Generate symmetric AES key (opaque, never hex string). */
+  generateKey: (length?: number) => Promise<SymmetricKey>;
 
   /**
-   * Generate an RSA key pair
+   * Generate an RSA key pair for encryption/decryption.
    * @param size in bits, defaults to a reasonable size for the default method
+   * @returns Opaque key pair
    */
-  generateKeyPair: (size?: number) => Promise<AnyKeyPair>;
-
-  generateSigningKeyPair: () => Promise<AnyKeyPair>;
+  generateKeyPair: (size?: number) => Promise<KeyPair>;
 
   /**
-   * Create an HMAC SHA256 hash
+   * Generate an RSA key pair for signing/verification.
+   * @returns Opaque key pair
    */
-  hmac: (key: string, content: string) => Promise<string>;
+  generateSigningKeyPair: () => Promise<KeyPair>;
 
   randomBytes: (byteLength: number) => Promise<Uint8Array>;
 
-  /** Compute the hex-encoded SHA hash of a UTF-16 encoded string. */
-  sha256: (content: string) => Promise<string>;
+  /**
+   * Sign data with an asymmetric private key.
+   * @param data - Data to sign
+   * @param privateKey - Opaque private key
+   * @param algorithm - Signing algorithm (RS256, ES256, ES384, ES512)
+   */
+  sign: (
+    data: Uint8Array,
+    privateKey: PrivateKey,
+    algorithm: AsymmetricSigningAlgorithm
+  ) => Promise<Uint8Array>;
+
+  /**
+   * Verify signature with an asymmetric public key.
+   * @param data - Original data that was signed
+   * @param signature - Signature to verify
+   * @param publicKey - Opaque public key
+   * @param algorithm - Must match algorithm used for signing
+   */
+  verify: (
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: PublicKey,
+    algorithm: AsymmetricSigningAlgorithm
+  ) => Promise<boolean>;
+
+  /**
+   * Compute HMAC-SHA256 of data with a symmetric key.
+   * @param data - Data to authenticate
+   * @param key - Opaque symmetric key
+   * @returns Raw HMAC bytes
+   */
+  hmac: (data: Uint8Array, key: SymmetricKey) => Promise<Uint8Array>;
+
+  /**
+   * Verify HMAC-SHA256.
+   * @param data - Original data that was authenticated
+   * @param signature - HMAC to verify
+   * @param key - Opaque symmetric key
+   */
+  verifyHmac: (data: Uint8Array, signature: Uint8Array, key: SymmetricKey) => Promise<boolean>;
+
+  /**
+   * Compute hash digest.
+   * @param algorithm - Hash algorithm to use (SHA-256, SHA-384, SHA-512)
+   * @param data - Data to hash
+   */
+  digest: (algorithm: HashAlgorithm, data: Uint8Array) => Promise<Uint8Array>;
+
+  /**
+   * Generate an EC key pair for ECDH key agreement.
+   * @param curve - Elliptic curve to use (defaults to P-256)
+   * @throws ConfigurationError if EC operations not supported
+   */
+  generateECKeyPair: (curve?: ECCurve) => Promise<KeyPair>;
+
+  /**
+   * Perform ECDH key agreement followed by HKDF key derivation.
+   * Returns opaque symmetric key suitable for symmetric encryption.
+   *
+   * @param privateKey - Opaque EC private key
+   * @param publicKey - Opaque EC public key of other party
+   * @param hkdfParams - Parameters for HKDF derivation
+   * @returns Opaque symmetric key
+   * @throws ConfigurationError if EC operations not supported
+   */
+  deriveKeyFromECDH: (
+    privateKey: PrivateKey,
+    publicKey: PublicKey,
+    hkdfParams: HkdfParams
+  ) => Promise<SymmetricKey>;
+
+  // === Key Import (PEM → opaque) ===
+
+  /**
+   * Import a PEM public key as an opaque key.
+   * @param pem - PEM-encoded public key
+   * @param options - Import options (usage required for RSA keys to disambiguate encrypt vs sign)
+   * @returns Opaque public key with metadata
+   */
+  importPublicKey: (pem: string, options: KeyOptions) => Promise<PublicKey>;
+
+  /**
+   * Import a PEM private key as an opaque key.
+   * Optional - intended for use in tests or by downstream integrators who need to bring
+   * their own PEM key material. Main SDK code should use opaque PrivateKey objects directly.
+   * @param pem - PEM-encoded private key
+   * @param options - Import options (usage required for RSA keys to disambiguate encrypt vs sign)
+   * @returns Opaque private key with metadata
+   */
+  importPrivateKey?: (pem: string, options: KeyOptions) => Promise<PrivateKey>;
+
+  /**
+   * Parse and validate a PEM public key, returning algorithm info.
+   *
+   * @param pem - PEM-encoded public key or X.509 certificate
+   * @returns Validated PEM and detected algorithm
+   * @throws ConfigurationError if key format invalid or algorithm not supported
+   */
+  parsePublicKeyPem: (pem: string) => Promise<PublicKeyInfo>;
+
+  // === Key Export (opaque → PEM/JWK) ===
+
+  /**
+   * Export an opaque public key to PEM format.
+   * @param key - Opaque public key
+   * @returns PEM-encoded public key (SPKI format)
+   */
+  exportPublicKeyPem: (key: PublicKey) => Promise<string>;
+
+  /**
+   * OPTIONAL -- ONLY USE FOR TESTING/DEVELOPMENT. Private keys should NOT be exportable in secure environments.
+   * Export an opaque private key to PEM format.
+   * @param key - Opaque private key
+   * @returns PEM-encoded private key (PKCS8 format)
+   */
+  exportPrivateKeyPem?: (key: PrivateKey) => Promise<string>;
+  /**
+   * Export an opaque public key to JWK format.
+   * @param key - Opaque public key
+   * @returns JWK representation
+   */
+  exportPublicKeyJwk: (key: PublicKey) => Promise<JsonWebKey>;
+
+  /**
+   * Extract PEM public key from X.509 certificate or return PEM key as-is.
+   *
+   * Used to normalize KAS public keys which may be provided as either:
+   * - X.509 certificates (-----BEGIN CERTIFICATE-----)
+   * - Raw PEM public keys (-----BEGIN PUBLIC KEY-----)
+   *
+   * For certificates, jwaAlgorithm must be provided to correctly parse the key
+   * (e.g., 'RS256', 'RS512', 'ES256', 'ES384', 'ES512'). For raw PEM keys,
+   * the algorithm parameter is ignored.
+   *
+   * @param certOrPem - PEM-encoded public key or X.509 certificate
+   * @param jwaAlgorithm - JWA algorithm for certificate parsing (required for certificates)
+   * @returns PEM-encoded public key (SPKI format)
+   * @throws Error if input is not valid PEM or certificate
+   */
+  extractPublicKeyPem: (certOrPem: string, jwaAlgorithm?: string) => Promise<string>;
+
+  /**
+   * Convert a JWK (JSON Web Key) public key to PEM format.
+   * Supports both RSA and EC keys.
+   *
+   * @param jwk - JSON Web Key object
+   * @returns PEM-encoded public key
+   * @throws ConfigurationError if JWK format invalid
+   */
+  jwkToPublicKeyPem: (jwk: JsonWebKey) => Promise<string>;
+
+  // === Symmetric Key Operations ===
+
+  /**
+   * Import raw key bytes as an opaque symmetric key.
+   * Used for external keys (e.g., unwrapped from KAS).
+   * @param keyBytes - Raw key bytes
+   * @returns Opaque symmetric key
+   */
+  importSymmetricKey: (keyBytes: Uint8Array) => Promise<SymmetricKey>;
+
+  /**
+   * Split a symmetric key into N shares using XOR secret sharing.
+   *
+   * DefaultCryptoService: Uses keySplit() utility (extracts bytes internally)
+   * HSM implementations: Must use native splitting OR throw ConfigurationError
+   *
+   * @param key - Symmetric key to split
+   * @param numShares - Number of shares to create
+   * @returns Array of opaque key shares
+   * @throws ConfigurationError if not supported by the implementation
+   *
+   * Note: Multi-KAS may not be available in all secure environments (single KAS only)
+   */
+  splitSymmetricKey: (key: SymmetricKey, numShares: number) => Promise<SymmetricKey[]>;
+
+  /**
+   * Merge symmetric key shares back into the original key using XOR.
+   *
+   * @param shares - Array of key shares (from splitSymmetricKey)
+   * @returns Merged symmetric key
+   * @throws ConfigurationError if not supported by the implementation
+   */
+  mergeSymmetricKeys: (shares: SymmetricKey[]) => Promise<SymmetricKey>;
 };