@kya-os/contracts 1.6.2-canary.0 → 1.6.2

package/dist/config/identity.d.ts

@@ -6,6 +6,7 @@
  *
  * @module @kya-os/contracts/config
  */
+import { z } from "zod";
 /**
  * Runtime Identity Configuration
  *
@@ -25,7 +26,7 @@ export interface RuntimeIdentityConfig {
      * Runtime environment for identity
      * Determines where keys come from and how they're managed
      */
-    environment: 'development' | 'production';
+    environment: "development" | "production";
     /**
      * Production identity configuration
      * Used when environment is 'production'
@@ -71,7 +72,218 @@ export interface RuntimeIdentityConfig {
      * - 'persistent': User DIDs are persisted in storage (requires did:web setup)
      * @default 'ephemeral'
      */
-    userDidStorage?: 'ephemeral' | 'persistent';
+    userDidStorage?: "ephemeral" | "persistent";
+}
+/**
+ * OAuth Provider Configuration
+ *
+ * Configuration for a single OAuth provider (GitHub, Google, etc.)
+ */
+export interface OAuthProvider {
+    /** OAuth client ID (public, safe to expose) */
+    clientId: string;
+    /** OAuth client secret (NOT returned in API response for security) */
+    clientSecret?: string | null;
+    /** OAuth authorization URL */
+    authorizationUrl: string;
+    /** OAuth token exchange URL */
+    tokenUrl: string;
+    /** OAuth user info endpoint URL */
+    userInfoUrl?: string;
+    /** Whether provider supports PKCE (Proof Key for Code Exchange) */
+    supportsPKCE: boolean;
+    /** Whether provider requires client secret (false for PKCE-only providers) */
+    requiresClientSecret: boolean;
+    /** Available scopes for this provider */
+    scopes?: string[];
+    /** Default scopes to request */
+    defaultScopes?: string[];
+    /** Whether provider uses proxy mode (via AgentShield) */
+    proxyMode?: boolean;
+    /** Custom OAuth parameters to include in authorization URL (e.g., audience, acr_values) */
+    customParams?: Record<string, string>;
+    /** Token endpoint authentication method */
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic";
+    /** OAuth response type (default: "code") */
+    responseType?: string;
+    /** OAuth grant type (default: "authorization_code") */
+    grantType?: string;
+}
+/**
+ * OAuth Configuration
+ *
+ * Configuration for OAuth providers fetched from AgentShield API.
+ * Contains all available providers for a project.
+ *
+ * The `configuredProvider` field indicates which provider (if any) has been
+ * explicitly configured in the AgentShield dashboard for this project.
+ * Phase 2+ requires tools to explicitly specify oauthProvider.
+ */
+export interface OAuthConfig {
+    /** Map of provider names to provider configurations */
+    providers: Record<string, OAuthProvider>;
+    /**
+     * The explicitly configured OAuth provider for this project.
+     * Null if no provider has been configured in AgentShield dashboard.
+     * Used by ProviderResolver as fallback when tool doesn't specify oauthProvider.
+     */
+    configuredProvider?: string | null;
+}
+/**
+ * Zod schema for OAuthProvider validation
+ */
+export declare const OAuthProviderSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    authorizationUrl: z.ZodString;
+    tokenUrl: z.ZodString;
+    userInfoUrl: z.ZodOptional<z.ZodString>;
+    supportsPKCE: z.ZodBoolean;
+    requiresClientSecret: z.ZodBoolean;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    proxyMode: z.ZodOptional<z.ZodBoolean>;
+    customParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    tokenEndpointAuthMethod: z.ZodOptional<z.ZodEnum<["client_secret_post", "client_secret_basic"]>>;
+    responseType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    grantType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    supportsPKCE: boolean;
+    requiresClientSecret: boolean;
+    responseType: string;
+    grantType: string;
+    scopes?: string[] | undefined;
+    clientSecret?: string | null | undefined;
+    userInfoUrl?: string | undefined;
+    defaultScopes?: string[] | undefined;
+    proxyMode?: boolean | undefined;
+    customParams?: Record<string, string> | undefined;
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+}, {
+    clientId: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    supportsPKCE: boolean;
+    requiresClientSecret: boolean;
+    scopes?: string[] | undefined;
+    clientSecret?: string | null | undefined;
+    userInfoUrl?: string | undefined;
+    defaultScopes?: string[] | undefined;
+    proxyMode?: boolean | undefined;
+    customParams?: Record<string, string> | undefined;
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    responseType?: string | undefined;
+    grantType?: string | undefined;
+}>;
+/**
+ * Zod schema for OAuthConfig validation
+ */
+export declare const OAuthConfigSchema: z.ZodObject<{
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        clientId: z.ZodString;
+        clientSecret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authorizationUrl: z.ZodString;
+        tokenUrl: z.ZodString;
+        userInfoUrl: z.ZodOptional<z.ZodString>;
+        supportsPKCE: z.ZodBoolean;
+        requiresClientSecret: z.ZodBoolean;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        proxyMode: z.ZodOptional<z.ZodBoolean>;
+        customParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        tokenEndpointAuthMethod: z.ZodOptional<z.ZodEnum<["client_secret_post", "client_secret_basic"]>>;
+        responseType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        grantType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        responseType: string;
+        grantType: string;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    }, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+        responseType?: string | undefined;
+        grantType?: string | undefined;
+    }>>;
+    configuredProvider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    providers: Record<string, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        responseType: string;
+        grantType: string;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    }>;
+    configuredProvider?: string | null | undefined;
+}, {
+    providers: Record<string, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+        responseType?: string | undefined;
+        grantType?: string | undefined;
+    }>;
+    configuredProvider?: string | null | undefined;
+}>;
+/**
+ * IDP Tokens
+ *
+ * Tokens received from OAuth provider (IDP = Identity Provider)
+ */
+export interface IdpTokens {
+    /** OAuth access token for API calls */
+    access_token: string;
+    /** OAuth refresh token (optional) */
+    refresh_token?: string;
+    /** Token expiration time in seconds */
+    expires_in?: number;
+    /** Token expiration timestamp (milliseconds since epoch) */
+    expires_at: number;
+    /** Token type (usually "Bearer") */
+    token_type: string;
+    /** Granted scopes */
+    scope?: string;
 }
 /**
  * Agent identity representation

package/dist/config/identity.js

@@ -8,3 +8,32 @@
  * @module @kya-os/contracts/config
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthConfigSchema = exports.OAuthProviderSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Zod schema for OAuthProvider validation
+ */
+exports.OAuthProviderSchema = zod_1.z.object({
+    clientId: zod_1.z.string().min(1),
+    clientSecret: zod_1.z.string().nullable().optional(),
+    authorizationUrl: zod_1.z.string().url(),
+    tokenUrl: zod_1.z.string().url(),
+    userInfoUrl: zod_1.z.string().url().optional(),
+    supportsPKCE: zod_1.z.boolean(),
+    requiresClientSecret: zod_1.z.boolean(),
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    defaultScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    proxyMode: zod_1.z.boolean().optional(),
+    // Phase 3: Custom IDP Support
+    customParams: zod_1.z.record(zod_1.z.string()).optional(),
+    tokenEndpointAuthMethod: zod_1.z.enum(["client_secret_post", "client_secret_basic"]).optional(),
+    responseType: zod_1.z.string().optional().default("code"),
+    grantType: zod_1.z.string().optional().default("authorization_code"),
+});
+/**
+ * Zod schema for OAuthConfig validation
+ */
+exports.OAuthConfigSchema = zod_1.z.object({
+    providers: zod_1.z.record(zod_1.z.string(), exports.OAuthProviderSchema),
+    configuredProvider: zod_1.z.string().nullable().optional(),
+});

package/dist/config/index.d.ts

@@ -12,7 +12,8 @@ import type { ProofingConfig } from "./proofing.js";
 import type { DelegationConfig } from "./delegation.js";
 import type { ToolProtectionSourceConfig } from "./tool-protection.js";
 export { MCPIBaseConfig } from "./base.js";
-export { RuntimeIdentityConfig, AgentIdentity } from "./identity.js";
+export { RuntimeIdentityConfig, AgentIdentity, OAuthProvider, OAuthConfig, IdpTokens, } from "./identity.js";
+export type { ToolExecutionContext } from "./tool-context.js";
 /**
  * @deprecated Use RuntimeIdentityConfig instead
  * This export is maintained for backward compatibility

package/dist/config/tool-context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool Execution Context
+ *
+ * Execution context passed to tool handlers, enabling tools to access
+ * IDP tokens for external API calls (GitHub, Google, etc.).
+ *
+ * All fields are optional for backward compatibility - tools that don't
+ * require OAuth will receive undefined context.
+ *
+ * @package @kya-os/contracts
+ */
+/**
+ * Execution context passed to tool handlers
+ *
+ * Enables tools to access IDP tokens for external API calls.
+ * Context is only provided when:
+ * - Tool requires OAuth (has requiredScopes)
+ * - User DID is available
+ * - IDP token is successfully resolved
+ */
+export interface ToolExecutionContext {
+    /** IDP access token for external API calls (e.g., GitHub, Google) */
+    idpToken?: string;
+    /** OAuth provider name (e.g., "github", "google") */
+    provider?: string;
+    /** Scopes granted for this token */
+    scopes?: string[];
+    /** User DID associated with this token */
+    userDid?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Delegation token (MCP-I internal authorization) */
+    delegationToken?: string;
+}

package/dist/config/tool-context.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Tool Execution Context
+ *
+ * Execution context passed to tool handlers, enabling tools to access
+ * IDP tokens for external API calls (GitHub, Google, etc.).
+ *
+ * All fields are optional for backward compatibility - tools that don't
+ * require OAuth will receive undefined context.
+ *
+ * @package @kya-os/contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/consent/schemas.d.ts

@@ -165,13 +165,14 @@ export type OAuthIdentity = z.infer<typeof oauthIdentitySchema>;
 /**
  * Consent Page Config Schema
  */
-export declare const consentPageConfigSchema: z.ZodObject<{
+export declare const consentPageConfigSchema: z.ZodEffects<z.ZodObject<{
     tool: z.ZodString;
     toolDescription: z.ZodString;
     scopes: z.ZodArray<z.ZodString, "many">;
     agentDid: z.ZodString;
     sessionId: z.ZodString;
     projectId: z.ZodString;
+    provider: z.ZodOptional<z.ZodString>;
     branding: z.ZodOptional<z.ZodObject<{
         primaryColor: z.ZodOptional<z.ZodString>;
         logoUrl: z.ZodOptional<z.ZodString>;
@@ -268,14 +269,25 @@ export declare const consentPageConfigSchema: z.ZodObject<{
     }>, "many">>;
     serverUrl: z.ZodString;
     autoClose: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Whether OAuth authorization is required immediately
+     * If true, the consent page will act as a landing page before redirecting
+     */
+    oauthRequired: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * The OAuth authorization URL to redirect to
+     * Required if oauthRequired is true
+     */
+    oauthUrl: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
 }, "strip", z.ZodTypeAny, {
     agentDid: string;
     sessionId: string;
     tool: string;
     scopes: string[];
     projectId: string;
-    toolDescription: string;
     serverUrl: string;
+    toolDescription: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -301,14 +313,89 @@ export declare const consentPageConfigSchema: z.ZodObject<{
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }, {
     agentDid: string;
     sessionId: string;
     tool: string;
     scopes: string[];
     projectId: string;
+    serverUrl: string;
+    toolDescription: string;
+    provider?: string | undefined;
+    branding?: {
+        primaryColor?: string | undefined;
+        logoUrl?: string | undefined;
+        companyName?: string | undefined;
+        theme?: "light" | "dark" | "auto" | undefined;
+    } | undefined;
+    terms?: {
+        version?: string | undefined;
+        url?: string | undefined;
+        required?: boolean | undefined;
+        text?: string | undefined;
+    } | undefined;
+    customFields?: {
+        type: "text" | "textarea" | "checkbox" | "select";
+        name: string;
+        required: boolean;
+        label: string;
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        placeholder?: string | undefined;
+        pattern?: string | undefined;
+    }[] | undefined;
+    autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
+}>, {
+    agentDid: string;
+    sessionId: string;
+    tool: string;
+    scopes: string[];
+    projectId: string;
+    serverUrl: string;
     toolDescription: string;
+    provider?: string | undefined;
+    branding?: {
+        primaryColor?: string | undefined;
+        logoUrl?: string | undefined;
+        companyName?: string | undefined;
+        theme?: "light" | "dark" | "auto" | undefined;
+    } | undefined;
+    terms?: {
+        required: boolean;
+        version?: string | undefined;
+        url?: string | undefined;
+        text?: string | undefined;
+    } | undefined;
+    customFields?: {
+        type: "text" | "textarea" | "checkbox" | "select";
+        name: string;
+        required: boolean;
+        label: string;
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        placeholder?: string | undefined;
+        pattern?: string | undefined;
+    }[] | undefined;
+    autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
+}, {
+    agentDid: string;
+    sessionId: string;
+    tool: string;
+    scopes: string[];
+    projectId: string;
     serverUrl: string;
+    toolDescription: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -334,6 +421,8 @@ export declare const consentPageConfigSchema: z.ZodObject<{
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }>;
 export type ConsentPageConfig = z.infer<typeof consentPageConfigSchema>;
 /**
@@ -658,8 +747,9 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
     tool: string;
     scopes: string[];
     projectId: string;
-    toolDescription: string;
     serverUrl: string;
+    toolDescription: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -685,14 +775,17 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }, {
     agentDid: string;
     sessionId: string;
     tool: string;
     scopes: string[];
     projectId: string;
-    toolDescription: string;
     serverUrl: string;
+    toolDescription: string;
+    provider?: string | undefined;
     branding?: {
         primaryColor?: string | undefined;
         logoUrl?: string | undefined;
@@ -718,6 +811,8 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
         pattern?: string | undefined;
     }[] | undefined;
     autoClose?: boolean | undefined;
+    oauthRequired?: boolean | undefined;
+    oauthUrl?: string | undefined;
 }>;
 /**
  * Validate a consent approval request

package/dist/consent/schemas.js

@@ -132,7 +132,8 @@ exports.oauthIdentitySchema = zod_1.z.object({
 /**
  * Consent Page Config Schema
  */
-exports.consentPageConfigSchema = zod_1.z.object({
+exports.consentPageConfigSchema = zod_1.z
+    .object({
     tool: zod_1.z.string().min(1, "Tool name is required"),
     toolDescription: zod_1.z
         .string()
@@ -141,6 +142,7 @@ exports.consentPageConfigSchema = zod_1.z.object({
     agentDid: zod_1.z.string().min(1, "Agent DID is required"),
     sessionId: zod_1.z.string().min(1, "Session ID is required"),
     projectId: zod_1.z.string().min(1, "Project ID is required"),
+    provider: zod_1.z.string().optional(), // Phase 2: OAuth provider name (e.g., "github", "google")
     branding: exports.consentBrandingSchema.optional(),
     terms: exports.consentTermsSchema.optional(),
     customFields: zod_1.z
@@ -149,6 +151,42 @@ exports.consentPageConfigSchema = zod_1.z.object({
         .optional(),
     serverUrl: zod_1.z.string().url("Server URL must be a valid URL"),
     autoClose: zod_1.z.boolean().optional(),
+    /**
+     * Whether OAuth authorization is required immediately
+     * If true, the consent page will act as a landing page before redirecting
+     */
+    oauthRequired: zod_1.z.boolean().optional(),
+    /**
+     * The OAuth authorization URL to redirect to
+     * Required if oauthRequired is true
+     */
+    oauthUrl: zod_1.z
+        .union([
+        zod_1.z.string().url(),
+        zod_1.z.literal(""), // Allow empty string to catch it in refine with better error
+    ])
+        .optional(),
+})
+    .superRefine((data, ctx) => {
+    // If oauthRequired is true, oauthUrl must be provided and non-empty
+    if (data.oauthRequired === true) {
+        if (data.oauthUrl === undefined || data.oauthUrl === "") {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "oauthUrl is required when oauthRequired is true",
+                path: ["oauthUrl"],
+            });
+            return;
+        }
+    }
+    // If oauthUrl is provided (not undefined), it must be a valid URL (not empty)
+    if (data.oauthUrl !== undefined && data.oauthUrl === "") {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "oauthUrl must be a valid URL",
+            path: ["oauthUrl"],
+        });
+    }
 });
 /**
  * Consent Approval Request Schema