aws-oidc-token-provider.js

'use strict';

/**
 * OIDC Token Provider for AWS Workload Identity Federation.
 *
 * Mints a GitHub Actions OIDC token, exchanges it for temporary AWS
 * credentials via STS AssumeRoleWithWebIdentity, caches the result,
 * and proactively refreshes before expiry.
 *
 * Token flow:
 *   1. Request GitHub OIDC JWT from Actions runtime (audience: sts.amazonaws.com)
 *   2. Exchange JWT for temporary AWS credentials via STS AssumeRoleWithWebIdentity
 *   3. Cache credentials, schedule refresh at 75% of lifetime
 *   4. Serve cached credentials synchronously via getCredentials()
 *
 * Note: AWS uses SigV4 request signing, not Bearer tokens. The consumer
 * must use getCredentials() and sign the complete request (method, path,
 * headers, body hash) with the returned access key, secret key, and
 * session token.
 */

const { mintGitHubOidcToken, httpGet } = require('./github-oidc');
const { logRequest } = require('./logging');

// Refresh at 75% of credential lifetime (STS default is 3600s)
const REFRESH_FACTOR = 0.75;
const MIN_REFRESH_MARGIN_SECS = 300;
const REFRESH_RETRY_DELAY_MS = 30_000;
const MAX_INIT_RETRIES = 3;

/**
 * @typedef {Object} AwsCredentials
 * @property {string} accessKeyId
 * @property {string} secretAccessKey
 * @property {string} sessionToken
 */

/**
 * @typedef {Object} AwsOidcTokenProviderConfig
 * @property {string} requestUrl - ACTIONS_ID_TOKEN_REQUEST_URL
 * @property {string} requestToken - ACTIONS_ID_TOKEN_REQUEST_TOKEN
 * @property {string} roleArn - AWS IAM role ARN to assume
 * @property {string} region - AWS region (e.g., us-east-1)
 * @property {string} [roleSessionName] - Session name (default: awf-oidc-session)
 * @property {string} [oidcAudience] - Audience for GitHub OIDC token (default: sts.amazonaws.com)
 * @property {number} [retryDelayMs] - Retry delay after failed refresh (default: 30000)
 * @property {number} [maxInitRetries] - Maximum retries for initial token acquisition (default: 3)
 */

class AwsOidcTokenProvider {
  /**
   * @param {AwsOidcTokenProviderConfig} config
   */
  constructor(config) {
    this._requestUrl = config.requestUrl;
    this._requestToken = config.requestToken;
    this._roleArn = config.roleArn;
    this._region = config.region;
    this._roleSessionName = config.roleSessionName || 'awf-oidc-session';
    this._oidcAudience = config.oidcAudience || 'sts.amazonaws.com';
    this._retryDelayMs = config.retryDelayMs ?? REFRESH_RETRY_DELAY_MS;
    this._maxInitRetries = config.maxInitRetries ?? MAX_INIT_RETRIES;

    /** @type {AwsCredentials|null} */
    this._cachedCredentials = null;
    this._expiresAt = 0;
    this._refreshTimer = null;
    this._refreshInFlight = null;
    this._initialized = false;
    this._initError = null;
  }

  /**
   * Initialize by acquiring the first set of credentials.
   * @returns {Promise<void>}
   */
  async initialize() {
    for (let attempt = 1; attempt <= this._maxInitRetries; attempt++) {
      try {
        await this._refreshCredentials();
        this._initialized = true;
        this._initError = null;
        logRequest('info', 'aws_oidc_init_success', {
          role_arn: this._roleArn,
          region: this._region,
          expires_in_secs: this._expiresAt - Math.floor(Date.now() / 1000),
        });
        return;
      } catch (err) {
        this._initError = err;
        logRequest('warn', 'aws_oidc_init_retry', {
          attempt,
          max_retries: this._maxInitRetries,
          error: err.message,
        });
        if (attempt < this._maxInitRetries) {
          await this._sleep(this._retryDelayMs * attempt);
        }
      }
    }
    logRequest('error', 'aws_oidc_init_failed', {
      error: this._initError?.message,
      role_arn: this._roleArn,
    });
  }

  /**
   * Get the current cached AWS credentials synchronously.
   * Returns null if no valid credentials are available.
   * @returns {AwsCredentials|null}
   */
  getCredentials() {
    const now = Math.floor(Date.now() / 1000);
    if (this._cachedCredentials && this._expiresAt > now) {
      return this._cachedCredentials;
    }
    if (!this._refreshInFlight) {
      this._scheduleRefresh(0);
    }
    return null;
  }

  /**
   * Get the AWS region for this provider.
   * @returns {string}
   */
  getRegion() {
    return this._region;
  }

  /** @returns {boolean} */
  isReady() {
    const now = Math.floor(Date.now() / 1000);
    return !!(this._cachedCredentials && this._expiresAt > now);
  }

  shutdown() {
    if (this._refreshTimer) {
      clearTimeout(this._refreshTimer);
      this._refreshTimer = null;
    }
  }

  /**
   * Exchange GitHub OIDC JWT for temporary AWS credentials via STS.
   * Uses the HTTPS query API (no SDK dependency).
   * @param {string} oidcJwt
   * @returns {Promise<{credentials: AwsCredentials, expires_in: number}>}
   */
  async _assumeRoleWithWebIdentity(oidcJwt) {
    const params = new URLSearchParams({
      Action: 'AssumeRoleWithWebIdentity',
      Version: '2011-06-15',
      RoleArn: this._roleArn,
      RoleSessionName: this._roleSessionName,
      WebIdentityToken: oidcJwt,
    });

    const stsHost = this._resolveStsHost();
    const url = `https://${stsHost}/?${params.toString()}`;

    const response = await httpGet(url, {
      'Accept': 'application/json',
    });

    if (response.statusCode !== 200) {
      throw new Error(`AWS STS AssumeRoleWithWebIdentity failed: HTTP ${response.statusCode} — ${response.body}`);
    }

    // STS returns XML by default, but JSON when Accept: application/json is set
    // Parse the response to extract credentials
    const data = JSON.parse(response.body);
    const result = data.AssumeRoleWithWebIdentityResponse?.AssumeRoleWithWebIdentityResult;
    if (!result?.Credentials) {
      throw new Error('AWS STS response missing Credentials');
    }

    const creds = result.Credentials;
    const expiration = new Date(creds.Expiration);
    const expiresIn = Math.floor((expiration.getTime() - Date.now()) / 1000);

    return {
      credentials: {
        accessKeyId: creds.AccessKeyId,
        secretAccessKey: creds.SecretAccessKey,
        sessionToken: creds.SessionToken,
      },
      expires_in: expiresIn > 0 ? expiresIn : 3600,
    };
  }

  /**
   * Resolve the STS endpoint for the configured region.
   * Uses regional STS endpoints for lower latency.
   * @returns {string}
   */
  _resolveStsHost() {
    // China regions use a separate partition
    if (this._region.startsWith('cn-')) {
      return `sts.${this._region}.amazonaws.com.cn`;
    }
    // GovCloud
    if (this._region.startsWith('us-gov-')) {
      return `sts.${this._region}.amazonaws.com`;
    }
    // Standard regions — use regional endpoint
    return `sts.${this._region}.amazonaws.com`;
  }

  /**
   * Full credential refresh: GitHub OIDC → AWS STS.
   */
  async _refreshCredentials() {
    const oidcJwt = await mintGitHubOidcToken({
      requestUrl: this._requestUrl,
      requestToken: this._requestToken,
      audience: this._oidcAudience,
    });

    const { credentials, expires_in } = await this._assumeRoleWithWebIdentity(oidcJwt);

    const now = Math.floor(Date.now() / 1000);
    this._cachedCredentials = credentials;
    this._expiresAt = now + expires_in;

    const refreshInSecs = Math.max(
      0,
      Math.min(
        expires_in * REFRESH_FACTOR,
        expires_in - MIN_REFRESH_MARGIN_SECS
      )
    );
    this._scheduleRefresh(Math.floor(refreshInSecs * 1000));
  }

  /** @param {number} delayMs */
  _scheduleRefresh(delayMs) {
    if (this._refreshTimer) clearTimeout(this._refreshTimer);
    this._refreshTimer = setTimeout(() => {
      this._refreshInFlight = this._refreshCredentials()
        .then(() => {
          logRequest('info', 'aws_oidc_refresh_success', {
            expires_in_secs: this._expiresAt - Math.floor(Date.now() / 1000),
          });
        })
        .catch((err) => {
          logRequest('error', 'aws_oidc_refresh_failed', { error: err.message });
          const now = Math.floor(Date.now() / 1000);
          if (this._expiresAt > now) {
            this._scheduleRefresh(this._retryDelayMs);
          }
        })
        .finally(() => { this._refreshInFlight = null; });
    }, delayMs);
    if (this._refreshTimer.unref) this._refreshTimer.unref();
  }

  /** @param {number} ms */
  _sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

module.exports = { AwsOidcTokenProvider };