azure-core

Azure core library - authentication, configuration, and shared utilities

Files

Dependencies

• crypto for HMAC-SHA256 request signing

This package also uses Kit standard modules:

• Env
• HTTP
• Time
• Encoding.Base64

Installation

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

Usage

import Kit.AzureCore as Azure

main = fn =>
  # Load a Shared Key client from AZURE_STORAGE_CONNECTION_STRING,
  # or from AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY.
  match Azure.client-from-env
    | Ok client ->
      println "Authenticated: ${client.account-name}"
      println "Blob endpoint: ${Azure.blob-url client.account-name}"

      if Azure.uses-shared-key? client then
        println "Using Shared Key authentication"
      else
        println "Using Bearer token authentication"

    | Err err ->
      println "Could not load Azure credentials: ${err}"

  # Parse a connection string directly.
  conn-str = "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=base64key==;EndpointSuffix=core.windows.net"

  match Azure.client-from-connection-string conn-str
    | Ok storage-client ->
      println "Queue endpoint: ${Azure.queue-url storage-client.account-name}"
    | Err err ->
      println "Invalid connection string: ${err}"

main

Authentication

kit-azure-core supports the auth building blocks used by higher-level Azure packages:

• Shared Key credentials from an Azure Storage connection string
• Shared Key credentials from AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY
• Azure AD/Entra ID client credentials flow via get-client-credentials-token
• Managed Identity token loading via the Azure Instance Metadata Service
• Bearer token clients via client-with-token

Common environment variables:

Capabilities

The package manifest declares the net capability because token and HTTP helpers can call Azure endpoints.

The crypto dependency uses FFI. When running examples or applications under explicit capability restrictions, include the capabilities your flow needs. For example:

kit run examples/basic.kit --allow=ffi,process

Networked token and HTTP calls also need net:

kit run examples/basic.kit --allow=ffi,process,net

Development

Running Examples

Run the basic example with the interpreter:

kit run examples/basic.kit --allow=ffi,process

Compile the example to a native binary:

kit build examples/basic.kit --debug --allow=ffi,process && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, example check, and tests):

kit dev

This will:

1. Check formatting for package files
2. Type check source files in src/
3. Type check example files in examples/
4. Run tests in tests/ with coverage

Running Parity

Check interpreter and compiler parity for examples:

kit parity --failures-only

This verifies that examples run through the interpreter, build successfully, execute as native binaries, and produce matching output.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/azure.kit

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

Cleaning Build Artifacts

Remove generated files, caches, coverage, parity results, 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/azure-core/, making it available for import as Kit.AzureCore in other projects.

License

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

Exported Functions & Types

AzureError

Azure error type with specific variants for different failure modes.

parse-connection-string

Parse Azure Storage connection string into credentials.

Extracts the AccountName and AccountKey from a standard Azure Storage connection string format (semicolon-delimited key=value pairs).

Parameters:

• conn-str - String - Connection string in format "AccountName=...;AccountKey=...;..."

Returns: Result StorageCredentials String - Parsed credentials or error message

String -> Result StorageCredentials AzureError

conn-str = "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=abc123==;EndpointSuffix=core.windows.net"
match parse-connection-string conn-str
  | Ok creds -> IO.print "Account: ${creds.account-name}"
  | Err err -> IO.print "Error: ${err}"

credentials-from-env

Load storage credentials from environment variables.

Attempts to load credentials from environment variables in the following order: 1. AZURE_STORAGE_CONNECTION_STRING (if present, parses connection string) 2. AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY (if both present)

Parameters:

• None

Returns: Result StorageCredentials String - Credentials loaded from environment or error

Environment Variables: AZURE_STORAGE_CONNECTION_STRING - Full Azure Storage connection string AZURE_STORAGE_ACCOUNT - Storage account name (alternative to connection string) AZURE_STORAGE_KEY - Storage account key (alternative to connection string)

() -> Result StorageCredentials AzureError

match credentials-from-env()
  | Ok creds -> IO.print "Loaded credentials for ${creds.account-name}"
  | Err err -> IO.print "Failed to load: ${err}"

storage-credentials

Create storage credentials explicitly.

Constructs a StorageCredentials record from account name and key.

Parameters:

• account-name - String - Azure storage account name
• account-key - String - Base64-encoded account access key

Returns: StorageCredentials - The constructed credentials

String -> String -> StorageCredentials

creds = storage-credentials "myaccount" "abc123base64key=="

client-credentials

Create Azure AD client credentials for service principal authentication.

Constructs a ClientCredentials record for OAuth 2.0 client credentials flow.

Parameters:

• tenant-id - String - Azure AD tenant ID (GUID)
• client-id - String - Application/client ID (GUID)
• client-secret - String - Client secret value

Returns: ClientCredentials - The constructed credentials

NonEmptyString -> NonEmptyString -> NonEmptyString -> ClientCredentials

creds = client-credentials "tenant-guid" "client-guid" "secret-value"

client

Create Azure client with storage credentials using Shared Key authentication.

This is the primary way to create a client for Azure Storage using an account key. The client will use Shared Key (HMAC-SHA256) to sign all requests.

Parameters:

• creds - StorageCredentials - Storage account name and key

Returns: AzureClient - Configured client ready for making authenticated requests

StorageCredentials -> AzureClient

creds = storage-credentials "myaccount" "mykey=="
client = client creds

client-from-connection-string

Create client from Azure Storage connection string.

Parses the connection string and creates a client configured for Shared Key auth.

Parameters:

• conn-str - String - Azure Storage connection string

Returns: Result AzureClient String - Configured client or error if parsing fails

String -> Result AzureClient AzureError

match client-from-connection-string conn-str
  | Ok client -> use-client client
  | Err err -> IO.print "Error: ${err}"

client-from-env

Create client from environment variables.

Loads credentials from AZURE_STORAGE_CONNECTION_STRING or from AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variables.

Parameters:

• None

Returns: Result AzureClient String - Configured client or error if credentials not found

() -> Result AzureClient AzureError

match client-from-env()
  | Ok client -> use-client client
  | Err err -> IO.print "No credentials: ${err}"

client-with-token

Create client with OAuth bearer token.

Creates a client that uses bearer token authentication instead of Shared Key. The token is assumed to expire in 1 hour (3600 seconds).

Parameters:

• account-name - String - Azure storage account name
• access-token - String - OAuth bearer token

Returns: AzureClient - Configured client using token authentication

NonEmptyString -> NonEmptyString -> AzureClient

token = "eyJ0eXAiOiJKV1QiLCJhbGc..."
client = client-with-token "myaccount" token

client-from-managed-identity

Create client using Azure Managed Identity.

Retrieves an access token from the Azure Instance Metadata Service (IMDS), which is available when running in Azure VMs, App Service, Functions, etc.

Parameters:

• account-name - String - Azure storage account name to access

Returns: Result AzureClient String - Configured client or error if IMDS unavailable

NonEmptyString -> Result AzureClient AzureError

  match client-from-managed-identity "myaccount"
    | Ok client -> use-client client
    | Err err -> IO.print "Managed identity failed: ${err}"

Note:
  This only works when running inside Azure services with managed identity enabled.

get-client-credentials-token

Get access token using client credentials (service principal).

ClientCredentials -> String -> Result AccessToken AzureError

sign-request

Sign a request using Shared Key authentication.

StorageCredentials -> String -> NonEmptyString -> List (String, String) -> Int -> List (String, String)

is-token-expired?

Check if token is expired (with 5 minute buffer).

AzureClient -> Bool

uses-shared-key?

Check if using Shared Key auth.

AzureClient -> Bool

refresh-token

Refresh managed identity token.

AzureClient -> Result AzureClient AzureError

get

Make authenticated GET request.

AzureClient -> NonEmptyString -> Result HttpResponse String

post

Make authenticated POST request.

AzureClient -> NonEmptyString -> String -> Result HttpResponse String

put

Make authenticated PUT request.

AzureClient -> NonEmptyString -> String -> Result HttpResponse String

delete

Make authenticated DELETE request.

AzureClient -> NonEmptyString -> Result HttpResponse String

blob-url

Build blob service URL.

NonEmptyString -> String

queue-url

Build queue service URL.

NonEmptyString -> String

table-url

Build table service URL.

NonEmptyString -> String

file-url

Build file service URL.

NonEmptyString -> String

url-encode

URL-encode a string.

String -> String