@hanzo/s3 0.6.3 → 8.0.7

package/src/AssumeRoleProvider.ts

@@ -0,0 +1,262 @@
+import * as http from 'node:http'
+import * as https from 'node:https'
+import { URL, URLSearchParams } from 'node:url'
+
+import { CredentialProvider } from './CredentialProvider.ts'
+import { Credentials } from './Credentials.ts'
+import { makeDateLong, parseXml, toSha256 } from './internal/helper.ts'
+import { request } from './internal/request.ts'
+import { readAsString } from './internal/response.ts'
+import type { Transport } from './internal/type.ts'
+import { signV4ByServiceName } from './signing.ts'
+
+/**
+ * @see https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html
+ */
+type CredentialResponse = {
+  ErrorResponse?: {
+    Error?: {
+      Code?: string
+      Message?: string
+    }
+  }
+
+  AssumeRoleResponse: {
+    AssumeRoleResult: {
+      Credentials: {
+        AccessKeyId: string
+        SecretAccessKey: string
+        SessionToken: string
+        Expiration: string
+      }
+    }
+  }
+}
+
+export interface AssumeRoleProviderOptions {
+  stsEndpoint: string
+  accessKey: string
+  secretKey: string
+  durationSeconds?: number
+  sessionToken?: string
+  policy?: string
+  region?: string
+  roleArn?: string
+  roleSessionName?: string
+  externalId?: string
+  token?: string
+  webIdentityToken?: string
+  action?: string
+  transportAgent?: http.Agent
+}
+
+const defaultExpirySeconds = 900
+
+export class AssumeRoleProvider extends CredentialProvider {
+  private readonly stsEndpoint: URL
+  private readonly accessKey: string
+  private readonly secretKey: string
+  private readonly durationSeconds: number
+  private readonly policy?: string
+  private readonly region: string
+  private readonly roleArn?: string
+  private readonly roleSessionName?: string
+  private readonly externalId?: string
+  private readonly token?: string
+  private readonly webIdentityToken?: string
+  private readonly action: string
+
+  private _credentials: Credentials | null
+  private readonly expirySeconds: number
+  private accessExpiresAt = ''
+  private readonly transportAgent?: http.Agent
+
+  private readonly transport: Transport
+
+  constructor({
+    stsEndpoint,
+    accessKey,
+    secretKey,
+    durationSeconds = defaultExpirySeconds,
+    sessionToken,
+    policy,
+    region = '',
+    roleArn,
+    roleSessionName,
+    externalId,
+    token,
+    webIdentityToken,
+    action = 'AssumeRole',
+    transportAgent = undefined,
+  }: AssumeRoleProviderOptions) {
+    super({ accessKey, secretKey, sessionToken })
+
+    this.stsEndpoint = new URL(stsEndpoint)
+    this.accessKey = accessKey
+    this.secretKey = secretKey
+    this.policy = policy
+    this.region = region
+    this.roleArn = roleArn
+    this.roleSessionName = roleSessionName
+    this.externalId = externalId
+    this.token = token
+    this.webIdentityToken = webIdentityToken
+    this.action = action
+
+    this.durationSeconds = parseInt(durationSeconds as unknown as string)
+
+    let expirySeconds = this.durationSeconds
+    if (this.durationSeconds < defaultExpirySeconds) {
+      expirySeconds = defaultExpirySeconds
+    }
+    this.expirySeconds = expirySeconds // for calculating refresh of credentials.
+
+    // By default, nodejs uses a global agent if the 'agent' property
+    // is set to undefined. Otherwise, it's okay to assume the users
+    // know what they're doing if they specify a custom transport agent.
+    this.transportAgent = transportAgent
+    const isHttp: boolean = this.stsEndpoint.protocol === 'http:'
+    this.transport = isHttp ? http : https
+
+    /**
+     * Internal Tracking variables
+     */
+    this._credentials = null
+  }
+
+  getRequestConfig(): {
+    requestOptions: http.RequestOptions
+    requestData: string
+  } {
+    const hostValue = this.stsEndpoint.hostname
+    const portValue = this.stsEndpoint.port
+    const qryParams = new URLSearchParams({ Action: this.action, Version: '2011-06-15' })
+
+    qryParams.set('DurationSeconds', this.expirySeconds.toString())
+
+    if (this.policy) {
+      qryParams.set('Policy', this.policy)
+    }
+    if (this.roleArn) {
+      qryParams.set('RoleArn', this.roleArn)
+    }
+
+    if (this.roleSessionName != null) {
+      qryParams.set('RoleSessionName', this.roleSessionName)
+    }
+    if (this.token != null) {
+      qryParams.set('Token', this.token)
+    }
+
+    if (this.webIdentityToken) {
+      qryParams.set('WebIdentityToken', this.webIdentityToken)
+    }
+
+    if (this.externalId) {
+      qryParams.set('ExternalId', this.externalId)
+    }
+
+    const urlParams = qryParams.toString()
+    const contentSha256 = toSha256(urlParams)
+
+    const date = new Date()
+
+    const requestOptions = {
+      hostname: hostValue,
+      port: portValue,
+      path: '/',
+      protocol: this.stsEndpoint.protocol,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'content-length': urlParams.length.toString(),
+        host: hostValue,
+        'x-amz-date': makeDateLong(date),
+        'x-amz-content-sha256': contentSha256,
+      } as Record<string, string>,
+      agent: this.transportAgent,
+    } satisfies http.RequestOptions
+
+    requestOptions.headers.authorization = signV4ByServiceName(
+      requestOptions,
+      this.accessKey,
+      this.secretKey,
+      this.region,
+      date,
+      contentSha256,
+      'sts',
+    )
+
+    return {
+      requestOptions,
+      requestData: urlParams,
+    }
+  }
+
+  async performRequest(): Promise<CredentialResponse> {
+    const { requestOptions, requestData } = this.getRequestConfig()
+
+    const res = await request(this.transport, requestOptions, requestData)
+
+    const body = await readAsString(res)
+
+    return parseXml(body)
+  }
+
+  parseCredentials(respObj: CredentialResponse): Credentials {
+    if (respObj.ErrorResponse) {
+      throw new Error(
+        `Unable to obtain credentials: ${respObj.ErrorResponse?.Error?.Code} ${respObj.ErrorResponse?.Error?.Message}`,
+        { cause: respObj },
+      )
+    }
+
+    const {
+      AssumeRoleResponse: {
+        AssumeRoleResult: {
+          Credentials: {
+            AccessKeyId: accessKey,
+            SecretAccessKey: secretKey,
+            SessionToken: sessionToken,
+            Expiration: expiresAt,
+          },
+        },
+      },
+    } = respObj
+
+    this.accessExpiresAt = expiresAt
+
+    return new Credentials({ accessKey, secretKey, sessionToken })
+  }
+
+  async refreshCredentials(): Promise<Credentials> {
+    try {
+      const assumeRoleCredentials = await this.performRequest()
+      this._credentials = this.parseCredentials(assumeRoleCredentials)
+    } catch (err) {
+      throw new Error(`Failed to get Credentials: ${err}`, { cause: err })
+    }
+
+    return this._credentials
+  }
+
+  async getCredentials(): Promise<Credentials> {
+    if (this._credentials && !this.isAboutToExpire()) {
+      return this._credentials
+    }
+
+    this._credentials = await this.refreshCredentials()
+    return this._credentials
+  }
+
+  isAboutToExpire() {
+    const expiresAt = new Date(this.accessExpiresAt)
+    const provisionalExpiry = new Date(Date.now() + 1000 * 10) // check before 10 seconds.
+    return provisionalExpiry > expiresAt
+  }
+}
+
+// deprecated default export, please use named exports.
+// keep for backward compatibility.
+// eslint-disable-next-line import/no-default-export
+export default AssumeRoleProvider

package/src/CredentialProvider.ts

@@ -0,0 +1,54 @@
+import { Credentials } from './Credentials.ts'
+
+export class CredentialProvider {
+  private credentials: Credentials
+
+  constructor({ accessKey, secretKey, sessionToken }: { accessKey: string; secretKey: string; sessionToken?: string }) {
+    this.credentials = new Credentials({
+      accessKey,
+      secretKey,
+      sessionToken,
+    })
+  }
+
+  async getCredentials(): Promise<Credentials> {
+    return this.credentials.get()
+  }
+
+  setCredentials(credentials: Credentials) {
+    if (credentials instanceof Credentials) {
+      this.credentials = credentials
+    } else {
+      throw new Error('Unable to set Credentials. it should be an instance of Credentials class')
+    }
+  }
+
+  setAccessKey(accessKey: string) {
+    this.credentials.setAccessKey(accessKey)
+  }
+
+  getAccessKey() {
+    return this.credentials.getAccessKey()
+  }
+
+  setSecretKey(secretKey: string) {
+    this.credentials.setSecretKey(secretKey)
+  }
+
+  getSecretKey() {
+    return this.credentials.getSecretKey()
+  }
+
+  setSessionToken(sessionToken: string) {
+    this.credentials.setSessionToken(sessionToken)
+  }
+
+  getSessionToken() {
+    return this.credentials.getSessionToken()
+  }
+}
+
+// deprecated default export, please use named exports.
+// keep for backward compatibility.
+// eslint-disable-next-line import/no-default-export
+export default CredentialProvider

package/src/Credentials.ts

@@ -0,0 +1,44 @@
+export class Credentials {
+  public accessKey: string
+  public secretKey: string
+  public sessionToken?: string
+
+  constructor({ accessKey, secretKey, sessionToken }: { accessKey: string; secretKey: string; sessionToken?: string }) {
+    this.accessKey = accessKey
+    this.secretKey = secretKey
+    this.sessionToken = sessionToken
+  }
+
+  setAccessKey(accessKey: string) {
+    this.accessKey = accessKey
+  }
+
+  getAccessKey() {
+    return this.accessKey
+  }
+
+  setSecretKey(secretKey: string) {
+    this.secretKey = secretKey
+  }
+
+  getSecretKey() {
+    return this.secretKey
+  }
+
+  setSessionToken(sessionToken: string) {
+    this.sessionToken = sessionToken
+  }
+
+  getSessionToken() {
+    return this.sessionToken
+  }
+
+  get(): Credentials {
+    return this
+  }
+}
+
+// deprecated default export, please use named exports.
+// keep for backward compatibility.
+// eslint-disable-next-line import/no-default-export
+export default Credentials

package/src/IamAwsProvider.ts

@@ -0,0 +1,234 @@
+import * as fs from 'node:fs/promises'
+import * as http from 'node:http'
+import * as https from 'node:https'
+import { URL, URLSearchParams } from 'node:url'
+
+import { CredentialProvider } from './CredentialProvider.ts'
+import { Credentials } from './Credentials.ts'
+import { parseXml } from './internal/helper.ts'
+import { request } from './internal/request.ts'
+import { readAsString } from './internal/response.ts'
+
+interface AssumeRoleResponse {
+  AssumeRoleWithWebIdentityResponse: {
+    AssumeRoleWithWebIdentityResult: {
+      Credentials: {
+        AccessKeyId: string
+        SecretAccessKey: string
+        SessionToken: string
+        Expiration: string
+      }
+    }
+  }
+}
+
+interface EcsCredentials {
+  AccessKeyID: string
+  SecretAccessKey: string
+  Token: string
+  Expiration: string
+  Code: string
+  Message: string
+}
+
+export interface IamAwsProviderOptions {
+  customEndpoint?: string
+  transportAgent?: http.Agent
+}
+
+export class IamAwsProvider extends CredentialProvider {
+  private readonly customEndpoint?: string
+
+  private _credentials: Credentials | null
+  private readonly transportAgent?: http.Agent
+  private accessExpiresAt = ''
+
+  constructor({ customEndpoint = undefined, transportAgent = undefined }: IamAwsProviderOptions) {
+    super({ accessKey: '', secretKey: '' })
+
+    this.customEndpoint = customEndpoint
+    this.transportAgent = transportAgent
+
+    /**
+     * Internal Tracking variables
+     */
+    this._credentials = null
+  }
+
+  async getCredentials(): Promise<Credentials> {
+    if (!this._credentials || this.isAboutToExpire()) {
+      this._credentials = await this.fetchCredentials()
+    }
+    return this._credentials
+  }
+
+  private async fetchCredentials(): Promise<Credentials> {
+    try {
+      // check for IRSA (https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
+      const tokenFile = process.env.AWS_WEB_IDENTITY_TOKEN_FILE
+      if (tokenFile) {
+        return await this.fetchCredentialsUsingTokenFile(tokenFile)
+      }
+
+      // try with IAM role for EC2 instances (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
+      let tokenHeader = 'Authorization'
+      let token = process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN
+      const relativeUri = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
+      const fullUri = process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI
+      let url: URL
+      if (relativeUri) {
+        url = new URL(relativeUri, 'http://169.254.170.2')
+      } else if (fullUri) {
+        url = new URL(fullUri)
+      } else {
+        token = await this.fetchImdsToken()
+        tokenHeader = 'X-aws-ec2-metadata-token'
+        url = await this.getIamRoleNamedUrl(token)
+      }
+
+      return this.requestCredentials(url, tokenHeader, token)
+    } catch (err) {
+      throw new Error(`Failed to get Credentials: ${err}`, { cause: err })
+    }
+  }
+
+  private async fetchCredentialsUsingTokenFile(tokenFile: string): Promise<Credentials> {
+    const token = await fs.readFile(tokenFile, { encoding: 'utf8' })
+    const region = process.env.AWS_REGION
+    const stsEndpoint = new URL(region ? `https://sts.${region}.amazonaws.com` : 'https://sts.amazonaws.com')
+
+    const hostValue = stsEndpoint.hostname
+    const portValue = stsEndpoint.port
+    const qryParams = new URLSearchParams({
+      Action: 'AssumeRoleWithWebIdentity',
+      Version: '2011-06-15',
+    })
+
+    const roleArn = process.env.AWS_ROLE_ARN
+    if (roleArn) {
+      qryParams.set('RoleArn', roleArn)
+      const roleSessionName = process.env.AWS_ROLE_SESSION_NAME
+      qryParams.set('RoleSessionName', roleSessionName ? roleSessionName : Date.now().toString())
+    }
+
+    qryParams.set('WebIdentityToken', token)
+    qryParams.sort()
+
+    const requestOptions = {
+      hostname: hostValue,
+      port: portValue,
+      path: `${stsEndpoint.pathname}?${qryParams.toString()}`,
+      protocol: stsEndpoint.protocol,
+      method: 'POST',
+      headers: {},
+      agent: this.transportAgent,
+    } satisfies http.RequestOptions
+
+    const transport = stsEndpoint.protocol === 'http:' ? http : https
+    const res = await request(transport, requestOptions, null)
+    const body = await readAsString(res)
+
+    const assumeRoleResponse: AssumeRoleResponse = parseXml(body)
+    const creds = assumeRoleResponse.AssumeRoleWithWebIdentityResponse.AssumeRoleWithWebIdentityResult.Credentials
+    this.accessExpiresAt = creds.Expiration
+    return new Credentials({
+      accessKey: creds.AccessKeyId,
+      secretKey: creds.SecretAccessKey,
+      sessionToken: creds.SessionToken,
+    })
+  }
+
+  private async fetchImdsToken() {
+    const endpoint = this.customEndpoint ? this.customEndpoint : 'http://169.254.169.254'
+    const url = new URL('/latest/api/token', endpoint)
+
+    const requestOptions = {
+      hostname: url.hostname,
+      port: url.port,
+      path: `${url.pathname}${url.search}`,
+      protocol: url.protocol,
+      method: 'PUT',
+      headers: {
+        'X-aws-ec2-metadata-token-ttl-seconds': '21600',
+      },
+      agent: this.transportAgent,
+    } satisfies http.RequestOptions
+
+    const transport = url.protocol === 'http:' ? http : https
+    const res = await request(transport, requestOptions, null)
+    return await readAsString(res)
+  }
+
+  private async getIamRoleNamedUrl(token: string) {
+    const endpoint = this.customEndpoint ? this.customEndpoint : 'http://169.254.169.254'
+    const url = new URL('latest/meta-data/iam/security-credentials/', endpoint)
+
+    const roleName = await this.getIamRoleName(url, token)
+    return new URL(`${url.pathname}/${encodeURIComponent(roleName)}`, url.origin)
+  }
+
+  private async getIamRoleName(url: URL, token: string): Promise<string> {
+    const requestOptions = {
+      hostname: url.hostname,
+      port: url.port,
+      path: `${url.pathname}${url.search}`,
+      protocol: url.protocol,
+      method: 'GET',
+      headers: {
+        'X-aws-ec2-metadata-token': token,
+      },
+      agent: this.transportAgent,
+    } satisfies http.RequestOptions
+
+    const transport = url.protocol === 'http:' ? http : https
+    const res = await request(transport, requestOptions, null)
+    const body = await readAsString(res)
+    const roleNames = body.split(/\r\n|[\n\r\u2028\u2029]/)
+    if (roleNames.length === 0) {
+      throw new Error(`No IAM roles attached to EC2 service ${url}`)
+    }
+    return roleNames[0] as string
+  }
+
+  private async requestCredentials(url: URL, tokenHeader: string, token: string | undefined): Promise<Credentials> {
+    const headers: Record<string, string> = {}
+    if (token) {
+      headers[tokenHeader] = token
+    }
+    const requestOptions = {
+      hostname: url.hostname,
+      port: url.port,
+      path: `${url.pathname}${url.search}`,
+      protocol: url.protocol,
+      method: 'GET',
+      headers: headers,
+      agent: this.transportAgent,
+    } satisfies http.RequestOptions
+
+    const transport = url.protocol === 'http:' ? http : https
+    const res = await request(transport, requestOptions, null)
+    const body = await readAsString(res)
+    const ecsCredentials = JSON.parse(body) as EcsCredentials
+    if (!ecsCredentials.Code || ecsCredentials.Code != 'Success') {
+      throw new Error(`${url} failed with code ${ecsCredentials.Code} and message ${ecsCredentials.Message}`)
+    }
+
+    this.accessExpiresAt = ecsCredentials.Expiration
+    return new Credentials({
+      accessKey: ecsCredentials.AccessKeyID,
+      secretKey: ecsCredentials.SecretAccessKey,
+      sessionToken: ecsCredentials.Token,
+    })
+  }
+
+  private isAboutToExpire() {
+    const expiresAt = new Date(this.accessExpiresAt)
+    const provisionalExpiry = new Date(Date.now() + 1000 * 10) // 10 seconds leeway
+    return provisionalExpiry > expiresAt
+  }
+}
+
+// deprecated default export, please use named exports.
+// keep for backward compatibility.
+// eslint-disable-next-line import/no-default-export
+export default IamAwsProvider

package/src/errors.ts

@@ -0,0 +1,120 @@
+/*
+ * Hanzo S3 Javascript Library for Amazon S3 Compatible Cloud Storage, (C) 2015 Hanzo AI, Inc.
+ *
+ * Licensed 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 CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/// <reference lib="ES2022.Error" />
+
+class ExtendableError extends Error {
+  constructor(message?: string, opt?: ErrorOptions) {
+    // error Option {cause?: unknown} is a 'nice to have',
+    // don't use it internally
+    super(message, opt)
+    // set error name, otherwise it's always 'Error'
+    this.name = this.constructor.name
+  }
+}
+
+/**
+ * AnonymousRequestError is generated for anonymous keys on specific
+ * APIs. NOTE: PresignedURL generation always requires access keys.
+ */
+export class AnonymousRequestError extends ExtendableError {}
+
+/**
+ * InvalidArgumentError is generated for all invalid arguments.
+ */
+export class InvalidArgumentError extends ExtendableError {}
+
+/**
+ * InvalidPortError is generated when a non integer value is provided
+ * for ports.
+ */
+export class InvalidPortError extends ExtendableError {}
+
+/**
+ * InvalidEndpointError is generated when an invalid end point value is
+ * provided which does not follow domain standards.
+ */
+export class InvalidEndpointError extends ExtendableError {}
+
+/**
+ * InvalidBucketNameError is generated when an invalid bucket name is
+ * provided which does not follow AWS S3 specifications.
+ * http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html
+ */
+export class InvalidBucketNameError extends ExtendableError {}
+
+/**
+ * InvalidObjectNameError is generated when an invalid object name is
+ * provided which does not follow AWS S3 specifications.
+ * http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html
+ */
+export class InvalidObjectNameError extends ExtendableError {}
+
+/**
+ * AccessKeyRequiredError generated by signature methods when access
+ * key is not found.
+ */
+export class AccessKeyRequiredError extends ExtendableError {}
+
+/**
+ * SecretKeyRequiredError generated by signature methods when secret
+ * key is not found.
+ */
+export class SecretKeyRequiredError extends ExtendableError {}
+
+/**
+ * ExpiresParamError generated when expires parameter value is not
+ * well within stipulated limits.
+ */
+export class ExpiresParamError extends ExtendableError {}
+
+/**
+ * InvalidDateError generated when invalid date is found.
+ */
+export class InvalidDateError extends ExtendableError {}
+
+/**
+ * InvalidPrefixError generated when object prefix provided is invalid
+ * or does not conform to AWS S3 object key restrictions.
+ */
+export class InvalidPrefixError extends ExtendableError {}
+
+/**
+ * InvalidBucketPolicyError generated when the given bucket policy is invalid.
+ */
+export class InvalidBucketPolicyError extends ExtendableError {}
+
+/**
+ * IncorrectSizeError generated when total data read mismatches with
+ * the input size.
+ */
+export class IncorrectSizeError extends ExtendableError {}
+
+/**
+ * InvalidXMLError generated when an unknown XML is found.
+ */
+export class InvalidXMLError extends ExtendableError {}
+
+/**
+ * S3Error is generated for errors returned from S3 server.
+ * see getErrorTransformer for details
+ */
+export class S3Error extends ExtendableError {
+  code?: string
+  region?: string
+}
+
+export class IsValidBucketNameError extends ExtendableError {}