@apiquest/plugin-auth 1.0.1

package/dist/oauth2-auth.d.ts

@@ -0,0 +1,35 @@
+import type { IAuthPlugin } from '@apiquest/types';
+/**
+ * OAuth2 configuration interface
+ *
+ * Client credential placement:
+ * - clientId/clientSecret: Always required, contain the actual credential values
+ * - clientAuthentication: Where/how to send credentials to token endpoint
+ *   - 'body': Send as client_id/client_secret in form body (default, standard OAuth2)
+ *   - 'basic': Send as HTTP Basic Auth header (Base64 encoded clientId:clientSecret)
+ *   - 'header': Send as custom headers (names specified by clientIdField/clientSecretField)
+ *   - 'query': Send as query parameters (names specified by clientIdField/clientSecretField)
+ * - clientIdField/clientSecretField: Custom field names for 'header' or 'query' placement
+ * - extraHeaders/extraBody/extraQuery: Additional parameters for token request
+ * - cacheToken: Whether to cache token across requests (default: true)
+ */
+export interface OAuth2Config {
+    grantType: 'client_credentials' | 'password' | 'authorization_code';
+    accessTokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    username?: string;
+    password?: string;
+    scope?: string;
+    authorizationCode?: string;
+    redirectUri?: string;
+    clientAuthentication?: 'body' | 'basic' | 'header' | 'query';
+    clientIdField?: string;
+    clientSecretField?: string;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, unknown>;
+    extraQuery?: Record<string, string>;
+    cacheToken?: boolean;
+}
+export declare const oauth2Auth: IAuthPlugin;
+//# sourceMappingURL=oauth2-auth.d.ts.map

package/dist/oauth2-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-auth.d.ts","sourceRoot":"","sources":["../src/oauth2-auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAG7G;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,oBAAoB,GAAG,UAAU,GAAG,oBAAoB,CAAC;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAkKD,eAAO,MAAM,UAAU,EAAE,WAyIxB,CAAC"}

package/dist/src/apikey-auth.d.ts

@@ -0,0 +1,3 @@
+import type { IAuthPlugin } from '@apiquest/types';
+export declare const apiKeyAuth: IAuthPlugin;
+//# sourceMappingURL=apikey-auth.d.ts.map

package/dist/src/apikey-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apikey-auth.d.ts","sourceRoot":"","sources":["../../src/apikey-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAE7G,eAAO,MAAM,UAAU,EAAE,WA6ExB,CAAC"}

package/dist/src/basic-auth.d.ts

@@ -0,0 +1,3 @@
+import type { IAuthPlugin } from '@apiquest/types';
+export declare const basicAuth: IAuthPlugin;
+//# sourceMappingURL=basic-auth.d.ts.map

package/dist/src/basic-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-auth.d.ts","sourceRoot":"","sources":["../../src/basic-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAE7G,eAAO,MAAM,SAAS,EAAE,WAsEvB,CAAC"}

package/dist/src/bearer-auth.d.ts

@@ -0,0 +1,3 @@
+import type { IAuthPlugin } from '@apiquest/types';
+export declare const bearerAuth: IAuthPlugin;
+//# sourceMappingURL=bearer-auth.d.ts.map

package/dist/src/bearer-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-auth.d.ts","sourceRoot":"","sources":["../../src/bearer-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAE7G,eAAO,MAAM,UAAU,EAAE,WAyDxB,CAAC"}

package/dist/src/helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function isNullOrEmpty(value: string | null | undefined): boolean;
+export declare function isNullOrWhitespace(value: string | null | undefined): boolean;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AACA,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEvE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E"}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthPlugin } from '@apiquest/types';
+export { bearerAuth } from './bearer-auth.js';
+export { basicAuth } from './basic-auth.js';
+export { apiKeyAuth } from './apikey-auth.js';
+export { oauth2Auth, type OAuth2Config } from './oauth2-auth.js';
+export { isNullOrEmpty, isNullOrWhitespace } from './helpers.js';
+export declare const authPlugins: IAuthPlugin[];
+export declare function getAuthPlugin(type: string): IAuthPlugin | undefined;
+export default authPlugins;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGjE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AASjE,eAAO,MAAM,WAAW,EAAE,WAAW,EAKpC,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEnE;AAGD,eAAe,WAAW,CAAC"}

package/dist/src/oauth2-auth.d.ts

@@ -0,0 +1,35 @@
+import type { IAuthPlugin } from '@apiquest/types';
+/**
+ * OAuth2 configuration interface
+ *
+ * Client credential placement:
+ * - clientId/clientSecret: Always required, contain the actual credential values
+ * - clientAuthentication: Where/how to send credentials to token endpoint
+ *   - 'body': Send as client_id/client_secret in form body (default, standard OAuth2)
+ *   - 'basic': Send as HTTP Basic Auth header (Base64 encoded clientId:clientSecret)
+ *   - 'header': Send as custom headers (names specified by clientIdField/clientSecretField)
+ *   - 'query': Send as query parameters (names specified by clientIdField/clientSecretField)
+ * - clientIdField/clientSecretField: Custom field names for 'header' or 'query' placement
+ * - extraHeaders/extraBody/extraQuery: Additional parameters for token request
+ * - cacheToken: Whether to cache token across requests (default: true)
+ */
+export interface OAuth2Config {
+    grantType: 'client_credentials' | 'password' | 'authorization_code';
+    accessTokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    username?: string;
+    password?: string;
+    scope?: string;
+    authorizationCode?: string;
+    redirectUri?: string;
+    clientAuthentication?: 'body' | 'basic' | 'header' | 'query';
+    clientIdField?: string;
+    clientSecretField?: string;
+    extraHeaders?: Record<string, string>;
+    extraBody?: Record<string, unknown>;
+    extraQuery?: Record<string, string>;
+    cacheToken?: boolean;
+}
+export declare const oauth2Auth: IAuthPlugin;
+//# sourceMappingURL=oauth2-auth.d.ts.map

package/dist/src/oauth2-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-auth.d.ts","sourceRoot":"","sources":["../../src/oauth2-auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAA4D,MAAM,iBAAiB,CAAC;AAG7G;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,oBAAoB,GAAG,UAAU,GAAG,oBAAoB,CAAC;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oBAAoB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA0KD,eAAO,MAAM,UAAU,EAAE,WA2IxB,CAAC"}

package/esbuild.config.js

@@ -0,0 +1,16 @@
+import esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  outfile: 'dist/index.js',
+  format: 'esm',
+  platform: 'node',
+  target: 'node18',
+  // Externalize peerDependencies - runner will provide these
+  external: ['@apiquest/fracture'],
+  minify: false,
+  sourcemap: true,
+});
+
+console.log('✓ Built plugin-auth');

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@apiquest/plugin-auth",
+  "version": "1.0.1",
+  "description": "Authentication plugins for ApiQuest (Bearer, Basic, OAuth2, API Key)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly",
+    "dev": "rollup -c --watch",
+    "test": "vitest"
+  },
+  "keywords": [
+    "apiquest",
+    "auth",
+    "authentication",
+    "bearer",
+    "oauth2"
+  ],
+  "author": "ApiQuest Contributors",
+  "license": "AGPL-3.0-or-later",
+  "peerDependencies": {
+    "@apiquest/types": "^1.0.0"
+  },
+  "dependencies": {
+    "got": "^14.6.6"
+  },
+  "devDependencies": {
+    "@apiquest/types": "workspace:*",
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "rollup": "^4.0.0",
+    "tslib": "^2.7.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "apiquest": {
+    "type": "auth",
+    "runtime": [
+      "fracture"
+    ],
+    "capabilities": {
+      "provides": {
+        "authTypes": [
+          "bearer",
+          "basic",
+          "apikey",
+          "oauth2"
+        ]
+      },
+      "supports": {
+        "protocols": [
+          "http",
+          "graphql",
+          "grpc"
+        ]
+      }
+    }
+  }
+}

package/rollup.config.js

@@ -0,0 +1,31 @@
+import typescript from '@rollup/plugin-typescript';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+
+export default {
+  input: 'src/index.ts',
+  output: {
+    file: 'dist/index.js',
+    format: 'esm',
+    sourcemap: true,
+  },
+  external: [
+    // Externalize peer dependencies
+    '@apiquest/fracture',
+  ],
+  plugins: [
+    // Resolve node modules
+    resolve({
+      preferBuiltins: true,  // Prefer Node.js built-in modules
+      exportConditions: ['node', 'import', 'default'],
+    }),
+    // Convert CommonJS to ESM (for axios and other CJS dependencies)
+    commonjs(),
+    // Compile TypeScript
+    typescript({
+      tsconfig: './tsconfig.json',
+      sourceMap: true,
+      declaration: false, // We'll use tsc for declarations
+    }),
+  ],
+};

package/src/apikey-auth.ts

@@ -0,0 +1,79 @@
+// API Key Authentication
+import type { IAuthPlugin, Request, Auth, RuntimeOptions, ValidationResult, ILogger } from '@apiquest/types';
+
+export const apiKeyAuth: IAuthPlugin = {
+  name: 'API Key',
+  version: '1.0.0',
+  description: 'API Key authentication (via header or query parameter)',
+  authTypes: ['apikey'],
+  protocols: ['http', 'graphql', 'grpc'],
+  dataSchema: {
+    type: 'object',
+    required: ['key', 'value'],
+    properties: {
+      key: {
+        type: 'string',
+        description: 'API key name'
+      },
+      value: {
+        type: 'string',
+        description: 'API key value'
+      },
+      in: {
+        type: 'string',
+        enum: ['header', 'query'],
+        default: 'header',
+        description: 'Where to add the API key'
+      }
+    }
+  },
+  
+  validate(auth: Auth, options: RuntimeOptions): ValidationResult {
+    const errors = [];
+    if ((auth.data?.key ?? null) === null) {
+      errors.push({
+        message: 'API key name is required',
+        location: '',
+        source: 'auth' as const
+      });
+    }
+    if ((auth.data?.value ?? null) === null) {
+      errors.push({
+        message: 'API key value is required',
+        location: '',
+        source: 'auth' as const
+      });
+    }
+    return errors.length > 0 ? { valid: false, errors } : { valid: true };
+  },
+  
+  async apply(request: Request, auth: Auth, options: RuntimeOptions, logger?: ILogger): Promise<Request> {
+    const key = auth.data?.key as string | undefined;
+    const value = auth.data?.value as string | undefined;
+    const rawLocation = auth.data?.in as string | undefined;
+    const location = rawLocation ?? 'header';
+
+    logger?.debug('API key auth apply started', { location });
+
+    if (key === undefined || value === undefined) {
+      logger?.error('API key auth missing key or value');
+      throw new Error('API key and value are required');
+    }
+
+    if (location === 'header') {
+      request.data.headers ??= {};
+      (request.data.headers as Record<string, string>)[key] = value;
+      logger?.trace('API key applied to headers', { header: key });
+    } else if (location === 'query') {
+      const url = new URL(request.data.url as string);
+      url.searchParams.set(key, value);
+      request.data.url = url.toString();
+      logger?.trace('API key applied to query string', { key });
+    } else {
+      logger?.error('Invalid API key location', { location });
+      throw new Error(`Invalid API key location: ${location}. Must be 'header' or 'query'`);
+    }
+
+    return request;
+  }
+};

package/src/basic-auth.ts

@@ -0,0 +1,65 @@
+// Basic Authentication
+import type { IAuthPlugin, Request, Auth, RuntimeOptions, ValidationResult, ILogger } from '@apiquest/types';
+
+export const basicAuth: IAuthPlugin = {
+  name: 'Basic Authentication',
+  version: '1.0.0',
+  description: 'HTTP Basic authentication (Authorization: Basic base64(username:password))',
+  authTypes: ['basic'],
+  protocols: ['http', 'graphql', 'grpc'],
+  dataSchema: {
+    type: 'object',
+    required: ['username', 'password'],
+    properties: {
+      username: {
+        type: 'string',
+        description: 'Username'
+      },
+      password: {
+        type: 'string',
+        description: 'Password'
+      }
+    }
+  },
+  
+  validate(auth: Auth, options: RuntimeOptions): ValidationResult {
+    const errors = [];
+    if ((auth.data?.username ?? null) === null) {
+      errors.push({
+        message: 'Username is required for basic auth',
+        location: '',
+        source: 'auth' as const
+      });
+    }
+    if ((auth.data?.password ?? null) === null) {
+      errors.push({
+        message: 'Password is required for basic auth',
+        location: '',
+        source: 'auth' as const
+      });
+    }
+    return errors.length > 0 ? { valid: false, errors } : { valid: true };
+  },
+  
+  async apply(request: Request, auth: Auth, options: RuntimeOptions, logger?: ILogger): Promise<Request> {
+    if ((request.data.headers as Record<string, unknown> | null | undefined)?.['Authorization'] !== undefined) {
+      logger?.trace('Authorization header already present, skipping basic auth apply');
+      return request;
+    }
+
+    const username = auth.data?.username as string | undefined;
+    const password = auth.data?.password as string | undefined;
+
+    if (username === undefined || password === undefined) {
+      logger?.error('Basic auth missing username or password');
+      throw new Error('Username and password are required for basic auth');
+    }
+
+    const credentials = Buffer.from(`${username}:${password}`).toString('base64');
+    request.data.headers ??= {};
+    (request.data.headers as Record<string, string>)['Authorization'] = `Basic ${credentials}`;
+    logger?.debug('Basic auth header applied');
+
+    return request;
+  }
+};

package/src/bearer-auth.ts

@@ -0,0 +1,54 @@
+// Bearer Token Authentication
+import type { IAuthPlugin, Request, Auth, RuntimeOptions, ValidationResult, ILogger } from '@apiquest/types';
+
+export const bearerAuth: IAuthPlugin = {
+  name: 'Bearer Token',
+  version: '1.0.0',
+  description: 'Bearer token authentication (Authorization: Bearer <token>)',
+  authTypes: ['bearer'],
+  protocols: ['http', 'graphql', 'grpc'],
+  dataSchema: {
+    type: 'object',
+    required: ['token'],
+    properties: {
+      token: {
+        type: 'string',
+        description: 'Bearer token value'
+      }
+    }
+  },
+  
+  validate(auth: Auth, options: RuntimeOptions): ValidationResult {
+    if ((auth.data?.token ?? null) === null) {
+      return {
+        valid: false,
+        errors: [{
+          message: 'Bearer token is required',
+          location: '',
+          source: 'auth'
+        }]
+      };
+    }
+    return { valid: true };
+  },
+  
+  async apply(request: Request, auth: Auth, options: RuntimeOptions, logger?: ILogger): Promise<Request> {
+    if ((request.data.headers as Record<string, unknown> | null | undefined)?.['Authorization'] !== undefined) {
+      logger?.trace('Authorization header already present, skipping bearer auth apply');
+      return request;
+    }
+
+    const token = auth.data?.token as string | undefined;
+
+    if (token === undefined) {
+      logger?.error('Bearer auth missing token');
+      throw new Error('Bearer token is required');
+    }
+
+    request.data.headers ??= {};
+    (request.data.headers as Record<string, string>)['Authorization'] = `Bearer ${token}`;
+    logger?.debug('Bearer auth header applied');
+
+    return request;
+  }
+};

package/src/helpers.ts

@@ -0,0 +1,8 @@
+// Helper functions for string validation
+export function isNullOrEmpty(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value === '';
+}
+
+export function isNullOrWhitespace(value: string | null | undefined): boolean {
+  return value === null || value === undefined || value.trim() === '';
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Authentication Plugins for ApiQuest
+import type { IAuthPlugin } from '@apiquest/types';
+
+// Export individual auth plugins
+export { bearerAuth } from './bearer-auth.js';
+export { basicAuth } from './basic-auth.js';
+export { apiKeyAuth } from './apikey-auth.js';
+export { oauth2Auth, type OAuth2Config } from './oauth2-auth.js';
+
+// Export helpers
+export { isNullOrEmpty, isNullOrWhitespace } from './helpers.js';
+
+// Import all plugins for registry
+import { bearerAuth } from './bearer-auth.js';
+import { basicAuth } from './basic-auth.js';
+import { apiKeyAuth } from './apikey-auth.js';
+import { oauth2Auth } from './oauth2-auth.js';
+
+// Auth Plugin Registry
+export const authPlugins: IAuthPlugin[] = [
+  bearerAuth,
+  basicAuth,
+  apiKeyAuth,
+  oauth2Auth
+];
+
+export function getAuthPlugin(type: string): IAuthPlugin | undefined {
+  return authPlugins.find(p => p.authTypes.includes(type));
+}
+
+// Export individual plugins and registry
+export default authPlugins;