@twin.org/web 0.0.1-next.9 → 0.0.2-next.3

package/dist/cjs/index.cjs

@@ -2,6 +2,7 @@
 
 var core = require('@twin.org/core');
 var crypto = require('@twin.org/crypto');
+var jose = require('jose');
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -345,23 +346,6 @@ const HttpStatusCode = {
     networkAuthenticationRequired: 511
 };
 
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * The cryptographic algorithms supported for JSON Web Tokens and JSON Web Keys.
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-const JwtAlgorithms = {
-    /**
-     * HMAC using SHA-256.
-     */
-    HS256: "HS256",
-    /**
-     * EdDSA using Ed25519.
-     */
-    EdDSA: "EdDSA"
-};
-
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -389,6 +373,10 @@ const MimeTypes = {
      * JSON-LD - application/ld+json
      */
     JsonLd: "application/ld+json",
+    /**
+     * JWT - application/jwt
+     */
+    Jwt: "application/jwt",
     /**
      * XML - application/xml
      */
@@ -401,6 +389,10 @@ const MimeTypes = {
      * Application GZIP - application/gzip
      */
     Gzip: "application/gzip",
+    /**
+     * Application deflate - application/zlib
+     */
+    Zlib: "application/zlib",
     /**
      * Application BZIP2 - application/x-bzip2
      */
@@ -555,7 +547,7 @@ class FetchHelper {
                 if (isErr && core.Is.stringValue(err.message) && err.message.includes("Failed to fetch")) {
                     lastError = new FetchError(source, `${FetchHelper._CLASS_NAME_CAMEL_CASE}.connectivity`, HttpStatusCode.serviceUnavailable, {
                         url
-                    });
+                    }, err);
                 }
                 else {
                     const isAbort = isErr && err.name === "AbortError";
@@ -570,7 +562,7 @@ class FetchHelper {
                     if (isErr && "statusText" in err) {
                         props.statusText = err.statusText;
                     }
-                    lastError = new FetchError(source, `${FetchHelper._CLASS_NAME_CAMEL_CASE}.${isAbort ? "timeout" : "general"}`, httpStatus, props);
+                    lastError = new FetchError(source, `${FetchHelper._CLASS_NAME_CAMEL_CASE}.${isAbort ? "timeout" : "general"}`, httpStatus, props, err);
                 }
             }
             finally {
@@ -627,12 +619,15 @@ class FetchHelper {
             }
         }
         const errorResponseData = await response.json();
+        const errorResponse = core.BaseError.fromError(errorResponseData);
+        const isErrorEmpty = core.BaseError.isEmpty(errorResponse);
         // False positive as FetchError is derived from Error
         // eslint-disable-next-line @typescript-eslint/only-throw-error
         throw new FetchError(source, `${FetchHelper._CLASS_NAME_CAMEL_CASE}.failureStatusText`, response.status, {
             statusText: response.statusText,
-            url
-        }, errorResponseData);
+            url,
+            data: isErrorEmpty ? errorResponseData : undefined
+        }, isErrorEmpty ? undefined : errorResponse);
     }
     /**
      * Perform a request for binary data.
@@ -677,12 +672,15 @@ class FetchHelper {
             }
         }
         const errorResponseData = await response.json();
+        const errorResponse = core.BaseError.fromError(errorResponseData);
+        const isErrorEmpty = core.BaseError.isEmpty(errorResponse);
         // False positive as FetchError is derived from Error
         // eslint-disable-next-line @typescript-eslint/only-throw-error
         throw new FetchError(source, `${FetchHelper._CLASS_NAME_CAMEL_CASE}.failureStatusText`, response.status, {
             statusText: response.statusText,
-            url
-        }, errorResponseData);
+            url,
+            data: isErrorEmpty ? errorResponseData : undefined
+        }, isErrorEmpty ? undefined : errorResponse);
     }
     /**
      * Clears the cache.
@@ -698,6 +696,15 @@ class FetchHelper {
     static async getCacheEntry(url) {
         return core.AsyncCache.get(`${FetchHelper._CACHE_PREFIX}${url}`);
     }
+    /**
+     * Set a cache entry.
+     * @param url The url for the request.
+     * @param value The value to cache.
+     * @returns The cache entry if it exists.
+     */
+    static async setCacheEntry(url, value) {
+        core.AsyncCache.set(`${FetchHelper._CACHE_PREFIX}${url}`, value);
+    }
     /**
      * Remove a cache entry.
      * @param url The url for the request.
@@ -710,7 +717,158 @@ class FetchHelper {
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
- * Class to encode and decode JSON Web Tokens.
+ * Class to handle JSON Web Keys.
+ */
+class Jwk {
+    /**
+     * Runtime name for the class.
+     * @internal
+     */
+    static _CLASS_NAME = "Jwk";
+    /**
+     * Convert the JWK to a crypto key.
+     * @param jwk The JWK to convert.
+     * @param alg The alg to be used, defaults to jwk.alg.
+     * @returns The crypto key.
+     */
+    static async toCryptoKey(jwk, alg) {
+        core.Guards.object(Jwk._CLASS_NAME, "jwk", jwk);
+        try {
+            return jose.importJWK(jwk, alg);
+        }
+        catch (err) {
+            throw new core.GeneralError(Jwk._CLASS_NAME, "jwkImportFailed", undefined, err);
+        }
+    }
+    /**
+     * Convert the Ed25519 private key to a crypto key.
+     * @param privateKey The private key to use.
+     * @returns The crypto key.
+     */
+    static async fromEd25519Private(privateKey) {
+        core.Guards.uint8Array(Jwk._CLASS_NAME, "privateKey", privateKey);
+        const publicKey = crypto.Ed25519.publicKeyFromPrivateKey(privateKey);
+        const jwk = {
+            kty: "OKP",
+            use: "enc",
+            alg: "EdDSA",
+            crv: "Ed25519",
+            x: core.Converter.bytesToBase64Url(publicKey),
+            d: core.Converter.bytesToBase64Url(privateKey)
+        };
+        return jwk;
+    }
+    /**
+     * Convert the Ed25519 public key to a crypto key.
+     * @param publicKey The private key to use.
+     * @returns The crypto key.
+     */
+    static async fromEd25519Public(publicKey) {
+        core.Guards.uint8Array(Jwk._CLASS_NAME, "publicKey", publicKey);
+        const jwk = {
+            kty: "OKP",
+            use: "sig",
+            alg: "EdDSA",
+            crv: "Ed25519",
+            x: core.Converter.bytesToBase64Url(publicKey)
+        };
+        return jwk;
+    }
+    /**
+     * Convert the JWK to raw keys.
+     * @param jwk The JWK to convert to raw.
+     * @returns The crypto key.
+     */
+    static async toRaw(jwk) {
+        core.Guards.object(Jwk._CLASS_NAME, "jwk", jwk);
+        let publicKey;
+        let privateKey;
+        if (core.Is.stringBase64Url(jwk.x)) {
+            publicKey = core.Converter.base64UrlToBytes(jwk.x);
+        }
+        if (core.Is.stringBase64Url(jwk.d)) {
+            privateKey = core.Converter.base64UrlToBytes(jwk.d);
+        }
+        return {
+            publicKey,
+            privateKey
+        };
+    }
+    /**
+     * Generate a KID for the JWK.
+     * @param jwk The JWK to generate a KID for.
+     * @returns The KID.
+     */
+    static async generateKid(jwk) {
+        core.Guards.object(Jwk._CLASS_NAME, "jwk", jwk);
+        const kidProps = core.ObjectHelper.pick(jwk, ["crv", "kty", "x"]);
+        const canonicalJson = core.JsonHelper.canonicalize(kidProps);
+        const hash = crypto.Sha256.sum256(core.Converter.utf8ToBytes(canonicalJson));
+        return core.Converter.bytesToBase64Url(hash);
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class to handle JSON Web Signatures.
+ */
+class Jws {
+    /**
+     * Runtime name for the class.
+     * @internal
+     */
+    static _CLASS_NAME = "Jws";
+    /**
+     * Create a signature.
+     * @param privateKey The private key to use.
+     * @param hash The hash to sign.
+     * @param algOverride An optional algorithm override.
+     * @returns The signature.
+     */
+    static async create(privateKey, hash, algOverride) {
+        core.Guards.defined(Jws._CLASS_NAME, "privateKey", privateKey);
+        core.Guards.uint8Array(Jws._CLASS_NAME, "hash", hash);
+        try {
+            const jws = await new jose.CompactSign(hash)
+                .setProtectedHeader({
+                alg: algOverride ?? (core.Is.uint8Array(privateKey) ? "EdDSA" : privateKey.algorithm.name),
+                b64: false,
+                crit: ["b64"]
+            })
+                .sign(privateKey);
+            return jws;
+        }
+        catch (err) {
+            throw new core.GeneralError(Jws._CLASS_NAME, "createFailed", undefined, err);
+        }
+    }
+    /**
+     * Verify a signature.
+     * @param jws The signature to verify.
+     * @param publicKey The public key to verify the signature with.
+     * @param hash The hash to verify.
+     * @returns True if the signature was verified.
+     */
+    static async verify(jws, publicKey, hash) {
+        core.Guards.stringValue(Jws._CLASS_NAME, "jws", jws);
+        core.Guards.defined(Jws._CLASS_NAME, "publicKey", publicKey);
+        core.Guards.uint8Array(Jws._CLASS_NAME, "hash", hash);
+        try {
+            const jwsParts = jws.split(".");
+            await jose.flattenedVerify({ protected: jwsParts[0], payload: hash, signature: jwsParts[2] }, publicKey);
+            return true;
+        }
+        catch (err) {
+            throw new core.GeneralError(Jws._CLASS_NAME, "verifyFailed", undefined, err);
+        }
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class to handle JSON Web Tokens.
  */
 class Jwt {
     /**
@@ -727,9 +885,8 @@ class Jwt {
      */
     static async encode(header, payload, key) {
         core.Guards.object(Jwt._CLASS_NAME, "header", header);
-        core.Guards.arrayOneOf(Jwt._CLASS_NAME, "header.alg", header.alg, Object.values(JwtAlgorithms));
         core.Guards.object(Jwt._CLASS_NAME, "payload", payload);
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "key", key);
+        core.Guards.defined(Jwt._CLASS_NAME, "key", key);
         return Jwt.internalEncode(header, payload, key);
     }
     /**
@@ -741,7 +898,7 @@ class Jwt {
      */
     static async encodeWithSigner(header, payload, signer) {
         core.Guards.object(Jwt._CLASS_NAME, "header", header);
-        core.Guards.arrayOneOf(Jwt._CLASS_NAME, "header.alg", header.alg, Object.values(JwtAlgorithms));
+        core.Guards.stringValue(Jwt._CLASS_NAME, "header.alg", header.alg);
         core.Guards.object(Jwt._CLASS_NAME, "payload", payload);
         core.Guards.function(Jwt._CLASS_NAME, "signer", signer);
         return Jwt.internalEncode(header, payload, undefined, signer);
@@ -788,13 +945,8 @@ class Jwt {
      */
     static async verify(token, key) {
         core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "key", key);
-        const decoded = await Jwt.decode(token);
-        const verified = await Jwt.verifySignature(decoded.header, decoded.payload, decoded.signature, key);
-        return {
-            verified,
-            ...decoded
-        };
+        core.Guards.defined(Jwt._CLASS_NAME, "key", key);
+        return Jwt.verifySignature(token, key);
     }
     /**
      * Verify a token.
@@ -805,79 +957,131 @@ class Jwt {
     static async verifyWithVerifier(token, verifier) {
         core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
         core.Guards.function(Jwt._CLASS_NAME, "verifier", verifier);
-        core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
-        const decoded = await Jwt.decode(token);
-        const verified = await Jwt.verifySignature(decoded.header, decoded.payload, decoded.signature, undefined, verifier);
-        return {
-            verified,
-            ...decoded
-        };
+        return Jwt.verifySignature(token, undefined, verifier);
     }
     /**
      * Verify a token by parts.
-     * @param header The header to verify.
-     * @param payload The payload to verify.
-     * @param signature The signature to verify.
+     * @param token The token to verify.
      * @param key The key for verifying the token, if not provided no verification occurs.
      * @param verifier Custom verification method.
      * @returns True if the parts are verified.
      */
-    static async verifySignature(header, payload, signature, key, verifier) {
+    static async verifySignature(token, key, verifier) {
+        core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
         const hasKey = core.Is.notEmpty(key);
         const hasVerifier = core.Is.notEmpty(verifier);
         if (!hasKey && !hasVerifier) {
             throw new core.GeneralError(Jwt._CLASS_NAME, "noKeyOrVerifier");
         }
-        let verified = false;
-        if (core.Is.object(header) &&
-            core.Is.object(payload) &&
-            core.Is.uint8Array(signature) &&
-            core.Is.arrayOneOf(header.alg, Object.values(JwtAlgorithms))) {
-            const segments = [];
-            const headerBytes = core.Converter.utf8ToBytes(JSON.stringify(header));
-            segments.push(core.Converter.bytesToBase64Url(headerBytes));
-            const payloadBytes = core.Converter.utf8ToBytes(JSON.stringify(payload));
-            segments.push(core.Converter.bytesToBase64Url(payloadBytes));
-            const jwtHeaderAndPayload = core.Converter.utf8ToBytes(segments.join("."));
-            verifier ??= async (alg, k, p, s) => Jwt.defaultVerifier(alg, k, p, s);
-            verified = await verifier(header.alg, key, jwtHeaderAndPayload, signature);
-        }
-        return verified;
+        verifier ??= async (t, k) => Jwt.defaultVerifier(t, k);
+        return verifier(token, key);
     }
     /**
      * The default signer for the JWT.
-     * @param alg The algorithm to use.
-     * @param key The key to sign with.
+     * @param header The header to sign.
      * @param payload The payload to sign.
+     * @param key The optional key to sign with.
      * @returns The signature.
      */
-    static async defaultSigner(alg, key, payload) {
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "key", key);
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "payload", payload);
-        if (alg === "HS256") {
-            const algo = new crypto.HmacSha256(key);
-            return algo.update(payload).digest();
+    static async defaultSigner(header, payload, key) {
+        core.Guards.object(Jwt._CLASS_NAME, "header", header);
+        core.Guards.object(Jwt._CLASS_NAME, "payload", payload);
+        core.Guards.defined(Jwt._CLASS_NAME, "key", key);
+        const signer = new jose.SignJWT(payload);
+        signer.setProtectedHeader(header);
+        let finalKey = key;
+        if (header.alg === "EdDSA" && core.Is.uint8Array(key)) {
+            // Jose does not support Ed25519 keys in raw format, so we need to convert it to PKCS8.
+            finalKey = await crypto.Ed25519.privateKeyToPkcs8(key);
         }
-        return crypto.Ed25519.sign(key, payload);
+        return signer.sign(finalKey);
     }
     /**
      * The default verifier for the JWT.
-     * @param alg The algorithm to use.
+     * @param token The token to verify.
      * @param key The key to verify with.
-     * @param payload The payload to verify.
-     * @param signature The signature to verify.
-     * @returns True if the signature was verified.
+     * @returns The header and payload if verification successful.
+     */
+    static async defaultVerifier(token, key) {
+        core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
+        core.Guards.defined(Jwt._CLASS_NAME, "key", key);
+        try {
+            const result = await jose.jwtVerify(token, key);
+            return {
+                header: result.protectedHeader,
+                payload: result.payload
+            };
+        }
+        catch (err) {
+            throw new core.GeneralError(Jwt._CLASS_NAME, "verifyFailed", undefined, err);
+        }
+    }
+    /**
+     * Create bytes for signing from header and payload.
+     * @param header The header.
+     * @param payload The payload.
+     * @returns The bytes to sign.
      */
-    static async defaultVerifier(alg, key, payload, signature) {
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "key", key);
-        core.Guards.uint8Array(Jwt._CLASS_NAME, "payload", payload);
+    static toSigningBytes(header, payload) {
+        core.Guards.object(Jwt._CLASS_NAME, "header", header);
+        core.Guards.object(Jwt._CLASS_NAME, "payload", payload);
+        const segments = [];
+        const headerBytes = core.Converter.utf8ToBytes(JSON.stringify(header));
+        segments.push(core.Converter.bytesToBase64Url(headerBytes));
+        const payloadBytes = core.Converter.utf8ToBytes(JSON.stringify(payload));
+        segments.push(core.Converter.bytesToBase64Url(payloadBytes));
+        return core.Converter.utf8ToBytes(segments.join("."));
+    }
+    /**
+     * Create header and payload from signing bytes.
+     * @param signingBytes The signing bytes from a token.
+     * @returns The header and payload.
+     * @throws If the signing bytes are invalid
+     */
+    static fromSigningBytes(signingBytes) {
+        core.Guards.uint8Array(Jwt._CLASS_NAME, "signingBytes", signingBytes);
+        const segments = core.Converter.bytesToUtf8(signingBytes).split(".");
+        if (segments.length !== 2) {
+            throw new core.GeneralError(Jwt._CLASS_NAME, "invalidSigningBytes");
+        }
+        const headerBytes = core.Converter.base64UrlToBytes(segments[0]);
+        const payloadBytes = core.Converter.base64UrlToBytes(segments[1]);
+        return {
+            header: core.ObjectHelper.fromBytes(headerBytes),
+            payload: core.ObjectHelper.fromBytes(payloadBytes)
+        };
+    }
+    /**
+     * Convert signed bytes and signature bytes to token.
+     * @param signingBytes The signed bytes.
+     * @param signature The signature.
+     * @returns The token.
+     */
+    static tokenFromBytes(signingBytes, signature) {
+        core.Guards.uint8Array(Jwt._CLASS_NAME, "signingBytes", signingBytes);
         core.Guards.uint8Array(Jwt._CLASS_NAME, "signature", signature);
-        if (alg === "HS256") {
-            const algo = new crypto.HmacSha256(key);
-            const sigBytes = algo.update(payload).digest();
-            return core.ArrayHelper.matches(sigBytes, signature);
+        const signedBytesUtf8 = core.Converter.bytesToUtf8(signingBytes);
+        const signatureBase64 = core.Converter.bytesToBase64Url(signature);
+        return `${signedBytesUtf8}.${signatureBase64}`;
+    }
+    /**
+     * Convert the token to signing bytes and signature bytes.
+     * @param token The token to convert to bytes.
+     * @returns The decoded bytes.
+     * @throws If the token is invalid.
+     */
+    static tokenToBytes(token) {
+        core.Guards.stringValue(Jwt._CLASS_NAME, "token", token);
+        const segments = token.split(".");
+        if (segments.length !== 3) {
+            throw new core.GeneralError(Jwt._CLASS_NAME, "invalidTokenParts");
         }
-        return crypto.Ed25519.verify(key, payload, signature);
+        const signingBytes = core.Converter.utf8ToBytes(`${segments[0]}.${segments[1]}`);
+        const signature = core.Converter.base64UrlToBytes(segments[2]);
+        return {
+            signingBytes,
+            signature
+        };
     }
     /**
      * Encode a token.
@@ -894,19 +1098,11 @@ class Jwt {
         if (!hasKey && !hasSigner) {
             throw new core.GeneralError(Jwt._CLASS_NAME, "noKeyOrSigner");
         }
-        signer ??= async (alg, k, p) => Jwt.defaultSigner(alg, k, p);
+        signer ??= async (h, p, k) => Jwt.defaultSigner(h, p, k);
         if (core.Is.undefined(header.typ)) {
             header.typ = "JWT";
         }
-        const segments = [];
-        const headerBytes = core.Converter.utf8ToBytes(JSON.stringify(header));
-        segments.push(core.Converter.bytesToBase64Url(headerBytes));
-        const payloadBytes = core.Converter.utf8ToBytes(JSON.stringify(payload));
-        segments.push(core.Converter.bytesToBase64Url(payloadBytes));
-        const jwtHeaderAndPayload = core.Converter.utf8ToBytes(segments.join("."));
-        const sigBytes = await signer(header.alg, key, jwtHeaderAndPayload);
-        segments.push(core.Converter.bytesToBase64Url(sigBytes));
-        return segments.join(".");
+        return signer(header, payload, key);
     }
 }
 
@@ -922,7 +1118,7 @@ class MimeTypeHelper {
      * @returns The mime type if detected.
      */
     static async detect(data) {
-        if (!core.Is.uint8Array(data)) {
+        if (!core.Is.uint8Array(data) || data.length === 0) {
             return undefined;
         }
         // Image
@@ -946,6 +1142,11 @@ class MimeTypeHelper {
         if (MimeTypeHelper.checkBytes(data, [0x1f, 0x8b, 0x8])) {
             return MimeTypes.Gzip;
         }
+        if (MimeTypeHelper.checkBytes(data, [0x78, 0x01]) ||
+            MimeTypeHelper.checkBytes(data, [0x78, 0x9c]) ||
+            MimeTypeHelper.checkBytes(data, [0x78, 0xda])) {
+            return MimeTypes.Zlib;
+        }
         if (MimeTypeHelper.checkBytes(data, [0x42, 0x5a, 0x68])) {
             return MimeTypes.Bzip2;
         }
@@ -994,12 +1195,14 @@ class MimeTypeHelper {
             [MimeTypes.Javascript]: "js",
             [MimeTypes.Json]: "json",
             [MimeTypes.JsonLd]: "jsonld",
+            [MimeTypes.Jwt]: "jwt",
             [MimeTypes.Xml]: "xml",
             [MimeTypes.OctetStream]: "bin",
             [MimeTypes.Gzip]: "gzip",
+            [MimeTypes.Zlib]: "zlib",
             [MimeTypes.Bzip2]: "bz2",
             [MimeTypes.Zip]: "zip",
-            [MimeTypes.Pdf]: "pfd",
+            [MimeTypes.Pdf]: "pdf",
             [MimeTypes.Gif]: "gif",
             [MimeTypes.Bmp]: "bmp",
             [MimeTypes.Jpeg]: "jpeg",
@@ -1050,7 +1253,8 @@ exports.FetchHelper = FetchHelper;
 exports.HeaderTypes = HeaderTypes;
 exports.HttpMethod = HttpMethod;
 exports.HttpStatusCode = HttpStatusCode;
+exports.Jwk = Jwk;
+exports.Jws = Jws;
 exports.Jwt = Jwt;
-exports.JwtAlgorithms = JwtAlgorithms;
 exports.MimeTypeHelper = MimeTypeHelper;
 exports.MimeTypes = MimeTypes;