@polyjose/node 0.0.0-stage → 0.1.2

package/addon-sha256.json

@@ -0,0 +1,10 @@
+{
+  "darwin-arm64": "2fddd1beba8c3bda8c3c6e7ebf84cb19b601ff3cf03db0c2b9ee421b17c5164e",
+  "darwin-x64": "b5a0c5b0fa18ffcb372944782f5ebaa01a1353d4734fab372db0d99b673f9866",
+  "linux-arm64-gnu": "197e9632aa6737a059789038366b0cbd3fb49ee4e8b09ec1194b7187c6f7d53a",
+  "linux-arm64-musl": "1ad5baebf6a0fa75d24ae343b9b5e180876edef836b033e8dbec5dd686df5396",
+  "linux-x64-gnu": "69c828632292671c0e3f8004b39de3fc4065cf2b734df85844280ddb35767bad",
+  "linux-x64-musl": "cb411795274b60909e022d080431b80494112df6ccf507a50538c12cab60b5d7",
+  "win32-arm64-msvc": "157a25122817918748b02eb0715d7f1163254b2575452327b358ac5cb381cd16",
+  "win32-x64-msvc": "7c2b07e6d943ea2fd3b6a96d8105e30d10489d719a614c29dba9c4f858a168d3"
+}

package/backend.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The napi-rs backend of `@polyjose/node` (ADR 0031 §1-§2, `bindings/js/BACKEND.md`; packaging as
+ * superseded by the feature 0017 ADR: one package that ships the addon of all eight targets).
+ *
+ * The native addon `polyjose.<platform>.node` 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). Its types are the `binding.d.ts` that
+ * `napi build --dts` generates. So this module only picks the addon for this host, authenticates
+ * it, loads it 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).
+ *
+ * **No resolving loader (feature 0017; review-security.md M1, feature 0007 F02).** napi-rs's
+ * generated loader picks the first module that loads from an override variable, the package
+ * directory, every ancestor `node_modules`, `NODE_PATH` and a WASI chain, so a JavaScript or native
+ * file planted in any of them could become the crypto backend and "verify" any token. polyjose
+ * builds no such loader (`napi build --no-js`) and resolves no module name at all: this file reads
+ * only files of its own package directory, `dirname(import.meta.url)`, by absolute path. It never
+ * reads `process.env`, so neither `NODE_PATH` nor any `NAPI_RS_*` variable changes what loads.
+ *
+ * **The steps (the F07 hash-pin model, bindings security audit N-M1, the JVM's 0008 F05 bar):**
+ *   1. The platform name (`detectPlatform`): `darwin-<arch>`, `win32-<arch>-msvc`, or
+ *      `linux-<arch>-gnu|musl` for x64 and arm64, with napi-rs's names. Any other host is refused
+ *      by name, pointing at `@polyjose/wasm`, which runs everywhere.
+ *   2. `addon-sha256.json`, in the package directory, maps each shipped platform 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 `scripts/pack-main.sh` over the eight addons the
+ *      package ships. No map, a malformed one, or no entry for this host refuses the load: nothing
+ *      is trusted by default.
+ *   3. It reads `polyjose.<platform>.node` from the package directory once, hashes those bytes with
+ *      `node:crypto` and refuses on a mismatch, naming the platform, the file and both hashes.
+ *      There is no fallback to another file.
+ *   4. 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 `require`s that absolute path, which Node's `.node` handler hands
+ *      to `dlopen`. 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 package can't. The
+ *      copy is deleted right after (a loaded library stays mapped; Windows can't delete a loaded
+ *      DLL, so there the copy stays in the temporary directory).
+ *   5. What loaded must be the exports of exactly that one module in the CommonJS cache, the
+ *      private copy, so no JavaScript module wraps or re-exports it.
+ *   6. It must be this package's version: `version()` equals `package.json`'s version, the
+ *      workspace version every release keeps in step (feature 0007 T04), so an addon of another
+ *      release is refused.
+ * 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 what this module loads (its built-ins and its one `require`), the
+ * platform detection, and each refusal.
+ */
+import type { Backend } from "./facade/backend.js";
+/** The one `fs` call platform detection makes (so tests can fake it). */
+interface TextReader {
+    readFileSync(path: string, encoding: "utf8"): string;
+}
+interface ProcessReport {
+    excludeNetwork: boolean;
+    getReport(): {
+        readonly header?: {
+            readonly glibcVersionRuntime?: unknown;
+        };
+        readonly sharedObjects?: unknown;
+    } | null;
+}
+/** What `detectPlatform` reads of `process`. */
+interface PlatformHost {
+    readonly platform: string;
+    readonly arch: string;
+    readonly report?: ProcessReport;
+}
+/**
+ * The eight platforms whose addon this package ships (ADR 0031 §2's targets): the only keys a map
+ * may have. `test/loader.test.ts` checks them against package.json's `napi.targets` and `files`.
+ */
+export declare const PLATFORMS: readonly ["darwin-x64", "darwin-arm64", "linux-x64-gnu", "linux-arm64-gnu", "linux-x64-musl", "linux-arm64-musl", "win32-x64-msvc", "win32-arm64-msvc"];
+/**
+ * Step 1: this host's platform name, napi-rs's (`napi build --platform` names the addon after it):
+ * `darwin-x64|arm64`, `win32-x64|arm64-msvc`, `linux-x64|arm64-gnu|musl`. Any other platform or
+ * architecture is `<platform>-<arch>`, which `PLATFORMS` does not list. On Linux it reads
+ * /usr/bin/ldd and may take a process report (`isMusl`); it refuses when it cannot tell the libc.
+ */
+export declare function detectPlatform(host: PlatformHost, fs: TextReader): string;
+/** The native addon, typed as the facade's backend. */
+export declare const backend: Backend;
+export {};

package/backend.js

@@ -0,0 +1,253 @@
+/**
+ * The napi-rs backend of `@polyjose/node` (ADR 0031 §1-§2, `bindings/js/BACKEND.md`; packaging as
+ * superseded by the feature 0017 ADR: one package that ships the addon of all eight targets).
+ *
+ * The native addon `polyjose.<platform>.node` 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). Its types are the `binding.d.ts` that
+ * `napi build --dts` generates. So this module only picks the addon for this host, authenticates
+ * it, loads it 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).
+ *
+ * **No resolving loader (feature 0017; review-security.md M1, feature 0007 F02).** napi-rs's
+ * generated loader picks the first module that loads from an override variable, the package
+ * directory, every ancestor `node_modules`, `NODE_PATH` and a WASI chain, so a JavaScript or native
+ * file planted in any of them could become the crypto backend and "verify" any token. polyjose
+ * builds no such loader (`napi build --no-js`) and resolves no module name at all: this file reads
+ * only files of its own package directory, `dirname(import.meta.url)`, by absolute path. It never
+ * reads `process.env`, so neither `NODE_PATH` nor any `NAPI_RS_*` variable changes what loads.
+ *
+ * **The steps (the F07 hash-pin model, bindings security audit N-M1, the JVM's 0008 F05 bar):**
+ *   1. The platform name (`detectPlatform`): `darwin-<arch>`, `win32-<arch>-msvc`, or
+ *      `linux-<arch>-gnu|musl` for x64 and arm64, with napi-rs's names. Any other host is refused
+ *      by name, pointing at `@polyjose/wasm`, which runs everywhere.
+ *   2. `addon-sha256.json`, in the package directory, maps each shipped platform 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 `scripts/pack-main.sh` over the eight addons the
+ *      package ships. No map, a malformed one, or no entry for this host refuses the load: nothing
+ *      is trusted by default.
+ *   3. It reads `polyjose.<platform>.node` from the package directory once, hashes those bytes with
+ *      `node:crypto` and refuses on a mismatch, naming the platform, the file and both hashes.
+ *      There is no fallback to another file.
+ *   4. 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 `require`s that absolute path, which Node's `.node` handler hands
+ *      to `dlopen`. 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 package can't. The
+ *      copy is deleted right after (a loaded library stays mapped; Windows can't delete a loaded
+ *      DLL, so there the copy stays in the temporary directory).
+ *   5. What loaded must be the exports of exactly that one module in the CommonJS cache, the
+ *      private copy, so no JavaScript module wraps or re-exports it.
+ *   6. It must be this package's version: `version()` equals `package.json`'s version, the
+ *      workspace version every release keeps in step (feature 0007 T04), so an addon of another
+ *      release is refused.
+ * 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 what this module loads (its built-ins and its one `require`), the
+ * platform detection, and each refusal.
+ */
+/** The addon hash map in the package directory (step 2): `{ "<platform>": "<SHA-256, 64 lowercase hex>" }`. */
+const PINS = "addon-sha256.json";
+/** The `code` of every load refusal. */
+const REFUSED = "ERR_POLYJOSE_ADDON_REFUSED";
+/**
+ * The eight platforms whose addon this package ships (ADR 0031 §2's targets): the only keys a map
+ * may have. `test/loader.test.ts` checks them against package.json's `napi.targets` and `files`.
+ */
+export const PLATFORMS = [
+    "darwin-x64",
+    "darwin-arm64",
+    "linux-x64-gnu",
+    "linux-arm64-gnu",
+    "linux-x64-musl",
+    "linux-arm64-musl",
+    "win32-x64-msvc",
+    "win32-arm64-msvc",
+];
+const SHIPPED = PLATFORMS;
+/**
+ * A load refusal, with `code` `ERR_POLYJOSE_ADDON_REFUSED`. It names a platform, a file of the
+ * package, a version or a SHA-256; never a file's contents.
+ */
+function refuse(reason) {
+    throw Object.assign(new Error(`@polyjose/node: ${reason}`), { code: REFUSED });
+}
+/**
+ * Step 1: this host's platform name, napi-rs's (`napi build --platform` names the addon after it):
+ * `darwin-x64|arm64`, `win32-x64|arm64-msvc`, `linux-x64|arm64-gnu|musl`. Any other platform or
+ * architecture is `<platform>-<arch>`, which `PLATFORMS` does not list. On Linux it reads
+ * /usr/bin/ldd and may take a process report (`isMusl`); it refuses when it cannot tell the libc.
+ */
+export function detectPlatform(host, fs) {
+    const { platform, arch } = host;
+    if (arch !== "x64" && arch !== "arm64")
+        return `${platform}-${arch}`;
+    if (platform === "darwin")
+        return `darwin-${arch}`;
+    if (platform === "win32")
+        return `win32-${arch}-msvc`;
+    if (platform === "linux")
+        return `linux-${arch}-${isMusl(host, fs) ? "musl" : "gnu"}`;
+    return `${platform}-${arch}`;
+}
+/**
+ * musl or glibc, decided in napi-rs's order (its generated `isMusl`): `/usr/bin/ldd` names musl
+ * or not (glibc ships ldd as a script of its own, musl's runs `ld-musl-*`); if it cannot be read,
+ * the process report, taken with `excludeNetwork` set (restored after): a glibc runtime version
+ * means glibc, else a `libc.musl-`/`ld-musl-` shared object means musl. napi-rs's last resort,
+ * `ldd --version` in a child process, is not run: without a usable report this refuses instead
+ * of guessing.
+ */
+function isMusl(host, fs) {
+    try {
+        return fs.readFileSync("/usr/bin/ldd", "utf8").includes("musl");
+    }
+    catch {
+        // Unreadable: ask the process report, as napi-rs does.
+    }
+    const report = host.report;
+    if (report === undefined || typeof report.getReport !== "function") {
+        return refuse(`cannot tell glibc from musl on linux-${host.arch} (no /usr/bin/ldd, no process report); refusing to load`);
+    }
+    const before = report.excludeNetwork;
+    report.excludeNetwork = true;
+    let r;
+    try {
+        r = report.getReport();
+    }
+    finally {
+        report.excludeNetwork = before;
+    }
+    if (r === null || typeof r !== "object") {
+        return refuse(`cannot tell glibc from musl on linux-${host.arch} (empty process report); refusing to load`);
+    }
+    if (r.header?.glibcVersionRuntime)
+        return false;
+    const objects = r.sharedObjects;
+    const musl = (f) => typeof f === "string" && (f.includes("libc.musl-") || f.includes("ld-musl-"));
+    return Array.isArray(objects) && objects.some(musl);
+}
+/** Step 2: the package's addon hash map, validated, as a null-prototype record. */
+function readPins(fs, file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return refuse("addon-sha256.json is missing, so no native addon is trusted; this package was not assembled by polyjose's build");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return refuse("addon-sha256.json is not valid JSON; refusing to load");
+    }
+    const pins = Object.create(null);
+    const valid = typeof parsed === "object" &&
+        parsed !== null &&
+        !Array.isArray(parsed) &&
+        Object.entries(parsed).every(([platform, hash]) => {
+            if (!SHIPPED.includes(platform) || typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash))
+                return false;
+            pins[platform] = hash;
+            return true;
+        });
+    if (!valid) {
+        return refuse("addon-sha256.json is not a map of shipped platforms to lowercase SHA-256 hex; refusing to load");
+    }
+    return pins;
+}
+/** SHA-256 (FIPS 180-4) of `bytes`, lowercase hex. */
+function sha256(crypto, bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Steps 1-4: requires a private, hash-checked copy of this package's addon for this host. Returns
+ * what it loaded and the copy's path (the CommonJS cache key, step 5).
+ */
+function loadPinned(host, req, b, dir) {
+    const platform = detectPlatform(host, b.fs);
+    if (!SHIPPED.includes(platform)) {
+        return refuse(`there is no native addon for ${platform} (this package ships ${SHIPPED.join(", ")}); ` +
+            "use @polyjose/wasm, which has the same API and runs on every platform");
+    }
+    const pins = readPins(b.fs, b.path.join(dir, PINS));
+    const expected = pins[platform];
+    if (expected === undefined) {
+        const listed = Object.keys(pins).sort().join(", ");
+        return refuse(`this package has no pinned SHA-256 for ${platform} (addon-sha256.json lists ${listed || "none"}); refusing to load`);
+    }
+    const name = `polyjose.${platform}.node`;
+    let bytes;
+    try {
+        bytes = b.fs.readFileSync(b.path.join(dir, name));
+    }
+    catch {
+        return refuse(`./${name} is missing from this package or cannot be read; reinstall @polyjose/node`);
+    }
+    const actual = sha256(b.crypto, bytes);
+    if (actual !== expected) {
+        refuse(`./${name} for ${platform} has SHA-256 ${actual}, but this package pins ${expected}; refusing to load it`);
+    }
+    // The real path, as the CommonJS cache keys it (macOS's tmpdir is a symlink).
+    const tmp = b.fs.realpathSync(b.fs.mkdtempSync(b.path.join(b.os.tmpdir(), "polyjose-addon-")));
+    try {
+        const copy = b.path.join(tmp, `polyjose-${b.crypto.randomBytes(16).toString("hex")}.node`);
+        b.fs.writeFileSync(copy, bytes, { flag: "wx", mode: 0o700 });
+        if (sha256(b.crypto, b.fs.readFileSync(copy)) !== expected) {
+            refuse(`the private copy of the addon for ${platform} does not have the pinned SHA-256; refusing to load it`);
+        }
+        return { loaded: req(copy), copy };
+    }
+    finally {
+        try {
+            b.fs.rmSync(tmp, { recursive: true, force: true });
+        }
+        catch {
+            // Windows can't delete a DLL while it is loaded; the copy stays in the temporary directory.
+        }
+    }
+}
+/** Steps 5-6: the loaded binding is the private copy, at this package's version. */
+function checkLoaded(req, b, dir, loaded, copy) {
+    if (typeof loaded !== "object" || loaded === null) {
+        return refuse("the native addon returned no binding object");
+    }
+    const owners = Object.keys(req.cache).filter((file) => req.cache[file]?.exports === loaded);
+    if (owners.length !== 1 || owners[0] !== copy) {
+        refuse("the loaded binding is not exactly the hash-checked native addon; refusing to load");
+    }
+    let expected;
+    try {
+        expected = JSON.parse(b.fs.readFileSync(b.path.join(dir, "package.json"), "utf8")).version;
+    }
+    catch {
+        expected = undefined;
+    }
+    const actual = typeof loaded.version === "function" ? loaded.version() : undefined;
+    if (typeof expected !== "string" || actual !== expected) {
+        refuse(`the native addon is version ${String(actual)}, but this package is ${String(expected)}; reinstall it`);
+    }
+    return loaded;
+}
+/** Loads this package's pinned native addon for this host (the module comment). */
+function loadBinding(host, moduleUrl) {
+    const builtins = {
+        fs: host.getBuiltinModule("node:fs"),
+        crypto: host.getBuiltinModule("node:crypto"),
+        os: host.getBuiltinModule("node:os"),
+        path: host.getBuiltinModule("node:path"),
+    };
+    // The package directory: backend.js sits at its root, next to the addons and the pins.
+    const dir = builtins.path.dirname(host.getBuiltinModule("node:url").fileURLToPath(moduleUrl));
+    const req = host.getBuiltinModule("node:module").createRequire(moduleUrl);
+    const { loaded, copy } = loadPinned(host, req, builtins, dir);
+    return checkLoaded(req, builtins, dir, loaded, copy);
+}
+const binding = loadBinding(globalThis.process, import.meta.url);
+/** The native addon, typed as the facade's backend. */
+export const backend = binding;

package/facade/api.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The polyjose JS facade (ADR 0030, ADR 0031 §1, ADR 0047), shared unchanged by
+ * `@polyjose/node` and `@polyjose/wasm`. Each package's entry binds it to its native layer:
+ *
+ * ```ts
+ * export const { version, errorCodes, jwsVerifyCompact, ... } = createApi(backend);
+ * export { PolyjoseError, ERROR_CODES } from "./api.js";
+ * ```
+ *
+ * The facade adds idiom only (ADR 0030 §1): Promises, object↔JSON, JS type checks
+ * (`TypeError`), `null` → `undefined`, the JS clock for JWT `now`, and `PolyjoseError`.
+ * Policy, defaults and every JOSE check stay in the core.
+ */
+import type { Backend } from "./backend.js";
+import { type ErrorCode } from "./error-codes.js";
+import type { EcCurve, JsonInput, JweDecrypted, JweDecryptOptions, JweEncryptOptions, JweJsonForm, Jwk, JwkObject, JwkSelector, JwkSet, JwsSigner, JwsSignOptions, JwsVerified, JwsVerifyOptions, JwtNestedVerified, JwtSignOptions, JwtVerified, JwtVerifyOptions, KeyFormat, OkpCurve, ThumbprintHash } from "./types.js";
+export type * from "./types.js";
+export type { Backend } from "./backend.js";
+export { ERROR_CODES, type ErrorCode } from "./error-codes.js";
+/**
+ * A polyjose failure (ADR 0030 §5). `code` is one of {@link ERROR_CODES}, the core's stable
+ * `Error::code()` (ADR 0007): match on it, never on `message`, which may be reworded. Neither
+ * ever contains key material or input bytes.
+ */
+export declare class PolyjoseError extends Error {
+    readonly name = "PolyjoseError";
+    /** The stable error code. */
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+/** Every operation of ADR 0030 §4, camelCase (§2), each returning a Promise (ADR 0031 §1). */
+export interface PolyjoseApi {
+    /** The polyjose crate version. */
+    version(): Promise<string>;
+    /** The stable error codes, equal to the core's `Error::CODES` (ADR 0030 §5). */
+    errorCodes(): Promise<string[]>;
+    /** base64url without padding (RFC 4648 §5, RFC 7515 §2). */
+    base64urlEncode(bytes: Uint8Array): Promise<string>;
+    /** Strict, canonical base64url decoding (RFC 4648 §5, §3.5). */
+    base64urlDecode(text: string): Promise<Uint8Array>;
+    /** Validates a JWK (RFC 7517 §4, RFC 7518 §6, RFC 8037 §2) and returns the core's serialization. */
+    jwkParse(jwk: Jwk): Promise<JwkObject>;
+    /** The public half of a JWK (RFC 7517 §4, RFC 7518 §6.2.1, §6.3.1). */
+    jwkToPublic(jwk: Jwk): Promise<JwkObject>;
+    /**
+     * The JWK Thumbprint (RFC 7638 §3, §3.4), base64url: 43, 64 or 86 characters for SHA-256,
+     * SHA-384 or SHA-512. An absent `hash` (or `null`) is the core default, SHA-256 (ADR 0054 §9,
+     * RFC 9278 §5). Any other name fails with `UnsupportedAlgorithm` from the core, after the key's
+     * own import errors (ADR 0057 §2). Never publish the thumbprint of a password or other
+     * low-entropy `oct` key, or use it as a `kid`: it is an unsalted fast hash of the secret
+     * (ADR 0057 §4, RFC 7638 §7).
+     */
+    jwkThumbprint(jwk: Jwk, hash?: ThumbprintHash): Promise<string>;
+    /**
+     * The JWK Thumbprint URI (RFC 9278 §3), `urn:ietf:params:oauth:jwk-thumbprint:<name>:<thumbprint>`,
+     * always with the IANA hash name (`sha-256`, `sha-384`, `sha-512`; RFC 9278 §4). `hash` is as
+     * for `jwkThumbprint`.
+     */
+    jwkThumbprintUri(jwk: Jwk, hash?: ThumbprintHash): Promise<string>;
+    /**
+     * The one key of a JWK Set (RFC 7517 §5) that `selector` picks by `kid`, `alg` and `keyUse`,
+     * under the core rule (`JwkSet::select`, ADR 0054 §2). An absent selector (or `{}`) matches
+     * every member. No match rejects with `NoMatchingKey`, two or more with `MultipleMatchingKeys`
+     * (RFC 7517 §5.1 gives a set's order no meaning); an `alg` or `keyUse` the core refuses with
+     * `UnsupportedAlgorithm`, after the set's own import errors (ADR 0054 §4).
+     *
+     * The key may be private (`d`, `k`): call `jwkToPublic` before publishing it. Selection never
+     * authorizes an algorithm, so pass the key only to an operation with an allow-list, and pair a
+     * `kid` from an untrusted header with `alg` (ADR 0054 §7). A server maps `NoMatchingKey` and
+     * `MultipleMatchingKeys` to one opaque client error, such as `invalid_token` (RFC 6750 §3.1).
+     */
+    jwksSelect(jwks: JwkSet, selector?: JwkSelector): Promise<JwkObject>;
+    /** A random `oct` key of `lenBytes` octets (RFC 7518 §6.4), from the OS CSPRNG (ADR 0005). */
+    jwkGenerateOct(lenBytes: number): Promise<JwkObject>;
+    /** A random EC private key (RFC 7518 §6.2). */
+    jwkGenerateEc(crv: EcCurve): Promise<JwkObject>;
+    /** A random OKP private key (RFC 8037 §2). */
+    jwkGenerateOkp(crv: OkpCurve): Promise<JwkObject>;
+    /** A random key for a JWS `alg`, JWE `alg` or `enc` (RFC 7518 §7.1 registry), with `alg` set. */
+    jwkGenerateForAlg(alg: string): Promise<JwkObject>;
+    /** Imports one RFC 7468 PEM block (ADR 0018 §3). */
+    jwkFromPem(pem: string): Promise<JwkObject>;
+    /** Imports DER in the structure `format` names; no sniffing (ADR 0018 §3, ADR 0007). */
+    jwkFromDer(der: Uint8Array, format: KeyFormat): Promise<JwkObject>;
+    /** Exports a JWK as PEM (RFC 7468, ADR 0018 §3). */
+    jwkToPem(jwk: Jwk, format: KeyFormat): Promise<string>;
+    /** Exports a JWK as DER (ADR 0018 §3). */
+    jwkToDer(jwk: Jwk, format: KeyFormat): Promise<Uint8Array>;
+    /** Signs in the JWS Compact Serialization (RFC 7515 §5.1, §7.1). */
+    jwsSignCompact(payload: Uint8Array, key: Jwk, options: JwsSignOptions): Promise<string>;
+    /** Signs in the flattened JWS JSON Serialization (RFC 7515 §7.2.2); returns JSON text. */
+    jwsSignFlattened(payload: Uint8Array, signer: JwsSigner, detached?: boolean): Promise<string>;
+    /** Signs in the general JWS JSON Serialization (RFC 7515 §7.2.1); returns JSON text. */
+    jwsSignGeneral(payload: Uint8Array, signers: readonly JwsSigner[], detached?: boolean): Promise<string>;
+    /** Verifies a compact JWS against an explicit allow-list (RFC 7515 §5.2, RFC 8725 §3.1). */
+    jwsVerifyCompact(token: string, key: Jwk, options: JwsVerifyOptions): Promise<JwsVerified>;
+    /** Verifies a flattened or general JWS JSON Serialization (RFC 7515 §7.2, §5.2). */
+    jwsVerifyJson(jws: JsonInput, key: Jwk, options: JwsVerifyOptions): Promise<JwsVerified>;
+    /** Encrypts to one recipient in the JWE Compact Serialization (RFC 7516 §5.1, §7.1). */
+    jweEncryptCompact(plaintext: Uint8Array, options: JweEncryptOptions): Promise<string>;
+    /** Encrypts in a JWE JSON Serialization (RFC 7516 §7.2); returns JSON text. */
+    jweEncryptJson(plaintext: Uint8Array, options: JweEncryptOptions, form: JweJsonForm): Promise<string>;
+    /** Decrypts a compact JWE against explicit allow-lists (RFC 7516 §5.2, RFC 8725 §3.1). */
+    jweDecryptCompact(token: string, key: Jwk, options: JweDecryptOptions): Promise<JweDecrypted>;
+    /** Decrypts a flattened or general JWE JSON Serialization (RFC 7516 §7.2, §5.2). */
+    jweDecryptJson(jwe: JsonInput, key: Jwk, options: JweDecryptOptions): Promise<JweDecrypted>;
+    /** Issues a signed JWT (RFC 7519 §7.1; ADR 0027 §8). */
+    jwtSign(claims: JsonInput, key: Jwk, options: JwtSignOptions): Promise<string>;
+    /** Validates a signed JWT with one key (RFC 7519 §7.2; ADR 0027 policy and error order). */
+    jwtVerify(token: string, key: Jwk, options: JwtVerifyOptions): Promise<JwtVerified>;
+    /** Validates a signed JWT with a JWK Set (RFC 7517 §5; ADR 0029 selection). */
+    jwtVerifyWithJwks(token: string, jwks: JwkSet, options: JwtVerifyOptions): Promise<JwtVerified>;
+    /** Encrypts a signed JWT as a nested JWT, `cty: "JWT"` (RFC 7519 §5.2, §11.2; ADR 0027 §7). */
+    jwtEncryptNested(signedJwt: string, options: JweEncryptOptions): Promise<string>;
+    /** Decrypts and validates a nested JWT with one verification key (RFC 7519 §7.2 step 8). */
+    jwtDecryptNested(token: string, decryptKey: Jwk, decryptOptions: JweDecryptOptions, key: Jwk, verifyOptions: JwtVerifyOptions): Promise<JwtNestedVerified>;
+    /** Decrypts and validates a nested JWT with a JWK Set for the inner signature. */
+    jwtDecryptNestedWithJwks(token: string, decryptKey: Jwk, decryptOptions: JweDecryptOptions, jwks: JwkSet, verifyOptions: JwtVerifyOptions): Promise<JwtNestedVerified>;
+    /** The error class every operation rejects with for a core failure. */
+    readonly PolyjoseError: typeof PolyjoseError;
+}
+/** Binds the facade to one native layer (BACKEND.md). */
+export declare function createApi(backend: Backend): PolyjoseApi;