@haikit/mcp 0.33.0 → 0.34.0

package/dist/oauth.d.ts

@@ -0,0 +1,193 @@
+import { type AuthorizationServerMetadata, type FetchLike, type OAuthClientMetadata, type OAuthDiscoveryState, type StoredOAuthClientInformation, type StoredOAuthTokens } from "@modelcontextprotocol/client";
+import { type Credential } from "./credential.js";
+import { type Sealer } from "./seal.js";
+import type { CredentialStore } from "./store.js";
+/** How long a connect flow lasts: from the connect route to the callback. */
+export declare const FLOW_MS = 600000;
+export interface OAuthServerOptions {
+    /**
+     * The authorization server this server must use, as its metadata's
+     * `issuer`. Strongly advised for a third party's server: a server names its
+     * own authorization server, and one compromised could send users to a fake
+     * sign-in page.
+     */
+    issuer?: string;
+    /** Asked for when connecting. Default: what the server's metadata asks for. */
+    scopes?: string[];
+    /**
+     * A client the app registered with the authorization server. Needs
+     * `issuer`. Without it, one is registered for the app: by its metadata
+     * document's URL where the authorization server takes one, else by dynamic
+     * client registration.
+     */
+    client?: {
+        id: string;
+        secret?: string;
+    };
+}
+/** What every `oauth()` server of one `createMcpAuth` shares. */
+export interface OAuthCore {
+    readonly store: CredentialStore;
+    readonly sealer: Sealer;
+    readonly redirectUri: string;
+    /** What a client is registered with, and the metadata document says. */
+    readonly clientMetadata: OAuthClientMetadata;
+    /** The metadata document's URL, when the redirect URI is https: an OAuth client can then be identified by it. */
+    readonly clientMetadataUrl: string | undefined;
+}
+/** What a user's credential holds, sealed. */
+interface Kept {
+    /** As the authorization server issued them, stamped with its `issuer`. */
+    tokens: StoredOAuthTokens & {
+        issuer: string;
+    };
+    /** The client they were issued to: refreshed and revoked as it, whatever the store keeps for new connects. */
+    client: StoredOAuthClientInformation;
+    /** The scope granted, or asked for when the authorization server didn't say. */
+    scope: string | null;
+    /** When the user connected, epoch ms. A refresh keeps it. */
+    connectedAt: number;
+}
+/** A credential as the store holds it: the sealed value, and what it opened to. */
+interface Held {
+    sealed: string;
+    kept: Kept;
+}
+/** A connect flow on its way, sealed in the store under its `state`. */
+export interface Flow {
+    user: string;
+    server: string;
+    /** The conversation it came from, if the user owns it: `onConnected` is told. */
+    conversation: string | null;
+    /** The PKCE verifier. */
+    verifier: string;
+    /** The client the code is issued to: exchanged as it, though another connect replaced the one the store keeps. */
+    client: StoredOAuthClientInformation;
+    /** The SDK's discovery state, from the connect route: the callback is bound to its authorization server. */
+    discovery: OAuthDiscoveryState;
+    /** The scope asked for. */
+    scope: string | null;
+    expiresAt: number;
+}
+/** A server's authorization server, as discovered and checked. */
+interface Where {
+    url: string;
+    issuer: string;
+    metadata: AuthorizationServerMetadata | undefined;
+    /** The RFC 8707 resource indicator: tokens are bound to this server. */
+    resource: string | undefined;
+}
+/** Loopback hosts, exempt from https: what the SDK exempts, and RFC 8252 does. */
+export declare const isLoopback: (host: string) => boolean;
+/** https, or http on this machine. */
+export declare const isSecure: (url: string | URL) => boolean;
+/** The connect flow a `state` names, once: null if there's none, it has expired, or it doesn't open. */
+export declare function takeFlow(core: OAuthCore, state: string): Promise<Flow | null>;
+/**
+ * One server's OAuth: its connect route and callback, each user's
+ * credential, refreshing, and revoking on disconnect.
+ */
+export declare class OAuthServer {
+    readonly core: OAuthCore;
+    private readonly options;
+    readonly name: string;
+    private readonly url;
+    private readonly baseFetch;
+    readonly timeoutMs: number;
+    /** Closes the user's connection to this server, so their next call dials with what's stored now. */
+    readonly forget: (userId: string) => Promise<void>;
+    /** The authorization server, discovered on the first refresh or revocation, or seeded by a callback. */
+    private found;
+    /** Each user's refresh on its way, which every 401 of theirs shares until it settles. */
+    private readonly refreshing;
+    constructor(core: OAuthCore, options: OAuthServerOptions, name: string, url: URL, baseFetch: FetchLike, timeoutMs: number, 
+    /** Closes the user's connection to this server, so their next call dials with what's stored now. */
+    forget: (userId: string) => Promise<void>);
+    /** Every request to the authorization server, bounded by `timeoutMs`. */
+    readonly fetch: FetchLike;
+    credential(user: string): Credential;
+    /** A user's credential as the store holds it, or null if there's none, or none that opens. `known` is given back as it is if the store still holds it. */
+    read(user: string, known?: Held | null): Promise<Held | null>;
+    seal(user: string, kept: Kept): string;
+    /** The client configured, stamped with the pinned issuer: the SDK refuses it for any other. */
+    private configured;
+    /**
+     * The client to connect with at an authorization server: the one
+     * configured, or the one registered for the app. One registered for
+     * another redirect URI or metadata document, or that doesn't open, is no
+     * use, and is registered again.
+     */
+    private client;
+    /** The client a flow or credential was issued to, as it's sent: the configured one with its secret as configured now. */
+    issuedTo(client: StoredOAuthClientInformation): StoredOAuthClientInformation;
+    private saveClient;
+    /**
+     * Checks what discovery found: the pinned issuer, and an authorization
+     * endpoint the browser can be sent to. Called by the SDK straight after
+     * discovery, before it looks up or registers a client, so a server that
+     * names another authorization server gets nothing from the app.
+     */
+    check(state: OAuthDiscoveryState): Promise<Where>;
+    /**
+     * The authorization server, which must be the one that issued a credential:
+     * found again once if it isn't, in case the server moved since.
+     */
+    where(issuer: string, resourceMetadataUrl?: URL): Promise<Where>;
+    /**
+     * The connect route: where to send the browser, with the flow stored under
+     * its `state` meanwhile. The SDK's `auth()` discovers the authorization
+     * server, registers a client if none is kept, and makes the PKCE challenge.
+     */
+    start(user: string, conversation: string | null, asked: string | undefined): Promise<URL>;
+    /**
+     * The callback: exchanges the code with the authorization server and as
+     * the client the flow was started with, which checks `iss` (RFC 9207)
+     * before it asks for any token, stores the credential, and closes the
+     * user's connection.
+     */
+    finish(flow: Flow, code: string, iss: string | undefined): Promise<void>;
+    /** Revokes the user's tokens where the authorization server takes it, then deletes them and closes the connection. */
+    disconnect(user: string): Promise<void>;
+    /** RFC 7009, at the authorization server's revocation endpoint, if it has one. */
+    private revoke;
+    /**
+     * After a 401: the credential to use instead of `before`. One refresh for
+     * each user at a time, shared until it settles, however long that takes,
+     * on whichever connection of theirs: a second would spend a refresh token
+     * the first may have spent already, and delete the credential when it's
+     * refused. Across processes, the store's lease does the same.
+     */
+    refresh(user: string, before: Held, resourceMetadataUrl: URL | undefined): Promise<Held>;
+    /**
+     * The store's newer credential if another refresh wrote one, else a
+     * refresh of `before`, under the store's lease. A refusal deletes it,
+     * unless another write came first; an outage keeps it.
+     */
+    private renew;
+    /**
+     * Writes a refresh's credential onto `before`, tried again while the
+     * store fails: the old refresh token is spent, so this is the only copy,
+     * and the lease is still held. False if another write or a delete came
+     * first. A try that landed, though its answer was lost, is written.
+     */
+    private write;
+    /**
+     * Revokes the tokens a refresh got but couldn't store: its refresh token
+     * if the authorization server rotated it, else only its access token, as
+     * the one refresh token may be what the store holds now.
+     */
+    private orphaned;
+    /**
+     * Takes the refresh lease of the user's credential, so one process at a
+     * time spends its refresh token. While another holds it: the credential
+     * that one writes, which is then the one to use, or the lease once it
+     * lapses, as it does when that process is gone.
+     */
+    private lease;
+    /** The store's credential if it's newer than `before`, or null if it's still `before`. With none, the server's refusal stands. */
+    private newer;
+    /** Deletes the credential, if the store still holds `before`: never a newer one. */
+    private drop;
+}
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}