@polyjose/node 0.0.0-stage → 0.1.1

package/binding.d.ts

@@ -0,0 +1,469 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+/**
+ * Decodes strict unpadded base64url (RFC 4648 §5, RFC 7515 §2): padding, characters outside the
+ * URL-safe alphabet, whitespace and non-canonical trailing bits reject with `InvalidBase64`.
+ * Resolves to a `Uint8Array`.
+ */
+export declare function base64urlDecode(text: string): Promise<unknown>
+
+/** Encodes `data` as unpadded base64url (RFC 4648 §5, RFC 7515 §2). Resolves to a string. */
+export declare function base64urlEncode(data: Uint8Array): Promise<unknown>
+
+/**
+ * Every stable error code, in the core's order: equal to `polyjose::Error::CODES` (ADR 0030 §5).
+ * Synchronous.
+ */
+export declare function errorCodes(): Array<string>
+
+/**
+ * Decrypts the compact JWE `token` with the JWK `key` under `options.allowedAlgs` and
+ * `options.allowedEnc` (RFC 7516 §5.2, RFC 8725 §3.1). Resolves to `{ plaintext, header,
+ * protectedHeader?, sharedUnprotectedHeader?, recipientHeader?, aad?, recipientIndex }`.
+ */
+export declare function jweDecryptCompact(token: string, key: string, options: JweDecryptOptions): Promise<unknown>
+
+/** A decrypted JWE (RFC 7516 §5.2): the result of `jweDecryptCompact`/`jweDecryptJson`. */
+export interface JweDecrypted {
+  /** The plaintext, copied from the surface's zeroizing buffer (ADR 0030 §7). */
+  plaintext: Uint8Array
+  /**
+   * The JOSE Header used (the union of the header members, RFC 7516 §5.2 step 4), as JSON
+   * text. Only its protected members are integrity-protected (ADR 0050 §3).
+   */
+  header: string
+  /** The JWE Protected Header as JSON text, when present (RFC 7516 §7.2.1). */
+  protectedHeader?: string
+  /** The JWE Shared Unprotected Header as JSON text, when present (RFC 7516 §7.2.1). */
+  sharedUnprotectedHeader?: string
+  /**
+   * The recipient's JWE Per-Recipient Unprotected Header as JSON text, when present
+   * (RFC 7516 §7.2.1).
+   */
+  recipientHeader?: string
+  /** The JWE AAD, when present, copied from the surface's zeroizing buffer (ADR 0050 §4). */
+  aad?: Uint8Array
+  /** The index of the recipient that decrypted (RFC 7516 §7.2.1). */
+  recipientIndex: number
+}
+
+/**
+ * Decrypts the JWE JSON Serialization `jwe` with the JWK `key` (RFC 7516 §5.2, §7.2,
+ * RFC 8725 §3.1). Resolves like [`jwe_decrypt_compact`].
+ */
+export declare function jweDecryptJson(jwe: string, key: string, options: JweDecryptOptions): Promise<unknown>
+
+/**
+ * Options of `jweDecryptCompact`/`jweDecryptJson` and the outer layer of nested JWT decryption
+ * (RFC 7516 §5.2, RFC 8725 §3.1). `allowedAlgs` and `allowedEnc` are required (ADR 0007); the
+ * limits default in the core (ADR 0023, ADR 0050 §2).
+ */
+export interface JweDecryptOptions {
+  /** The key management algorithms the caller accepts (RFC 8725 §3.1). */
+  allowedAlgs: Array<string>
+  /** The content encryption algorithms the caller accepts (RFC 8725 §3.1). */
+  allowedEnc: Array<string>
+  /** The PBES2 iteration budget per token (ADR 0050 §2). */
+  maxPbes2Count?: number
+  /** The largest decompressed plaintext, in octets (ADR 0017). */
+  maxDecompressedLen?: number
+  /** The longest input accepted, in octets. */
+  maxInputLen?: number
+  /** The most recipients a JSON Serialization may carry. */
+  maxRecipients?: number
+  /** Extra `crit` names the caller understands (RFC 7516 §4.1.13, RFC 7515 §4.1.11). */
+  understoodCrit?: Array<string>
+}
+
+/**
+ * Encrypts `plaintext` for the single recipient of `options` into a JWE Compact Serialization
+ * (RFC 7516 §5.1, §7.1). Resolves to the token.
+ */
+export declare function jweEncryptCompact(plaintext: Uint8Array, options: JweEncryptOptions): Promise<unknown>
+
+/**
+ * Encrypts `plaintext` for the recipients of `options` into a JWE JSON Serialization of `form`
+ * (`general`, RFC 7516 §7.2.1, or `flattened`, §7.2.2). Resolves to JSON text.
+ */
+export declare function jweEncryptJson(plaintext: Uint8Array, options: JweEncryptOptions, form: string): Promise<unknown>
+
+/** Options of `jweEncryptCompact`/`jweEncryptJson`/`jwtEncryptNested` (RFC 7516 §5.1). */
+export interface JweEncryptOptions {
+  /** The content encryption algorithm, as registered (RFC 7518 §5.1). */
+  enc: string
+  /** The JWE Protected Header as JSON text (RFC 7516 §7.2.1). */
+  protectedHeader?: string
+  /** The JWE Shared Unprotected Header as JSON text (RFC 7516 §7.2.1). */
+  sharedUnprotectedHeader?: string
+  /** The JWE AAD (RFC 7516 §5.1 step 14). Secret (ADR 0050 §4). */
+  aad?: Uint8Array
+  /** Compress with DEFLATE before encryption (RFC 7516 §4.1.3). Absent: no compression. */
+  compress?: boolean
+  /**
+   * The recipients (exactly one for the compact form, RFC 7516 §7.1). They hold the secret
+   * keys, so they are declared last: see the module docs.
+   */
+  recipients: Array<JweRecipient>
+}
+
+/** One recipient of a JWE (RFC 7516 §7.2.1, RFC 7518 §4). The key is secret (ADR 0030 §7). */
+export interface JweRecipient {
+  /** The key management algorithm, as registered (RFC 7518 §4.1). */
+  alg: string
+  /** The per-recipient JWE Unprotected Header as JSON text (RFC 7516 §7.2.1). */
+  header?: string
+  /** The ECDH-ES `apu` (RFC 7518 §4.6.1.2). */
+  apu?: Uint8Array
+  /** The ECDH-ES `apv` (RFC 7518 §4.6.1.3). */
+  apv?: Uint8Array
+  /** The PBES2 iteration count (RFC 7518 §4.8.1.2). */
+  p2c?: number
+  /** The PBES2 salt input length, in octets (RFC 7518 §4.8.1.1). */
+  p2sLen?: number
+  /** The recipient JWK as JSON text (RFC 7517 §4). Declared last: see the module docs. */
+  key: string
+}
+
+/**
+ * Imports a DER key in `format` (`pkcs8` RFC 5958, `sec1` RFC 5915, `spki` RFC 5280 §4.1,
+ * `pkcs1` RFC 8017 Appendix A.1.1) as a JWK; another format rejects with
+ * `UnsupportedAlgorithm`. The borrowed bytes are copied on the JS thread. Resolves to JWK JSON
+ * text.
+ */
+export declare function jwkFromDer(der: Uint8Array, format: string): Promise<unknown>
+
+/**
+ * Imports a PEM key (`PRIVATE KEY`, `EC PRIVATE KEY`, `PUBLIC KEY`, `RSA PUBLIC KEY`;
+ * RFC 7468 §10, §11, §13) as a JWK. RSA private keys reject with `UnsupportedAlgorithm`
+ * (ADR 0021). Resolves to JWK JSON text.
+ */
+export declare function jwkFromPem(pem: string): Promise<unknown>
+
+/**
+ * Generates an EC private JWK on `crv` (`P-256`, `P-384`, `P-521`, `secp256k1`) (RFC 7518
+ * §6.2, RFC 8812 §3.1); another name rejects with `UnsupportedAlgorithm`. Resolves to JWK JSON
+ * text.
+ */
+export declare function jwkGenerateEc(crv: string): Promise<unknown>
+
+/**
+ * Generates a JWK for the JWS `alg`, JWE `alg` or `enc` name, with `alg` set (RFC 7517 §4.4,
+ * RFC 7518 §3.1, §4.1, §5.1). RSA rejects with `UnsupportedAlgorithm` (ADR 0021). Resolves to
+ * JWK JSON text.
+ */
+export declare function jwkGenerateForAlg(alg: string): Promise<unknown>
+
+/**
+ * Generates an `oct` JWK of `lenBytes` octets (16..=512) from the OS CSPRNG (RFC 7518 §6.4,
+ * ADR 0005); out of range rejects with `InvalidKey`. Resolves to JWK JSON text.
+ */
+export declare function jwkGenerateOct(lenBytes: number): Promise<unknown>
+
+/**
+ * Generates an OKP private JWK on `crv` (`Ed25519`, `X25519`) (RFC 8037 §2); another name
+ * rejects with `UnsupportedAlgorithm`. Resolves to JWK JSON text.
+ */
+export declare function jwkGenerateOkp(crv: string): Promise<unknown>
+
+/**
+ * Validates `jwk` and returns it re-serialized by the core, members in core order (RFC 7517 §4,
+ * RFC 7518 §6, RFC 8037 §2). Resolves to JWK JSON text.
+ */
+export declare function jwkParse(jwk: string): Promise<unknown>
+
+/**
+ * Which member of a JWK Set `jwksSelect` picks; an absent member places no constraint
+ * (RFC 7517 §4.2, §4.4, §4.5, §5).
+ */
+export interface JwkSelector {
+  /** The JWK `kid` to match exactly (RFC 7517 §4.5). */
+  kid?: string
+  /** The algorithm the key must serve, as registered (RFC 7517 §4.4). */
+  alg?: string
+  /** The JWK `use` to match, `sig` or `enc` (RFC 7517 §4.2). JS: `keyUse`. */
+  keyUse?: string
+}
+
+/**
+ * The one member of the JWK Set `jwks` that `selector` picks (RFC 7517 §5, §4.2, §4.4, §4.5),
+ * by the core's `JwkSet::select` rule (ADR 0054 §2, ADR 0057 §1). Each selector member is passed
+ * on unchanged; an absent one places no constraint.
+ *
+ * Rejects, the first error being the outcome (ADR 0054 §4): the set's import errors, then
+ * `UnsupportedAlgorithm` for an `alg` or `keyUse` the core refuses, then `NoMatchingKey` when no
+ * member matches or `MultipleMatchingKeys` when more than one does (ADR 0054 §5). Resolves to
+ * the member's JWK JSON text, which may be private, so it is built from the surface's
+ * `SecretString` (ADR 0030 §7.2).
+ */
+export declare function jwksSelect(jwks: string, selector: JwkSelector): Promise<unknown>
+
+/**
+ * The JWK Thumbprint of `jwk` under `hash`, base64url-encoded (RFC 7638 §3, RFC 9278 §5).
+ *
+ * `hash` is optional and passed on unchanged (ADR 0054 §9; ADR 0030 §1, §3: the adapter has no
+ * default). Absent, `undefined` or `null` is `None`, the core default SHA-256 (RFC 9278 §5). A
+ * name is parsed by the core: `sha-256`, `SHA-256`, `sha256` and the same forms for 384 and 512,
+ * exactly (ADR 0054 §8.2); any other, SHA-1 among them, rejects with `UnsupportedAlgorithm`
+ * (ADR 0022). The JWK is imported first, so an invalid key is reported before an invalid name
+ * (ADR 0057 §2). Resolves to a string of 43, 64 or 86 characters.
+ */
+export declare function jwkThumbprint(jwk: string, hash?: string | undefined | null): Promise<unknown>
+
+/**
+ * The JWK Thumbprint URI of `jwk` under `hash`,
+ * `urn:ietf:params:oauth:jwk-thumbprint:<hash>:<thumbprint>` (RFC 9278 §3), `<hash>` being the
+ * IANA name (`sha-256`, `sha-384`, `sha-512`, RFC 9278 §4) whichever spelling was passed.
+ * `hash` is as for `jwkThumbprint` (ADR 0054 §9, ADR 0057 §2). Resolves to a string.
+ */
+export declare function jwkThumbprintUri(jwk: string, hash?: string | undefined | null): Promise<unknown>
+
+/**
+ * Exports `jwk` as DER in `format` (`pkcs8`, `sec1`, `spki`, `pkcs1`). A private key exports
+ * secret octets (ADR 0030 §7). Resolves to a `Uint8Array`.
+ */
+export declare function jwkToDer(jwk: string, format: string): Promise<unknown>
+
+/**
+ * Exports `jwk` as PEM in `format` (`pkcs8`, `sec1`, `spki`, `pkcs1`; RFC 7468). A private key
+ * exports secret text (ADR 0030 §7). Resolves to a string.
+ */
+export declare function jwkToPem(jwk: string, format: string): Promise<unknown>
+
+/**
+ * The public form of `jwk` (RFC 7517 §4, RFC 7518 §6.2.2, §6.3.2, RFC 8037 §2); an `oct` key
+ * has none and rejects with `UnsupportedAlgorithm`. Resolves to JWK JSON text.
+ */
+export declare function jwkToPublic(jwk: string): Promise<unknown>
+
+/**
+ * Signs `payload` with the JWK `key` into a JWS Compact Serialization (RFC 7515 §5.1, §7.1),
+ * detached on request (RFC 7515 Appendix F). Resolves to the token.
+ */
+export declare function jwsSignCompact(payload: Uint8Array, key: string, options: JwsSignOptions): Promise<unknown>
+
+/**
+ * One signature of a JWS JSON Serialization (RFC 7515 §7.2.1): the key and its headers, with
+ * the `JwsSignOptions` header rule (ADR 0030 §4). The key is secret (ADR 0030 §7).
+ */
+export interface JwsSigner {
+  /** The JWS Protected Header as JSON text (RFC 7515 §7.2.1). */
+  protectedHeader?: string
+  /** The JWS Protected Header already base64url-encoded (RFC 7515 §7.2.1). */
+  protectedB64u?: string
+  /** The JWS Unprotected Header as JSON text (RFC 7515 §7.2.1). */
+  unprotectedHeader?: string
+  /** The signing JWK as JSON text (RFC 7517 §4). Declared last: see the module docs. */
+  key: string
+}
+
+/**
+ * Signs `payload` for one signer into a flattened JWS JSON Serialization (RFC 7515 §7.2.2).
+ * Resolves to JSON text.
+ */
+export declare function jwsSignFlattened(payload: Uint8Array, signer: JwsSigner, detached: boolean): Promise<unknown>
+
+/**
+ * Signs `payload` for every signer into a general JWS JSON Serialization (RFC 7515 §7.2.1).
+ * Resolves to JSON text.
+ */
+export declare function jwsSignGeneral(payload: Uint8Array, signers: Array<JwsSigner>, detached: boolean): Promise<unknown>
+
+/**
+ * Options of `jwsSignCompact` (RFC 7515 §5.1, §7.1). Exactly one of `protectedHeader` and
+ * `protectedB64u`; both or neither reject with `InvalidHeader` (ADR 0030 §4).
+ */
+export interface JwsSignOptions {
+  /** The JWS Protected Header as JSON text (RFC 7515 §5.1 step 3). */
+  protectedHeader?: string
+  /**
+   * The JWS Protected Header already base64url-encoded, signed over as given (RFC 7515 §5.1
+   * step 3, Appendix A.1).
+   */
+  protectedB64u?: string
+  /** Leave the payload out of the output (RFC 7515 Appendix F). Absent: not detached. */
+  detached?: boolean
+}
+
+/** A verified JWS (RFC 7515 §5.2): the result of `jwsVerifyCompact`/`jwsVerifyJson`. */
+export interface JwsVerified {
+  /** The algorithm that verified (RFC 7515 §4.1.1). */
+  alg: string
+  /** The payload octets, copied from the surface's zeroizing buffer (ADR 0049 §4). */
+  payload: Uint8Array
+  /** The JWS Protected Header as JSON text, when present (RFC 7515 §4). */
+  protectedHeader?: string
+  /**
+   * The JWS Unprotected Header as JSON text, when present; not integrity-protected
+   * (RFC 7515 §7.2.1, ADR 0049 §2).
+   */
+  unprotectedHeader?: string
+  /** The index of the signature that verified (RFC 7515 §7.2.1). */
+  signatureIndex: number
+}
+
+/**
+ * Verifies the compact JWS `token` with the JWK `key` under `options.allowedAlgs` (RFC 7515
+ * §5.2, RFC 8725 §3.1). Resolves to `{ alg, payload, protectedHeader?, unprotectedHeader?,
+ * signatureIndex }`.
+ */
+export declare function jwsVerifyCompact(token: string, key: string, options: JwsVerifyOptions): Promise<unknown>
+
+/**
+ * Verifies the JWS JSON Serialization `jws` (flattened or general) with the JWK `key` under
+ * `options.allowedAlgs` (RFC 7515 §5.2, §7.2, RFC 8725 §3.1). Resolves like
+ * [`jws_verify_compact`].
+ */
+export declare function jwsVerifyJson(jws: string, key: string, options: JwsVerifyOptions): Promise<unknown>
+
+/**
+ * Options of `jwsVerifyCompact`/`jwsVerifyJson` (RFC 7515 §5.2, RFC 8725 §3.1). `allowedAlgs`
+ * is required (ADR 0007); the limits default in the core (ADR 0026 §7).
+ */
+export interface JwsVerifyOptions {
+  /**
+   * The algorithms the caller accepts (RFC 8725 §3.1). Empty rejects with
+   * `AlgorithmNotAllowed`.
+   */
+  allowedAlgs: Array<string>
+  /** The payload of a detached JWS (RFC 7515 Appendix F). Secret (ADR 0030 §7). */
+  detachedPayload?: Uint8Array
+  /** The longest input accepted, in octets (ADR 0026 §7). */
+  maxInputLen?: number
+  /** The most signatures a JSON Serialization may carry (ADR 0026 §7). */
+  maxSignatures?: number
+}
+
+/**
+ * Decrypts the nested JWT `token` with `decryptKey` under `decryptOptions`, then verifies the
+ * inner JWT with `key` under `verifyOptions` (RFC 7519 §7.2 step 8, RFC 8725 §3). Resolves to
+ * `{ inner, outerHeader, recipientIndex }`.
+ */
+export declare function jwtDecryptNested(token: string, decryptKey: string, decryptOptions: JweDecryptOptions, key: string, verifyOptions: JwtVerifyOptions): Promise<unknown>
+
+/**
+ * Like [`jwt_decrypt_nested`], verifying the inner JWT with a member of the JWK Set `jwks`
+ * (ADR 0029).
+ */
+export declare function jwtDecryptNestedWithJwks(token: string, decryptKey: string, decryptOptions: JweDecryptOptions, jwks: string, verifyOptions: JwtVerifyOptions): Promise<unknown>
+
+/**
+ * Encrypts the signed JWT `signedJwt` into a compact JWE for the single recipient of `options`,
+ * `cty: "JWT"` set by the core (RFC 7519 §5.2, §7.1 step 5). Resolves to the token.
+ */
+export declare function jwtEncryptNested(signedJwt: string, options: JweEncryptOptions): Promise<unknown>
+
+/**
+ * A verified nested JWT (RFC 7519 §5.2, §7.2 step 8): the result of `jwtDecryptNested` and
+ * `jwtDecryptNestedWithJwks`.
+ */
+export interface JwtNestedVerified {
+  /** The inner, signed JWT. */
+  inner: JwtVerified
+  /** The outer JWE's JOSE Header as JSON text (RFC 7516 §5.2). */
+  outerHeader: string
+  /** The index of the JWE recipient that decrypted (RFC 7516 §7.2.1). */
+  recipientIndex: number
+}
+
+/**
+ * Signs the JWT Claims Set `claims` (JSON text) with the JWK `key` (RFC 7519 §7.1). RS*\/PS*
+ * signing rejects with `UnsupportedAlgorithm` (ADR 0021). Resolves to the token.
+ */
+export declare function jwtSign(claims: string, key: string, options: JwtSignOptions): Promise<unknown>
+
+/**
+ * Options of `jwtSign` (RFC 7519 §7.1, RFC 9068 §2.1). `typ` together with `omitTyp` or
+ * `accessToken` rejects with `InvalidHeader` (ADR 0030 §4).
+ */
+export interface JwtSignOptions {
+  /** The signing algorithm, as registered (RFC 7518 §3.1). */
+  alg: string
+  /** The `typ` header; absent: the core default `JWT` (RFC 7519 §5.1). */
+  typ?: string
+  /** Write no `typ` header. Absent: not set. */
+  omitTyp?: boolean
+  /** Issue an RFC 9068 access token (`typ: at+jwt`, RFC 9068 §2.1). Absent: not set. */
+  accessToken?: boolean
+  /** Extra JWS Protected Header members as a JSON object text (RFC 7515 §4). */
+  header?: string
+}
+
+/** A verified JWT (RFC 7519 §7.2): the result of `jwtVerify`/`jwtVerifyWithJwks`. */
+export interface JwtVerified {
+  /**
+   * The claims as the core's JSON serialization (ADR 0027 §1). Plain in the API (ADR 0058,
+   * owner decision 2); the adapter's copy is wiped all the same (see the module docs).
+   */
+  claims: string
+  /** The JOSE Header as JSON text (RFC 7519 §5). */
+  header: string
+  /** The algorithm that verified (RFC 7515 §4.1.1). */
+  alg: string
+  /** The index of the JWK Set member that verified, for a set (ADR 0029). */
+  keyIndex?: number
+  /** The `kid` of the key that verified, when it has one (RFC 7517 §4.5). */
+  kid?: string
+}
+
+/**
+ * Verifies the signed JWT `token` with the JWK `key` and validates its claims under `options`
+ * (RFC 7519 §7.2, RFC 8725 §3; ADR 0027 §9 fixes the error order). Resolves to `{ claims,
+ * header, alg, keyIndex?, kid? }`.
+ */
+export declare function jwtVerify(token: string, key: string, options: JwtVerifyOptions): Promise<unknown>
+
+/**
+ * Options of the JWT verify operations (RFC 7519 §7.2, RFC 8725 §3, RFC 9068 §4). Each field
+ * maps to one core `Policy` method, and an absent one calls nothing (ADR 0030 §4, ADR 0027).
+ * The facade always passes `now` (ADR 0028 §4); an absent one reaches the surface as `None`.
+ */
+export interface JwtVerifyOptions {
+  /** The algorithms the caller accepts (RFC 8725 §3.1). */
+  allowedAlgs: Array<string>
+  /** The verification time, whole seconds since the epoch (RFC 7519 §2, ADR 0028). */
+  now?: number
+  /** The accepted `iss` values (RFC 7519 §4.1.1). */
+  issuers?: Array<string>
+  /** The accepted `aud` values (RFC 7519 §4.1.3). */
+  audiences?: Array<string>
+  /** The required `sub` (RFC 7519 §4.1.2). */
+  subject?: string
+  /** Clock skew allowance in seconds (RFC 7519 §4.1.4, §4.1.5). */
+  leeway?: number
+  /** The oldest `iat` accepted, in seconds (RFC 7519 §4.1.6). */
+  maxAge?: number
+  /** Claims that must be present (RFC 7519 §4). */
+  requiredClaims?: Array<string>
+  /** Accept a token without `exp` (RFC 7519 §4.1.4). Absent: not set. */
+  allowMissingExp?: boolean
+  /** Do not check `aud` (RFC 7519 §4.1.3). Absent: not set. */
+  ignoreAudience?: boolean
+  /** The expected `typ` header (RFC 8725 §3.11). */
+  typ?: string
+  /** Accept any `typ` (RFC 8725 §3.11). Absent: not set. */
+  anyTyp?: boolean
+  /** A validation profile, `access_token` (RFC 9068 §4). */
+  profile?: string
+  /** The most JWK Set members tried (ADR 0029). */
+  maxKeyCandidates?: number
+  /** The longest token accepted, in octets. */
+  maxInputLen?: number
+}
+
+/**
+ * Verifies the signed JWT `token` with a member of the JWK Set `jwks` (RFC 7517 §5, ADR 0029;
+ * no member verifying rejects with `NoMatchingKey`). Resolves like [`jwt_verify`].
+ */
+export declare function jwtVerifyWithJwks(token: string, jwks: string, options: JwtVerifyOptions): Promise<unknown>
+
+/** The polyjose crate version, e.g. `0.1.0` (ADR 0030 §4). Synchronous. */
+export declare function version(): string

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;