@frontmcp/sdk 0.4.0 → 0.5.0

package/src/auth/authorization/authorization.types.d.ts

@@ -0,0 +1,300 @@
+import { z } from 'zod';
+import { ProviderSnapshot } from '../session/session.types';
+import { TransportSession, TransportProtocol } from '../session';
+import type { AuthMode } from '../../common';
+/**
+ * User identity from authentication
+ */
+export interface AuthUser {
+    /** Subject identifier */
+    sub: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Profile picture URL */
+    picture?: string;
+    /** Whether this is an anonymous user */
+    anonymous?: boolean;
+}
+/**
+ * Authorized tool entry
+ */
+export interface AuthorizedTool {
+    /** Execution path: [appId, toolId] */
+    executionPath: [appId: string, toolId: string];
+    /** Required scopes for this tool */
+    scopes?: string[];
+    /** Additional tool metadata */
+    details?: Record<string, unknown>;
+}
+/**
+ * Authorized prompt entry
+ */
+export interface AuthorizedPrompt {
+    /** Execution path: [appId, promptId] */
+    executionPath: [appId: string, promptId: string];
+    /** Required scopes for this prompt */
+    scopes?: string[];
+    /** Additional prompt metadata */
+    details?: Record<string, unknown>;
+}
+/**
+ * Authorization represents the authenticated user context.
+ * Created from JWT verification, independent of transport.
+ * One authorization can have multiple transport sessions.
+ */
+export interface Authorization {
+    /** Unique authorization ID (derived from token signature) */
+    readonly id: string;
+    /** Auth mode that created this authorization */
+    readonly mode: AuthMode;
+    /** Whether this is an anonymous/public authorization */
+    readonly isAnonymous: boolean;
+    /** User identity */
+    readonly user: AuthUser;
+    /** JWT claims */
+    readonly claims?: Record<string, unknown>;
+    /** Token expiration (epoch ms) */
+    readonly expiresAt?: number;
+    /** Granted scopes */
+    readonly scopes: string[];
+    /** Authorized providers (for orchestrated mode) */
+    readonly authorizedProviders: Record<string, ProviderSnapshot>;
+    /** Authorized provider IDs */
+    readonly authorizedProviderIds: string[];
+    /** Authorized apps */
+    readonly authorizedApps: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    /** Authorized app IDs */
+    readonly authorizedAppIds: string[];
+    /** Authorized tools */
+    readonly authorizedTools: Record<string, AuthorizedTool>;
+    /** Authorized tool IDs */
+    readonly authorizedToolIds: string[];
+    /** Authorized prompts */
+    readonly authorizedPrompts: Record<string, AuthorizedPrompt>;
+    /** Authorized prompt IDs */
+    readonly authorizedPromptIds: string[];
+    /** Authorized resources */
+    readonly authorizedResources: string[];
+    /**
+     * Get access token for a provider (orchestrated mode)
+     * @param providerId - Provider ID, defaults to primary
+     */
+    getToken(providerId?: string): Promise<string>;
+    /**
+     * Create a new transport session for this authorization
+     * @param protocol - Transport protocol (sse, streamable-http, etc.)
+     * @param fingerprint - Optional client fingerprint for tracking
+     */
+    createTransportSession(protocol: TransportProtocol, fingerprint?: string): TransportSession;
+    /**
+     * Get existing transport session by ID
+     * @param sessionId - Session ID to retrieve
+     */
+    getTransportSession(sessionId: string): TransportSession | undefined;
+    /**
+     * Check if a scope is granted
+     * @param scope - Scope to check
+     */
+    hasScope(scope: string): boolean;
+    /**
+     * Check if all scopes are granted
+     * @param scopes - Scopes to check
+     */
+    hasAllScopes(scopes: string[]): boolean;
+    /**
+     * Check if any scope is granted
+     * @param scopes - Scopes to check
+     */
+    hasAnyScope(scopes: string[]): boolean;
+    /**
+     * Check if a tool is authorized
+     * @param toolId - Tool ID to check
+     */
+    canAccessTool(toolId: string): boolean;
+    /**
+     * Check if a prompt is authorized
+     * @param promptId - Prompt ID to check
+     */
+    canAccessPrompt(promptId: string): boolean;
+}
+/**
+ * Context for creating an authorization
+ */
+export interface AuthorizationCreateCtx {
+    /** Unique ID (typically token signature fingerprint) */
+    id: string;
+    /** Whether this is anonymous */
+    isAnonymous: boolean;
+    /** User identity */
+    user: AuthUser;
+    /** JWT claims */
+    claims?: Record<string, unknown>;
+    /** Token expiration (epoch ms) */
+    expiresAt?: number;
+    /** Granted scopes */
+    scopes?: string[];
+    /** The original token (for transparent mode) */
+    token?: string;
+    /** Authorized providers */
+    authorizedProviders?: Record<string, ProviderSnapshot>;
+    /** Authorized provider IDs */
+    authorizedProviderIds?: string[];
+    /** Authorized apps */
+    authorizedApps?: Record<string, {
+        id: string;
+        toolIds: string[];
+    }>;
+    /** Authorized app IDs */
+    authorizedAppIds?: string[];
+    /** Authorized tools */
+    authorizedTools?: Record<string, AuthorizedTool>;
+    /** Authorized tool IDs */
+    authorizedToolIds?: string[];
+    /** Authorized prompts */
+    authorizedPrompts?: Record<string, AuthorizedPrompt>;
+    /** Authorized prompt IDs */
+    authorizedPromptIds?: string[];
+    /** Authorized resources */
+    authorizedResources?: string[];
+}
+/**
+ * LLM-safe session context (no tokens exposed)
+ */
+export interface LLMSafeAuthContext {
+    /** Authorization ID */
+    authorizationId: string;
+    /** Session ID */
+    sessionId: string;
+    /** Auth mode */
+    mode: AuthMode;
+    /** Whether anonymous */
+    isAnonymous: boolean;
+    /** User (sub and name only) */
+    user: {
+        sub: string;
+        name?: string;
+    };
+    /** Granted scopes */
+    scopes: string[];
+    /** Authorized tool IDs */
+    authorizedToolIds: string[];
+    /** Authorized prompt IDs */
+    authorizedPromptIds: string[];
+}
+export declare const authUserSchema: z.ZodObject<{
+    sub: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    picture: z.ZodOptional<z.ZodString>;
+    anonymous: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const authorizedToolSchema: z.ZodObject<{
+    executionPath: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const authorizedPromptSchema: z.ZodObject<{
+    executionPath: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const authModeSchema: z.ZodEnum<{
+    public: "public";
+    transparent: "transparent";
+    orchestrated: "orchestrated";
+}>;
+export declare const llmSafeAuthContextSchema: z.ZodObject<{
+    authorizationId: z.ZodString;
+    sessionId: z.ZodString;
+    mode: z.ZodEnum<{
+        public: "public";
+        transparent: "transparent";
+        orchestrated: "orchestrated";
+    }>;
+    isAnonymous: z.ZodBoolean;
+    user: z.ZodObject<{
+        sub: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    scopes: z.ZodArray<z.ZodString>;
+    authorizedToolIds: z.ZodArray<z.ZodString>;
+    authorizedPromptIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * State of app authorization within a session.
+ * Used for progressive authorization flow.
+ */
+export declare enum AppAuthState {
+    /** App has been fully authorized with tokens stored */
+    AUTHORIZED = "authorized",
+    /** User explicitly skipped this app during initial auth */
+    SKIPPED = "skipped",
+    /** App authorization is pending (not yet presented to user) */
+    PENDING = "pending"
+}
+/**
+ * App authorization record with state tracking.
+ * Stored server-side, NOT in JWT.
+ */
+export interface AppAuthorizationRecord {
+    /** App ID */
+    appId: string;
+    /** Current authorization state */
+    state: AppAuthState;
+    /** When the state was last changed (epoch ms) */
+    stateChangedAt: number;
+    /** Scopes granted for this app */
+    grantedScopes?: string[];
+    /** Auth provider ID used for this app */
+    authProviderId?: string;
+    /** Tool IDs accessible through this app authorization */
+    toolIds: string[];
+}
+/**
+ * Progressive auth session state.
+ * Tracks which apps are authorized, skipped, or pending.
+ * Stored server-side for security.
+ */
+export interface ProgressiveAuthState {
+    /** App authorization records by app ID */
+    apps: Record<string, AppAuthorizationRecord>;
+    /** Apps authorized during initial auth */
+    initiallyAuthorized: string[];
+    /** Apps skipped during initial auth */
+    initiallySkipped: string[];
+}
+/**
+ * Zod schema for AppAuthState enum
+ */
+export declare const appAuthStateSchema: z.ZodEnum<typeof AppAuthState>;
+/**
+ * Zod schema for AppAuthorizationRecord
+ */
+export declare const appAuthorizationRecordSchema: z.ZodObject<{
+    appId: z.ZodString;
+    state: z.ZodEnum<typeof AppAuthState>;
+    stateChangedAt: z.ZodNumber;
+    grantedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authProviderId: z.ZodOptional<z.ZodString>;
+    toolIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for ProgressiveAuthState
+ */
+export declare const progressiveAuthStateSchema: z.ZodObject<{
+    apps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        appId: z.ZodString;
+        state: z.ZodEnum<typeof AppAuthState>;
+        stateChangedAt: z.ZodNumber;
+        grantedScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        authProviderId: z.ZodOptional<z.ZodString>;
+        toolIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    initiallyAuthorized: z.ZodArray<z.ZodString>;
+    initiallySkipped: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;

package/src/auth/authorization/authorization.types.js

@@ -0,0 +1,79 @@
+"use strict";
+// auth/authorization/authorization.types.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.progressiveAuthStateSchema = exports.appAuthorizationRecordSchema = exports.appAuthStateSchema = exports.AppAuthState = exports.llmSafeAuthContextSchema = exports.authModeSchema = exports.authorizedPromptSchema = exports.authorizedToolSchema = exports.authUserSchema = void 0;
+const zod_1 = require("zod");
+// ============================================
+// Zod Schemas
+// ============================================
+exports.authUserSchema = zod_1.z.object({
+    sub: zod_1.z.string(),
+    name: zod_1.z.string().optional(),
+    email: zod_1.z.string().email().optional(),
+    picture: zod_1.z.string().url().optional(),
+    anonymous: zod_1.z.boolean().optional(),
+});
+exports.authorizedToolSchema = zod_1.z.object({
+    executionPath: zod_1.z.tuple([zod_1.z.string(), zod_1.z.string()]),
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    details: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+exports.authorizedPromptSchema = zod_1.z.object({
+    executionPath: zod_1.z.tuple([zod_1.z.string(), zod_1.z.string()]),
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    details: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+exports.authModeSchema = zod_1.z.enum(['public', 'transparent', 'orchestrated']);
+exports.llmSafeAuthContextSchema = zod_1.z.object({
+    authorizationId: zod_1.z.string(),
+    sessionId: zod_1.z.string(),
+    mode: exports.authModeSchema,
+    isAnonymous: zod_1.z.boolean(),
+    user: zod_1.z.object({
+        sub: zod_1.z.string(),
+        name: zod_1.z.string().optional(),
+    }),
+    scopes: zod_1.z.array(zod_1.z.string()),
+    authorizedToolIds: zod_1.z.array(zod_1.z.string()),
+    authorizedPromptIds: zod_1.z.array(zod_1.z.string()),
+});
+// ============================================
+// Progressive/Incremental Authorization Types
+// ============================================
+/**
+ * State of app authorization within a session.
+ * Used for progressive authorization flow.
+ */
+var AppAuthState;
+(function (AppAuthState) {
+    /** App has been fully authorized with tokens stored */
+    AppAuthState["AUTHORIZED"] = "authorized";
+    /** User explicitly skipped this app during initial auth */
+    AppAuthState["SKIPPED"] = "skipped";
+    /** App authorization is pending (not yet presented to user) */
+    AppAuthState["PENDING"] = "pending";
+})(AppAuthState || (exports.AppAuthState = AppAuthState = {}));
+/**
+ * Zod schema for AppAuthState enum
+ */
+exports.appAuthStateSchema = zod_1.z.nativeEnum(AppAuthState);
+/**
+ * Zod schema for AppAuthorizationRecord
+ */
+exports.appAuthorizationRecordSchema = zod_1.z.object({
+    appId: zod_1.z.string(),
+    state: exports.appAuthStateSchema,
+    stateChangedAt: zod_1.z.number(),
+    grantedScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    authProviderId: zod_1.z.string().optional(),
+    toolIds: zod_1.z.array(zod_1.z.string()),
+});
+/**
+ * Zod schema for ProgressiveAuthState
+ */
+exports.progressiveAuthStateSchema = zod_1.z.object({
+    apps: zod_1.z.record(zod_1.z.string(), exports.appAuthorizationRecordSchema),
+    initiallyAuthorized: zod_1.z.array(zod_1.z.string()),
+    initiallySkipped: zod_1.z.array(zod_1.z.string()),
+});
+//# sourceMappingURL=authorization.types.js.map

package/src/auth/authorization/authorization.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.types.js","sourceRoot":"","sources":["../../../../src/auth/authorization/authorization.types.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/authorization/authorization.types.ts\n\nimport { z } from 'zod';\nimport { ProviderSnapshot } from '../session/session.types';\nimport { TransportSession, TransportProtocol } from '../session';\nimport type { AuthMode } from '../../common';\n\n/**\n * User identity from authentication\n */\nexport interface AuthUser {\n  /** Subject identifier */\n  sub: string;\n  /** Display name */\n  name?: string;\n  /** Email address */\n  email?: string;\n  /** Profile picture URL */\n  picture?: string;\n  /** Whether this is an anonymous user */\n  anonymous?: boolean;\n}\n\n/**\n * Authorized tool entry\n */\nexport interface AuthorizedTool {\n  /** Execution path: [appId, toolId] */\n  executionPath: [appId: string, toolId: string];\n  /** Required scopes for this tool */\n  scopes?: string[];\n  /** Additional tool metadata */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Authorized prompt entry\n */\nexport interface AuthorizedPrompt {\n  /** Execution path: [appId, promptId] */\n  executionPath: [appId: string, promptId: string];\n  /** Required scopes for this prompt */\n  scopes?: string[];\n  /** Additional prompt metadata */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Authorization represents the authenticated user context.\n * Created from JWT verification, independent of transport.\n * One authorization can have multiple transport sessions.\n */\nexport interface Authorization {\n  /** Unique authorization ID (derived from token signature) */\n  readonly id: string;\n\n  /** Auth mode that created this authorization */\n  readonly mode: AuthMode;\n\n  /** Whether this is an anonymous/public authorization */\n  readonly isAnonymous: boolean;\n\n  /** User identity */\n  readonly user: AuthUser;\n\n  /** JWT claims */\n  readonly claims?: Record<string, unknown>;\n\n  /** Token expiration (epoch ms) */\n  readonly expiresAt?: number;\n\n  /** Granted scopes */\n  readonly scopes: string[];\n\n  /** Authorized providers (for orchestrated mode) */\n  readonly authorizedProviders: Record<string, ProviderSnapshot>;\n\n  /** Authorized provider IDs */\n  readonly authorizedProviderIds: string[];\n\n  /** Authorized apps */\n  readonly authorizedApps: Record<string, { id: string; toolIds: string[] }>;\n\n  /** Authorized app IDs */\n  readonly authorizedAppIds: string[];\n\n  /** Authorized tools */\n  readonly authorizedTools: Record<string, AuthorizedTool>;\n\n  /** Authorized tool IDs */\n  readonly authorizedToolIds: string[];\n\n  /** Authorized prompts */\n  readonly authorizedPrompts: Record<string, AuthorizedPrompt>;\n\n  /** Authorized prompt IDs */\n  readonly authorizedPromptIds: string[];\n\n  /** Authorized resources */\n  readonly authorizedResources: string[];\n\n  /**\n   * Get access token for a provider (orchestrated mode)\n   * @param providerId - Provider ID, defaults to primary\n   */\n  getToken(providerId?: string): Promise<string>;\n\n  /**\n   * Create a new transport session for this authorization\n   * @param protocol - Transport protocol (sse, streamable-http, etc.)\n   * @param fingerprint - Optional client fingerprint for tracking\n   */\n  createTransportSession(protocol: TransportProtocol, fingerprint?: string): TransportSession;\n\n  /**\n   * Get existing transport session by ID\n   * @param sessionId - Session ID to retrieve\n   */\n  getTransportSession(sessionId: string): TransportSession | undefined;\n\n  /**\n   * Check if a scope is granted\n   * @param scope - Scope to check\n   */\n  hasScope(scope: string): boolean;\n\n  /**\n   * Check if all scopes are granted\n   * @param scopes - Scopes to check\n   */\n  hasAllScopes(scopes: string[]): boolean;\n\n  /**\n   * Check if any scope is granted\n   * @param scopes - Scopes to check\n   */\n  hasAnyScope(scopes: string[]): boolean;\n\n  /**\n   * Check if a tool is authorized\n   * @param toolId - Tool ID to check\n   */\n  canAccessTool(toolId: string): boolean;\n\n  /**\n   * Check if a prompt is authorized\n   * @param promptId - Prompt ID to check\n   */\n  canAccessPrompt(promptId: string): boolean;\n}\n\n/**\n * Context for creating an authorization\n */\nexport interface AuthorizationCreateCtx {\n  /** Unique ID (typically token signature fingerprint) */\n  id: string;\n  /** Whether this is anonymous */\n  isAnonymous: boolean;\n  /** User identity */\n  user: AuthUser;\n  /** JWT claims */\n  claims?: Record<string, unknown>;\n  /** Token expiration (epoch ms) */\n  expiresAt?: number;\n  /** Granted scopes */\n  scopes?: string[];\n  /** The original token (for transparent mode) */\n  token?: string;\n  /** Authorized providers */\n  authorizedProviders?: Record<string, ProviderSnapshot>;\n  /** Authorized provider IDs */\n  authorizedProviderIds?: string[];\n  /** Authorized apps */\n  authorizedApps?: Record<string, { id: string; toolIds: string[] }>;\n  /** Authorized app IDs */\n  authorizedAppIds?: string[];\n  /** Authorized tools */\n  authorizedTools?: Record<string, AuthorizedTool>;\n  /** Authorized tool IDs */\n  authorizedToolIds?: string[];\n  /** Authorized prompts */\n  authorizedPrompts?: Record<string, AuthorizedPrompt>;\n  /** Authorized prompt IDs */\n  authorizedPromptIds?: string[];\n  /** Authorized resources */\n  authorizedResources?: string[];\n}\n\n/**\n * LLM-safe session context (no tokens exposed)\n */\nexport interface LLMSafeAuthContext {\n  /** Authorization ID */\n  authorizationId: string;\n  /** Session ID */\n  sessionId: string;\n  /** Auth mode */\n  mode: AuthMode;\n  /** Whether anonymous */\n  isAnonymous: boolean;\n  /** User (sub and name only) */\n  user: { sub: string; name?: string };\n  /** Granted scopes */\n  scopes: string[];\n  /** Authorized tool IDs */\n  authorizedToolIds: string[];\n  /** Authorized prompt IDs */\n  authorizedPromptIds: string[];\n}\n\n// ============================================\n// Zod Schemas\n// ============================================\n\nexport const authUserSchema = z.object({\n  sub: z.string(),\n  name: z.string().optional(),\n  email: z.string().email().optional(),\n  picture: z.string().url().optional(),\n  anonymous: z.boolean().optional(),\n});\n\nexport const authorizedToolSchema = z.object({\n  executionPath: z.tuple([z.string(), z.string()]),\n  scopes: z.array(z.string()).optional(),\n  details: z.record(z.string(), z.unknown()).optional(),\n});\n\nexport const authorizedPromptSchema = z.object({\n  executionPath: z.tuple([z.string(), z.string()]),\n  scopes: z.array(z.string()).optional(),\n  details: z.record(z.string(), z.unknown()).optional(),\n});\n\nexport const authModeSchema = z.enum(['public', 'transparent', 'orchestrated']);\n\nexport const llmSafeAuthContextSchema = z.object({\n  authorizationId: z.string(),\n  sessionId: z.string(),\n  mode: authModeSchema,\n  isAnonymous: z.boolean(),\n  user: z.object({\n    sub: z.string(),\n    name: z.string().optional(),\n  }),\n  scopes: z.array(z.string()),\n  authorizedToolIds: z.array(z.string()),\n  authorizedPromptIds: z.array(z.string()),\n});\n\n// ============================================\n// Progressive/Incremental Authorization Types\n// ============================================\n\n/**\n * State of app authorization within a session.\n * Used for progressive authorization flow.\n */\nexport enum AppAuthState {\n  /** App has been fully authorized with tokens stored */\n  AUTHORIZED = 'authorized',\n  /** User explicitly skipped this app during initial auth */\n  SKIPPED = 'skipped',\n  /** App authorization is pending (not yet presented to user) */\n  PENDING = 'pending',\n}\n\n/**\n * App authorization record with state tracking.\n * Stored server-side, NOT in JWT.\n */\nexport interface AppAuthorizationRecord {\n  /** App ID */\n  appId: string;\n  /** Current authorization state */\n  state: AppAuthState;\n  /** When the state was last changed (epoch ms) */\n  stateChangedAt: number;\n  /** Scopes granted for this app */\n  grantedScopes?: string[];\n  /** Auth provider ID used for this app */\n  authProviderId?: string;\n  /** Tool IDs accessible through this app authorization */\n  toolIds: string[];\n}\n\n/**\n * Progressive auth session state.\n * Tracks which apps are authorized, skipped, or pending.\n * Stored server-side for security.\n */\nexport interface ProgressiveAuthState {\n  /** App authorization records by app ID */\n  apps: Record<string, AppAuthorizationRecord>;\n  /** Apps authorized during initial auth */\n  initiallyAuthorized: string[];\n  /** Apps skipped during initial auth */\n  initiallySkipped: string[];\n}\n\n/**\n * Zod schema for AppAuthState enum\n */\nexport const appAuthStateSchema = z.nativeEnum(AppAuthState);\n\n/**\n * Zod schema for AppAuthorizationRecord\n */\nexport const appAuthorizationRecordSchema = z.object({\n  appId: z.string(),\n  state: appAuthStateSchema,\n  stateChangedAt: z.number(),\n  grantedScopes: z.array(z.string()).optional(),\n  authProviderId: z.string().optional(),\n  toolIds: z.array(z.string()),\n});\n\n/**\n * Zod schema for ProgressiveAuthState\n */\nexport const progressiveAuthStateSchema = z.object({\n  apps: z.record(z.string(), appAuthorizationRecordSchema),\n  initiallyAuthorized: z.array(z.string()),\n  initiallySkipped: z.array(z.string()),\n});\n"]}

package/src/auth/authorization/index.d.ts

@@ -0,0 +1,5 @@
+export * from './authorization.types';
+export { AuthorizationBase, getMachineId } from './authorization.class';
+export { PublicAuthorization, PublicAuthorizationCreateCtx } from './public.authorization';
+export { TransparentAuthorization, TransparentAuthorizationCreateCtx, TransparentVerifiedPayload, } from './transparent.authorization';
+export { OrchestratedAuthorization, OrchestratedAuthorizationCreateCtx, OrchestratedProviderState, TokenStore, TokenRefreshCallback, } from './orchestrated.authorization';

package/src/auth/authorization/index.js

@@ -0,0 +1,19 @@
+"use strict";
+// auth/authorization/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestratedAuthorization = exports.TransparentAuthorization = exports.PublicAuthorization = exports.getMachineId = exports.AuthorizationBase = void 0;
+const tslib_1 = require("tslib");
+// Types
+tslib_1.__exportStar(require("./authorization.types"), exports);
+// Base class
+var authorization_class_1 = require("./authorization.class");
+Object.defineProperty(exports, "AuthorizationBase", { enumerable: true, get: function () { return authorization_class_1.AuthorizationBase; } });
+Object.defineProperty(exports, "getMachineId", { enumerable: true, get: function () { return authorization_class_1.getMachineId; } });
+// Mode-specific implementations
+var public_authorization_1 = require("./public.authorization");
+Object.defineProperty(exports, "PublicAuthorization", { enumerable: true, get: function () { return public_authorization_1.PublicAuthorization; } });
+var transparent_authorization_1 = require("./transparent.authorization");
+Object.defineProperty(exports, "TransparentAuthorization", { enumerable: true, get: function () { return transparent_authorization_1.TransparentAuthorization; } });
+var orchestrated_authorization_1 = require("./orchestrated.authorization");
+Object.defineProperty(exports, "OrchestratedAuthorization", { enumerable: true, get: function () { return orchestrated_authorization_1.OrchestratedAuthorization; } });
+//# sourceMappingURL=index.js.map

package/src/auth/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/auth/authorization/index.ts"],"names":[],"mappings":";AAAA,8BAA8B;;;;AAE9B,QAAQ;AACR,gEAAsC;AAEtC,aAAa;AACb,6DAAwE;AAA/D,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAExC,gCAAgC;AAChC,+DAA2F;AAAlF,2HAAA,mBAAmB,OAAA;AAC5B,yEAIqC;AAHnC,qIAAA,wBAAwB,OAAA;AAI1B,2EAMsC;AALpC,uIAAA,yBAAyB,OAAA","sourcesContent":["// auth/authorization/index.ts\n\n// Types\nexport * from './authorization.types';\n\n// Base class\nexport { AuthorizationBase, getMachineId } from './authorization.class';\n\n// Mode-specific implementations\nexport { PublicAuthorization, PublicAuthorizationCreateCtx } from './public.authorization';\nexport {\n  TransparentAuthorization,\n  TransparentAuthorizationCreateCtx,\n  TransparentVerifiedPayload,\n} from './transparent.authorization';\nexport {\n  OrchestratedAuthorization,\n  OrchestratedAuthorizationCreateCtx,\n  OrchestratedProviderState,\n  TokenStore,\n  TokenRefreshCallback,\n} from './orchestrated.authorization';\n"]}

package/src/auth/authorization/orchestrated.authorization.d.ts

@@ -0,0 +1,242 @@
+import { AuthorizationBase } from './authorization.class';
+import { AuthorizationCreateCtx, AuthUser } from './authorization.types';
+import { EncryptedBlob } from '../session';
+import { AuthMode } from '../../common';
+/**
+ * Token store interface for orchestrated mode
+ * Implementations can be memory-based, Redis, or custom stores
+ */
+export interface TokenStore {
+    /**
+     * Retrieve decrypted access token for a provider
+     */
+    getAccessToken(authorizationId: string, providerId: string): Promise<string | null>;
+    /**
+     * Retrieve decrypted refresh token for a provider
+     */
+    getRefreshToken(authorizationId: string, providerId: string): Promise<string | null>;
+    /**
+     * Store tokens for a provider (encrypted)
+     */
+    storeTokens(authorizationId: string, providerId: string, tokens: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresAt?: number;
+    }): Promise<void>;
+    /**
+     * Delete tokens for a provider
+     */
+    deleteTokens(authorizationId: string, providerId: string): Promise<void>;
+    /**
+     * Check if tokens exist for a provider
+     */
+    hasTokens(authorizationId: string, providerId: string): Promise<boolean>;
+}
+/**
+ * Token refresh callback type
+ */
+export type TokenRefreshCallback = (providerId: string, refreshToken: string) => Promise<{
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+}>;
+/**
+ * Provider token state for orchestrated authorization
+ */
+export interface OrchestratedProviderState {
+    /** Provider ID */
+    id: string;
+    /** Encrypted access token blob */
+    accessTokenEnc?: EncryptedBlob;
+    /** Encrypted refresh token blob */
+    refreshTokenEnc?: EncryptedBlob;
+    /** Token expiration (epoch ms) */
+    expiresAt?: number;
+    /** External reference ID (for vault/store) */
+    secretRefId?: string;
+    /** Refresh reference ID */
+    refreshRefId?: string;
+}
+/**
+ * Context for creating an OrchestratedAuthorization
+ */
+export interface OrchestratedAuthorizationCreateCtx {
+    /**
+     * The local JWT issued by the orchestrating server
+     */
+    token: string;
+    /**
+     * User identity from upstream provider
+     */
+    user: AuthUser;
+    /**
+     * Scopes granted to this authorization
+     */
+    scopes?: string[];
+    /**
+     * JWT claims
+     */
+    claims?: Record<string, unknown>;
+    /**
+     * Expiration (epoch ms)
+     */
+    expiresAt?: number;
+    /**
+     * Primary provider ID (default for getToken)
+     */
+    primaryProviderId?: string;
+    /**
+     * Token store for retrieving/storing provider tokens
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Token refresh callback
+     */
+    onTokenRefresh?: TokenRefreshCallback;
+    /**
+     * Provider states (with encrypted tokens)
+     */
+    providers?: Record<string, OrchestratedProviderState>;
+    /**
+     * Precomputed authorization projections
+     */
+    authorizedTools?: AuthorizationCreateCtx['authorizedTools'];
+    authorizedToolIds?: string[];
+    authorizedPrompts?: AuthorizationCreateCtx['authorizedPrompts'];
+    authorizedPromptIds?: string[];
+    authorizedApps?: AuthorizationCreateCtx['authorizedApps'];
+    authorizedAppIds?: string[];
+    authorizedResources?: string[];
+}
+/**
+ * OrchestratedAuthorization - Local auth server with secure token storage
+ *
+ * In orchestrated mode:
+ * - The MCP server acts as an OAuth client to upstream providers
+ * - Provider tokens are encrypted and never exposed to the LLM
+ * - Supports token refresh and multi-provider scenarios
+ * - getToken() retrieves decrypted tokens from secure storage
+ * - Ideal for multi-tenant, federated auth, or high-security scenarios
+ */
+export declare class OrchestratedAuthorization extends AuthorizationBase {
+    #private;
+    readonly mode: AuthMode;
+    /**
+     * Primary provider ID (default for getToken)
+     */
+    readonly primaryProviderId?: string;
+    private constructor();
+    /**
+     * Create an OrchestratedAuthorization
+     *
+     * @param ctx - Creation context
+     * @returns A new OrchestratedAuthorization instance
+     *
+     * @example
+     * ```typescript
+     * const auth = OrchestratedAuthorization.create({
+     *   token: localJwt,
+     *   user: { sub: 'user123', name: 'John' },
+     *   primaryProviderId: 'github',
+     *   tokenStore: redisTokenStore,
+     *   providers: {
+     *     github: { id: 'github', secretRefId: 'vault:github:user123' },
+     *   },
+     * });
+     *
+     * // Retrieve token securely (never exposed to LLM)
+     * const githubToken = await auth.getToken('github');
+     * ```
+     */
+    static create(ctx: OrchestratedAuthorizationCreateCtx): OrchestratedAuthorization;
+    /**
+     * Get access token for a provider
+     *
+     * Retrieves the decrypted token from the secure store.
+     * If the token is expired and refresh is available, attempts refresh.
+     *
+     * @param providerId - Provider ID (defaults to primaryProviderId)
+     * @returns The decrypted access token
+     * @throws If no token store or no token available
+     */
+    getToken(providerId?: string): Promise<string>;
+    /**
+     * Refresh token and return new access token
+     */
+    private refreshAndGetToken;
+    /**
+     * Generate authorization ID from token
+     */
+    private static generateAuthorizationId;
+    /**
+     * Check if a provider has tokens stored
+     */
+    hasProvider(providerId: string): boolean;
+    /**
+     * Get all provider IDs with tokens
+     */
+    getProviderIds(): string[];
+    /**
+     * Add a new provider to this authorization
+     * Used when user authorizes additional providers after initial auth
+     */
+    addProvider(providerId: string, tokens: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }): Promise<void>;
+    /**
+     * Add app authorization after initial auth (progressive authorization).
+     * Stores app tokens server-side and updates authorized apps without JWT reissue.
+     *
+     * @param appId - App ID to authorize
+     * @param toolIds - Tool IDs accessible through this app authorization
+     * @param tokens - OAuth tokens from the app's auth provider
+     *
+     * @example
+     * ```typescript
+     * // User clicks auth link for Slack app
+     * await auth.addAppAuthorization('slack', ['slack:send_message', 'slack:list_channels'], {
+     *   accessToken: slackAccessToken,
+     *   refreshToken: slackRefreshToken,
+     *   expiresIn: 3600,
+     * });
+     *
+     * // Now slack tools will work without re-auth
+     * ```
+     */
+    addAppAuthorization(appId: string, toolIds: string[], tokens: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }): Promise<void>;
+    /**
+     * Get access token for a specific app (for tool execution).
+     * Retrieves the app's OAuth token from server-side storage.
+     *
+     * @param appId - App ID to get token for
+     * @returns The decrypted access token, or null if not authorized
+     */
+    getAppToken(appId: string): Promise<string | null>;
+    /**
+     * Check if an app is authorized (includes progressively authorized apps).
+     * Overrides base class to include mutable app authorization state.
+     */
+    isAppAuthorized(appId: string): boolean;
+    /**
+     * Get all authorized app IDs (includes progressively authorized apps).
+     */
+    getAllAuthorizedAppIds(): string[];
+    /**
+     * Get tool IDs authorized through an app.
+     */
+    getAppToolIds(appId: string): string[] | undefined;
+    /**
+     * Remove a provider from this authorization
+     */
+    removeProvider(providerId: string): Promise<void>;
+    /**
+     * Get the issuer (local orchestrator)
+     */
+    get issuer(): string | undefined;
+}