@raytio/core 11.5.0 → 11.6.0

package/dist/accessApplication/api/legacy/convertRelationships.d.ts

@@ -3,11 +3,9 @@ import type { IId, NId, PId, Relationship } from "@raytio/types";
 export type ServerRelationship = Omit<Relationship, "p_id" | "start" | "end"> & {
     id: PId;
     from_id: NId;
-} & ({
-    to_id: NId;
-} | {
-    to_i_id: IId;
-});
+    to_id?: NId | null;
+    to_i_id?: IId | null;
+};
 /**
  * Converts relationship type used by the server into the (Urn format) type used by the client
  * @param serverRelationship relationship type used in the server

package/dist/accessApplication/api/legacy/convertRelationships.js

@@ -13,8 +13,8 @@ function convertServerRelationship(serverRelationship) {
      * This functionality is similar to LinkToCrust, but in this case the API has already worked out
      * which instance the PO links to (if any) so we simply convert it into a {@link Urn}
      */
-    const end = "to_id" in serverRelationship
-        ? `urn:profile_object:${serverRelationship.to_id}`
-        : `urn:instance:${serverRelationship.to_i_id}`;
+    const end = serverRelationship.to_i_id
+        ? `urn:instance:${serverRelationship.to_i_id}`
+        : `urn:profile_object:${serverRelationship.to_id}`;
     return Object.assign({ p_id: id, start: `urn:profile_object:${from_id}`, end }, (0, ramda_1.omit)(["id", "from_id", "to_id", "to_i_id"], serverRelationship));
 }

package/dist/crypto/cognitoAttributes.d.ts

@@ -4,6 +4,9 @@ import type { ICognitoUserAttributeData } from "amazon-cognito-identity-js";
  * Given a `UserDoc` from the maxcryptor, this returns an object
  * which you can provide to `Auth.updateUserAttributes()`. It is
  * an object of stringified Json.
+ *
+ * Note: Only includes attributes that exist in userDoc. Missing attributes
+ * are filtered out to avoid Cognito "Attribute value must not be null" errors.
  */
 export declare const toCognitoAttributes: (userDoc: UserDoc) => {
     [customCognitoName: string]: string;

package/dist/crypto/cognitoAttributes.js

@@ -9,16 +9,27 @@ const ATTRIBUTE_MAP = {
     "custom:aek_private": ["encryption_key_pair", "private_key"],
     "custom:ask_public": ["signing_key_pair", "public_key"],
     "custom:ask_private": ["signing_key_pair", "private_key"],
+    // Two-Secret Key Derivation (2SKD) attributes - Issue #1649
+    "custom:kdf_version": ["kdf_version"],
+    "custom:kdf_config": ["kdf_config"],
 };
 /**
  * Given a `UserDoc` from the maxcryptor, this returns an object
  * which you can provide to `Auth.updateUserAttributes()`. It is
  * an object of stringified Json.
+ *
+ * Note: Only includes attributes that exist in userDoc. Missing attributes
+ * are filtered out to avoid Cognito "Attribute value must not be null" errors.
  */
-const toCognitoAttributes = (userDoc) => Object.fromEntries(Object.entries(ATTRIBUTE_MAP).map(([cognitoKey, deepPath]) => [
-    cognitoKey,
-    JSON.stringify((0, ramda_1.path)(deepPath, userDoc)),
-]));
+const toCognitoAttributes = (userDoc) => Object.fromEntries(Object.entries(ATTRIBUTE_MAP)
+    .map(([cognitoKey, deepPath]) => {
+    const value = (0, ramda_1.path)(deepPath, userDoc);
+    // Filter out undefined values - Cognito rejects null attribute values
+    if (value === undefined)
+        return undefined;
+    return [cognitoKey, JSON.stringify(value)];
+})
+    .filter((entry) => entry !== undefined));
 exports.toCognitoAttributes = toCognitoAttributes;
 /**
  * This function converts Cognito's userAttributes into a maxcryptor UserDoc.

package/dist/crypto/getAADecryptor.d.ts

@@ -11,7 +11,7 @@ type PublicKeyNode = CommonNodeFields<KId> & {
  */
 export declare function getAAPublicKey({ apiUrl, apiToken, aId, }: {
     apiUrl: string;
-    apiToken: string;
+    apiToken?: string;
     aId: AId;
 }): Promise<PublicKeyNode>;
 /**

package/dist/crypto/getAADecryptor.js

@@ -8,9 +8,7 @@ const util_1 = require("../util");
  * @returns the id and Key information of the Applications Public Key
  */
 async function getAAPublicKey({ apiUrl, apiToken, aId, }) {
-    const [publicKey] = await fetch(`${apiUrl}/db/v1/dsm_access_application_public_keys?aa_id=eq.${aId}`, {
-        headers: { Authorization: `Bearer ${apiToken}` },
-    }).then(util_1.handleResponse);
+    const [publicKey] = await fetch(`${apiUrl}/db/v1/dsm_access_application_public_keys?aa_id=eq.${aId}`, Object.assign({}, (apiToken && { headers: { Authorization: `Bearer ${apiToken}` } }))).then(util_1.handleResponse);
     if (!publicKey) {
         throw new Error("Could not Find Encryption Key");
     }

package/dist/crypto/index.d.ts

@@ -2,3 +2,6 @@ export * from "./cognitoAttributes";
 export * from "./decryptSharedData";
 export * from "./getAADecryptor";
 export * from "./helpers";
+export * from "./kdf";
+export * from "./localSecret";
+export * from "./pgpKey";

package/dist/crypto/index.js

@@ -19,3 +19,9 @@ __exportStar(require("./cognitoAttributes"), exports);
 __exportStar(require("./decryptSharedData"), exports);
 __exportStar(require("./getAADecryptor"), exports);
 __exportStar(require("./helpers"), exports);
+// KDF module - Two-Secret Key Derivation (Issue #1649)
+__exportStar(require("./kdf"), exports);
+// LocalSecret module - device-bound secrets (Issue #1649)
+__exportStar(require("./localSecret"), exports);
+// PGP Key module - device-bound PGP keys (Issue #1374)
+__exportStar(require("./pgpKey"), exports);

package/dist/crypto/kdf/argon2.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Argon2id Key Derivation
+ *
+ * Modern memory-hard key derivation using Argon2id.
+ * Requires the argon2-browser package for WASM implementation.
+ * Issue #1649
+ */
+import type { Argon2idConfig, KdfResult } from "./types";
+/**
+ * Argon2 type constants
+ * These match the values from argon2-browser's ArgonType enum
+ */
+export declare const ARGON2_TYPE: {
+    readonly Argon2d: 0;
+    readonly Argon2i: 1;
+    readonly Argon2id: 2;
+};
+type Argon2Module = {
+    hash: (options: {
+        pass: string | Uint8Array;
+        salt: Uint8Array;
+        type: number;
+        time: number;
+        mem: number;
+        parallelism: number;
+        hashLen: number;
+    }) => Promise<{
+        hash: Uint8Array;
+        encoded: string;
+    }>;
+    ArgonType?: {
+        Argon2d: number;
+        Argon2i: number;
+        Argon2id: number;
+    };
+};
+/**
+ * Set the Argon2 module reference
+ *
+ * This must be called before using deriveArgon2id.
+ * The module is passed in from packages/client where argon2-browser is imported.
+ *
+ * @param module - The argon2-browser module
+ */
+export declare function setArgon2Module(module: Argon2Module): void;
+/**
+ * Check if Argon2 module is available
+ */
+export declare function isArgon2Available(): boolean;
+/**
+ * Derive a key using Argon2id
+ *
+ * @param password - User's password (will be normalized)
+ * @param config - Argon2id configuration from Cognito attributes
+ * @returns KdfResult containing the derived 32-byte key
+ * @throws Error if argon2 module is not available
+ */
+export declare function deriveArgon2id(password: string, config: Argon2idConfig): Promise<KdfResult>;
+/**
+ * Create a new Argon2id configuration
+ *
+ * @param salt - Base64 encoded salt (optional, will generate if not provided)
+ * @param params - Optional custom parameters
+ * @returns Argon2idConfig ready for storage
+ */
+export declare function createArgon2idConfig(salt: string, params?: Partial<Pick<Argon2idConfig, "memory" | "iterations" | "parallelism">>): Argon2idConfig;
+export {};

package/dist/crypto/kdf/argon2.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Argon2id Key Derivation
+ *
+ * Modern memory-hard key derivation using Argon2id.
+ * Requires the argon2-browser package for WASM implementation.
+ * Issue #1649
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARGON2_TYPE = void 0;
+exports.setArgon2Module = setArgon2Module;
+exports.isArgon2Available = isArgon2Available;
+exports.deriveArgon2id = deriveArgon2id;
+exports.createArgon2idConfig = createArgon2idConfig;
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+/**
+ * Argon2 type constants
+ * These match the values from argon2-browser's ArgonType enum
+ */
+exports.ARGON2_TYPE = {
+    Argon2d: 0,
+    Argon2i: 1,
+    Argon2id: 2,
+};
+// Module-level reference to argon2, set via setArgon2Module
+let argon2Module = null;
+/**
+ * Set the Argon2 module reference
+ *
+ * This must be called before using deriveArgon2id.
+ * The module is passed in from packages/client where argon2-browser is imported.
+ *
+ * @param module - The argon2-browser module
+ */
+function setArgon2Module(module) {
+    // eslint-disable-next-line fp/no-mutation -- Module-level singleton pattern
+    argon2Module = module;
+}
+/**
+ * Check if Argon2 module is available
+ */
+function isArgon2Available() {
+    return argon2Module !== null;
+}
+/**
+ * Derive a key using Argon2id
+ *
+ * @param password - User's password (will be normalized)
+ * @param config - Argon2id configuration from Cognito attributes
+ * @returns KdfResult containing the derived 32-byte key
+ * @throws Error if argon2 module is not available
+ */
+async function deriveArgon2id(password, config) {
+    var _a, _b, _c;
+    if (!argon2Module) {
+        throw new Error("Argon2 module not available. Call setArgon2Module() first.");
+    }
+    // Normalize password for consistent derivation
+    const normalizedPassword = (0, utils_1.normalizePassword)(password);
+    // Decode salt from base64
+    const salt = (0, utils_1.base64ToUint8Array)(config.salt);
+    // Use config values or defaults
+    const memory = (_a = config.memory) !== null && _a !== void 0 ? _a : types_1.DEFAULT_ARGON2ID_PARAMS.memory;
+    const iterations = (_b = config.iterations) !== null && _b !== void 0 ? _b : types_1.DEFAULT_ARGON2ID_PARAMS.iterations;
+    const parallelism = (_c = config.parallelism) !== null && _c !== void 0 ? _c : types_1.DEFAULT_ARGON2ID_PARAMS.parallelism;
+    // Derive key using Argon2id
+    const result = await argon2Module.hash({
+        pass: normalizedPassword,
+        salt,
+        type: exports.ARGON2_TYPE.Argon2id,
+        time: iterations,
+        mem: memory,
+        parallelism,
+        hashLen: 32, // 256 bits
+    });
+    return {
+        key: result.hash,
+    };
+}
+/**
+ * Create a new Argon2id configuration
+ *
+ * @param salt - Base64 encoded salt (optional, will generate if not provided)
+ * @param params - Optional custom parameters
+ * @returns Argon2idConfig ready for storage
+ */
+function createArgon2idConfig(salt, params) {
+    var _a, _b, _c;
+    return {
+        algorithm_name: "Argon2id",
+        memory: (_a = params === null || params === void 0 ? void 0 : params.memory) !== null && _a !== void 0 ? _a : types_1.DEFAULT_ARGON2ID_PARAMS.memory,
+        iterations: (_b = params === null || params === void 0 ? void 0 : params.iterations) !== null && _b !== void 0 ? _b : types_1.DEFAULT_ARGON2ID_PARAMS.iterations,
+        parallelism: (_c = params === null || params === void 0 ? void 0 : params.parallelism) !== null && _c !== void 0 ? _c : types_1.DEFAULT_ARGON2ID_PARAMS.parallelism,
+        salt,
+        version: 2,
+        requires_local_secret: true,
+    };
+}

package/dist/crypto/kdf/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Key Derivation Function (KDF) Module
+ *
+ * Provides a unified interface for key derivation supporting both:
+ * - Legacy PBKDF2 (v1)
+ * - Modern Argon2id with Two-Secret Key Derivation (v2)
+ *
+ * Issue #1649
+ */
+import type { KdfConfig, KdfResult } from "./types";
+export * from "./types";
+export { base64ToUint8Array, uint8ArrayToBase64, xorBytes, normalizePassword, generateRandomBytes, generateSalt, constantTimeEqual, } from "./utils";
+export { derivePbkdf2 } from "./pbkdf2";
+export { deriveArgon2id, setArgon2Module, isArgon2Available, createArgon2idConfig, } from "./argon2";
+export { deriveTwoSecretKdf, isValidLocalSecret } from "./twoSecretKdf";
+/**
+ * Derive a key using the appropriate KDF based on configuration
+ *
+ * This is the main entry point for key derivation. It automatically
+ * selects the correct algorithm based on the config.
+ *
+ * @param password - User's password
+ * @param config - KDF configuration from Cognito attributes
+ * @param localSecret - Optional LocalSecret for 2SKD (required for Argon2id with requires_local_secret)
+ * @returns KdfResult containing the derived key
+ * @throws LocalSecretRequiredError if LocalSecret is required but not provided
+ * @throws UnknownKdfAlgorithmError if the algorithm is not recognized
+ */
+export declare function deriveKey(password: string, config: KdfConfig, localSecret?: Uint8Array | null): Promise<KdfResult>;
+/**
+ * Check if a KDF configuration requires LocalSecret
+ *
+ * @param config - KDF configuration
+ * @returns true if LocalSecret is required
+ */
+export declare function requiresLocalSecret(config: KdfConfig): boolean;
+/**
+ * Get the KDF version from configuration
+ *
+ * @param config - KDF configuration
+ * @returns Version number (1 for PBKDF2, 2 for Argon2id with 2SKD)
+ */
+export declare function getKdfVersion(config: KdfConfig): number;

package/dist/crypto/kdf/index.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Key Derivation Function (KDF) Module
+ *
+ * Provides a unified interface for key derivation supporting both:
+ * - Legacy PBKDF2 (v1)
+ * - Modern Argon2id with Two-Secret Key Derivation (v2)
+ *
+ * Issue #1649
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidLocalSecret = exports.deriveTwoSecretKdf = exports.createArgon2idConfig = exports.isArgon2Available = exports.setArgon2Module = exports.deriveArgon2id = exports.derivePbkdf2 = exports.constantTimeEqual = exports.generateSalt = exports.generateRandomBytes = exports.normalizePassword = exports.xorBytes = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = void 0;
+exports.deriveKey = deriveKey;
+exports.requiresLocalSecret = requiresLocalSecret;
+exports.getKdfVersion = getKdfVersion;
+const types_1 = require("./types");
+const pbkdf2_1 = require("./pbkdf2");
+const twoSecretKdf_1 = require("./twoSecretKdf");
+// Re-export types
+__exportStar(require("./types"), exports);
+// Re-export utils
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "base64ToUint8Array", { enumerable: true, get: function () { return utils_1.base64ToUint8Array; } });
+Object.defineProperty(exports, "uint8ArrayToBase64", { enumerable: true, get: function () { return utils_1.uint8ArrayToBase64; } });
+Object.defineProperty(exports, "xorBytes", { enumerable: true, get: function () { return utils_1.xorBytes; } });
+Object.defineProperty(exports, "normalizePassword", { enumerable: true, get: function () { return utils_1.normalizePassword; } });
+Object.defineProperty(exports, "generateRandomBytes", { enumerable: true, get: function () { return utils_1.generateRandomBytes; } });
+Object.defineProperty(exports, "generateSalt", { enumerable: true, get: function () { return utils_1.generateSalt; } });
+Object.defineProperty(exports, "constantTimeEqual", { enumerable: true, get: function () { return utils_1.constantTimeEqual; } });
+// Re-export PBKDF2
+var pbkdf2_2 = require("./pbkdf2");
+Object.defineProperty(exports, "derivePbkdf2", { enumerable: true, get: function () { return pbkdf2_2.derivePbkdf2; } });
+// Re-export Argon2id
+var argon2_1 = require("./argon2");
+Object.defineProperty(exports, "deriveArgon2id", { enumerable: true, get: function () { return argon2_1.deriveArgon2id; } });
+Object.defineProperty(exports, "setArgon2Module", { enumerable: true, get: function () { return argon2_1.setArgon2Module; } });
+Object.defineProperty(exports, "isArgon2Available", { enumerable: true, get: function () { return argon2_1.isArgon2Available; } });
+Object.defineProperty(exports, "createArgon2idConfig", { enumerable: true, get: function () { return argon2_1.createArgon2idConfig; } });
+// Re-export Two-Secret KDF
+var twoSecretKdf_2 = require("./twoSecretKdf");
+Object.defineProperty(exports, "deriveTwoSecretKdf", { enumerable: true, get: function () { return twoSecretKdf_2.deriveTwoSecretKdf; } });
+Object.defineProperty(exports, "isValidLocalSecret", { enumerable: true, get: function () { return twoSecretKdf_2.isValidLocalSecret; } });
+/**
+ * Derive a key using the appropriate KDF based on configuration
+ *
+ * This is the main entry point for key derivation. It automatically
+ * selects the correct algorithm based on the config.
+ *
+ * @param password - User's password
+ * @param config - KDF configuration from Cognito attributes
+ * @param localSecret - Optional LocalSecret for 2SKD (required for Argon2id with requires_local_secret)
+ * @returns KdfResult containing the derived key
+ * @throws LocalSecretRequiredError if LocalSecret is required but not provided
+ * @throws UnknownKdfAlgorithmError if the algorithm is not recognized
+ */
+async function deriveKey(password, config, localSecret) {
+    if ((0, types_1.isPbkdf2Config)(config)) {
+        // Legacy v1: PBKDF2 only
+        return (0, pbkdf2_1.derivePbkdf2)(password, config);
+    }
+    if ((0, types_1.isArgon2idConfig)(config)) {
+        // v2: Argon2id with optional 2SKD
+        return (0, twoSecretKdf_1.deriveTwoSecretKdf)(password, config, localSecret);
+    }
+    // Unknown algorithm
+    throw new types_1.UnknownKdfAlgorithmError(config.algorithm_name);
+}
+/**
+ * Check if a KDF configuration requires LocalSecret
+ *
+ * @param config - KDF configuration
+ * @returns true if LocalSecret is required
+ */
+function requiresLocalSecret(config) {
+    return (0, types_1.isArgon2idConfig)(config) && config.requires_local_secret === true;
+}
+/**
+ * Get the KDF version from configuration
+ *
+ * @param config - KDF configuration
+ * @returns Version number (1 for PBKDF2, 2 for Argon2id with 2SKD)
+ */
+function getKdfVersion(config) {
+    var _a;
+    if ((0, types_1.isPbkdf2Config)(config)) {
+        return 1;
+    }
+    if ((0, types_1.isArgon2idConfig)(config)) {
+        return (_a = config.version) !== null && _a !== void 0 ? _a : 2;
+    }
+    return 0; // Unknown
+}

package/dist/crypto/kdf/pbkdf2.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PBKDF2 Key Derivation
+ *
+ * Legacy v1 key derivation using PBKDF2-SHA512.
+ * This module extracts the existing PBKDF2 logic for backward compatibility.
+ * Issue #1649
+ */
+import type { KdfResult, Pbkdf2Config } from "./types";
+/**
+ * Derive a key using PBKDF2
+ *
+ * @param password - User's password
+ * @param config - PBKDF2 configuration from Cognito attributes
+ * @returns KdfResult containing the derived 32-byte key
+ */
+export declare function derivePbkdf2(password: string, config: Pbkdf2Config): Promise<KdfResult>;

package/dist/crypto/kdf/pbkdf2.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * PBKDF2 Key Derivation
+ *
+ * Legacy v1 key derivation using PBKDF2-SHA512.
+ * This module extracts the existing PBKDF2 logic for backward compatibility.
+ * Issue #1649
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.derivePbkdf2 = derivePbkdf2;
+const utils_1 = require("./utils");
+/**
+ * Derive a key using PBKDF2
+ *
+ * @param password - User's password
+ * @param config - PBKDF2 configuration from Cognito attributes
+ * @returns KdfResult containing the derived 32-byte key
+ */
+async function derivePbkdf2(password, config) {
+    const encoder = new TextEncoder();
+    const passwordBuffer = encoder.encode(password);
+    // Import password as key material
+    const passwordKey = await crypto.subtle.importKey("raw", passwordBuffer, "PBKDF2", false, ["deriveBits", "deriveKey"]);
+    // Decode salt from base64
+    const salt = (0, utils_1.base64ToUint8Array)(config.salt);
+    // Normalize hash name (e.g., "SHA512" -> "SHA-512", "SHA-512" -> "SHA-512")
+    const hashUpper = config.hash.toUpperCase();
+    // Handle both "SHA512" and "SHA-512" formats
+    const hashName = hashUpper.includes("-")
+        ? hashUpper
+        : hashUpper.replace(/^(SHA)(\d+)$/, "$1-$2");
+    // Derive the key
+    const derivedKey = await crypto.subtle.deriveKey({
+        name: "PBKDF2",
+        salt,
+        iterations: config.iterations,
+        hash: hashName,
+    }, passwordKey, { name: "AES-GCM", length: 256 }, true, // extractable
+    ["encrypt", "decrypt"]);
+    // Export as raw bytes
+    const keyBuffer = await crypto.subtle.exportKey("raw", derivedKey);
+    return {
+        key: new Uint8Array(keyBuffer),
+    };
+}

package/dist/crypto/kdf/twoSecretKdf.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Two-Secret Key Derivation (2SKD)
+ *
+ * Combines password-derived key with LocalSecret using XOR.
+ * This follows the 1Password security model where both secrets
+ * are required to derive the Key Encryption Key (KEK).
+ *
+ * Security properties:
+ * - Password alone cannot derive KEK
+ * - LocalSecret alone cannot derive KEK
+ * - Both are required, providing two-factor encryption
+ *
+ * Issue #1649
+ */
+import type { Argon2idConfig, KdfResult } from "./types";
+/**
+ * Derive KEK using Two-Secret Key Derivation
+ *
+ * Combines:
+ * 1. Password → Argon2id → 32 bytes
+ * 2. LocalSecret → 32 bytes
+ * 3. XOR(1, 2) → KEK
+ *
+ * @param password - User's password
+ * @param config - Argon2id configuration
+ * @param localSecret - Device-bound LocalSecret (32 bytes)
+ * @returns KdfResult containing the derived KEK
+ * @throws LocalSecretRequiredError if localSecret is not provided but required
+ */
+export declare function deriveTwoSecretKdf(password: string, config: Argon2idConfig, localSecret: Uint8Array | null | undefined): Promise<KdfResult>;
+/**
+ * Verify that a LocalSecret is valid
+ *
+ * @param localSecret - The LocalSecret to verify
+ * @returns true if valid
+ */
+export declare function isValidLocalSecret(localSecret: Uint8Array | null | undefined): localSecret is Uint8Array;

package/dist/crypto/kdf/twoSecretKdf.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Two-Secret Key Derivation (2SKD)
+ *
+ * Combines password-derived key with LocalSecret using XOR.
+ * This follows the 1Password security model where both secrets
+ * are required to derive the Key Encryption Key (KEK).
+ *
+ * Security properties:
+ * - Password alone cannot derive KEK
+ * - LocalSecret alone cannot derive KEK
+ * - Both are required, providing two-factor encryption
+ *
+ * Issue #1649
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveTwoSecretKdf = deriveTwoSecretKdf;
+exports.isValidLocalSecret = isValidLocalSecret;
+const types_1 = require("./types");
+const argon2_1 = require("./argon2");
+const utils_1 = require("./utils");
+/**
+ * Derive KEK using Two-Secret Key Derivation
+ *
+ * Combines:
+ * 1. Password → Argon2id → 32 bytes
+ * 2. LocalSecret → 32 bytes
+ * 3. XOR(1, 2) → KEK
+ *
+ * @param password - User's password
+ * @param config - Argon2id configuration
+ * @param localSecret - Device-bound LocalSecret (32 bytes)
+ * @returns KdfResult containing the derived KEK
+ * @throws LocalSecretRequiredError if localSecret is not provided but required
+ */
+async function deriveTwoSecretKdf(password, config, localSecret) {
+    // Check if LocalSecret is required
+    if (config.requires_local_secret && !localSecret) {
+        throw new types_1.LocalSecretRequiredError();
+    }
+    // Derive key from password using Argon2id
+    const passwordDerived = await (0, argon2_1.deriveArgon2id)(password, config);
+    // If no LocalSecret, return password-derived key
+    // (fallback for accounts not using 2SKD)
+    if (!localSecret) {
+        return passwordDerived;
+    }
+    // Validate LocalSecret length
+    if (localSecret.length !== 32) {
+        throw new Error(`LocalSecret must be 32 bytes (got ${localSecret.length})`);
+    }
+    // XOR password-derived key with LocalSecret
+    const combinedKey = (0, utils_1.xorBytes)(passwordDerived.key, localSecret);
+    return {
+        key: combinedKey,
+    };
+}
+/**
+ * Verify that a LocalSecret is valid
+ *
+ * @param localSecret - The LocalSecret to verify
+ * @returns true if valid
+ */
+function isValidLocalSecret(localSecret) {
+    return localSecret instanceof Uint8Array && localSecret.length === 32;
+}

package/dist/crypto/kdf/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Key Derivation Function (KDF) Types
+ *
+ * Types for the Two-Secret Key Derivation (2SKD) system.
+ * Issue #1649
+ */
+/**
+ * PBKDF2 configuration (legacy v1)
+ */
+export interface Pbkdf2Config {
+    algorithm_name: "PBKDF2";
+    iterations: number;
+    hash: string;
+    salt: string;
+}
+/**
+ * Argon2id configuration (v2 with 2SKD)
+ */
+export interface Argon2idConfig {
+    algorithm_name: "Argon2id";
+    memory: number;
+    iterations: number;
+    parallelism: number;
+    salt: string;
+    version?: number;
+    requires_local_secret?: boolean;
+}
+/**
+ * Union type for all KDF configurations
+ */
+export type KdfConfig = Pbkdf2Config | Argon2idConfig;
+/**
+ * Result of key derivation
+ */
+export interface KdfResult {
+    key: Uint8Array;
+}
+/**
+ * Error thrown when LocalSecret is required but not provided
+ */
+export declare class LocalSecretRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when KDF algorithm is unknown
+ */
+export declare class UnknownKdfAlgorithmError extends Error {
+    constructor(algorithm: string);
+}
+/**
+ * Default Argon2id parameters (matching Bitwarden recommendations)
+ */
+export declare const DEFAULT_ARGON2ID_PARAMS: {
+    readonly memory: 65536;
+    readonly iterations: 3;
+    readonly parallelism: 4;
+};
+/**
+ * Type guard for PBKDF2 config
+ */
+export declare function isPbkdf2Config(config: KdfConfig): config is Pbkdf2Config;
+/**
+ * Type guard for Argon2id config
+ */
+export declare function isArgon2idConfig(config: KdfConfig): config is Argon2idConfig;