@idpartners/client-attestation-sdk 0.0.0-stage → 0.2.0

package/dist/validator/config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Validator configuration.
+ */
+import type { JSONWebKeySet } from "jose";
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. */
+export declare const DEFAULT_ALGORITHMS: readonly string[];
+/** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
+export declare const DEFAULT_TOKEN_TYPES: readonly string[];
+/** How the resource server authenticates to the AS when introspecting. */
+export type IntrospectionAuthMethod = "client_secret_basic" | "client_secret_post";
+/**
+ * RFC 7662 introspection endpoint + client credentials (the resource server authenticating to the AS).
+ */
+export interface IntrospectionConfig {
+    endpoint: string;
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to `"client_secret_basic"`. */
+    authMethod?: IntrospectionAuthMethod;
+}
+/**
+ * What this resource server accepts: the trusted issuer, its own audience identifier(s), the signing
+ * keys (static `jwks` or a `jwksUri` to fetch), required scopes, accepted algorithms, clock leeway,
+ * and optional introspection.
+ *
+ * `issuer` and `audiences` are required: a validator that skips either accepts tokens minted for someone
+ * else. `acceptedTokenTypes` is checked against the JWT `typ` header when the token carries one, so an ID
+ * token can't stand in for an access token. Pass `null` to turn that check off for an issuer that stamps
+ * something other than `at+jwt`.
+ */
+export interface ValidatorConfig {
+    issuer: string;
+    audiences: string | string[];
+    jwks?: JSONWebKeySet;
+    jwksUri?: string;
+    requiredScopes?: string[];
+    /** Defaults to {@link DEFAULT_ALGORITHMS}. */
+    acceptedAlgorithms?: string[];
+    /** Clock skew allowed on `exp` / `nbf` / `iat`, in seconds. Defaults to 60. */
+    leewaySeconds?: number;
+    introspection?: IntrospectionConfig;
+    /** Defaults to {@link DEFAULT_TOKEN_TYPES}; `null` disables the `typ` check. */
+    acceptedTokenTypes?: string[] | null;
+}
+/** A {@link ValidatorConfig} with every optional field defaulted. */
+export interface ResolvedConfig {
+    issuer: string;
+    audiences: string[];
+    jwks?: JSONWebKeySet;
+    jwksUri?: string;
+    requiredScopes: string[];
+    acceptedAlgorithms: string[];
+    leewaySeconds: number;
+    introspection?: IntrospectionConfig;
+    /** Normalised with {@link normaliseType}; `null` when the check is off. */
+    acceptedTokenTypes: string[] | null;
+}
+/**
+ * Compare JOSE `typ` values the way RFC 7515 section 4.1.9 says to: case-insensitively, with an optional
+ * `application/` prefix.
+ */
+export declare function normaliseType(value: string): string;
+/** Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`). */
+export declare function resolveConfig(config: ValidatorConfig): ResolvedConfig;

package/dist/validator/config.js

@@ -0,0 +1,44 @@
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. */
+export const DEFAULT_ALGORITHMS = [
+    "ES256",
+    "ES384",
+    "ES512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
+];
+/** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
+export const DEFAULT_TOKEN_TYPES = ["at+jwt"];
+/**
+ * Compare JOSE `typ` values the way RFC 7515 section 4.1.9 says to: case-insensitively, with an optional
+ * `application/` prefix.
+ */
+export function normaliseType(value) {
+    const lower = value.toLowerCase();
+    return lower.startsWith("application/") ? lower.slice("application/".length) : lower;
+}
+/** Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`). */
+export function resolveConfig(config) {
+    if (!config.issuer) {
+        throw new Error("issuer is required");
+    }
+    const audiences = typeof config.audiences === "string" ? [config.audiences] : [...(config.audiences ?? [])];
+    if (audiences.length === 0) {
+        throw new Error("at least one audience is required");
+    }
+    const types = config.acceptedTokenTypes === undefined ? DEFAULT_TOKEN_TYPES : config.acceptedTokenTypes;
+    return {
+        issuer: config.issuer,
+        audiences,
+        jwks: config.jwks,
+        jwksUri: config.jwksUri,
+        requiredScopes: [...(config.requiredScopes ?? [])],
+        acceptedAlgorithms: [...(config.acceptedAlgorithms ?? DEFAULT_ALGORITHMS)],
+        leewaySeconds: config.leewaySeconds ?? 60,
+        introspection: config.introspection,
+        acceptedTokenTypes: types === null ? null : types.map(normaliseType),
+    };
+}

package/dist/validator/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stable validation outcome codes, shared across the Python / TypeScript / Go ports so their verdicts
+ * can be compared directly.
+ */
+export declare const VALID = "valid";
+export declare const EXPIRED = "expired";
+export declare const NOT_YET_VALID = "not_yet_valid";
+export declare const INVALID_SIGNATURE = "invalid_signature";
+export declare const INVALID_ISSUER = "invalid_issuer";
+export declare const INVALID_AUDIENCE = "invalid_audience";
+export declare const INSUFFICIENT_SCOPE = "insufficient_scope";
+export declare const INVALID_TOKEN = "invalid_token";
+export declare const UNSUPPORTED_ALGORITHM = "unsupported_algorithm";
+export declare const KEY_NOT_FOUND = "key_not_found";
+export declare const INACTIVE = "inactive";
+export declare const MISSING_EXPIRY = "missing_expiry";
+export declare const ISSUED_IN_FUTURE = "issued_in_future";
+export declare const INVALID_TOKEN_TYPE = "invalid_token_type";
+/** Every stable error code a validation can report. */
+export type ValidationError = typeof EXPIRED | typeof NOT_YET_VALID | typeof INVALID_SIGNATURE | typeof INVALID_ISSUER | typeof INVALID_AUDIENCE | typeof INSUFFICIENT_SCOPE | typeof INVALID_TOKEN | typeof UNSUPPORTED_ALGORITHM | typeof KEY_NOT_FOUND | typeof INACTIVE | typeof MISSING_EXPIRY | typeof ISSUED_IN_FUTURE | typeof INVALID_TOKEN_TYPE;

package/dist/validator/errors.js

@@ -0,0 +1,18 @@
+/**
+ * Stable validation outcome codes, shared across the Python / TypeScript / Go ports so their verdicts
+ * can be compared directly.
+ */
+export const VALID = "valid";
+export const EXPIRED = "expired";
+export const NOT_YET_VALID = "not_yet_valid";
+export const INVALID_SIGNATURE = "invalid_signature";
+export const INVALID_ISSUER = "invalid_issuer";
+export const INVALID_AUDIENCE = "invalid_audience";
+export const INSUFFICIENT_SCOPE = "insufficient_scope";
+export const INVALID_TOKEN = "invalid_token";
+export const UNSUPPORTED_ALGORITHM = "unsupported_algorithm";
+export const KEY_NOT_FOUND = "key_not_found";
+export const INACTIVE = "inactive";
+export const MISSING_EXPIRY = "missing_expiry";
+export const ISSUED_IN_FUTURE = "issued_in_future";
+export const INVALID_TOKEN_TYPE = "invalid_token_type";

package/dist/validator/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resource-server access-token validation: JWT signature + scope/audience checks in a fixed,
+ * cross-language error-precedence order, plus optional RFC 7662 introspection.
+ *
+ * This is the validator counterpart to the client-side builder SDK, and mirrors the Python
+ * `token_validator` package so every port reports the same verdict for the shared vectors.
+ */
+export { AccessTokenValidator } from "./validator.js";
+export type { HttpPost, Claims, ValidatorOptions } from "./validator.js";
+export type { HttpGet } from "./jwks.js";
+export { resolveConfig, DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export type { ValidatorConfig, ResolvedConfig, IntrospectionConfig, IntrospectionAuthMethod, } from "./config.js";
+export type { ValidationResult } from "./result.js";
+export type { ValidationError } from "./errors.js";
+export * as errors from "./errors.js";
+export { ProtectedResource, bearerToken } from "./resource.js";
+export type { ProtectedResourceMetadata, AuthDecision } from "./resource.js";
+export declare const VALIDATOR_VERSION = "0.2.0";

package/dist/validator/index.js

@@ -0,0 +1,12 @@
+/**
+ * Resource-server access-token validation: JWT signature + scope/audience checks in a fixed,
+ * cross-language error-precedence order, plus optional RFC 7662 introspection.
+ *
+ * This is the validator counterpart to the client-side builder SDK, and mirrors the Python
+ * `token_validator` package so every port reports the same verdict for the shared vectors.
+ */
+export { AccessTokenValidator } from "./validator.js";
+export { resolveConfig, DEFAULT_ALGORITHMS, DEFAULT_TOKEN_TYPES } from "./config.js";
+export * as errors from "./errors.js";
+export { ProtectedResource, bearerToken } from "./resource.js";
+export const VALIDATOR_VERSION = "0.2.0";

package/dist/validator/jwks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resolves issuer signing keys — from a static JWKS or a `jwksUri` (fetched and cached, refreshed on an
+ * unknown `kid` and when the cached set grows old).
+ *
+ * A `jwksUri` provider never fetches more than once per `minRefreshSeconds`, however many unknown `kid`
+ * values it is shown, and concurrent misses share one fetch. Without that, a stream of tokens with made-up
+ * `kid` values turns every request into a request to the issuer.
+ */
+import { type CryptoKey, type JSONWebKeySet } from "jose";
+/** An imported verification key, as returned by jose's `importJWK`. */
+export type VerificationKey = CryptoKey | Uint8Array;
+/** Fetch a URL and return its body text. Injectable so tests can avoid real network I/O. */
+export type HttpGet = (url: string) => Promise<string>;
+export declare const MAX_JWKS_BYTES: number;
+export declare const DEFAULT_MIN_REFRESH_SECONDS = 30;
+export declare const DEFAULT_MAX_AGE_SECONDS = 3600;
+export interface JwksProviderOptions {
+    jwks?: JSONWebKeySet;
+    jwksUri?: string;
+    httpGet?: HttpGet;
+    /** Minimum time between fetches. Defaults to {@link DEFAULT_MIN_REFRESH_SECONDS}. */
+    minRefreshSeconds?: number;
+    /** Refresh a fetched set once it is this old. Defaults to {@link DEFAULT_MAX_AGE_SECONDS}. */
+    maxAgeSeconds?: number;
+    /** Milliseconds clock, injectable for tests. Defaults to `Date.now`. */
+    clock?: () => number;
+}
+export declare class JwksProvider {
+    #private;
+    /** Why the last fetch failed, or `null` after a successful one. */
+    lastError: string | null;
+    constructor(opts: JwksProviderOptions);
+    /**
+     * Resolve the verification key for a header `kid` (and `alg`). Falls back to the single configured key
+     * when the header carries no `kid`. Returns `undefined` when no key can be found; never rejects — a
+     * failed fetch leaves its reason in {@link lastError}.
+     */
+    resolve(kid: string | undefined, alg?: string): Promise<VerificationKey | undefined>;
+}

package/dist/validator/jwks.js

@@ -0,0 +1,135 @@
+var _a;
+/**
+ * Resolves issuer signing keys — from a static JWKS or a `jwksUri` (fetched and cached, refreshed on an
+ * unknown `kid` and when the cached set grows old).
+ *
+ * A `jwksUri` provider never fetches more than once per `minRefreshSeconds`, however many unknown `kid`
+ * values it is shown, and concurrent misses share one fetch. Without that, a stream of tokens with made-up
+ * `kid` values turns every request into a request to the issuer.
+ */
+import { importJWK } from "jose";
+import { request } from "../http.js";
+export const MAX_JWKS_BYTES = 512 * 1024;
+export const DEFAULT_MIN_REFRESH_SECONDS = 30;
+export const DEFAULT_MAX_AGE_SECONDS = 3600;
+const FETCH_TIMEOUT_MS = 10_000;
+const defaultGet = async (url) => {
+    // the shared transport refuses redirects and caps the body at MAX_JWKS_BYTES while reading it
+    const resp = await request(url, { method: "GET", timeoutMs: FETCH_TIMEOUT_MS, maxBytes: MAX_JWKS_BYTES });
+    if (!resp.ok) {
+        throw new Error(`GET ${url} failed: ${resp.status}`);
+    }
+    return resp.body;
+};
+/** Best-effort JWS `alg` for a JWK that omits `alg`, from its key type / curve. */
+function algorithmFor(jwk) {
+    if (jwk.kty === "EC") {
+        return { "P-256": "ES256", "P-384": "ES384", "P-521": "ES512" }[jwk.crv ?? ""] ?? "ES256";
+    }
+    if (jwk.kty === "RSA") {
+        return "RS256";
+    }
+    if (jwk.kty === "OKP") {
+        return "EdDSA";
+    }
+    return "RS256";
+}
+export class JwksProvider {
+    #static;
+    #jwksUri;
+    #httpGet;
+    #minRefreshMs;
+    #maxAgeMs;
+    #clock;
+    /** kid -> key, plus the JWK's declared `alg` (a JWK that declares one is only used for that alg). */
+    #keys = new Map();
+    #loaded = null;
+    #inFlight = null;
+    #loadedAt = null;
+    #lastAttempt = null;
+    /** Why the last fetch failed, or `null` after a successful one. */
+    lastError = null;
+    constructor(opts) {
+        this.#static = opts.jwks != null;
+        this.#jwksUri = opts.jwksUri;
+        this.#httpGet = opts.httpGet ?? defaultGet;
+        this.#minRefreshMs = (opts.minRefreshSeconds ?? DEFAULT_MIN_REFRESH_SECONDS) * 1000;
+        this.#maxAgeMs = (opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS) * 1000;
+        this.#clock = opts.clock ?? Date.now;
+        if (opts.jwks != null) {
+            this.#loaded = _a.#parse(opts.jwks).then((keys) => {
+                this.#keys = keys;
+            });
+        }
+    }
+    static async #parse(jwks) {
+        const keys = new Map();
+        for (const jwk of jwks.keys ?? []) {
+            const alg = jwk.alg ?? algorithmFor(jwk);
+            try {
+                keys.set(jwk.kid, { key: await importJWK(jwk, alg), alg: jwk.alg });
+            }
+            catch {
+                continue;
+            }
+        }
+        return keys;
+    }
+    /**
+     * Resolve the verification key for a header `kid` (and `alg`). Falls back to the single configured key
+     * when the header carries no `kid`. Returns `undefined` when no key can be found; never rejects — a
+     * failed fetch leaves its reason in {@link lastError}.
+     */
+    async resolve(kid, alg) {
+        if (this.#loaded) {
+            await this.#loaded;
+        }
+        if (!this.#static && this.#jwksUri && (this.#lookup(kid) === undefined || this.#stale())) {
+            await this.#refresh();
+        }
+        const entry = this.#lookup(kid);
+        if (entry === undefined || (alg != null && entry.alg != null && entry.alg !== alg)) {
+            return undefined;
+        }
+        return entry.key;
+    }
+    #lookup(kid) {
+        if (kid != null) {
+            return this.#keys.get(kid);
+        }
+        return this.#keys.size === 1 ? this.#keys.values().next().value : undefined;
+    }
+    #stale() {
+        return this.#loadedAt === null || this.#clock() - this.#loadedAt >= this.#maxAgeMs;
+    }
+    #refresh() {
+        if (this.#inFlight) {
+            return this.#inFlight;
+        }
+        const now = this.#clock();
+        if (this.#lastAttempt !== null && now - this.#lastAttempt < this.#minRefreshMs) {
+            return Promise.resolve();
+        }
+        this.#lastAttempt = now;
+        this.#inFlight = (async () => {
+            try {
+                const body = await this.#httpGet(this.#jwksUri);
+                if (body.length > MAX_JWKS_BYTES) {
+                    throw new Error(`JWKS is larger than ${MAX_JWKS_BYTES} bytes`);
+                }
+                this.#keys = await _a.#parse(JSON.parse(body));
+                this.#loadedAt = this.#clock();
+                this.lastError = null;
+            }
+            catch (exc) {
+                // keep serving the keys already held
+                this.lastError = `JWKS fetch failed: ${exc instanceof Error ? exc.message : String(exc)}`;
+            }
+            finally {
+                this.#inFlight = null;
+            }
+        })();
+        return this.#inFlight;
+    }
+}
+_a = JwksProvider;

package/dist/validator/resource.d.ts

@@ -0,0 +1,42 @@
+import type { ValidationResult } from "./result.js";
+import type { AccessTokenValidator } from "./validator.js";
+/** Extract the token from an `Authorization: Bearer <token>` header value, or null. */
+export declare function bearerToken(authorizationHeader?: string | null): string | null;
+/** RFC 9728 protected-resource metadata document. */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+}
+/** The outcome of guarding a request. */
+export interface AuthDecision {
+    authorized: boolean;
+    result?: ValidationResult;
+    status: number;
+    wwwAuthenticate?: string;
+    error?: string;
+    errorDescription?: string | null;
+}
+/**
+ * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
+ * incoming tokens to this resource (RFC 8707), which MCP servers MUST enforce. The constructor refuses one
+ * that doesn't.
+ */
+export declare class ProtectedResource {
+    #private;
+    readonly resource: string;
+    readonly authorizationServers: string[];
+    readonly scopesSupported: string[];
+    constructor(resource: string, authorizationServers: string[], validator: AccessTokenValidator, scopesSupported?: string[]);
+    metadata(): ProtectedResourceMetadata;
+    metadataPath(): string;
+    metadataUrl(): string;
+    challenge(error?: string, errorDescription?: string | null): string;
+    authenticate(authorizationHeader?: string | null, requiredScopes?: string[]): Promise<AuthDecision>;
+}
+/**
+ * Make a value safe inside a quoted-string header parameter: drop CR, LF and every other control
+ * character (0x00-0x1F, 0x7F) so nothing can split or forge a header, then escape backslash and quote.
+ */
+export declare function quote(value: string): string;

package/dist/validator/resource.js

@@ -0,0 +1,96 @@
+/**
+ * OAuth 2.0/2.1 protected-resource conventions on top of {@link AccessTokenValidator}.
+ *
+ * A {@link ProtectedResource} is the resource-server side of any OAuth-protected HTTP service — an MCP
+ * server (OAuth 2.1 resource server per the MCP authorization spec), an A2A agent, or a plain REST API. It
+ * adds what the validator itself doesn't: RFC 9728 Protected Resource Metadata
+ * (`/.well-known/oauth-protected-resource`), RFC 6750 bearer extraction + `WWW-Authenticate` challenges, and
+ * a request guard that binds the token audience to this resource (RFC 8707). Protocol-neutral — not MCP-only.
+ */
+import * as errors from "./errors.js";
+const WELL_KNOWN = "/.well-known/oauth-protected-resource";
+/** Extract the token from an `Authorization: Bearer <token>` header value, or null. */
+export function bearerToken(authorizationHeader) {
+    if (!authorizationHeader)
+        return null;
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(authorizationHeader);
+    return match ? match[1] : null;
+}
+/**
+ * An OAuth-protected resource server. The `validator` must accept `resource` as an audience — that binds
+ * incoming tokens to this resource (RFC 8707), which MCP servers MUST enforce. The constructor refuses one
+ * that doesn't.
+ */
+export class ProtectedResource {
+    resource;
+    authorizationServers;
+    scopesSupported;
+    #validator;
+    constructor(resource, authorizationServers, validator, scopesSupported = []) {
+        if (!validator.config.audiences.includes(resource)) {
+            throw new Error(`the validator does not accept this resource (${resource}) as an audience`);
+        }
+        this.resource = resource;
+        this.authorizationServers = authorizationServers;
+        this.#validator = validator;
+        this.scopesSupported = scopesSupported;
+    }
+    metadata() {
+        const md = {
+            resource: this.resource,
+            authorization_servers: this.authorizationServers,
+            bearer_methods_supported: ["header"],
+        };
+        if (this.scopesSupported.length > 0)
+            md.scopes_supported = this.scopesSupported;
+        return md;
+    }
+    metadataPath() {
+        const path = new URL(this.resource).pathname;
+        return path && path !== "/" ? WELL_KNOWN + path : WELL_KNOWN;
+    }
+    metadataUrl() {
+        const u = new URL(this.resource);
+        return `${u.protocol}//${u.host}${this.metadataPath()}`;
+    }
+    challenge(error, errorDescription) {
+        const params = [];
+        if (error) {
+            params.push(`error="${quote(error)}"`);
+            if (errorDescription)
+                params.push(`error_description="${quote(errorDescription)}"`);
+        }
+        params.push(`resource_metadata="${quote(this.metadataUrl())}"`);
+        return "Bearer " + params.join(", ");
+    }
+    async authenticate(authorizationHeader, requiredScopes) {
+        const token = bearerToken(authorizationHeader);
+        if (token == null) {
+            return { authorized: false, status: 401, wwwAuthenticate: this.challenge(), errorDescription: "authentication required" };
+        }
+        const result = await this.#validator.validate(token, requiredScopes);
+        if (result.valid) {
+            return { authorized: true, result, status: 200 };
+        }
+        const [status, oauthError] = httpError(result.error);
+        return {
+            authorized: false,
+            result,
+            status,
+            error: oauthError,
+            errorDescription: result.errorDescription,
+            wwwAuthenticate: this.challenge(oauthError, result.errorDescription),
+        };
+    }
+}
+function httpError(error) {
+    return error === errors.INSUFFICIENT_SCOPE ? [403, "insufficient_scope"] : [401, "invalid_token"];
+}
+/**
+ * Make a value safe inside a quoted-string header parameter: drop CR, LF and every other control
+ * character (0x00-0x1F, 0x7F) so nothing can split or forge a header, then escape backslash and quote.
+ */
+export function quote(value) {
+    // eslint-disable-next-line no-control-regex
+    return value.replace(/[\x00-\x1f\x7f]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/validator/result.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The outcome of validating an access token: either a valid token (with its subject, granted scopes,
+ * audience and claims) or a failure carrying a stable `error` code (see {@link ./errors}).
+ */
+import type { ValidationError } from "./errors.js";
+export interface ValidationResult {
+    valid: boolean;
+    /** Stable error code when `valid` is false; `null` when valid. */
+    error: ValidationError | null;
+    errorDescription: string | null;
+    subject: string | null;
+    scopes: string[];
+    audience: string[];
+    claims: Record<string, unknown>;
+    /** The `exp` claim (integer epoch seconds) when present. */
+    expiresAt: number | null;
+}
+export declare function success(claims: Record<string, unknown>, scopes: string[], audience: string[]): ValidationResult;
+export declare function failure(error: ValidationError, description?: string): ValidationResult;

package/dist/validator/result.js

@@ -0,0 +1,26 @@
+export function success(claims, scopes, audience) {
+    const sub = claims.sub;
+    const exp = claims.exp;
+    return {
+        valid: true,
+        error: null,
+        errorDescription: null,
+        subject: typeof sub === "string" ? sub : null,
+        scopes,
+        audience,
+        claims,
+        expiresAt: exp == null ? null : Number(exp),
+    };
+}
+export function failure(error, description) {
+    return {
+        valid: false,
+        error,
+        errorDescription: description ?? null,
+        subject: null,
+        scopes: [],
+        audience: [],
+        claims: {},
+        expiresAt: null,
+    };
+}

package/dist/validator/validator.d.ts

@@ -0,0 +1,33 @@
+import { type ResolvedConfig, type ValidatorConfig } from "./config.js";
+import { type HttpGet } from "./jwks.js";
+import { type ValidationResult } from "./result.js";
+/** Claims as decoded from a JWT payload (or an introspection response). */
+export type Claims = Record<string, unknown>;
+/**
+ * Inject a POST transport (mirrors Python's `http_post`). Resolves to the parsed JSON response body.
+ */
+export type HttpPost = (url: string, body: string, headers: Record<string, string>) => Promise<Claims>;
+/** Optional injectable transports, primarily so tests can mock network I/O. */
+export interface ValidatorOptions {
+    httpPost?: HttpPost;
+    httpGet?: HttpGet;
+}
+/** Validates access tokens for a resource server. */
+export declare class AccessTokenValidator {
+    #private;
+    readonly config: ResolvedConfig;
+    constructor(config: ValidatorConfig, opts?: ValidatorOptions);
+    /**
+     * Locally validate a JWT access token. Returns the first failure in the fixed contract order, or a
+     * success result exposing subject / scopes / audience / claims.
+     */
+    validate(token: string, requiredScopes?: string[]): Promise<ValidationResult>;
+    /**
+     * RFC 7662: POST the token to the AS introspection endpoint and return the parsed response.
+     */
+    introspect(token: string, tokenTypeHint?: string): Promise<Claims>;
+    /**
+     * Introspect the token and enforce `active` plus scope/audience from the response.
+     */
+    validateActive(token: string, requiredScopes?: string[]): Promise<ValidationResult>;
+}