@polyjose/node 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The polyjose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @polyjose/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+polyjose for Node.js: JOSE (JWS, JWE, JWK and JWT; RFC 7515 to 7519) implemented in pure Rust and
+loaded as a Node-API addon. All cryptography comes from the RustCrypto and dalek crates, with no
+OpenSSL. Verify and decrypt always take an explicit algorithm allow-list, and `none` is never
+accepted (RFC 8725).
+
+## Install
+
+```sh
+npm install @polyjose/node
+```
+
+npm also installs the matching prebuilt addon, `@polyjose/node-<platform>`, for macOS (x64,
+arm64), Linux glibc and musl (x64, arm64) and Windows (x64, arm64). Each is an optional
+dependency at exactly this package's version, and npm installs only the one for your platform.
+If you install with `--omit=optional`, no addon is installed and the import throws.
+
+### Linux glibc floor
+
+The Linux glibc addons (`linux-x64-gnu`, `linux-arm64-gnu`) need **glibc 2.28 or later**. That is
+also the floor of the official Node.js 22 and later Linux builds, so any glibc system that runs
+official Node 22 can load the addon. They are built in the `manylinux_2_28` images (glibc 2.28),
+and the build fails if an addon needs a newer glibc symbol version.
+
+| Distribution | glibc |
+|---|---|
+| RHEL, AlmaLinux, Rocky Linux 8 | 2.28 |
+| Debian 11 | 2.31 |
+| Ubuntu 20.04 | 2.31 |
+| RHEL, AlmaLinux, Rocky Linux 9 | 2.34 |
+| Amazon Linux 2023, AWS Lambda `nodejs22.x` and `nodejs24.x` | 2.34 |
+| Ubuntu 22.04 | 2.35 |
+| Debian 12 | 2.36 |
+| Ubuntu 24.04 | 2.39 |
+
+Any later release of these works too. Amazon Linux 2 (glibc 2.26) is not supported: it reached its
+end of life on 2026-06-30, and official Node 22 doesn't run on it either. Alpine and other musl
+systems use the `linux-x64-musl` and `linux-arm64-musl` addons instead.
+
+## Module format
+
+- The package is **ESM only** and needs **Node.js 22.12 or later**.
+- CommonJS code can still load it with `require("@polyjose/node")`, through Node's `require(esm)`
+  (unflagged since 22.12).
+- Every operation returns a Promise. The work runs on the libuv thread pool, so it doesn't block
+  the event loop.
+- The API and its TypeScript types are the same as `@polyjose/wasm`, so you can switch between
+  the two packages by changing the import.
+
+## Documentation
+
+Guides and the API reference are at <https://polyjose.dev>. The Node.js guide is at
+<https://polyjose.dev/start/node/>.
+
+## Loading the addon
+
+The package loads **only the polyjose addon whose SHA-256 it was built with**. Otherwise the
+import throws an `Error` with `code` `ERR_POLYJOSE_ADDON_REFUSED`, and nothing it refused has run.
+
+- **The hash pin.** The package ships `addon-sha256.json`: the SHA-256 of each platform's addon,
+  generated when the package is built. Before anything loads, the package picks the one addon file
+  for your platform, the same one the generated napi-rs loader (`binding.cjs`) would pick:
+  1. the file named by `NAPI_RS_NATIVE_LIBRARY_PATH`, if set (see below);
+  2. else a local `polyjose.<platform>.node` next to the loader;
+  3. else the platform package `@polyjose/node-<platform>`, found through Node's normal module
+     resolution: this package's `node_modules`, then every ancestor `node_modules`, then
+     `NODE_PATH`.
+
+  It hashes that file and refuses it unless the hash is the pinned one. The refusal names the
+  platform, both hashes and where the file came from. There is no fallback to another file. So a
+  substitute is refused wherever it was planted, a native addon as much as a JavaScript file,
+  including when the genuine platform package is missing: after `npm install --omit=optional`, or
+  on a platform polyjose doesn't publish. A package without the map, or without an entry for your
+  platform, loads nothing.
+- **No swap after the check.** The package writes the bytes it checked to a new private directory
+  in `os.tmpdir()` (mode `0700`; on Windows, your own `%TEMP%`), checks the copy again, and has
+  the loader load exactly that copy. Then it deletes the copy; the loaded addon stays in memory.
+  Windows can't delete a loaded DLL, so there each copy (the size of the addon) stays in the
+  temporary directory. The temporary directory must allow loading native code: if yours is
+  mounted `noexec`, point `TMPDIR` (`TEMP` on Windows) at one that does.
+- **Every candidate is native.** Before that, everything the loader could pick must be a native
+  `.node` file. If any candidate resolves to something else, such as a JavaScript
+  `@polyjose/node-<platform>` in a parent folder or on `NODE_PATH`, the import throws before that
+  file runs.
+- **After loading,** the result must be exactly the checked copy, not wrapped by any JavaScript,
+  and its own `version()` must be this package's version. An addon from another polyjose release
+  is refused, whatever `NAPI_RS_ENFORCE_VERSION_CHECK` says.
+- polyjose **never publishes a `wasm32-wasi` package**. The napi-rs loader still has a WASI
+  fallback, tried when the native load fails: `./polyjose.wasi.cjs`, then
+  `@polyjose/node-wasm32-wasi`. The package never reaches it. If either WASI file or package can be
+  found from the loader's directory, the import throws before anything is loaded. If loading the
+  checked copy fails, the import throws "Cannot find native binding". For WebAssembly, use
+  `@polyjose/wasm`.
+
+These checks keep the package from *choosing* a substitute. They can't protect against code that
+already runs in your process, which can change anything.
+
+### Environment variables
+
+| Variable | Effect |
+|---|---|
+| `NAPI_RS_NATIVE_LIBRARY_PATH` | Loads the addon from this path instead of the installed one, **only if its SHA-256 is the pinned one** for your platform (see below). |
+| `NAPI_RS_FORCE_WASI` | **Refused.** If it is set, whatever the value (even `false` or empty), the import throws. |
+| `NAPI_RS_WASI_FLAVOR` | **Refused**, like `NAPI_RS_FORCE_WASI`. |
+| `NAPI_RS_ENFORCE_VERSION_CHECK` | Read by the generated loader only. The package checks the hash and the version anyway (see above). |
+
+**`NAPI_RS_NATIVE_LIBRARY_PATH` is held to the same pin.** It names the file the package checks, so
+it can only relocate polyjose's own addon, for example out of an archive or a bundle. A JavaScript
+file there is refused before it runs; any other native library is refused by its hash. The package
+sets the variable to its private copy while the loader runs and restores your value right after.
+
+### A panic in the addon aborts the process
+
+If the Rust code ever panics, Node.js **aborts the whole process** (SIGABRT). The Promise isn't
+rejected, and no `catch` or `process.on("uncaughtException")` handler runs. This fails closed:
+no partial result is returned, and no memory is corrupted. Today we know of no input that causes a
+panic; the core forbids `panic!`, `unwrap` and `expect`. A server that must survive a panic should
+run polyjose in a worker process it can restart. Turning panics into rejected Promises is planned.
+
+### Side effects of loading
+
+- **Linux:** to tell musl from glibc, the package reads `/usr/bin/ldd`, as the generated loader
+  would. If that fails, it calls `process.report.getReport()`, and before that it sets
+  `process.report.excludeNetwork = true` for the whole process. If there is no report either, the
+  import throws. (The loader's last resort, `ldd --version` in a child process, is never run.)
+- **Windows x64:** an embedder that runs Node as a shared library (`node_target_type` is
+  `shared_library`), or a Node whose `shlib_suffix` is `dll.a`, maps to the `win32-x64-gnu`
+  platform, as in the loader. polyjose doesn't publish that addon, so those hosts can't load the
+  package.
+- **Temporary directory:** each import that loads the addon creates one directory in
+  `os.tmpdir()` (see "No swap after the check").
+- **`__napiBindingTarget`:** the loaded addon has an extra property, `__napiBindingTarget`
+  (`"native"`), set by the loader. The package's own API doesn't export it.
+
+## Secrets in results
+
+Results are plain objects, and their byte fields are plain `Uint8Array`s. So **printing a result
+prints its secret bytes**: `console.log`, `util.inspect`, `JSON.stringify` and error reporters
+show every byte. (The Kotlin and Swift bindings redact these fields when printed; JavaScript keeps
+plain data instead, ADR 0065.)
+
+- Never log a `JwsVerified` or `JweDecrypted` result.
+- Never log the options and records that carry a secret: `JwsVerifyOptions` (`detachedPayload`),
+  `JweEncryptOptions` (`aad`), `JwsSigner` and `JweRecipient` (`key`). Never log a private JWK.
+- The seven secret fields are `JwsSigner.key`, `JweRecipient.key`, `JwsVerified.payload`,
+  `JweDecrypted.plaintext`, `JweDecrypted.aad`, `JweEncryptOptions.aad` and
+  `JwsVerifyOptions.detachedPayload`.
+- When you are done with a returned `Uint8Array`, wipe it with `fill(0)`. JavaScript strings, such
+  as a JWK's text, can't be wiped.
+
+## License
+
+MIT; see `LICENSE`. `THIRD-PARTY-NOTICES.txt` lists the third-party code this package contains.
+Each platform package carries its own `THIRD-PARTY-NOTICES.txt` for the Rust crates compiled into
+its addon.

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,80 @@
+THIRD-PARTY NOTICES
+
+Artifact: @polyjose/node 0.1.1
+
+This package is polyjose's JavaScript layer for Node.js: the shared facade (facade/), the
+package entry (index.js, backend.js), their TypeScript declarations, and the Node-API loader
+(binding.cjs, binding.d.ts). It contains no native code. The facade and the entry are
+polyjose's own code. binding.cjs and binding.d.ts are generated by @napi-rs/cli 3.10.12
+from its loader template; its license is reproduced below.
+
+The native addon, and the Rust crates compiled into it, ship in one platform package per
+target, each with its own THIRD-PARTY-NOTICES.txt:
+@polyjose/node-darwin-arm64
+@polyjose/node-darwin-x64
+@polyjose/node-linux-arm64-gnu
+@polyjose/node-linux-arm64-musl
+@polyjose/node-linux-x64-gnu
+@polyjose/node-linux-x64-musl
+@polyjose/node-win32-arm64-msvc
+@polyjose/node-win32-x64-msvc
+
+Generated by bindings/node/scripts/pack-main.sh; do not edit.
+
+================================================================================
+polyjose
+================================================================================
+License: MIT
+Repository: https://github.com/bharathkontham/polyjose
+
+--- License text: LICENSE ---
+MIT License
+
+Copyright (c) 2026 The polyjose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+@napi-rs/cli 3.10.12 (generated binding.cjs and binding.d.ts)
+================================================================================
+License: MIT
+Repository: https://github.com/napi-rs/napi-rs
+
+--- License text: LICENSE ---
+MIT License
+
+Copyright (c) 2020 LongYinan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/addon-sha256.json

@@ -0,0 +1,10 @@
+{
+  "darwin-arm64": "eb38505b0e82c9c6b0000422bc4818e82dc71aa3deaf9eb86e28b1ccfecc72b6",
+  "darwin-x64": "237d8fe44770833f96a8d2ae5b2c41122d939d6ce4f1dfe8e8801ba3f7d064d1",
+  "linux-arm64-gnu": "115fd95fce72f00ec5e0029abf44205068f9c4097ed52fd9d6a1618eaaa61ef5",
+  "linux-arm64-musl": "de73ab1a2f5f61d9917e043aac756a2ca54021a788a994145d6e5e0f0211ac86",
+  "linux-x64-gnu": "a13b6b39e8661230844fa43d2b8baa9396e55c2a7ccfb6917cb56bc033083aef",
+  "linux-x64-musl": "1a114b20c79f6e5b974c42f01a2bc1f1cd2a9542fa98b05af5720c22f9544732",
+  "win32-arm64-msvc": "2d1fa65e5b8b45cf2f9bc04e0a33063af9d6eb374fdea0cca5bd74bb072bd2aa",
+  "win32-x64-msvc": "f69ec67864cbb3e898c36d8f0aae2643cf2c37f533320fb9d095cc7db6c5a3f2"
+}

package/backend.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The napi-rs backend of `@polyjose/node` (ADR 0031 §1-§2, `bindings/js/BACKEND.md`).
+ *
+ * The generated loader `binding.cjs` (`napi build --platform --js binding.cjs`) already is the
+ * backend contract: one function per ADR 0030 §4 operation, camelCase, in the ADR's argument
+ * order, rejecting with an `Error` whose `code` is one of `errorCodes()` (ADR 0030 §5). So this
+ * module only loads it, checks what it loaded and gives it the facade's `Backend` type; it adds no
+ * JOSE logic and renames nothing (ADR 0030 §1: loading and integrity checks are entry idiom).
+ *
+ * The loader is CommonJS (it picks the platform's `.node` file at run time), loaded here through
+ * `createRequire`, so the package stays ESM-only (ADR 0031 §3). Its types come from the generated
+ * `binding.d.ts`.
+ *
+ * **Fail closed (feature 0007 F02; review-code.md SF-4, review-security.md M1).** The generated
+ * loader returns the first module that loads, of any kind:
+ *   - `NAPI_RS_NATIVE_LIBRARY_PATH`, if set;
+ *   - then `./polyjose.<platform>.node` next to it;
+ *   - then `require('@polyjose/node-<platform>')`, which walks every ancestor `node_modules` and
+ *     `NODE_PATH`;
+ *   - then a WASI chain: `./polyjose.wasi.cjs`, then `@polyjose/node-wasm32-wasi`. The napi-rs CLI
+ *     3.10.12 template always emits it; no `napi build` option omits it, and
+ *     `NAPI_RS_FORCE_WASI` / `NAPI_RS_WASI_FLAVOR` can select it.
+ * It stamps a JavaScript module found that way `"native"` too. So a JS file planted in an
+ * ancestor directory or on `NODE_PATH` would become the crypto backend and could "verify" any
+ * token. polyjose publishes only native addons (ADR 0031 §2: eight targets, no WASI build;
+ * `@polyjose/wasm` is a separate package). The generated file is never edited; this module wraps
+ * it and accepts nothing else.
+ *
+ * **Before loading,** nothing runs unless every module the loader could pick is a native addon:
+ *   1. Neither WASI variable is set, whatever its value.
+ *   2. No WASI candidate resolves.
+ *   3. Every native candidate that resolves is a `.node` file: the override path, and for every
+ *      platform the loader probes, `./polyjose.<platform>.node` and `@polyjose/node-<platform>`.
+ *      `@polyjose/node-<platform>/package.json`, which the loader also reads, must be a
+ *      `package.json`.
+ * Resolution is the loader's own: `backend.js` sits next to `binding.cjs`, and `require.resolve`
+ * uses the same directory, `node_modules` walk, `NODE_PATH` and symlink handling as the loader's
+ * `require`, and runs no code. Node loads a `.node` file only as a native addon, never as
+ * JavaScript.
+ *
+ * **The hash pin (feature 0007 F07; bindings security audit N-M1, the JVM's 0008 F05 bar).** Steps
+ * 1-6 make sure the package loads a native addon at this version, but `version()` is what the
+ * addon itself says, and a native addon is as easy to plant as a JavaScript file. So before the
+ * loader runs, this module also *authenticates* the addon:
+ *   a. `addon-sha256.json`, next to this file, maps each platform polyjose built this package for
+ *      to its addon's SHA-256 (FIPS 180-4). It is generated, never hand-edited:
+ *      `scripts/addon-hashes.sh`, run by `scripts/build.sh` for a local build and by the release
+ *      assembly of the main package for every published platform. No map, a malformed one, or no
+ *      entry for this host refuses the load: nothing is trusted by default.
+ *   b. It picks the one file the loader would load on this host (the platform name of
+ *      `hostPlatform`, the loader's own): `NAPI_RS_NATIVE_LIBRARY_PATH` when set, else
+ *      `./polyjose.<platform>.node`, else `@polyjose/node-<platform>`, resolved as above. A
+ *      caller's override is not refused; it is held to the same pin.
+ *   c. It reads that file once, hashes those bytes with `node:crypto` and refuses on a mismatch,
+ *      naming the platform, the source and both hashes. There is no fallback to another candidate.
+ *   d. It writes the same bytes, with `O_EXCL`, into a new directory from `fs.mkdtempSync` under
+ *      `os.tmpdir()` (mode 0700 on POSIX; on Windows the per-user `%TEMP%` ACL), under a random
+ *      leaf name (macOS looks a leaf name up in `DYLD_LIBRARY_PATH` before the path), checks the
+ *      copy's SHA-256 again, and points `NAPI_RS_NATIVE_LIBRARY_PATH` at it for the one
+ *      synchronous `require("./binding.cjs")`. The loader's override branch loads exactly that
+ *      path and probes nothing else, so between the check and `dlopen` only this user (who can
+ *      already change anything they run) could swap the file; whoever can write the installed
+ *      file or an ancestor `node_modules` can't. The caller's environment is restored right
+ *      after, and the copy is deleted (a loaded library stays mapped; Windows can't delete a
+ *      loaded DLL, so there the copy stays in the temporary directory).
+ *
+ * **After loading,** what the loader returned must be:
+ *   4. the exports of exactly one `.node` module in the CommonJS cache, the private copy of step
+ *      d, shared only with a loader (`binding.cjs`), so no JavaScript module wraps or re-exports
+ *      it, and a `binding.cjs` that other code required first (with its own addon) is refused;
+ *   5. stamped `__napiBindingTarget === "native"`;
+ *   6. at this package's version: `version()` must equal `package.json`'s version. That is the
+ *      workspace version, which every release keeps in step (feature 0007 T04). So an addon from
+ *      another release is refused, whatever `NAPI_RS_ENFORCE_VERSION_CHECK` says (SF-4 item 3).
+ * Every refusal is an `Error` with `code` `ERR_POLYJOSE_ADDON_REFUSED`. This doesn't defend against
+ * code already running in the process, which can patch anything. It makes sure the package never
+ * selects a substitute.
+ *
+ * `test/loader.test.ts` pins the loader's load targets and checks `LOADER_PLATFORMS` against them.
+ * So a CLI bump that adds a candidate fails there before this module can miss it.
+ */
+import type { Backend } from "./facade/backend.js";
+/**
+ * Every platform name the generated loader probes: the eight polyjose publishes (ADR 0031 §2) and
+ * the napi-rs template's others, which are never published. `test/loader.test.ts` checks that this
+ * is exactly the loader's set.
+ */
+export declare const LOADER_PLATFORMS: readonly ["darwin-x64", "darwin-arm64", "linux-x64-gnu", "linux-arm64-gnu", "linux-x64-musl", "linux-arm64-musl", "win32-x64-msvc", "win32-arm64-msvc", "android-arm64", "android-arm-eabi", "win32-x64-gnu", "win32-ia32-msvc", "darwin-universal", "freebsd-x64", "freebsd-arm64", "freebsd-ppc64", "linux-arm-musleabihf", "linux-arm-gnueabihf", "linux-loong64-musl", "linux-loong64-gnu", "linux-riscv64-musl", "linux-riscv64-gnu", "linux-ppc64-gnu", "linux-s390x-gnu", "openharmony-arm64", "openharmony-x64", "openharmony-arm"];
+/** The napi loader, typed as the facade's backend. */
+export declare const backend: Backend;