@qlever-llc/trellis 0.5.1

package/esm/trellis/trellis.js

@@ -0,0 +1,710 @@
+// @ts-nocheck
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Trellis_instances, _Trellis_log, _Trellis_tasks, _Trellis_noResponderMaxRetries, _Trellis_noResponderRetryMs, _Trellis_authBypassMethods, _Trellis_handleRPC, _Trellis_processRPCMessage, _Trellis_respondWithError, _Trellis_handleEvent, _Trellis_escapeSubjectToken, _Trellis_createProof, _TrellisServer_version, _TrellisServer_log;
+import { jetstream, jetstreamManager, } from "@nats-io/jetstream";
+import { headers as natsHeaders, } from "@nats-io/nats-core";
+import { AsyncResult, err, isErr, ok, Result, } from "@qlever-llc/trellis-result";
+import { API as trellisCoreApi } from "@qlever-llc/trellis-sdk-core";
+import { createNatsHeaderCarrier, extractTraceContext, injectTraceContext, SpanStatusCode, startClientSpan, startServerSpan, withSpanAsync } from "@qlever-llc/trellis-telemetry";
+import { Pointer } from "typebox/value";
+import { ulid } from "ulid";
+import { encodeSchema, parse, parseSchema } from "./codec.js";
+import { AuthError, UnexpectedError, ValidationError, } from "./errors/index.js";
+import { RemoteError } from "./errors/RemoteError.js";
+import { logger } from "./globals.js";
+import { TrellisErrorDataSchema } from "./models/trellis/TrellisError.js";
+import { TrellisTasks } from "./tasks.js";
+/**
+ * Safely extract JSON from a NATS message.
+ * The .json() method can throw if the message data is not valid JSON.
+ */
+function safeJson(msg) {
+    return Result.try(() => msg.json());
+}
+function base64urlEncode(data) {
+    const b64 = btoa(String.fromCharCode(...data));
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64urlDecode(s) {
+    const normalized = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padLen = (4 - (normalized.length % 4)) % 4;
+    const padded = normalized + "=".repeat(padLen);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function toArrayBuffer(data) {
+    const buf = data.buffer;
+    if (buf instanceof ArrayBuffer) {
+        return buf.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    }
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    return copy.buffer;
+}
+async function sha256(data) {
+    const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(data));
+    return new Uint8Array(digest);
+}
+function buildProofInput(sessionKey, subject, payloadHash) {
+    const enc = new TextEncoder();
+    const sessionKeyBytes = enc.encode(sessionKey);
+    const subjectBytes = enc.encode(subject);
+    const buf = new Uint8Array(4 +
+        sessionKeyBytes.length +
+        4 +
+        subjectBytes.length +
+        4 +
+        payloadHash.length);
+    const view = new DataView(buf.buffer);
+    let offset = 0;
+    view.setUint32(offset, sessionKeyBytes.length);
+    offset += 4;
+    buf.set(sessionKeyBytes, offset);
+    offset += sessionKeyBytes.length;
+    view.setUint32(offset, subjectBytes.length);
+    offset += 4;
+    buf.set(subjectBytes, offset);
+    offset += subjectBytes.length;
+    view.setUint32(offset, payloadHash.length);
+    offset += 4;
+    buf.set(payloadHash, offset);
+    return buf;
+}
+const NATS_SUBJECT_TOKEN_FORBIDDEN = /[\u0000\s.*>~]/gu;
+const DEFAULT_NO_RESPONDER_MAX_RETRIES = 2;
+const DEFAULT_NO_RESPONDER_RETRY_MS = 200;
+export class Trellis {
+    constructor(name, // Must be unique for a service
+    nats, auth, opts) {
+        _Trellis_instances.add(this);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "timeout", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "stream", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "nats", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "js", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "auth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "api", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _Trellis_log.set(this, void 0);
+        _Trellis_tasks.set(this, void 0);
+        _Trellis_noResponderMaxRetries.set(this, void 0);
+        _Trellis_noResponderRetryMs.set(this, void 0);
+        _Trellis_authBypassMethods.set(this, void 0);
+        this.name = name;
+        this.nats = nats;
+        this.js = jetstream(this.nats);
+        this.auth = auth;
+        this.api = (opts?.api ?? trellisCoreApi);
+        __classPrivateFieldSet(this, _Trellis_log, (opts?.log ?? logger).child({ lib: "trellis" }), "f");
+        this.timeout = opts?.timeout ?? 3000;
+        this.stream = opts?.stream ?? "trellis";
+        __classPrivateFieldSet(this, _Trellis_noResponderMaxRetries, opts?.noResponderRetry?.maxAttempts ??
+            DEFAULT_NO_RESPONDER_MAX_RETRIES, "f");
+        __classPrivateFieldSet(this, _Trellis_noResponderRetryMs, opts?.noResponderRetry?.baseDelayMs ??
+            DEFAULT_NO_RESPONDER_RETRY_MS, "f");
+        __classPrivateFieldSet(this, _Trellis_authBypassMethods, new Set(opts?.authBypassMethods ?? []), "f");
+        __classPrivateFieldSet(this, _Trellis_tasks, new TrellisTasks({ log: __classPrivateFieldGet(this, _Trellis_log, "f") }), "f");
+    }
+    /**
+     * Returns the underlying NATS connection.
+     */
+    get natsConnection() {
+        return this.nats;
+    }
+    /**
+     * Makes an authenticated request to a Trellis RPC method.
+     *
+     * @template M The specific RPC method being called.
+     * @param method The name of the RPC method to call.
+     * @param input The input data for the method, conforming to its schema.
+     * @param opts Optional request-specific options.
+     * @returns A promise that resolves with a `Result` containing either the method's
+     * output or an error.
+     * @returns A `Result` object:
+     *              ok: A validated reponse of method M
+     *              err: RemoteError | ValidationError | UnexpectedError
+     */
+    // TypeScript hits recursion limits on this generic surface under the app's Svelte check.
+    // The implementation still builds and is exercised by runtime validation below.
+    // @ts-expect-error
+    async request(method, input, opts) {
+        __classPrivateFieldGet(this, _Trellis_log, "f").trace({ method: String(method), input: input }, `Calling ${method.toString()}.`);
+        const ctx = this.api["rpc"][method];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: new Error(`Unknown RPC method '${method.toString()}'. Did you forget to include its API module?`),
+                context: { method: method.toString() },
+            }));
+        }
+        const msg = encodeSchema(ctx.input, input).take();
+        if (isErr(msg)) {
+            return msg;
+        }
+        const subject = this.template(ctx.subject, input).take();
+        if (isErr(subject)) {
+            return subject;
+        }
+        // Start a client span for this RPC request
+        const span = startClientSpan(method, subject);
+        const attempt = async () => {
+            const proof = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_createProof).call(this, subject, msg);
+            const headers = natsHeaders();
+            headers.set("session-key", this.auth.sessionKey);
+            headers.set("proof", proof);
+            // Inject trace context into NATS headers for propagation
+            injectTraceContext(createNatsHeaderCarrier(headers), span);
+            // Attempt request with retry for transient "no responders" errors
+            const requestWithRetry = async () => {
+                for (let retry = 0; retry <= __classPrivateFieldGet(this, _Trellis_noResponderMaxRetries, "f"); retry++) {
+                    const result = await AsyncResult.try(() => this.nats.request(subject, msg, {
+                        headers,
+                        timeout: opts?.timeout ?? this.timeout,
+                    }));
+                    if (result.isOk()) {
+                        return ok((await result).take());
+                    }
+                    const cause = result.error.cause;
+                    const message = cause instanceof Error
+                        ? cause.message
+                        : String(cause);
+                    const isNoResponders = message.includes("no responders");
+                    // If it's a no-responders error and we have retries left, retry
+                    if (isNoResponders && retry < __classPrivateFieldGet(this, _Trellis_noResponderMaxRetries, "f")) {
+                        __classPrivateFieldGet(this, _Trellis_log, "f").debug({ method, subject, retry }, "No responders, retrying...");
+                        await new Promise((r) => setTimeout(r, __classPrivateFieldGet(this, _Trellis_noResponderRetryMs, "f") * (retry + 1)));
+                        continue;
+                    }
+                    // Final attempt failed or non-retryable error
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method, subject, error: message }, "NATS request failed");
+                    const isNatsPermission = message.includes("Permissions Violation");
+                    const reason = isNatsPermission
+                        ? `Permission denied. You need one of these capabilities: ${ctx.callerCapabilities.join(", ")}`
+                        : message;
+                    return err(new UnexpectedError({
+                        cause,
+                        context: {
+                            method,
+                            subject,
+                            reason,
+                            requiredCapabilities: ctx.callerCapabilities,
+                            noResponders: isNoResponders,
+                        },
+                    }));
+                }
+                // Should be unreachable, but TypeScript needs explicit return
+                return err(new UnexpectedError({
+                    context: { method, subject, reason: "retry loop exhausted" },
+                }));
+            };
+            const msgResult = await requestWithRetry();
+            const m = msgResult.take();
+            if (isErr(m)) {
+                return m;
+            }
+            if (m.headers?.get("status") === "error") {
+                const json = safeJson(m).take();
+                if (isErr(json)) {
+                    return json;
+                }
+                const error = parse(TrellisErrorDataSchema, json).take();
+                if (isErr(error)) {
+                    return error;
+                }
+                return err(new RemoteError({ error }));
+            }
+            const json = safeJson(m).take();
+            if (isErr(json)) {
+                return json;
+            }
+            const outputResult = parseSchema(ctx.output, json);
+            if (outputResult.isErr()) {
+                return outputResult;
+            }
+            const output = outputResult.take();
+            return ok(output);
+        };
+        return withSpanAsync(span, async () => {
+            try {
+                const result = await attempt();
+                const value = result.take();
+                if (isErr(value)) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: value.error.message,
+                    });
+                }
+                else {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                }
+                return result;
+            }
+            catch (cause) {
+                const unexpected = new UnexpectedError({ cause });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: unexpected.message,
+                });
+                span.recordException(unexpected);
+                return err(unexpected);
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /*
+     * Mount a handler to process requests made to a specific Trellis API
+     */
+    async mount(method, fn) {
+        __classPrivateFieldGet(this, _Trellis_tasks, "f").add(method, __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_handleRPC).call(this, method, fn));
+    }
+    async publish(event, data) {
+        const ctx = this.api["events"][event];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: new Error(`Unknown event '${event.toString()}'. Did you forget to include its API module?`),
+                context: { event: event.toString() },
+            }));
+        }
+        const subject = this.template(ctx.subject, data).take();
+        if (isErr(subject)) {
+            logger.error({ err: subject.error }, "Failed to template event.");
+            return subject;
+        }
+        const msg = encodeSchema(ctx.event, {
+            ...data,
+            header: {
+                id: ulid(),
+                time: new Date().toISOString(),
+            },
+        }).take();
+        if (isErr(msg)) {
+            logger.error({ err: msg.error }, "Failed to encode event.");
+            return msg;
+        }
+        logger.trace({ subject }, `Publishing ${event.toString()} event.`);
+        await this.js.publish(subject, msg);
+        return ok(undefined);
+    }
+    async event(event, subjectData, fn) {
+        const ctx = this.api["events"][event];
+        if (!ctx) {
+            return err(new UnexpectedError({
+                cause: new Error(`Unknown event '${event.toString()}'. Did you forget to include its API module?`),
+                context: { event: event.toString() },
+            }));
+        }
+        const jsm = await jetstreamManager(this.nats);
+        const subject = this.template(ctx.subject, subjectData, true).take();
+        if (isErr(subject))
+            return subject;
+        const consumerName = `${this.name}-${event.replaceAll(".", "_")}`;
+        const addResult = await AsyncResult.try(() => jsm.consumers.add(this.stream, {
+            durable_name: consumerName,
+            ack_policy: "explicit",
+            deliver_policy: "all",
+            filter_subjects: [subject],
+        }));
+        // If add failed (consumer already exists), try to get existing consumer info
+        const consumerInfoResult = addResult.isOk()
+            ? addResult
+            : await AsyncResult.try(() => jsm.consumers.info(this.stream, consumerName));
+        const info = consumerInfoResult.take();
+        if (isErr(info))
+            return info;
+        const consumer = this.js.consumers.getConsumerFromInfo(info);
+        __classPrivateFieldGet(this, _Trellis_tasks, "f").add(event, __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_handleEvent).call(this, event, consumer, fn));
+        return ok(undefined);
+    }
+    wait() {
+        return __classPrivateFieldGet(this, _Trellis_tasks, "f").wait();
+    }
+    // FIXME: If are validating things twice in most cases...
+    template(subject, data, allowWildcards = false) {
+        // Find all template placeholders and check if values exist
+        const placeholders = subject.match(/\{([^}]+)\}/g) || [];
+        for (const placeholder of placeholders) {
+            const key = placeholder.slice(1, -1); // Remove { and }
+            const value = Pointer.Get(data, key);
+            if ((value === undefined || value === null) && !allowWildcards) {
+                return err(new ValidationError({
+                    errors: [
+                        {
+                            path: key,
+                            message: "Missing required data for subject template",
+                        },
+                    ],
+                    context: { key },
+                }));
+            }
+        }
+        const result = subject.replace(/\{([^}]+)\}/g, (_, key) => {
+            const value = Pointer.Get(data, key);
+            if (allowWildcards && value === "*") {
+                return "*";
+            }
+            if (allowWildcards && (value === undefined || value === null)) {
+                return "*";
+            }
+            return __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_escapeSubjectToken).call(this, `${value}`);
+        });
+        return ok(result);
+    }
+}
+_Trellis_log = new WeakMap(), _Trellis_tasks = new WeakMap(), _Trellis_noResponderMaxRetries = new WeakMap(), _Trellis_noResponderRetryMs = new WeakMap(), _Trellis_authBypassMethods = new WeakMap(), _Trellis_instances = new WeakSet(), _Trellis_handleRPC = function _Trellis_handleRPC(method, fn, subjectData = {}) {
+    // Get API details
+    const ctx = this.api["rpc"][method];
+    const subject = this.template(ctx.subject, subjectData, true).take();
+    if (isErr(subject)) {
+        return AsyncResult.lift(subject);
+    }
+    __classPrivateFieldGet(this, _Trellis_log, "f").info({ method: String(method) }, `Mounting ${method.toString()} RPC handler`);
+    const sub = this.nats.subscribe(subject);
+    return AsyncResult.try(async () => {
+        for await (const msg of sub) {
+            const resultPromise = await __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_processRPCMessage).call(this, method, ctx, msg, fn);
+            const result = resultPromise.take();
+            if (isErr(result)) {
+                __classPrivateFieldGet(this, _Trellis_instances, "m", _Trellis_respondWithError).call(this, msg, result.error);
+                continue;
+            }
+            msg.respond(result);
+        }
+    });
+}, _Trellis_processRPCMessage = async function _Trellis_processRPCMessage(method, ctx, msg, fn) {
+    __classPrivateFieldGet(this, _Trellis_log, "f").debug({ method: String(method), subject: msg.subject }, "Processing RPC message");
+    // Extract trace context from incoming NATS headers
+    const parentContext = extractTraceContext(createNatsHeaderCarrier({
+        get: (k) => msg.headers?.get(k) ?? undefined,
+        set: () => { }, // Server doesn't need to set headers on incoming messages
+    }));
+    // Start a server span for this RPC handler
+    const span = startServerSpan(method, msg.subject, parentContext);
+    // Execute the handler within the span's context
+    return withSpanAsync(span, async () => {
+        const execute = async () => {
+            const jsonData = safeJson(msg).take();
+            if (isErr(jsonData)) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method, error: jsonData.error.message }, "Failed to parse JSON");
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Failed to parse JSON",
+                });
+                return jsonData;
+            }
+            const parsedInput = parseSchema(ctx.input, jsonData).take();
+            if (isErr(parsedInput)) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Input validation failed",
+                });
+                return parsedInput;
+            }
+            let user;
+            const callerSessionKey = msg.headers?.get("session-key") ?? "";
+            const authRequired = ctx.authRequired ?? true;
+            if (!authRequired || __classPrivateFieldGet(this, _Trellis_authBypassMethods, "f").has(method)) {
+                user = {
+                    id: "system",
+                    origin: "trellis",
+                    active: true,
+                    name: "System",
+                    email: "system@trellis.internal",
+                    capabilities: ["service"],
+                };
+            }
+            else {
+                const sessionKey = msg.headers?.get("session-key");
+                const proof = msg.headers?.get("proof");
+                if (!sessionKey) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method }, "Missing session-key header");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Missing session-key",
+                    });
+                    return err(new AuthError({ reason: "missing_session_key" }));
+                }
+                if (!proof) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({ method }, "Missing proof in request");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Missing proof",
+                    });
+                    return err(new AuthError({ reason: "missing_proof" }));
+                }
+                // Verify proof signature locally using the raw request bytes we received.
+                const payloadBytes = msg.data ?? new Uint8Array();
+                const payloadHash = await sha256(payloadBytes);
+                const proofInput = buildProofInput(sessionKey, msg.subject, payloadHash);
+                const digest = await sha256(proofInput);
+                const verifyResult = await AsyncResult.try(async () => {
+                    const publicKeyRaw = base64urlDecode(sessionKey);
+                    const pub = await crypto.subtle.importKey("raw", toArrayBuffer(publicKeyRaw), { name: "Ed25519" }, true, ["verify"]);
+                    return crypto.subtle.verify({ name: "Ed25519" }, pub, toArrayBuffer(base64urlDecode(proof)), toArrayBuffer(digest));
+                });
+                const signatureOk = verifyResult.isOk() &&
+                    (await verifyResult).take() === true;
+                if (!signatureOk) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Invalid signature",
+                    });
+                    return err(new AuthError({
+                        reason: "invalid_signature",
+                        context: { sessionKey },
+                    }));
+                }
+                const authResult = await this.request("Auth.ValidateRequest", {
+                    sessionKey,
+                    proof,
+                    subject: msg.subject,
+                    payloadHash: base64urlEncode(payloadHash),
+                    capabilities: ctx.callerCapabilities,
+                });
+                const auth = authResult.take();
+                if (isErr(auth)) {
+                    __classPrivateFieldGet(this, _Trellis_log, "f").warn({
+                        method,
+                        error: auth.error.message,
+                        errorType: auth.error.name,
+                        remoteError: auth.error instanceof RemoteError
+                            ? auth.error.toSerializable()
+                            : undefined,
+                    }, "Auth.ValidateRequest failed");
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Auth.ValidateRequest failed",
+                    });
+                    return auth;
+                }
+                if (!auth.allowed) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Insufficient permissions",
+                    });
+                    return err(new AuthError({
+                        reason: "insufficient_permissions",
+                        context: {
+                            requiredCapabilities: ctx.callerCapabilities,
+                            userCapabilities: auth.user.capabilities,
+                        },
+                    }));
+                }
+                if (typeof msg.reply !== "string" ||
+                    !msg.reply.startsWith(`${auth.inboxPrefix}.`)) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: "Reply subject mismatch",
+                    });
+                    return err(new AuthError({
+                        reason: "reply_subject_mismatch",
+                        context: { expected: auth.inboxPrefix, actual: msg.reply },
+                    }));
+                }
+                user = auth.user;
+            }
+            // Add user info to span attributes
+            span.setAttribute("user.id", user.id);
+            span.setAttribute("user.origin", user.origin);
+            const handlerResultWrapped = await AsyncResult.try(() => fn(parsedInput, {
+                user,
+                sessionKey: callerSessionKey,
+            }));
+            if (handlerResultWrapped.isErr()) {
+                const error = handlerResultWrapped.error.withContext({ method });
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({
+                    method,
+                    error: error.message,
+                    cause: error.cause instanceof Error
+                        ? { message: error.cause.message, stack: error.cause.stack }
+                        : error.cause,
+                }, "Handler threw unexpectedly.");
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                span.recordException(error);
+                return err(error);
+            }
+            const handlerResult = (await handlerResultWrapped).take();
+            const handlerOutcome = handlerResult.take();
+            if (isErr(handlerOutcome)) {
+                const handlerError = handlerOutcome.error;
+                const error = handlerError instanceof UnexpectedError ||
+                    handlerError instanceof AuthError ||
+                    handlerError instanceof ValidationError
+                    ? handlerError
+                    : new UnexpectedError({ cause: handlerError });
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({
+                    method,
+                    error: error.message,
+                    errorType: error.name,
+                    cause: error.cause instanceof Error
+                        ? { message: error.cause.message, stack: error.cause.stack }
+                        : error.cause,
+                }, "Handler returned error.");
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                return err(error);
+            }
+            const encoded = encodeSchema(ctx.output, handlerOutcome).take();
+            if (isErr(encoded)) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Output encoding failed",
+                });
+                return encoded;
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            return ok(encoded);
+        };
+        const result = await execute();
+        span.end();
+        return result;
+    });
+}, _Trellis_respondWithError = function _Trellis_respondWithError(msg, error) {
+    const trellisError = error instanceof UnexpectedError ||
+        error instanceof AuthError ||
+        error instanceof ValidationError ||
+        error instanceof RemoteError
+        ? error
+        : new UnexpectedError({ cause: error });
+    __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: trellisError.toSerializable() }, "RPC error");
+    const errorData = trellisError.toSerializable();
+    const hdrs = natsHeaders();
+    hdrs.set("status", "error");
+    const serialized = Result.try(() => JSON.stringify(errorData));
+    if (serialized.isErr()) {
+        __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: serialized.error }, "Failed to serialize error response");
+        msg.respond('{"type":"UnexpectedError","message":"Failed to serialize error"}', { headers: hdrs });
+        return;
+    }
+    msg.respond(serialized.take(), { headers: hdrs });
+}, _Trellis_handleEvent = function _Trellis_handleEvent(event, consumer, fn) {
+    const ctx = this.api["events"][event];
+    return AsyncResult.try(async () => {
+        const msgs = await consumer.consume();
+        for await (const msg of msgs) {
+            const jsonData = Result.try(() => msg.json());
+            if (jsonData.isErr()) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: jsonData.error }, "Event parse failed");
+                msg.term();
+                continue;
+            }
+            const m = parseSchema(ctx.event, jsonData.take()).take();
+            if (isErr(m)) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: m.error }, "Event validation failed");
+                msg.term();
+                continue;
+            }
+            const handlerResult = await AsyncResult.lift(fn(m));
+            if (handlerResult.isErr()) {
+                __classPrivateFieldGet(this, _Trellis_log, "f").error({ error: handlerResult.error.toSerializable(), event, subject: msg.subject }, "Event handler failed");
+                msg.nak();
+                continue;
+            }
+            msg.ack();
+        }
+    });
+}, _Trellis_escapeSubjectToken = function _Trellis_escapeSubjectToken(token) {
+    const out = token.replace(NATS_SUBJECT_TOKEN_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    // Protect stapRet with $ due to NATS internal use of it
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}, _Trellis_createProof = async function _Trellis_createProof(subject, payload) {
+    const payloadBytes = new TextEncoder().encode(payload);
+    const payloadHash = await sha256(payloadBytes);
+    const input = buildProofInput(this.auth.sessionKey, subject, payloadHash);
+    const digest = await sha256(input);
+    const sigBytes = await this.auth.sign(digest);
+    return base64urlEncode(sigBytes);
+};
+export class TrellisServer extends Trellis {
+    constructor(name, nats, auth, opts) {
+        super(name, nats, auth, opts);
+        _TrellisServer_version.set(this, void 0);
+        _TrellisServer_log.set(this, void 0);
+        __classPrivateFieldSet(this, _TrellisServer_version, opts?.version, "f");
+        __classPrivateFieldSet(this, _TrellisServer_log, (opts?.log ?? logger).child({ lib: "trellis-server" }), "f");
+    }
+    /**
+     * Creates an authenticated TrellisServer instance.
+     *
+     * Services connect to NATS using the session-key auth flow (see ADR):
+     * - NATS `auth_token` (aka `token`) is a JSON string `{ v: 1, sessionKey, iat, sig }`
+     * - `sig` signs SHA-256(`nats-connect:${iat}`) with the session key
+     * - `inboxPrefix` MUST be `_INBOX.${sessionKey.slice(0, 16)}`
+     *
+     * @param name Unique name for this service
+     * @param nats Existing NATS connection (already authenticated)
+     * @param auth Service session-key credentials
+     * @param opts Optional server options
+     * @returns An authenticated TrellisServer instance
+     */
+    static create(name, nats, auth, opts) {
+        return new TrellisServer(name, nats, auth, opts);
+    }
+    /**
+     * Stops the server by clearing refresh timers and draining the NATS connection.
+     * Draining allows in-flight messages to complete before closing the connection.
+     * This method is idempotent and can be called multiple times safely.
+     */
+    async stop() {
+        // Only drain if the connection is not already closed
+        if (!this.natsConnection.isClosed()) {
+            await this.natsConnection.drain();
+        }
+    }
+}
+_TrellisServer_version = new WeakMap(), _TrellisServer_log = new WeakMap();