@adobe/aio-commerce-lib-auth 0.6.2 → 0.8.0

package/dist/cjs/index.d.cts

@@ -1,33 +1,141 @@
-/**
- * @license
- * 
- * Copyright 2025 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
-import * as valibot21 from "valibot";
+import * as v from "valibot";
 import { InferOutput } from "valibot";
 
+//#region source/lib/ims-auth/types.d.ts
+/** Defines the headers required for IMS authentication. */
+type ImsAuthHeaders = {
+  Authorization: string;
+  "x-api-key"?: string;
+};
+/** Defines an authentication provider for Adobe IMS. */
+type ImsAuthProvider = {
+  getAccessToken: () => Promise<string> | string;
+  getHeaders: () => Promise<ImsAuthHeaders> | ImsAuthHeaders;
+};
+//#endregion
+//#region source/lib/ims-auth/forwarding.d.ts
+declare const ForwardedImsAuthSourceSchema: v.VariantSchema<"from", [v.ObjectSchema<{
+  readonly from: v.LiteralSchema<"headers", undefined>;
+  readonly headers: v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+  readonly from: v.LiteralSchema<"getter", undefined>;
+  readonly getHeaders: v.CustomSchema<() => ImsAuthHeaders | Promise<ImsAuthHeaders>, v.ErrorMessage<v.CustomIssue> | undefined>;
+}, undefined>, v.ObjectSchema<{
+  readonly from: v.LiteralSchema<"params", undefined>;
+  readonly params: v.LooseObjectSchema<{
+    readonly AIO_COMMERCE_AUTH_IMS_TOKEN: v.StringSchema<`Expected a string value for '${string}'`>;
+    readonly AIO_COMMERCE_AUTH_IMS_API_KEY: v.OptionalSchema<v.StringSchema<`Expected a string value for '${string}'`>, undefined>;
+  }, undefined>;
+}, undefined>], undefined>;
+/**
+ * Discriminated union for different sources of forwarded IMS auth credentials.
+ *
+ * - `headers`: Extract credentials from a raw headers object (e.g. an HTTP request).
+ * - `getter`: Use a function that returns IMS auth headers (sync or async).
+ * - `params`: Read credentials from a params object using `AIO_COMMERCE_AUTH_IMS_TOKEN` and `AIO_COMMERCE_AUTH_IMS_API_KEY` keys.
+ */
+type ForwardedImsAuthSource = v.InferOutput<typeof ForwardedImsAuthSourceSchema>;
+/**
+ * Creates an {@link ImsAuthProvider} by forwarding authentication credentials from various sources.
+ *
+ * @param source The source of the credentials to forward, as a {@link ForwardedImsAuthSource}.
+ * @returns An {@link ImsAuthProvider} instance that returns the forwarded access token and headers.
+ *
+ * @throws {CommerceSdkValidationError} If the source object is invalid.
+ * @throws {CommerceSdkValidationError} If `from: "headers"` is used and the `Authorization` header is missing.
+ * @throws {CommerceSdkValidationError} If `from: "headers"` is used and the `Authorization` header is not in Bearer token format.
+ * @throws {CommerceSdkValidationError} If `from: "params"` is used and `AIO_COMMERCE_AUTH_IMS_TOKEN` is missing or empty.
+ *
+ * @example
+ * ```typescript
+ * import { getForwardedImsAuthProvider } from "@adobe/aio-commerce-lib-auth";
+ *
+ * // From raw headers (e.g. from an HTTP request).
+ * const provider1 = getForwardedImsAuthProvider({
+ *   from: "headers",
+ *   headers: params.__ow_headers,
+ * });
+ *
+ * // From async getter (e.g. fetch from secret manager)
+ * const provider2 = getForwardedImsAuthProvider({
+ *   from: "getter",
+ *   getHeaders: async () => {
+ *     const token = await secretManager.getSecret("ims-token");
+ *     return { Authorization: `Bearer ${token}` };
+ *   },
+ * });
+ *
+ * // From a params object (using AIO_COMMERCE_AUTH_IMS_TOKEN and AIO_COMMERCE_AUTH_IMS_API_KEY keys)
+ * const provider3 = getForwardedImsAuthProvider({
+ *   from: "params",
+ *   params: actionParams,
+ * });
+ *
+ * // Use the provider
+ * const token = await provider1.getAccessToken();
+ * const headers = await provider1.getHeaders();
+ * ```
+ */
+declare function getForwardedImsAuthProvider(source: v.InferInput<typeof ForwardedImsAuthSourceSchema>): ImsAuthProvider;
+/**
+ * Creates an {@link ImsAuthProvider} by forwarding authentication credentials from runtime action parameters.
+ *
+ * This function automatically detects the source of credentials by trying multiple strategies in order:
+ * 1. **Params token** - Looks for `AIO_COMMERCE_AUTH_IMS_TOKEN` (and optionally `AIO_COMMERCE_AUTH_IMS_API_KEY`) in the params object
+ * 2. **HTTP headers** - Falls back to extracting the `Authorization` header from `__ow_headers`
+ *
+ * Use this function when building actions that receive authenticated requests and need to forward
+ * those credentials to downstream services (proxy pattern).
+ *
+ * @param params The runtime action parameters object. Can contain either:
+ *   - `AIO_COMMERCE_AUTH_IMS_TOKEN` and optionally `AIO_COMMERCE_AUTH_IMS_API_KEY` for direct token forwarding
+ *   - `__ow_headers` with an `Authorization` header for HTTP request forwarding
+ * @returns An {@link ImsAuthProvider} instance that returns the forwarded access token and headers.
+ *
+ * @throws {Error} If neither a valid token param nor Authorization header is found.
+ *
+ * @example
+ * ```typescript
+ * import { forwardImsAuthProvider } from "@adobe/aio-commerce-lib-auth";
+ *
+ * export async function main(params: Record<string, unknown>) {
+ *   // Automatically detects credentials from params or headers
+ *   const authProvider = forwardImsAuthProvider(params);
+ *
+ *   // Get the access token
+ *   const token = await authProvider.getAccessToken();
+ *
+ *   // Get headers for downstream API requests
+ *   const headers = await authProvider.getHeaders();
+ *   // {
+ *   //   Authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+ *   //   "x-api-key": "my-api-key" // Only if available
+ *   // }
+ *
+ *   // Use the forwarded credentials in downstream API calls
+ *   const response = await fetch("https://api.adobe.io/some-endpoint", {
+ *     headers,
+ *   });
+ *
+ *   return { statusCode: 200, body: await response.json() };
+ * }
+ * ```
+ */
+declare function forwardImsAuthProvider(params: Record<string, unknown>): ImsAuthProvider;
+//#endregion
 //#region source/lib/ims-auth/schema.d.ts
 /** Validation schema for IMS auth environment values. */
-declare const ImsAuthEnvSchema: valibot21.PicklistSchema<["prod", "stage"], undefined>;
+declare const ImsAuthEnvSchema: v.PicklistSchema<["prod", "stage"], undefined>;
 /** Defines the schema to validate the necessary parameters for the IMS auth service. */
-declare const ImsAuthParamsSchema: valibot21.ObjectSchema<{
-  readonly clientId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly clientSecrets: valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a string array value for the IMS auth parameter ${string}`>, valibot21.MinLengthAction<string[], number, `Expected at least ${number} items for the IMS auth parameter ${string}`>]>;
-  readonly technicalAccountId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly technicalAccountEmail: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<"Expected a string value for the IMS auth parameter technicalAccountEmail">, valibot21.EmailAction<string, "Expected a valid email format for technicalAccountEmail">]>;
-  readonly imsOrgId: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
-  readonly environment: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.PicklistSchema<["prod", "stage"], undefined>, undefined>]>;
-  readonly context: valibot21.SchemaWithPipe<readonly [valibot21.OptionalSchema<valibot21.StringSchema<undefined>, undefined>]>;
-  readonly scopes: valibot21.SchemaWithPipe<readonly [valibot21.ArraySchema<valibot21.StringSchema<undefined>, `Expected a string array value for the IMS auth parameter ${string}`>, valibot21.MinLengthAction<string[], number, `Expected at least ${number} items for the IMS auth parameter ${string}`>]>;
+declare const ImsAuthParamsSchema: v.ObjectSchema<{
+  readonly clientId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly clientSecrets: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, `Expected a string array value for the IMS auth parameter ${string}`>, v.MinLengthAction<string[], number, `Expected at least ${number} items for the IMS auth parameter ${string}`>]>;
+  readonly technicalAccountId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly technicalAccountEmail: v.SchemaWithPipe<readonly [v.StringSchema<"Expected a string value for the IMS auth parameter technicalAccountEmail">, v.EmailAction<string, "Expected a valid email format for technicalAccountEmail">]>;
+  readonly imsOrgId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the IMS auth parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the IMS auth parameter ${string}`>]>;
+  readonly environment: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<["prod", "stage"], undefined>, undefined>]>;
+  readonly context: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, undefined>]>;
+  readonly scopes: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, `Expected a string array value for the IMS auth parameter ${string}`>, v.MinLengthAction<string[], number, `Expected at least ${number} items for the IMS auth parameter ${string}`>]>;
 }, undefined>;
 /** Defines the parameters for the IMS auth service. */
 type ImsAuthParams = InferOutput<typeof ImsAuthParamsSchema>;
@@ -35,15 +143,6 @@ type ImsAuthParams = InferOutput<typeof ImsAuthParamsSchema>;
 type ImsAuthEnv = InferOutput<typeof ImsAuthEnvSchema>;
 //#endregion
 //#region source/lib/ims-auth/provider.d.ts
-/** Defines the header keys used for IMS authentication. */
-type ImsAuthHeader = "Authorization" | "x-api-key";
-/** Defines the headers required for IMS authentication. */
-type ImsAuthHeaders = Record<ImsAuthHeader, string>;
-/** Defines an authentication provider for Adobe IMS. */
-type ImsAuthProvider = {
-  getAccessToken: () => Promise<string>;
-  getHeaders: () => Promise<ImsAuthHeaders>;
-};
 /**
  * Type guard to check if a value is an ImsAuthProvider instance.
  *
@@ -103,10 +202,7 @@ declare function isImsAuthProvider(provider: unknown): provider is ImsAuthProvid
  */
 declare function getImsAuthProvider(authParams: ImsAuthParams): {
   getAccessToken: () => Promise<string>;
-  getHeaders: () => Promise<{
-    Authorization: string;
-    "x-api-key": string;
-  }>;
+  getHeaders: () => Promise<ImsAuthHeaders>;
 };
 //#endregion
 //#region source/lib/ims-auth/utils.d.ts
@@ -156,11 +252,11 @@ type HttpMethodInput = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  * The schema for the Commerce Integration parameters.
  * This is used to validate the parameters passed to the Commerce Integration provider.
  */
-declare const IntegrationAuthParamsSchema: valibot21.NonOptionalSchema<valibot21.ObjectSchema<{
-  readonly consumerKey: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly consumerSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly accessToken: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
-  readonly accessTokenSecret: valibot21.SchemaWithPipe<readonly [valibot21.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, valibot21.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+declare const IntegrationAuthParamsSchema: v.NonOptionalSchema<v.ObjectSchema<{
+  readonly consumerKey: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly consumerSecret: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessToken: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
+  readonly accessTokenSecret: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for the Commerce Integration parameter ${string}`>, v.NonEmptyAction<string, `Expected a non-empty string value for the Commerce Integration parameter ${string}`>]>;
 }, undefined>, undefined>;
 /** Defines the parameters required for Commerce Integration authentication. */
 type IntegrationAuthParams = InferOutput<typeof IntegrationAuthParamsSchema>;
@@ -272,7 +368,8 @@ declare function assertIntegrationAuthParams(config: Record<PropertyKey, unknown
  * }
  * ```
  */
-declare function resolveAuthParams(params: Record<string, unknown>): ({
+declare function resolveAuthParams(params: Record<string, unknown>): {
+  strategy: "ims";
   clientId: string;
   clientSecrets: string[];
   technicalAccountId: string;
@@ -281,15 +378,12 @@ declare function resolveAuthParams(params: Record<string, unknown>): ({
   environment?: "prod" | "stage" | undefined;
   context?: string | undefined;
   scopes: string[];
-} & {
-  readonly strategy: "ims";
-}) | ({
+} | {
+  strategy: "integration";
   consumerKey: string;
   consumerSecret: string;
   accessToken: string;
   accessTokenSecret: string;
-} & {
-  readonly strategy: "integration";
-});
+};
 //#endregion
-export { type ImsAuthEnv, type ImsAuthParams, type ImsAuthProvider, type IntegrationAuthParams, type IntegrationAuthProvider, assertImsAuthParams, assertIntegrationAuthParams, getImsAuthProvider, getIntegrationAuthProvider, isImsAuthProvider, isIntegrationAuthProvider, resolveAuthParams };
+export { type ForwardedImsAuthSource, type ImsAuthEnv, type ImsAuthHeaders, type ImsAuthParams, type ImsAuthProvider, type IntegrationAuthParams, type IntegrationAuthProvider, assertImsAuthParams, assertIntegrationAuthParams, forwardImsAuthProvider, getForwardedImsAuthProvider, getImsAuthProvider, getIntegrationAuthProvider, isImsAuthProvider, isIntegrationAuthProvider, resolveAuthParams };

package/dist/es/commands/index.d.mts

@@ -0,0 +1 @@
+export { };