@polyjose/node 0.0.0-stage → 0.1.2

package/facade/backend.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The backend contract: what each native layer (`@polyjose/node`'s napi-rs loader,
+ * `@polyjose/wasm`'s wasm-bindgen glue) exports for the facade (ADR 0031 §1). Documented in
+ * `bindings/js/BACKEND.md`.
+ *
+ * - Every ADR 0030 §4 operation, camelCase, with the ADR's argument order.
+ * - JSON-valued arguments and result fields are JSON **text**; the facade does the
+ *   object↔JSON idiom (ADR 0030 §2). Rust parses with the core's strict I-JSON parser.
+ * - Records are plain objects with camelCase fields. The facade only ever passes fields it has
+ *   validated; an absent optional field is **left out** (never `undefined` or `null`: napi
+ *   throws on `null`, research §3).
+ * - Integers are already range-checked (u32 sizes and counts, safe-integer `now`), because
+ *   wasm-bindgen coerces `-1` to `4294967295` (research §3).
+ * - Results may be returned directly or as a Promise (napi `AsyncTask`). Errors are thrown or
+ *   rejected with an object whose `code` is one of `errorCodes()` (ADR 0030 §5).
+ * - `version()` and `errorCodes()` are synchronous; `ready()` is optional and awaited once,
+ *   lazily, before the first call (WASM initialisation without top-level await).
+ */
+/** A value or a Promise of it. */
+export type MaybePromise<T> = T | Promise<T>;
+export interface BackendJwkSelector {
+    kid?: string;
+    alg?: string;
+    keyUse?: string;
+}
+export interface BackendJwsSignOptions {
+    protectedHeader?: string;
+    protectedB64u?: string;
+    detached?: boolean;
+}
+export interface BackendJwsSigner {
+    key: string;
+    protectedHeader?: string;
+    protectedB64u?: string;
+    unprotectedHeader?: string;
+}
+export interface BackendJwsVerifyOptions {
+    allowedAlgs: string[];
+    detachedPayload?: Uint8Array;
+    maxInputLen?: number;
+    maxSignatures?: number;
+}
+export interface BackendJwsVerified {
+    alg: string;
+    payload: Uint8Array;
+    protectedHeader?: string | null | undefined;
+    unprotectedHeader?: string | null | undefined;
+    signatureIndex: number;
+}
+export interface BackendJweRecipient {
+    alg: string;
+    key: string;
+    header?: string;
+    apu?: Uint8Array;
+    apv?: Uint8Array;
+    p2c?: number;
+    p2sLen?: number;
+}
+export interface BackendJweEncryptOptions {
+    enc: string;
+    recipients: BackendJweRecipient[];
+    protectedHeader?: string;
+    sharedUnprotectedHeader?: string;
+    aad?: Uint8Array;
+    compress?: boolean;
+}
+export interface BackendJweDecryptOptions {
+    allowedAlgs: string[];
+    allowedEnc: string[];
+    maxPbes2Count?: number;
+    maxDecompressedLen?: number;
+    maxInputLen?: number;
+    maxRecipients?: number;
+    understoodCrit?: string[];
+}
+export interface BackendJweDecrypted {
+    plaintext: Uint8Array;
+    header: string;
+    protectedHeader?: string | null | undefined;
+    sharedUnprotectedHeader?: string | null | undefined;
+    recipientHeader?: string | null | undefined;
+    aad?: Uint8Array | null | undefined;
+    recipientIndex: number;
+}
+export interface BackendJwtSignOptions {
+    alg: string;
+    typ?: string;
+    omitTyp?: boolean;
+    accessToken?: boolean;
+    header?: string;
+}
+/** `now` is always present: the facade reads the JS clock when the caller gives none (ADR 0030 §4). */
+export interface BackendJwtVerifyOptions {
+    allowedAlgs: string[];
+    now: number;
+    issuers?: string[];
+    audiences?: string[];
+    subject?: string;
+    leeway?: number;
+    maxAge?: number;
+    requiredClaims?: string[];
+    allowMissingExp?: boolean;
+    ignoreAudience?: boolean;
+    typ?: string;
+    anyTyp?: boolean;
+    profile?: string;
+    maxKeyCandidates?: number;
+    maxInputLen?: number;
+}
+export interface BackendJwtVerified {
+    claims: string;
+    header: string;
+    alg: string;
+    keyIndex?: number | null | undefined;
+    kid?: string | null | undefined;
+}
+export interface BackendJwtNestedVerified {
+    inner: BackendJwtVerified;
+    outerHeader: string;
+    recipientIndex: number;
+}
+/** The functions a native layer provides (BACKEND.md). */
+export interface Backend {
+    /** Optional one-time initialisation, awaited lazily before the first call. */
+    ready?(): Promise<void>;
+    version(): string;
+    errorCodes(): readonly string[];
+    base64urlEncode(bytes: Uint8Array): MaybePromise<string>;
+    base64urlDecode(text: string): MaybePromise<Uint8Array>;
+    jwkParse(jwk: string): MaybePromise<string>;
+    jwkToPublic(jwk: string): MaybePromise<string>;
+    /** `hash` is `undefined` when the caller gave none: the core default, SHA-256 (ADR 0054 §9). */
+    jwkThumbprint(jwk: string, hash: string | undefined): MaybePromise<string>;
+    jwkThumbprintUri(jwk: string, hash: string | undefined): MaybePromise<string>;
+    jwksSelect(jwks: string, selector: BackendJwkSelector): MaybePromise<string>;
+    jwkGenerateOct(lenBytes: number): MaybePromise<string>;
+    jwkGenerateEc(crv: string): MaybePromise<string>;
+    jwkGenerateOkp(crv: string): MaybePromise<string>;
+    jwkGenerateForAlg(alg: string): MaybePromise<string>;
+    jwkFromPem(pem: string): MaybePromise<string>;
+    jwkFromDer(der: Uint8Array, format: string): MaybePromise<string>;
+    jwkToPem(jwk: string, format: string): MaybePromise<string>;
+    jwkToDer(jwk: string, format: string): MaybePromise<Uint8Array>;
+    jwsSignCompact(payload: Uint8Array, key: string, options: BackendJwsSignOptions): MaybePromise<string>;
+    jwsSignFlattened(payload: Uint8Array, signer: BackendJwsSigner, detached: boolean): MaybePromise<string>;
+    jwsSignGeneral(payload: Uint8Array, signers: BackendJwsSigner[], detached: boolean): MaybePromise<string>;
+    jwsVerifyCompact(token: string, key: string, options: BackendJwsVerifyOptions): MaybePromise<BackendJwsVerified>;
+    jwsVerifyJson(jws: string, key: string, options: BackendJwsVerifyOptions): MaybePromise<BackendJwsVerified>;
+    jweEncryptCompact(plaintext: Uint8Array, options: BackendJweEncryptOptions): MaybePromise<string>;
+    jweEncryptJson(plaintext: Uint8Array, options: BackendJweEncryptOptions, form: string): MaybePromise<string>;
+    jweDecryptCompact(token: string, key: string, options: BackendJweDecryptOptions): MaybePromise<BackendJweDecrypted>;
+    jweDecryptJson(jwe: string, key: string, options: BackendJweDecryptOptions): MaybePromise<BackendJweDecrypted>;
+    jwtSign(claims: string, key: string, options: BackendJwtSignOptions): MaybePromise<string>;
+    jwtVerify(token: string, key: string, options: BackendJwtVerifyOptions): MaybePromise<BackendJwtVerified>;
+    jwtVerifyWithJwks(token: string, jwks: string, options: BackendJwtVerifyOptions): MaybePromise<BackendJwtVerified>;
+    jwtEncryptNested(signedJwt: string, options: BackendJweEncryptOptions): MaybePromise<string>;
+    jwtDecryptNested(token: string, decryptKey: string, decryptOptions: BackendJweDecryptOptions, key: string, verifyOptions: BackendJwtVerifyOptions): MaybePromise<BackendJwtNestedVerified>;
+    jwtDecryptNestedWithJwks(token: string, decryptKey: string, decryptOptions: BackendJweDecryptOptions, jwks: string, verifyOptions: BackendJwtVerifyOptions): MaybePromise<BackendJwtNestedVerified>;
+}

package/facade/backend.js

@@ -0,0 +1,19 @@
+/**
+ * The backend contract: what each native layer (`@polyjose/node`'s napi-rs loader,
+ * `@polyjose/wasm`'s wasm-bindgen glue) exports for the facade (ADR 0031 §1). Documented in
+ * `bindings/js/BACKEND.md`.
+ *
+ * - Every ADR 0030 §4 operation, camelCase, with the ADR's argument order.
+ * - JSON-valued arguments and result fields are JSON **text**; the facade does the
+ *   object↔JSON idiom (ADR 0030 §2). Rust parses with the core's strict I-JSON parser.
+ * - Records are plain objects with camelCase fields. The facade only ever passes fields it has
+ *   validated; an absent optional field is **left out** (never `undefined` or `null`: napi
+ *   throws on `null`, research §3).
+ * - Integers are already range-checked (u32 sizes and counts, safe-integer `now`), because
+ *   wasm-bindgen coerces `-1` to `4294967295` (research §3).
+ * - Results may be returned directly or as a Promise (napi `AsyncTask`). Errors are thrown or
+ *   rejected with an object whose `code` is one of `errorCodes()` (ADR 0030 §5).
+ * - `version()` and `errorCodes()` are synchronous; `ready()` is optional and awaited once,
+ *   lazily, before the first call (WASM initialisation without top-level await).
+ */
+export {};

package/facade/error-codes.d.ts

@@ -0,0 +1,4 @@
+/** The stable error codes of every polyjose binding, in the core's order (ADR 0030 §5). */
+export declare const ERROR_CODES: readonly ["InvalidBase64", "InvalidJson", "InvalidHeader", "UnsupportedAlgorithm", "AlgorithmNotAllowed", "InvalidKey", "KeyAlgorithmMismatch", "InvalidSignature", "DecryptionFailed", "UnknownCritical", "TokenExpired", "TokenNotYetValid", "InvalidClaim", "RandomnessUnavailable", "InvalidFormat", "NoMatchingKey", "MultipleMatchingKeys"];
+/** One stable error code: `PolyjoseError.code` is always one of these (ADR 0030 §5). */
+export type ErrorCode = (typeof ERROR_CODES)[number];

package/facade/error-codes.js

@@ -0,0 +1,22 @@
+// GENERATED by tools/gen-error-codes.ts from crates/polyjose/src/error.rs (Error::CODES).
+// Do not edit: `npm run build` (or bindings/js/test.sh) regenerates it (ADR 0047).
+/** The stable error codes of every polyjose binding, in the core's order (ADR 0030 §5). */
+export const ERROR_CODES = [
+    "InvalidBase64",
+    "InvalidJson",
+    "InvalidHeader",
+    "UnsupportedAlgorithm",
+    "AlgorithmNotAllowed",
+    "InvalidKey",
+    "KeyAlgorithmMismatch",
+    "InvalidSignature",
+    "DecryptionFailed",
+    "UnknownCritical",
+    "TokenExpired",
+    "TokenNotYetValid",
+    "InvalidClaim",
+    "RandomnessUnavailable",
+    "InvalidFormat",
+    "NoMatchingKey",
+    "MultipleMatchingKeys",
+];

package/facade/normalize.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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").
+ */
+import type { JsonObject } from "./types.js";
+/** `null` and `undefined` both mean "absent" (napi throws on `null`, research §3). */
+export declare function isAbsent(v: unknown): v is null | undefined;
+/** A `Uint8Array`, including a Node `Buffer` (a subclass). */
+export declare function isUint8Array(v: unknown): v is Uint8Array;
+/** An object literal (or `Object.create(null)`), not an array or class instance. */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function str(v: unknown, at: string): string;
+export declare function optStr(v: unknown, at: string): string | undefined;
+/**
+ * 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 declare function bytes(v: unknown, at: string, copies: Uint8Array[]): Uint8Array;
+export declare function optBytes(v: unknown, at: string, copies: Uint8Array[]): Uint8Array | undefined;
+/**
+ * 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 declare function wipe(copies: readonly Uint8Array[]): void;
+export declare function bool(v: unknown, at: string): boolean;
+export declare function optBool(v: unknown, at: string): boolean | undefined;
+/**
+ * A size or count: an integer in 0..=2^32−1. Checked here because wasm-bindgen would coerce
+ * `-1` to `4294967295` (research §3).
+ */
+export declare function u32(v: unknown, at: string): number;
+export declare function optU32(v: unknown, at: string): number | undefined;
+/**
+ * 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 declare function optSeconds(v: unknown, at: string): number | undefined;
+/**
+ * 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 declare function json(v: unknown, at: string): string;
+export declare function optJson(v: unknown, at: string): string | undefined;
+/**
+ * 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 declare function list<T>(v: unknown, at: string, item: (x: unknown, at: string) => T): T[];
+export declare function strList(v: unknown, at: string): string[];
+export declare function optStrList(v: unknown, at: string): string[] | undefined;
+/**
+ * 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 declare function allowList(v: unknown, at: string): string[];
+/**
+ * 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 declare function bare<T extends object>(init: T): T;
+/**
+ * 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 declare function record(v: unknown, at: string, members: readonly string[]): Record<string, unknown>;
+/**
+ * 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 declare function define<T extends object, K extends keyof T>(out: T, key: K, value: T[K]): void;
+/** {@link define}s `out[key]` only when `value` is present, so absent optional fields are left out. */
+export declare function put<T extends object, K extends keyof T>(out: T, key: K, value: T[K] | undefined): void;
+/**
+ * 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 declare function append<T>(out: T[], value: T): void;
+export declare function outStr(v: unknown, at: string): string;
+export declare function outBytes(v: unknown, at: string): Uint8Array;
+export declare function outIndex(v: unknown, at: string): number;
+/**
+ * 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 declare function outList<T>(v: unknown, at: string, item: (x: unknown, at: string) => T): T[];
+/** JSON text the core serialized, parsed to an object (ADR 0030 §2: JWKs, headers, claims). */
+export declare function outObject(v: unknown, at: string): JsonObject;
+/**
+ * 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 declare function member(v: unknown, name: string, at: string): unknown;