@twin.org/web 0.0.1-next.37 → 0.0.1-next.39

package/dist/cjs/index.cjs

@@ -2,6 +2,7 @@
 
 var core = require('@twin.org/core');
 var jose = require('jose');
+var crypto = require('@twin.org/crypto');
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -835,34 +836,23 @@ class Jwt {
     }
     /**
      * 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, header, payload) {
-        core.Guards.defined(Jwt._CLASS_NAME, "key", key);
+    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);
-        header.alg = alg;
         signer.setProtectedHeader(header);
-        if (alg === "EdDSA" && core.Is.uint8Array(key)) {
-            // crypto.subtle.importKey does not support Ed25519 keys in raw format.
-            // We need to convert the key to PKCS8 format before importing.
-            // The PKCS8 format is the raw key prefixed with the ASN.1 sequence for an Ed25519 private key.
-            // The ASN.1 sequence is 48 46 02 01 00 30 05 06 03 2b 65 70 04 20 04 20
-            const pkcs8Prefix = new Uint8Array([
-                48, 46, 2, 1, 0, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32
-            ]); // 0x302e020100300506032b657004220420
-            const pkcs8PrivateKey = core.Uint8ArrayHelper.concat([pkcs8Prefix, key]);
-            const imported = await crypto.subtle.importKey("pkcs8", pkcs8PrivateKey, "Ed25519", false, [
-                "sign"
-            ]);
-            return signer.sign(imported);
+        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 signer.sign(key);
+        return signer.sign(finalKey);
     }
     /**
      * The default verifier for the JWT.
@@ -884,6 +874,73 @@ class Jwt {
             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 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);
+        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");
+        }
+        const signingBytes = core.Converter.utf8ToBytes(`${segments[0]}.${segments[1]}`);
+        const signature = core.Converter.base64UrlToBytes(segments[2]);
+        return {
+            signingBytes,
+            signature
+        };
+    }
     /**
      * Encode a token.
      * @param header The header to encode.
@@ -899,11 +956,11 @@ class Jwt {
         if (!hasKey && !hasSigner) {
             throw new core.GeneralError(Jwt._CLASS_NAME, "noKeyOrSigner");
         }
-        signer ??= async (alg, k, h, p) => Jwt.defaultSigner(alg, k, h, p);
+        signer ??= async (h, p, k) => Jwt.defaultSigner(h, p, k);
         if (core.Is.undefined(header.typ)) {
             header.typ = "JWT";
         }
-        return signer(header.alg, key, header, payload);
+        return signer(header, payload, key);
     }
 }
 

package/dist/esm/index.mjs

@@ -1,5 +1,6 @@
-import { BaseError, StringHelper, Guards, Is, AsyncCache, ObjectHelper, GeneralError, Converter, Uint8ArrayHelper } from '@twin.org/core';
+import { BaseError, StringHelper, Guards, Is, AsyncCache, ObjectHelper, GeneralError, Converter } from '@twin.org/core';
 import { importJWK, SignJWT, jwtVerify } from 'jose';
+import { Ed25519 } from '@twin.org/crypto';
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -833,34 +834,23 @@ class Jwt {
     }
     /**
      * 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, header, payload) {
-        Guards.defined(Jwt._CLASS_NAME, "key", key);
+    static async defaultSigner(header, payload, key) {
         Guards.object(Jwt._CLASS_NAME, "header", header);
         Guards.object(Jwt._CLASS_NAME, "payload", payload);
+        Guards.defined(Jwt._CLASS_NAME, "key", key);
         const signer = new SignJWT(payload);
-        header.alg = alg;
         signer.setProtectedHeader(header);
-        if (alg === "EdDSA" && Is.uint8Array(key)) {
-            // crypto.subtle.importKey does not support Ed25519 keys in raw format.
-            // We need to convert the key to PKCS8 format before importing.
-            // The PKCS8 format is the raw key prefixed with the ASN.1 sequence for an Ed25519 private key.
-            // The ASN.1 sequence is 48 46 02 01 00 30 05 06 03 2b 65 70 04 20 04 20
-            const pkcs8Prefix = new Uint8Array([
-                48, 46, 2, 1, 0, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32
-            ]); // 0x302e020100300506032b657004220420
-            const pkcs8PrivateKey = Uint8ArrayHelper.concat([pkcs8Prefix, key]);
-            const imported = await crypto.subtle.importKey("pkcs8", pkcs8PrivateKey, "Ed25519", false, [
-                "sign"
-            ]);
-            return signer.sign(imported);
+        let finalKey = key;
+        if (header.alg === "EdDSA" && Is.uint8Array(key)) {
+            // Jose does not support Ed25519 keys in raw format, so we need to convert it to PKCS8.
+            finalKey = await Ed25519.privateKeyToPKCS8(key);
         }
-        return signer.sign(key);
+        return signer.sign(finalKey);
     }
     /**
      * The default verifier for the JWT.
@@ -882,6 +872,73 @@ class Jwt {
             throw new 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 toSigningBytes(header, payload) {
+        Guards.object(Jwt._CLASS_NAME, "header", header);
+        Guards.object(Jwt._CLASS_NAME, "payload", payload);
+        const segments = [];
+        const headerBytes = Converter.utf8ToBytes(JSON.stringify(header));
+        segments.push(Converter.bytesToBase64Url(headerBytes));
+        const payloadBytes = Converter.utf8ToBytes(JSON.stringify(payload));
+        segments.push(Converter.bytesToBase64Url(payloadBytes));
+        return 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) {
+        Guards.uint8Array(Jwt._CLASS_NAME, "signingBytes", signingBytes);
+        const segments = Converter.bytesToUtf8(signingBytes).split(".");
+        if (segments.length !== 2) {
+            throw new GeneralError(Jwt._CLASS_NAME, "invalidSigningBytes");
+        }
+        const headerBytes = Converter.base64UrlToBytes(segments[0]);
+        const payloadBytes = Converter.base64UrlToBytes(segments[1]);
+        return {
+            header: ObjectHelper.fromBytes(headerBytes),
+            payload: 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) {
+        Guards.uint8Array(Jwt._CLASS_NAME, "signingBytes", signingBytes);
+        Guards.uint8Array(Jwt._CLASS_NAME, "signature", signature);
+        const signedBytesUtf8 = Converter.bytesToUtf8(signingBytes);
+        const signatureBase64 = 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) {
+        Guards.stringValue(Jwt._CLASS_NAME, "token", token);
+        const segments = token.split(".");
+        if (segments.length !== 3) {
+            throw new GeneralError(Jwt._CLASS_NAME, "invalidTokenParts");
+        }
+        const signingBytes = Converter.utf8ToBytes(`${segments[0]}.${segments[1]}`);
+        const signature = Converter.base64UrlToBytes(segments[2]);
+        return {
+            signingBytes,
+            signature
+        };
+    }
     /**
      * Encode a token.
      * @param header The header to encode.
@@ -897,11 +954,11 @@ class Jwt {
         if (!hasKey && !hasSigner) {
             throw new GeneralError(Jwt._CLASS_NAME, "noKeyOrSigner");
         }
-        signer ??= async (alg, k, h, p) => Jwt.defaultSigner(alg, k, h, p);
+        signer ??= async (h, p, k) => Jwt.defaultSigner(h, p, k);
         if (Is.undefined(header.typ)) {
             header.typ = "JWT";
         }
-        return signer(header.alg, key, header, payload);
+        return signer(header, payload, key);
     }
 }
 

package/dist/types/utils/jwt.d.ts

@@ -12,7 +12,7 @@ export declare class Jwt {
      * @param key The key for signing the token, can be omitted if a signer is provided.
      * @returns The encoded token.
      */
-    static encode<U extends IJwtHeader, T extends IJwtPayload>(header: U, payload: T, key: JwkCryptoKey): Promise<string>;
+    static encode<T extends IJwtHeader, U extends IJwtPayload>(header: T, payload: U, key: JwkCryptoKey): Promise<string>;
     /**
      * Encode a token.
      * @param header The header to encode.
@@ -20,15 +20,15 @@ export declare class Jwt {
      * @param signer Custom signer method.
      * @returns The encoded token.
      */
-    static encodeWithSigner<U extends IJwtHeader, T extends IJwtPayload>(header: U, payload: T, signer: (alg: string, key: JwkCryptoKey | undefined, header: IJwtHeader, payload: IJwtPayload) => Promise<string>): Promise<string>;
+    static encodeWithSigner<T extends IJwtHeader, U extends IJwtPayload>(header: T, payload: U, signer: (header: IJwtHeader, payload: IJwtPayload, key: JwkCryptoKey | undefined) => Promise<string>): Promise<string>;
     /**
      * Decode a token.
      * @param token The token to decode.
      * @returns The decoded payload.
      */
-    static decode<U extends IJwtHeader, T extends IJwtPayload>(token: string): Promise<{
-        header?: U;
-        payload?: T;
+    static decode<T extends IJwtHeader, U extends IJwtPayload>(token: string): Promise<{
+        header?: T;
+        payload?: U;
         signature?: Uint8Array;
     }>;
     /**
@@ -70,13 +70,12 @@ export declare class Jwt {
     }>;
     /**
      * 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 defaultSigner(alg: string, key: JwkCryptoKey | undefined, header: IJwtHeader, payload: IJwtPayload): Promise<string>;
+    static defaultSigner(header: IJwtHeader, payload: IJwtPayload, key: JwkCryptoKey | undefined): Promise<string>;
     /**
      * The default verifier for the JWT.
      * @param token The token to verify.
@@ -87,4 +86,38 @@ export declare class Jwt {
         header: T;
         payload: U;
     }>;
+    /**
+     * Create bytes for signing from header and payload.
+     * @param header The header.
+     * @param payload The payload.
+     * @returns The bytes to sign.
+     */
+    static toSigningBytes<T extends IJwtHeader, U extends IJwtPayload>(header: T, payload: U): Uint8Array;
+    /**
+     * 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<T extends IJwtHeader, U extends IJwtPayload>(signingBytes: Uint8Array): {
+        header: T;
+        payload: U;
+    };
+    /**
+     * Convert signed bytes and signature bytes to token.
+     * @param signingBytes The signed bytes.
+     * @param signature The signature.
+     * @returns The token.
+     */
+    static tokenFromBytes(signingBytes: Uint8Array, signature: Uint8Array): string;
+    /**
+     * 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: string): {
+        signingBytes: Uint8Array;
+        signature: Uint8Array;
+    };
 }

package/docs/changelog.md

@@ -1,5 +1,5 @@
 # @twin.org/web - Changelog
 
-## 0.0.1-next.37
+## 0.0.1-next.39
 
 - Initial Release

package/docs/reference/classes/Jwt.md

@@ -16,27 +16,27 @@ Class to handle JSON Web Tokens.
 
 ### encode()
 
-> `static` **encode**\<`U`, `T`\>(`header`, `payload`, `key`): `Promise`\<`string`\>
+> `static` **encode**\<`T`, `U`\>(`header`, `payload`, `key`): `Promise`\<`string`\>
 
 Encode a token.
 
 #### Type Parameters
 
-• **U** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
+• **T** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
 
-• **T** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
+• **U** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
 
 #### Parameters
 
 ##### header
 
-`U`
+`T`
 
 The header to encode.
 
 ##### payload
 
-`T`
+`U`
 
 The payload to encode.
 
@@ -56,33 +56,33 @@ The encoded token.
 
 ### encodeWithSigner()
 
-> `static` **encodeWithSigner**\<`U`, `T`\>(`header`, `payload`, `signer`): `Promise`\<`string`\>
+> `static` **encodeWithSigner**\<`T`, `U`\>(`header`, `payload`, `signer`): `Promise`\<`string`\>
 
 Encode a token.
 
 #### Type Parameters
 
-• **U** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
+• **T** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
 
-• **T** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
+• **U** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
 
 #### Parameters
 
 ##### header
 
-`U`
+`T`
 
 The header to encode.
 
 ##### payload
 
-`T`
+`U`
 
 The payload to encode.
 
 ##### signer
 
-(`alg`, `key`, `header`, `payload`) => `Promise`\<`string`\>
+(`header`, `payload`, `key`) => `Promise`\<`string`\>
 
 Custom signer method.
 
@@ -96,15 +96,15 @@ The encoded token.
 
 ### decode()
 
-> `static` **decode**\<`U`, `T`\>(`token`): `Promise`\<\{ `header`: `U`; `payload`: `T`; `signature`: `Uint8Array`; \}\>
+> `static` **decode**\<`T`, `U`\>(`token`): `Promise`\<\{ `header`: `T`; `payload`: `U`; `signature`: `Uint8Array`; \}\>
 
 Decode a token.
 
 #### Type Parameters
 
-• **U** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
+• **T** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
 
-• **T** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
+• **U** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
 
 #### Parameters
 
@@ -116,7 +116,7 @@ The token to decode.
 
 #### Returns
 
-`Promise`\<\{ `header`: `U`; `payload`: `T`; `signature`: `Uint8Array`; \}\>
+`Promise`\<\{ `header`: `T`; `payload`: `U`; `signature`: `Uint8Array`; \}\>
 
 The decoded payload.
 
@@ -232,24 +232,12 @@ True if the parts are verified.
 
 ### defaultSigner()
 
-> `static` **defaultSigner**(`alg`, `key`, `header`, `payload`): `Promise`\<`string`\>
+> `static` **defaultSigner**(`header`, `payload`, `key`): `Promise`\<`string`\>
 
 The default signer for the JWT.
 
 #### Parameters
 
-##### alg
-
-`string`
-
-The algorithm to use.
-
-##### key
-
-The key to sign with.
-
-`undefined` | [`JwkCryptoKey`](../type-aliases/JwkCryptoKey.md)
-
 ##### header
 
 [`IJwtHeader`](../interfaces/IJwtHeader.md)
@@ -262,6 +250,12 @@ The header to sign.
 
 The payload to sign.
 
+##### key
+
+The optional key to sign with.
+
+`undefined` | [`JwkCryptoKey`](../type-aliases/JwkCryptoKey.md)
+
 #### Returns
 
 `Promise`\<`string`\>
@@ -301,3 +295,139 @@ The key to verify with.
 `Promise`\<\{ `header`: `T`; `payload`: `U`; \}\>
 
 True if the signature was verified.
+
+***
+
+### toSigningBytes()
+
+> `static` **toSigningBytes**\<`T`, `U`\>(`header`, `payload`): `Uint8Array`
+
+Create bytes for signing from header and payload.
+
+#### Type Parameters
+
+• **T** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
+
+• **U** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
+
+#### Parameters
+
+##### header
+
+`T`
+
+The header.
+
+##### payload
+
+`U`
+
+The payload.
+
+#### Returns
+
+`Uint8Array`
+
+The bytes to sign.
+
+***
+
+### fromSigningBytes()
+
+> `static` **fromSigningBytes**\<`T`, `U`\>(`signingBytes`): `object`
+
+Create header and payload from signing bytes.
+
+#### Type Parameters
+
+• **T** *extends* [`IJwtHeader`](../interfaces/IJwtHeader.md)
+
+• **U** *extends* [`IJwtPayload`](../interfaces/IJwtPayload.md)
+
+#### Parameters
+
+##### signingBytes
+
+`Uint8Array`
+
+The signing bytes from a token.
+
+#### Returns
+
+`object`
+
+The header and payload.
+
+##### header
+
+> **header**: `T`
+
+##### payload
+
+> **payload**: `U`
+
+#### Throws
+
+If the signing bytes are invalid
+
+***
+
+### tokenFromBytes()
+
+> `static` **tokenFromBytes**(`signingBytes`, `signature`): `string`
+
+Convert signed bytes and signature bytes to token.
+
+#### Parameters
+
+##### signingBytes
+
+`Uint8Array`
+
+The signed bytes.
+
+##### signature
+
+`Uint8Array`
+
+The signature.
+
+#### Returns
+
+`string`
+
+The token.
+
+***
+
+### tokenToBytes()
+
+> `static` **tokenToBytes**(`token`): `object`
+
+Convert the token to signing bytes and signature bytes.
+
+#### Parameters
+
+##### token
+
+`string`
+
+The token to convert to bytes.
+
+#### Returns
+
+`object`
+
+The decoded bytes.
+
+##### signingBytes
+
+> **signingBytes**: `Uint8Array`
+
+##### signature
+
+> **signature**: `Uint8Array`
+
+#### Throws
+
+If the token is invalid.

package/locales/en.json

@@ -10,7 +10,9 @@
 		"jwt": {
 			"noKeyOrSigner": "No key or signer was provided for JWT creation",
 			"noKeyOrVerifier": "No key or verifier was provided for JWT creation",
-			"verifyFailed": "Failed to verify JWT"
+			"verifyFailed": "Failed to verify JWT",
+			"invalidTokenParts": "The JSON Web Token could not be parsed, it should contain three parts separated by dots",
+			"invalidSigningBytes": "The signing bytes are invalid, it should contain two parts separated by a dot"
 		},
 		"jwk": {
 			"jwkImportFailed": "Failed to import JWK"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/web",
-	"version": "0.0.1-next.37",
+	"version": "0.0.1-next.39",
 	"description": "Contains classes for use with web operations",
 	"repository": {
 		"type": "git",
@@ -14,8 +14,8 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.1-next.37",
-		"@twin.org/crypto": "0.0.1-next.37",
+		"@twin.org/core": "0.0.1-next.39",
+		"@twin.org/crypto": "0.0.1-next.39",
 		"@twin.org/nameof": "next",
 		"jose": "6.0.8"
 	},