@frontmcp/sdk 0.1.0

package/src/interfaces/auth-hook.interface.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Lifecycle stages for auth invocation.
+ *
+ * Ordering notes:
+ * - "will*" stages run before the action; "did*" stages run after.
+ * - Higher `priority()` runs earlier for "will*" (outermost), and later for "did*".
+ * - Finalization stages (`willFinalize`, `willAudit`, `didAudit`, `onMetrics`) should be placed
+ *   in your plan’s `finalize` array to run on both success and error paths.
+ *
+ * Control flow:
+ * - Hooks may call `ctx.respond(value)` to short-circuit with a return value.
+ * - Hooks may call `ctx.abort(reason, code?, httpStatus?)` to stop with an error.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthHookStage = void 0;
+var AuthHookStage;
+(function (AuthHookStage) {
+    /** Prepare a new session (or re-register an incoming secureJwt).
+     * Responsibilities:
+     * - Validate incoming token (if any); compute defaults; attach user hints.
+     * - Initialize per-session resources and attach to `ctx.data`.
+     * Failure modes:
+     * - `ctx.abort('invalid jwt', 'INVALID_SESSION', 401)`.
+     */
+    AuthHookStage["willCreateSession"] = "willCreateSession";
+    /** Session created and registered.
+     * Responsibilities:
+     * - Announce readiness (mount handlers/streams), emit side-effects if needed.
+     * - Optionally shape `ctx.output` with a `SessionContextView`.
+     */
+    AuthHookStage["didCreateSession"] = "didCreateSession";
+    /** Bind DI providers needed for this session/request.
+     * Responsibilities:
+     * - Resolve and bind providers so later hooks can `ctx.get(...)`.
+     * - May set `ctx.bindProvider/bindProviders` helpers.
+     */
+    AuthHookStage["willBindProviders"] = "willBindProviders";
+    // ---------- Auth (within a session) ----------
+    /** Signal the beginning of an auth sequence in the scope of this session.
+     * Responsibilities:
+     * - Initialize auth-related state (PKCE/state, CSRF, telemetry).
+     * - Decide transport (SSE/StreamableHTTP) for status/URL events if applicable.
+     */
+    AuthHookStage["willBeginAuth"] = "willBeginAuth";
+    /** Streamable authorization progress within the session.
+     * Responsibilities:
+     * - Emit URL/status events (e.g., “authorize_url”, “awaiting_callback”).
+     * - Optionally `ctx.respond({event: ...})` for push-style transports.
+     */
+    AuthHookStage["willAuthorize"] = "willAuthorize";
+    /** Prepare and gate the token exchange with the provider.
+     * Responsibilities:
+     * - Verify callback params; ensure prerequisites (sessionId present).
+     * - Compute exchange request; rate-limit/anti-replay checks.
+     * Failure modes:
+     * - `ctx.abort('invalid state/pkce', 'OAUTH_CALLBACK_ERROR', 400)`.
+     */
+    AuthHookStage["willExchangeToken"] = "willExchangeToken";
+    /** SecureMcp JWT has been minted/confirmed for this session.
+     * Responsibilities:
+     * - React to issuance (e.g., persist session claims, notify listeners).
+     * Notes:
+     * - Fired once the session’s secureJwt is known; avoid logging secrets.
+     */
+    AuthHookStage["didIssueSecureJwt"] = "didIssueSecureJwt";
+    /** Encrypt and store provider tokens for this session.
+     * Responsibilities:
+     * - Write encrypted blobs to the session record (per provider).
+     * - Derive minimal metadata (scopes/expiry) for later claims-only exposure.
+     */
+    AuthHookStage["willStoreTokens"] = "willStoreTokens";
+    // ---------- Access (read path) ----------
+    /** Authorize and prepare a session read.
+     * Responsibilities:
+     * - Validate access to the session; attach read-scoped providers if required.
+     * - Optionally shape a partial view before execute.
+     */
+    AuthHookStage["willGetSession"] = "willGetSession";
+    /** Post-process the session view.
+     * Responsibilities:
+     * - Redact/transform/derive fields for the final response.
+     * - Set `ctx.output` to a `SessionContextView`.
+     */
+    AuthHookStage["didGetSession"] = "didGetSession";
+    // ---------- Disposal ----------
+    /** Announce shutdown and allow flush/cleanup.
+     * Responsibilities:
+     * - Close streams, unsubscribe listeners, schedule disposers.
+     */
+    AuthHookStage["willDisposeSession"] = "willDisposeSession";
+    /** Confirm teardown and emit metrics.
+     * Responsibilities:
+     * - Final confirmation of resource release; summarize outcome.
+     */
+    AuthHookStage["didDisposeSession"] = "didDisposeSession";
+    // ---------- Finalize / audit / metrics / errors ----------
+    /** Optional “late finally” hook if you need a single place before audit/metrics.
+     * Responsibilities:
+     * - Last-chance cleanup across success/error paths (idempotent, non-throwing).
+     * Notes:
+     * - Include this stage in your plan’s `finalize` array to activate.
+     */
+    AuthHookStage["willFinalize"] = "willFinalize";
+    /** Centralized error handler.
+     * Responsibilities:
+     * - Redact sensitive data; map internal errors to public codes.
+     * - Optionally `ctx.respond({ error })` or `ctx.abort(...)`.
+     * Notes:
+     * - Should not throw; runs before audit/metrics finalize.
+     */
+    AuthHookStage["onError"] = "onError";
+    /** Pre-audit collection on both success and error paths.
+     * Responsibilities:
+     * - Build audit envelope (actor, sessionId, providers touched).
+     * - Normalize and strip secrets (no raw tokens).
+     */
+    AuthHookStage["willAudit"] = "willAudit";
+    /** Persist/emit the audit record.
+     * Responsibilities:
+     * - Write to audit sink(s) with outcome and timings.
+     * - Correlate via `ctx.requestId`/`ctx.sessionId`.
+     */
+    AuthHookStage["didAudit"] = "didAudit";
+    /** Telemetry/metrics emission for both success and errors.
+     * Responsibilities:
+     * - Counters & timings (create/get/dispose/auth/exchange/store).
+     * - Error code/tag cardinality kept small for SLOs/alerts.
+     * Constraints:
+     * - Non-throwing; must not alter control flow.
+     */
+    AuthHookStage["onMetrics"] = "onMetrics";
+})(AuthHookStage || (exports.AuthHookStage = AuthHookStage = {}));
+//# sourceMappingURL=auth-hook.interface.js.map

package/src/interfaces/auth-hook.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-hook.interface.js","sourceRoot":"","sources":["../../../src/interfaces/auth-hook.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,IAAY,aAwIX;AAxID,WAAY,aAAa;IACvB;;;;;;OAMG;IACH,wDAAuC,CAAA;IAGvC;;;;OAIG;IACH,sDAAqC,CAAA;IAErC;;;;OAIG;IACH,wDAAuC,CAAA;IAEvC,gDAAgD;IAEhD;;;;OAIG;IACH,gDAA+B,CAAA;IAE/B;;;;OAIG;IACH,gDAA+B,CAAA;IAE/B;;;;;;OAMG;IACH,wDAAuC,CAAA;IAEvC;;;;;OAKG;IACH,wDAAuC,CAAA;IAEvC;;;;OAIG;IACH,oDAAmC,CAAA;IAEnC,2CAA2C;IAE3C;;;;OAIG;IACH,kDAAiC,CAAA;IAEjC;;;;OAIG;IACH,gDAA+B,CAAA;IAE/B,iCAAiC;IAEjC;;;OAGG;IACH,0DAAyC,CAAA;IAEzC;;;OAGG;IACH,wDAAuC,CAAA;IAEvC,4DAA4D;IAE5D;;;;;OAKG;IACH,8CAA6B,CAAA;IAE7B;;;;;;OAMG;IACH,oCAAmB,CAAA;IAEnB;;;;OAIG;IACH,wCAAuB,CAAA;IAEvB;;;;OAIG;IACH,sCAAqB,CAAA;IAErB;;;;;;OAMG;IACH,wCAAuB,CAAA;AACzB,CAAC,EAxIW,aAAa,6BAAb,aAAa,QAwIxB","sourcesContent":["/**\n * Lifecycle stages for auth invocation.\n *\n * Ordering notes:\n * - \"will*\" stages run before the action; \"did*\" stages run after.\n * - Higher `priority()` runs earlier for \"will*\" (outermost), and later for \"did*\".\n * - Finalization stages (`willFinalize`, `willAudit`, `didAudit`, `onMetrics`) should be placed\n *   in your plan’s `finalize` array to run on both success and error paths.\n *\n * Control flow:\n * - Hooks may call `ctx.respond(value)` to short-circuit with a return value.\n * - Hooks may call `ctx.abort(reason, code?, httpStatus?)` to stop with an error.\n *\n */\n\nexport enum AuthHookStage {\n  /** Prepare a new session (or re-register an incoming secureJwt).\n   * Responsibilities:\n   * - Validate incoming token (if any); compute defaults; attach user hints.\n   * - Initialize per-session resources and attach to `ctx.data`.\n   * Failure modes:\n   * - `ctx.abort('invalid jwt', 'INVALID_SESSION', 401)`.\n   */\n  willCreateSession = 'willCreateSession',\n\n\n  /** Session created and registered.\n   * Responsibilities:\n   * - Announce readiness (mount handlers/streams), emit side-effects if needed.\n   * - Optionally shape `ctx.output` with a `SessionContextView`.\n   */\n  didCreateSession = 'didCreateSession',\n\n  /** Bind DI providers needed for this session/request.\n   * Responsibilities:\n   * - Resolve and bind providers so later hooks can `ctx.get(...)`.\n   * - May set `ctx.bindProvider/bindProviders` helpers.\n   */\n  willBindProviders = 'willBindProviders',\n\n  // ---------- Auth (within a session) ----------\n\n  /** Signal the beginning of an auth sequence in the scope of this session.\n   * Responsibilities:\n   * - Initialize auth-related state (PKCE/state, CSRF, telemetry).\n   * - Decide transport (SSE/StreamableHTTP) for status/URL events if applicable.\n   */\n  willBeginAuth = 'willBeginAuth',\n\n  /** Streamable authorization progress within the session.\n   * Responsibilities:\n   * - Emit URL/status events (e.g., “authorize_url”, “awaiting_callback”).\n   * - Optionally `ctx.respond({event: ...})` for push-style transports.\n   */\n  willAuthorize = 'willAuthorize', // stream-able events (URL/status)\n\n  /** Prepare and gate the token exchange with the provider.\n   * Responsibilities:\n   * - Verify callback params; ensure prerequisites (sessionId present).\n   * - Compute exchange request; rate-limit/anti-replay checks.\n   * Failure modes:\n   * - `ctx.abort('invalid state/pkce', 'OAUTH_CALLBACK_ERROR', 400)`.\n   */\n  willExchangeToken = 'willExchangeToken',\n\n  /** SecureMcp JWT has been minted/confirmed for this session.\n   * Responsibilities:\n   * - React to issuance (e.g., persist session claims, notify listeners).\n   * Notes:\n   * - Fired once the session’s secureJwt is known; avoid logging secrets.\n   */\n  didIssueSecureJwt = 'didIssueSecureJwt',\n\n  /** Encrypt and store provider tokens for this session.\n   * Responsibilities:\n   * - Write encrypted blobs to the session record (per provider).\n   * - Derive minimal metadata (scopes/expiry) for later claims-only exposure.\n   */\n  willStoreTokens = 'willStoreTokens',\n\n  // ---------- Access (read path) ----------\n\n  /** Authorize and prepare a session read.\n   * Responsibilities:\n   * - Validate access to the session; attach read-scoped providers if required.\n   * - Optionally shape a partial view before execute.\n   */\n  willGetSession = 'willGetSession',\n\n  /** Post-process the session view.\n   * Responsibilities:\n   * - Redact/transform/derive fields for the final response.\n   * - Set `ctx.output` to a `SessionContextView`.\n   */\n  didGetSession = 'didGetSession',\n\n  // ---------- Disposal ----------\n\n  /** Announce shutdown and allow flush/cleanup.\n   * Responsibilities:\n   * - Close streams, unsubscribe listeners, schedule disposers.\n   */\n  willDisposeSession = 'willDisposeSession',\n\n  /** Confirm teardown and emit metrics.\n   * Responsibilities:\n   * - Final confirmation of resource release; summarize outcome.\n   */\n  didDisposeSession = 'didDisposeSession',\n\n  // ---------- Finalize / audit / metrics / errors ----------\n\n  /** Optional “late finally” hook if you need a single place before audit/metrics.\n   * Responsibilities:\n   * - Last-chance cleanup across success/error paths (idempotent, non-throwing).\n   * Notes:\n   * - Include this stage in your plan’s `finalize` array to activate.\n   */\n  willFinalize = 'willFinalize',\n\n  /** Centralized error handler.\n   * Responsibilities:\n   * - Redact sensitive data; map internal errors to public codes.\n   * - Optionally `ctx.respond({ error })` or `ctx.abort(...)`.\n   * Notes:\n   * - Should not throw; runs before audit/metrics finalize.\n   */\n  onError = 'onError',\n\n  /** Pre-audit collection on both success and error paths.\n   * Responsibilities:\n   * - Build audit envelope (actor, sessionId, providers touched).\n   * - Normalize and strip secrets (no raw tokens).\n   */\n  willAudit = 'willAudit',\n\n  /** Persist/emit the audit record.\n   * Responsibilities:\n   * - Write to audit sink(s) with outcome and timings.\n   * - Correlate via `ctx.requestId`/`ctx.sessionId`.\n   */\n  didAudit = 'didAudit',\n\n  /** Telemetry/metrics emission for both success and errors.\n   * Responsibilities:\n   * - Counters & timings (create/get/dispose/auth/exchange/store).\n   * - Error code/tag cardinality kept small for SLOs/alerts.\n   * Constraints:\n   * - Non-throwing; must not alter control flow.\n   */\n  onMetrics = 'onMetrics',\n}\n"]}

package/src/interfaces/auth-provider.interface.d.ts

@@ -0,0 +1,22 @@
+import { Type, Token, ClassType, ValueType, FactoryType, ClassToken } from './base.interface';
+import { AuthProviderMetadata } from '../metadata';
+export interface AuthProviderInterface {
+    headers(): Record<string, string>;
+    refreshToken?(): Promise<string | undefined>;
+}
+export type AuthProviderClassType<Provide> = ClassType<Provide> & AuthProviderMetadata;
+export type AuthProviderValueType<Provide> = ValueType<Provide> & AuthProviderMetadata;
+export type AuthProviderFactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> = FactoryType<Provide, Tokens> & AuthProviderMetadata;
+export type AuthProviderType<Provide extends AuthProviderInterface = any, Tokens extends readonly (ClassToken | Token)[] = readonly (ClassToken | Token)[]> = Type<Provide> | AuthProviderClassType<Provide> | AuthProviderValueType<Provide> | AuthProviderFactoryType<Provide, Tokens>;
+/**
+ * Helper to define factory providers without tuple widening.
+ * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).
+ *
+ * Usage:
+ *   const p = AsyncMcpProvider({
+ *     provide: RedisProviderRef,
+ *     inject: () => [ExpenseConfigRef, RedisType] as const,
+ *     useFactory: async (config, redis) => new RedisProvider(redis),
+ *   });
+ */
+export declare function AsyncAuthProvider<Provide, const Tokens extends readonly (ClassToken | Token)[]>(cfg: AuthProviderFactoryType<Provide, Tokens>): AuthProviderFactoryType<Provide, Tokens>;

package/src/interfaces/auth-provider.interface.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncAuthProvider = AsyncAuthProvider;
+/**
+ * Helper to define factory providers without tuple widening.
+ * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).
+ *
+ * Usage:
+ *   const p = AsyncMcpProvider({
+ *     provide: RedisProviderRef,
+ *     inject: () => [ExpenseConfigRef, RedisType] as const,
+ *     useFactory: async (config, redis) => new RedisProvider(redis),
+ *   });
+ */
+function AsyncAuthProvider(cfg) {
+    return cfg;
+}
+//# sourceMappingURL=auth-provider.interface.js.map

package/src/interfaces/auth-provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.interface.js","sourceRoot":"","sources":["../../../src/interfaces/auth-provider.interface.ts"],"names":[],"mappings":";;AAuCA,8CAIC;AAfD;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAC/B,GAA6C;IAE7C,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import { Type, Token, ClassType, ValueType, FactoryType, ClassToken } from './base.interface';\nimport { AuthProviderMetadata } from '../metadata';\n\n\nexport interface AuthProviderInterface {\n  headers(): Record<string, string>;\n\n  refreshToken?(): Promise<string | undefined>;\n}\n\n\nexport type AuthProviderClassType<Provide> = ClassType<Provide> & AuthProviderMetadata;\nexport type AuthProviderValueType<Provide> = ValueType<Provide> & AuthProviderMetadata;\nexport type AuthProviderFactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> =\n  FactoryType<Provide, Tokens>\n  & AuthProviderMetadata;\n\n\nexport type AuthProviderType<\n  Provide extends AuthProviderInterface = any,\n  Tokens extends readonly (ClassToken | Token)[] = readonly (ClassToken | Token)[]\n> =\n  | Type<Provide>\n  | AuthProviderClassType<Provide>\n  | AuthProviderValueType<Provide>\n  | AuthProviderFactoryType<Provide, Tokens>\n\n\n/**\n * Helper to define factory providers without tuple widening.\n * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).\n *\n * Usage:\n *   const p = AsyncMcpProvider({\n *     provide: RedisProviderRef,\n *     inject: () => [ExpenseConfigRef, RedisType] as const,\n *     useFactory: async (config, redis) => new RedisProvider(redis),\n *   });\n */\nexport function AsyncAuthProvider<Provide, const Tokens extends readonly (ClassToken | Token)[]>(\n  cfg: AuthProviderFactoryType<Provide, Tokens>,\n): AuthProviderFactoryType<Provide, Tokens> {\n  return cfg;\n}\n"]}

package/src/interfaces/base.interface.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Constructor type for a concrete class that produces instances of T.
+ *
+ * Useful anywhere a factory/DI container expects a class reference that can be
+ * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.
+ */
+export interface Type<T = unknown> extends Function {
+    new (...args: any[]): T;
+}
+/**
+ * Constructor type for a concrete class that produces instances of T.
+ *
+ * Useful anywhere a factory/DI container expects a class reference that can be
+ * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.
+ */
+export type FuncType<T> = (...args: any[]) => any | Promise<any>;
+export type PartialStagesType<T extends string> = Partial<Record<T, Type[]>>;
+/**
+ * Empty Constructor type for a concrete class that produces instances of T.
+ *
+ * Useful anywhere a factory/DI container expects a class reference that can be
+ * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.
+ */
+export interface CtorType<T = unknown> extends Function {
+    new (): T;
+}
+export type Ctor<T> = new (...args: any[]) => T;
+/**
+ * Shape of an abstract class (or interface-like constructor) whose instances
+ * cannot be created directly but still expose a prototype of T.
+ *
+ * This is handy when accepting references that may point at abstract bases
+ * instead of concrete implementors.
+ */
+export interface Abstract<T> extends Function {
+    prototype: T;
+}
+/**
+ * A reference token that may be used to look up or identify a dependency.
+ *
+ * Typical usages:
+ * - string | symbol: named tokens (e.g., provider IDs like "provider:redis").
+ * - Type<T>: a concrete class constructor (can be instantiated).
+ * - Abstract<T>: an abstract base reference (resolved to a concrete impl).
+ * - Function: generic function references when needed.
+ */
+export type Reference<T = unknown> = string | symbol | Type<T> | Abstract<T> | Function;
+/** A DI token that can be either a class constructor or a logical reference. */
+export type Token<T = any> = Type<T> | Reference<T>;
+export interface ClassType<Provide> {
+    provide: Reference<Provide>;
+    useClass: Type<Provide>;
+}
+export interface ValueType<Provide> {
+    provide: Reference<Provide>;
+    useValue: Provide;
+}
+/** Map a tuple of tokens to a tuple of their instance types (order preserved). */
+export type ClassToken<T = any> = abstract new (...a: any) => T;
+/** 2) Map tokens -> runtime parameter types **/
+type ResolveToken<T> = T extends ClassToken<infer R> ? R : T extends symbol & {
+    readonly __di_type?: infer R;
+} ? R : never;
+type ResolveTokens<Tokens extends readonly unknown[]> = {
+    [K in keyof Tokens]: Tokens[K] extends Token<infer R> ? R : ResolveToken<Tokens[K]>;
+};
+type Mutable<T extends readonly unknown[]> = {
+    -readonly [K in keyof T]: T[K];
+};
+/** 3) FactoryType with correct useFactory shape **/
+export interface FactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> {
+    provide: Reference<Provide>;
+    inject: () => Tokens;
+    useFactory: (...args: Mutable<ResolveTokens<Tokens>>) => Provide | Promise<Provide>;
+}
+export type RequiredByKey<T, K extends keyof T> = T & Required<Omit<T, K>>;
+export {};

package/src/interfaces/base.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=base.interface.js.map

package/src/interfaces/base.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.interface.js","sourceRoot":"","sources":["../../../src/interfaces/base.interface.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Constructor type for a concrete class that produces instances of T.\n *\n * Useful anywhere a factory/DI container expects a class reference that can be\n * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.\n */\nexport interface Type<T = unknown> extends Function {\n  new(...args: any[]): T;\n}\n\n/**\n * Constructor type for a concrete class that produces instances of T.\n *\n * Useful anywhere a factory/DI container expects a class reference that can be\n * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.\n */\nexport type FuncType<T> = (...args: any[]) => any | Promise<any>;\n\n\nexport type PartialStagesType<T extends string> = Partial<Record<T, Type[]>>;\n\n/**\n * Empty Constructor type for a concrete class that produces instances of T.\n *\n * Useful anywhere a factory/DI container expects a class reference that can be\n * `new`-ed. For example: `getProvider(UserRepo as Type<UserRepo>)`.\n */\nexport interface CtorType<T = unknown> extends Function {\n  new(): T;\n}\n\nexport type Ctor<T> = new (...args: any[]) => T;\n\n/**\n * Shape of an abstract class (or interface-like constructor) whose instances\n * cannot be created directly but still expose a prototype of T.\n *\n * This is handy when accepting references that may point at abstract bases\n * instead of concrete implementors.\n */\nexport interface Abstract<T> extends Function {\n  prototype: T;\n}\n\n/**\n * A reference token that may be used to look up or identify a dependency.\n *\n * Typical usages:\n * - string | symbol: named tokens (e.g., provider IDs like \"provider:redis\").\n * - Type<T>: a concrete class constructor (can be instantiated).\n * - Abstract<T>: an abstract base reference (resolved to a concrete impl).\n * - Function: generic function references when needed.\n */\nexport type Reference<T = unknown> = string | symbol | Type<T> | Abstract<T> | Function;\n\n/** A DI token that can be either a class constructor or a logical reference. */\nexport type Token<T = any> = Type<T> | Reference<T>;\n\n\nexport interface ClassType<Provide> {\n  provide: Reference<Provide>;\n  useClass: Type<Provide>;\n}\n\nexport interface ValueType<Provide> {\n  provide: Reference<Provide>;\n  useValue: Provide;\n}\n\n/** Map a tuple of tokens to a tuple of their instance types (order preserved). */\n\nexport type ClassToken<T = any> = abstract new (...a: any) => T;\n// Branded symbol token that carries the payload type T\n\n// export type Resolve<Tokens extends readonly Token[]> = {\n//   [K in keyof Tokens]: Tokens[K] extends Token<infer R> ? R : never;\n// };\n\n/** 2) Map tokens -> runtime parameter types **/\ntype ResolveToken<T> =\n  T extends ClassToken<infer R> ? R\n  : T extends symbol & { readonly __di_type?: infer R } ? R\n  : never;\n\ntype ResolveTokens<Tokens extends readonly unknown[]> = {\n  [K in keyof Tokens]: Tokens[K] extends Token<infer R> ? R : ResolveToken<Tokens[K]>;\n};\n\n// Rest parameters can't be readonly tuples; strip readonly.\ntype Mutable<T extends readonly unknown[]> = { -readonly [K in keyof T]: T[K] };\n\n/** 3) FactoryType with correct useFactory shape **/\nexport interface FactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> {\n  provide: Reference<Provide>;\n  inject: () => Tokens;\n  useFactory: (...args: Mutable<ResolveTokens<Tokens>>) => Provide | Promise<Provide>;\n}\n\n\n\nexport type RequiredByKey<T, K extends keyof T> = T & Required<Omit<T, K>>;\n"]}

package/src/interfaces/flow.interface.d.ts

@@ -0,0 +1,38 @@
+import { Token, Type } from './base.interface';
+import { FlowMetadata, FlowName } from '../metadata';
+import { z } from 'zod';
+import { ScopeEntry } from '../entries';
+import { FlowStateOf } from './internal/flow.utils';
+import { FrontMcpLogger } from "./logger.interface";
+export type FlowInputOf<N extends FlowName> = z.infer<ExtendFlows[N]['input']>;
+export type FlowOutputOf<N extends FlowName> = z.infer<ExtendFlows[N]['output']>;
+export type FlowPlanOf<N extends FlowName> = ExtendFlows[N]['plan'];
+export type FlowCtxOf<N extends FlowName> = ExtendFlows[N]['ctx'];
+export type FlowControlType = 'respond' | 'fail' | 'abort' | 'next' | 'handled';
+export declare class FlowControl extends Error {
+    readonly type: FlowControlType;
+    readonly output: any;
+    constructor(type: FlowControlType, output: any);
+    static respond<T>(output: T): never;
+    static next(): never;
+    static handled(): never;
+    static fail(error: Error): never;
+    static abort(reason: string): never;
+}
+export declare abstract class FlowBase<N extends FlowName = FlowName> {
+    protected readonly metadata: FlowMetadata<N>;
+    protected readonly rawInput: Partial<FlowInputOf<N>> | any;
+    protected readonly scope: ScopeEntry;
+    protected readonly deps: ReadonlyMap<Token, unknown>;
+    protected input: FlowInputOf<N>;
+    state: FlowStateOf<N>;
+    scopeLogger: FrontMcpLogger;
+    constructor(metadata: FlowMetadata<N>, rawInput: Partial<FlowInputOf<N>> | any, scope: ScopeEntry, deps?: ReadonlyMap<Token, unknown>);
+    get<T>(token: Token<T>): T;
+    protected respond(output: FlowOutputOf<N>): void;
+    protected fail(error: Error): void;
+    protected abort(message: string): void;
+    protected next(): void;
+    protected handled(): void;
+}
+export type FlowType<Provide = FlowBase<FlowName>> = Type<Provide>;

package/src/interfaces/flow.interface.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowBase = exports.FlowControl = void 0;
+const flow_utils_1 = require("./internal/flow.utils");
+class FlowControl extends Error {
+    type;
+    output;
+    constructor(type, output) {
+        super();
+        this.type = type;
+        this.output = output;
+    }
+    static respond(output) {
+        throw new FlowControl('respond', output);
+    }
+    static next() {
+        throw new FlowControl('next', null);
+    }
+    static handled() {
+        throw new FlowControl('handled', null);
+    }
+    static fail(error) {
+        throw new FlowControl('fail', error);
+    }
+    static abort(reason) {
+        throw new FlowControl('abort', reason);
+    }
+}
+exports.FlowControl = FlowControl;
+// 1) The actual abstract class (value)
+class FlowBase {
+    metadata;
+    rawInput;
+    scope;
+    deps;
+    input;
+    state = flow_utils_1.FlowState.create({});
+    scopeLogger;
+    constructor(metadata, rawInput, scope, deps = new Map()) {
+        this.metadata = metadata;
+        this.rawInput = rawInput;
+        this.scope = scope;
+        this.deps = deps;
+        this.input = metadata.inputSchema?.parse?.(rawInput);
+        this.scopeLogger = scope.logger;
+    }
+    get(token) {
+        if (this.deps.has(token))
+            return this.deps.get(token);
+        return this.scope.providers.get(token);
+    }
+    respond(output) {
+        throw FlowControl.respond(this.metadata.outputSchema.parse(output));
+    }
+    fail(error) {
+        throw FlowControl.fail(error);
+    }
+    abort(message) {
+        throw FlowControl.abort(message);
+    }
+    next() {
+        throw FlowControl.next();
+    }
+    handled() {
+        throw FlowControl.handled();
+    }
+}
+exports.FlowBase = FlowBase;
+//# sourceMappingURL=flow.interface.js.map

package/src/interfaces/flow.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.interface.js","sourceRoot":"","sources":["../../../src/interfaces/flow.interface.ts"],"names":[],"mappings":";;;AAIA,sDAA6D;AAW7D,MAAa,WAAY,SAAQ,KAAK;IACR;IAAuC;IAAnE,YAA4B,IAAqB,EAAkB,MAAW;QAC5E,KAAK,EAAE,CAAC;QADkB,SAAI,GAAJ,IAAI,CAAiB;QAAkB,WAAM,GAAN,MAAM,CAAK;IAE9E,CAAC;IAED,MAAM,CAAC,OAAO,CAAI,MAAS;QACzB,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,CAAC,IAAI;QACT,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,CAAC,OAAO;QACZ,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAY;QACtB,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAc;QACzB,MAAM,IAAI,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;CAEF;AAzBD,kCAyBC;AAGD,uCAAuC;AACvC,MAAsB,QAAQ;IAMP;IACA;IACA;IACA;IARX,KAAK,CAAiB;IAChC,KAAK,GAAmB,sBAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,WAAW,CAAiB;IAE5B,YACqB,QAAyB,EACzB,QAAuC,EACvC,KAAiB,EACjB,OAAoC,IAAI,GAAG,EAAE;QAH7C,aAAQ,GAAR,QAAQ,CAAiB;QACzB,aAAQ,GAAR,QAAQ,CAA+B;QACvC,UAAK,GAAL,KAAK,CAAY;QACjB,SAAI,GAAJ,IAAI,CAAyC;QAEhE,IAAI,CAAC,KAAK,GAAI,QAAQ,CAAC,WAAmB,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC;QAC9D,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC;IAClC,CAAC;IAED,GAAG,CAAI,KAAe;QACpB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAM,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAES,OAAO,CAAC,MAAuB;QACvC,MAAM,WAAW,CAAC,OAAO,CAAE,IAAI,CAAC,QAAQ,CAAC,YAAiC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5F,CAAC;IAES,IAAI,CAAC,KAAY;QACzB,MAAM,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAES,KAAK,CAAC,OAAe;QAC7B,MAAM,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAES,IAAI;QACZ,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAES,OAAO;QACf,MAAM,WAAW,CAAC,OAAO,EAAE,CAAC;IAC9B,CAAC;CACF;AAvCD,4BAuCC","sourcesContent":["import {Token, Type} from './base.interface';\nimport {FlowMetadata, FlowName} from '../metadata';\nimport {z} from 'zod';\nimport {ScopeEntry} from '../entries';\nimport {FlowState, FlowStateOf} from './internal/flow.utils';\nimport {FrontMcpLogger} from \"./logger.interface\";\n\nexport type FlowInputOf<N extends FlowName> = z.infer<ExtendFlows[N]['input']>;\nexport type FlowOutputOf<N extends FlowName> = z.infer<ExtendFlows[N]['output']>;\nexport type FlowPlanOf<N extends FlowName> = ExtendFlows[N]['plan'];\nexport type FlowCtxOf<N extends FlowName> = ExtendFlows[N]['ctx'];\n\n\nexport type FlowControlType = 'respond' | 'fail' | 'abort' | 'next' | 'handled';\n\nexport class FlowControl extends Error {\n  constructor(public readonly type: FlowControlType, public readonly output: any) {\n    super();\n  }\n\n  static respond<T>(output: T): never {\n    throw new FlowControl('respond', output);\n  }\n\n  static next(): never {\n    throw new FlowControl('next', null);\n  }\n\n  static handled(): never {\n    throw new FlowControl('handled', null);\n  }\n\n  static fail(error: Error): never {\n    throw new FlowControl('fail', error);\n  }\n\n  static abort(reason: string): never {\n    throw new FlowControl('abort', reason);\n  }\n\n}\n\n\n// 1) The actual abstract class (value)\nexport abstract class FlowBase<N extends FlowName = FlowName> {\n  protected input: FlowInputOf<N>;\n  state: FlowStateOf<N> = FlowState.create({});\n  scopeLogger: FrontMcpLogger;\n\n  constructor(\n    protected readonly metadata: FlowMetadata<N>,\n    protected readonly rawInput: Partial<FlowInputOf<N>> | any,\n    protected readonly scope: ScopeEntry,\n    protected readonly deps: ReadonlyMap<Token, unknown> = new Map(),\n  ) {\n    this.input = (metadata.inputSchema as any)?.parse?.(rawInput);\n    this.scopeLogger = scope.logger;\n  }\n\n  get<T>(token: Token<T>): T {\n    if (this.deps.has(token)) return this.deps.get(token) as T;\n    return this.scope.providers.get(token);\n  }\n\n  protected respond(output: FlowOutputOf<N>) {\n    throw FlowControl.respond((this.metadata.outputSchema as z.ZodObject<any>).parse(output));\n  }\n\n  protected fail(error: Error) {\n    throw FlowControl.fail(error);\n  }\n\n  protected abort(message: string) {\n    throw FlowControl.abort(message);\n  }\n\n  protected next() {\n    throw FlowControl.next();\n  }\n\n  protected handled() {\n    throw FlowControl.handled();\n  }\n}\n\nexport type FlowType<Provide = FlowBase<FlowName>> =\n  | Type<Provide>\n\n"]}

package/src/interfaces/front-mcp.interface.d.ts

@@ -0,0 +1,5 @@
+import { FrontMcpConfigType } from '../metadata';
+export interface FrontMcpInterface {
+    readonly config: FrontMcpConfigType;
+    readonly ready: Promise<void>;
+}

package/src/interfaces/front-mcp.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=front-mcp.interface.js.map

package/src/interfaces/front-mcp.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"front-mcp.interface.js","sourceRoot":"","sources":["../../../src/interfaces/front-mcp.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { FrontMcpConfigType } from '../metadata';\n\n\nexport interface FrontMcpInterface {\n  readonly config: FrontMcpConfigType;\n  readonly ready: Promise<void>;\n\n}"]}

package/src/interfaces/index.d.ts

@@ -0,0 +1,15 @@
+export * from './base.interface';
+export * from './front-mcp.interface';
+export * from './server.interface';
+export * from './scope.interface';
+export * from './flow.interface';
+export * from './app.interface';
+export * from './provider.interface';
+export * from './auth-provider.interface';
+export * from './adapter.interface';
+export * from './plugin.interface';
+export * from './tool.interface';
+export * from './resource.interface';
+export * from './prompt.interface';
+export * from './logger.interface';
+export * from './internal';

package/src/interfaces/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./base.interface"), exports);
+tslib_1.__exportStar(require("./front-mcp.interface"), exports);
+tslib_1.__exportStar(require("./server.interface"), exports);
+tslib_1.__exportStar(require("./scope.interface"), exports);
+tslib_1.__exportStar(require("./flow.interface"), exports);
+tslib_1.__exportStar(require("./app.interface"), exports);
+tslib_1.__exportStar(require("./provider.interface"), exports);
+tslib_1.__exportStar(require("./auth-provider.interface"), exports);
+tslib_1.__exportStar(require("./adapter.interface"), exports);
+tslib_1.__exportStar(require("./plugin.interface"), exports);
+tslib_1.__exportStar(require("./tool.interface"), exports);
+tslib_1.__exportStar(require("./resource.interface"), exports);
+tslib_1.__exportStar(require("./prompt.interface"), exports);
+tslib_1.__exportStar(require("./logger.interface"), exports);
+tslib_1.__exportStar(require("./internal"), exports);
+//# sourceMappingURL=index.js.map

package/src/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interfaces/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,gEAAsC;AACtC,6DAAmC;AACnC,4DAAkC;AAClC,2DAAiC;AACjC,0DAAgC;AAChC,+DAAqC;AACrC,oEAA0C;AAC1C,8DAAoC;AACpC,6DAAmC;AACnC,2DAAiC;AACjC,+DAAqC;AACrC,6DAAmC;AACnC,6DAAmC;AAEnC,qDAA0B","sourcesContent":["export * from './base.interface';\nexport * from './front-mcp.interface';\nexport * from './server.interface';\nexport * from './scope.interface';\nexport * from './flow.interface';\nexport * from './app.interface';\nexport * from './provider.interface';\nexport * from './auth-provider.interface';\nexport * from './adapter.interface';\nexport * from './plugin.interface';\nexport * from './tool.interface';\nexport * from './resource.interface';\nexport * from './prompt.interface';\nexport * from './logger.interface';\n\nexport * from './internal'"]}

package/src/interfaces/internal/flow.utils.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { FlowName } from '../../metadata';
+export type Dict = Record<PropertyKey, unknown>;
+type RequiredView<T> = {
+    [K in keyof T]-?: Exclude<T[K], undefined>;
+};
+type StateAccess<T> = {
+    [K in keyof T]: T[K] | undefined;
+} & {
+    required: RequiredView<T>;
+};
+type StateType<Name extends FlowName> = z.infer<ExtendFlows[Name]['state']>;
+export type FlowStateOf<Name extends FlowName, T = StateType<Name>> = StateAccess<T> & {
+    get<K extends keyof T>(key: K): T[K] | undefined;
+    getOrThrow<K extends keyof T>(key: K, message?: string): Exclude<T[K], undefined>;
+    set<K extends keyof T>(key: K, value: T[K]): FlowStateOf<Name, T>;
+    set(patch: Partial<T>): FlowStateOf<Name, T>;
+    snapshot(): Readonly<Partial<T>>;
+};
+export declare class FlowState {
+    private constructor();
+    static create<Name extends FlowName, T = StateType<Name>>(initial?: Partial<T>): FlowStateOf<Name>;
+}
+export {};

package/src/interfaces/internal/flow.utils.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowState = void 0;
+class FlowState {
+    constructor() {
+        /* empty */
+    }
+    static create(initial) {
+        const data = initial ? { ...initial } : {};
+        const api = {
+            get(key) {
+                return data[key];
+            },
+            getOrThrow(key, message) {
+                const val = data[key];
+                if (val === undefined || val === null) {
+                    throw new Error(message ?? `InvokeState: missing required key "${String(key)}"`);
+                }
+                return val;
+            },
+            set(...args) {
+                if (args.length === 1)
+                    Object.assign(data, args[0]);
+                else {
+                    const [k, v] = args;
+                    data[k] = v;
+                }
+                return proxy;
+            },
+            snapshot() {
+                return { ...data };
+            },
+        };
+        const requiredProxy = new Proxy({}, {
+            get(_t, prop) {
+                const val = data[prop];
+                if (val === undefined || val === null) {
+                    throw new Error(`InvokeState: missing required key "${String(prop)}"`);
+                }
+                return val;
+            },
+            has(_t, prop) {
+                const val = data[prop];
+                return val !== undefined && val !== null;
+            },
+            ownKeys() {
+                return Reflect.ownKeys(data);
+            },
+            getOwnPropertyDescriptor() {
+                return { enumerable: true, configurable: true };
+            },
+        });
+        const methodKeys = new Set(['get', 'getOrThrow', 'set', 'snapshot']);
+        const proxy = new Proxy(api, {
+            get(_t, prop, receiver) {
+                if (prop === 'required')
+                    return requiredProxy;
+                if (methodKeys.has(prop))
+                    return Reflect.get(api, prop, receiver);
+                return data[prop];
+            },
+            set(_t, prop, value) {
+                data[prop] = value;
+                return true;
+            },
+            has(_t, prop) {
+                return prop === 'required' || methodKeys.has(prop) || prop in data;
+            },
+            ownKeys() {
+                return [...Reflect.ownKeys(data), 'required', ...methodKeys];
+            },
+            getOwnPropertyDescriptor(_t, prop) {
+                if (prop === 'required' || methodKeys.has(prop)) {
+                    return { enumerable: false, configurable: true };
+                }
+                return { enumerable: true, configurable: true };
+            },
+        });
+        return proxy;
+    }
+}
+exports.FlowState = FlowState;
+//# sourceMappingURL=flow.utils.js.map

package/src/interfaces/internal/flow.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.utils.js","sourceRoot":"","sources":["../../../../src/interfaces/internal/flow.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { FlowName } from '../../metadata';\n\nexport type Dict = Record<PropertyKey, unknown>;\ntype RequiredView<T> = { [K in keyof T]-?: Exclude<T[K], undefined> };\ntype StateAccess<T> = { [K in keyof T]: T[K] | undefined } & { required: RequiredView<T> };\n\ntype StateType<Name extends FlowName> = z.infer<ExtendFlows[Name]['state']>\n\nexport type FlowStateOf<Name extends FlowName, T = StateType<Name>> = StateAccess<T> & {\n  get<K extends keyof T>(key: K): T[K] | undefined;\n  getOrThrow<K extends keyof T>(key: K, message?: string): Exclude<T[K], undefined>;\n  set<K extends keyof T>(key: K, value: T[K]): FlowStateOf<Name, T>;\n  set(patch: Partial<T>): FlowStateOf<Name, T>;\n  snapshot(): Readonly<Partial<T>>;\n};\n\nexport class FlowState {\n  private constructor() {\n    /* empty */\n  }\n\n  static create<Name extends FlowName, T = StateType<Name>>(initial?: Partial<T>): FlowStateOf<Name> {\n    const data: Partial<T> = initial ? { ...initial } : {};\n\n    const api = {\n      get<K extends keyof T>(key: K) {\n        return data[key] as T[K] | undefined;\n      },\n      getOrThrow<K extends keyof T>(key: K, message?: string) {\n        const val = data[key];\n        if (val === undefined || val === null) {\n          throw new Error(message ?? `InvokeState: missing required key \"${String(key)}\"`);\n        }\n        return val as Exclude<T[K], undefined>;\n      },\n      set<K extends keyof T>(...args: [K, T[K]] | [Partial<T>]) {\n        if (args.length === 1) Object.assign(data, args[0]);\n        else {\n          const [k, v] = args as [K, T[K]];\n          (data as any)[k] = v;\n        }\n        return proxy as FlowStateOf<Name>;\n      },\n      snapshot() {\n        return { ...data } as Readonly<Partial<T>>;\n      },\n    };\n\n    const requiredProxy = new Proxy({} as RequiredView<T>, {\n      get(_t, prop: PropertyKey) {\n        const val = (data as any)[prop];\n        if (val === undefined || val === null) {\n          throw new Error(`InvokeState: missing required key \"${String(prop)}\"`);\n        }\n        return val;\n      },\n      has(_t, prop) {\n        const val = (data as any)[prop];\n        return val !== undefined && val !== null;\n      },\n      ownKeys() {\n        return Reflect.ownKeys(data as object);\n      },\n      getOwnPropertyDescriptor() {\n        return { enumerable: true, configurable: true };\n      },\n    });\n\n    const methodKeys = new Set<PropertyKey>(['get', 'getOrThrow', 'set', 'snapshot']);\n\n    const proxy = new Proxy(api as any, {\n      get(_t, prop: PropertyKey, receiver) {\n        if (prop === 'required') return requiredProxy;\n        if (methodKeys.has(prop)) return Reflect.get(api as any, prop, receiver);\n        return (data as any)[prop];\n      },\n      set(_t, prop: PropertyKey, value) {\n        (data as any)[prop] = value;\n        return true;\n      },\n      has(_t, prop) {\n        return prop === 'required' || methodKeys.has(prop) || prop in (data as object);\n      },\n      ownKeys() {\n        return [...Reflect.ownKeys(data as object), 'required', ...methodKeys] as ArrayLike<string | symbol>;\n      },\n      getOwnPropertyDescriptor(_t, prop) {\n        if (prop === 'required' || methodKeys.has(prop)) {\n          return { enumerable: false, configurable: true };\n        }\n        return { enumerable: true, configurable: true };\n      },\n    });\n\n    return proxy as FlowStateOf<Name>;\n  }\n}\n"]}

package/src/interfaces/internal/index.d.ts

@@ -0,0 +1,2 @@
+export * from './primary-auth-provider.interface';
+export * from './registry.interface';

package/src/interfaces/internal/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// core interfaces
+tslib_1.__exportStar(require("./primary-auth-provider.interface"), exports);
+tslib_1.__exportStar(require("./registry.interface"), exports);
+//# sourceMappingURL=index.js.map

package/src/interfaces/internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/interfaces/internal/index.ts"],"names":[],"mappings":";;;AAAA,kBAAkB;AAClB,4EAAkD;AAClD,+DAAqC","sourcesContent":["// core interfaces\nexport * from './primary-auth-provider.interface';\nexport * from './registry.interface';\n"]}

package/src/interfaces/internal/primary-auth-provider.interface.d.ts

@@ -0,0 +1,24 @@
+import { ServerRequest } from '../server.interface';
+import { AuthOptions } from '../../types';
+/**
+ * Base class for primary auth provider.
+ * Used for easy access current auth context by dependency injection.
+ *
+ * In tool context, you can access current auth context by calling:
+ *  this.get(FrontMcpAuth) | this.get(Auth)
+ *
+ * Or in session scoped Providers in constructor arguments:
+ *  constructor(private readonly auth: FrontMcpAuth) {
+ *  // auth.fetch('MY endpoint ')
+ *  }
+ */
+export declare abstract class FrontMcpAuth {
+    ready: Promise<void>;
+    readonly options: AuthOptions;
+    readonly id: string;
+    constructor(options: AuthOptions);
+    abstract fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    abstract validate(request: ServerRequest): Promise<void>;
+    abstract get issuer(): string;
+}
+export { FrontMcpAuth as Auth, };