aws-core

AWS core library - credentials, signing, and shared utilities

Files

Dependencies

• crypto - HMAC-SHA256 and SHA256 support for AWS Signature Version 4

Capabilities

This package declares the net capability in kit.toml because AWS.execute can send signed HTTP requests.

The credential, region, URL encoding, and request signing helpers can be used without making network calls.

Installation

kit add gitlab.com/kit-lang/packages/kit-aws-core.git

Usage

import Kit.AwsCore as AWS

main = fn =>
  # Credentials can be passed explicitly.
  creds = AWS.credentials "AKIAEXAMPLE" "secretkey123"
  region = AWS.us-east-1

  # Sign a request without sending it.
  signed = AWS.sign-request creds region "s3" "GET" "https://bucket.s3.us-east-1.amazonaws.com/key" [] ""

  match signed
    | Ok req ->
      println "Signed ${req.method} request"
      println "URL: ${req.url}"
      println "Header count: ${Int.to-string (List.length req.headers)}"
    | Err err ->
      println "Signing failed: ${show err}"

main

Load credentials and region from the environment:

import Kit.AwsCore as AWS

main = fn =>
  match (AWS.credentials-from-env, AWS.region-from-env)
    | (Ok creds, Ok region) ->
      println "Loaded AWS credentials for ${region.name}"
      println "Access key: ${creds.access-key-id}"
    | (Err err, _) ->
      println "Credential error: ${show err}"
    | (_, Err err) ->
      println "Region error: ${show err}"

main

Environment variables used by this package:

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/regions.kit
kit run examples/sign-request.kit

Compile an example to a native binary:

kit build examples/basic.kit && ./basic

The examples import ../src/aws.kit so they exercise the local workspace source during development.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity

Check interpreter and compiled output parity for examples:

kit parity --no-spinner --failures-only

This is useful after changing examples or shared signing behavior because parity verifies that kit run and kit build produce matching output.

Running kit dev

Run the standard development workflow (format, check, examples, test):

kit dev

This will:

1. Format and check source files in src/
2. Format and check examples in examples/
3. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc src/aws.kit

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, coverage reports, parity reports, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/aws-core/, making it available for import as Kit.AwsCore in other projects.

When editing this package, run examples through the local examples/ files or reinstall with kit install before testing another project that imports Kit.AwsCore.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

AWSError

AWS error type with specific variants for different failure modes.

credentials

Create AWS credentials explicitly from access key and secret key

Use this when you have credentials hardcoded or loaded from a custom source. For temporary credentials, use credentials-with-token instead.

Parameters:

• access-key-id - String - AWS access key ID
• secret-access-key - String - AWS secret access key

Returns: Credentials - Credentials object with empty session token

String -> String -> Credentials

creds = AWS.credentials "AKIAIOSFODNN7EXAMPLE" "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

credentials-with-token

Create AWS credentials with session token for temporary credentials

Use this for temporary credentials obtained from AWS STS, IAM roles, or federated access.

Parameters:

• access-key-id - String - AWS access key ID
• secret-access-key - String - AWS secret access key
• session-token - String - Session token for temporary credentials

Returns: Credentials - Credentials object with session token

String -> String -> String -> Credentials

creds = AWS.credentials-with-token access-key secret-key session-token

credentials-from-env

Load AWS credentials from environment variables

Looks for the following environment variables: - AWS_ACCESS_KEY_ID (required) - AWS_SECRET_ACCESS_KEY (required) - AWS_SESSION_TOKEN (optional, for temporary credentials)

Returns: Result Credentials String - Ok with credentials if found, Err if not

Errors: Returns Err if AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY are not set

() -> Result Credentials AWSError

match AWS.credentials-from-env()
  | Ok creds -> use-credentials creds
  | Err err -> print "Error: ${err}"

us-east-1

Pre-configured AWS region: US East (N. Virginia)

us-east-2

Pre-configured AWS region: US East (Ohio)

us-west-1

Pre-configured AWS region: US West (N. California)

us-west-2

Pre-configured AWS region: US West (Oregon)

eu-west-1

Pre-configured AWS region: Europe (Ireland)

eu-west-2

Pre-configured AWS region: Europe (London)

eu-central-1

Pre-configured AWS region: Europe (Frankfurt)

ap-northeast-1

Pre-configured AWS region: Asia Pacific (Tokyo)

ap-southeast-1

Pre-configured AWS region: Asia Pacific (Singapore)

ap-southeast-2

Pre-configured AWS region: Asia Pacific (Sydney)

region

Create a custom AWS region configuration

Use this for regions not pre-defined above or for newer AWS regions.

Parameters:

• name - String - AWS region name (e.g., "us-east-1", "eu-central-1")

Returns: Region - Region configuration with standard amazonaws.com endpoint

NonEmptyString -> Region

region = AWS.region "ap-south-1"

region-with-endpoint

Create a region with custom endpoint for S3-compatible services

Use this for LocalStack, MinIO, Wasabi, or other S3-compatible services.

Parameters:

• name - String - Region name (can be arbitrary for non-AWS services)
• endpoint - String - Custom endpoint domain (e.g., "localhost:4566" for LocalStack)

Returns: Region - Region configuration with custom endpoint

NonEmptyString -> NonEmptyString -> Region

# LocalStack
region = AWS.region-with-endpoint "us-east-1" "localhost:4566"

# MinIO
region = AWS.region-with-endpoint "us-east-1" "localhost:9000"

region-from-env

Load AWS region from environment variables

Looks for the following environment variables in order: 1. AWS_REGION 2. AWS_DEFAULT_REGION

Returns: Result Region String - Ok with region if found, Err if not

Errors: Returns Err if neither AWS_REGION nor AWS_DEFAULT_REGION are set

() -> Result Region AWSError

match AWS.region-from-env()
  | Ok region -> use-region region
  | Err err -> print "Error: ${err}"

sign-request

Sign a request using AWS Signature Version 4. Returns a SignedRequest with Authorization header added.

Credentials -> Region -> String -> String -> NonEmptyString -> List (String, String) -> String -> Result SignedRequest AWSError

execute

Execute a signed request.

SignedRequest -> Result String String

url-encode

URL encode a string (for paths and query params).

String -> String