Linter: enforce JSDoc @access directive

To make sure only user-facing entities are included in the docs,
since access is public by default.

NB: the top-level access directive seems to work to hide index entrypoint files,
but in other cases (e.g. s2k submodules), exported functions may need to
manually be marked as private.

Also, the 'initialCommentsOnly' rule sometimes reports false positives
in case of multiple comment blocks separated by new lines. The solution
is to remove the new lines.

.jsdocrc.cjs

@@ -20,5 +20,9 @@ module.exports = {
     },
     source: {
         includePattern: "\\.(js|ts)$",
+        include: ['src/', 'README.md']
+    },
+    opts: {
+        recurse: true,
     },
 };

eslint.config.js

@@ -9,11 +9,23 @@ import pluginImport from 'eslint-plugin-import';
 import pluginStylistic from '@stylistic/eslint-plugin';
 // @ts-expect-error missing types
 import pluginUnicorn from 'eslint-plugin-unicorn';
+import pluginJSDoc from 'eslint-plugin-jsdoc';
 
 export default defineConfig(
   eslint.configs.recommended,
   tseslint.configs.recommendedTypeChecked,
   globalIgnores(['dist/', 'test/lib/', 'docs/', '.jsdocrc.cjs']),
+  { // JSDoc-specific linting rules
+    files: ['src/**/!(*.d).{js,ts}'], // exclude .d.ts files
+    plugins: { 'jsdoc': pluginJSDoc },
+    rules: {
+      'jsdoc/require-file-overview': ['error', {
+        'tags': {
+          'access': { 'initialCommentsOnly': true, 'mustExist': true }
+        }
+      }]
+    }
+  },
   {
     languageOptions: {
       ecmaVersion: 2022,

package-lock.json

@@ -44,6 +44,7 @@
         "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-chai-friendly": "^1.1.0",
         "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-jsdoc": "^60.7.0",
         "eslint-plugin-unicorn": "^48.0.1",
         "fflate": "^0.8.2",
         "globals": "^16.4.0",
@@ -397,6 +398,23 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@es-joy/jsdoccomment": {
+      "version": "0.71.0",
+      "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.71.0.tgz",
+      "integrity": "sha512-2p9+dXWNQnp5Kq/V0XVWZiVAabzlX6rUW8vXXvtX8Yc1CkKgD93IPDEnv1sYZFkkS6HMvg6H0RMZfob/Co0YXA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.8",
+        "@typescript-eslint/types": "^8.46.0",
+        "comment-parser": "1.4.1",
+        "esquery": "^1.6.0",
+        "jsdoc-type-pratt-parser": "~6.6.0"
+      },
+      "engines": {
+        "node": ">=20.11.0"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.25.4",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.4.tgz",
@@ -3702,6 +3720,16 @@
         "node": ">= 14"
       }
     },
+    "node_modules/are-docs-informative": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz",
+      "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/argon2id": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/argon2id/-/argon2id-1.0.1.tgz",
@@ -4932,6 +4960,16 @@
         "node": ">= 0.6.x"
       }
     },
+    "node_modules/comment-parser": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz",
+      "integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12.0.0"
+      }
+    },
     "node_modules/commondir": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz",
@@ -6273,6 +6311,57 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/eslint-plugin-jsdoc": {
+      "version": "60.8.3",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-60.8.3.tgz",
+      "integrity": "sha512-4191bTMvnd5WUtopCdzNhQchvv/MxtPD86ZGl3vem8Ibm22xJhKuIyClmgSxw+YERtorVc/NhG+bGjfFVa6+VQ==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@es-joy/jsdoccomment": "~0.71.0",
+        "are-docs-informative": "^0.0.2",
+        "comment-parser": "1.4.1",
+        "debug": "^4.4.3",
+        "escape-string-regexp": "^4.0.0",
+        "espree": "^10.4.0",
+        "esquery": "^1.6.0",
+        "html-entities": "^2.6.0",
+        "object-deep-merge": "^1.0.5",
+        "parse-imports-exports": "^0.2.4",
+        "semver": "^7.7.2",
+        "spdx-expression-parse": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.11.0"
+      },
+      "peerDependencies": {
+        "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
+      }
+    },
+    "node_modules/eslint-plugin-jsdoc/node_modules/escape-string-regexp": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
+      "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/eslint-plugin-jsdoc/node_modules/spdx-expression-parse": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz",
+      "integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "spdx-exceptions": "^2.1.0",
+        "spdx-license-ids": "^3.0.0"
+      }
+    },
     "node_modules/eslint-plugin-unicorn": {
       "version": "48.0.1",
       "resolved": "https://registry.npmjs.org/eslint-plugin-unicorn/-/eslint-plugin-unicorn-48.0.1.tgz",
@@ -7615,6 +7704,23 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/html-entities": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.6.0.tgz",
+      "integrity": "sha512-kig+rMn/QOVRvr7c86gQ8lWXq+Hkv6CbAH1hLu+RG338StTpE8Z0b44SDVaqVu7HGKf27frdmUYEs9hTUX/cLQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/mdevils"
+        },
+        {
+          "type": "patreon",
+          "url": "https://patreon.com/mdevils"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/html-escaper": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@@ -8660,6 +8766,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/jsdoc-type-pratt-parser": {
+      "version": "6.6.0",
+      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-6.6.0.tgz",
+      "integrity": "sha512-3hSD14nXx66Rspx1RMnz1Pj4JacrMBAsC0CrF9lZYO/Qsp5/oIr6KqujVUNhQu94B6mMip2ukki8MpEWZwyhKA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -9835,6 +9951,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/object-deep-merge": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/object-deep-merge/-/object-deep-merge-1.0.5.tgz",
+      "integrity": "sha512-3DioFgOzetbxbeUq8pB2NunXo8V0n4EvqsWM/cJoI6IA9zghd7cl/2pBOuWRf4dlvA+fcg5ugFMZaN2/RuoaGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "type-fest": "4.2.0"
+      }
+    },
     "node_modules/object-inspect": {
       "version": "1.13.4",
       "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
@@ -10197,6 +10323,16 @@
         "node": ">=6"
       }
     },
+    "node_modules/parse-imports-exports": {
+      "version": "0.2.4",
+      "resolved": "https://registry.npmjs.org/parse-imports-exports/-/parse-imports-exports-0.2.4.tgz",
+      "integrity": "sha512-4s6vd6dx1AotCx/RCI2m7t7GCh5bDRUtGNvRfHSP2wbBQdMi67pPe7mtzmgwcaQ8VKK/6IB7Glfyu3qdZJPybQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "parse-statements": "1.0.11"
+      }
+    },
     "node_modules/parse-json": {
       "version": "5.2.0",
       "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz",
@@ -10216,6 +10352,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/parse-statements": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/parse-statements/-/parse-statements-1.0.11.tgz",
+      "integrity": "sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/parse5": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/parse5/-/parse5-6.0.1.tgz",
@@ -12897,6 +13040,19 @@
         "node": ">=4"
       }
     },
+    "node_modules/type-fest": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.2.0.tgz",
+      "integrity": "sha512-5zknd7Dss75pMSED270A1RQS3KloqRJA9XbXLe0eCxyw7xXFb3rd+9B0UQ/0E+LQT6lnrLviEolYORlRWamn4w==",
+      "dev": true,
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/type-is": {
       "version": "1.6.18",
       "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz",

package.json

@@ -57,7 +57,7 @@
     "test-browserstack": "web-test-runner --config test/web-test-runner.browserstack.config.js",
     "coverage": "c8 npm test",
     "lint": "eslint .",
-    "docs": "jsdoc --configure .jsdocrc.cjs --destination docs --recurse README.md src && printf '%s' 'docs.openpgpjs.org' > docs/CNAME",
+    "docs": "jsdoc --configure .jsdocrc.cjs --destination docs && printf '%s' 'docs.openpgpjs.org' > docs/CNAME",
     "preversion": "rm -rf dist docs node_modules && npm ci && npm test",
     "version": "npm run docs && git add -A docs",
     "postversion": "git push --follow-tags && npm publish"
@@ -98,6 +98,7 @@
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-chai-friendly": "^1.1.0",
     "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsdoc": "^60.7.0",
     "eslint-plugin-unicorn": "^48.0.1",
     "fflate": "^0.8.2",
     "globals": "^16.4.0",

src/cleartext.js

@@ -1,3 +1,4 @@
+/** @access public */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/config/config.js

@@ -16,7 +16,8 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
- * Global configuration values.
+ * Global configuration values
+ * @access public
  */
 
 import enums from '../enums';

src/config/index.js

@@ -2,6 +2,7 @@
  * @fileoverview This object contains global configuration values.
  * @see module:config/config
  * @module config
+ * @access public
  */
 
 import config from './config';

src/crypto/aes_kw.js

@@ -19,6 +19,7 @@
  * @fileoverview Implementation of RFC 3394 AES Key Wrap & Key Unwrap funcions
  * @see module:crypto/public_key/elliptic/ecdh
  * @module crypto/aes_kw
+ * @access private
  */
 
 import { aeskw as nobleAesKW } from '@noble/ciphers/aes';

src/crypto/biginteger.ts

@@ -1,3 +1,8 @@
+/**
+ * @module biginteger
+ * @access private
+ */
+
 // Operations are not constant time, but we try and limit timing leakage where we can
 
 const _0n = BigInt(0);

src/crypto/cipher/blowfish.js

@@ -1,4 +1,6 @@
-/* Modified by Recurity Labs GmbH
+/**
+ * @access private
+ * Modified by Recurity Labs GmbH
  *
  * Originally written by nklein software (nklein.com)
  */

src/crypto/cipher/cast5.js

@@ -1,3 +1,4 @@
+/** @access private */
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 

src/crypto/cipher/des.js

@@ -1,3 +1,4 @@
+/** @access private */
 //Paul Tero, July 2001
 //http://www.tero.co.uk/des/
 //

src/crypto/cipher/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module crypto/cipher
+ * @access private
+ */
 import enums from '../../enums';
 
 export async function getLegacyCipher(algo) {

src/crypto/cipher/legacy_ciphers.js

@@ -1,4 +1,5 @@
 /**
+ * @access private
  * This file is needed to dynamic import the legacy ciphers.
  * Separate dynamic imports are not convenient as they result in multiple chunks.
  */

src/crypto/cipher/twofish.js

@@ -1,4 +1,6 @@
-/* Modified by Recurity Labs GmbH
+/**
+ * @access private
+ * Modified by Recurity Labs GmbH
  *
  * Cipher.js
  * A block-cipher algorithm implementation on JavaScript

src/crypto/cipherMode/cfb.js

@@ -19,6 +19,7 @@
 
 /**
  * @module crypto/mode/cfb
+ * @access private
  */
 
 import { cfb as nobleAesCfb, unsafe as nobleAesHelpers } from '@noble/ciphers/aes';

src/crypto/cipherMode/eax.js

@@ -19,6 +19,7 @@
  * @fileoverview This module implements AES-EAX en/decryption on top of
  * native AES-CTR using either the WebCrypto API or Node.js' crypto API.
  * @module crypto/mode/eax
+ * @access private
  */
 
 import { ctr as nobleAesCtr } from '@noble/ciphers/aes';

src/crypto/cipherMode/gcm.js

@@ -19,6 +19,7 @@
  * @fileoverview This module wraps native AES-GCM en/decryption for both
  * the WebCrypto api as well as node.js' crypto api.
  * @module crypto/mode/gcm
+ * @access private
  */
 
 import { gcm as nobleAesGcm } from '@noble/ciphers/aes';

src/crypto/cipherMode/index.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Cipher modes
  * @module crypto/cipherMode
+ * @access private
  */
 
 export * as cfb from './cfb';

src/crypto/cipherMode/ocb.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview This module implements AES-OCB en/decryption.
  * @module crypto/mode/ocb
+ * @access private
  */
 
 import { cbc as nobleAesCbc } from '@noble/ciphers/aes';

src/crypto/cmac.js

@@ -2,6 +2,7 @@
  * @fileoverview This module implements AES-CMAC on top of
  * native AES-CBC using either the WebCrypto API or Node.js' crypto API.
  * @module crypto/cmac
+ * @access private
  */
 
 import { cbc as nobleAesCbc } from '@noble/ciphers/aes';

src/crypto/crypto.js

@@ -21,6 +21,7 @@
  * @fileoverview Provides functions for asymmetric encryption and decryption as
  * well as key generation and parameter handling for all public-key cryptosystems.
  * @module crypto/crypto
+ * @access private
  */
 
 import { rsa, elliptic, elgamal, dsa } from './public_key';

src/crypto/hash/index.js

@@ -3,6 +3,7 @@
  * @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto}
  * @see {@link https://github.com/indutny/hash.js|hash.js}
  * @module crypto/hash
+ * @access private
  */
 
 import { transform as streamTransform, isArrayStream, readToEnd as streamReadToEnd } from '@openpgp/web-stream-tools';

src/crypto/hash/md5.ts

@@ -1,3 +1,4 @@
+/** @access private */
 // Copied from https://github.com/paulmillr/noble-hashes/blob/main/test/misc/md5.ts
 
 import { HashMD } from '@noble/hashes/_md';

src/crypto/hash/noble_hashes.js

@@ -1,4 +1,5 @@
 /**
+ * @access private
  * This file is needed to dynamic import the noble-hashes.
  * Separate dynamic imports are not convenient as they result in too many chunks,
  * which share a lot of code anyway.

src/crypto/hkdf.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview This module implements HKDF using either the WebCrypto API or Node.js' crypto API.
  * @module crypto/hkdf
+ * @access private
  */
 
 import enums from '../enums';

src/crypto/index.js

@@ -7,6 +7,7 @@
  * @see module:crypto/random
  * @see module:crypto/hash
  * @module crypto
+ * @access private
  */
 
 export * from './crypto';

src/crypto/pkcs1.js

@@ -21,6 +21,7 @@
  * @see module:crypto/public_key/elliptic/ecdh
  * @see PublicKeyEncryptedSessionKeyPacket
  * @module crypto/pkcs1
+ * @access private
  */
 
 import { getRandomBytes } from './random';

src/crypto/pkcs5.js

@@ -14,16 +14,15 @@
 // You should have received a copy of the GNU Lesser General Public
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
-
-import util from '../util';
-
 /**
  * @fileoverview Functions to add and remove PKCS5 padding
  * @see PublicKeyEncryptedSessionKeyPacket
  * @module crypto/pkcs5
- * @private
+ * @access private
  */
 
+import util from '../util';
+
 /**
  * Add pkcs5 padding to a message
  * @param {Uint8Array} message - message to pad

src/crypto/public_key/dsa.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview A Digital signature algorithm implementation
  * @module crypto/public_key/dsa
+ * @access private
  */
 import { getRandomBigInteger } from '../random';
 import util from '../../util';

src/crypto/public_key/elgamal.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview ElGamal implementation
  * @module crypto/public_key/elgamal
+ * @access private
  */
 import { getRandomBigInteger } from '../random';
 import { emeEncode, emeDecode } from '../pkcs1';

src/crypto/public_key/elliptic/brainpool/brainpoolP256r1.ts

@@ -1,3 +1,4 @@
+/** @access private */
 import { createCurve } from '@noble/curves/_shortw_utils';
 import { sha256 } from '@noble/hashes/sha256';
 import { Field } from '@noble/curves/abstract/modular';

src/crypto/public_key/elliptic/brainpool/brainpoolP384r1.ts

@@ -1,3 +1,4 @@
+/** @access private */
 import { createCurve } from '@noble/curves/_shortw_utils';
 import { sha384 } from '@noble/hashes/sha512';
 import { Field } from '@noble/curves/abstract/modular';

src/crypto/public_key/elliptic/brainpool/brainpoolP512r1.ts

@@ -1,3 +1,4 @@
+/** @access private */
 import { createCurve } from '@noble/curves/_shortw_utils';
 import { sha512 } from '@noble/hashes/sha512';
 import { Field } from '@noble/curves/abstract/modular';

src/crypto/public_key/elliptic/ecdh.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Key encryption and decryption for RFC 6637 ECDH
  * @module crypto/public_key/elliptic/ecdh
+ * @access private
  */
 
 import { CurveWithOID, jwkToRawPublic, rawPublicToJWK, privateToJWK, validateStandardParams, checkPublicPointEnconding } from './oid_curves';

src/crypto/public_key/elliptic/ecdh_x.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Key encryption and decryption for RFC 6637 ECDH
  * @module crypto/public_key/elliptic/ecdh
+ * @access private
  */
 
 import * as aesKW from '../../aes_kw';

src/crypto/public_key/elliptic/ecdsa.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Implementation of ECDSA following RFC6637 for Openpgpjs
  * @module crypto/public_key/elliptic/ecdsa
+ * @access private
  */
 
 import enums from '../../../enums';

src/crypto/public_key/elliptic/eddsa.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Implementation of EdDSA following RFC4880bis-03 for OpenPGP
  * @module crypto/public_key/elliptic/eddsa
+ * @access private
  */
 
 import util from '../../../util';

src/crypto/public_key/elliptic/eddsa_legacy.js

@@ -19,6 +19,7 @@
  * @fileoverview Implementation of legacy EdDSA following RFC4880bis-03 for OpenPGP.
  * This key type has been deprecated by the crypto-refresh RFC.
  * @module crypto/public_key/elliptic/eddsa_legacy
+ * @access private
  */
 
 import util from '../../../util';

src/crypto/public_key/elliptic/index.js

@@ -22,6 +22,7 @@
  * @see module:crypto/public_key/elliptic/ecdsa
  * @see module:crypto/public_key/elliptic/eddsa
  * @module crypto/public_key/elliptic
+ * @access private
  */
 
 import { CurveWithOID, generate, getPreferredHashAlgo } from './oid_curves';

src/crypto/public_key/elliptic/noble_curves.js

@@ -1,4 +1,5 @@
 /**
+ * @access private
  * This file is needed to dynamic import the noble-curves.
  * Separate dynamic imports are not convenient as they result in too many chunks,
  * which share a lot of code anyway.

src/crypto/public_key/elliptic/oid_curves.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Wrapper of an instance of an Elliptic Curve
  * @module crypto/public_key/elliptic/curve
+ * @access private
  */
 import enums from '../../../enums';
 import util from '../../../util';

src/crypto/public_key/index.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Asymmetric cryptography functions
  * @module crypto/public_key
+ * @access private
  */
 
 export * as rsa from './rsa';

src/crypto/public_key/prime.ts

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Algorithms for probabilistic random prime generation
  * @module crypto/public_key/prime
+ * @access private
  */
 import { bigIntToNumber, bitLength, gcd, getBit, mod, modExp } from '../biginteger';
 import { getRandomBigInteger } from '../random';

src/crypto/public_key/rsa.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview RSA implementation
  * @module crypto/public_key/rsa
+ * @access private
  */
 import { randomProbablePrime } from './prime';
 import { getRandomBigInteger } from '../random';

src/crypto/random.js

@@ -20,6 +20,7 @@
 /**
  * @fileoverview Provides tools for retrieving secure randomness from browsers or Node.js
  * @module crypto/random
+ * @access private
  */
 import { byteLength, mod, uint8ArrayToBigInt } from './biginteger';
 import util from '../util';

src/crypto/signature.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Provides functions for asymmetric signing and signature verification
  * @module crypto/signature
+ * @access private
  */
 
 import { elliptic, rsa, dsa } from './public_key';

src/encoding/armor.js

@@ -1,3 +1,5 @@
+/** @access private */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/encoding/base64.js

@@ -13,6 +13,7 @@
 
 /**
  * @module encoding/base64
+ * @access private
  */
 
 import { transform as streamTransform } from '@openpgp/web-stream-tools';

src/enums.js

@@ -1,5 +1,6 @@
 /**
  * @module enums
+ * @access public
  */
 
 const byValue = Symbol('byValue');

src/index.js

@@ -1,4 +1,5 @@
 /**
+ * @access public
  * Export high level API functions.
  * Usage:
  *

src/key/factory.js

@@ -1,3 +1,8 @@
+/**
+ * @module key/factory
+ * @access private
+ */
+
 // OpenPGP.js - An OpenPGP implementation in javascript
 // Copyright (C) 2015-2016 Decentral
 //

src/key/helper.js

@@ -1,6 +1,7 @@
 /**
  * @fileoverview Provides helpers methods for key module
  * @module key/helper
+ * @access private
  */
 
 import {

src/key/index.js

@@ -1,3 +1,4 @@
+/** @access private */
 import {
   readKey,
   readKeys,

src/key/key.js

@@ -1,3 +1,4 @@
+/** @access public */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/key/private_key.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 import PublicKey from './public_key';
 import { armor } from '../encoding/armor';
 import {

src/key/public_key.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Lesser General Public
 // License as published by the Free Software Foundation; either

src/key/subkey.js

@@ -1,5 +1,6 @@
 /**
  * @module key/Subkey
+ * @access private
  */
 
 import enums from '../enums';

src/key/user.js

@@ -1,5 +1,6 @@
 /**
  * @module key/User
+ * @access private
  */
 
 import enums from '../enums';

src/message.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/openpgp.js

@@ -1,3 +1,4 @@
+/** @access public */
 // OpenPGP.js - An OpenPGP implementation in javascript
 // Copyright (C) 2016 Tankred Hase
 //
@@ -723,6 +724,7 @@ function linkStreams(result, inputMessage, ...intermediateMessages) {
  * @param {'armored'|'binary'|'object'} format
  * @param {Object} config - Full configuration
  * @returns {String|Uint8Array|Object}
+ * @access private
  */
 function formatObject(object, format, config) {
   switch (format) {

src/packet/aead_encrypted_data.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // OpenPGP.js - An OpenPGP implementation in javascript
 // Copyright (C) 2016 Tankred Hase
 //

src/packet/all_packets.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Exports all OpenPGP packet types
  * @module packet/all_packets
- * @private
+ * @access private
  */
 
 export { default as CompressedDataPacket } from './compressed_data';

src/packet/compressed_data.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //
@@ -144,6 +146,7 @@ export default CompressedDataPacket;
  * @param {function(): CompressionStream|function(): DecompressionStream} compressionStreamInstantiator
  * @param {FunctionConstructor} ZlibStreamedConstructor - fflate constructor
  * @returns {ReadableStream<Uint8Array>} compressed or decompressed data
+ * @private
  */
 function zlib(compressionStreamInstantiator, ZlibStreamedConstructor) {
   return data => {
@@ -220,6 +223,7 @@ function bzip2Decompress() {
  * (supported formats cannot be determined in advance).
  * @param {'deflate-raw'|'deflate'|'gzip'|string} compressionFormat
  * @returns {{ compressor: function(): CompressionStream | false, decompressor: function(): DecompressionStream | false }}
+ * @private
  */
 const getCompressionStreamInstantiators = compressionFormat => ({
   compressor: typeof CompressionStream !== 'undefined' && (() => new CompressionStream(compressionFormat)),

src/packet/grammar.ts

@@ -1,3 +1,4 @@
+/** @access private */
 import enums from '../enums';
 
 export class GrammarError extends Error {
@@ -27,6 +28,7 @@ enum MessageType {
  * - `recordPacket` must be called for each packet in the sequence; the function will throw as soon as
  *  an invalid packet is detected.
  * - `recordEnd` must be called at the end of the packet sequence to confirm its validity.
+ * @access private
  */
 export class MessageGrammarValidator {
   // PDA validator inspired by https://blog.jabberhead.tk/2022/10/26/implementing-packet-sequence-validation-using-pushdown-automata/ .

src/packet/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module packet
+ * @access private
+ */
 export * from './all_packets';
 export { default as PacketList } from './packetlist';
 export { UnparseablePacket } from './packet';

src/packet/literal_data.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/marker.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/one_pass_signature.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/packet.js

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Functions for reading and writing packets
  * @module packet/packet
+ * @access private
  */
 
 import { ArrayStream, getWriter as streamGetWriter } from '@openpgp/web-stream-tools';

src/packet/packetlist.js

@@ -1,3 +1,4 @@
+/** @access private */
 import { transformPair as streamTransformPair, transform as streamTransform, getWriter as streamGetWriter, getReader as streamGetReader, clone as streamClone } from '@openpgp/web-stream-tools';
 import {
   readPacket, supportsStreaming,
@@ -19,6 +20,7 @@ import defaultConfig from '../config';
  * @param {Object} allowedPackets - mapping where keys are allowed packet tags, pointing to their Packet class
  * @returns {Object} New packet object with type based on tag
  * @throws {Error|UnsupportedError} for disallowed or unknown packets
+ * @access private
  */
 export function newPacketFromTag(tag, allowedPackets) {
   if (!allowedPackets[tag]) {
@@ -39,6 +41,7 @@ export function newPacketFromTag(tag, allowedPackets) {
  * Take care when iterating over it - the packets themselves
  * are stored as numerical indices.
  * @extends Array
+ * @access public
  */
 class PacketList extends Array {
   /**

src/packet/padding.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // OpenPGP.js - An OpenPGP implementation in javascript
 // Copyright (C) 2022 Proton AG
 //

src/packet/public_key.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/public_key_encrypted_session_key.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/public_subkey.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/secret_key.js

@@ -1,3 +1,4 @@
+/** @access public */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //
@@ -566,6 +567,7 @@ class SecretKeyPacket extends PublicKeyPacket {
  * @param {Uint8Array} [serializedPacketTag] - for AEAD-encrypted keys only (excluding v5)
  * @param {Boolean} [isLegacyAEAD] - for AEAD-encrypted keys from RFC4880bis (v4 and v5 only)
  * @returns encryption key
+ * @access private
  */
 async function produceEncryptionKey(keyVersion, s2k, passphrase, cipherAlgo, aeadMode, serializedPacketTag, isLegacyAEAD) {
   if (s2k.type === 'argon2' && !aeadMode) {

src/packet/secret_subkey.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/signature.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/sym_encrypted_integrity_protected_data.js

@@ -1,3 +1,4 @@
+/** @access public */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //
@@ -238,6 +239,7 @@ export default SymEncryptedIntegrityProtectedDataPacket;
  * @param {Uint8Array | ReadableStream<Uint8Array>} data - The data to en/decrypt
  * @returns {Promise<Uint8Array | ReadableStream<Uint8Array>>}
  * @async
+ * @access private
  */
 export async function runAEAD(packet, fn, key, data) {
   const isSEIPDv2 = packet instanceof SymEncryptedIntegrityProtectedDataPacket && packet.version === 2;

src/packet/sym_encrypted_session_key.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/symmetrically_encrypted_data.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/trust.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 import enums from '../enums';
 import { UnsupportedError } from './packet';
 

src/packet/user_attribute.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/packet/userid.js

@@ -1,3 +1,5 @@
+/** @access public */
+
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/signature.js

@@ -1,3 +1,4 @@
+/** @access public */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //

src/type/ecdh_symkey.js

@@ -19,6 +19,7 @@
  * Encoded symmetric key for ECDH (incl. legacy x25519)
  *
  * @module type/ecdh_symkey
+ * @access private
  */
 
 import util from '../util';

src/type/ecdh_x_symkey.js

@@ -4,6 +4,7 @@
  * the former includes an algorithm byte preceeding the encrypted session key.
  *
  * @module type/x25519x448_symkey
+ * @access private
  */
 
 import util from '../util';

src/type/kdf_params.js

@@ -1,3 +1,4 @@
+/** @access private */
 // OpenPGP.js - An OpenPGP implementation in javascript
 // Copyright (C) 2015-2016 Decentral
 //
@@ -25,10 +26,8 @@ import { UnsupportedError } from '../packet/packet';
  * encryption.  The Concatenation Key Derivation Function (Approved
  * Alternative 1) [NIST-SP800-56A] with the KDF hash function that is
  * SHA2-256 [FIPS-180-3] or stronger is REQUIRED.
- * @module type/kdf_params
+ * @access private
- * @private
  */
-
 class KDFParams {
   /**
    * @param {enums.hash} hash - Hash algorithm

src/type/keyid.js

@@ -1,3 +1,4 @@
+/** @access private */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //
@@ -15,10 +16,6 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
-/**
- * @module type/keyid
- */
-
 import util from '../util';
 
 /**
@@ -29,6 +26,7 @@ import util from '../util';
  * Implementations SHOULD NOT assume that Key IDs are unique.  The
  * section "Enhanced Key Formats" below describes how Key IDs are
  * formed.
+ * @access private
  */
 class KeyID {
   constructor() {

src/type/oid.js

@@ -30,6 +30,7 @@
  * is constructed by omitting the first two octets.  Only the truncated
  * sequence of octets is the valid representation of a curve OID.
  * @module type/oid
+ * @access private
  */
 
 import util from '../util';

src/type/s2k/argon2.js

@@ -1,3 +1,4 @@
+/** @access private */
 import defaultConfig from '../../config';
 import enums from '../../enums';
 import util from '../../util';
@@ -25,6 +26,7 @@ let argon2Promise;
 // reload wasm module above this treshold, to deallocated used memory
 const ARGON2_WASM_MEMORY_THRESHOLD_RELOAD = 2 << 19;
 
+/** @access private */
 class Argon2S2K {
   /**
   * @param {Object} [config] - Full configuration, defaults to openpgp.config

src/type/s2k/generic.js

@@ -1,3 +1,4 @@
+/** @access private */
 // GPG4Browsers - An OpenPGP implementation in javascript
 // Copyright (C) 2011 Recurity Labs GmbH
 //
@@ -15,6 +16,12 @@
 // License along with this library; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+import defaultConfig from '../../config';
+import { getRandomBytes, computeDigest } from '../../crypto';
+import enums from '../../enums';
+import { UnsupportedError } from '../../packet/packet';
+import util from '../../util';
+
 /**
  * Implementation of the String-to-key specifier
  *
@@ -24,15 +31,8 @@
  * places, currently: to encrypt the secret part of private keys in the
  * private keyring, and to convert passphrases to encryption keys for
  * symmetrically encrypted messages.
- * @module type/s2k
+ * @access private
  */
-
-import defaultConfig from '../../config';
-import { getRandomBytes, computeDigest } from '../../crypto';
-import enums from '../../enums';
-import { UnsupportedError } from '../../packet/packet';
-import util from '../../util';
-
 class GenericS2K {
   /**
    * @param {Object} [config] - Full configuration, defaults to openpgp.config

src/type/s2k/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module type/s2k
+ * @access private
+ */
 import defaultConfig from '../../config';
 import Argon2S2K, { Argon2OutOfMemoryError } from './argon2';
 import GenericS2K from './generic';
@@ -9,9 +13,10 @@ const allowedS2KTypesForEncryption = new Set([enums.s2k.argon2, enums.s2k.iterat
 /**
  * Instantiate a new S2K instance of the given type
  * @param {module:enums.s2k} type
- * @oaram {Object} [config]
+ * @param {Object} [config]
  * @returns {Object} New s2k object
  * @throws {Error} for unknown or unsupported types
+
  */
 export function newS2KFromType(type, config = defaultConfig) {
   switch (type) {

src/util.js

@@ -20,6 +20,7 @@
 /**
  * This object contains utility functions
  * @module util
+ * @access private
  */
 
 import { concat as streamConcat, transform as streamTransform, concatUint8Array, isStream, isUint8Array } from '@openpgp/web-stream-tools';