@udibo/oauth2 0.1.0

package/esm/server/redirect-uri.js

@@ -0,0 +1,331 @@
+/**
+ * Redirect URI matching for the authorization server.
+ *
+ * RFC 6749 §3.1.2.3 and the OAuth 2.0 Security BCP require `redirect_uri` to be
+ * compared against a pre-registered value by exact string match, and that is
+ * what {@link matchRedirectUri} does for every ordinary registration. A
+ * registration may instead be a **pattern** — a single `*` in the leftmost host
+ * label — which lets one registration cover the per-deploy hostnames a preview
+ * environment produces.
+ *
+ * Patterns are deliberately narrow, because a wildcard that reaches beyond the
+ * registrant's own namespace hands authorization codes to whoever can obtain a
+ * neighbouring host. The rules are enforced by {@link checkRedirectUriPattern},
+ * and {@link matchRedirectUri} refuses to match a pattern that violates any of
+ * them, so an invalid pattern in storage is inert rather than dangerous.
+ *
+ * The narrowest of those rules — the domain under the wildcard has to be one
+ * registrant's — is decided by the Public Suffix List, injected as
+ * {@link IsPublicSuffix} so this module carries no data. Pass `isPublicSuffix`
+ * from `@udibo/oauth2/server/public-suffix`; a server that never accepts
+ * patterns can leave it out and refuse them all.
+ *
+ * A registration whose host is a **loopback IP literal** (`127.0.0.1` or
+ * `[::1]`) is the one other departure from exact matching: RFC 8252 §7.3
+ * requires the authorization server to allow any port at request time, because
+ * a native app binds an OS-assigned port it cannot know when it registers.
+ * Only the port is relaxed, and only for the IP literals — `localhost` is a
+ * name resolved by a host file this server does not control (RFC 8252 §8.3),
+ * so it keeps exact matching.
+ *
+ * This module has no notion of environments. Deciding *which* clients may
+ * register a pattern at all is the application's call — the usual policy is to
+ * permit them for development registrations and refuse them for production
+ * ones, which an application enforces by validating at registration time and by
+ * not handing a pattern to the authorization server for a production client.
+ * The loopback relaxation is likewise only reachable once the application has
+ * chosen to register a loopback URI.
+ *
+ * @module
+ */
+/**
+ * A label used to ask whether the *children* of a parent domain are public
+ * suffixes, which is a different question from whether the parent is one.
+ *
+ * `r.appspot.com` is a registrable domain by the list's reckoning, but the rule
+ * `*.r.appspot.com` makes every one of its subdomains a public suffix belonging
+ * to a different registrant — so a wildcard over it hands codes to strangers
+ * even though the parent itself passes. Probing with a label no registry has
+ * ever issued answers that in one lookup.
+ */
+const CHILD_PROBE_LABEL = "udibo-public-suffix-probe";
+/**
+ * Split a hostname into labels, or `null` when it is not usable for matching.
+ *
+ * A single trailing dot is the DNS root and is dropped, so `example.com.` and
+ * `example.com` are the same host — without this, the extra empty label would
+ * shift every label the public-suffix check looks at and let `*.deno.net.`
+ * through. Any *other* empty label (`a..b`, a leading `.`) is refused outright
+ * rather than normalized: it cannot resolve, and an empty leftmost label would
+ * otherwise satisfy any prefix/suffix test.
+ */
+function hostLabels(hostname) {
+    const normalized = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+    if (normalized.length === 0)
+        return null;
+    const labels = normalized.split(".");
+    if (labels.some((label) => label.length === 0))
+        return null;
+    return labels;
+}
+/**
+ * Whether a registered redirect URI is a wildcard pattern rather than a literal
+ * URI. Says nothing about whether the pattern is *valid* — use
+ * {@link checkRedirectUriPattern} for that.
+ *
+ * @example
+ * ```ts
+ * import { isRedirectUriPattern } from "@udibo/oauth2/server";
+ *
+ * isRedirectUriPattern("https://myapp-*.myorg.deno.net/cb"); // true
+ * isRedirectUriPattern("https://myapp.example.com/cb"); // false
+ * ```
+ */
+export function isRedirectUriPattern(redirectUri) {
+    return redirectUri.includes("*");
+}
+function violation(rule, message) {
+    return { rule, message };
+}
+/**
+ * Check a registered redirect URI pattern against the pattern rules.
+ *
+ * Returns `null` when the value is safe to register — which includes any value
+ * with no `*` in it at all, since a literal redirect URI is matched exactly and
+ * has no pattern rules to break. Otherwise it returns the first
+ * {@link RedirectUriPatternViolation}, whose `message` is written to be shown
+ * to whoever is registering the URI.
+ *
+ * Use this at registration time to reject a bad pattern where the person
+ * responsible can fix it. {@link matchRedirectUri} applies the same check at
+ * request time, so a pattern that slipped into storage never matches.
+ *
+ * **Patterns need `isPublicSuffix`.** Without it there is no way to tell
+ * `myorg.deno.net` (yours) from `deno.net` (everyone's), so every pattern is
+ * refused. Pass `isPublicSuffix` from `@udibo/oauth2/server/public-suffix`, or
+ * omit it deliberately on a server that only accepts literal redirect URIs.
+ *
+ * @param pattern The registered redirect URI to check.
+ * @param isPublicSuffix Decides whether the domain under the wildcard is a
+ * public suffix. Omitting it refuses every pattern.
+ * @returns The violated rule and an explanation, or `null` when there is none.
+ *
+ * @example
+ * ```ts
+ * import { checkRedirectUriPattern } from "@udibo/oauth2/server";
+ * import { isPublicSuffix } from "@udibo/oauth2/server/public-suffix";
+ *
+ * checkRedirectUriPattern("https://myapp-*.myorg.deno.net/cb", isPublicSuffix); // null
+ * checkRedirectUriPattern("https://*.deno.net/cb", isPublicSuffix)?.rule; // "parent-domain"
+ * checkRedirectUriPattern("http://*.a.example.com/cb", isPublicSuffix)?.rule; // "scheme"
+ * ```
+ */
+export function checkRedirectUriPattern(pattern, isPublicSuffix) {
+    if (!isRedirectUriPattern(pattern))
+        return null;
+    let url;
+    try {
+        url = new URL(pattern);
+    }
+    catch {
+        return violation("syntax", `"${pattern}" is not a valid absolute URL, so it cannot be matched ` +
+            `against a redirect_uri. Register the full callback URL, for example ` +
+            `https://myapp-*.myorg.example.com/auth/callback.`);
+    }
+    if (url.protocol !== "https:") {
+        return violation("scheme", `"${pattern}" must use https. A wildcard registration covers hosts that ` +
+            `do not exist yet, so the authorization code it receives has to be ` +
+            `protected in transit.`);
+    }
+    if ((pattern.match(/\*/g) ?? []).length !== 1) {
+        return violation("wildcard-count", `"${pattern}" must contain exactly one "*". More than one wildcard ` +
+            `widens the set of matching hosts past what can be reasoned about.`);
+    }
+    const labels = hostLabels(url.hostname);
+    if (!labels) {
+        return violation("syntax", `"${pattern}" has an empty host label. Remove the repeated or leading ` +
+            `"." — a host like "a..example.com" cannot resolve, and an empty ` +
+            `label beside the wildcard would match anything.`);
+    }
+    if (!url.hostname.includes("*") || !labels[0].includes("*")) {
+        return violation("wildcard-placement", `"${pattern}" may only use "*" in the leftmost part of the host — never ` +
+            `in the scheme, port, path, query, or fragment. A wildcard elsewhere ` +
+            `would let an attacker choose where the authorization code is sent.`);
+    }
+    const parentDomain = labels.slice(1).join(".");
+    if (!isPublicSuffix) {
+        return violation("parent-domain", `"${pattern}" cannot be registered: this server has no Public Suffix ` +
+            `List, so it cannot tell whether "${parentDomain}" is a namespace ` +
+            `your organization controls or one anyone can obtain a host under. ` +
+            `Register the callback URLs in full, or ask the operator to configure ` +
+            `isPublicSuffix.`);
+    }
+    if (isPublicSuffix(parentDomain)) {
+        return violation("parent-domain", `"${pattern}" wildcards "${parentDomain}", which is a public suffix — ` +
+            `anyone can register a name directly under it, obtain a neighbouring ` +
+            `host, and receive your authorization codes. Put the wildcard under a ` +
+            `domain your organization registered, for example ` +
+            `https://myapp-*.myorg.${parentDomain}/callback.`);
+    }
+    if (isPublicSuffix(`${CHILD_PROBE_LABEL}.${parentDomain}`)) {
+        return violation("parent-domain", `"${pattern}" wildcards "${parentDomain}", whose subdomains are each a ` +
+            `public suffix belonging to a different registrant, so a neighbouring ` +
+            `host is available to anyone. Put the wildcard under a domain your ` +
+            `organization registered.`);
+    }
+    return null;
+}
+/**
+ * The loopback IP literals RFC 8252 §7.3 covers, in the form
+ * `URL.hostname` normalizes them to. `localhost` is deliberately absent: RFC
+ * 8252 §8.3 advises against it because its resolution depends on a host file
+ * the authorization server does not control.
+ */
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "[::1]"]);
+function matchesLoopback(registration, redirectUri) {
+    if (isRedirectUriPattern(registration))
+        return false;
+    let registeredUrl;
+    let url;
+    try {
+        registeredUrl = new URL(registration);
+        url = new URL(redirectUri);
+    }
+    catch {
+        return false;
+    }
+    if (!LOOPBACK_HOSTNAMES.has(registeredUrl.hostname))
+        return false;
+    return registeredUrl.protocol === url.protocol &&
+        registeredUrl.hostname === url.hostname &&
+        registeredUrl.username === url.username &&
+        registeredUrl.password === url.password &&
+        registeredUrl.pathname === url.pathname &&
+        registeredUrl.search === url.search &&
+        registeredUrl.hash === url.hash;
+}
+function matchesPattern(pattern, redirectUri, isPublicSuffix) {
+    if (checkRedirectUriPattern(pattern, isPublicSuffix) !== null)
+        return false;
+    let patternUrl;
+    let url;
+    try {
+        patternUrl = new URL(pattern);
+        url = new URL(redirectUri);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:")
+        return false;
+    if (url.port !== patternUrl.port)
+        return false;
+    if (url.username !== patternUrl.username)
+        return false;
+    if (url.password !== patternUrl.password)
+        return false;
+    if (url.pathname !== patternUrl.pathname)
+        return false;
+    if (url.search !== patternUrl.search)
+        return false;
+    if (url.hash !== patternUrl.hash)
+        return false;
+    if (url.hostname.includes("*"))
+        return false;
+    const patternLabels = hostLabels(patternUrl.hostname);
+    const labels = hostLabels(url.hostname);
+    if (!patternLabels || !labels)
+        return false;
+    if (patternLabels.length !== labels.length)
+        return false;
+    for (let i = 1; i < patternLabels.length; i++) {
+        if (patternLabels[i] !== labels[i])
+            return false;
+    }
+    const [prefix, suffix] = patternLabels[0].split("*");
+    const label = labels[0];
+    return label.length >= prefix.length + suffix.length &&
+        label.startsWith(prefix) && label.endsWith(suffix);
+}
+/**
+ * Find the registered redirect URI that authorizes a requested `redirect_uri`.
+ *
+ * Literal registrations are compared by exact string match (RFC 6749
+ * §3.1.2.3), and an exact match always wins.
+ *
+ * A registration whose host is a **loopback IP literal** — `127.0.0.1` or
+ * `[::1]`, after `URL` normalizes forms like `127.1` and
+ * `[0:0:0:0:0:0:0:1]` — is tried next, matching the request on every part
+ * *except* the port (RFC 8252 §7.3: "the authorization server MUST allow any
+ * port to be specified at the time of the request for loopback IP redirect
+ * URIs"). Scheme, host, userinfo, path, query, and fragment must still be
+ * equal, and `localhost` is not covered — it is a name resolved by a host file
+ * this server does not control (RFC 8252 §8.3), so it matches exactly like any
+ * other host.
+ *
+ * Only if neither matches are the pattern registrations tried, under the rules
+ * in {@link checkRedirectUriPattern} plus:
+ *
+ * - The requested URI must be `https`, so a pattern can never be satisfied over
+ *   plaintext.
+ * - `*` matches within one host label and never across a `.`, so
+ *   `https://a-*.example.com/cb` does not match
+ *   `https://a-x.evil.example.com/cb`.
+ * - Port, userinfo, path, query, and fragment must match the pattern exactly.
+ * - A host label may never be empty, and a single trailing dot is treated as
+ *   the same host, so `example.com.` cannot smuggle an extra label past the
+ *   parent-domain rule.
+ * - A requested URI containing `*` never matches anything, checked both on the
+ *   raw string and on the percent-decoded host, so a pattern can never be
+ *   replayed back as a literal redirect target.
+ *
+ * That last rule is a deliberate tightening: `*` is a legal host character, so
+ * a registration containing one that was previously matched by exact string
+ * comparison no longer matches at all. Such a registration cannot be created
+ * any more — a `*` now makes the value a pattern, which must satisfy the rules
+ * above — so this only affects rows written before patterns existed.
+ *
+ * @param registered The client's registered redirect URIs.
+ * @param redirectUri The `redirect_uri` from the authorization request.
+ * @param isPublicSuffix Decides whether the domain under a wildcard is a public
+ * suffix. Omitting it makes every pattern registration inert; literal
+ * registrations are unaffected.
+ * @returns The registered entry that authorized the request, or `undefined`
+ * when none did.
+ *
+ * @example
+ * ```ts
+ * import { matchRedirectUri } from "@udibo/oauth2/server";
+ * import { isPublicSuffix } from "@udibo/oauth2/server/public-suffix";
+ *
+ * const registered = ["https://myapp-*.myorg.deno.net/auth/callback"];
+ * matchRedirectUri(registered, "https://myapp-a1b2.myorg.deno.net/auth/callback", isPublicSuffix);
+ * // "https://myapp-*.myorg.deno.net/auth/callback"
+ * matchRedirectUri(registered, "https://myapp-a1b2.evil.myorg.deno.net/auth/callback", isPublicSuffix);
+ * // undefined
+ *
+ * matchRedirectUri(["http://127.0.0.1/callback"], "http://127.0.0.1:53211/callback");
+ * // "http://127.0.0.1/callback"
+ * matchRedirectUri(["http://localhost/callback"], "http://localhost:53211/callback");
+ * // undefined
+ * ```
+ */
+export function matchRedirectUri(registered, redirectUri, isPublicSuffix) {
+    if (isRedirectUriPattern(redirectUri))
+        return undefined;
+    for (const entry of registered) {
+        if (entry === redirectUri)
+            return entry;
+    }
+    for (const entry of registered) {
+        if (matchesLoopback(entry, redirectUri))
+            return entry;
+    }
+    for (const entry of registered) {
+        if (isRedirectUriPattern(entry) &&
+            matchesPattern(entry, redirectUri, isPublicSuffix)) {
+            return entry;
+        }
+    }
+    return undefined;
+}

package/esm/server/resource-server.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Resource Server implementation for protecting resources with OAuth2 tokens.
+ *
+ * Implements bearer token validation per RFC 6750.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import type { ClientInterface } from "../models/client.js";
+import type { Token } from "../models/token.js";
+import type { AbstractScope, ScopeConstructor } from "../models/scope.js";
+import { BasicScope } from "../models/scope.js";
+import { type OAuth2Error } from "../errors.js";
+import { type Authorization, type RequireConditions } from "../models/authorization.js";
+import type { TokenReaderInterface } from "./services/token.js";
+/** Bearer token regex pattern. */
+export declare const BEARER_TOKEN: RegExp;
+/** Services required by the resource server. */
+export interface ResourceServerServices<Client extends ClientInterface, User, S extends AbstractScope> {
+    /** Reads and validates access tokens for this request. */
+    tokenService: TokenReaderInterface<Client, User, S>;
+}
+/** Per-request context resolved by a {@link ResourceServer}. */
+export interface ResourceServerContext<Client extends ClientInterface, User, S extends AbstractScope> {
+    /** Tenant-scoped services to use for this request. */
+    services: ResourceServerServices<Client, User, S>;
+}
+/** Options for configuring the resource server. */
+export interface ResourceServerOptions<Client extends ClientInterface, User, S extends AbstractScope> {
+    /**
+     * Resolves the per-request context — the (e.g. tenant-scoped) {@link
+     * ResourceServerServices} for THIS request — so a single instance serves
+     * every tenant/origin. This is the only services seam: for a single-tenant
+     * server it is a constant function returning the same services every time
+     * (create the services once, outside `resolve`, and return them here).
+     */
+    resolve: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
+    /** Scope constructor used to parse and compare scopes. Defaults to {@linkcode BasicScope}. */
+    Scope?: ScopeConstructor<S>;
+    /** Protection space named in `WWW-Authenticate` challenges. Defaults to `"Service"`. */
+    realm?: string;
+    /**
+     * Leeway in seconds applied to the access token's expiry, to absorb clock
+     * drift between whoever issued the token and this server. Defaults to `0`:
+     * a token whose expiry has passed is refused immediately.
+     *
+     * This is the one expiry check every token reader's result passes through,
+     * which is why the leeway belongs here rather than in a reader:
+     * {@linkcode IntrospectionTokenReader} reports the authorization server's
+     * `exp` verbatim and has no notion of skew at all, and
+     * {@linkcode JwksTokenReaderOptions.clockSkewSeconds} governs only that
+     * reader's own claim checks. Set this whenever you need drift tolerance, no
+     * matter which reader is in play.
+     */
+    clockSkewSeconds?: number;
+    /**
+     * Format for error responses.
+     * - `"oauth2"` (default): Standard OAuth2 error format with `error`,
+     *   `error_description`, and `error_uri` fields.
+     * - `"problem-details"`: RFC 9457 Problem Details format with OAuth2
+     *   extensions. `type` and `error_uri` carry the same URI; `detail` and
+     *   `error_description` carry the same message.
+     */
+    errorFormat?: "oauth2" | "problem-details";
+    /**
+     * If true, handlers rethrow errors (as {@link OAuth2Error}) instead of
+     * catching them and returning a response. Framework adapters that want to
+     * build responses themselves should enable this. Default: false.
+     */
+    throwOnError?: boolean;
+}
+/** Authentication context returned by the resource server. */
+export interface AuthenticatedContext<Client extends ClientInterface, User, S extends AbstractScope> {
+    /** The validated access token backing this request. */
+    token: Token<Client, User, S>;
+    /** The client the token was issued to. */
+    client: Client;
+    /** The resource owner, absent for client-credentials tokens. */
+    user?: User;
+    /** The scope granted to the token, if any. */
+    scope?: S | null;
+    /**
+     * The token's claims as one checkable object — scope, roles, permissions,
+     * and the active organization. Built from {@linkcode Token.claims}; a token
+     * with no claims yields an authorization that answers scope checks only.
+     */
+    authorization: Authorization;
+}
+/**
+ * Validates OAuth2 bearer access tokens (RFC 6750) so API endpoints can require
+ * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
+ * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
+ *
+ * A single instance serves every tenant/origin; per-request services come from
+ * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
+ * single-tenant server, `resolve` is a constant function returning the same
+ * services every time.
+ *
+ * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
+ * ({@linkcode AccessDeniedError} when no token is sent,
+ * {@linkcode InvalidTokenError} for an invalid/expired token, and
+ * {@linkcode InsufficientScopeError} when scope is lacking); use
+ * {@linkcode handleAuthError} to turn them into RFC 6750 responses.
+ *
+ * @template Client The client entity type.
+ * @template User The resource-owner entity type.
+ * @template S The scope type used for granted/required scope comparisons.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import type { ClientInterface, TokenReaderInterface } from "@udibo/oauth2/server";
+ * import { ResourceServer } from "@udibo/oauth2/server/resource";
+ *
+ * interface User { id: string }
+ *
+ * declare const app: Hono;
+ * declare const tokenService: TokenReaderInterface<ClientInterface, User>;
+ *
+ * const server = new ResourceServer({
+ *   resolve: () => ({ services: { tokenService } }),
+ * });
+ *
+ * app.get("/api/me", async (c) => {
+ *   try {
+ *     const { user } = await server.authenticate(c.req.raw, "identity:read");
+ *     return c.json(user ?? null);
+ *   } catch (error) {
+ *     return server.handleAuthError(error);
+ *   }
+ * });
+ * ```
+ */
+export declare class ResourceServer<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> {
+    #private;
+    /** Scope constructor used to parse and compare scopes. */
+    Scope: ScopeConstructor<S>;
+    /** Protection space named in `WWW-Authenticate` challenges. */
+    realm: string;
+    /** Leeway in seconds applied to the access token's expiry. Defaults to `0`. */
+    clockSkewSeconds: number;
+    /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
+    errorFormat: "oauth2" | "problem-details";
+    /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
+    throwOnError: boolean;
+    /** Resolves the per-request {@link ResourceServerContext}. */
+    protected resolveContext: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
+    /** Creates a resource server from the given {@linkcode ResourceServerOptions}. */
+    constructor(options: ResourceServerOptions<Client, User, S>);
+    /**
+     * Builds a WWW-Authenticate header value per RFC 6750 Section 3.
+     *
+     * The header includes:
+     * - realm: The protection space
+     * - error: The error code (for 401/403 responses)
+     * - error_description: Human-readable error description
+     * - scope: Required scope (for insufficient_scope errors)
+     *
+     * RFC 6750 Section 3.1 registers exactly three challenge codes —
+     * `invalid_request`, `invalid_token`, `insufficient_scope` — so an error
+     * carrying anything else (including the `access_denied` this server raises
+     * when a request presents no credentials at all, which the same section says
+     * MUST NOT be given a code) produces a bare `realm` challenge. Pick the error
+     * class accordingly: a client reads a coded challenge and acts on it, and
+     * {@linkcode InsufficientScopeError} is the one that tells it "your token is
+     * fine, it just lacks scope" rather than sending it off to refresh.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3
+     */
+    buildWwwAuthenticate(error?: OAuth2Error, requiredScope?: string): string;
+    /**
+     * Creates an error response for an OAuth2 error.
+     *
+     * The response body is formatted according to {@link errorFormat}:
+     * - `"oauth2"`: `{ error, error_description?, error_uri? }` as JSON.
+     * - `"problem-details"`: RFC 9457 Problem Details with OAuth2 extensions.
+     *
+     * Does **not** set any response headers beyond `Content-Type`. Any extra
+     * response headers (`WWW-Authenticate`, `Cache-Control`, `Pragma`, …) must
+     * be set on the error via its `headers` property before calling this
+     * method; they are copied through verbatim.
+     */
+    createErrorResponse(error: unknown): Response;
+    /**
+     * Normalizes an error at a handler boundary and either rethrows it (when
+     * {@link throwOnError} is true) or converts it to a response.
+     *
+     * The optional `prepare` callback lets a handler annotate the error —
+     * usually by setting headers like `Cache-Control` or `WWW-Authenticate`
+     * that belong on both the thrown error and the response — before the
+     * throw/respond decision is made.
+     */
+    handleError(error: unknown, prepare?: (error: OAuth2Error) => void): Response;
+    /**
+     * {@link handleError} variant that automatically attaches a
+     * `WWW-Authenticate` header (per RFC 6750 Section 3) when the error's
+     * status is 401 or 403. Use this at bearer-token boundaries to avoid the
+     * boilerplate of building the header for each error response.
+     *
+     * @example
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { ClientInterface } from "@udibo/oauth2/server";
+     * import { ResourceServer } from "@udibo/oauth2/server/resource";
+     *
+     * interface User { id: string }
+     *
+     * declare const app: Hono;
+     * declare const server: ResourceServer<ClientInterface, User>;
+     *
+     * app.get("/api/me", async (c) => {
+     *   try {
+     *     const ctx = await server.authenticate(c.req.raw);
+     *     return c.json(ctx.user ?? null);
+     *   } catch (error) {
+     *     return server.handleAuthError(error);
+     *   }
+     * });
+     * ```
+     */
+    handleAuthError(error: unknown): Response;
+    /**
+     * Extracts an access token from a request.
+     * Looks in the Authorization header (Bearer token) first,
+     * then in the request body for form-encoded requests.
+     */
+    getAccessToken(request: Request): Promise<string | null>;
+    /**
+     * Retrieves and validates a token by access token string.
+     *
+     * The token's expiry is compared against now with {@linkcode
+     * clockSkewSeconds} of leeway, so the same tolerance applies whichever
+     * token reader produced the token.
+     *
+     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
+     *   configured leeway, or revoked
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+     */
+    getToken(accessToken: string, services: ResourceServerServices<Client, User, S>): Promise<Token<Client, User, S>>;
+    /**
+     * Authenticates a request and verifies the token has the required scope.
+     *
+     * @param request The incoming request
+     * @param requiredScope Optional scope required to access the resource
+     * @returns The authenticated context with token, client, user, and scope
+     * @throws {AccessDeniedError} If no token is provided
+     * @throws {InvalidTokenError} If the token is invalid or expired
+     * @throws {InsufficientScopeError} If the token lacks required scope (HTTP 403)
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+     */
+    authenticate(request: Request, requiredScope?: S | string): Promise<AuthenticatedContext<Client, User, S>>;
+    /**
+     * Throws unless the authenticated context satisfies every condition —
+     * the assertion behind the adapters' `require()` middleware, public so a
+     * handler authenticating manually can reuse the same checks.
+     *
+     * Scope conditions go through {@linkcode assertScope}, so their failure is
+     * the same RFC 6750 `insufficient_scope` challenge `requireScope` sends.
+     * Every other condition is answered by the context's
+     * {@linkcode AuthenticatedContext.authorization}; the first unmet one
+     * throws a plain 403 naming the failed check.
+     *
+     * @throws {InsufficientScopeError} If the token lacks a required scope (403,
+     *   `insufficient_scope` challenge).
+     * @throws {InsufficientPermissionsError} If a permission, role, or
+     *   organization condition fails (403, no challenge code).
+     */
+    assertAuthorized(context: AuthenticatedContext<Client, User, S>, conditions: RequireConditions): void;
+    /**
+     * Throws {@link InsufficientScopeError} unless `granted` contains
+     * `requiredScope`. Shared by {@link authenticate} and the adapters'
+     * scope-only guards (`requireScope`) so the comparison and the RFC 6750
+     * error stay identical — a guard that checks an already-authenticated
+     * request's scope (without re-validating the token) calls this with the
+     * context's `scope`. Public so a handler authenticating manually can reuse
+     * the same check.
+     *
+     * @throws {InsufficientScopeError} If `granted` lacks `requiredScope` (403).
+     */
+    assertScope(granted: S | null | undefined, requiredScope: S | string): void;
+}
+export { IntrospectionTokenReader } from "./introspection-token-reader.js";
+export type { IntrospectionTokenReaderOptions } from "./introspection-token-reader.js";
+export { JwksTokenReader } from "./jwks-token-reader.js";
+export type { JwksTokenReaderOptions, JwtAccessTokenClaims, } from "./jwks-token-reader.js";