tessl/maven-io-ktor--ktor-http-js

JavaScript/WebAssembly implementation of Ktor's HTTP core library providing HTTP utilities, URL building, request/response handling, and HTTP method definitions for multiplatform Kotlin applications targeting JavaScript environments

—

Pending

Overview

Eval results

Files

Authentication

Name: tessl/maven-io-ktor--ktor-http-js
Author: tessl

HTTP authentication header parsing, challenge generation, and authentication scheme support.

Capabilities

HttpAuthHeader Base Class

Base class for all HTTP authentication headers with rendering support.

/**
 * Base sealed class for HTTP authentication headers
 * @param authScheme Authentication scheme (e.g., "Basic", "Bearer")
 */
sealed class HttpAuthHeader(val authScheme: String) {
    
    /**
     * Render header value using default encoding
     * @return Header value string
     */
    abstract fun render(): String
    
    /**
     * Render header value with specific encoding
     * @param encoding Header value encoding mode
     * @return Header value string
     */
    abstract fun render(encoding: HeaderValueEncoding): String
    
    companion object {
        /**
         * Create Basic authentication challenge
         * @param realm Authentication realm
         * @param charset Character set for credentials
         * @return Parameterized auth header
         */
        fun basicAuthChallenge(realm: String, charset: Charset): HttpAuthHeader.Parameterized
        
        /**
         * Create Digest authentication challenge
         * @param realm Authentication realm
         * @param nonce Server nonce value
         * @param opaque Opaque value for client
         * @param algorithm Hash algorithm (default MD5)
         * @param stale Whether credentials are stale
         * @param domain Protection domain
         * @return Parameterized auth header
         */
        fun digestAuthChallenge(
            realm: String,
            nonce: String,
            opaque: String? = null,
            algorithm: String? = null,
            stale: Boolean? = null,
            domain: String? = null
        ): HttpAuthHeader.Parameterized
        
        /**
         * Create Bearer authentication challenge
         * @param realm Authentication realm (optional)
         * @param scope Access scope (optional)
         * @return Auth header
         */
        fun bearerAuthChallenge(realm: String? = null, scope: String? = null): HttpAuthHeader
    }
}

Single Value Authentication

Authentication header with single value (e.g., Bearer token).

/**
 * Authentication header with single value
 * @param authScheme Authentication scheme
 * @param blob Authentication value/token
 */
class HttpAuthHeader.Single(
    authScheme: String,
    val blob: String
) : HttpAuthHeader(authScheme) {
    
    override fun render(): String
    override fun render(encoding: HeaderValueEncoding): String
}

Parameterized Authentication

Authentication header with parameters (e.g., Digest authentication).

/**
 * Authentication header with parameters
 * @param authScheme Authentication scheme
 * @param parameters List of header parameters
 * @param encoding Parameter value encoding
 */
class HttpAuthHeader.Parameterized(
    authScheme: String,
    val parameters: List<HeaderValueParam>,
    val encoding: HeaderValueEncoding = HeaderValueEncoding.QUOTED_WHEN_REQUIRED
) : HttpAuthHeader(authScheme) {
    
    constructor(
        authScheme: String,
        parameters: Map<String, String>,
        encoding: HeaderValueEncoding = HeaderValueEncoding.QUOTED_WHEN_REQUIRED
    )
    
    /**
     * Get parameter value by name
     * @param name Parameter name
     * @return Parameter value or null
     */
    fun parameter(name: String): String?
    
    /**
     * Add parameter to existing header
     * @param name Parameter name
     * @param value Parameter value
     * @return New Parameterized header with parameter
     */
    fun withParameter(name: String, value: String): HttpAuthHeader.Parameterized
    
    /**
     * Replace existing parameter or add new one
     * @param name Parameter name
     * @param value Parameter value
     * @return New Parameterized header with replaced parameter
     */
    fun withReplacedParameter(name: String, value: String): HttpAuthHeader.Parameterized
    
    override fun render(): String
    override fun render(encoding: HeaderValueEncoding): String
}

Authentication Schemes

Constants for common authentication schemes.

/**
 * Common authentication schemes
 */
object AuthScheme {
    val Basic: String
    val Bearer: String
    val Digest: String
    val Negotiate: String
    val OAuth: String
}

Authentication Parameters

Constants for standard authentication parameters.

/**
 * Standard authentication header parameters
 */
object HttpAuthHeader.Parameters {
    val Realm: String
    val Charset: String
    
    // OAuth parameters
    val OAuthCallback: String
    val OAuthCallbackConfirmed: String
    val OAuthConsumerKey: String
    val OAuthNonce: String
    val OAuthSignature: String
    val OAuthSignatureMethod: String
    val OAuthTimestamp: String
    val OAuthToken: String
    val OAuthTokenSecret: String
    val OAuthVerifier: String
    val OAuthVersion: String
}

Header Value Encoding

Enumeration for different header value encoding modes.

/**
 * Header value encoding modes
 */
enum class HeaderValueEncoding {
    /**
     * Quote values only when required by HTTP specification
     */
    QUOTED_WHEN_REQUIRED,
    
    /**
     * Always quote parameter values  
     */
    QUOTED_ALWAYS,
    
    /**
     * URI encode parameter values
     */
    URI_ENCODE
}

Header Parsing Functions

Functions for parsing authentication headers from strings.

/**
 * Parse Authorization header value
 * @param headerValue Raw Authorization header value
 * @return HttpAuthHeader instance or null if invalid
 */
fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?

/**
 * Parse multiple Authorization headers
 * @param headerValue Raw Authorization header value with multiple schemes
 * @return List of HttpAuthHeader instances
 */
fun parseAuthorizationHeaders(headerValue: String): List<HttpAuthHeader>

Usage Examples:

import io.ktor.http.auth.*
import io.ktor.http.*
import java.nio.charset.StandardCharsets

// Create authentication headers
val basicAuth = HttpAuthHeader.Single(AuthScheme.Basic, "dXNlcjpwYXNz") // user:pass base64
val bearerAuth = HttpAuthHeader.Single(AuthScheme.Bearer, "eyJhbGciOiJIUzI1NiJ9...")

// Create parameterized authentication
val digestAuth = HttpAuthHeader.Parameterized(
    AuthScheme.Digest,
    listOf(
        HeaderValueParam("realm", "Protected Area"),
        HeaderValueParam("nonce", "abc123"),
        HeaderValueParam("uri", "/api/data"),
        HeaderValueParam("response", "def456")
    )
)

// Create challenges for WWW-Authenticate header
val basicChallenge = HttpAuthHeader.basicAuthChallenge("Protected Area", StandardCharsets.UTF_8)
val digestChallenge = HttpAuthHeader.digestAuthChallenge(
    realm = "Protected Area",
    nonce = "abc123def456",
    opaque = "xyz789"
)
val bearerChallenge = HttpAuthHeader.bearerAuthChallenge(
    realm = "API Access",
    scope = "read write"
)

// Render headers
val basicHeaderValue = basicAuth.render() // "Basic dXNlcjpwYXNz"
val bearerHeaderValue = bearerAuth.render() // "Bearer eyJhbGciOiJIUzI1NiJ9..."
val digestHeaderValue = digestAuth.render() // "Digest realm="Protected Area", nonce="abc123", ..."

// Parse headers
val parsed = parseAuthorizationHeader("Basic dXNlcjpwYXNz")
when (parsed) {
    is HttpAuthHeader.Single -> println("Single auth: ${parsed.blob}")
    is HttpAuthHeader.Parameterized -> println("Parameterized auth with ${parsed.parameters.size} params")
}

// Work with parameters
val realmParam = digestAuth.parameter("realm") // "Protected Area"
val withNewParam = digestAuth.withParameter("cnonce", "client123")

// Different encoding modes
val quoted = digestAuth.render(HeaderValueEncoding.QUOTED_ALWAYS)
val uriEncoded = digestAuth.render(HeaderValueEncoding.URI_ENCODE)

// Multiple authorization headers
val multipleHeaders = parseAuthorizationHeaders("Basic dXNlcjpwYXNz, Bearer token123")
println("Found ${multipleHeaders.size} auth headers")

// OAuth example
val oauthAuth = HttpAuthHeader.Parameterized(
    AuthScheme.OAuth,
    mapOf(
        HttpAuthHeader.Parameters.OAuthConsumerKey to "consumer123",
        HttpAuthHeader.Parameters.OAuthToken to "token456",
        HttpAuthHeader.Parameters.OAuthSignatureMethod to "HMAC-SHA1",
        HttpAuthHeader.Parameters.OAuthTimestamp to "1234567890",
        HttpAuthHeader.Parameters.OAuthNonce to "nonce789",
        HttpAuthHeader.Parameters.OAuthSignature to "signature="
    )
)

// Build complete authentication flow
fun buildBasicAuth(username: String, password: String): String {
    val credentials = "$username:$password"
    val encoded = java.util.Base64.getEncoder().encodeToString(credentials.toByteArray())
    return HttpAuthHeader.Single(AuthScheme.Basic, encoded).render()
}

fun buildBearerAuth(token: String): String {
    return HttpAuthHeader.Single(AuthScheme.Bearer, token).render()
}

// Challenge responses
fun createBasicChallenge(realm: String): String {
    return HttpAuthHeader.basicAuthChallenge(realm, StandardCharsets.UTF_8).render()
}

fun createDigestChallenge(realm: String, nonce: String): String {
    return HttpAuthHeader.digestAuthChallenge(realm, nonce).render()
}

Install with Tessl CLI

npx tessl i tessl/maven-io-ktor--ktor-http-js

docs