@ractive-ch/tab-mcp 0.2.1 → 0.3.1

package/jwt.d.ts

@@ -0,0 +1,75 @@
+/**
+ * JWT signature checks on WebCrypto, without a JOSE library (DEC-076): the tab
+ * assertion and the provider's ID token. Only asymmetric algorithms, each tied
+ * to its key type; keys come only from a configured JWKS URL, never from the
+ * token's header (`jwk`, `jku`, `x5u` are ignored).
+ */
+/** The accepted algorithms; never `none` or HMAC. */
+export declare const JWT_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+export type JwtAlgorithm = (typeof JWT_ALGORITHMS)[number];
+/** Longest JWT the relay reads. */
+export declare const MAX_JWT_BYTES = 8192;
+export declare class JwtError extends Error {
+    name: string;
+    /** A short reason for the log. */
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+export interface Jwk {
+    kty?: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+    crv?: string;
+    n?: string;
+    e?: string;
+    x?: string;
+    y?: string;
+    [key: string]: unknown;
+}
+export interface DecodedJwt {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    signingInput: Uint8Array<ArrayBuffer>;
+    signature: Uint8Array<ArrayBuffer>;
+}
+/** Split and decode a compact JWS (no signature check). */
+export declare function decodeJwt(token: string): DecodedJwt;
+/** A source of verification keys (a JWKS URL in production). */
+export interface KeySource {
+    /** Keys for `kid`; may fetch again when the kid is unknown. */
+    keys(kid: string | undefined): Promise<Jwk[]>;
+}
+/** Fetch JSON from an operator-configured URL with a timeout and a size limit. */
+export declare function fetchJson(url: string, init?: RequestInit, maxBytes?: number): Promise<unknown>;
+export declare class HttpJsonError extends Error {
+    name: string;
+    readonly status: number;
+    readonly error: string;
+    constructor(status: number, error: string, url: string);
+}
+/**
+ * A JWKS URL, cached 10 minutes, fetched again for an unknown kid at most every
+ * 30 s. After a failed fetch the last good keys are served for up to an hour
+ * (an outage must not refuse every token at once), and the next attempt waits
+ * the same 30 s, so a dead endpoint is not hit (and waited for) on every check.
+ */
+export declare class JwksCache implements KeySource {
+    #private;
+    constructor(url: string | (() => Promise<string>), options?: {
+        now?: () => number;
+    });
+    keys(kid: string | undefined): Promise<Jwk[]>;
+}
+export interface VerifyOptions {
+    /** Required header `typ` (compared exactly), if any. */
+    typ?: string;
+    /** Allowed algorithms; default all of `JWT_ALGORITHMS`. */
+    algorithms?: readonly JwtAlgorithm[];
+}
+/** Check the signature of a compact JWS; returns the decoded token. */
+export declare function verifyJwt(token: string, source: KeySource, options?: VerifyOptions): Promise<DecodedJwt>;
+/** Claim helpers shared by the assertion and ID token checks. */
+export declare function numericDate(payload: Record<string, unknown>, name: string): number | undefined;
+/** `aud` as a list (a string or an array of strings). */
+export declare function audiences(payload: Record<string, unknown>): string[];