wkd-checker 1.2.0 → 2.0.0

package/dist/cli.js

@@ -35,6 +35,7 @@ const printSection = (title, result) => {
     const statusBadge = isWorking ? `${GREEN} ${statusLabel} ${RESET}` : `${RED} ${statusLabel} ${RESET}`;
     console.log(`\n${BOLD}${title}${RESET} ${statusBadge}`);
     console.log(`${DIM}------------------------------------------------------------${RESET}`);
+    console.log(`Policy Location:    ${CYAN}${result.policy_location}${RESET}`);
     console.log(`Policy Available:   ${formatBoolean(result.policyAvailable)}`);
     console.log(`Policy CORS Valid:  ${formatBoolean(result.policyCorsValid)}`);
     console.log(`\nKey Location:       ${CYAN}${result.key_location || 'N/A'}${RESET}`);

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * Result of a key check operation.
  */
 export interface KeyCheckResult {
+    policy_location: string;
     policyAvailable: boolean;
     policyCorsValid: boolean;
     key_location: string | null;

package/dist/index.js

@@ -28,6 +28,7 @@ class WKDError extends Error {
 }
 exports.WKDError = WKDError;
 const EMAIL_REGEX = /^[^@]+@[^@]+\.[^@]+$/;
+const USER_AGENT = "WKD-Checker (+https://www.npmjs.com/package/wkd-checker)";
 /**
  * Validates an email address format.
  * @param {string} email - The email address to validate.
@@ -44,6 +45,7 @@ exports.validateEmail = validateEmail;
 const fetchWithCorsCheck = (url, options) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const response = yield fetch(url, options);
+        // Spec does not mandate CORS, but it is beneficial for web clients (e.g. webmail usage). Not factored into validity.
         const corsValid = response.headers.get("access-control-allow-origin") === "*";
         return { response: response.ok ? response : null, corsValid };
     }
@@ -62,12 +64,14 @@ const detectKeyType = (keyData) => __awaiter(void 0, void 0, void 0, function* (
         const binaryKey = new Uint8Array(buffer);
         const header = "-----BEGIN PGP PUBLIC KEY BLOCK-----";
         const prefix = new TextDecoder().decode(binaryKey.slice(0, header.length));
+        // Spec Section 3.1: "The server SHOULD use "application/octet-stream" as the Content-Type for the data but clients SHOULD also accept any other Content-Type. The server SHOULD NOT return an ASCII armored version of the key."
         if (prefix === header) {
             const text = new TextDecoder().decode(binaryKey);
             const key = yield (0, openpgp_1.readKey)({ armoredKey: text });
             return { keyType: KeyType.ArmoredKey, key };
         }
         else {
+            // Spec Section 3.1: "The HTTP GET method MUST return the binary representation of the OpenPGP key for the given mail address."
             const key = yield (0, openpgp_1.readKey)({ binaryKey });
             return { keyType: KeyType.BinaryKey, key };
         }
@@ -85,15 +89,16 @@ const detectKeyType = (keyData) => __awaiter(void 0, void 0, void 0, function* (
  * @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;
+    var _a, _b;
     const [policyData, keyData] = yield Promise.all([
         fetchWithCorsCheck(policy, options),
         fetchWithCorsCheck(url, options)
     ]);
     const result = {
+        policy_location: ((_a = policyData.response) === null || _a === void 0 ? void 0 : _a.url) || policy,
         policyAvailable: !!policyData.response,
         policyCorsValid: policyData.corsValid,
-        key_location: ((_a = keyData.response) === null || _a === void 0 ? void 0 : _a.url) || url,
+        key_location: ((_b = keyData.response) === null || _b === void 0 ? void 0 : _b.url) || url,
         key_available: !!keyData.response,
         keyCorsValid: keyData.corsValid,
         keyType: KeyType.Invalid,
@@ -105,19 +110,36 @@ const checkKeyUrl = (url, policy, options, email) => __awaiter(void 0, void 0, v
     if (keyData.response) {
         const { keyType, key } = yield detectKeyType(keyData.response);
         result.keyType = keyType;
+        // The HTTP GET method MUST return the binary representation of the OpenPGP key for the given mail address.
         result.keyTypeValid = keyType === KeyType.BinaryKey;
         if (key) {
             const identities = yield key.getUserIDs();
-            result.emailInKey = identities.some(identity => identity.includes(email));
+            // Spec Section 5: "The mail provider MUST make sure to publish a key in a way that only the mail address belonging to the requested user is part of the User ID packets included in the returned key."
+            // "Other User ID packets and their associated binding signatures MUST be removed before publication."
+            if (identities.length === 1) {
+                const id = identities[0];
+                // robustly extract email from "Name <email>" format
+                const match = id.match(/<(.+)>/);
+                const emailInId = match ? match[1] : id;
+                result.emailInKey = emailInId.trim() === email;
+            }
+            else {
+                result.emailInKey = false;
+            }
             result.fingerprint = key.getFingerprint().toUpperCase();
         }
     }
-    result.valid = result.policyAvailable && result.policyCorsValid && result.key_available && result.keyCorsValid && result.keyTypeValid && result.emailInKey;
+    result.valid = result.policyAvailable &&
+        result.key_available &&
+        result.keyTypeValid &&
+        result.emailInKey;
     return result;
 });
 /**
  * Encode input using Z-Base32 encoding.
  *
+ * Spec Section 3.1: "The resulting 160 bit digest is encoded using the Z-Base-32 method as described in [RFC6189], section 5.1.6."
+ *
  * @param {Uint8Array} data - The binary data to encode
  * @returns {String} Binary data encoded using Z-Base32.
  */
@@ -152,21 +174,27 @@ function zbase32Encode(data) {
 }
 /**
  * Generates WKD URLs for a given email address.
+ * Spec Section 3.1: "Key Discovery"
  * @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.
+    // Spec Section 3.1: "all upper-case ASCII characters in a User ID are mapped to lowercase. Non-ASCII characters are not changed."
     const localPartHashInput = localPart.replace(/[A-Z]/g, c => c.toLowerCase());
     const domainLower = domain.toLowerCase();
+    // Spec Section 3.1: "The so mapped local-part is hashed using the SHA-1 algorithm."
     const hashBuffer = yield crypto.subtle.digest("SHA-1", new TextEncoder().encode(localPartHashInput));
+    // Spec Section 3.1: "The resulting 160 bit digest is encoded using the Z-Base-32 method as described in [RFC6189], section 5.1.6.  The resulting string has a fixed length of 32 octets."
     const hash = zbase32Encode(new Uint8Array(hashBuffer));
     const nameParam = encodeURIComponent(localPart);
     return {
+        // Spec Section 3.1: Advanced Method URI Construction
         advancedUrl: `https://openpgpkey.${domainLower}/.well-known/openpgpkey/${domainLower}/hu/${hash}?l=${nameParam}`,
+        // Spec Section 3.1: Direct Method URI Construction
         directUrl: `https://${domainLower}/.well-known/openpgpkey/hu/${hash}?l=${nameParam}`,
-        advancedPolicyUrl: `https://openpgpkey.${domainLower}/.well-known/openpgpkey/policy`,
+        // Spec Section 4.5: Policy Flags
+        advancedPolicyUrl: `https://openpgpkey.${domainLower}/.well-known/openpgpkey/${domainLower}/policy`,
         directPolicyUrl: `https://${domainLower}/.well-known/openpgpkey/policy`
     };
 });
@@ -180,11 +208,13 @@ const getKey = (email) => __awaiter(void 0, void 0, void 0, function* () {
         throw new WKDError('Invalid e-mail address.');
     }
     const { advancedUrl, directUrl } = yield generateWkdUrls(email);
+    // Spec Section 3.1: "Implementations MUST first try the advanced method. Only if an address for the required sub-domain does not exist, they SHOULD fall back to the direct method."
     const urls = [advancedUrl, directUrl];
     for (const url of urls) {
         try {
-            const response = yield fetch(url);
+            const response = yield fetch(url, { headers: { 'User-Agent': USER_AGENT } });
             if (response.ok) {
+                // Spec Section 3.1
                 return new Uint8Array(yield response.arrayBuffer());
             }
         }
@@ -203,7 +233,7 @@ exports.getKey = getKey;
 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/)" }
+        headers: { "User-Agent": USER_AGENT }
     };
     const [advancedResult, directResult] = yield Promise.all([
         checkKeyUrl(advancedUrl, advancedPolicyUrl, options, email),

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "wkd-checker",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Web Key Directory library for Node.js. Retreive OpenPGP keys from WKD servers and validate them.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/JonatanMGit/wkd-checker.git"
+    "url": "git+https://github.com/JonatanMGit/wkd-checker.git"
+  },
+  "keywords": [
+    "wkd",
+    "openpgp",
+    "pgp",
+    "gpg",
+    "keyserver"
+  ],
+  "homepage": "https://miarecki.eu/tools/wkd-checker/",
+  "bugs": {
+    "url": "https://github.com/JonatanMGit/wkd-checker/issues"
   },
   "bin": {
     "wkd-checker": "dist/cli.js"