@absol-labs/agent 0.4.0 → 0.6.0

package/src/gateway/server-entry.ts

@@ -0,0 +1,38 @@
+import { startCallerAuthGatewayServerFromEnv } from "./http-server.js";
+
+/**
+ * Runnable entrypoint for the reference caller-auth gateway (metrik-agent#63).
+ * Reads all configuration from the environment (see
+ * {@link parseCallerAuthGatewayEnvConfig}) and refuses to start if required
+ * config is missing (fail-closed).
+ *
+ * Start with: `pnpm gateway` (or `node dist/gateway/server-entry.js`).
+ */
+async function main(): Promise<void> {
+  const server = await startCallerAuthGatewayServerFromEnv();
+  const host = process.env.METRIK_GATEWAY_HOST ?? "0.0.0.0";
+  console.error(
+    `[metrik-caller-auth-gateway] listening on http://${host}:${server.boundPort}`,
+  );
+
+  const shutdown = (signal: string) => {
+    console.error(
+      `[metrik-caller-auth-gateway] ${signal} received — shutting down`,
+    );
+    server
+      .close()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+main().catch((error) => {
+  console.error(
+    error instanceof Error
+      ? error.message
+      : "failed to start caller-auth gateway server",
+  );
+  process.exit(1);
+});

package/src/index.ts

@@ -49,6 +49,8 @@ export {
   DEFAULT_METRIK_REGISTRY_URL,
   DEMO_SEED_LISTING,
   DEMO_SEED_SERVICE_REF,
+  LIVE_DATA_SEED_LISTING,
+  LIVE_DATA_SEED_SERVICE_REF,
   discoverServices,
   type DiscoverServicesOptions,
   type ServiceListing,
@@ -113,6 +115,21 @@ export {
   type WalletBackedAgentClient,
 } from "./wallet/provider.js";
 
+export {
+  UnsupportedFaucetChainError,
+  faucetHint,
+  getWalletBalances,
+  requestCdpFaucet,
+  type BalanceReader,
+  type CdpFaucetClientLike,
+  type FaucetHint,
+  type FaucetRequestResult,
+  type FaucetToken,
+  type GetWalletBalancesOptions,
+  type RequestCdpFaucetOptions,
+  type WalletBalances,
+} from "./wallet/lifecycle.js";
+
 export {
   ReclaimConsumerProofService,
   ResponseProofUnavailableError,
@@ -154,6 +171,75 @@ export {
   type WireDeliveryReceipt,
 } from "./zktls/t2-delivery-proof.js";
 
+export {
+  CAPABILITY_HEADER_NAME,
+  DEFAULT_CAPABILITY_TTL_SECONDS,
+  InvalidCapabilityHeaderError,
+  buildInvocationCapabilityTypedData,
+  createInvocationCapabilityEip712Domain,
+  decodeCapabilityHeader,
+  encodeCapabilityHeader,
+  generateCapabilityNonce,
+  hashInvocationPath,
+  httpMethodSchema,
+  invocationCapabilityDomainName,
+  invocationCapabilityDomainVersion,
+  invocationCapabilitySchema,
+  invocationCapabilityTypedData,
+  normalizeInvocationPath,
+  recoverInvocationCapabilitySigner,
+  signInvocationCapability,
+  signedInvocationCapabilitySchema,
+  type HttpMethod,
+  type InvocationCapability,
+  type InvocationCapabilityDomainInput,
+  type SignedInvocationCapability,
+} from "./capability/invocation-capability.js";
+
+export {
+  CallerAuthGateway,
+  InMemoryNonceReplayCache,
+  UnknownStreamGatewayError,
+  createSdkStreamReader,
+  type CallerAuthDecision,
+  type CallerAuthDenialReason,
+  type CallerAuthGatewayConfig,
+  type CallerAuthRequestInput,
+  type GatewayStreamView,
+  type NonceReplayCache,
+  type StreamReader,
+} from "./gateway/caller-auth-gateway.js";
+
+export {
+  createCallerAuthGatewayServer,
+  parseCallerAuthGatewayEnvConfig,
+  startCallerAuthGatewayServerFromEnv,
+  type CallerAuthGatewayEnvConfig,
+  type CallerAuthGatewayServer,
+  type CallerAuthGatewayServerConfig,
+} from "./gateway/http-server.js";
+
+export {
+  InvokeBuyerMismatchError,
+  InvokeAccessUrlError,
+  InvokePathError,
+  InvokeServiceRefMismatchError,
+  InvokeStreamExpiredError,
+  InvokeStreamNotActiveError,
+  capabilityFor,
+  createSdkInvokeStreamReader,
+  invoke,
+  invokeWithT2DeliveryProof,
+  type CapabilityForOptions,
+  type InvokeOptions,
+  type InvokeResult,
+  type InvokeServiceInput,
+  type InvokeStreamReader,
+  type InvokeStreamView,
+  type InvokeWithT2DeliveryProofOptions,
+  type InvokeWithT2DeliveryProofResult,
+} from "./sdk/invoke.js";
+
 // Framework adapters are NOT re-exported from this top-level barrel on purpose.
 // Some of them (notably the Coinbase AgentKit adapter) pull heavy optional
 // dependency graphs, so importing "@absol-labs/agent" must stay light and load

package/src/mcp/server.ts

@@ -171,13 +171,13 @@ export const METRIK_MCP_TOOLS: readonly McpToolSpec[] = [
   {
     name: "check_stream_status",
     description:
-      "Read a stream's live status, accrued amount, and claimable/reclaimable balances.",
+      "Read a stream's live status, accrued amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
     movesFunds: false,
   },
   {
     name: "reclaim_unspent",
     description:
-      "Close a stream and reclaim unspent funds to the buyer after failure or completion.",
+      "Close a stream and reclaim unspent funds to the buyer. V2 reclaim follows checkpoint finalization or escape-window rules.",
     movesFunds: true,
   },
   {
@@ -923,6 +923,8 @@ function serializeServiceListing(
     serviceRef: listing.serviceRef,
     operator: listing.operator,
     publicUrl: listing.publicUrl,
+    access: listing.access,
+    accessUrl: listing.accessUrl,
     category: listing.category,
     ...(listing.targetMetadata === undefined
       ? {}

package/src/sdk/invoke.ts

@@ -0,0 +1,495 @@
+import {
+  deriveServiceRef,
+  recoverServiceBindingSigner,
+  recoverServiceDescriptorSigner,
+  signedServiceBindingSchema,
+  signedServiceDescriptorSchema,
+  type DeliveryReceiptDomainInput,
+} from "@absol-labs/shared";
+import { MetrikClient } from "@absol-labs/sdk";
+import type { Address, Hex, LocalAccount } from "viem";
+
+import type { ServiceListing } from "../discovery/registry.js";
+
+import {
+  buildT2DeliveryProofSubmission,
+  type BuildT2DeliveryProofResult,
+  type DeliveryProofAttestor,
+  type PaidRouteRequestSpec,
+} from "../zktls/t2-delivery-proof.js";
+import {
+  CAPABILITY_HEADER_NAME,
+  encodeCapabilityHeader,
+  generateCapabilityNonce,
+  hashInvocationPath,
+  signInvocationCapability,
+  type HttpMethod,
+  type InvocationCapability,
+  type InvocationCapabilityDomainInput,
+  type SignedInvocationCapability,
+  DEFAULT_CAPABILITY_TTL_SECONDS,
+} from "../capability/invocation-capability.js";
+
+/**
+ * Buyer half of the pay -> use loop (metrik-agent#64, impl of #62 part 2/2).
+ *
+ * After `hire()`/`openStream()`, an agent calls the purchased service directly
+ * with no out-of-band credentials: `invoke()` loads the stream, builds+signs
+ * a minimal-scope `InvocationCapability`, attaches it, and calls the
+ * gateway-fronted service (`../gateway/caller-auth-gateway.ts`).
+ */
+
+/** The subset of `MetrikClient.getStreamV2` this module needs. Duck-typed so any real SDK client satisfies it. */
+export interface InvokeStreamView {
+  readonly buyer: Address;
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly status: "active" | "closed";
+  readonly expiresAt: number;
+}
+
+export interface InvokeStreamReader {
+  getStreamV2(streamId: Hex): Promise<InvokeStreamView>;
+}
+
+/** Default `InvokeStreamReader`: a real, read-only `MetrikClient` (no wallet, no writes). */
+export function createSdkInvokeStreamReader(options: {
+  readonly escrowAddress: Address;
+  readonly rpcUrl: string;
+}): InvokeStreamReader {
+  const metrik = MetrikClient.baseSepolia({
+    escrow: options.escrowAddress,
+    rpcUrl: options.rpcUrl,
+  });
+  return {
+    async getStreamV2(streamId) {
+      const stream = await metrik.getStreamV2(streamId);
+      return {
+        buyer: stream.buyer,
+        operator: stream.operator,
+        serviceRef: stream.serviceRef,
+        status: stream.status,
+        expiresAt: stream.expiresAt,
+      };
+    },
+  };
+}
+
+export class InvokeStreamNotActiveError extends Error {
+  constructor(streamId: Hex, status: string) {
+    super(`stream ${streamId} is not active (status=${status})`);
+    this.name = "InvokeStreamNotActiveError";
+  }
+}
+
+export class InvokeStreamExpiredError extends Error {
+  constructor(streamId: Hex, expiresAt: number) {
+    super(`stream ${streamId} expired at ${expiresAt}`);
+    this.name = "InvokeStreamExpiredError";
+  }
+}
+
+export class InvokeBuyerMismatchError extends Error {
+  constructor(streamId: Hex, streamBuyer: Address, signer: Address) {
+    super(
+      `stream ${streamId} buyer ${streamBuyer} does not match the signing account ${signer}`,
+    );
+    this.name = "InvokeBuyerMismatchError";
+  }
+}
+
+export class InvokeServiceRefMismatchError extends Error {
+  constructor(streamRef: Hex, listingRef: Hex) {
+    super(
+      `stream serviceRef ${streamRef} does not match listing serviceRef ${listingRef}`,
+    );
+    this.name = "InvokeServiceRefMismatchError";
+  }
+}
+
+export class InvokeAccessUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvokeAccessUrlError";
+  }
+}
+
+export class InvokePathError extends Error {
+  constructor(path: string) {
+    super(
+      `invocation path must be origin-relative and start with one slash: ${path}`,
+    );
+    this.name = "InvokePathError";
+  }
+}
+
+export interface CapabilityForOptions {
+  readonly buyer: LocalAccount;
+  readonly domain: InvocationCapabilityDomainInput;
+  readonly serviceRef: Hex;
+  /** Default {@link DEFAULT_CAPABILITY_TTL_SECONDS}. */
+  readonly ttlSeconds?: number;
+  /** Default a fresh random nonce. */
+  readonly nonce?: Hex;
+  /** Default `Math.floor(Date.now() / 1000)`. Injectable for tests. */
+  readonly nowSeconds?: number;
+}
+
+/**
+ * Builds and signs a minimal-scope `InvocationCapability` for one
+ * `method`+`path` call against `streamId`, WITHOUT touching the network.
+ */
+export async function capabilityFor(
+  streamId: Hex,
+  request: { readonly method: HttpMethod; readonly path: string },
+  options: CapabilityForOptions,
+): Promise<SignedInvocationCapability> {
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const capability: InvocationCapability = {
+    streamId,
+    buyer: options.buyer.address,
+    serviceRef: options.serviceRef,
+    method: request.method,
+    pathHash: hashInvocationPath(request.path),
+    nonce: options.nonce ?? generateCapabilityNonce(),
+    expiry: nowSeconds + (options.ttlSeconds ?? DEFAULT_CAPABILITY_TTL_SECONDS),
+  };
+  const signature = await signInvocationCapability(
+    capability,
+    options.domain,
+    options.buyer,
+  );
+  return { ...capability, signature };
+}
+
+export interface InvokeServiceInput {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: NonNullable<RequestInit["body"]>;
+}
+
+export interface InvokeOptions {
+  /** Reads the stream's current serviceRef/operator/status/expiry. Real default: a `MetrikClient` instance. */
+  readonly streamReader: InvokeStreamReader;
+  /** The buyer's own wallet - signs the capability, never broadcasts a transaction. */
+  readonly buyer: LocalAccount;
+  /** `{chainId, verifyingContract}` - the `StreamEscrowV2` the stream settles on. */
+  readonly domain: InvocationCapabilityDomainInput;
+  /** Preferred: a cryptographically verified result from discoverServices(). */
+  readonly listing?: ServiceListing;
+  /** @deprecated Manual escape hatch. Verified listing routing is safer. */
+  readonly serviceBaseUrl?: string;
+  readonly ttlSeconds?: number;
+  readonly nonce?: Hex;
+  readonly nowSeconds?: number;
+  /** Injectable `fetch` implementation, for tests. Default: global `fetch`. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+export interface InvokeResult {
+  readonly response: Response;
+  readonly capability: SignedInvocationCapability;
+  readonly stream: InvokeStreamView;
+}
+
+/**
+ * `open()` -> `invoke()`: loads the stream, builds+signs a capability scoped
+ * to exactly this `method`+`path`, and calls the gateway-fronted service.
+ * Fails closed BEFORE any network call to the service if the stream is not
+ * active, is expired, or does not belong to the signing account.
+ */
+export async function invoke(
+  streamId: Hex,
+  request: InvokeServiceInput,
+  options: InvokeOptions,
+): Promise<InvokeResult> {
+  assertOriginRelativePath(request.path);
+  const stream = await options.streamReader.getStreamV2(streamId);
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+
+  if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+    throw new InvokeBuyerMismatchError(
+      streamId,
+      stream.buyer,
+      options.buyer.address,
+    );
+  }
+  if (stream.status !== "active") {
+    throw new InvokeStreamNotActiveError(streamId, stream.status);
+  }
+  if (nowSeconds >= stream.expiresAt) {
+    throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+  }
+
+  const serviceBaseUrl = await resolveInvocationBaseUrl(
+    stream.serviceRef,
+    options,
+  );
+
+  const capability = await capabilityFor(streamId, request, {
+    buyer: options.buyer,
+    domain: options.domain,
+    serviceRef: stream.serviceRef,
+    ...(options.ttlSeconds === undefined
+      ? {}
+      : { ttlSeconds: options.ttlSeconds }),
+    ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+    nowSeconds,
+  });
+
+  const header = encodeCapabilityHeader(capability);
+  const url = new URL(
+    request.path,
+    ensureTrailingSlash(serviceBaseUrl),
+  ).toString();
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(url, {
+    method: request.method,
+    headers: {
+      ...(request.headers ?? {}),
+      [CAPABILITY_HEADER_NAME]: header,
+    },
+    ...(request.body === undefined ? {} : { body: request.body }),
+  });
+
+  return { response, capability, stream };
+}
+
+// ── T2 integration: usage + delivery proof as one action ───────────────────
+
+export interface InvokeWithT2DeliveryProofOptions {
+  readonly streamReader: InvokeStreamReader;
+  readonly buyer: LocalAccount;
+  readonly domain: DeliveryReceiptDomainInput;
+  /** The T2 paid-route spec (absolute `url`, `responseMatches`, nonce injection point, ...). */
+  readonly request: PaidRouteRequestSpec;
+  /** Verified listing. Gated T2 is rejected until proof-target pinning supports it. */
+  readonly listing?: ServiceListing;
+  /** Which billing interval this delivery proof covers. */
+  readonly intervalIndex: bigint;
+  /** Oracle-issued anti-replay nonce, from `GET /delivery/nonce`. */
+  readonly nonce: Hex;
+  readonly issuedAt?: number;
+  readonly mandateId?: string;
+  readonly attestor?: DeliveryProofAttestor;
+  readonly capabilityTtlSeconds?: number;
+  readonly capabilityNonce?: Hex;
+  readonly nowSeconds?: number;
+}
+
+export interface InvokeWithT2DeliveryProofResult {
+  readonly capability: SignedInvocationCapability;
+  readonly stream: InvokeStreamView;
+  readonly t2: BuildT2DeliveryProofResult;
+}
+
+/**
+ * The T2 variant of `invoke()`: the SAME capability-authorized call the
+ * gateway serves is what the buyer's Reclaim attestor proves, so usage and
+ * delivery proof are one action (issue #63's "the invocation IS the
+ * delivery"). Attaches the `InvocationCapability` header to the exact request
+ * `buildT2DeliveryProofSubmission` proves via zkTLS, then signs the resulting
+ * `DeliveryReceipt` - identical evidence chain as the plain T2 flow, just
+ * capability-gated at the gateway.
+ */
+export async function invokeWithT2DeliveryProof(
+  streamId: Hex,
+  options: InvokeWithT2DeliveryProofOptions,
+): Promise<InvokeWithT2DeliveryProofResult> {
+  const stream = await options.streamReader.getStreamV2(streamId);
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+
+  if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+    throw new InvokeBuyerMismatchError(
+      streamId,
+      stream.buyer,
+      options.buyer.address,
+    );
+  }
+  if (stream.status !== "active") {
+    throw new InvokeStreamNotActiveError(streamId, stream.status);
+  }
+  if (nowSeconds >= stream.expiresAt) {
+    throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+  }
+
+  if (options.listing !== undefined) {
+    const route = await verifyListingRoute(stream.serviceRef, options.listing);
+    if (route.access === "gated") {
+      throw new InvokeAccessUrlError(
+        "consumer-attested T2 invocation is not supported for gated listings",
+      );
+    }
+    const requestOrigin = new URL(options.request.url).origin;
+    const signedOrigin = new URL(route.url).origin;
+    if (requestOrigin !== signedOrigin) {
+      throw new InvokeAccessUrlError(
+        `T2 request origin ${requestOrigin} does not match signed listing origin ${signedOrigin}`,
+      );
+    }
+  }
+
+  const path = new URL(options.request.url).pathname;
+  const capability = await capabilityFor(
+    streamId,
+    { method: options.request.method ?? "GET", path },
+    {
+      buyer: options.buyer,
+      domain: options.domain,
+      serviceRef: stream.serviceRef,
+      ...(options.capabilityTtlSeconds === undefined
+        ? {}
+        : { ttlSeconds: options.capabilityTtlSeconds }),
+      ...(options.capabilityNonce === undefined
+        ? {}
+        : { nonce: options.capabilityNonce }),
+      nowSeconds,
+    },
+  );
+
+  const requestWithCapability: PaidRouteRequestSpec = {
+    ...options.request,
+    headers: {
+      ...(options.request.headers ?? {}),
+      [CAPABILITY_HEADER_NAME]: encodeCapabilityHeader(capability),
+    },
+  };
+
+  const t2 = await buildT2DeliveryProofSubmission({
+    streamId,
+    operator: stream.operator,
+    serviceRef: stream.serviceRef,
+    intervalIndex: options.intervalIndex,
+    nonce: options.nonce,
+    buyer: options.buyer,
+    domain: options.domain,
+    request: requestWithCapability,
+    ...(options.issuedAt === undefined ? {} : { issuedAt: options.issuedAt }),
+    ...(options.mandateId === undefined
+      ? {}
+      : { mandateId: options.mandateId }),
+    ...(options.attestor === undefined ? {} : { attestor: options.attestor }),
+  });
+
+  return { capability, stream, t2 };
+}
+
+async function resolveInvocationBaseUrl(
+  streamRef: Hex,
+  options: InvokeOptions,
+): Promise<string> {
+  if (options.listing !== undefined) {
+    return (await verifyListingRoute(streamRef, options.listing)).url;
+  }
+  if (options.serviceBaseUrl === undefined) {
+    throw new InvokeAccessUrlError(
+      "a verified listing is required (or pass deprecated serviceBaseUrl explicitly)",
+    );
+  }
+  return requireHttpUrl(options.serviceBaseUrl, "serviceBaseUrl");
+}
+
+async function verifyListingRoute(
+  streamRef: Hex,
+  listing: ServiceListing,
+): Promise<{ readonly access: "public" | "gated"; readonly url: string }> {
+  if (streamRef.toLowerCase() !== listing.serviceRef.toLowerCase()) {
+    throw new InvokeServiceRefMismatchError(streamRef, listing.serviceRef);
+  }
+
+  const descriptor = signedServiceDescriptorSchema.safeParse(listing.signed);
+  if (descriptor.success) {
+    const signed = descriptor.data;
+    const derived = deriveServiceRef(signed.descriptor);
+    const signer = await recoverServiceDescriptorSigner(
+      signed.descriptor,
+      signed.signature as Hex,
+    );
+    const access = signed.descriptor.access ?? "public";
+    const url =
+      access === "gated"
+        ? signed.descriptor.callerAuth?.accessUrl
+        : (signed.descriptor.interface?.baseUrl ?? signed.descriptor.publicUrl);
+    if (
+      derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signer === null ||
+      signer.toLowerCase() !== signed.descriptor.operator.toLowerCase() ||
+      listing.operator.toLowerCase() !==
+        signed.descriptor.operator.toLowerCase() ||
+      listing.publicUrl !== signed.descriptor.publicUrl ||
+      listing.access !== access ||
+      url === undefined ||
+      listing.accessUrl !== url
+    ) {
+      throw new InvokeAccessUrlError(
+        "listing does not match its verified signed descriptor",
+      );
+    }
+    const verifiedUrl = requireHttpUrl(url, "signed listing access URL");
+    if (access === "gated" && new URL(verifiedUrl).protocol !== "https:") {
+      throw new InvokeAccessUrlError(
+        "signed gated listing access URL must use HTTPS",
+      );
+    }
+    return { access, url: verifiedUrl };
+  }
+
+  const binding = signedServiceBindingSchema.safeParse(listing.signed);
+  if (binding.success) {
+    const signed = binding.data;
+    const derived = deriveServiceRef(signed.binding);
+    const signer = await recoverServiceBindingSigner(
+      signed.binding,
+      signed.signature as Hex,
+    );
+    if (
+      derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signer === null ||
+      signer.toLowerCase() !== signed.binding.operator.toLowerCase() ||
+      listing.operator.toLowerCase() !==
+        signed.binding.operator.toLowerCase() ||
+      listing.publicUrl !== signed.binding.publicUrl ||
+      listing.access !== "public" ||
+      listing.accessUrl !== signed.binding.publicUrl
+    ) {
+      throw new InvokeAccessUrlError(
+        "listing does not match its verified signed binding",
+      );
+    }
+    return {
+      access: "public",
+      url: requireHttpUrl(
+        signed.binding.publicUrl,
+        "signed listing access URL",
+      ),
+    };
+  }
+
+  throw new InvokeAccessUrlError("listing signed record is invalid");
+}
+
+function requireHttpUrl(value: string, label: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+  }
+  return parsed.toString();
+}
+
+function assertOriginRelativePath(path: string): void {
+  if (!path.startsWith("/") || path.startsWith("//") || path.includes("#")) {
+    throw new InvokePathError(path);
+  }
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}