@polyjose/node 0.0.0-stage → 0.1.2

package/facade/normalize.js

@@ -0,0 +1,380 @@
+/**
+ * Input and output normalisation of the facade: idiom only (ADR 0030 §1 host facade row, §2;
+ * ADR 0031 §1). No policy, no defaults, no JOSE validation: the core decides all of that.
+ *
+ * Every failure here is a host `TypeError`, never a `PolyjoseError` (ADR 0030 E2: host type
+ * errors stay outside the code contract). A message names the argument and the expected type,
+ * never the value, which may be key material (ADR 0030 §5, "no input in errors").
+ */
+/** `null` and `undefined` both mean "absent" (napi throws on `null`, research §3). */
+export function isAbsent(v) {
+    return v === undefined || v === null;
+}
+function fail(at, expected) {
+    return new TypeError(`polyjose: ${at} must be ${expected}`);
+}
+/**
+ * `%TypedArray%.prototype[Symbol.toStringTag]` reads the internal [[TypedArrayName]] slot, so
+ * it can't be spoofed by an object's own `Symbol.toStringTag`, and it works across realms.
+ */
+const typedArrayName = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag)?.get;
+/** A `Uint8Array`, including a Node `Buffer` (a subclass). */
+export function isUint8Array(v) {
+    return ArrayBuffer.isView(v) && typedArrayName?.call(v) === "Uint8Array";
+}
+/** An object literal (or `Object.create(null)`), not an array or class instance. */
+export function isPlainObject(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+export function str(v, at) {
+    if (typeof v !== "string")
+        throw fail(at, "a string");
+    return v;
+}
+export function optStr(v, at) {
+    return isAbsent(v) ? undefined : str(v, at);
+}
+/**
+ * A byte input, as a fresh copy (ADR 0030 §7; 0013 B06). The facade calls this synchronously,
+ * when the operation is called and before it awaits the backend's lazy `ready()` (ADR 0031 §3),
+ * so a caller that reuses its array after starting a call can't change what is signed or
+ * encrypted. The copy is a plain `Uint8Array` holding exactly the view's bytes (a `Buffer` or a
+ * subarray shares no memory with it) and is pushed onto `copies`, which the facade wipes once the
+ * backend call settles; the caller's own array is never wiped. A view over a detached buffer
+ * can't be copied and is a TypeError.
+ */
+export function bytes(v, at, copies) {
+    if (!isUint8Array(v))
+        throw fail(at, "a Uint8Array");
+    let copy;
+    try {
+        // The TypedArray constructor reads the internal slots, not `length` or an iterator.
+        copy = new Uint8Array(v);
+    }
+    catch {
+        throw fail(at, "a Uint8Array over an attached ArrayBuffer");
+    }
+    append(copies, copy);
+    return copy;
+}
+export function optBytes(v, at, copies) {
+    return isAbsent(v) ? undefined : bytes(v, at, copies);
+}
+/**
+ * Wipes the copies {@link bytes} made with `fill(0)` (ADR 0030 §7). JS gives no guarantee that
+ * the engine kept no other copy (ADR 0030 §7 rule 4); this removes the facade's own.
+ */
+export function wipe(copies) {
+    for (const copy of copies)
+        copy.fill(0);
+}
+export function bool(v, at) {
+    if (typeof v !== "boolean")
+        throw fail(at, "a boolean");
+    return v;
+}
+export function optBool(v, at) {
+    return isAbsent(v) ? undefined : bool(v, at);
+}
+/** The largest `u32`: sizes and counts are `u32` in the surface (ADR 0030 §2). */
+const U32_MAX = 0xffff_ffff;
+/**
+ * A size or count: an integer in 0..=2^32−1. Checked here because wasm-bindgen would coerce
+ * `-1` to `4294967295` (research §3).
+ */
+export function u32(v, at) {
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > U32_MAX) {
+        throw fail(at, "an integer from 0 to 4294967295");
+    }
+    return v;
+}
+export function optU32(v, at) {
+    return isAbsent(v) ? undefined : u32(v, at);
+}
+/**
+ * Whole seconds since the epoch (RFC 7519 §2), a safe integer: the NumericDate and clock range
+ * ±(2^53 − 1) of ADR 0027 §2 and ADR 0028 §1, which a JS number holds exactly.
+ */
+export function optSeconds(v, at) {
+    if (isAbsent(v))
+        return undefined;
+    if (typeof v !== "number" || !Number.isSafeInteger(v))
+        throw fail(at, "a safe integer (whole seconds)");
+    return v;
+}
+/** An array literal: an `Array` whose prototype is `Array.prototype` or `null`, like {@link isPlainObject}. */
+function isPlainArray(v) {
+    if (!Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Array.prototype || proto === null;
+}
+/** A value {@link jsonText} can't serialise: caught by {@link json} and reported without the value. */
+class NotJsonData extends Error {
+}
+/**
+ * The JSON text of plain data (RFC 8259 §2–§7), read from the caller's own members only
+ * (0013 F09, security audit M1 follow-up). The output equals `JSON.stringify(v)` for plain data
+ * in an unpolluted realm: the same member order (`Object.keys`, ECMA-262 EnumerableOwnProperties),
+ * escapes and number spelling (both from `JSON.stringify` of a primitive), a member whose value
+ * is `undefined` left out and an `undefined` element written as `null`, `NaN` and `±Infinity` as
+ * `null`.
+ *
+ * It differs from `JSON.stringify` exactly where that reads the host's global state or calls
+ * the caller's code:
+ * - **no `toJSON` is called, at any depth**: neither an inherited one (a polluted
+ *   `Object.prototype.toJSON`, `Array.prototype.toJSON` or `BigInt.prototype.toJSON` could
+ *   otherwise replace the claims, key or header being sent) nor an own one;
+ * - **an array hole is not data**: `JSON.stringify` reads it through `Array.prototype`, where a
+ *   pollution bug could have put a key into a JWK Set; here it is a TypeError, as in
+ *   {@link list};
+ * - **only JSON data is accepted** (ADR 0030 §2 "a plain object", the `JsonValue` type):
+ *   {@link isPlainObject} objects, {@link isPlainArray} arrays, strings, numbers, booleans and
+ *   `null`. A `Date`, `Map`, class instance, boxed primitive, typed array, function, symbol or
+ *   BigInt is a TypeError wherever it appears, never coerced by its own or an inherited method.
+ *
+ * Each own member is read once (a getter runs once, as in {@link record}), and one an earlier
+ * getter deleted is skipped, never read through the prototype. A cycle is a TypeError; the same
+ * object reached twice without a cycle is written twice, as `JSON.stringify` does.
+ *
+ * `JSON.stringify` of a string or number is safe: ECMA-262 SerializeJSONProperty looks up
+ * `toJSON` only on an Object or a BigInt, so a primitive is never coerced through a prototype.
+ * The output is built with `+` only, so no `Array.prototype` method is involved.
+ */
+function jsonText(v, ancestors) {
+    if (v === null)
+        return "null";
+    switch (typeof v) {
+        case "string":
+            return JSON.stringify(v);
+        case "number":
+            return Number.isFinite(v) ? JSON.stringify(v) : "null";
+        case "boolean":
+            return v ? "true" : "false";
+        case "undefined":
+            return undefined;
+        case "object":
+            break;
+        default:
+            // function, symbol, bigint: not JSON data.
+            throw new NotJsonData();
+    }
+    if (ancestors.has(v))
+        throw new NotJsonData();
+    if (isPlainArray(v)) {
+        ancestors.add(v);
+        const n = v.length;
+        let out = "[";
+        for (let i = 0; i < n; i++) {
+            if (!Object.hasOwn(v, i))
+                throw new NotJsonData();
+            if (i > 0)
+                out += ",";
+            out += jsonText(v[i], ancestors) ?? "null";
+        }
+        ancestors.delete(v);
+        return out + "]";
+    }
+    if (isPlainObject(v)) {
+        ancestors.add(v);
+        let out = "{";
+        let first = true;
+        for (const key of Object.keys(v)) {
+            if (!Object.hasOwn(v, key))
+                continue;
+            const text = jsonText(v[key], ancestors);
+            if (text === undefined)
+                continue;
+            out += (first ? "" : ",") + JSON.stringify(key) + ":" + text;
+            first = false;
+        }
+        ancestors.delete(v);
+        return out + "}";
+    }
+    throw new NotJsonData();
+}
+/**
+ * JSON text (ADR 0030 §2): a string is passed through unchanged (so member order and number
+ * spelling reach the core's strict parser as written); a plain object is serialised by
+ * {@link jsonText}, the `JSON.stringify` text of its own plain data, with no `toJSON` consulted
+ * and nothing read through a prototype (0013 F09).
+ */
+export function json(v, at) {
+    if (typeof v === "string")
+        return v;
+    if (!isPlainObject(v))
+        throw fail(at, "JSON text or a plain object");
+    try {
+        return jsonText(v, new Set()) ?? "{}";
+    }
+    catch {
+        // Not JSON data, a cycle, a throwing getter or a nesting too deep for the stack. The message
+        // names the argument only: a value or member name may be key material (ADR 0030 §5).
+        throw fail(at, "JSON text or a plain object of JSON data (plain objects, arrays without holes, strings, numbers, booleans, null)");
+    }
+}
+export function optJson(v, at) {
+    return isAbsent(v) ? undefined : json(v, at);
+}
+/**
+ * A list, item by item, copied. Only the array's own elements below its `length` are read: a
+ * hole is a TypeError naming its index, never read through `Array.prototype`, where a pollution
+ * bug elsewhere in the host app could have put a value (0013 F04, security audit M1).
+ */
+export function list(v, at, item) {
+    if (!Array.isArray(v))
+        throw fail(at, "an array");
+    const n = v.length;
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        if (!Object.hasOwn(v, i))
+            throw fail(`${at}[${i}]`, "present: an array without holes");
+        append(out, item(v[i], `${at}[${i}]`));
+    }
+    return out;
+}
+export function strList(v, at) {
+    return list(v, at, str);
+}
+export function optStrList(v, at) {
+    return isAbsent(v) ? undefined : strList(v, at);
+}
+/**
+ * An allow-list (`allowedAlgs`, `allowedEnc`). Absent is passed as `[]`, which the core refuses
+ * with `AlgorithmNotAllowed`, the code an empty or `none`-only list gets on every platform
+ * (ADR 0030 §3). This is not a default list: it can never accept anything.
+ */
+export function allowList(v, at) {
+    return isAbsent(v) ? [] : strList(v, at);
+}
+/**
+ * A record with no prototype, holding only `init`'s own members. Every record the facade hands
+ * the backend is one, so a backend that reads a member by name or tests it with `in` sees only
+ * what the facade put there, never an inherited member of a polluted `Object.prototype`
+ * (0013 F04, security audit M1; ADR 0030 §3: an absent member is the core default).
+ */
+export function bare(init) {
+    return Object.assign(Object.create(null), init);
+}
+/**
+ * A record argument: a plain object whose own enumerable members are all among `members`.
+ * Absent means no members. An unknown member is a TypeError, so a misspelling (`issuer` for
+ * `issuers`) can never silently drop a check. The message lists the accepted members, not the
+ * unknown one.
+ *
+ * Returns a {@link bare} copy of the caller's own enumerable members, each read exactly once, and
+ * the facade reads options only from that copy (0013 F04, review S2, security audit M1). An
+ * inherited member, such as `Object.prototype.ignoreAudience = true` set by a pollution bug
+ * elsewhere in the host app, is never read, so it can't loosen policy, lift a limit, stand in
+ * for a missing required member or inject a header: ADR 0030 §3 makes an absent option the core
+ * default, and the host's global state must not write one either. A non-enumerable own member is
+ * not read either, and reading once means a getter can't pass the type check with one value and
+ * reach the backend with another.
+ */
+export function record(v, at, members) {
+    const out = bare({});
+    if (isAbsent(v))
+        return out;
+    if (!isPlainObject(v))
+        throw fail(at, "a plain object");
+    for (const key of Object.keys(v)) {
+        if (!members.includes(key))
+            throw fail(at, `an object with only the members ${members.join(", ")}`);
+        out[key] = v[key];
+    }
+    return out;
+}
+/**
+ * Creates `out[key]` as an own, enumerable, writable, configurable data property holding `value`
+ * (ECMA-262 ValidateAndApplyPropertyDescriptor), the descriptor an object literal's member gets
+ * (CreateDataProperty). Never an assignment (0013 F13, security audit M1 follow-up): an assignment
+ * to a member `out` doesn't own consults `out`'s prototype (OrdinarySet), so on a result, which
+ * keeps `Object.prototype`, an accessor a pollution bug put on `Object.prototype.aad` would run
+ * its setter with the secret `aad` (ADR 0030 §7) and leave the result without it, and a
+ * non-writable inherited member would make the write a TypeError.
+ *
+ * The descriptor itself has no prototype: `Object.defineProperty` reads `value`, `get`, `set`,
+ * `writable`, ... through the descriptor's prototype chain (ToPropertyDescriptor), so with an
+ * ordinary descriptor object a polluted `Object.prototype.get` would make every write a TypeError.
+ */
+export function define(out, key, value) {
+    Object.defineProperty(out, key, bare({ value, enumerable: true, writable: true, configurable: true }));
+}
+/** {@link define}s `out[key]` only when `value` is present, so absent optional fields are left out. */
+export function put(out, key, value) {
+    if (value !== undefined)
+        define(out, key, value);
+}
+/**
+ * Adds `value` at the end of `out` as an own data element ({@link define} at index `length`,
+ * which also grows `length`, ECMA-262 ArrayDefineOwnProperty). Never `push`: `push` assigns the
+ * next index (Array.prototype.push, Set(O, len, E, true)), so an accessor a pollution bug put on
+ * `Array.prototype[0]` or `Object.prototype[0]` would receive the element (a byte copy of a
+ * secret, a `JweRecipient` with its key) and leave a hole, and a non-writable one would make the
+ * call a TypeError (0013 F13).
+ */
+export function append(out, value) {
+    define(out, out.length, value);
+}
+// --- outputs (what the backend returned) -------------------------------------------------
+function badResult(at, expected) {
+    return new TypeError(`polyjose: the backend returned ${at} that is not ${expected}`);
+}
+export function outStr(v, at) {
+    if (typeof v !== "string")
+        throw badResult(at, "a string");
+    return v;
+}
+export function outBytes(v, at) {
+    if (!isUint8Array(v))
+        throw badResult(at, "a Uint8Array");
+    return v;
+}
+export function outIndex(v, at) {
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > U32_MAX)
+        throw badResult(at, "an index");
+    return v;
+}
+/**
+ * A list result (`errorCodes()`), item by item, copied: only the array's own elements below its
+ * `length` are read, so a hole reaches `item` as `undefined` (a TypeError naming its index) and is
+ * never read through a polluted `Array.prototype` (0013 F09).
+ */
+export function outList(v, at, item) {
+    if (!Array.isArray(v))
+        throw badResult(at, "an array");
+    const n = v.length;
+    const out = [];
+    for (let i = 0; i < n; i++)
+        append(out, item(Object.hasOwn(v, i) ? v[i] : undefined, `${at}[${i}]`));
+    return out;
+}
+/** JSON text the core serialized, parsed to an object (ADR 0030 §2: JWKs, headers, claims). */
+export function outObject(v, at) {
+    let parsed;
+    try {
+        parsed = JSON.parse(outStr(v, at));
+    }
+    catch (e) {
+        if (e instanceof TypeError)
+            throw e;
+        throw badResult(at, "JSON text");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw badResult(at, "a JSON object");
+    return parsed;
+}
+/**
+ * One member of a backend result (a plain object, BACKEND.md), read only if the result owns it
+ * (0013 F09, security audit M1 follow-up). A member the backend left out is `undefined`, never
+ * a value a pollution bug put on `Object.prototype`: an absent optional field (`kid`,
+ * `keyIndex`, a header, `aad`) stays absent, and a missing required one is a TypeError.
+ */
+export function member(v, name, at) {
+    if (typeof v !== "object" || v === null)
+        throw badResult(at, "an object");
+    return Object.hasOwn(v, name) ? v[name] : undefined;
+}

package/facade/types.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The public records of the JS facade: ADR 0030 §3–§4 with camelCase fields (§2).
+ *
+ * - Allow-lists (`allowedAlgs`, `allowedEnc`) are required, with no default (ADR 0007,
+ *   RFC 8725 §3.1); omitting one does not type-check. Plain JS callers that omit one get
+ *   `AlgorithmNotAllowed` from the core, never a default list.
+ * - Every tunable is optional, and absent means the core default (ADR 0030 §3). The facade
+ *   writes no default of its own.
+ * - Algorithm names are the IANA JOSE registry strings, passed as given (ADR 0030 D1).
+ * - JSON values (JWKs, JWK Sets, headers, claims, JWS/JWE JSON serializations) are accepted
+ *   as JSON text or as a plain object (ADR 0030 §2); results come back as parsed objects
+ *   (JWKs, headers, claims) or strings (tokens and JSON serializations).
+ */
+/** A JSON value as `JSON.parse` returns it. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+/** A JSON object as `JSON.parse` returns it. */
+export interface JsonObject {
+    [member: string]: JsonValue;
+}
+/** A JWK (RFC 7517 §4) as an object. */
+export interface JwkObject {
+    kty: string;
+    [member: string]: JsonValue;
+}
+/** A JWK Set (RFC 7517 §5) as an object. */
+export interface JwkSetObject {
+    keys: JsonValue[];
+    [member: string]: JsonValue;
+}
+/** A JWK: its JSON text or a plain object (ADR 0030 §2, C1). */
+export type Jwk = string | JwkObject;
+/** A JWK Set: its JSON text or a plain object. */
+export type JwkSet = string | JwkSetObject;
+/** A JSON object argument (a header, a Claims Set, a JWS/JWE JSON serialization): text or a plain object. */
+export type JsonInput = string | JsonObject;
+/**
+ * JWK Thumbprint hash names (RFC 7638 §3.4, RFC 9278 §4): the nine names the core accepts,
+ * matched exactly (ADR 0054 §8.2). Each hash has its IANA Named Information name (`sha-256`,
+ * canonical, the one the URI carries), the ADR 0030 §4 form (`SHA-256`) and the panva/jose form
+ * (`sha256`). SHA-1 is not offered (ADR 0022). The core parses the name; the facade passes it
+ * as given.
+ */
+export type ThumbprintHash = "sha-256" | "SHA-256" | "sha256" | "sha-384" | "SHA-384" | "sha384" | "sha-512" | "SHA-512" | "sha512";
+/** EC curves `jwkGenerateEc` takes (RFC 7518 §6.2.1.1, RFC 8812 §3.1). */
+export type EcCurve = "P-256" | "P-384" | "P-521" | "secp256k1";
+/** OKP curves `jwkGenerateOkp` takes (RFC 8037 §2). */
+export type OkpCurve = "Ed25519" | "X25519";
+/** Key encodings (ADR 0018 §3): PKCS#8 (RFC 5958), SEC1 (RFC 5915), SPKI (RFC 5280), PKCS#1 (RFC 8017). */
+export type KeyFormat = "pkcs8" | "sec1" | "spki" | "pkcs1";
+/** The JWE JSON serializations (RFC 7516 §7.2.1 general, §7.2.2 flattened). */
+export type JweJsonForm = "general" | "flattened";
+/**
+ * `jwksSelect` criteria (RFC 7517 §4.2, §4.4, §4.5; ADR 0054 §1). Each is optional and passed
+ * to the core as given: `alg` a JWS or JWE key management algorithm, `keyUse` `sig` or `enc`.
+ */
+export interface JwkSelector {
+    kid?: string | undefined;
+    alg?: string | undefined;
+    keyUse?: string | undefined;
+}
+/**
+ * `jwsSignCompact` options (RFC 7515 §7.1). Exactly one of `protectedHeader` and
+ * `protectedB64u`; both or neither fail with `InvalidHeader` in the core. `protectedB64u`
+ * signs over the caller's exact octets (RFC 7515 §5.1 step 3).
+ */
+export interface JwsSignOptions {
+    protectedHeader?: JsonInput | undefined;
+    protectedB64u?: string | undefined;
+    /** Leave the payload out of the output (RFC 7515 Appendix F). */
+    detached?: boolean | undefined;
+}
+/**
+ * One signer of a JWS JSON serialization (RFC 7515 §7.2). A signer may carry only an
+ * unprotected header (RFC 7515 §7.2.1, ADR 0045 §1). This record holds a key: don't log it.
+ */
+export interface JwsSigner {
+    key: Jwk;
+    protectedHeader?: JsonInput | undefined;
+    protectedB64u?: string | undefined;
+    unprotectedHeader?: JsonInput | undefined;
+}
+/** JWS verification options (RFC 7515 §5.2, RFC 8725 §3.1; ADR 0026 §7 limits). */
+export interface JwsVerifyOptions {
+    /** The accepted `alg` names. Required; `none` is never accepted (ADR 0007). */
+    allowedAlgs: readonly string[];
+    /** The detached payload (RFC 7515 Appendix F). */
+    detachedPayload?: Uint8Array | undefined;
+    maxInputLen?: number | undefined;
+    maxSignatures?: number | undefined;
+}
+/** A verified JWS. `unprotectedHeader` is not integrity-protected (ADR 0049 §2). */
+export interface JwsVerified {
+    alg: string;
+    payload: Uint8Array;
+    protectedHeader?: JsonObject;
+    unprotectedHeader?: JsonObject;
+    /** The index of the signature that verified (0 for compact and flattened; ADR 0026 §3). */
+    signatureIndex: number;
+}
+/** One JWE recipient (RFC 7516 §5.1, RFC 7518 §4). This record holds a key: don't log it. */
+export interface JweRecipient {
+    alg: string;
+    key: Jwk;
+    header?: JsonInput | undefined;
+    apu?: Uint8Array | undefined;
+    apv?: Uint8Array | undefined;
+    p2c?: number | undefined;
+    p2sLen?: number | undefined;
+}
+/** JWE encryption options (RFC 7516 §5.1). */
+export interface JweEncryptOptions {
+    enc: string;
+    recipients: readonly JweRecipient[];
+    protectedHeader?: JsonInput | undefined;
+    sharedUnprotectedHeader?: JsonInput | undefined;
+    aad?: Uint8Array | undefined;
+    /** `zip: "DEF"` (RFC 7516 §4.1.3); `UnsupportedAlgorithm` while bindings build without `deflate`. */
+    compress?: boolean | undefined;
+}
+/** JWE decryption options (RFC 7516 §5.2, RFC 8725 §3.1; ADR 0023, 0017 bounds). */
+export interface JweDecryptOptions {
+    /** The accepted key management `alg` names. Required (ADR 0007). */
+    allowedAlgs: readonly string[];
+    /** The accepted content encryption `enc` names. Required (ADR 0007). */
+    allowedEnc: readonly string[];
+    maxPbes2Count?: number | undefined;
+    maxDecompressedLen?: number | undefined;
+    maxInputLen?: number | undefined;
+    maxRecipients?: number | undefined;
+    /** The `crit` extensions the caller understands (RFC 7516 §4.1.13). */
+    understoodCrit?: readonly string[] | undefined;
+}
+/**
+ * A decrypted JWE. Only `protectedHeader` is integrity-protected; `header`,
+ * `sharedUnprotectedHeader` and `recipientHeader` may hold unprotected members (ADR 0050 §3).
+ */
+export interface JweDecrypted {
+    plaintext: Uint8Array;
+    /** The union of the headers used (RFC 7516 §5.2 step 5). */
+    header: JsonObject;
+    protectedHeader?: JsonObject;
+    sharedUnprotectedHeader?: JsonObject;
+    recipientHeader?: JsonObject;
+    aad?: Uint8Array;
+    recipientIndex: number;
+}
+/** JWT signing options (RFC 7519 §7.1; ADR 0027 §8). */
+export interface JwtSignOptions {
+    alg: string;
+    /** The `typ` header; absent gives the core default `JWT`. */
+    typ?: string | undefined;
+    /** Omit `typ` (RFC 7519 §5.1). */
+    omitTyp?: boolean | undefined;
+    /** An RFC 9068 access token (`typ: at+jwt`). */
+    accessToken?: boolean | undefined;
+    /** Extra protected header parameters. */
+    header?: JsonInput | undefined;
+}
+/**
+ * JWT validation options (RFC 7519 §7.2, RFC 8725 §3; ADR 0027 policy, ADR 0029 key sets).
+ * Each field maps to one core `Policy` method; absent or `false` keeps the core default.
+ */
+export interface JwtVerifyOptions {
+    /** The accepted JWS `alg` names. Required (ADR 0007). */
+    allowedAlgs: readonly string[];
+    /**
+     * The current time in whole seconds since the epoch (RFC 7519 §2). When absent the facade
+     * passes `Math.floor(Date.now() / 1000)` (ADR 0028 §4, ADR 0030 §4).
+     */
+    now?: number | undefined;
+    issuers?: readonly string[] | undefined;
+    audiences?: readonly string[] | undefined;
+    subject?: string | undefined;
+    /** Clock skew in seconds (core default 60, at most 600). */
+    leeway?: number | undefined;
+    maxAge?: number | undefined;
+    requiredClaims?: readonly string[] | undefined;
+    allowMissingExp?: boolean | undefined;
+    ignoreAudience?: boolean | undefined;
+    typ?: string | undefined;
+    anyTyp?: boolean | undefined;
+    /**
+     * `"access_token"`: the RFC 9068 §4 JWT access-token profile (`Policy::access_token`), the only
+     * profile, so a typo fails to compile (0013 F04, review N5). The type is the only check: an
+     * untyped caller's other string still reaches the core, which refuses it with
+     * `UnsupportedAlgorithm` (ADR 0030 §4).
+     */
+    profile?: "access_token" | undefined;
+    maxKeyCandidates?: number | undefined;
+    maxInputLen?: number | undefined;
+}
+/** A validated JWT. */
+export interface JwtVerified {
+    claims: JsonObject;
+    header: JsonObject;
+    alg: string;
+    /** The JWK Set position of the key that verified; present only for a key set (ADR 0029 §4). */
+    keyIndex?: number;
+    kid?: string;
+}
+/** A validated nested JWT (ADR 0027 §7). */
+export interface JwtNestedVerified {
+    inner: JwtVerified;
+    outerHeader: JsonObject;
+    recipientIndex: number;
+}

package/facade/types.js

@@ -0,0 +1,14 @@
+/**
+ * The public records of the JS facade: ADR 0030 §3–§4 with camelCase fields (§2).
+ *
+ * - Allow-lists (`allowedAlgs`, `allowedEnc`) are required, with no default (ADR 0007,
+ *   RFC 8725 §3.1); omitting one does not type-check. Plain JS callers that omit one get
+ *   `AlgorithmNotAllowed` from the core, never a default list.
+ * - Every tunable is optional, and absent means the core default (ADR 0030 §3). The facade
+ *   writes no default of its own.
+ * - Algorithm names are the IANA JOSE registry strings, passed as given (ADR 0030 D1).
+ * - JSON values (JWKs, JWK Sets, headers, claims, JWS/JWE JSON serializations) are accepted
+ *   as JSON text or as a plain object (ADR 0030 §2); results come back as parsed objects
+ *   (JWKs, headers, claims) or strings (tokens and JSON serializations).
+ */
+export {};

package/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@polyjose/node`: the shared facade (`bindings/js`, ADR 0031 §1, ADR 0047) bound once to the
+ * napi-rs backend (ADR 0031 §2), re-exported as the package's API (BACKEND.md, "A package entry").
+ *
+ * Every operation of ADR 0030 §4 returns a Promise and runs on the libuv thread pool; a core
+ * failure rejects with a `PolyjoseError` whose `code` is one of `ERROR_CODES` (ADR 0030 §5).
+ * ESM only; CommonJS callers load it with `require()` (require(esm), Node >= 22.12, ADR 0031 §3).
+ */
+export declare const version: () => Promise<string>, errorCodes: () => Promise<string[]>, base64urlEncode: (bytes: Uint8Array) => Promise<string>, base64urlDecode: (text: string) => Promise<Uint8Array>, jwkParse: (jwk: import("./facade/types.js").Jwk) => Promise<import("./facade/types.js").JwkObject>, jwkToPublic: (jwk: import("./facade/types.js").Jwk) => Promise<import("./facade/types.js").JwkObject>, jwkThumbprint: (jwk: import("./facade/types.js").Jwk, hash?: import("./facade/types.js").ThumbprintHash) => Promise<string>, jwkThumbprintUri: (jwk: import("./facade/types.js").Jwk, hash?: import("./facade/types.js").ThumbprintHash) => Promise<string>, jwksSelect: (jwks: import("./facade/types.js").JwkSet, selector?: import("./facade/types.js").JwkSelector) => Promise<import("./facade/types.js").JwkObject>, jwkGenerateOct: (lenBytes: number) => Promise<import("./facade/types.js").JwkObject>, jwkGenerateEc: (crv: import("./facade/types.js").EcCurve) => Promise<import("./facade/types.js").JwkObject>, jwkGenerateOkp: (crv: import("./facade/types.js").OkpCurve) => Promise<import("./facade/types.js").JwkObject>, jwkGenerateForAlg: (alg: string) => Promise<import("./facade/types.js").JwkObject>, jwkFromPem: (pem: string) => Promise<import("./facade/types.js").JwkObject>, jwkFromDer: (der: Uint8Array, format: import("./facade/types.js").KeyFormat) => Promise<import("./facade/types.js").JwkObject>, jwkToPem: (jwk: import("./facade/types.js").Jwk, format: import("./facade/types.js").KeyFormat) => Promise<string>, jwkToDer: (jwk: import("./facade/types.js").Jwk, format: import("./facade/types.js").KeyFormat) => Promise<Uint8Array>, jwsSignCompact: (payload: Uint8Array, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JwsSignOptions) => Promise<string>, jwsSignFlattened: (payload: Uint8Array, signer: import("./facade/types.js").JwsSigner, detached?: boolean) => Promise<string>, jwsSignGeneral: (payload: Uint8Array, signers: readonly import("./facade/types.js").JwsSigner[], detached?: boolean) => Promise<string>, jwsVerifyCompact: (token: string, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JwsVerifyOptions) => Promise<import("./facade/types.js").JwsVerified>, jwsVerifyJson: (jws: import("./facade/types.js").JsonInput, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JwsVerifyOptions) => Promise<import("./facade/types.js").JwsVerified>, jweEncryptCompact: (plaintext: Uint8Array, options: import("./facade/types.js").JweEncryptOptions) => Promise<string>, jweEncryptJson: (plaintext: Uint8Array, options: import("./facade/types.js").JweEncryptOptions, form: import("./facade/types.js").JweJsonForm) => Promise<string>, jweDecryptCompact: (token: string, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JweDecryptOptions) => Promise<import("./facade/types.js").JweDecrypted>, jweDecryptJson: (jwe: import("./facade/types.js").JsonInput, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JweDecryptOptions) => Promise<import("./facade/types.js").JweDecrypted>, jwtSign: (claims: import("./facade/types.js").JsonInput, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JwtSignOptions) => Promise<string>, jwtVerify: (token: string, key: import("./facade/types.js").Jwk, options: import("./facade/types.js").JwtVerifyOptions) => Promise<import("./facade/types.js").JwtVerified>, jwtVerifyWithJwks: (token: string, jwks: import("./facade/types.js").JwkSet, options: import("./facade/types.js").JwtVerifyOptions) => Promise<import("./facade/types.js").JwtVerified>, jwtEncryptNested: (signedJwt: string, options: import("./facade/types.js").JweEncryptOptions) => Promise<string>, jwtDecryptNested: (token: string, decryptKey: import("./facade/types.js").Jwk, decryptOptions: import("./facade/types.js").JweDecryptOptions, key: import("./facade/types.js").Jwk, verifyOptions: import("./facade/types.js").JwtVerifyOptions) => Promise<import("./facade/types.js").JwtNestedVerified>, jwtDecryptNestedWithJwks: (token: string, decryptKey: import("./facade/types.js").Jwk, decryptOptions: import("./facade/types.js").JweDecryptOptions, jwks: import("./facade/types.js").JwkSet, verifyOptions: import("./facade/types.js").JwtVerifyOptions) => Promise<import("./facade/types.js").JwtNestedVerified>, PolyjoseError: typeof import("./facade/api.js").PolyjoseError;
+export { ERROR_CODES } from "./facade/api.js";
+export type * from "./facade/api.js";

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@polyjose/node`: the shared facade (`bindings/js`, ADR 0031 §1, ADR 0047) bound once to the
+ * napi-rs backend (ADR 0031 §2), re-exported as the package's API (BACKEND.md, "A package entry").
+ *
+ * Every operation of ADR 0030 §4 returns a Promise and runs on the libuv thread pool; a core
+ * failure rejects with a `PolyjoseError` whose `code` is one of `ERROR_CODES` (ADR 0030 §5).
+ * ESM only; CommonJS callers load it with `require()` (require(esm), Node >= 22.12, ADR 0031 §3).
+ */
+import { createApi } from "./facade/api.js";
+import { backend } from "./backend.js";
+export const { version, errorCodes, base64urlEncode, base64urlDecode, jwkParse, jwkToPublic, jwkThumbprint, jwkThumbprintUri, jwksSelect, jwkGenerateOct, jwkGenerateEc, jwkGenerateOkp, jwkGenerateForAlg, jwkFromPem, jwkFromDer, jwkToPem, jwkToDer, jwsSignCompact, jwsSignFlattened, jwsSignGeneral, jwsVerifyCompact, jwsVerifyJson, jweEncryptCompact, jweEncryptJson, jweDecryptCompact, jweDecryptJson, jwtSign, jwtVerify, jwtVerifyWithJwks, jwtEncryptNested, jwtDecryptNested, jwtDecryptNestedWithJwks, PolyjoseError, } = createApi(backend);
+export { ERROR_CODES } from "./facade/api.js";