@kidd-cli/core 0.2.0 → 0.4.0

package/dist/middleware/auth.d.ts

@@ -1,6 +1,27 @@
-import { s as Middleware } from "../types-BaZ5WqVM.js";
+import { p as Context, u as Middleware } from "../types-U73X_oQ_.js";
 import { AsyncResult } from "@kidd-cli/utils/fp";
 
+//#region src/middleware/auth/require.d.ts
+/**
+* Options for {@link createAuthRequire}.
+*/
+interface AuthRequireOptions {
+  readonly message?: string;
+}
+/**
+* Create an enforcement middleware that gates on authentication.
+*
+* When `ctx.auth.authenticated()` returns true, the middleware calls
+* `next()`. When not authenticated, it calls `ctx.fail()` with the
+* provided (or default) message. When `ctx.auth` is absent (auth
+* middleware not configured), it calls `ctx.fail()` with an
+* `AUTH_MIDDLEWARE_MISSING` code.
+*
+* @param options - Optional configuration for the require gate.
+* @returns A Middleware that enforces authentication.
+*/
+declare function createAuthRequire(options?: AuthRequireOptions): Middleware;
+//#endregion
 //#region src/middleware/auth/types.d.ts
 /**
 * Bearer token credential — sends `Authorization: Bearer <token>`.
@@ -112,23 +133,40 @@ interface CustomSourceConfig {
 * Discriminated union of all supported credential source configurations.
 * The `source` field acts as the discriminator.
 */
-type ResolverConfig = EnvSourceConfig | DotenvSourceConfig | FileSourceConfig | OAuthSourceConfig | DeviceCodeSourceConfig | TokenSourceConfig | CustomSourceConfig;
+type StrategyConfig = EnvSourceConfig | DotenvSourceConfig | FileSourceConfig | OAuthSourceConfig | DeviceCodeSourceConfig | TokenSourceConfig | CustomSourceConfig;
+/**
+* Callback that validates a resolved credential before it is persisted.
+*
+* Returning a successful Result allows the credential to be saved (the
+* returned credential is what gets persisted, so the callback may also
+* enrich or transform it). Returning a failure Result prevents persistence
+* and surfaces the error to the caller.
+*/
+type ValidateCredential = (credential: AuthCredential) => AsyncResult<AuthCredential, AuthError>;
 /**
 * Error returned by {@link AuthContext.login} or {@link AuthContext.logout}
 * when the operation fails.
 */
 interface AuthError {
-  readonly type: "no_credential" | "save_failed" | "remove_failed";
+  readonly type: "no_credential" | "save_failed" | "remove_failed" | "validation_failed";
   readonly message: string;
 }
 /**
+* Options accepted by {@link AuthContext.login} to override the default
+* strategy list for a single login attempt.
+*/
+interface LoginOptions {
+  readonly strategies?: readonly StrategyConfig[];
+  readonly validate?: ValidateCredential;
+}
+/**
 * Auth context decorated onto `ctx.auth` by the auth middleware.
 *
 * No credential data is stored directly on the context. Instead, callers
 * use `credential()` to read saved credentials on demand and
 * `authenticated()` to check whether a credential exists without exposing it.
 *
-* `login()` runs the configured interactive resolvers (OAuth, prompt,
+* `login()` runs the configured interactive strategies (OAuth, prompt,
 * etc.), persists the resulting credential to disk, and returns a
 * {@link AsyncResult}.
 *
@@ -137,58 +175,46 @@ interface AuthError {
 interface AuthContext {
   readonly credential: () => AuthCredential | null;
   readonly authenticated: () => boolean;
-  readonly login: () => AsyncResult<AuthCredential, AuthError>;
+  readonly login: (options?: LoginOptions) => AsyncResult<AuthCredential, AuthError>;
   readonly logout: () => AsyncResult<string, AuthError>;
 }
 /**
 * Options for the `auth.env()` builder. Omits the `source` discriminator.
 */
-type EnvResolverOptions = Omit<EnvSourceConfig, "source">;
+type EnvStrategyOptions = Omit<EnvSourceConfig, "source">;
 /**
 * Options for the `auth.dotenv()` builder. Omits the `source` discriminator.
 */
-type DotenvResolverOptions = Omit<DotenvSourceConfig, "source">;
+type DotenvStrategyOptions = Omit<DotenvSourceConfig, "source">;
 /**
 * Options for the `auth.file()` builder. Omits the `source` discriminator.
 */
-type FileResolverOptions = Omit<FileSourceConfig, "source">;
+type FileStrategyOptions = Omit<FileSourceConfig, "source">;
 /**
 * Options for the `auth.oauth()` builder. Omits the `source` discriminator.
 */
-type OAuthResolverOptions = Omit<OAuthSourceConfig, "source">;
+type OAuthStrategyOptions = Omit<OAuthSourceConfig, "source">;
 /**
 * Options for the `auth.deviceCode()` builder. Omits the `source` discriminator.
 */
-type DeviceCodeResolverOptions = Omit<DeviceCodeSourceConfig, "source">;
+type DeviceCodeStrategyOptions = Omit<DeviceCodeSourceConfig, "source">;
 /**
 * Options for the `auth.token()` builder. Omits the `source` discriminator.
 */
-type TokenResolverOptions = Omit<TokenSourceConfig, "source">;
+type TokenStrategyOptions = Omit<TokenSourceConfig, "source">;
 /**
 * Function signature accepted by `auth.custom()`.
 */
-type CustomResolverFn = () => Promise<AuthCredential | null> | AuthCredential | null;
-/**
-* Configuration for an HTTP client created by the auth middleware.
-*
-* When provided on {@link AuthOptions}, the auth middleware creates an HTTP
-* client with automatic credential header injection and decorates it onto
-* `ctx[namespace]`.
-*/
-interface AuthHttpOptions {
-  readonly baseUrl: string;
-  readonly namespace: string;
-  readonly headers?: Readonly<Record<string, string>>;
-}
+type CustomStrategyFn = () => Promise<AuthCredential | null> | AuthCredential | null;
 /**
 * Options accepted by the `auth()` middleware factory.
 *
-* @property resolvers - Ordered list of credential sources to try via `login()`.
-* @property http - Optional HTTP client(s) with automatic credential injection.
+* @property strategies - Ordered list of credential sources to try via `login()`.
+* @property validate - Optional callback to validate a credential before persisting.
 */
 interface AuthOptions {
-  readonly resolvers: readonly ResolverConfig[];
-  readonly http?: AuthHttpOptions | readonly AuthHttpOptions[];
+  readonly strategies: readonly StrategyConfig[];
+  readonly validate?: ValidateCredential;
 }
 /**
 * Augments the base {@link Context} with an optional `auth` property.
@@ -205,27 +231,41 @@ declare module "@kidd-cli/core" {
 //#region src/middleware/auth/auth.d.ts
 /**
 * Auth factory interface — callable as a middleware factory and as a
-* namespace for resolver builder functions.
+* namespace for strategy builder functions.
 */
 interface AuthFactory {
   (options: AuthOptions): Middleware;
-  readonly env: (options?: EnvResolverOptions) => EnvSourceConfig;
-  readonly dotenv: (options?: DotenvResolverOptions) => DotenvSourceConfig;
-  readonly file: (options?: FileResolverOptions) => FileSourceConfig;
-  readonly oauth: (options: OAuthResolverOptions) => OAuthSourceConfig;
-  readonly deviceCode: (options: DeviceCodeResolverOptions) => DeviceCodeSourceConfig;
-  readonly token: (options?: TokenResolverOptions) => TokenSourceConfig;
-  readonly apiKey: (options?: TokenResolverOptions) => TokenSourceConfig;
-  readonly custom: (resolver: CustomResolverFn) => CustomSourceConfig;
+  readonly env: (options?: EnvStrategyOptions) => EnvSourceConfig;
+  readonly dotenv: (options?: DotenvStrategyOptions) => DotenvSourceConfig;
+  readonly file: (options?: FileStrategyOptions) => FileSourceConfig;
+  readonly oauth: (options: OAuthStrategyOptions) => OAuthSourceConfig;
+  readonly deviceCode: (options: DeviceCodeStrategyOptions) => DeviceCodeSourceConfig;
+  readonly token: (options?: TokenStrategyOptions) => TokenSourceConfig;
+  readonly apiKey: (options?: TokenStrategyOptions) => TokenSourceConfig;
+  readonly custom: (fn: CustomStrategyFn) => CustomSourceConfig;
+  readonly headers: () => (ctx: Context) => Readonly<Record<string, string>>;
+  readonly require: (options?: AuthRequireOptions) => Middleware;
 }
 /**
-* Auth middleware factory with resolver builder methods.
+* Auth middleware factory with strategy builder methods.
 *
-* Use as `auth({ resolvers: [...] })` to create middleware, or use
+* Use as `auth({ strategies: [...] })` to create middleware, or use
 * the builder methods (`auth.env()`, `auth.oauth()`, etc.) to construct
-* resolver configs with a cleaner API.
+* strategy configs with a cleaner API.
 */
 declare const auth: AuthFactory;
 //#endregion
-export { type AuthContext, type AuthCredential, type AuthError, type AuthFactory, type AuthHttpOptions, type AuthOptions, type CustomResolverFn, type CustomSourceConfig, type DeviceCodeResolverOptions, type DeviceCodeSourceConfig, type DotenvResolverOptions, type DotenvSourceConfig, type EnvResolverOptions, type EnvSourceConfig, type FileResolverOptions, type FileSourceConfig, type OAuthResolverOptions, type OAuthSourceConfig, type ResolverConfig, type TokenResolverOptions, type TokenSourceConfig, auth };
+//#region src/middleware/auth/headers.d.ts
+/**
+* Create a function that resolves auth credentials from `ctx.auth` into HTTP headers.
+*
+* The returned function reads `ctx.auth.credential()` and converts the credential
+* into the appropriate header format using `buildAuthHeaders()`. Returns an empty
+* record when no auth middleware is present or no credential exists.
+*
+* @returns A function that takes a Context and returns auth headers.
+*/
+declare function createAuthHeaders(): (ctx: Context) => Readonly<Record<string, string>>;
+//#endregion
+export { type AuthContext, type AuthCredential, type AuthError, type AuthFactory, type AuthOptions, type AuthRequireOptions, type CustomSourceConfig, type CustomStrategyFn, type DeviceCodeSourceConfig, type DeviceCodeStrategyOptions, type DotenvSourceConfig, type DotenvStrategyOptions, type EnvSourceConfig, type EnvStrategyOptions, type FileSourceConfig, type FileStrategyOptions, type LoginOptions, type OAuthSourceConfig, type OAuthStrategyOptions, type StrategyConfig, type TokenSourceConfig, type TokenStrategyOptions, type ValidateCredential, auth, createAuthHeaders, createAuthRequire };
 //# sourceMappingURL=auth.d.ts.map

package/dist/middleware/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","names":[],"sources":["../../src/middleware/auth/types.ts","../../src/middleware/auth/auth.ts"],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../src/middleware/auth/require.ts","../../src/middleware/auth/types.ts","../../src/middleware/auth/auth.ts","../../src/middleware/auth/headers.ts"],"mappings":"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"}