Website: Renew (#384)

* chore(website): add empty "docs" folder to prevent build crash

* chore(website): add option to hide code sources

* chore(website): add few source examples

* chore(website): add empty example sources

* ci: update deploy website flow

* lint: remove website folder

.eslintrc.json

@@ -16,7 +16,8 @@
   ],
   "ignorePatterns": [
     "build/**/*.ts",
-    "**/*.js"
+    "**/*.js",
+    "website"
   ],
   "rules": {
     "@typescript-eslint/ban-ts-ignore": 0,

.github/workflows/test.yml → .github/workflows/library.yml

@@ -1,4 +1,4 @@
-name: Node.js CI
+name: Build and test library
 
 on: [push, pull_request]
 

.github/workflows/website.yml

@@ -0,0 +1,35 @@
+name: Build and publish website
+
+on:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'yarn'
+
+      - name: Install library dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build library
+        run: yarn build
+
+      - name: Install website dependencies
+        run: yarn install --frozen-lockfile --cwd website
+
+      - name: Build website
+        run: yarn build --cwd website
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: website/build

.gitignore

@@ -5,7 +5,6 @@ build
 coverage
 .vs
 .vscode
-docs
 
 bundle.js
 test/browser/*.js

README.md

@@ -37,31 +37,31 @@ This assumes you are using [npm](https://www.npmjs.com/) as your package manager
 
 ### Certificates and Revocation
 
-- [Create and validate an X.509 certificate](https://pkijs.org/examples/CertificateComplexExample/X509_cert_complex_example.html)
-- [Working with certificate requests](https://pkijs.org/examples/PKCS10ComplexExample/PKCS10_complex_example.html)
-- [Creating and parsing CRLs](https://pkijs.org/examples/CRLComplexExample/CRL_complex_example.html)
-- [Working with OCSP requests](https://pkijs.org/examples/OCSPRequestComplexExample/OCSP_req_complex_example.html)
-- [Working with OCSP responses](https://pkijs.org/examples/OCSPResponseComplexExample/OCSP_resp_complex_example.html)
+- [Create and validate an X.509 certificate](https://pkijs.org/docs/examples/certificates-and-revocation/create-and-validate-certificate)
+- [Working with certificate requests](https://pkijs.org/docs/examples/certificates-and-revocation/working-with-certificate-requests)
+- [Creating and parsing CRLs](https://pkijs.org/docs/examples/certificates-and-revocation/creating-and-parsing-CRLs)
+- [Working with OCSP requests](https://pkijs.org/docs/examples/certificates-and-revocation/working-with-OCSP-requests)
+- [Working with OCSP responses](https://pkijs.org/docs/examples/certificates-and-revocation/working-with-OCSP-responses)
 
 ### Signing and Encryption with CMS
 
-- [Working with CMS Signing](https://pkijs.org/examples/CMSSignedComplexExample/CMSSigned_complex_example.html)
-- [Working with CMS Certificate-based Encryption](https://pkijs.org/examples/HowToEncryptCMSviaCertificate/CMSEnvelopedExample.html)
-- [Working with CMS password-based Encryption](https://pkijs.org/examples/HowToEncryptCMSviaPassword/CMSEnvelopedPreDefineDataExample.html)
-- [Working with PKCS#7 Certificate bags (P7B)](https://pkijs.org/examples/P7BSimpleExample/P7BSimpleExample.html)
+- [Working with CMS Signing](https://pkijs.org/docs/examples/signing-and-encryption-with-CMS/working-with-CMS-signing)
+- [Working with CMS Certificate-based Encryption](https://pkijs.org/docs/examples/signing-and-encryption-with-CMS/working-with-CMS-certificate-based-encryption)
+- [Working with CMS password-based Encryption](https://pkijs.org/docs/examples/signing-and-encryption-with-CMS/working-with-CMS-password-based-encryption)
+- [Working with PKCS#7 Certificate bags (P7B)](https://pkijs.org/docs/examples/signing-and-encryption-with-CMS/working-with-PKCS-7-certificate-bags-P7B)
 
 ### Timestamping
-- [Creating a Timestamp request](https://pkijs.org/examples/TSPRequestComplexExample/TSP_req_complex_example.html)
-- [Creating a Timestamp response](https://pkijs.org/examples/TSPResponseComplexExample/TSP_resp_complex_example.html)
+- [Creating a Timestamp request](https://pkijs.org/docs/examples/timestamping/creating-a-timestamp-request)
+- [Creating a Timestamp response](https://pkijs.org/docs/examples/timestamping/creating-a-timestamp-response)
 
 ### Other
-- [How to verify a signature in a PDF file](https://pkijs.org/examples/PDFExample/PDFexample.html)
-- [S/MIME signature verification](https://pkijs.org/examples/SMIMEVerificationExample/SMIMEexample.html)
-- [S/MIME signature encryption](https://pkijs.org/examples/SMIMEEncryptionExample/SMIMEEncryptionExample.html)
-- [Working with PKCS#12 files](https://pkijs.org/examples/PKCS12SimpleExample/PKCS12SimpleExample.html)
+- [How to verify a signature in a PDF file](https://pkijs.org/docs/examples/other/how-to-verify-a-signature-in-a-PDF-file)
+- [S/MIME signature verification](https://pkijs.org/docs/examples/other/S-MIME-signature-verification)
+- [S/MIME signature encryption](https://pkijs.org/docs/examples/other/S-MIME-signature-encryption)
+- [Working with PKCS#12 files](https://pkijs.org/docs/examples/other/working-with-PKCS-12-files)
 
 ## Documentation
-You can find the PKI.js documentation [on the website](https://pkijs.org/docs).
+You can find the PKI.js documentation [on the website](https://pkijs.org/docs/installation).
 
 ## Want to help?
 Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our guidelines for [contribution](https://github.com/PeculiarVentures/PKI.js/blob/master/CONTRIBUTING.md).

package.json

@@ -15,12 +15,12 @@
     "url": "git://github.com/PeculiarVentures/PKI.js.git"
   },
   "devDependencies": {
-    "@peculiar/webcrypto": "^1.4.0",
+    "@peculiar/webcrypto": "^1.4.3",
     "@rollup/plugin-alias": "^3.1.9",
     "@rollup/plugin-commonjs": "^22.0.1",
     "@rollup/plugin-node-resolve": "^13.3.0",
     "@types/mocha": "^9.1.1",
-    "@types/node": "^18.6.3",
+    "@types/node": "^18.18.9",
     "@typescript-eslint/eslint-plugin": "^5.32.0",
     "@typescript-eslint/parser": "^5.32.0",
     "assert": "^2.0.0",
@@ -34,7 +34,6 @@
     "rollup-plugin-dts": "^4.2.2",
     "rollup-plugin-typescript2": "^0.32.1",
     "ts-node": "^10.9.1",
-    "typedoc": "^0.23.10",
     "typescript": "^4.7.4"
   },
   "dependencies": {
@@ -50,7 +49,6 @@
   "scripts": {
     "build": "rollup -c",
     "build:examples": "rollup -c examples/rollup.config.js",
-    "build:docs": "typedoc",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint --fix . --ext .ts",
     "coverage": "nyc npm test",

src/OtherKeyAttribute.ts

@@ -76,7 +76,7 @@ export class OtherKeyAttribute extends PkiObject implements IOtherKeyAttribute {
    * @param memberName String name for a class member
    * @param memberValue Value to compare with default value
    */
-  public static compareWithDefault<T>(memberName: string, memberValue: T): memberValue is T {
+  public static compareWithDefault<T extends object>(memberName: string, memberValue: T): memberValue is T {
     switch (memberName) {
       case KEY_ATTR_ID:
         return (typeof memberValue === "string" && memberValue === EMPTY_STRING);

src/TimeStampReq.ts

@@ -95,6 +95,7 @@ export type TimeStampReqParameters = PkiObjectParameters & Partial<ITimeStampReq
  * });
  *
  * const tspReqRaw = tspReq.toSchema().toBER();
+ * ```
  */
 export class TimeStampReq extends PkiObject implements ITimeStampReq {
 

tsconfig.json

@@ -9,6 +9,7 @@
     "experimentalDecorators": true
   },
   "exclude": [
+    "website",
     "build/*.ts"
   ]
 }

website/.gitignore

@@ -0,0 +1,23 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+
+/docs/api/

website/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docs/examples/certificates-and-revocation/create-and-validate-certificate.example.ts

@@ -0,0 +1,64 @@
+import * as pkijs from 'pkijs';
+import * as asn1js from 'asn1js';
+
+const crypto = pkijs.getCrypto(true);
+
+// Create certificate
+const certificate = new pkijs.Certificate();
+certificate.version = 2;
+certificate.serialNumber = new asn1js.Integer({ value: 1 });
+certificate.issuer.typesAndValues.push(new pkijs.AttributeTypeAndValue({
+  type: "2.5.4.3", // Common name
+  value: new asn1js.BmpString({ value: "Test" })
+}));
+certificate.subject.typesAndValues.push(new pkijs.AttributeTypeAndValue({
+  type: "2.5.4.3", // Common name
+  value: new asn1js.BmpString({ value: "Test" })
+}));
+
+certificate.notBefore.value = new Date();
+const notAfter = new Date();
+notAfter.setUTCFullYear(notAfter.getUTCFullYear() + 1);
+certificate.notAfter.value = notAfter;
+
+certificate.extensions = []; // Extensions are not a part of certificate by default, it's an optional array
+
+// "BasicConstraints" extension
+const basicConstr = new pkijs.BasicConstraints({
+  cA: true,
+  pathLenConstraint: 3
+});
+certificate.extensions.push(new pkijs.Extension({
+  extnID: "2.5.29.19",
+  critical: false,
+  extnValue: basicConstr.toSchema().toBER(false),
+  parsedValue: basicConstr // Parsed value for well-known extensions
+}));
+
+// "KeyUsage" extension
+const bitArray = new ArrayBuffer(1);
+const bitView = new Uint8Array(bitArray);
+bitView[0] |= 0x02; // Key usage "cRLSign" flag
+bitView[0] |= 0x04; // Key usage "keyCertSign" flag
+const keyUsage = new asn1js.BitString({ valueHex: bitArray });
+certificate.extensions.push(new pkijs.Extension({
+  extnID: "2.5.29.15",
+  critical: false,
+  extnValue: keyUsage.toBER(false),
+  parsedValue: keyUsage // Parsed value for well-known extensions
+}));
+
+const algorithm = pkijs.getAlgorithmParameters("RSASSA-PKCS1-v1_5", "generateKey");
+if ("hash" in algorithm.algorithm) {
+  algorithm.algorithm.hash.name = "SHA-256";
+}
+
+const keys = await crypto.generateKey(algorithm.algorithm, true, algorithm.usages);
+
+// Exporting public key into "subjectPublicKeyInfo" value of certificate
+await certificate.subjectPublicKeyInfo.importKey(keys.publicKey);
+
+// Signing final certificate
+await certificate.sign(keys.privateKey, "SHA-256");
+
+const raw = certificate.toSchema().toBER();

website/docs/examples/certificates-and-revocation/create-and-validate-certificate.mdx

@@ -0,0 +1,10 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./create-and-validate-certificate.example';
+
+# Create and validate certificate
+
+In this example, you will see how to create a self-signed X.509 certificate, parse an X.509 certificate, and show how to do certificate chain validation engine.
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/examples/certificates-and-revocation/creating-and-parsing-CRLs.example.ts

@@ -0,0 +1 @@
+// Coming soon

website/docs/examples/certificates-and-revocation/creating-and-parsing-CRLs.mdx

@@ -0,0 +1,10 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./creating-and-parsing-CRLs.example';
+
+# Creating and parsing CRLs
+
+In this example, you will see how to create a CRL, parse, and validate it.
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/examples/certificates-and-revocation/index.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Certificates and Revocation
+
+<DocCardList />