feat: support include ims credentials annotation (#5)

* feat: support ims compatible api params

* fix: cache key, imsEnv input and validation as first step

* fix: scopes must be an array

* chore: tests

* feat: read from include-ims-credentials

* detect stage namespace and default to stage ims env

* fix: stage ims (+ chore: test re-org)

* fixes and cleanups

* readme update

* fix AI generated garbage test file

* another round of fixing AI generated tests

* readme precisions

Author: moritzraho

README.md

@@ -36,21 +36,25 @@ const { generateAccessToken } = require('@adobe/aio-lib-core-auth')
 
 async function main(params) {
   try {
-    // Note: Will cache for 5 min
+    // if the include-ims-credentials annotation is set, the library infers credentials from the Runtime params
+    const token = await generateAccessToken(params)
+
+    // otherwise credentials can be passed manually
     const token = await generateAccessToken({
-      clientId: params.IMS_CLIENT_ID,
-      clientSecret: params.IMS_CLIENT_SECRET,
-      orgId: params.IMS_ORG_ID,
-      scopes: params.IMS_SCOPES,
+      clientId: '<clientId>',
+      clientSecret: '<clientSecret>',
+      orgId: '<orgId>@AdobeOrg',
+      scopes: ['<scope1>', '<scope2>', '..']
     })
+
     console.log('Authentication successful:', token.access_token)
   } catch (error) {
     console.error('Authentication failed:', error)
   }
 }
 ```
 
-Note: The token is cached in the Runtime's container memory, a single Runtime action can run in multiple containers.
+Note: The token is cached for 5 minutes in the Runtime's container memory. A single Runtime action can run in multiple containers, meaning the cache is not shared across actions.
 
 ### Invalidating the Token Cache in a Runtime action
 

src/constants.js

@@ -0,0 +1,14 @@
+/*
+Copyright 2026 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.
+*/
+
+// support parameters set in the include-ims-credentials annotation
+export const IMS_OAUTH_S2S_INPUT = '__ims_oauth_s2s'
+export const IMS_ENV_INPUT = '__ims_env'

src/errors.js

@@ -39,7 +39,7 @@ const E = ErrorWrapper(
 
 // Error codes
 E('IMS_TOKEN_ERROR', 'Error calling IMS to get access token: %s')
-E('MISSING_PARAMETERS', 'Missing required parameters: %s')
+E('MISSING_PARAMETERS', 'Missing required parameters: %s. You may want to set the include-ims-credentials annotation.')
 E('BAD_CREDENTIALS_FORMAT', 'Credentials must be either an object or a stringified object')
 E('BAD_SCOPES_FORMAT', 'Scopes must be an array')
 E('GENERIC_ERROR', 'An unexpected error occurred: %s')

src/ims.js

@@ -33,20 +33,23 @@ function getImsUrl (env) {
  *
  * @private
  * @param {object} params - Parameters to validate
- * @returns {object} Validated credentials object
- * @throws {Error} If any required parameters are missing
+ * @returns {{ error, credentials }} Object with error (if any) and validated credentials object
  */
 function getAndValidateCredentials (params) {
   if (!(typeof params === 'object' && params !== null && !Array.isArray(params))) {
-    throw new codes.BAD_CREDENTIALS_FORMAT({
-      sdkDetails: { paramsType: typeof params }
-    })
+    return {
+      error: new codes.BAD_CREDENTIALS_FORMAT({
+        sdkDetails: { paramsType: typeof params }
+      })
+    }
   }
 
   if (params.scopes && !Array.isArray(params.scopes)) {
-    throw new codes.BAD_SCOPES_FORMAT({
-      sdkDetails: { scopesType: typeof params.scopes }
-    })
+    return {
+      error: new codes.BAD_SCOPES_FORMAT({
+        sdkDetails: { scopesType: typeof params.scopes }
+      })
+    }
   }
 
   const credentials = {}
@@ -68,13 +71,13 @@ function getAndValidateCredentials (params) {
   }
 
   if (missingParams.length > 0) {
-    throw new codes.MISSING_PARAMETERS({
+    return { error: new codes.MISSING_PARAMETERS({
       messageValues: missingParams.join(', '),
       sdkDetails: { clientId, orgId, scopes }
-    })
+    }) }
   }
 
-  return credentials
+  return { credentials, error: null }
 }
 
 /**

src/index.js

@@ -10,10 +10,13 @@ governing permissions and limitations under the License.
 */
 
 const { getAccessTokenByClientCredentials, getAndValidateCredentials } = require('./ims.js')
-const { codes, messages } = require('./errors.js')
 const { TTLCache } = require('@isaacs/ttlcache')
 const crypto = require('crypto')
 
+// include-ims-credentials annotation input keys (keep in sync with src/constants.js)
+const IMS_OAUTH_S2S_INPUT = '__ims_oauth_s2s'
+const IMS_ENV_INPUT = '__ims_env'
+
 // Token cache with TTL
 // Opinionated for now, we could make it configurable in the future if needed -mg
 const tokenCache = new TTLCache({ ttl: 5 * 60 * 1000 }) // 5 minutes in milliseconds
@@ -56,9 +59,21 @@ function invalidateCache () {
  * @throws {Error} If there's an error getting the access token
  */
 async function generateAccessToken (params, imsEnv) {
-  imsEnv = imsEnv || (ioRuntimeStageNamespace() ? 'stage' : 'prod')
+  // integrate with the runtime environment and include-ims-credentials annotation
+  imsEnv = imsEnv || params?.[IMS_ENV_INPUT] || (ioRuntimeStageNamespace() ? 'stage' : 'prod')
+
+  let credentials
 
-  const credentials = getAndValidateCredentials(params)
+  // get parameters from params in priority otherwise try to load the credentials set to params.__ims_oauth_s2s by the annotation
+  const fromParams = getAndValidateCredentials(params)
+  credentials = fromParams.credentials
+  if (fromParams.error) {
+    const fromAnnotation = getAndValidateCredentials(params?.[IMS_OAUTH_S2S_INPUT])
+    if (fromAnnotation.error) {
+      throw fromParams.error // still throw original error
+    }
+    credentials = fromAnnotation.credentials
+  }
 
   const credAndEnv = { ...credentials, env: imsEnv }