wkd-checker 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jonatan_M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# WKD Checker
+A Node.js library for retrieving and validating OpenPGP keys from Web Key Directory (WKD) servers.
+
+## Example Usage
+
+```js
+const wkd = require('wkd-checker');
+
+const email = 'test@example.com';
+
+wkd.checkKey(email)
+    .then(result => {
+        console.log('WKD Result:', result);
+        console.log('Advanced:', result.advanced.valid);
+        console.log('Direct:', result.direct.valid);
+    })
+
+wkd.getKey(email)
+    .then(key => {
+        console.log('Retrieved Key:\n', key);
+    })
+    .catch(err => {
+        console.error('Error retrieving key:', err);
+    });
+```

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Result of a key check operation.
+ */
+export interface KeyCheckResult {
+    policyAvailable: boolean;
+    policyCorsValid: boolean;
+    key_location: string | null;
+    key_available: boolean;
+    keyCorsValid: boolean;
+    keyType: KeyType;
+    keyTypeValid: boolean;
+    fingerprint: string | null;
+    emailInKey: boolean;
+    valid: boolean;
+}
+/**
+ * Enum representing the type of key found.
+ */
+export declare enum KeyType {
+    Invalid = "Invalid",
+    BinaryKey = "BinaryKey",
+    ArmoredKey = "ArmoredKey"
+}
+export declare class WKDError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates an email address format.
+ * @param {string} email - The email address to validate.
+ * @returns {boolean} True if the email is valid, false otherwise.
+ */
+export declare const validateEmail: (email: string) => boolean;
+/**
+ * Search for a public key using Web Key Directory protocol.
+ * @param {string} email - User's email.
+ * @returns {Promise<Uint8Array>} The public key.
+ */
+export declare const getKey: (email: string) => Promise<Uint8Array>;
+/**
+ * Processes an email to find WKD keys using both Advanced and Direct methods.
+ * @param {string} email - The email address to look up.
+ * @returns {Promise<{ advanced: KeyCheckResult, direct: KeyCheckResult }>} Results for both lookup methods.
+ */
+export declare const checkKey: (email: string) => Promise<{
+    advanced: KeyCheckResult;
+    direct: KeyCheckResult;
+}>;

package/dist/index.js

@@ -0,0 +1,214 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkKey = exports.getKey = exports.validateEmail = exports.WKDError = exports.KeyType = void 0;
+const openpgp_1 = require("openpgp");
+/**
+ * Enum representing the type of key found.
+ */
+var KeyType;
+(function (KeyType) {
+    KeyType["Invalid"] = "Invalid";
+    KeyType["BinaryKey"] = "BinaryKey";
+    KeyType["ArmoredKey"] = "ArmoredKey";
+})(KeyType || (exports.KeyType = KeyType = {}));
+class WKDError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WKDError";
+    }
+}
+exports.WKDError = WKDError;
+const EMAIL_REGEX = /^[^@]+@[^@]+\.[^@]+$/;
+/**
+ * Validates an email address format.
+ * @param {string} email - The email address to validate.
+ * @returns {boolean} True if the email is valid, false otherwise.
+ */
+const validateEmail = (email) => EMAIL_REGEX.test(email);
+exports.validateEmail = validateEmail;
+/**
+ * Fetches a URL and checks for CORS headers.
+ * @param {string} url - The URL to fetch.
+ * @param {RequestInit} options - Fetch options.
+ * @returns {Promise<{ response: Response | null, corsValid: boolean }>} The response and CORS validity status.
+ */
+const fetchWithCorsCheck = (url, options) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const response = yield fetch(url, options);
+        const corsValid = response.headers.get("access-control-allow-origin") === "*";
+        return { response: response.ok ? response : null, corsValid };
+    }
+    catch (_a) {
+        return { response: null, corsValid: false };
+    }
+});
+/**
+ * Detects the type of OpenPGP key (Armor or Binary).
+ * @param {Response} keyData - The response containing the key data.
+ * @returns {Promise<{ keyType: KeyType, key: Key | null }>} The detected key type and parsed key object.
+ */
+const detectKeyType = (keyData) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const buffer = yield keyData.clone().arrayBuffer();
+        const binaryKey = new Uint8Array(buffer);
+        const header = "-----BEGIN PGP PUBLIC KEY BLOCK-----";
+        const prefix = new TextDecoder().decode(binaryKey.slice(0, header.length));
+        if (prefix === header) {
+            const text = new TextDecoder().decode(binaryKey);
+            const key = yield (0, openpgp_1.readKey)({ armoredKey: text });
+            return { keyType: KeyType.ArmoredKey, key };
+        }
+        else {
+            const key = yield (0, openpgp_1.readKey)({ binaryKey });
+            return { keyType: KeyType.BinaryKey, key };
+        }
+    }
+    catch (_a) {
+        return { keyType: KeyType.Invalid, key: null };
+    }
+});
+/**
+ * Checks for a key at a specific WKD URL.
+ * @param {string} url - The WKD URL for the key.
+ * @param {string} policy - The policy URL.
+ * @param {RequestInit} options - Fetch options.
+ * @param {string} email - The email address used to verify the key user ID.
+ * @returns {Promise<KeyCheckResult>} The result of the key check.
+ */
+const checkKeyUrl = (url, policy, options, email) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const [policyData, keyData] = yield Promise.all([
+        fetchWithCorsCheck(policy, options),
+        fetchWithCorsCheck(url, options)
+    ]);
+    const result = {
+        policyAvailable: !!policyData.response,
+        policyCorsValid: policyData.corsValid,
+        key_location: ((_a = keyData.response) === null || _a === void 0 ? void 0 : _a.url) || url,
+        key_available: !!keyData.response,
+        keyCorsValid: keyData.corsValid,
+        keyType: KeyType.Invalid,
+        keyTypeValid: false,
+        fingerprint: null,
+        emailInKey: false,
+        valid: false,
+    };
+    if (keyData.response) {
+        const { keyType, key } = yield detectKeyType(keyData.response);
+        result.keyType = keyType;
+        result.keyTypeValid = keyType === KeyType.BinaryKey;
+        if (key) {
+            const identities = yield key.getUserIDs();
+            result.emailInKey = identities.some(identity => identity.includes(email));
+            result.fingerprint = key.getFingerprint().toUpperCase();
+        }
+    }
+    result.valid = result.policyAvailable && result.policyCorsValid && result.key_available && result.keyCorsValid && result.keyTypeValid && result.emailInKey;
+    return result;
+});
+/**
+ * Encode input using Z-Base32 encoding.
+ *
+ * @param {Uint8Array} data - The binary data to encode
+ * @returns {String} Binary data encoded using Z-Base32.
+ */
+function zbase32Encode(data) {
+    if (data.length === 0) {
+        return "";
+    }
+    const ALPHABET = "ybndrfg8ejkmcpqxot1uwisza345h769";
+    const SHIFT = 5;
+    const MASK = 31;
+    let buffer = data[0];
+    let index = 1;
+    let bitsLeft = 8;
+    let result = '';
+    while (bitsLeft > 0 || index < data.length) {
+        if (bitsLeft < SHIFT) {
+            if (index < data.length) {
+                buffer <<= 8;
+                buffer |= data[index++] & 0xff;
+                bitsLeft += 8;
+            }
+            else {
+                const pad = SHIFT - bitsLeft;
+                buffer <<= pad;
+                bitsLeft += pad;
+            }
+        }
+        bitsLeft -= SHIFT;
+        result += ALPHABET[MASK & (buffer >> bitsLeft)];
+    }
+    return result;
+}
+/**
+ * Generates WKD URLs for a given email address.
+ * @param {string} email - The email address.
+ * @returns {Promise<{ advancedUrl: string, directUrl: string, advancedPolicyUrl: string, directPolicyUrl: string }>} The generated URLs.
+ */
+const generateWkdUrls = (email) => __awaiter(void 0, void 0, void 0, function* () {
+    const [localPart, domain] = email.split('@');
+    // Spec Requirement: map uppercase ASCII to lowercase. Non-ASCII are not changed.
+    const localPartHashInput = localPart.replace(/[A-Z]/g, c => c.toLowerCase());
+    const domainLower = domain.toLowerCase();
+    const hashBuffer = yield crypto.subtle.digest("SHA-1", new TextEncoder().encode(localPartHashInput));
+    const hash = zbase32Encode(new Uint8Array(hashBuffer));
+    const nameParam = encodeURIComponent(localPart);
+    return {
+        advancedUrl: `https://openpgpkey.${domainLower}/.well-known/openpgpkey/${domainLower}/hu/${hash}?l=${nameParam}`,
+        directUrl: `https://${domainLower}/.well-known/openpgpkey/hu/${hash}?l=${nameParam}`,
+        advancedPolicyUrl: `https://openpgpkey.${domainLower}/.well-known/openpgpkey/policy`,
+        directPolicyUrl: `https://${domainLower}/.well-known/openpgpkey/policy`
+    };
+});
+/**
+ * Search for a public key using Web Key Directory protocol.
+ * @param {string} email - User's email.
+ * @returns {Promise<Uint8Array>} The public key.
+ */
+const getKey = (email) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!(0, exports.validateEmail)(email)) {
+        throw new WKDError('Invalid e-mail address.');
+    }
+    const { advancedUrl, directUrl } = yield generateWkdUrls(email);
+    const urls = [advancedUrl, directUrl];
+    for (const url of urls) {
+        try {
+            const response = yield fetch(url);
+            if (response.ok) {
+                return new Uint8Array(yield response.arrayBuffer());
+            }
+        }
+        catch (_a) {
+            // Ignore error and try next URL
+        }
+    }
+    throw new WKDError('No keys found');
+});
+exports.getKey = getKey;
+/**
+ * Processes an email to find WKD keys using both Advanced and Direct methods.
+ * @param {string} email - The email address to look up.
+ * @returns {Promise<{ advanced: KeyCheckResult, direct: KeyCheckResult }>} Results for both lookup methods.
+ */
+const checkKey = (email) => __awaiter(void 0, void 0, void 0, function* () {
+    const { advancedUrl, directUrl, advancedPolicyUrl, directPolicyUrl } = yield generateWkdUrls(email);
+    const options = {
+        headers: { "User-Agent": "WKD-Checker (+https://miarecki.eu/posts/web-key-directory-setup/)" }
+    };
+    const [advancedResult, directResult] = yield Promise.all([
+        checkKeyUrl(advancedUrl, advancedPolicyUrl, options, email),
+        checkKeyUrl(directUrl, directPolicyUrl, options, email)
+    ]);
+    return { advanced: advancedResult, direct: directResult };
+});
+exports.checkKey = checkKey;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "wkd-checker",
+  "version": "1.1.1",
+  "description": "Web Key Directory library for Node.js. Retreive OpenPGP keys from WKD servers and validate them.",
+  "author": "Jonatan Miarecki",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.2"
+  },
+  "dependencies": {
+    "openpgp": "^6.3.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}