{"id":49359093,"url":"https://github.com/timothymeadows/ml-kem.netcore.browser","last_synced_at":"2026-04-27T15:03:04.071Z","repository":{"id":344312450,"uuid":"1181353525","full_name":"TimothyMeadows/ML-KEM.NetCore.Browser","owner":"TimothyMeadows","description":"ML-KEM.NetCore.Browser is a pure JavaScript companion package to ML-KEM.NetCore focused on **ML-KEM-768** compatibility in browser and Node.js runtimes.","archived":false,"fork":false,"pushed_at":"2026-03-14T03:10:52.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-14T14:49:59.978Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimothyMeadows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T03:09:47.000Z","updated_at":"2026-03-14T03:10:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TimothyMeadows/ML-KEM.NetCore.Browser","commit_stats":null,"previous_names":["timothymeadows/ml-kem.netcore.browser"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TimothyMeadows/ML-KEM.NetCore.Browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FML-KEM.NetCore.Browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FML-KEM.NetCore.Browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FML-KEM.NetCore.Browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FML-KEM.NetCore.Browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimothyMeadows","download_url":"https://codeload.github.com/TimothyMeadows/ML-KEM.NetCore.Browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyMeadows%2FML-KEM.NetCore.Browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32341455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-27T15:02:40.205Z","updated_at":"2026-04-27T15:03:04.060Z","avatar_url":"https://github.com/TimothyMeadows.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ML-KEM.NetCore.Browser\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm](https://img.shields.io/npm/v/ml-kem.netcore.browser.svg)](https://www.npmjs.com/package/ml-kem.netcore.browser)\n[![nuget](https://img.shields.io/nuget/v/ML-KEM.NetCore.Browser.svg)](https://www.nuget.org/packages/ML-KEM.NetCore.Browser/)\n\n`ML-KEM.NetCore.Browser` is a pure JavaScript companion package to [`ML-KEM.NetCore`](https://github.com/TimothyMeadows/ML-KEM.NetCore), focused on **ML-KEM-768** compatibility in browser and Node.js runtimes.\n\nThe package includes high-level KEM APIs (`generateKeyPair`, `encapsulate`, `decapsulate`) and lower-level modules for polynomial math, packing, NTT, and CPA-PKE internals.\n\n---\n\n## Table of contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [npm](#npm)\n  - [NuGet](#nuget)\n  - [Browser script bundle](#browser-script-bundle)\n- [Quick start](#quick-start)\n  - [ESM usage](#esm-usage)\n  - [Browser global usage](#browser-global-usage)\n- [API reference](#api-reference)\n  - [`generateKeyPair(seed64?)`](#generatekeypairseed64)\n  - [`encapsulate(publicKey, seed32?)`](#encapsulatepublickey-seed32)\n  - [`decapsulate(secretKey, ciphertext)`](#decapsulatesecretkey-ciphertext)\n  - [`setRandomBytesProvider(provider)`](#setrandombytesproviderprovider)\n  - [`MLKEM_768` parameter sizes](#mlkem_768-parameter-sizes)\n- [Deterministic/vector workflows](#deterministicvector-workflows)\n- [Validation and testing](#validation-and-testing)\n- [Development](#development)\n- [Interoperability notes](#interoperability-notes)\n- [Security notes](#security-notes)\n- [License](#license)\n\n---\n\n## Requirements\n\n- Runtime: modern browser or Node.js with ES modules.\n- No native addons required.\n- Project package type: `\"module\"`.\n\n---\n\n## Installation\n\n### npm\n\n```bash\nnpm install ml-kem.netcore.browser\n```\n\n### NuGet\n\n```bash\ndotnet add package ML-KEM.NetCore.Browser\n```\n\n### Browser script bundle\n\nBuild the one-file bundle:\n\n```bash\nnpm run build:bundle\n```\n\nThen include it in your page:\n\n```html\n\u003cscript src=\"./dist/ML-KEM.NetCore.Browser.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { generateKeyPair, encapsulate, decapsulate } = window.MLKEMNetCoreBrowser;\n\u003c/script\u003e\n```\n\n---\n\n## Quick start\n\n### ESM usage\n\n```js\nimport { generateKeyPair, encapsulate, decapsulate } from 'ml-kem.netcore.browser';\n\nconst { publicKey, secretKey } = await generateKeyPair();\nconst { ciphertext, sharedSecret: senderSecret } = await encapsulate(publicKey);\nconst { sharedSecret: receiverSecret } = await decapsulate(secretKey, ciphertext);\n\nconsole.log(senderSecret.length, receiverSecret.length); // 32, 32\n```\n\n### Browser global usage\n\n```html\n\u003cscript src=\"./dist/ML-KEM.NetCore.Browser.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  (async () =\u003e {\n    const { generateKeyPair, encapsulate, decapsulate } = window.MLKEMNetCoreBrowser;\n\n    const { publicKey, secretKey } = await generateKeyPair();\n    const { ciphertext, sharedSecret: senderSecret } = await encapsulate(publicKey);\n    const { sharedSecret: receiverSecret } = await decapsulate(secretKey, ciphertext);\n\n    console.log(senderSecret, receiverSecret);\n  })();\n\u003c/script\u003e\n```\n\n---\n\n## API reference\n\nAll binary values are `Uint8Array`.\n\n### `generateKeyPair(seed64?)`\n\n```ts\nasync function generateKeyPair(seed64?: Uint8Array): Promise\u003c{\n  publicKey: Uint8Array;\n  secretKey: Uint8Array;\n}\u003e;\n```\n\n- Without `seed64`, key generation uses the configured random source.\n- With `seed64`, deterministic derivation is used (intended for vectors/tests).\n\n### `encapsulate(publicKey, seed32?)`\n\n```ts\nasync function encapsulate(publicKey: Uint8Array, seed32?: Uint8Array): Promise\u003c{\n  ciphertext: Uint8Array;\n  sharedSecret: Uint8Array;\n}\u003e;\n```\n\n- `publicKey` must be a `Uint8Array` with ML-KEM-768 public key length.\n- Optional `seed32` enables deterministic encapsulation for vector scenarios.\n\n### `decapsulate(secretKey, ciphertext)`\n\n```ts\nasync function decapsulate(secretKey: Uint8Array, ciphertext: Uint8Array): Promise\u003c{\n  sharedSecret: Uint8Array;\n}\u003e;\n```\n\n- Both arguments must be `Uint8Array` values.\n- Returns the receiver shared secret.\n\n### `setRandomBytesProvider(provider)`\n\n```ts\nfunction setRandomBytesProvider(provider: (length: number) =\u003e Uint8Array): void;\n```\n\n- Overrides random byte generation used internally.\n- Useful for deterministic testing harnesses and controlled environments.\n\n### `MLKEM_768` parameter sizes\n\n```ts\nconst MLKEM_768 = {\n  publicKeyBytes: 1184,\n  secretKeyBytes: 2400,\n  ciphertextBytes: 1088,\n  sharedSecretBytes: 32,\n  // ...other structural parameters\n};\n```\n\nImport from:\n\n```js\nimport { MLKEM_768 } from 'ml-kem.netcore.browser';\n// or: import { MLKEM_768 } from 'ml-kem.netcore.browser/params';\n```\n\n---\n\n## Deterministic/vector workflows\n\nThis package supports deterministic pathways used for fixture generation and cross-language verification:\n\n- `generateKeyPair(seed64)` for deterministic key derivation.\n- `encapsulate(publicKey, seed32)` for deterministic encapsulation.\n\nReference fixture:\n\n- `test/vectors/mlkem768-fixture.json`\n\n---\n\n## Validation and testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\nDry-run publish contents:\n\n```bash\nnpm run pack:check\n```\n\nTests include:\n\n- ML-KEM round-trip behavior\n- CPA-PKE layer checks\n- Cross-language deterministic vector validation\n\n---\n\n## Development\n\n### Build browser bundle\n\n```bash\nnpm run build:bundle\n```\n\n### Main implementation modules\n\n- High-level API:\n  - `src/index.js`\n  - `src/mlkem.js`\n- Core primitives:\n  - `src/params.js`\n  - `src/random.js`\n  - `src/sha3.js`\n  - `src/shake.js`\n  - `src/keccak-f1600.js`\n  - `src/sponge.js`\n  - `src/utils.js`\n  - `src/modq.js`\n  - `src/poly.js`\n  - `src/polyvec.js`\n  - `src/ntt.js`\n  - `src/packing.js`\n  - `src/cpapke.js`\n- Vendored core:\n  - `src/vendor/mlkem/*`\n\n---\n\n## Interoperability notes\n\n- This package is intended to maintain byte-level interoperability with `ML-KEM.NetCore` for ML-KEM-768 workflows.\n- Keep parameter set and serialized sizes aligned between communicating peers.\n- Prefer deterministic methods only for test vectors and reproducibility.\n\n---\n\n## Security notes\n\n- Treat secret material (`secretKey`, `sharedSecret`) as sensitive and keep lifetimes short.\n- Clear transient buffers in application code when possible.\n- Validate all external key/ciphertext lengths before calling KEM operations.\n- For high-assurance use, perform an independent cryptographic and implementation review.\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothymeadows%2Fml-kem.netcore.browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimothymeadows%2Fml-kem.netcore.browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothymeadows%2Fml-kem.netcore.browser/lists"}