@dcdr/contracts 1.9.6

package/dist/runtime.client.js

@@ -0,0 +1,545 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DcdrRuntimeClient = exports.DcdrRuntimeAuthCheckEntitlementsStatus = void 0;
+const execution_contract_1 = require("./execution.contract");
+/**
+ * Max characters to include when embedding a response body preview inside an Error message.
+ *
+ * Notes
+ * - Keeps logs and CLI output readable.
+ * - Reduces the chance of leaking large/sensitive upstream HTML or debug payloads.
+ */
+const ERROR_BODY_PREVIEW_MAX_CHARS = 4000;
+/**
+ * Status for optional entitlements data returned by the auth check endpoint.
+ */
+var DcdrRuntimeAuthCheckEntitlementsStatus;
+(function (DcdrRuntimeAuthCheckEntitlementsStatus) {
+    DcdrRuntimeAuthCheckEntitlementsStatus["OK"] = "OK";
+    DcdrRuntimeAuthCheckEntitlementsStatus["ERROR"] = "ERROR";
+    DcdrRuntimeAuthCheckEntitlementsStatus["SKIPPED"] = "SKIPPED";
+})(DcdrRuntimeAuthCheckEntitlementsStatus || (exports.DcdrRuntimeAuthCheckEntitlementsStatus = DcdrRuntimeAuthCheckEntitlementsStatus = {}));
+/**
+ * HTTP client for interacting with the DCDR Runtime REST API.
+ *
+ * @remarks
+ * `DcdrRuntimeClient` wraps a `fetch` implementation and provides typed convenience methods for common runtime endpoints
+ * (execution, system info, health, metrics, circuit breaker inspection/reset). It supports request timeouts via
+ * {@link AbortController} and can be configured with additional headers.
+ *
+ * This client is intentionally small and dependency-free:
+ * - It does not attempt retries or circuit breaking (those are runtime concerns).
+ * - It does not validate payload schemas beyond basic response shape parsing.
+ *
+ * ## Authentication
+ * Exactly one of the following auth modes should be used:
+ * - **Bearer token**: sets `Authorization: Bearer <token>`
+ * - **API token**: sets `token: <token>` and optionally `x-session-bypass: <token>` when `sessionBypassToken` is provided
+ *
+ * If both `bearerToken` and `apiToken` are provided, construction throws.
+ *
+ * ## Timeouts
+ * Requests are aborted after `timeoutMs` (default: `10_000`) using `AbortController`.
+ *
+ * ## Error behavior
+ * - Non-OK HTTP responses throw an {@link Error} including method, path, status, and a short body preview.
+ * - JSON endpoints require `content-type: application/json` (runtime should set this).
+ * - Abort/timeout failures surface as a thrown {@link Error} from the underlying `fetch` implementation.
+ *
+ * ## Version / build info
+ * The {@link DcdrRuntimeClient.version} method calls `GET /api/system/version` and returns a {@link DcdrRuntimeVersionResponse}
+ * intended for support diagnostics (build number/date/SHA and, in runtime mode only, node version + uptime).
+ *
+ * @example
+ * ```ts
+ * // Customer mode (cloud)
+ * const client = new DcdrRuntimeClient({
+ *   bearerToken: process.env.DCDR_SESSION_TOKEN,
+ * });
+ *
+ * const hc = await client.healthcheck();
+ * const res = await client.executeIntent("MY_INTENT", { vars: { name: "Ada" } });
+ * const ver = await client.version();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Internal mode (dev/ops)
+ * const client = new DcdrRuntimeClient({
+ *   baseUrl: "http://localhost:8000",
+ *   apiToken: "dev-token",
+ *   sessionBypassToken: "bypass-token",
+ * });
+ *
+ * const ver = await client.version();
+ * ```
+ *
+ * @public
+ */
+class DcdrRuntimeClient {
+    baseUrl;
+    bearerToken;
+    apiToken;
+    sessionBypassToken;
+    timeoutMs;
+    extraHeaders;
+    fetchFn;
+    /**
+     * Creates a new runtime client.
+     * @param cfg Client configuration.
+     */
+    constructor(cfg) {
+        const resolvedBaseUrl = cfg?.baseUrl ?? "https://runtime.dcdr.ai";
+        const resolvedBaseUrlTrimmed = String(resolvedBaseUrl).trim();
+        if (!resolvedBaseUrlTrimmed) {
+            throw new Error("DcdrRuntimeClient requires baseUrl (or omit it to use https://runtime.dcdr.ai)");
+        }
+        this.baseUrl = resolvedBaseUrlTrimmed.replace(/\/$/, "");
+        this.bearerToken = cfg.bearerToken ? String(cfg.bearerToken).trim() : undefined;
+        this.apiToken = cfg.apiToken ? String(cfg.apiToken).trim() : undefined;
+        this.sessionBypassToken = cfg.sessionBypassToken ? String(cfg.sessionBypassToken).trim() : undefined;
+        this.timeoutMs = typeof cfg.timeoutMs === "number" && cfg.timeoutMs > 0 ? cfg.timeoutMs : 10_000;
+        this.extraHeaders = cfg.extraHeaders ? { ...cfg.extraHeaders } : {};
+        const f = cfg.fetchFn ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+        if (!f) {
+            throw new Error("DcdrRuntimeClient requires a fetch implementation (global fetch missing)");
+        }
+        this.fetchFn = f;
+        // Basic config validation: do not silently pick an auth mode.
+        if (this.bearerToken && this.apiToken) {
+            throw new Error("DcdrRuntimeClient config should not set both bearerToken and apiToken");
+        }
+    }
+    /**
+     * Calls `POST /api/execution/run/:intent`.
+     * @param intent Intent name.
+     * @param request Execute request payload.
+     * @returns Execution result.
+     */
+    async executeIntent(intent, request) {
+        const safeIntent = encodeURIComponent(String(intent ?? "").trim());
+        return this.requestJson({
+            method: "POST",
+            path: `/api/execution/run/${safeIntent}`,
+            body: request ?? {},
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `POST /api/execution/stream/:intent` and yields SSE events.
+     *
+     * Notes
+     * - The streaming endpoint is additive; `executeIntent()` remains the stable JSON path.
+     * - v1 streams a minimal envelope (`meta` then `final`). Providers without native streaming
+     *   may yield zero `delta` events.
+     *
+     * @param intent Intent name.
+     * @param request Execute request payload.
+     * @param opts Streaming options (timeout/signal).
+     */
+    async *executeIntentStream(intent, request, opts) {
+        const safeIntent = encodeURIComponent(String(intent ?? "").trim());
+        const url = `${this.baseUrl}/api/execution/stream/${safeIntent}`;
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "text/event-stream",
+            ...this.extraHeaders,
+        };
+        if (this.bearerToken) {
+            headers["Authorization"] = `Bearer ${this.bearerToken}`;
+        }
+        else if (this.apiToken) {
+            headers["token"] = this.apiToken;
+            if (this.sessionBypassToken) {
+                headers["x-session-bypass"] = this.sessionBypassToken;
+            }
+        }
+        const controller = new AbortController();
+        const timeoutMs = typeof opts?.timeoutMs === "number" && opts.timeoutMs > 0 ? opts.timeoutMs : this.timeoutMs;
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const onAbort = () => controller.abort();
+        if (opts?.signal) {
+            if (opts.signal.aborted)
+                controller.abort();
+            else
+                opts.signal.addEventListener("abort", onAbort);
+        }
+        try {
+            const resp = await this.fetchFn(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(request ?? {}),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const text = await resp.text();
+                const preview = buildBodyPreview(text);
+                throw new Error(`DcdrRuntimeClient request failed: POST /api/execution/stream/:intent status=${resp.status} body=${preview}`);
+            }
+            const ct = resp.headers.get("content-type") ?? "";
+            if (!/text\/event-stream/i.test(ct)) {
+                const text = await resp.text();
+                const preview = buildBodyPreview(text);
+                throw new Error(`DcdrRuntimeClient expected text/event-stream but got content-type='${ct}' body=${preview}`);
+            }
+            if (!resp.body) {
+                throw new Error("DcdrRuntimeClient streaming response body is missing");
+            }
+            for await (const evt of this.parseSseStream(resp.body)) {
+                const eventName = evt.event;
+                const json = evt.data ? JSON.parse(evt.data) : {};
+                if (eventName === execution_contract_1.ExecutionStreamEventType.META) {
+                    yield { type: execution_contract_1.ExecutionStreamEventType.META, data: json };
+                }
+                else if (eventName === execution_contract_1.ExecutionStreamEventType.DELTA) {
+                    yield { type: execution_contract_1.ExecutionStreamEventType.DELTA, data: json };
+                }
+                else if (eventName === execution_contract_1.ExecutionStreamEventType.FINAL) {
+                    yield { type: execution_contract_1.ExecutionStreamEventType.FINAL, data: json };
+                    return;
+                }
+                else if (eventName === execution_contract_1.ExecutionStreamEventType.ERROR) {
+                    yield { type: execution_contract_1.ExecutionStreamEventType.ERROR, data: json };
+                    return;
+                }
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            if (opts?.signal)
+                opts.signal.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * Parses a ReadableStream of SSE bytes into discrete `{event,data}` frames.
+     */
+    async *parseSseStream(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            while (true) {
+                const idx = buffer.indexOf("\n\n");
+                if (idx < 0)
+                    break;
+                const raw = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                const parsed = this.parseSseEvent(raw);
+                if (parsed)
+                    yield parsed;
+            }
+        }
+        // Flush remaining bytes.
+        buffer += decoder.decode();
+        const remaining = buffer.trim();
+        if (remaining) {
+            const parsed = this.parseSseEvent(remaining);
+            if (parsed)
+                yield parsed;
+        }
+    }
+    /**
+     * Parses a single SSE event frame.
+     */
+    parseSseEvent(raw) {
+        const lines = raw.split("\n");
+        let event = "message";
+        const dataLines = [];
+        for (const line of lines) {
+            const l = line.trimEnd();
+            if (!l)
+                continue;
+            if (l.startsWith(":"))
+                continue; // comment/heartbeat
+            if (l.startsWith("event:")) {
+                event = l.slice("event:".length).trim();
+                continue;
+            }
+            if (l.startsWith("data:")) {
+                dataLines.push(l.slice("data:".length).trim());
+                continue;
+            }
+        }
+        const data = dataLines.join("\n");
+        if (!event && !data)
+            return null;
+        return { event, data };
+    }
+    /**
+     * Calls `POST /api/execution/demo/:intent`.
+     * @param intent Demo intent (e.g. `DCDR_LOCAL_DEMO`).
+     * @param request Execute request payload.
+     * @returns Execution result.
+     */
+    async demo(intent, request) {
+        const safeIntent = encodeURIComponent(String(intent ?? "").trim());
+        return this.requestJson({
+            method: "POST",
+            path: `/api/execution/demo/${safeIntent}`,
+            body: request ?? {},
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `GET /api/system/healthcheck`.
+     * @returns Healthcheck response.
+     */
+    async healthcheck() {
+        return this.requestJson({
+            method: "GET",
+            path: "/api/system/healthcheck",
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `GET /api/system/version`.
+     * @returns Runtime version/build info.
+     */
+    async version() {
+        return this.requestJson({
+            method: "GET",
+            path: "/api/system/version",
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `GET /api/system/metrics`.
+     * Returns the raw Prometheus exposition format text.
+     *
+     * @param token Optional metrics query token (`?token=...`) when the runtime is configured to require it.
+     * @returns Metrics text.
+     */
+    async metrics(token) {
+        const t = String(token ?? "").trim();
+        const qp = t ? `?token=${encodeURIComponent(t)}` : "";
+        return this.requestText({
+            method: "GET",
+            path: `/api/system/metrics${qp}`,
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `GET /api/auth/check`.
+     *
+     * Notes
+     * - This endpoint is intended for customer integrations to verify their auth configuration.
+     * - It performs the same validation path as execution calls, but does not execute an Intent.
+     */
+    async authCheck() {
+        return this.requestJson({
+            method: "GET",
+            path: "/api/auth/check",
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `POST /api/execution/dry-run/:intent`.
+     * @param intent Intent name.
+     * @param vars Template variables.
+     * @returns Dry-run response.
+     */
+    async dryRun(intent, vars) {
+        const safeIntent = encodeURIComponent(String(intent ?? "").trim());
+        return this.requestJson({
+            method: "POST",
+            path: `/api/execution/dry-run/${safeIntent}`,
+            body: { vars: vars ?? {} },
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `POST /api/execution/eval/:intent`.
+     *
+     * Notes
+     * - Eval is disabled in freeware runtime mode (`--registry`).
+     *
+     * @param intent Intent name.
+     * @param vars Template variables.
+     * @returns Eval response.
+     */
+    async eval(intent, vars) {
+        const safeIntent = encodeURIComponent(String(intent ?? "").trim());
+        return this.requestJson({
+            method: "POST",
+            path: `/api/execution/eval/${safeIntent}`,
+            body: { vars: vars ?? {} },
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `GET /api/execution/circuit-breakers?provider=...&model=...`.
+     *
+     * Notes
+     * - Breakers are tenant-scoped server-side based on auth.
+     * - In internal mode, you may optionally pass `tenantCid` to inspect a specific tenant.
+     *
+     * @param provider Provider name.
+     * @param model Optional model.
+     * @param tenantCid Optional tenant/customer identifier (internal mode only).
+     * @returns Circuit breaker snapshot.
+     */
+    async circuitBreakerStatus(provider, model, tenantCid) {
+        const safeProvider = encodeURIComponent(String(provider ?? "").trim());
+        const safeModel = model ? encodeURIComponent(String(model).trim()) : "";
+        const safeTenant = tenantCid ? encodeURIComponent(String(tenantCid).trim()) : "";
+        const qp = [];
+        if (safeTenant)
+            qp.push(`tenantCid=${safeTenant}`);
+        qp.push(`provider=${safeProvider}`);
+        if (safeModel)
+            qp.push(`model=${safeModel}`);
+        const query = `?${qp.join("&")}`;
+        return this.requestJson({
+            method: "GET",
+            path: `/api/execution/circuit-breakers${query}`,
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Calls `PUT /api/execution/circuit-breakers/reset`.
+     *
+     * Notes
+     * - Internal-only endpoint.
+     * - Breakers are tenant-scoped server-side.
+     * - In internal mode, you may optionally pass `tenantCid` to reset a specific tenant.
+     *
+     * @param provider Provider name.
+     * @param model Optional model.
+     * @param tenantCid Optional tenant/customer identifier (internal mode only).
+     * @returns Reset operation result.
+     */
+    async resetCircuitBreaker(provider, model, tenantCid) {
+        return this.requestJson({
+            method: "PUT",
+            path: "/api/execution/circuit-breakers/reset",
+            body: {
+                tenantCid: tenantCid ? String(tenantCid).trim() : undefined,
+                provider: String(provider ?? "").trim(),
+                model: model ? String(model).trim() : undefined,
+            },
+            timeoutMs: this.timeoutMs,
+        });
+    }
+    /**
+     * Performs an HTTP request and parses a JSON response.
+     *
+     * @remarks
+     * - Requires `content-type: application/json` on successful responses.
+     * - Allows an empty response body and treats it as `{}` (for endpoints that may return no content).
+     * - Applies auth headers based on the configured auth mode.
+     * - Aborts the request after `timeoutMs` via {@link AbortController}.
+     *
+     * @param args Request parameters.
+     * @returns Parsed JSON body.
+     * @throws {@link Error} If the HTTP response is not OK, if the response is not JSON, or if JSON parsing fails.
+     */
+    async requestJson(args) {
+        const url = `${this.baseUrl}${args.path}`;
+        const headers = {
+            "Content-Type": "application/json",
+            ...this.extraHeaders,
+        };
+        if (this.bearerToken) {
+            headers["Authorization"] = `Bearer ${this.bearerToken}`;
+        }
+        else if (this.apiToken) {
+            headers["token"] = this.apiToken;
+            if (this.sessionBypassToken) {
+                headers["x-session-bypass"] = this.sessionBypassToken;
+            }
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), args.timeoutMs);
+        try {
+            const resp = await this.fetchFn(url, {
+                method: args.method,
+                headers,
+                body: args.body ? JSON.stringify(args.body) : undefined,
+                signal: controller.signal,
+            });
+            const text = await resp.text();
+            const isJson = /application\/json/i.test(resp.headers.get("content-type") ?? "");
+            if (!resp.ok) {
+                const preview = buildBodyPreview(text);
+                throw new Error(`DcdrRuntimeClient request failed: ${args.method} ${args.path} status=${resp.status} body=${preview}`);
+            }
+            if (!text) {
+                // Allow empty body for endpoints that might not return content.
+                return JSON.parse("{}");
+            }
+            if (!isJson) {
+                throw new Error(`DcdrRuntimeClient expected JSON but got content-type='${resp.headers.get("content-type") ?? ""}'`);
+            }
+            return JSON.parse(text);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Performs an HTTP request and returns the response body as plain text.
+     *
+     * @remarks
+     * Builds the request URL by concatenating {@link DcdrRuntimeClient.baseUrl} with {@link RequestTextArgs.path}.
+     * Merges {@link DcdrRuntimeClient.extraHeaders} into the request headers and applies authentication:
+     * - If {@link DcdrRuntimeClient.bearerToken} is set, adds an `Authorization: Bearer <token>` header.
+     * - Otherwise, if {@link DcdrRuntimeClient.apiToken} is set, adds a `token: <token>` header and, if present,
+     *   adds `x-session-bypass: <token>` from {@link DcdrRuntimeClient.sessionBypassToken}.
+     *
+     * Uses an {@link AbortController} to abort the request after {@link RequestTextArgs.timeoutMs} milliseconds.
+     *
+     * @param args - Request configuration including method, path, and timeout.
+     * @returns The response body as text.
+     * @throws {@link Error} If the response status is not OK (`resp.ok === false`). The error message includes the
+    * HTTP method, path, status code, and a bounded preview of the response body.
+     */
+    async requestText(args) {
+        const url = `${this.baseUrl}${args.path}`;
+        const headers = {
+            ...this.extraHeaders,
+        };
+        if (this.bearerToken) {
+            headers["Authorization"] = `Bearer ${this.bearerToken}`;
+        }
+        else if (this.apiToken) {
+            headers["token"] = this.apiToken;
+            if (this.sessionBypassToken) {
+                headers["x-session-bypass"] = this.sessionBypassToken;
+            }
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), args.timeoutMs);
+        try {
+            const resp = await this.fetchFn(url, {
+                method: args.method,
+                headers,
+                signal: controller.signal,
+            });
+            const text = await resp.text();
+            if (!resp.ok) {
+                const preview = buildBodyPreview(text);
+                throw new Error(`DcdrRuntimeClient request failed: ${args.method} ${args.path} status=${resp.status} body=${preview}`);
+            }
+            return text;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.DcdrRuntimeClient = DcdrRuntimeClient;
+/**
+ * Builds a bounded, human-readable body preview string.
+ * @param text Full response body text.
+ * @returns Preview string capped to {@link ERROR_BODY_PREVIEW_MAX_CHARS}.
+ */
+function buildBodyPreview(text) {
+    const t = String(text ?? "");
+    return t.length > ERROR_BODY_PREVIEW_MAX_CHARS
+        ? t.slice(0, ERROR_BODY_PREVIEW_MAX_CHARS) + "…"
+        : t;
+}

package/dist/service-tokens.contract.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Snapshot of allowed (and revoked) customer service tokens.
+ *
+ * IMPORTANT:
+ * - Never include tokens in clear.
+ * - Tokens are referenced by sha256(utf8(tokenString)) in hex.
+ * - Backend should keep this snapshot stable & ordered for reproducible ETags.
+ */
+export type DcdrServiceTokenStatus = "ACTIVE" | "REVOKED";
+export type DcdrServiceTokenSnapshotItem = {
+    /** Human-friendly identifier ("ci-pipeline", "mobile-app", etc.). */
+    id: string;
+    /** SHA-256 hash of the full bearer token string (hex). */
+    sha256: string;
+    status: DcdrServiceTokenStatus;
+    /** Token scopes as understood by the gateway (should match or superset payload.scopes policy). */
+    scopes: string[];
+    /** Optional snapshot-side expiry hint (unix ms). Token exp enforcement remains the token payload exp. */
+    exp?: number;
+    /** Optional note for operators. */
+    note?: string;
+};
+export type DcdrServiceTokensSnapshotContract = {
+    cid: string;
+    tokens: DcdrServiceTokenSnapshotItem[];
+    /** Snapshot issued at (unix ms). Optional. */
+    iat?: number;
+};
+//# sourceMappingURL=service-tokens.contract.d.ts.map

package/dist/service-tokens.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-tokens.contract.d.ts","sourceRoot":"","sources":["../src/service-tokens.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,4BAA4B,GAAG;IACzC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IAEX,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IAEf,MAAM,EAAE,sBAAsB,CAAC;IAE/B,kGAAkG;IAClG,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,yGAAyG;IACzG,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,4BAA4B,EAAE,CAAC;IACvC,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC"}

package/dist/service-tokens.contract.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Snapshot of allowed (and revoked) customer service tokens.
+ *
+ * IMPORTANT:
+ * - Never include tokens in clear.
+ * - Tokens are referenced by sha256(utf8(tokenString)) in hex.
+ * - Backend should keep this snapshot stable & ordered for reproducible ETags.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/session.contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic session token payload for dcdr.
+ * - id: session id (e.g. missionId)
+ * - aid: app id (e.g. scraperId)
+ */
+export interface DcdrSessionPayload {
+    id: string;
+    aid: string;
+    cid?: string;
+    iat: number;
+    exp: number;
+    /**
+     * Allowed scopes for this session token.
+     *
+     * Notes
+     * - Scopes are treated as opaque strings by the token format; semantics are enforced by the runtime.
+     * - The runtime may require execution scopes for `/api/execution/*` endpoints.
+     *
+     * Common scope forms
+     * - `execute:*` to allow executing any intent
+     * - `execute:<INTENT>` to allow a specific intent
+     * - Legacy (backward compatible): include the intent name itself (e.g. `BANKING_INCIDENT_CLASSIFIER`).
+     * - `*` grants full access.
+     */
+    scopes: string[];
+}
+/**
+ * Crypto dependencies injected from Node runtimes (backend/dcdr).
+ * This avoids importing "crypto" in shared libs that may be bundled for web.
+ */
+export interface HmacDeps {
+    createHmac: (alg: "sha256", key: string) => {
+        update: (data: string) => any;
+        digest: (encoding: "base64") => string;
+    };
+    timingSafeEqual?: (a: Uint8Array, b: Uint8Array) => boolean;
+}
+/**
+ * Token format:
+ *   token = base64url(JSON(payload)) + "." + base64url(HMAC_SHA256(secret, payloadB64url))
+ */
+export declare class DcdrSessionToken {
+    static sign(deps: HmacDeps, payload: DcdrSessionPayload, secret: string): string;
+    static verify(deps: HmacDeps, token: string, secrets: string[] | string, opts?: {
+        clockSkewSeconds?: number;
+        revokeBeforeIat?: number;
+    }): DcdrSessionPayload;
+    static decodeUnverified(token: string): DcdrSessionPayload;
+    private static assertValidPayload;
+}
+//# sourceMappingURL=session.contract.d.ts.map

package/dist/session.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.contract.d.ts","sourceRoot":"","sources":["../src/session.contract.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,CACV,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,KACR;QACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC;QAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC;KACxC,CAAC;IACF,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC;CAC7D;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,MAAM,CAAC,IAAI,CACT,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,GACb,MAAM;IAeT,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAC1B,IAAI,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,kBAAkB;IAsDrB,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB;IAa1D,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAoBlC"}