Base64 Encoding

The base64 module encodes strings and binary data using standard RFC 4648 Base64 and decodes them back to bytes.

This is an API reference. Output-only expressions show successful values; filesystem and transport examples check the optional second error return before consuming data. Names such as username, password, encoded_image, and user_input are application-supplied strings.

Base64 is an encoding, not encryption or authentication. Do not use it to conceal secrets or to verify that data has not been modified. Send Basic authentication credentials only over TLS and obtain them from application-owned secret storage rather than literals.

Loading

local base64 = require("base64")

Add base64 to the executable entry's modules: list before requiring it. Filesystem and JSON examples also require fs and json respectively.

Encoding

encode

Encodes a string, including binary data, as Base64.

-- Encode text
local encoded, err = base64.encode("Hello, World!")
if err then return nil, err end
print(encoded)  -- "SGVsbG8sIFdvcmxkIQ=="

-- Encode binary data (e.g., from file)
local image_data = fs.get("app:data"):readfile("photo.jpg")
local image_b64 = base64.encode(image_data)

-- Encode JSON for transport
local json = require("json")
local payload, json_err = json.encode({user = "alice", action = "login"})
if json_err then return nil, json_err end
local token_part, token_err = base64.encode(payload)
if token_err then return nil, token_err end

-- Encode credentials
local credentials, credentials_err = base64.encode(username .. ":" .. password)
if credentials_err then return nil, credentials_err end
local auth_header = "Basic " .. credentials

Returns: string, error — an empty input returns an empty string

Decoding

decode

Decodes a Base64 string to its original bytes.

-- Decode text
local decoded, decode_err = base64.decode("SGVsbG8sIFdvcmxkIQ==")
if decode_err then return nil, decode_err end
print(decoded)  -- "Hello, World!"

-- Decode with error handling
local data, err = base64.decode(user_input)
if err then
    return nil, errors.new("Invalid base64 data"):kind(errors.INVALID)
end

-- Decode binary data
local image_data, err = base64.decode(encoded_image)
if err then
    return nil, err
end
fs.get("app:data"):writefile("output.jpg", image_data)

-- Decode a base64-wrapped JSON document
local json = require("json")
local doc = json.decode(base64.decode(encoded_json))

The final block demonstrates delimiter handling only. It does not parse or verify a signed token format.

Returns: string, error — an empty input returns an empty string

Errors

See Error Handling for working with errors.