egress Module

Public Luau surface over the __egress Internal FFI namespace — credential-injecting HTTP for BYO-key world egress (Mechanism B).

Purpose

Wrap the raw __egress.* FFI namespace in a typed Luau table that gets auto-injected as _G.egress via the prelude. The seam through which user-scope world code reaches external APIs with a world-owned credential. The built-in .service assets use the credit-metered path (Service.invoke), not this.

Why this layer exists:

• Secrets must never be visible to user-scope Luau (the world VFS is publicly visible; WASM has no env vars).
• So the credential value lives ONLY in the Rust-side store. The trusted VM sets it via egress.setCredential; user-scope code calls egress.fetch(name, ...) and the header is appended to the outbound request in Rust — never returned to Luau.
• base_url enforcement prevents a named credential from being used against an arbitrary host.

Scope enforcement is in the FFI layer: setCredential / clearCredential are TRUSTED ONLY and the wrapper surfaces them for the trusted VM's use. User-scope calls into the setters get refused by the binding scope check.

Usage

-- Trusted VM (boot, secrets vault):
egress.setCredential("meshy", "https://api.meshy.ai/", "Authorization",
    "Bearer " .. meshyKey)

-- User-scope service code:
if not egress.hasCredential("meshy") then
    error("meshy credential not configured")
end

local handle = egress.fetch("meshy", "POST",
    "https://api.meshy.ai/v2/text-to-3d", nil, { prompt = "a dragon" })
local resp = task.await(handle)

Exports

• Trusted-only: egress.setCredential(name, baseUrl, headerName, headerValue) -> boolean / egress.clearCredential(name) -> boolean.
• Public: egress.hasCredential(name) -> boolean / egress.credentialNames() -> { string } / egress.fetch(name, method, url, headers?, body?, response?) -> promiseId?.