@caracalai/sdk 0.1.2 → 0.1.4-rc.1

package/dist/client.js

@@ -5,34 +5,88 @@
  * Caracal: drop-in bound client wrapping zone, application, subject token, and coordinator.
  */
 import { bind, fromEnvelope, toEnvelope, current } from "./context.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { parse } from "smol-toml";
 import { decodeEnvelope, toHeaders, } from "./envelope.js";
 import { spawn as spawnPrimitive, delegate as delegatePrimitive, delegateToSpawn as delegateToSpawnPrimitive, } from "./primitives.js";
 import { AgentKind } from "./coordinator.js";
+import { OAuthClient } from "@caracalai/oauth";
+const DEFAULT_STS_URL = "http://localhost:8080";
+const DEFAULT_COORDINATOR_URL = "http://localhost:4000";
+const DEFAULT_GATEWAY_URL = "http://localhost:8081";
 export class Caracal {
     config;
     agentStartHooks = [];
     agentEndHooks = [];
     constructor(config) {
         this.config = config;
+        if ((config.subjectToken === undefined) === (config.tokenSource === undefined)) {
+            throw new Error("CaracalConfig requires exactly one of subjectToken or tokenSource");
+        }
         if (config.resources && config.resources.length > 1) {
             this.config = { ...config, resources: sortBindingsLongestFirst(config.resources) };
         }
     }
+    /**
+     * Builds a Caracal client from explicit values, a generated profile, or env.
+     */
+    static connect(opts = {}) {
+        if (opts.clientSecret && Object.keys(opts.clientSecret).length > 0) {
+            const cs = opts.clientSecret;
+            const missing = [
+                ["coordinatorUrl", cs.coordinatorUrl],
+                ["stsUrl", cs.stsUrl],
+                ["zoneId", cs.zoneId],
+                ["applicationId", cs.applicationId],
+                ["clientSecret", cs.clientSecret],
+                ["resources", cs.resources?.length ? "set" : undefined],
+            ].filter(([, v]) => !v).map(([k]) => k);
+            if (missing.length) {
+                throw new Error(`Caracal.connect: clientSecret missing ${missing.join(", ")}`);
+            }
+            return Caracal.fromClientSecret(cs);
+        }
+        const env = opts.env ?? process.env;
+        if (opts.configPath)
+            return Caracal.fromConfig(opts.configPath, env);
+        const path = resolveProfilePath(env);
+        if (path)
+            return Caracal.fromConfig(path, env);
+        return Caracal.fromEnv(env);
+    }
     static fromEnv(env = process.env) {
-        const url = env.CARACAL_COORDINATOR_URL;
+        const url = serviceUrl(env, "CARACAL_COORDINATOR_URL", DEFAULT_COORDINATOR_URL);
         const zoneId = env.CARACAL_ZONE_ID;
         const applicationId = env.CARACAL_APPLICATION_ID;
         const subjectToken = env.CARACAL_SUBJECT_TOKEN;
-        const gatewayUrl = env.CARACAL_GATEWAY_URL;
+        const stsUrl = stsUrlFromEnv(env);
+        const gatewayUrl = serviceUrl(env, "CARACAL_GATEWAY_URL", DEFAULT_GATEWAY_URL);
         const missing = [
-            ["CARACAL_COORDINATOR_URL", url],
             ["CARACAL_ZONE_ID", zoneId],
             ["CARACAL_APPLICATION_ID", applicationId],
-            ["CARACAL_SUBJECT_TOKEN", subjectToken],
         ].filter(([, v]) => !v).map(([k]) => k);
         if (missing.length) {
             throw new Error(`Caracal.fromEnv: missing ${missing.join(", ")}`);
         }
+        const clientSecret = clientSecretFromEnv(env, zoneId, applicationId);
+        const profileResources = resourcesFromEnv(env, zoneId, applicationId);
+        const resources = profileResources.bindings;
+        if (clientSecret) {
+            return Caracal.fromClientSecret({
+                coordinatorUrl: url,
+                stsUrl,
+                zoneId: zoneId,
+                applicationId: applicationId,
+                clientSecret,
+                resources: resourceIdsFromEnv(env.CARACAL_APP_RESOURCES, profileResources.credentialResources ?? [], profileResources.resources),
+                gatewayUrl,
+            });
+        }
+        if (!subjectToken) {
+            throw new Error("Caracal.fromEnv: provide CARACAL_APP_CLIENT_SECRET or CARACAL_SUBJECT_TOKEN");
+        }
         validateSubjectToken(subjectToken);
         return new Caracal({
             coordinator: { baseUrl: url },
@@ -40,45 +94,90 @@ export class Caracal {
             applicationId: applicationId,
             subjectToken: subjectToken,
             gatewayUrl,
-            resources: parseResourceBindings(env.CARACAL_RESOURCES),
+            resources,
+        });
+    }
+    static fromClientSecret(opts) {
+        const resourceIds = opts.resources.map((value) => typeof value === "string" ? value : value.resourceId);
+        if (!resourceIds.length)
+            throw new Error("Caracal.fromClientSecret requires at least one resource");
+        const bindings = opts.resources.filter((value) => typeof value !== "string");
+        return new Caracal({
+            coordinator: { baseUrl: opts.coordinatorUrl },
+            zoneId: opts.zoneId,
+            applicationId: opts.applicationId,
+            tokenSource: createClientSecretTokenSource(opts.stsUrl, opts.zoneId, opts.applicationId, opts.clientSecret, resourceIds, opts.scope, opts.fetchImpl),
+            gatewayUrl: opts.gatewayUrl,
+            resources: bindings.length ? bindings : undefined,
+        });
+    }
+    static fromConfig(path = defaultProfilePath(), env = process.env) {
+        if (!existsSync(path))
+            throw new Error(`Caracal.fromConfig: profile not found: ${path}`);
+        assertProfileFileSecure(path);
+        const value = parse(readFileSync(path, "utf8"));
+        if (!isRecord(value))
+            throw new Error("Caracal.fromConfig: profile must be a TOML table");
+        const zoneId = requiredString(value, "zone_id", path);
+        const applicationId = requiredString(value, "application_id", path);
+        const stsUrl = stringValue(value, "sts_url")
+            ?? stringValue(value, "zone_url")
+            ?? env.CARACAL_STS_URL
+            ?? env.CARACAL_ZONE_URL
+            ?? serviceUrl(env, "CARACAL_STS_URL", DEFAULT_STS_URL);
+        const coordinatorUrl = stringValue(value, "coordinator_url") ?? serviceUrl(env, "CARACAL_COORDINATOR_URL", DEFAULT_COORDINATOR_URL);
+        const resources = resourcesFromProfile(value, path, env, zoneId, applicationId);
+        if (!resources.resources.length) {
+            throw new Error(`Caracal.fromConfig: ${path} requires at least one resource via credentials, CARACAL_RESOURCES, or CARACAL_RESOURCES_FILE`);
+        }
+        return Caracal.fromClientSecret({
+            coordinatorUrl,
+            stsUrl,
+            zoneId,
+            applicationId,
+            clientSecret: clientSecretFromProfile(value, path, env, zoneId, applicationId),
+            resources: resources.resources,
+            gatewayUrl: stringValue(value, "gateway_url") ?? serviceUrl(env, "CARACAL_GATEWAY_URL", DEFAULT_GATEWAY_URL),
         });
     }
     async close() {
-        // No-op until transport resources need teardown.
     }
-    spawn(fn, opts = {}) {
+    async spawn(fn, opts = {}) {
         const input = {
             coordinator: this.config.coordinator,
             zoneId: this.config.zoneId,
             applicationId: this.config.applicationId,
-            subjectToken: this.config.subjectToken,
+            subjectToken: await this.rootToken(),
             kind: opts.kind ?? this.config.defaultKind ?? AgentKind.Instance,
             ttlSeconds: opts.ttlSeconds ?? this.config.defaultTtlSeconds,
+            subjectSessionId: opts.subjectSessionId,
             parentId: opts.parentId,
             metadata: opts.metadata,
             traceId: opts.traceId,
             onAgentStart: this.agentStartHooks.length ? (c) => this.fire(this.agentStartHooks, c) : undefined,
             onAgentEnd: this.agentEndHooks.length ? (c) => this.fire(this.agentEndHooks, c) : undefined,
         };
-        return spawnPrimitive(input, fn);
+        return await spawnPrimitive(input, fn);
     }
     delegate(opts, fn) {
         const input = {
             coordinator: this.config.coordinator,
             toAgentSessionId: opts.to,
             toApplicationId: opts.toApplicationId,
+            resourceId: opts.resourceId,
             scopes: opts.scopes,
             constraints: opts.constraints,
             ttlSeconds: opts.ttlSeconds,
         };
         return delegatePrimitive(input, fn);
     }
-    delegateToSpawn(opts, fn) {
+    async delegateToSpawn(opts, fn) {
         const input = {
             coordinator: this.config.coordinator,
             zoneId: this.config.zoneId,
             applicationId: this.config.applicationId,
-            subjectToken: this.config.subjectToken,
+            subjectToken: await this.rootToken(),
+            resourceId: opts.resourceId,
             scopes: opts.scopes,
             constraints: opts.constraints,
             delegationTtlSeconds: opts.delegationTtlSeconds,
@@ -89,7 +188,7 @@ export class Caracal {
             onAgentStart: this.agentStartHooks.length ? (c) => this.fire(this.agentStartHooks, c) : undefined,
             onAgentEnd: this.agentEndHooks.length ? (c) => this.fire(this.agentEndHooks, c) : undefined,
         };
-        return delegateToSpawnPrimitive(input, fn);
+        return await delegateToSpawnPrimitive(input, fn);
     }
     bind(ctx, fn) {
         return bind(ctx, fn);
@@ -107,17 +206,30 @@ export class Caracal {
     current() {
         return current();
     }
-    headers() {
+    headers(opts = {}) {
         const ctx = current();
         if (!ctx) {
+            if (!opts.allowRoot) {
+                throw new Error("Caracal.headers(): no Caracal context is bound. Pass { allowRoot: true } to use the application subject token.");
+            }
             return toHeaders({
-                subjectToken: this.config.subjectToken,
+                subjectToken: this.rootTokenSync(),
                 hop: 0,
             });
         }
         return toHeaders(toEnvelope(ctx));
     }
-    bindFromHeaders(headers, fn) {
+    async headersAsync(opts = {}) {
+        const ctx = current();
+        if (!ctx) {
+            if (!opts.allowRoot) {
+                throw new Error("Caracal.headersAsync(): no Caracal context is bound. Pass { allowRoot: true } to use the application subject token.");
+            }
+            return toHeaders({ subjectToken: await this.rootToken(), hop: 0 });
+        }
+        return toHeaders(toEnvelope(ctx));
+    }
+    async bindFromHeaders(headers, fn, opts = {}) {
         const env = typeof headers === "function"
             ? decodeEnvelope(headers)
             : decodeEnvelope((n) => {
@@ -130,13 +242,17 @@ export class Caracal {
                 }
                 return undefined;
             });
-        if (!env.subjectToken)
-            env.subjectToken = this.config.subjectToken;
+        if (!env.subjectToken) {
+            if (!opts.allowRoot) {
+                throw new Error("Caracal.bindFromHeaders(): inbound request is missing a bearer token. Pass { allowRoot: true } only for trusted service-root ingress.");
+            }
+            env.subjectToken = await this.rootToken();
+        }
         const ctx = fromEnvelope(env, {
             zoneId: this.config.zoneId,
             clientId: this.config.applicationId,
         });
-        return bind(ctx, fn);
+        return await bind(ctx, fn);
     }
     /**
      * Returns a fetch-shaped function that injects the Caracal envelope (traceparent
@@ -144,13 +260,15 @@ export class Caracal {
      * `Authorization` header with the current subject token. Pass to any provider
      * SDK that accepts a custom fetch.
      */
-    transport() {
+    transport(opts = {}) {
         const outer = this;
+        const rootAllowed = opts.allowRoot === true;
         const fn = (async (input, init) => {
             const ctx = current();
-            const env = ctx
-                ? toEnvelope(ctx)
-                : { subjectToken: outer.config.subjectToken, hop: 0 };
+            if (!ctx && !rootAllowed) {
+                throw new Error("Caracal.transport(): no Caracal context is bound. Pass { allowRoot: true } to use the application subject token.");
+            }
+            const env = ctx ? toEnvelope(ctx) : { subjectToken: await outer.rootToken(), hop: 0 };
             const merged = new Headers(init?.headers ?? {});
             for (const [k, v] of Object.entries(toHeaders(env))) {
                 if (!merged.has(k))
@@ -161,13 +279,36 @@ export class Caracal {
             const rewritten = outer.routeThroughGateway(input, explicitResource);
             if (rewritten) {
                 merged.set("X-Caracal-Resource", rewritten.resourceId);
-                merged.set("Authorization", `Bearer ${env.subjectToken ?? outer.config.subjectToken}`);
+                merged.set("Authorization", `Bearer ${env.subjectToken}`);
                 return fetchImpl(rewritten.url, { ...init, headers: merged });
             }
             return fetchImpl(input, { ...init, headers: merged });
         });
         return fn;
     }
+    gatewayRequest(resourceId, path = "/") {
+        if (!this.config.gatewayUrl)
+            throw new Error("Caracal.gatewayRequest(): gatewayUrl is not configured");
+        if (!resourceId.trim())
+            throw new Error("Caracal.gatewayRequest(): resourceId is required");
+        return {
+            url: joinGatewayPath(this.config.gatewayUrl, path),
+            headers: { "X-Caracal-Resource": resourceId },
+        };
+    }
+    /**
+     * One-call happy path: sends `init` to `path` on the given resource through the
+     * Gateway with Caracal context and authority injected. Equivalent to building a
+     * `gatewayRequest` and calling it with `transport`. The resource header always
+     * wins over any caller-supplied `X-Caracal-Resource`.
+     */
+    fetch(resourceId, path = "/", init = {}, opts = {}) {
+        const request = this.gatewayRequest(resourceId, path);
+        const headers = new Headers(init.headers ?? {});
+        for (const [key, value] of Object.entries(request.headers))
+            headers.set(key, value);
+        return this.transport(opts)(request.url, { ...init, headers });
+    }
     routeThroughGateway(input, explicitResource) {
         const gw = this.config.gatewayUrl;
         if (!gw)
@@ -205,13 +346,305 @@ export class Caracal {
         const target = base + suffix;
         return { url: target, resourceId: binding?.resourceId ?? explicitResource };
     }
-    middleware() {
+    /**
+     * Binds Caracal context after a verifier boundary. This does not verify JWT
+     * signatures, audience, scopes, token use, or revocation.
+     */
+    contextMiddleware(opts = {}) {
         return (req, _res, next) => {
             this.bindFromHeaders(req.headers, async () => {
                 next();
-            }).catch(next);
+            }, opts).catch(next);
         };
     }
+    rootTokenSync() {
+        if (this.config.subjectToken)
+            return this.config.subjectToken;
+        throw new Error("Caracal.headers(): this client uses an async token source. Use headersAsync({ allowRoot: true }) for root headers.");
+    }
+    async rootToken() {
+        if (this.config.tokenSource)
+            return await this.config.tokenSource();
+        if (this.config.subjectToken)
+            return this.config.subjectToken;
+        throw new Error("Caracal client has no subject token source");
+    }
+}
+function serviceUrl(env, key, fallback) {
+    const value = env[key];
+    if (value)
+        return value;
+    if (env.NODE_ENV === "production")
+        throw new Error(`Caracal SDK: ${key} is required when NODE_ENV=production`);
+    return fallback;
+}
+function stsUrlFromEnv(env) {
+    return env.CARACAL_STS_URL ?? env.CARACAL_ZONE_URL ?? serviceUrl(env, "CARACAL_STS_URL", DEFAULT_STS_URL);
+}
+function defaultProfilePath(env = process.env) {
+    return join(defaultConfigDir(env), "caracal.toml");
+}
+function defaultConfigDir(env = process.env) {
+    if (env.CARACAL_CONFIG_HOME)
+        return env.CARACAL_CONFIG_HOME;
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, "caracal");
+    if (platform() === "win32")
+        return join(env.APPDATA || env.LOCALAPPDATA || join(homedir(), "AppData", "Roaming"), "Caracal");
+    if (platform() === "darwin")
+        return join(homedir(), "Library", "Application Support", "Caracal");
+    return join(homedir(), ".config", "caracal");
+}
+function defaultCredentialDir(env, zoneId, applicationId) {
+    return join(defaultConfigDir(env), "runtime", safePathSegment(zoneId), safePathSegment(applicationId));
+}
+function defaultClientSecretPath(env, zoneId, applicationId) {
+    return join(defaultCredentialDir(env, zoneId, applicationId), "client-secret");
+}
+function defaultRunCredentialsPath(env, zoneId, applicationId) {
+    return join(defaultCredentialDir(env, zoneId, applicationId), "credentials.json");
+}
+function safePathSegment(value) {
+    const segment = value.trim().replace(/[^A-Za-z0-9._-]+/g, "_");
+    let start = 0;
+    let end = segment.length;
+    while (start < end && segment[start] === "_")
+        start += 1;
+    while (end > start && segment[end - 1] === "_")
+        end -= 1;
+    return segment.slice(start, end) || "default";
+}
+function existingLocalFile(path, env) {
+    if (env.NODE_ENV === "production")
+        return undefined;
+    return existsSync(path) ? path : undefined;
+}
+function resolveProfilePath(env) {
+    if (env.CARACAL_CONFIG) {
+        if (!existsSync(env.CARACAL_CONFIG))
+            throw new Error(`Caracal.connect: profile not found: ${env.CARACAL_CONFIG}`);
+        return env.CARACAL_CONFIG;
+    }
+    const path = defaultProfilePath(env);
+    return existsSync(path) ? path : undefined;
+}
+function assertProfileFileSecure(path) {
+    if (process.platform === "win32")
+        return;
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o022) !== 0)
+        throw new Error(`Caracal.fromConfig: profile permissions are too broad: ${path}`);
+}
+function assertSecretFileSecure(path) {
+    if (process.platform === "win32")
+        return;
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o022) !== 0)
+        throw new Error(`Caracal profile secret file permissions are too broad: ${path}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(record, key) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Caracal profile: ${key} must be a non-empty string`);
+    return value;
+}
+function requiredString(record, key, source) {
+    const value = stringValue(record, key);
+    if (!value)
+        throw new Error(`${source}: ${key} is required`);
+    return value;
+}
+function clientSecretFromProfile(record, source, env, zoneId, applicationId) {
+    const inline = stringValue(record, "app_client_secret");
+    const file = stringValue(record, "app_client_secret_file");
+    if (inline && file)
+        throw new Error(`${source}: set only one of app_client_secret or app_client_secret_file`);
+    if (inline)
+        return inline;
+    const localFile = file ?? existingLocalFile(defaultClientSecretPath(env, zoneId, applicationId), env);
+    if (!localFile)
+        throw new Error(`${source}: client secret is required; local dev/stable auto-detects ${defaultClientSecretPath(env, zoneId, applicationId)} when it exists`);
+    return readSecretFile(localFile);
+}
+function clientSecretFromEnv(env, zoneId, applicationId) {
+    if (env.CARACAL_APP_CLIENT_SECRET && env.CARACAL_APP_CLIENT_SECRET_FILE) {
+        throw new Error("Caracal.fromEnv: set only one of CARACAL_APP_CLIENT_SECRET or CARACAL_APP_CLIENT_SECRET_FILE");
+    }
+    if (env.CARACAL_APP_CLIENT_SECRET_FILE)
+        return readSecretFile(env.CARACAL_APP_CLIENT_SECRET_FILE);
+    const localFile = existingLocalFile(defaultClientSecretPath(env, zoneId, applicationId), env);
+    if (localFile)
+        return readSecretFile(localFile);
+    return env.CARACAL_APP_CLIENT_SECRET;
+}
+function readSecretFile(path) {
+    if (!existsSync(path))
+        throw new Error(`Caracal profile secret file does not exist: ${path}`);
+    assertSecretFileSecure(path);
+    const secret = readFileSync(path, "utf8").trim();
+    if (!secret)
+        throw new Error(`Caracal profile secret file is empty: ${path}`);
+    return secret;
+}
+function resourcesFromProfile(record, source, env, zoneId, applicationId) {
+    const credentials = [
+        ...credentialEntries(record.credentials, `${source}.credentials`),
+        ...credentialEntries(record.optional_credentials, `${source}.optional_credentials`),
+        ...credentialManifestFromEnv(env, zoneId, applicationId),
+    ];
+    const resources = resourcesFromCredentials(credentials);
+    const resolved = resolveProfileResources(resources.resources, resources.bindings ?? [], env);
+    return { ...resolved, credentialResources: resources.resources };
+}
+function resourcesFromEnv(env, zoneId, applicationId) {
+    const credentials = credentialManifestFromEnv(env, zoneId, applicationId);
+    const resources = resourcesFromCredentials(credentials);
+    const resolved = resolveProfileResources(resources.resources, resources.bindings ?? [], env);
+    return { ...resolved, credentialResources: resources.resources };
+}
+function resolveProfileResources(resources, credentialBindings, env) {
+    const envBindings = parseResourceBindings(env.CARACAL_RESOURCES) ?? [];
+    const bindings = sortBindingsLongestFirst(mergeResourceBindings(credentialBindings, resourceBindingsFromFile(env.CARACAL_RESOURCES_FILE), envBindings));
+    const byResource = new Map();
+    for (const item of resources)
+        byResource.set(typeof item === "string" ? item : item.resourceId, item);
+    for (const binding of bindings)
+        byResource.set(binding.resourceId, binding);
+    const values = [...byResource.values()];
+    return { resources: values, bindings };
+}
+function resourceBindingsFromFile(path) {
+    if (!path)
+        return [];
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const errors = [];
+    if (Array.isArray(parsed)) {
+        const out = [];
+        for (const [index, entry] of parsed.entries()) {
+            if (!isRecord(entry)) {
+                errors.push(`[${index}]: entry must be an object`);
+                continue;
+            }
+            const keys = Object.keys(entry);
+            if (keys.length !== 2 || !keys.includes("resource_id") || !keys.includes("upstream_prefix")) {
+                errors.push(`[${index}]: expected exactly resource_id and upstream_prefix`);
+                continue;
+            }
+            const resourceId = entry.resource_id;
+            const upstreamPrefix = entry.upstream_prefix;
+            if (typeof resourceId !== "string" || !resourceId) {
+                errors.push(`[${index}]: resource_id must be a non-empty string`);
+                continue;
+            }
+            if (typeof upstreamPrefix !== "string" || !upstreamPrefix) {
+                errors.push(`[${index}]: upstream_prefix must be a non-empty string`);
+                continue;
+            }
+            if (!isAbsoluteUrl(upstreamPrefix)) {
+                errors.push(`[${index}]: upstream_prefix must be an absolute URL`);
+                continue;
+            }
+            out.push({ resourceId, upstreamPrefix });
+        }
+        if (errors.length)
+            throw new Error(`invalid CARACAL_RESOURCES_FILE:\n- ${errors.join("\n- ")}`);
+        return out;
+    }
+    if (isRecord(parsed)) {
+        const out = [];
+        for (const [resourceId, upstreamPrefix] of Object.entries(parsed)) {
+            if (!resourceId) {
+                errors.push("key must be a non-empty string");
+                continue;
+            }
+            if (typeof upstreamPrefix !== "string" || !upstreamPrefix) {
+                errors.push(`entry ${JSON.stringify(resourceId)} upstream_prefix must be a non-empty string`);
+                continue;
+            }
+            if (!isAbsoluteUrl(upstreamPrefix)) {
+                errors.push(`entry ${JSON.stringify(resourceId)} upstream_prefix must be an absolute URL`);
+                continue;
+            }
+            out.push({ resourceId, upstreamPrefix });
+        }
+        if (errors.length)
+            throw new Error(`invalid CARACAL_RESOURCES_FILE:\n- ${errors.join("\n- ")}`);
+        return out;
+    }
+    throw new Error("CARACAL_RESOURCES_FILE must contain an object or array");
+}
+function mergeResourceBindings(...sources) {
+    const order = [];
+    const byResource = new Map();
+    for (const source of sources) {
+        for (const binding of source) {
+            if (!byResource.has(binding.resourceId))
+                order.push(binding.resourceId);
+            byResource.set(binding.resourceId, binding);
+        }
+    }
+    return order.map((resourceId) => byResource.get(resourceId));
+}
+function isAbsoluteUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return Boolean(parsed.protocol && parsed.host);
+    }
+    catch {
+        return false;
+    }
+}
+function credentialManifestFromEnv(env, zoneId, applicationId) {
+    const file = env.CARACAL_RUN_CREDENTIALS_FILE;
+    const inline = env.CARACAL_RUN_CREDENTIALS;
+    if (file && inline)
+        throw new Error("Caracal.fromEnv: set only one of CARACAL_RUN_CREDENTIALS or CARACAL_RUN_CREDENTIALS_FILE");
+    const localFile = !file && !inline ? existingLocalFile(defaultRunCredentialsPath(env, zoneId, applicationId), env) : undefined;
+    if (!file && !inline && !localFile)
+        return [];
+    const raw = file || localFile ? readSecretFile(file ?? localFile) : inline;
+    const parsed = JSON.parse(raw);
+    const manifest = Array.isArray(parsed) ? { credentials: parsed } : parsed;
+    if (!isRecord(manifest))
+        throw new Error("Caracal.fromEnv: credential manifest must be an array or object");
+    return [
+        ...credentialEntries(manifest.credentials, "CARACAL_RUN_CREDENTIALS.credentials"),
+        ...credentialEntries(manifest.optional_credentials, "CARACAL_RUN_CREDENTIALS.optional_credentials"),
+    ];
+}
+function credentialEntries(value, source) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${source} must be an array`);
+    return value.map((entry, index) => {
+        if (!isRecord(entry))
+            throw new Error(`${source}[${index}] must be an object`);
+        const resource = stringValue(entry, "resource");
+        if (!resource)
+            throw new Error(`${source}[${index}].resource is required`);
+        const upstreamPrefix = stringValue(entry, "upstream_prefix");
+        return upstreamPrefix ? { resource, upstream_prefix: upstreamPrefix } : { resource };
+    });
+}
+function resourcesFromCredentials(credentials) {
+    const values = [];
+    const seen = new Set();
+    for (const credential of credentials) {
+        if (seen.has(credential.resource))
+            continue;
+        seen.add(credential.resource);
+        values.push(credential.upstream_prefix
+            ? { resourceId: credential.resource, upstreamPrefix: credential.upstream_prefix }
+            : credential.resource);
+    }
+    const bindings = values.filter((value) => typeof value !== "string");
+    return { resources: values, bindings };
 }
 function sameOrigin(a, b) {
     try {
@@ -222,6 +655,18 @@ function sameOrigin(a, b) {
         return false;
     }
 }
+function joinGatewayPath(gatewayUrl, path) {
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(path)) {
+        throw new Error("Caracal.gatewayRequest(): path must be relative to the configured gateway");
+    }
+    const gateway = new URL(gatewayUrl);
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    const queryIndex = normalized.indexOf("?");
+    const pathname = queryIndex === -1 ? normalized : normalized.slice(0, queryIndex);
+    const query = queryIndex === -1 ? "" : normalized.slice(queryIndex + 1);
+    const base = gateway.origin + gateway.pathname.replace(/\/$/, "");
+    return `${base}${pathname || "/"}${query ? `?${query}` : ""}`;
+}
 function urlMatchesPrefix(target, prefix) {
     let p;
     try {
@@ -242,21 +687,60 @@ function parseResourceBindings(raw) {
     if (!raw)
         return undefined;
     const out = [];
-    for (const entry of raw.split(",")) {
+    const errors = [];
+    for (const [index, entry] of raw.split(",").entries()) {
         const trimmed = entry.trim();
         if (!trimmed)
             continue;
         const idx = trimmed.indexOf("=");
-        if (idx <= 0)
+        if (idx <= 0) {
+            errors.push(`entry ${index + 1} must use resourceId=upstreamPrefix`);
             continue;
+        }
         const resourceId = trimmed.slice(0, idx).trim();
         const upstreamPrefix = trimmed.slice(idx + 1).trim();
-        if (resourceId && upstreamPrefix) {
-            out.push({ resourceId, upstreamPrefix });
+        if (!resourceId || !upstreamPrefix) {
+            errors.push(`entry ${index + 1} must contain non-empty resourceId and upstreamPrefix`);
+            continue;
         }
+        if (!isAbsoluteUrl(upstreamPrefix)) {
+            errors.push(`entry ${index + 1} upstreamPrefix must be an absolute URL`);
+            continue;
+        }
+        out.push({ resourceId, upstreamPrefix });
+    }
+    if (errors.length) {
+        throw new Error(`Caracal.fromEnv: invalid CARACAL_RESOURCES:\n- ${errors.join("\n- ")}`);
     }
     return out.length ? sortBindingsLongestFirst(out) : undefined;
 }
+function compactResourceValues(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const resourceId = typeof value === "string" ? value : value.resourceId;
+        if (!resourceId || seen.has(resourceId))
+            continue;
+        seen.add(resourceId);
+        out.push(value);
+    }
+    return out;
+}
+function resourceIdsFromEnv(raw, first, resources) {
+    const explicit = raw?.split(",").map((value) => value.trim()).filter(Boolean);
+    if (explicit?.length)
+        return compactResourceValues([...first, ...explicit]);
+    if (resources?.length)
+        return resources;
+    throw new Error("Caracal.fromEnv: client-secret mode requires resources via CARACAL_APP_RESOURCES, CARACAL_RUN_CREDENTIALS, CARACAL_RESOURCES, or CARACAL_RESOURCES_FILE");
+}
+function createClientSecretTokenSource(stsUrl, zoneId, applicationId, clientSecret, resources, scope = "agent:lifecycle", fetchImpl) {
+    const client = new OAuthClient(stsUrl, zoneId, applicationId, undefined, fetchImpl);
+    return async () => {
+        const token = await client.exchange("", resources, { clientSecret, scopes: [scope] });
+        return token.accessToken;
+    };
+}
 function sortBindingsLongestFirst(bindings) {
     return [...bindings].sort((a, b) => b.upstreamPrefix.length - a.upstreamPrefix.length);
 }
@@ -290,7 +774,7 @@ function validateSubjectToken(token) {
     if (typeof payload.exp !== "number")
         return;
     if (payload.exp <= Math.floor(Date.now() / 1000)) {
-        throw new Error("CARACAL_SUBJECT_TOKEN is expired — refresh the bootstrap token before starting the application");
+        throw new Error("CARACAL_SUBJECT_TOKEN is expired: refresh the bootstrap token before starting the application");
     }
 }
 //# sourceMappingURL=client.js.map