@udibo/oauth2 0.1.0

package/esm/server/jwks-token-reader.js

@@ -0,0 +1,508 @@
+/**
+ * Token reader that validates JWT access tokens locally against the
+ * issuer's published JWKS, with no per-request network hop.
+ *
+ * This is the validating half of RFC 9068 (`at+jwt`): the authorization
+ * server signs access tokens and publishes its public keys at a `jwks_uri`;
+ * the resource server fetches those keys once, caches them, and verifies
+ * every subsequent token in-process. Signature verification uses Web Crypto
+ * only — the package takes no JOSE dependency.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9068
+ * @see https://datatracker.ietf.org/doc/html/rfc7517
+ * @module
+ */
+import { ServerError, TemporarilyUnavailableError } from "../errors.js";
+import { BasicScope } from "../models/scope.js";
+import { toArrayBuffer } from "../utils/_buffer.js";
+import { base64urlDecode } from "../utils/crypto.js";
+const ALGORITHMS = {
+    ES256: {
+        kty: "EC",
+        crv: "P-256",
+        importParams: { name: "ECDSA", namedCurve: "P-256" },
+        verifyParams: { name: "ECDSA", hash: "SHA-256" },
+    },
+    ES384: {
+        kty: "EC",
+        crv: "P-384",
+        importParams: { name: "ECDSA", namedCurve: "P-384" },
+        verifyParams: { name: "ECDSA", hash: "SHA-384" },
+    },
+    ES512: {
+        kty: "EC",
+        crv: "P-521",
+        importParams: { name: "ECDSA", namedCurve: "P-521" },
+        verifyParams: { name: "ECDSA", hash: "SHA-512" },
+    },
+    RS256: {
+        kty: "RSA",
+        importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+        verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+    },
+    RS384: {
+        kty: "RSA",
+        importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-384" },
+        verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+    },
+    RS512: {
+        kty: "RSA",
+        importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" },
+        verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+    },
+    PS256: {
+        kty: "RSA",
+        importParams: { name: "RSA-PSS", hash: "SHA-256" },
+        verifyParams: { name: "RSA-PSS", saltLength: 32 },
+    },
+    PS384: {
+        kty: "RSA",
+        importParams: { name: "RSA-PSS", hash: "SHA-384" },
+        verifyParams: { name: "RSA-PSS", saltLength: 48 },
+    },
+    PS512: {
+        kty: "RSA",
+        importParams: { name: "RSA-PSS", hash: "SHA-512" },
+        verifyParams: { name: "RSA-PSS", saltLength: 64 },
+    },
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function parseJws(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    const [headerPart, payloadPart, signaturePart] = parts;
+    try {
+        const header = JSON.parse(decoder.decode(base64urlDecode(headerPart)));
+        const payload = JSON.parse(decoder.decode(base64urlDecode(payloadPart)));
+        if (!isRecord(header) || !isRecord(payload))
+            return undefined;
+        return {
+            header,
+            payload,
+            signingInput: toArrayBuffer(encoder.encode(`${headerPart}.${payloadPart}`)),
+            signature: toArrayBuffer(base64urlDecode(signaturePart)),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const MEDIA_TYPE_PREFIX = "application/";
+function normalizeType(value) {
+    const lowered = value.toLowerCase();
+    return lowered.startsWith(MEDIA_TYPE_PREFIX)
+        ? lowered.slice(MEDIA_TYPE_PREFIX.length)
+        : lowered;
+}
+function verifyJwkOf(jwk) {
+    return jwk.kty === "EC"
+        ? { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y, ext: true }
+        : { kty: jwk.kty, n: jwk.n, e: jwk.e, ext: true };
+}
+function usableForVerification(jwk) {
+    if (jwk.kty !== "EC" && jwk.kty !== "RSA")
+        return false;
+    if (jwk.use !== undefined && jwk.use !== "sig")
+        return false;
+    if (jwk.key_ops !== undefined) {
+        if (!Array.isArray(jwk.key_ops) || !jwk.key_ops.includes("verify")) {
+            return false;
+        }
+    }
+    if (jwk.alg !== undefined) {
+        if (typeof jwk.alg !== "string" || !(jwk.alg in ALGORITHMS))
+            return false;
+    }
+    return true;
+}
+const ID_TOKEN_ONLY_CLAIMS = ["nonce", "at_hash", "c_hash", "s_hash"];
+function metadataUrlsFor(issuer) {
+    let url;
+    try {
+        url = new URL(issuer);
+    }
+    catch {
+        throw new TypeError("`issuer` must be an absolute URL");
+    }
+    const path = url.pathname.replace(/\/$/, "");
+    return [
+        ...new Set([
+            `${url.origin}/.well-known/oauth-authorization-server${path}`,
+            `${url.origin}/.well-known/openid-configuration${path}`,
+            `${url.origin}${path}/.well-known/openid-configuration`,
+        ]),
+    ];
+}
+function scopeTextOf(claims) {
+    if (typeof claims.scope === "string" && claims.scope)
+        return claims.scope;
+    if (Array.isArray(claims.scp))
+        return claims.scp.join(" ") || undefined;
+    if (typeof claims.scp === "string" && claims.scp)
+        return claims.scp;
+    return undefined;
+}
+/**
+ * Validates JWT access tokens (RFC 9068) against the issuer's remote JWKS.
+ *
+ * Use this with {@linkcode ResourceServer} when the authorization server
+ * issues **signed** access tokens: keys are fetched once and cached on the
+ * instance, so validation costs no network round-trip per request — the
+ * trade-off against {@linkcode IntrospectionTokenReader}, which sees
+ * revocation immediately but calls the authorization server every time. A
+ * revoked JWT stays valid here until it expires, so keep access-token
+ * lifetimes short, or introspect on the endpoints where revocation latency
+ * matters.
+ *
+ * A token is accepted only when its signature verifies against a published
+ * key whose algorithm the header matches, and its `typ`, `iss`, `aud`, `exp`
+ * and `nbf` all satisfy the configuration. Anything else is `undefined` —
+ * the same `invalid_token` surface as an unknown opaque token. Unreachable
+ * key material throws instead, so a down issuer is never reported as a bad
+ * token.
+ *
+ * **Token substitution.** An access token must never be confused with
+ * another JWT the same issuer signs. Three checks enforce that
+ * independently: `typ` must be `at+jwt`
+ * ({@linkcode JwksTokenReaderOptions.types}), the client-id claim must be
+ * present ({@linkcode JwksTokenReaderOptions.clientIdClaim}, REQUIRED by
+ * RFC 9068 §2.2 and absent from an `id_token`), and `id_token`-only claims
+ * (`nonce`, `at_hash`, `c_hash`, `s_hash`) are rejected outright.
+ * `auth_time`, `acr` and `amr` are **not** in that list — RFC 9068 §2.2.1
+ * permits them on an access token. A `crit` header is rejected per RFC 7515
+ * §4.1.11, since this reader understands no JWS extensions.
+ *
+ * The cache lives on the instance: construct one reader and reuse it.
+ *
+ * @example
+ * ```ts
+ * import { JwksTokenReader, ResourceServer } from "@udibo/oauth2/server/resource";
+ *
+ * interface MyClient { id: string }
+ * interface MyUser { id: string }
+ *
+ * const tokenReader = new JwksTokenReader<MyClient, MyUser>({
+ *   issuer: "https://auth.example.com",
+ *   audience: "https://api.example.com",
+ *   getClient: (claims) => ({ id: String(claims.client_id) }),
+ *   getUser: (claims) => claims.sub ? { id: claims.sub } : undefined,
+ * });
+ *
+ * const resourceServer = new ResourceServer<MyClient, MyUser>({
+ *   resolve: () => ({ services: { tokenService: tokenReader } }),
+ * });
+ * ```
+ */
+export class JwksTokenReader {
+    #issuer;
+    #audience;
+    #algorithms;
+    #types;
+    #clientIdClaim;
+    #clockSkewSeconds;
+    #cacheMaxAgeMs;
+    #minFetchIntervalMs;
+    #fetchTimeoutMs;
+    #metadataUrls;
+    #Scope;
+    #getClient;
+    #getUser;
+    #customFetch;
+    #jwksUri;
+    #entries = [];
+    #fetchedAt = 0;
+    #lastAttemptAt = 0;
+    #inFlight;
+    /**
+     * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
+     * required as `typ`, `client_id` as the required client-id claim, 30
+     * seconds of clock skew, a 10-minute cache with a 30-second minimum
+     * between fetches, a 5-second request deadline, {@linkcode BasicScope},
+     * and the global `fetch`.
+     *
+     * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
+     *   empty, or `algorithms` names an algorithm this package cannot verify
+     *   (a silently ignored entry would read as a policy that isn't enforced).
+     */
+    constructor(options) {
+        this.#issuer = options.issuer;
+        this.#metadataUrls = metadataUrlsFor(options.issuer);
+        this.#audience = Array.isArray(options.audience)
+            ? [...options.audience]
+            : [options.audience];
+        if (this.#audience.length === 0) {
+            throw new TypeError("`audience` must name at least one value");
+        }
+        this.#algorithms = options.algorithms ?? Object.keys(ALGORITHMS);
+        for (const algorithm of this.#algorithms) {
+            if (!(algorithm in ALGORITHMS)) {
+                throw new TypeError(`unsupported algorithm: ${algorithm}`);
+            }
+        }
+        this.#types = (options.types ?? ["at+jwt"]).map(normalizeType);
+        this.#clientIdClaim = options.clientIdClaim ?? "client_id";
+        this.#clockSkewSeconds = options.clockSkewSeconds ?? 30;
+        this.#cacheMaxAgeMs = options.cacheMaxAgeMs ?? 600_000;
+        this.#minFetchIntervalMs = options.minFetchIntervalMs ?? 30_000;
+        this.#fetchTimeoutMs = options.fetchTimeoutMs ?? 5_000;
+        this.#Scope = options.Scope ??
+            BasicScope;
+        this.#getClient = options.getClient;
+        this.#getUser = options.getUser;
+        this.#customFetch = options.fetch;
+        this.#jwksUri = options.jwksUri;
+    }
+    /**
+     * Validates a JWT access token against the cached JWKS.
+     *
+     * Refreshes the keys when no published key verifies the signature — at
+     * most one fetch per {@linkcode
+     * JwksTokenReaderOptions.minFetchIntervalMs}, shared by concurrent
+     * callers. A token whose `kid` matched a cached key and still failed
+     * verification is a forgery, not a rotation, and provokes no fetch. A
+     * stale cache refreshes in the background: requests are served from the
+     * cached keys rather than blocked on the issuer.
+     *
+     * @returns The token with client/user/scope info, or `undefined` when the
+     *   token is malformed, signed by an unknown or unaccepted key, or fails
+     *   any claim check.
+     * @throws {TemporarilyUnavailableError} If the JWKS (or discovery
+     *   document) is unreachable or returns a 5xx **and** no cached keys are
+     *   available — a down issuer must be distinguishable from a genuinely
+     *   invalid token, not collapsed into it. Once keys are cached, a failed
+     *   refresh is absorbed and the cached keys keep serving.
+     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
+     *   is not a JWKS, or discovery reports no `jwks_uri` — a
+     *   misconfiguration, not a verdict on the caller's token.
+     */
+    async getToken(accessToken) {
+        const parsed = parseJws(accessToken);
+        if (!parsed)
+            return undefined;
+        const { alg, kid, typ, crit } = parsed.header;
+        if (crit !== undefined)
+            return undefined;
+        if (typeof alg !== "string" || !this.#algorithms.includes(alg)) {
+            return undefined;
+        }
+        if (!this.#acceptsType(typ))
+            return undefined;
+        const verified = await this.#verified(parsed, alg, typeof kid === "string" ? kid : undefined);
+        if (!verified)
+            return undefined;
+        const claims = parsed.payload;
+        if (!this.#validClaims(claims))
+            return undefined;
+        const [client, user] = await Promise.all([
+            this.#getClient(claims),
+            this.#getUser?.(claims),
+        ]);
+        const scopeText = scopeTextOf(claims);
+        return {
+            accessToken,
+            accessTokenExpiresAt: new Date(claims.exp * 1000),
+            client,
+            user,
+            scope: scopeText ? new this.#Scope(scopeText) : undefined,
+            claims: claims,
+        };
+    }
+    #acceptsType(typ) {
+        if (this.#types.length === 0)
+            return true;
+        if (typeof typ !== "string")
+            return false;
+        return this.#types.includes(normalizeType(typ));
+    }
+    #validClaims(claims) {
+        if (claims.iss !== this.#issuer)
+            return false;
+        const clientId = claims[this.#clientIdClaim];
+        if (typeof clientId !== "string" || !clientId)
+            return false;
+        for (const claim of ID_TOKEN_ONLY_CLAIMS) {
+            if (claims[claim] !== undefined)
+                return false;
+        }
+        const audience = Array.isArray(claims.aud)
+            ? claims.aud
+            : typeof claims.aud === "string"
+                ? [claims.aud]
+                : [];
+        if (!audience.some((value) => this.#audience.includes(value)))
+            return false;
+        const now = Math.floor(Date.now() / 1000);
+        if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
+            return false;
+        }
+        if (now >= claims.exp + this.#clockSkewSeconds)
+            return false;
+        if (claims.nbf !== undefined) {
+            if (typeof claims.nbf !== "number" || !Number.isFinite(claims.nbf)) {
+                return false;
+            }
+            if (claims.nbf - this.#clockSkewSeconds > now)
+                return false;
+        }
+        return true;
+    }
+    async #verifySignature(candidates, alg, parsed) {
+        const { verifyParams } = ALGORITHMS[alg];
+        for (const entry of candidates) {
+            const key = await this.#importKey(entry, alg);
+            if (!key)
+                continue;
+            const valid = await crypto.subtle.verify(verifyParams, key, parsed.signature, parsed.signingInput);
+            if (valid)
+                return true;
+        }
+        return false;
+    }
+    async #importKey(entry, alg) {
+        const cached = entry.imported.get(alg);
+        if (cached)
+            return cached;
+        try {
+            const key = await crypto.subtle.importKey("jwk", verifyJwkOf(entry.jwk), ALGORITHMS[alg].importParams, false, ["verify"]);
+            entry.imported.set(alg, key);
+            return key;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #match(kid, alg) {
+        const spec = ALGORITHMS[alg];
+        return this.#entries.filter((entry) => {
+            if (kid !== undefined && entry.kid !== kid)
+                return false;
+            if (entry.alg !== undefined && entry.alg !== alg)
+                return false;
+            if (entry.jwk.kty !== spec.kty)
+                return false;
+            if (spec.crv !== undefined && entry.jwk.crv !== spec.crv)
+                return false;
+            return true;
+        });
+    }
+    async #verified(parsed, alg, kid) {
+        await this.#ensureKeys();
+        const candidates = this.#match(kid, alg);
+        if (await this.#verifySignature(candidates, alg, parsed))
+            return true;
+        if (kid !== undefined && candidates.length > 0)
+            return false;
+        await this.#refreshQuietly();
+        return await this.#verifySignature(this.#match(kid, alg), alg, parsed);
+    }
+    async #ensureKeys() {
+        if (this.#entries.length === 0) {
+            await this.#refresh();
+            return;
+        }
+        if (Date.now() - this.#fetchedAt > this.#cacheMaxAgeMs) {
+            void this.#refreshQuietly();
+        }
+    }
+    async #refreshQuietly() {
+        await this.#refresh().catch(() => { });
+    }
+    async #refresh() {
+        if (this.#inFlight)
+            return await this.#inFlight;
+        if (Date.now() - this.#lastAttemptAt < this.#minFetchIntervalMs) {
+            if (this.#entries.length === 0) {
+                throw new TemporarilyUnavailableError("jwks is unavailable");
+            }
+            return;
+        }
+        const promise = this.#load();
+        this.#inFlight = promise;
+        try {
+            await promise;
+        }
+        finally {
+            this.#inFlight = undefined;
+            this.#lastAttemptAt = Date.now();
+        }
+    }
+    async #load() {
+        const jwksUri = this.#jwksUri ?? await this.#discoverJwksUri();
+        const body = await this.#fetchJson(jwksUri, "jwks");
+        if (!isRecord(body) || !Array.isArray(body.keys)) {
+            throw new ServerError("jwks response has no `keys` array");
+        }
+        this.#entries = body.keys
+            .filter((jwk) => isRecord(jwk))
+            .filter(usableForVerification)
+            .map((jwk) => ({
+            jwk,
+            kid: typeof jwk.kid === "string" ? jwk.kid : undefined,
+            alg: typeof jwk.alg === "string" ? jwk.alg : undefined,
+            imported: new Map(),
+        }));
+        this.#fetchedAt = Date.now();
+    }
+    async #discoverJwksUri() {
+        let transientError;
+        let lastError;
+        for (const url of this.#metadataUrls) {
+            try {
+                const metadata = await this.#fetchJson(url, "discovery");
+                const jwksUri = isRecord(metadata) ? metadata.jwks_uri : undefined;
+                if (typeof jwksUri !== "string") {
+                    throw new ServerError("discovery metadata has no `jwks_uri`");
+                }
+                this.#jwksUri = jwksUri;
+                return jwksUri;
+            }
+            catch (error) {
+                if (error instanceof TemporarilyUnavailableError &&
+                    transientError === undefined) {
+                    transientError = error;
+                }
+                lastError = error;
+            }
+        }
+        throw transientError ?? lastError ?? new ServerError("discovery failed");
+    }
+    async #fetchJson(url, label) {
+        const fetchImpl = this.#customFetch ?? globalThis.fetch;
+        const controller = new AbortController();
+        const deadline = setTimeout(() => controller.abort(), this.#fetchTimeoutMs);
+        try {
+            let response;
+            try {
+                response = await fetchImpl(url, {
+                    headers: { "Accept": "application/json" },
+                    signal: controller.signal,
+                });
+            }
+            catch (cause) {
+                throw new TemporarilyUnavailableError(`${label} request failed`, {
+                    cause,
+                });
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw response.status >= 500
+                    ? new TemporarilyUnavailableError(`${label} request failed (HTTP ${response.status})`)
+                    : new ServerError(`${label} request failed (HTTP ${response.status})`);
+            }
+            try {
+                return await response.json();
+            }
+            catch (cause) {
+                throw new ServerError(`${label} response was not JSON`, { cause });
+            }
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+}

package/esm/server/mod.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared types for OAuth2 servers (both resource and authorization servers).
+ *
+ * This module exports errors, models, service interfaces, and utilities
+ * common to both server types. Import server-specific classes from:
+ * - `@udibo/oauth2/server/resource` for ResourceServer
+ * - `@udibo/oauth2/server/authorization` for AuthorizationServer
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export type { ClientCredentials, ClientInterface } from "../models/client.js";
+export type { AuthenticationContext } from "../models/authentication.js";
+export type { IntrospectionResponse, RefreshToken, Token, TokenResponse, } from "../models/token.js";
+export { AbstractScope, BasicScope } from "../models/scope.js";
+export type { ScopeConstructor } from "../models/scope.js";
+export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
+export type { AuthorizationFailure, AuthorizationInit, OrganizationContext, RequireConditions, } from "../models/authorization.js";
+export { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+export type { OAuth2ErrorClass, OAuth2ProblemDetailsExtensions, } from "../errors.js";
+export type { TokenReaderInterface } from "./services/token.js";
+export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";
+export type { IsPublicSuffix, RedirectUriPatternRule, RedirectUriPatternViolation, } from "./redirect-uri.js";

package/esm/server/mod.js

@@ -0,0 +1,15 @@
+/**
+ * Shared types for OAuth2 servers (both resource and authorization servers).
+ *
+ * This module exports errors, models, service interfaces, and utilities
+ * common to both server types. Import server-specific classes from:
+ * - `@udibo/oauth2/server/resource` for ResourceServer
+ * - `@udibo/oauth2/server/authorization` for AuthorizationServer
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { AbstractScope, BasicScope } from "../models/scope.js";
+export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
+export { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";

package/esm/server/public-suffix/mod.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The bundled Public Suffix List, as an {@link isPublicSuffix} implementation.
+ *
+ * A *public suffix* is a domain you can only register names **under**, never
+ * **at** — `com`, `co.uk`, `deno.net`, `s3.amazonaws.com`. The authorization
+ * server needs the distinction to bound a wildcard redirect URI: everything a
+ * wildcard covers must belong to one registrant, which is only true when the
+ * domain beneath it is a registrable name rather than a shared suffix.
+ *
+ * This entrypoint is separate from `@udibo/oauth2/server` on purpose. The list
+ * is roughly 150 kB of generated source, and a server that never accepts
+ * wildcard registrations should not carry it — so
+ * `checkRedirectUriPattern` takes the check as an injected seam and
+ * refuses every pattern when none is supplied. Wire it once, where you build
+ * the authorization server:
+ *
+ * ```ts
+ * import { AuthorizationServer } from "@udibo/oauth2/server/authorization";
+ * import { isPublicSuffix } from "@udibo/oauth2/server/public-suffix";
+ *
+ * const server = new AuthorizationServer({ isPublicSuffix, ...options });
+ * ```
+ *
+ * The snapshot covers both the ICANN and the private sections. The private
+ * section is the security-relevant half here: every shared hosting platform a
+ * wildcard must not straddle (`github.io`, `vercel.app`, `blob.core.windows.net`)
+ * is listed there and nowhere else.
+ *
+ * Regenerate it with `deno task psl:update`; `deno task psl:check` fails when
+ * the snapshot has drifted from publicsuffix.org and runs on a schedule in CI.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { publicSuffixListInfo } from "./rules.js";
+export { publicSuffixListInfo };
+/**
+ * Whether a domain is a public suffix — a name others register *under* rather
+ * than a registrable domain someone owns.
+ *
+ * Implements the publicsuffix.org algorithm against the bundled snapshot,
+ * including wildcard rules (`*.ck`), exception rules (`!www.ck`), and the
+ * implicit `*` rule that makes any unlisted top-level domain a public suffix.
+ * The argument may be Unicode or punycode, upper or lower case, with or
+ * without a trailing dot; a host that cannot be normalized (empty, or with an
+ * empty label) is reported as a public suffix so a caller bounding a wildcard
+ * fails closed.
+ *
+ * @param domain The hostname to classify.
+ * @returns `true` when the whole domain is a public suffix.
+ *
+ * @example
+ * ```ts
+ * import { isPublicSuffix } from "@udibo/oauth2/server/public-suffix";
+ *
+ * isPublicSuffix("co.uk"); // true
+ * isPublicSuffix("deno.net"); // true — anyone can take a subdomain
+ * isPublicSuffix("myorg.deno.net"); // false — one organization's namespace
+ * isPublicSuffix("example.com"); // false
+ * ```
+ */
+export declare function isPublicSuffix(domain: string): boolean;