feat(toolkit/crypto): provide digest function to compute the hash o…

…f data

README.md

@@ -23,6 +23,9 @@ This module is available as [@scion/toolkit][link-toolkit-download] in the NPM r
 - [**BeanManager**][link-tool-bean-manager]\
   Provides a registry for looking up singleton objects.
 
+- [**Crypto**][link-tool-crypto]\
+  Provides cryptographic functions.
+
 - [**Observable**][link-tool-observable]\
   Provides RxJS Observables for observing the size or DOM mutations of an HTML element.
 
@@ -81,6 +84,7 @@ This module is available as [@scion/components][link-components-download] in the
 [link-tool-uuid]: /docs/site/tools/uuid.md
 [link-tool-web-storage]: /docs/site/tools/web-storage.md
 [link-tool-bean-manager]: /docs/site/tools/bean-manager.md
+[link-tool-crypto]: /docs/site/tools/crypto.md
 [link-scion-microfrontend-platform]: https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform/blob/master/README.md
 [link-scion-workbench]: https://github.com/SchweizerischeBundesbahnen/scion-workbench/blob/master/README.md
 

docs/site/tools/crypto.md

@@ -0,0 +1,37 @@
+<a href="/README.md"><img src="/resources/branding/scion-toolkit-banner.svg" height="50" alt="SCION Toolkit"></a>
+
+| SCION Toolkit | [Projects Overview][menu-projects-overview] | [Changelog][menu-changelog] | [Contributing][menu-contributing] | [Sponsoring][menu-sponsoring] |  
+| --- | --- | --- | --- | --- |
+
+## [SCION Toolkit][menu-home] > Crypto
+
+The NPM sub-module `@scion/toolkit/crypto` provides cryptographic functions.
+
+To use the crypto module, install the NPM module `@scion/toolkit` as following:
+
+```
+npm install @scion/toolkit --save
+```
+
+<details>
+  <summary><strong>Crypto.digest</strong></summary>
+
+Generates a digest of the given data using the specified algorithm (or SHA-256 by default) and converts it to a hex string.
+
+```typescript
+import { Crypto } from '@scion/toolkit/crypto';
+
+const hash: string = await Crypto.digest('some-data');
+```
+</details>
+
+
+[menu-home]: /README.md
+
+[menu-projects-overview]: /docs/site/projects-overview.md
+
+[menu-changelog]: /docs/site/changelog.md
+
+[menu-contributing]: /CONTRIBUTING.md
+
+[menu-sponsoring]: /docs/site/sponsoring.md

projects/scion/toolkit/README.md

@@ -22,6 +22,9 @@ This library is written in plain TypeScript and has no dependency on any other l
 - [**BeanManager**][link-tool-bean-manager]\
   Provides a registry for looking up singleton objects.
 
+- [**Crypto**][link-tool-crypto]\
+  Provides cryptographic functions.
+
 - [**WebStorage**][link-tool-web-storage]\
   Allows observing items contained in local or session storage.
 
@@ -41,3 +44,4 @@ License: EPL-2.0
 [link-tool-uuid]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/uuid.md
 [link-tool-web-storage]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/web-storage.md
 [link-tool-bean-manager]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/bean-manager.md
+[link-tool-crypto]: https://github.com/SchweizerischeBundesbahnen/scion-toolkit/blob/master/docs/site/tools/crypto.md

projects/scion/toolkit/crypto/ng-package.json

@@ -0,0 +1 @@
+{}

projects/scion/toolkit/crypto/src/crypto.util.spec.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2018-2022 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ *  SPDX-License-Identifier: EPL-2.0
+ */
+
+import {Crypto} from './crypto.util';
+
+describe('Crypto', () => {
+
+  it('should hash data', async () => {
+    const hash = await Crypto.digest('A');
+    expect(hash).toEqual('559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd');
+  });
+});

projects/scion/toolkit/crypto/src/crypto.util.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2018-2022 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ *  SPDX-License-Identifier: EPL-2.0
+ */
+
+/**
+ * Provides cryptographic functions.
+ */
+export namespace Crypto {
+
+  /**
+   * Generates a digest of the given data using the specified algorithm (or SHA-256 by default) and converts it to a hex string.
+   *
+   * Can only be used in secure contexts (HTTPS) or on localhost. For more information, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts.
+   *
+   * Credits: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
+   */
+  export async function digest(data: string | BufferSource, options?: {algorithm?: 'SHA-256' | 'SHA-384' | 'SHA-512'}): Promise<string> {
+    if (!isSecureContext) {
+      throw Error('Function "digest" of @scion/toolkit/crypto is available only in secure contexts (HTTPS) or on localhost. For more information, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts.');
+    }
+    data = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    // Hash the data.
+    const hashBuffer = await crypto.subtle.digest(options?.algorithm ?? 'SHA-256', data);
+    // Convert buffer to byte array.
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    // Convert bytes to hex string.
+    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+}

projects/scion/toolkit/crypto/src/public_api.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2018-2022 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ *  SPDX-License-Identifier: EPL-2.0
+ */
+
+/*
+ * Secondary entrypoint: '@scion/toolkit/crypto'
+ * This module does not depend on Angular.
+ *
+ * @see https://github.com/ng-packagr/ng-packagr/blob/master/docs/secondary-entrypoints.md
+ */
+export {Crypto} from './crypto.util';

tsconfig.json

@@ -61,6 +61,9 @@
     //      "@scion/toolkit/bean-manager": [
     //        "projects/scion/toolkit/bean-manager/src/public_api"
     //      ],
+    //      "@scion/toolkit/crypto": [
+    //        "projects/scion/toolkit/crypto/src/public_api"
+    //      ],
     //      "@scion/toolkit/observable": [
     //        "projects/scion/toolkit/observable/src/public_api"
     //      ],