@adonis-agora/agent
Version:
Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.
59 lines • 3.51 kB
TypeScript
/**
* The OAuth discovery surface of the MCP server (MCP Authorization spec, RFC 9728, RFC 6750 §3): the
* protected-resource metadata document, its well-known URL, and the `WWW-Authenticate` challenge a
* `401`/`403` carries so an MCP client knows where to start the login.
*
* Pure functions over strings — the provider decides which origin to feed them (the configured
* `publicUrl`, or the request's own protocol and `Host` as a fallback).
*/
import type { McpOAuthMetadata } from './auth.js';
/** Normalize a route prefix the way the provider mounts it: no leading/trailing slashes. */
export declare function normalizeMcpPath(path: string | undefined): string;
/**
* Validate `publicUrl` from `config/mcp.ts` and reduce it to its origin (`https://app.example.com`).
* Only an origin is meaningful: the MCP endpoint and its well-known document are mounted at fixed
* paths on this app, so a path, query, or fragment would advertise URLs the app does not serve.
*/
export declare function publicOrigin(publicUrl: string): string;
/** The protected resource (RFC 9728 `resource`): the URL an MCP client points at, e.g. `https://app.example.com/mcp`. */
export declare function mcpResourceUrl(origin: string, path: string): string;
/** Where the protected-resource metadata lives (RFC 9728 §3.1): the well-known segment goes between host and path. */
export declare function protectedResourceMetadataUrl(origin: string, path: string): string;
/** The RFC 9728 protected-resource metadata document. */
export interface ProtectedResourceMetadata {
resource: string;
authorization_servers: string[];
scopes_supported: string[];
bearer_methods_supported: string[];
resource_name: string;
}
/**
* The Poppy issuer `@adonis-agora/authkit-server` announces in `Symbol.for('@adonis-agora/poppy:issuer')`
* when Personal Agent Protocol is on — Poppy §6 requires a listed MCP server's `authorization_servers`
* to include it, so a Poppy Session Token's issuer is one this server names.
*/
export declare function announcedPoppyIssuer(): string | undefined;
/**
* Build the RFC 9728 document for the MCP endpoint at `origin` + `path`. Its `authorization_servers`
* is the configured issuer, plus the Poppy issuer when one is announced (and different).
*/
export declare function protectedResourceMetadata(meta: McpOAuthMetadata, origin: string, path: string): ProtectedResourceMetadata;
/** Options for {@link wwwAuthenticateChallenge}. */
export interface WwwAuthenticateOptions {
/**
* The RFC 6750 error code. `invalid_token` when the request carried a token that was refused,
* `insufficient_scope` for a `403`, omitted when no token was sent at all (RFC 6750 §3.1).
*/
error?: 'invalid_token' | 'insufficient_scope' | 'sign_in_required';
/** The metadata URL (RFC 9728 §5.1). Set only when the auth strategy exposes OAuth metadata. */
resourceMetadataUrl?: string;
/** With `insufficient_scope`: the scopes the request needs (RFC 6750 §3), space-separated. */
scope?: string;
}
/**
* The `WWW-Authenticate` value for a `401`/`403` from the MCP endpoint — e.g.
* `Bearer error="invalid_token", resource_metadata="https://app.example.com/.well-known/oauth-protected-resource/mcp"`.
* `resource_metadata` is what makes an MCP client discover the authorization server and open the login.
*/
export declare function wwwAuthenticateChallenge(options?: WwwAuthenticateOptions): string;
//# sourceMappingURL=discovery.d.ts.map