@pikku/openapi-parser 0.12.11 → 0.12.13

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pikku/openapi-parser
 
+## 0.12.13
+
+### Patch Changes
+
+- 0f3edd3: Support an operator-supplied auth config that overrides/augments a spec's securitySchemes: custom auth header name/format (e.g. a raw token in `authentication:` instead of `Authorization: Bearer`), and a delegated-login descriptor (login path, credential fields, token dot-path, claims mapping from the decoded JWT payload or response body) that emits a self-contained `src/<name>-upstream-auth.ts` `authenticate<Name>Upstream()` for wiring into `@pikku/better-auth`'s `delegatedAuth()` plugin.
+
+## 0.12.12
+
+### Patch Changes
+
+- d97f2a1: Always emit a description for generated addon functions (and their MCP tools). When an OpenAPI operation omits both `description` and `summary` (common), the generator now synthesizes one — a humanized `operationId` (with the `Controller` segment stripped), else `METHOD /path` — instead of emitting none. This removes the "MCP tool is missing a description" warnings and makes `--mcp`-exposed tools usable.
+
 ## 0.12.11
 
 ### Patch Changes

package/dist/auth-config.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export declare const DelegatedClaimsSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        jwt: "jwt";
+        response: "response";
+    }>;
+    externalId: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    role: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const DelegatedLoginSchema: z.ZodObject<{
+    loginPath: z.ZodString;
+    loginMethod: z.ZodDefault<z.ZodString>;
+    credentials: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        email: "email";
+        password: "password";
+        apiKey: "apiKey";
+    }>>>;
+    apiKeyHeader: z.ZodDefault<z.ZodString>;
+    tokenPath: z.ZodString;
+    expiresAtPath: z.ZodOptional<z.ZodString>;
+    claims: z.ZodObject<{
+        source: z.ZodEnum<{
+            jwt: "jwt";
+            response: "response";
+        }>;
+        externalId: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        role: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const AuthConfigSchema: z.ZodObject<{
+    headerName: z.ZodOptional<z.ZodString>;
+    headerFormat: z.ZodOptional<z.ZodEnum<{
+        raw: "raw";
+        bearer: "bearer";
+    }>>;
+    delegated: z.ZodOptional<z.ZodObject<{
+        loginPath: z.ZodString;
+        loginMethod: z.ZodDefault<z.ZodString>;
+        credentials: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            email: "email";
+            password: "password";
+            apiKey: "apiKey";
+        }>>>;
+        apiKeyHeader: z.ZodDefault<z.ZodString>;
+        tokenPath: z.ZodString;
+        expiresAtPath: z.ZodOptional<z.ZodString>;
+        claims: z.ZodObject<{
+            source: z.ZodEnum<{
+                jwt: "jwt";
+                response: "response";
+            }>;
+            externalId: z.ZodString;
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            role: z.ZodOptional<z.ZodString>;
+            tenantId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DelegatedLoginConfig = z.infer<typeof DelegatedLoginSchema>;
+export type AuthConfig = z.infer<typeof AuthConfigSchema>;
+/** The effective value template for the auth header. */
+export declare const authHeaderValue: (config: AuthConfig, tokenExpr: string) => {
+    header: string;
+    value: string;
+};
+/** Load and validate an auth-config JSON file; throws with the zod issue list on mismatch. */
+export declare function loadAuthConfig(filePath: string): Promise<AuthConfig>;

package/dist/auth-config.js

@@ -0,0 +1,74 @@
+/**
+ * Operator/agent-supplied auth configuration that overrides or augments an
+ * OpenAPI spec's securitySchemes. Needed for real-world enterprise specs that
+ * carry no machine-readable auth at all (auth described only in prose), or
+ * that use a custom auth header the spec doesn't declare.
+ */
+import { readFile } from 'fs/promises';
+import { z } from 'zod';
+export const DelegatedClaimsSchema = z.object({
+    /** Where identity claims live: the decoded login-JWT payload, or the login response body. */
+    source: z.enum(['jwt', 'response']),
+    /** Dot-path to the stable upstream user id (e.g. 'user._id'). */
+    externalId: z.string(),
+    email: z.string(),
+    /** One dot-path, or several joined with a space (e.g. first + last name). */
+    name: z.union([z.string(), z.array(z.string())]).optional(),
+    role: z.string().optional(),
+    tenantId: z.string().optional(),
+});
+export const DelegatedLoginSchema = z.object({
+    /** Spec-relative path of the login operation (e.g. '/users/login'). */
+    loginPath: z.string(),
+    loginMethod: z.string().default('post'),
+    /** Which credential fields the login accepts. email/password go in the JSON body; apiKey in a header. */
+    credentials: z
+        .array(z.enum(['email', 'password', 'apiKey']))
+        .default(['email', 'password']),
+    /** Header carrying the apiKey when 'apiKey' is a supported credential. */
+    apiKeyHeader: z.string().default('x-api-key'),
+    /** Dot-path to the token in the login response (e.g. 'token'). */
+    tokenPath: z.string(),
+    /** Dot-path to an epoch-seconds expiry in the response; defaults to the JWT `exp` claim when source is jwt. */
+    expiresAtPath: z.string().optional(),
+    claims: DelegatedClaimsSchema,
+});
+export const AuthConfigSchema = z.object({
+    /** Auth header the API expects on authenticated calls (e.g. 'authentication'). Overrides the spec. */
+    headerName: z.string().optional(),
+    /** 'raw' sends the bare token; 'bearer' prefixes it. Default: bearer for Authorization, raw for custom headers. */
+    headerFormat: z.enum(['raw', 'bearer']).optional(),
+    /** Present when end-users sign in with their existing upstream credentials (delegated login). */
+    delegated: DelegatedLoginSchema.optional(),
+});
+/** The effective value template for the auth header. */
+export const authHeaderValue = (config, tokenExpr) => {
+    const header = config.headerName ?? 'Authorization';
+    const format = config.headerFormat ??
+        (config.headerName && config.headerName !== 'Authorization'
+            ? 'raw'
+            : 'bearer');
+    return {
+        header,
+        value: format === 'bearer' ? `\`Bearer \${${tokenExpr}}\`` : tokenExpr,
+    };
+};
+/** Load and validate an auth-config JSON file; throws with the zod issue list on mismatch. */
+export async function loadAuthConfig(filePath) {
+    const raw = await readFile(filePath, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Auth config ${filePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = AuthConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Auth config ${filePath} is invalid:\n${issues}`);
+    }
+    return result.data;
+}

package/dist/codegen.d.ts

@@ -3,6 +3,7 @@
  * Returns Record<string, string> compatible with getAddonFiles output.
  */
 import type { ParsedSpec } from './parse-openapi.js';
+import { type AuthConfig } from './auth-config.js';
 interface AddonVars {
     name: string;
     camelName: string;
@@ -17,6 +18,8 @@ interface CodegenFlags {
     credential?: 'apikey' | 'bearer' | 'oauth2';
     mcp?: boolean;
     camelCase?: boolean;
+    /** Operator-supplied auth overrides (custom header, delegated login). */
+    authConfig?: AuthConfig;
 }
 export declare function generateAddonFromOpenAPI(spec: ParsedSpec, vars: AddonVars, flags: CodegenFlags): Record<string, string>;
 export {};

package/dist/codegen.js

@@ -1,5 +1,6 @@
 import { schemaToZod, schemaVarName, sanitizeTypeName, createContext, snakeToCamel, } from './zod-codegen.js';
 import { generateOperationNames, detectCommonPrefix, } from './naming.js';
+import { authHeaderValue } from './auth-config.js';
 function safeKey(key) {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
 }
@@ -27,12 +28,41 @@ const STATUS_TO_ERROR = {
 function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId) {
+    if (!operationId)
+        return undefined;
+    const words = operationId
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(/\s+/)
+        .map((w) => w.trim())
+        .filter((w) => w && w.toLowerCase() !== 'controller');
+    if (words.length === 0)
+        return undefined;
+    return capitalize(words.join(' ').toLowerCase());
+}
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
 function humanDescription(parsed) {
     const description = parsed.description?.trim();
     if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
         return capitalize(description);
     }
-    return undefined;
+    const summary = parsed.summary?.trim();
+    if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+        return capitalize(summary);
+    }
+    return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`;
 }
 function getErrorClassesForResponses(errorResponses) {
     const classes = [];
@@ -254,8 +284,17 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
         files[`src/functions/${named.functionName}.function.ts`] = funcCode;
         functionExports.push(named.functionName);
     }
+    // Delegated login: emit the upstream authenticate() implementation
+    const upstreamAuthExport = flags.authConfig?.delegated
+        ? `authenticate${vars.pascalName}Upstream`
+        : undefined;
+    if (flags.authConfig?.delegated) {
+        files[`src/${name}-upstream-auth.ts`] = generateUpstreamAuthFile(vars, flags.authConfig);
+    }
     // Generate index.ts with all exports
-    files['src/index.ts'] = generateIndexFile(functionExports);
+    files['src/index.ts'] = generateIndexFile(functionExports, {
+        upstreamAuth: upstreamAuthExport ? { name, export: upstreamAuthExport } : undefined,
+    });
     // Generate typed API service class with route map
     files[`src/${name}-api.service.ts`] = generateServiceFile(spec, opPairs, vars, flags);
     // Generate variable file for BASE_URL
@@ -720,11 +759,164 @@ function buildOutputSchema(schema, ctx) {
     }
     return schemaToZod(schema, ctx);
 }
-function generateIndexFile(functionExports) {
+function generateIndexFile(functionExports, extras) {
     const lines = [];
     for (const name of functionExports) {
         lines.push(`export { ${name} } from './functions/${name}.function.js'`);
     }
+    if (extras?.upstreamAuth) {
+        lines.push(`export { ${extras.upstreamAuth.export} } from './${extras.upstreamAuth.name}-upstream-auth.js'`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Emit `src/<name>-upstream-auth.ts`: a self-contained authenticate() for
+ * delegated login. It performs the upstream login call described by the auth
+ * config, extracts the token, reads identity claims from the decoded JWT
+ * payload (base64url, NOT signature-verified — the token was just received
+ * over TLS from the login we ourselves performed) or the response body, and
+ * returns an identity object structurally compatible with
+ * `@pikku/better-auth`'s `UpstreamIdentity` — without depending on it.
+ */
+function generateUpstreamAuthFile(vars, authConfig) {
+    const { pascalName } = vars;
+    const delegated = authConfig.delegated;
+    const claims = delegated.claims;
+    const namePaths = claims.name
+        ? Array.isArray(claims.name)
+            ? claims.name
+            : [claims.name]
+        : [];
+    const lines = [];
+    lines.push(`export interface ${pascalName}UpstreamIdentity {`);
+    lines.push('  externalId: string');
+    lines.push('  email: string');
+    lines.push('  name?: string');
+    lines.push('  role?: string');
+    lines.push('  tenantId?: string');
+    lines.push('  credential: { token: string; expiresAt?: number; tenantId?: string }');
+    lines.push('}');
+    lines.push('');
+    lines.push(`export interface ${pascalName}UpstreamCredentials {`);
+    lines.push('  email?: string');
+    lines.push('  password?: string');
+    lines.push('  apiKey?: string');
+    lines.push('}');
+    lines.push('');
+    lines.push('const pick = (obj: unknown, path: string): unknown =>');
+    lines.push('  path');
+    lines.push("    .split('.')");
+    lines.push('    .reduce<any>(');
+    lines.push("      (o, key) => (o && typeof o === 'object' ? o[key] : undefined),");
+    lines.push('      obj');
+    lines.push('    )');
+    lines.push('');
+    lines.push('const str = (value: unknown): string | undefined =>');
+    lines.push("  typeof value === 'string' && value ? value : typeof value === 'number' ? String(value) : undefined");
+    lines.push('');
+    lines.push('/** Decode a JWT payload without verifying — see file docblock. */');
+    lines.push('const decodeJwtPayload = (token: string): unknown => {');
+    lines.push("  const part = token.split('.')[1]");
+    lines.push('  if (!part) return undefined');
+    lines.push('  try {');
+    lines.push("    const pad = part + '==='.slice((part.length + 3) % 4)");
+    lines.push("    const bin = atob(pad.replace(/-/g, '+').replace(/_/g, '/'))");
+    lines.push('    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))');
+    lines.push('    return JSON.parse(new TextDecoder().decode(bytes))');
+    lines.push('  } catch {');
+    lines.push('    // Not a decodable JWT — caller treats it as missing claims.');
+    lines.push('    return undefined');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    lines.push('/**');
+    lines.push(` * Verify credentials against the upstream ${vars.displayName} login and map`);
+    lines.push(' * its response onto an upstream identity. Returns null when the upstream');
+    lines.push(' * rejects the credentials; network errors propagate to the caller.');
+    lines.push(' */');
+    lines.push(`export const authenticate${pascalName}Upstream = async (`);
+    lines.push(`  credentials: ${pascalName}UpstreamCredentials,`);
+    lines.push('  baseUrl: string');
+    lines.push(`): Promise<${pascalName}UpstreamIdentity | null> => {`);
+    lines.push("  const headers: Record<string, string> = { 'Content-Type': 'application/json' }");
+    lines.push('  const body: Record<string, string> = {}');
+    if (delegated.credentials.includes('email')) {
+        lines.push('  if (credentials.email) body.email = credentials.email');
+    }
+    if (delegated.credentials.includes('password')) {
+        lines.push('  if (credentials.password) body.password = credentials.password');
+    }
+    if (delegated.credentials.includes('apiKey')) {
+        lines.push(`  if (credentials.apiKey) headers[${JSON.stringify(delegated.apiKeyHeader)}] = credentials.apiKey`);
+    }
+    lines.push('');
+    lines.push(`  const response = await fetch(\`\${baseUrl.replace(/\\/+$/, '')}${delegated.loginPath}\`, {`);
+    lines.push(`    method: ${JSON.stringify(delegated.loginMethod.toUpperCase())},`);
+    lines.push('    headers,');
+    lines.push('    body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,');
+    lines.push('  })');
+    lines.push('  if (!response.ok) return null');
+    lines.push('');
+    lines.push('  const data: unknown = await response.json()');
+    lines.push(`  const token = str(pick(data, ${JSON.stringify(delegated.tokenPath)}))`);
+    lines.push('  if (!token) return null');
+    lines.push('');
+    if (claims.source === 'jwt') {
+        lines.push('  const claims = decodeJwtPayload(token)');
+    }
+    else {
+        lines.push('  const claims = data');
+    }
+    lines.push('  if (!claims) return null');
+    lines.push('');
+    lines.push(`  const externalId = str(pick(claims, ${JSON.stringify(claims.externalId)}))`);
+    lines.push(`  const email = str(pick(claims, ${JSON.stringify(claims.email)}))`);
+    lines.push('  if (!externalId || !email) return null');
+    lines.push('');
+    if (namePaths.length > 0) {
+        const parts = namePaths
+            .map((p) => `str(pick(claims, ${JSON.stringify(p)}))`)
+            .join(', ');
+        lines.push(`  const name = [${parts}]`);
+        lines.push('    .filter((part): part is string => Boolean(part))');
+        lines.push("    .join(' ') || undefined");
+    }
+    else {
+        lines.push('  const name = undefined');
+    }
+    if (claims.role) {
+        lines.push(`  const role = str(pick(claims, ${JSON.stringify(claims.role)}))`);
+    }
+    else {
+        lines.push('  const role = undefined');
+    }
+    if (claims.tenantId) {
+        lines.push(`  const tenantId = str(pick(claims, ${JSON.stringify(claims.tenantId)}))`);
+    }
+    else {
+        lines.push('  const tenantId = undefined');
+    }
+    if (delegated.expiresAtPath) {
+        lines.push(`  const expiresAtRaw = pick(data, ${JSON.stringify(delegated.expiresAtPath)})`);
+    }
+    else if (claims.source === 'jwt') {
+        lines.push("  const expiresAtRaw = pick(claims, 'exp')");
+    }
+    else {
+        lines.push('  const expiresAtRaw = undefined');
+    }
+    lines.push("  const expiresAt = typeof expiresAtRaw === 'number' ? expiresAtRaw : undefined");
+    lines.push('');
+    lines.push('  return {');
+    lines.push('    externalId,');
+    lines.push('    email,');
+    lines.push('    name,');
+    lines.push('    role,');
+    lines.push('    tenantId,');
+    lines.push('    credential: { token, expiresAt, tenantId },');
+    lines.push('  }');
+    lines.push('}');
     lines.push('');
     return lines.join('\n');
 }
@@ -890,12 +1082,23 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     if (flags.credential && flags.credential !== 'oauth2') {
         // Per-user credential: use creds from wire.getCredentials()
         if (flags.credential === 'bearer') {
-            lines.push('    headers.Authorization = `Bearer ${this.creds.token}`');
+            if (flags.authConfig?.headerName) {
+                // Custom auth header (e.g. `authentication: <raw jwt>`) from the auth config.
+                const { header, value } = authHeaderValue(flags.authConfig, 'this.creds.token');
+                lines.push(`    headers[${JSON.stringify(header)}] = ${value}`);
+            }
+            else {
+                lines.push('    headers.Authorization = `Bearer ${this.creds.token}`');
+            }
         }
         else {
-            // apikey: check spec for custom header name
+            // apikey: auth-config override wins, else check spec for custom header name
             const apiKeyScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'apiKey');
-            if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
+            if (flags.authConfig?.headerName) {
+                const { header, value } = authHeaderValue(flags.authConfig, 'this.creds.apiKey');
+                lines.push(`    headers[${JSON.stringify(header)}] = ${value}`);
+            }
+            else if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
                 lines.push(`    headers[${JSON.stringify(apiKeyScheme.name)}] = this.creds.apiKey`);
             }
             else {
@@ -917,9 +1120,13 @@ function generateServiceFile(spec, opPairs, vars, flags) {
         lines.push('    })');
     }
     else if (flags.secret) {
-        // Use apiKey details from spec if available
+        // Auth-config override wins, else use apiKey details from spec if available
         const apiKeyScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'apiKey');
-        if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
+        if (flags.authConfig?.headerName) {
+            const { header, value } = authHeaderValue(flags.authConfig, 'this.creds.apiKey');
+            lines.push(`    headers[${JSON.stringify(header)}] = ${value}`);
+        }
+        else if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
             lines.push(`    headers[${JSON.stringify(apiKeyScheme.name)}] = this.creds.apiKey`);
         }
         else {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { parseOpenAPISpec, computeContractHash, type ParsedSpec, type ParsedOperation, type ParsedParam, type ErrorResponse, type SecuritySchemeInfo, } from './parse-openapi.js';
 export { generateAddonFromOpenAPI } from './codegen.js';
+export { AuthConfigSchema, DelegatedLoginSchema, loadAuthConfig, authHeaderValue, type AuthConfig, type DelegatedLoginConfig, } from './auth-config.js';
 export { generateOperationNames, detectCommonPrefix, type NamedOperation, } from './naming.js';
 export { type OpenAPISchema, type ZodCodegenContext, createContext, schemaToZod, schemaVarName, sanitizeTypeName, snakeToCamel, } from './openapi-to-zod-schema.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { parseOpenAPISpec, computeContractHash, } from './parse-openapi.js';
 export { generateAddonFromOpenAPI } from './codegen.js';
+export { AuthConfigSchema, DelegatedLoginSchema, loadAuthConfig, authHeaderValue, } from './auth-config.js';
 export { generateOperationNames, detectCommonPrefix, } from './naming.js';
 export { createContext, schemaToZod, schemaVarName, sanitizeTypeName, snakeToCamel, } from './openapi-to-zod-schema.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "OpenAPI spec parser and code generator for Pikku",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/auth-config.ts

@@ -0,0 +1,87 @@
+/**
+ * Operator/agent-supplied auth configuration that overrides or augments an
+ * OpenAPI spec's securitySchemes. Needed for real-world enterprise specs that
+ * carry no machine-readable auth at all (auth described only in prose), or
+ * that use a custom auth header the spec doesn't declare.
+ */
+import { readFile } from 'fs/promises'
+import { z } from 'zod'
+
+export const DelegatedClaimsSchema = z.object({
+  /** Where identity claims live: the decoded login-JWT payload, or the login response body. */
+  source: z.enum(['jwt', 'response']),
+  /** Dot-path to the stable upstream user id (e.g. 'user._id'). */
+  externalId: z.string(),
+  email: z.string(),
+  /** One dot-path, or several joined with a space (e.g. first + last name). */
+  name: z.union([z.string(), z.array(z.string())]).optional(),
+  role: z.string().optional(),
+  tenantId: z.string().optional(),
+})
+
+export const DelegatedLoginSchema = z.object({
+  /** Spec-relative path of the login operation (e.g. '/users/login'). */
+  loginPath: z.string(),
+  loginMethod: z.string().default('post'),
+  /** Which credential fields the login accepts. email/password go in the JSON body; apiKey in a header. */
+  credentials: z
+    .array(z.enum(['email', 'password', 'apiKey']))
+    .default(['email', 'password']),
+  /** Header carrying the apiKey when 'apiKey' is a supported credential. */
+  apiKeyHeader: z.string().default('x-api-key'),
+  /** Dot-path to the token in the login response (e.g. 'token'). */
+  tokenPath: z.string(),
+  /** Dot-path to an epoch-seconds expiry in the response; defaults to the JWT `exp` claim when source is jwt. */
+  expiresAtPath: z.string().optional(),
+  claims: DelegatedClaimsSchema,
+})
+
+export const AuthConfigSchema = z.object({
+  /** Auth header the API expects on authenticated calls (e.g. 'authentication'). Overrides the spec. */
+  headerName: z.string().optional(),
+  /** 'raw' sends the bare token; 'bearer' prefixes it. Default: bearer for Authorization, raw for custom headers. */
+  headerFormat: z.enum(['raw', 'bearer']).optional(),
+  /** Present when end-users sign in with their existing upstream credentials (delegated login). */
+  delegated: DelegatedLoginSchema.optional(),
+})
+
+export type DelegatedLoginConfig = z.infer<typeof DelegatedLoginSchema>
+export type AuthConfig = z.infer<typeof AuthConfigSchema>
+
+/** The effective value template for the auth header. */
+export const authHeaderValue = (
+  config: AuthConfig,
+  tokenExpr: string
+): { header: string; value: string } => {
+  const header = config.headerName ?? 'Authorization'
+  const format =
+    config.headerFormat ??
+    (config.headerName && config.headerName !== 'Authorization'
+      ? 'raw'
+      : 'bearer')
+  return {
+    header,
+    value: format === 'bearer' ? `\`Bearer \${${tokenExpr}}\`` : tokenExpr,
+  }
+}
+
+/** Load and validate an auth-config JSON file; throws with the zod issue list on mismatch. */
+export async function loadAuthConfig(filePath: string): Promise<AuthConfig> {
+  const raw = await readFile(filePath, 'utf-8')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(
+      `Auth config ${filePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+  const result = AuthConfigSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('\n')
+    throw new Error(`Auth config ${filePath} is invalid:\n${issues}`)
+  }
+  return result.data
+}

package/src/codegen.test.ts

@@ -780,3 +780,165 @@ describe('camelCase flag', () => {
     )
   })
 })
+
+// ---------------------------------------------------------------------------
+// Function/MCP-tool description synthesis (specs that omit descriptions)
+// ---------------------------------------------------------------------------
+describe('function description synthesis', () => {
+  test('synthesizes a description from operationId when the spec omits one', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({
+          operationId: 'contactsControllerGetContacts',
+          method: 'get',
+          path: '/contacts',
+        }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      mcp: true,
+    })
+    const funcFile = files['src/functions/contactsControllerGetContacts.function.ts']
+    assert.ok(funcFile, 'function file should exist')
+    assert.ok(
+      funcFile.includes('description: "Contacts get contacts"'),
+      'humanized operationId (Controller stripped) should be emitted as the description'
+    )
+    assert.ok(funcFile.includes('mcp: true'), 'mcp tool flag should be present')
+  })
+
+  test('falls back to "METHOD /path" when operationId is absent', () => {
+    const spec = makeSpec({
+      operations: [makeOp({ operationId: undefined, method: 'get', path: '/health' })],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const key = Object.keys(files).find((k) => k.startsWith('src/functions/'))
+    assert.ok(key, 'a function file should be generated')
+    assert.ok(
+      files[key].includes('description: "GET /health"'),
+      'should fall back to METHOD path when nothing else is available'
+    )
+  })
+
+  test('prefers the spec description over synthesis', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({ operationId: 'getPet', description: 'Fetch a single pet by id' }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const funcFile = files['src/functions/getPet.function.ts']
+    assert.ok(
+      funcFile.includes('description: "Fetch a single pet by id"'),
+      'the real spec description should win over the synthesized one'
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Auth-config: custom headers + delegated login
+// ---------------------------------------------------------------------------
+describe('auth config', () => {
+  const delegatedConfig = {
+    headerName: 'authentication',
+    headerFormat: 'raw' as const,
+    delegated: {
+      loginPath: '/users/login-ai-plugin',
+      loginMethod: 'post',
+      credentials: ['email', 'password'] as ('email' | 'password' | 'apiKey')[],
+      apiKeyHeader: 'x-api-key',
+      tokenPath: 'token',
+      claims: {
+        source: 'jwt' as const,
+        externalId: 'user._id',
+        email: 'user.email',
+        name: ['user.first_name', 'user.last_name'],
+        role: 'user.role',
+        tenantId: 'user.company',
+      },
+    },
+  }
+
+  test('custom raw header replaces Authorization Bearer in the bearer-credential service', () => {
+    const spec = makeSpec({ operations: [makeOp()] })
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      credential: 'bearer',
+      authConfig: delegatedConfig,
+    })
+    const service = files['src/test-api-api.service.ts']
+    assert.ok(
+      service.includes('headers["authentication"] = this.creds.token'),
+      'custom raw header should carry the bare token'
+    )
+    assert.ok(
+      !service.includes('headers.Authorization'),
+      'default Authorization header must not be emitted'
+    )
+  })
+
+  test('custom header with bearer format keeps the Bearer prefix', () => {
+    const spec = makeSpec({ operations: [makeOp()] })
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      credential: 'bearer',
+      authConfig: { headerName: 'x-auth', headerFormat: 'bearer' as const },
+    })
+    const service = files['src/test-api-api.service.ts']
+    assert.ok(
+      service.includes('headers["x-auth"] = `Bearer ${this.creds.token}`'),
+      'bearer format should keep the prefix on the custom header'
+    )
+  })
+
+  test('delegated config emits the upstream-auth file and exports it', () => {
+    const spec = makeSpec({ operations: [makeOp()] })
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      credential: 'bearer',
+      authConfig: delegatedConfig,
+    })
+    const authFile = files['src/test-api-upstream-auth.ts']
+    assert.ok(authFile, 'upstream auth file should be generated')
+    assert.ok(authFile.includes('export const authenticateTestApiUpstream'))
+    assert.ok(
+      authFile.includes('/users/login-ai-plugin'),
+      'login path baked in'
+    )
+    assert.ok(authFile.includes('"user._id"'), 'externalId claim path baked in')
+    assert.ok(
+      authFile.includes("pick(claims, 'exp')"),
+      'jwt source defaults expiry to the exp claim'
+    )
+    assert.ok(
+      files['src/index.ts'].includes(
+        "export { authenticateTestApiUpstream } from './test-api-upstream-auth.js'"
+      ),
+      'index should export the authenticate function'
+    )
+  })
+
+  test('no delegated config → no upstream-auth file', () => {
+    const spec = makeSpec({ operations: [makeOp()] })
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      credential: 'bearer',
+    })
+    assert.equal(files['src/test-api-upstream-auth.ts'], undefined)
+  })
+})

package/src/codegen.ts

@@ -20,6 +20,7 @@ import {
   detectCommonPrefix,
   type NamedOperation,
 } from './naming.js'
+import { authHeaderValue, type AuthConfig } from './auth-config.js'
 
 interface AddonVars {
   name: string
@@ -36,6 +37,8 @@ interface CodegenFlags {
   credential?: 'apikey' | 'bearer' | 'oauth2'
   mcp?: boolean
   camelCase?: boolean
+  /** Operator-supplied auth overrides (custom header, delegated login). */
+  authConfig?: AuthConfig
 }
 
 function safeKey(key: string): string {
@@ -69,12 +72,40 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
-function humanDescription(parsed: ParsedOperation): string | undefined {
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId?: string): string | undefined {
+  if (!operationId) return undefined
+  const words = operationId
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .split(/\s+/)
+    .map((w) => w.trim())
+    .filter((w) => w && w.toLowerCase() !== 'controller')
+  if (words.length === 0) return undefined
+  return capitalize(words.join(' ').toLowerCase())
+}
+
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
+function humanDescription(parsed: ParsedOperation): string {
   const description = parsed.description?.trim()
   if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
     return capitalize(description)
   }
-  return undefined
+  const summary = parsed.summary?.trim()
+  if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+    return capitalize(summary)
+  }
+  return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`
 }
 
 function getErrorClassesForResponses(
@@ -389,8 +420,21 @@ export function generateAddonFromOpenAPI(
     functionExports.push(named.functionName)
   }
 
+  // Delegated login: emit the upstream authenticate() implementation
+  const upstreamAuthExport = flags.authConfig?.delegated
+    ? `authenticate${vars.pascalName}Upstream`
+    : undefined
+  if (flags.authConfig?.delegated) {
+    files[`src/${name}-upstream-auth.ts`] = generateUpstreamAuthFile(
+      vars,
+      flags.authConfig
+    )
+  }
+
   // Generate index.ts with all exports
-  files['src/index.ts'] = generateIndexFile(functionExports)
+  files['src/index.ts'] = generateIndexFile(functionExports, {
+    upstreamAuth: upstreamAuthExport ? { name, export: upstreamAuthExport } : undefined,
+  })
 
   // Generate typed API service class with route map
   files[`src/${name}-api.service.ts`] = generateServiceFile(
@@ -980,11 +1024,206 @@ function buildOutputSchema(schema: any, ctx: ZodCodegenContext): string {
   return schemaToZod(schema, ctx)
 }
 
-function generateIndexFile(functionExports: string[]): string {
+function generateIndexFile(
+  functionExports: string[],
+  extras?: { upstreamAuth?: { name: string; export: string } }
+): string {
   const lines: string[] = []
   for (const name of functionExports) {
     lines.push(`export { ${name} } from './functions/${name}.function.js'`)
   }
+  if (extras?.upstreamAuth) {
+    lines.push(
+      `export { ${extras.upstreamAuth.export} } from './${extras.upstreamAuth.name}-upstream-auth.js'`
+    )
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * Emit `src/<name>-upstream-auth.ts`: a self-contained authenticate() for
+ * delegated login. It performs the upstream login call described by the auth
+ * config, extracts the token, reads identity claims from the decoded JWT
+ * payload (base64url, NOT signature-verified — the token was just received
+ * over TLS from the login we ourselves performed) or the response body, and
+ * returns an identity object structurally compatible with
+ * `@pikku/better-auth`'s `UpstreamIdentity` — without depending on it.
+ */
+function generateUpstreamAuthFile(
+  vars: AddonVars,
+  authConfig: AuthConfig
+): string {
+  const { pascalName } = vars
+  const delegated = authConfig.delegated!
+  const claims = delegated.claims
+  const namePaths = claims.name
+    ? Array.isArray(claims.name)
+      ? claims.name
+      : [claims.name]
+    : []
+
+  const lines: string[] = []
+  lines.push(`export interface ${pascalName}UpstreamIdentity {`)
+  lines.push('  externalId: string')
+  lines.push('  email: string')
+  lines.push('  name?: string')
+  lines.push('  role?: string')
+  lines.push('  tenantId?: string')
+  lines.push(
+    '  credential: { token: string; expiresAt?: number; tenantId?: string }'
+  )
+  lines.push('}')
+  lines.push('')
+  lines.push(
+    `export interface ${pascalName}UpstreamCredentials {`
+  )
+  lines.push('  email?: string')
+  lines.push('  password?: string')
+  lines.push('  apiKey?: string')
+  lines.push('}')
+  lines.push('')
+  lines.push('const pick = (obj: unknown, path: string): unknown =>')
+  lines.push('  path')
+  lines.push("    .split('.')")
+  lines.push('    .reduce<any>(')
+  lines.push(
+    "      (o, key) => (o && typeof o === 'object' ? o[key] : undefined),"
+  )
+  lines.push('      obj')
+  lines.push('    )')
+  lines.push('')
+  lines.push('const str = (value: unknown): string | undefined =>')
+  lines.push(
+    "  typeof value === 'string' && value ? value : typeof value === 'number' ? String(value) : undefined"
+  )
+  lines.push('')
+  lines.push('/** Decode a JWT payload without verifying — see file docblock. */')
+  lines.push('const decodeJwtPayload = (token: string): unknown => {')
+  lines.push("  const part = token.split('.')[1]")
+  lines.push('  if (!part) return undefined')
+  lines.push('  try {')
+  lines.push("    const pad = part + '==='.slice((part.length + 3) % 4)")
+  lines.push(
+    "    const bin = atob(pad.replace(/-/g, '+').replace(/_/g, '/'))"
+  )
+  lines.push(
+    '    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))'
+  )
+  lines.push('    return JSON.parse(new TextDecoder().decode(bytes))')
+  lines.push('  } catch {')
+  lines.push('    // Not a decodable JWT — caller treats it as missing claims.')
+  lines.push('    return undefined')
+  lines.push('  }')
+  lines.push('}')
+  lines.push('')
+  lines.push('/**')
+  lines.push(
+    ` * Verify credentials against the upstream ${vars.displayName} login and map`
+  )
+  lines.push(
+    ' * its response onto an upstream identity. Returns null when the upstream'
+  )
+  lines.push(
+    ' * rejects the credentials; network errors propagate to the caller.'
+  )
+  lines.push(' */')
+  lines.push(`export const authenticate${pascalName}Upstream = async (`)
+  lines.push(`  credentials: ${pascalName}UpstreamCredentials,`)
+  lines.push('  baseUrl: string')
+  lines.push(`): Promise<${pascalName}UpstreamIdentity | null> => {`)
+  lines.push(
+    "  const headers: Record<string, string> = { 'Content-Type': 'application/json' }"
+  )
+  lines.push('  const body: Record<string, string> = {}')
+  if (delegated.credentials.includes('email')) {
+    lines.push('  if (credentials.email) body.email = credentials.email')
+  }
+  if (delegated.credentials.includes('password')) {
+    lines.push(
+      '  if (credentials.password) body.password = credentials.password'
+    )
+  }
+  if (delegated.credentials.includes('apiKey')) {
+    lines.push(
+      `  if (credentials.apiKey) headers[${JSON.stringify(delegated.apiKeyHeader)}] = credentials.apiKey`
+    )
+  }
+  lines.push('')
+  lines.push(
+    `  const response = await fetch(\`\${baseUrl.replace(/\\/+$/, '')}${delegated.loginPath}\`, {`
+  )
+  lines.push(`    method: ${JSON.stringify(delegated.loginMethod.toUpperCase())},`)
+  lines.push('    headers,')
+  lines.push(
+    '    body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,'
+  )
+  lines.push('  })')
+  lines.push('  if (!response.ok) return null')
+  lines.push('')
+  lines.push('  const data: unknown = await response.json()')
+  lines.push(`  const token = str(pick(data, ${JSON.stringify(delegated.tokenPath)}))`)
+  lines.push('  if (!token) return null')
+  lines.push('')
+  if (claims.source === 'jwt') {
+    lines.push('  const claims = decodeJwtPayload(token)')
+  } else {
+    lines.push('  const claims = data')
+  }
+  lines.push('  if (!claims) return null')
+  lines.push('')
+  lines.push(
+    `  const externalId = str(pick(claims, ${JSON.stringify(claims.externalId)}))`
+  )
+  lines.push(`  const email = str(pick(claims, ${JSON.stringify(claims.email)}))`)
+  lines.push('  if (!externalId || !email) return null')
+  lines.push('')
+  if (namePaths.length > 0) {
+    const parts = namePaths
+      .map((p) => `str(pick(claims, ${JSON.stringify(p)}))`)
+      .join(', ')
+    lines.push(`  const name = [${parts}]`)
+    lines.push('    .filter((part): part is string => Boolean(part))')
+    lines.push("    .join(' ') || undefined")
+  } else {
+    lines.push('  const name = undefined')
+  }
+  if (claims.role) {
+    lines.push(
+      `  const role = str(pick(claims, ${JSON.stringify(claims.role)}))`
+    )
+  } else {
+    lines.push('  const role = undefined')
+  }
+  if (claims.tenantId) {
+    lines.push(
+      `  const tenantId = str(pick(claims, ${JSON.stringify(claims.tenantId)}))`
+    )
+  } else {
+    lines.push('  const tenantId = undefined')
+  }
+  if (delegated.expiresAtPath) {
+    lines.push(
+      `  const expiresAtRaw = pick(data, ${JSON.stringify(delegated.expiresAtPath)})`
+    )
+  } else if (claims.source === 'jwt') {
+    lines.push("  const expiresAtRaw = pick(claims, 'exp')")
+  } else {
+    lines.push('  const expiresAtRaw = undefined')
+  }
+  lines.push(
+    "  const expiresAt = typeof expiresAtRaw === 'number' ? expiresAtRaw : undefined"
+  )
+  lines.push('')
+  lines.push('  return {')
+  lines.push('    externalId,')
+  lines.push('    email,')
+  lines.push('    name,')
+  lines.push('    role,')
+  lines.push('    tenantId,')
+  lines.push('    credential: { token, expiresAt, tenantId },')
+  lines.push('  }')
+  lines.push('}')
   lines.push('')
   return lines.join('\n')
 }
@@ -1214,13 +1453,28 @@ function generateServiceFile(
   if (flags.credential && flags.credential !== 'oauth2') {
     // Per-user credential: use creds from wire.getCredentials()
     if (flags.credential === 'bearer') {
-      lines.push('    headers.Authorization = `Bearer ${this.creds.token}`')
+      if (flags.authConfig?.headerName) {
+        // Custom auth header (e.g. `authentication: <raw jwt>`) from the auth config.
+        const { header, value } = authHeaderValue(
+          flags.authConfig,
+          'this.creds.token'
+        )
+        lines.push(`    headers[${JSON.stringify(header)}] = ${value}`)
+      } else {
+        lines.push('    headers.Authorization = `Bearer ${this.creds.token}`')
+      }
     } else {
-      // apikey: check spec for custom header name
+      // apikey: auth-config override wins, else check spec for custom header name
       const apiKeyScheme = Object.values(spec.securitySchemes).find(
         (s) => s.type === 'apiKey'
       )
-      if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
+      if (flags.authConfig?.headerName) {
+        const { header, value } = authHeaderValue(
+          flags.authConfig,
+          'this.creds.apiKey'
+        )
+        lines.push(`    headers[${JSON.stringify(header)}] = ${value}`)
+      } else if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
         lines.push(
           `    headers[${JSON.stringify(apiKeyScheme.name)}] = this.creds.apiKey`
         )
@@ -1243,11 +1497,17 @@ function generateServiceFile(
     lines.push('      body: body ? JSON.stringify(body) : undefined,')
     lines.push('    })')
   } else if (flags.secret) {
-    // Use apiKey details from spec if available
+    // Auth-config override wins, else use apiKey details from spec if available
     const apiKeyScheme = Object.values(spec.securitySchemes).find(
       (s) => s.type === 'apiKey'
     )
-    if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
+    if (flags.authConfig?.headerName) {
+      const { header, value } = authHeaderValue(
+        flags.authConfig,
+        'this.creds.apiKey'
+      )
+      lines.push(`    headers[${JSON.stringify(header)}] = ${value}`)
+    } else if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
       lines.push(
         `    headers[${JSON.stringify(apiKeyScheme.name)}] = this.creds.apiKey`
       )

package/src/index.ts

@@ -10,6 +10,15 @@ export {
 
 export { generateAddonFromOpenAPI } from './codegen.js'
 
+export {
+  AuthConfigSchema,
+  DelegatedLoginSchema,
+  loadAuthConfig,
+  authHeaderValue,
+  type AuthConfig,
+  type DelegatedLoginConfig,
+} from './auth-config.js'
+
 export {
   generateOperationNames,
   detectCommonPrefix,

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/codegen.ts","./src/index.ts","./src/naming.ts","./src/openapi-to-zod-schema.ts","./src/parse-openapi.ts","./src/zod-codegen.ts"],"version":"6.0.3"}
+{"root":["./src/auth-config.ts","./src/codegen.ts","./src/index.ts","./src/naming.ts","./src/openapi-to-zod-schema.ts","./src/parse-openapi.ts","./src/zod-codegen.ts"],"version":"6.0.3"}