@dcdr/contracts 1.9.6

package/dist/session.contract.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DcdrSessionToken = void 0;
+/**
+ * Token format:
+ *   token = base64url(JSON(payload)) + "." + base64url(HMAC_SHA256(secret, payloadB64url))
+ */
+class DcdrSessionToken {
+    static sign(deps, payload, secret) {
+        this.assertValidPayload(payload);
+        const payloadJson = JSON.stringify(payload);
+        const payloadB64url = base64urlEncode(utf8ToBytes(payloadJson));
+        const sigB64 = deps
+            .createHmac("sha256", secret)
+            .update(payloadB64url)
+            .digest("base64");
+        const sigB64url = base64ToBase64url(sigB64);
+        return `${payloadB64url}.${sigB64url}`;
+    }
+    static verify(deps, token, secrets, opts) {
+        const secretsArr = Array.isArray(secrets) ? secrets : [secrets];
+        const clockSkewMilliseconds = (opts?.clockSkewSeconds ?? 30) * 1000;
+        if (!token || typeof token !== "string")
+            throw new Error("TOKEN_MISSING");
+        const parts = token.split(".");
+        if (parts.length !== 2)
+            throw new Error("TOKEN_FORMAT_INVALID");
+        const [payloadB64url, sigB64url] = parts;
+        if (!payloadB64url || !sigB64url)
+            throw new Error("TOKEN_FORMAT_INVALID");
+        const sigB64 = base64urlToBase64(sigB64url);
+        // Verify signature against any allowed secret (rotation)
+        let ok = false;
+        for (const secret of secretsArr) {
+            const expectedB64 = deps
+                .createHmac("sha256", secret)
+                .update(payloadB64url)
+                .digest("base64");
+            if (safeEqualBase64(deps, expectedB64, sigB64)) {
+                ok = true;
+                break;
+            }
+        }
+        if (!ok)
+            throw new Error("TOKEN_SIGNATURE_INVALID");
+        // Decode payload
+        const payloadJson = bytesToUtf8(base64urlDecodeToBytes(payloadB64url));
+        const payload = normalizePayloadTimes(JSON.parse(payloadJson));
+        this.assertValidPayload(payload);
+        // Time checks (unix milliseconds)
+        const now = Date.now();
+        if (opts?.revokeBeforeIat && payload.iat < opts.revokeBeforeIat) {
+            throw new Error("TOKEN_REVOKED");
+        }
+        if (payload.iat > now + clockSkewMilliseconds) {
+            throw new Error("TOKEN_IAT_IN_FUTURE");
+        }
+        if (payload.exp < now - clockSkewMilliseconds) {
+            throw new Error("TOKEN_EXPIRED");
+        }
+        return payload;
+    }
+    static decodeUnverified(token) {
+        const [payloadB64url] = (token ?? "").split(".");
+        if (!payloadB64url)
+            throw new Error("TOKEN_FORMAT_INVALID");
+        const payloadJson = bytesToUtf8(base64urlDecodeToBytes(payloadB64url));
+        const payload = normalizePayloadTimes(JSON.parse(payloadJson));
+        this.assertValidPayload(payload);
+        return payload;
+    }
+    static assertValidPayload(p) {
+        if (!p || typeof p !== "object")
+            throw new Error("PAYLOAD_INVALID");
+        if (!p.id || typeof p.id !== "string")
+            throw new Error("PAYLOAD_ID_INVALID");
+        if (!p.aid || typeof p.aid !== "string")
+            throw new Error("PAYLOAD_AID_INVALID");
+        if (typeof p.iat !== "number" || !Number.isFinite(p.iat))
+            throw new Error("PAYLOAD_IAT_INVALID");
+        if (typeof p.exp !== "number" || !Number.isFinite(p.exp))
+            throw new Error("PAYLOAD_EXP_INVALID");
+        if (!Array.isArray(p.scopes) ||
+            p.scopes.some((s) => typeof s !== "string" || !s)) {
+            throw new Error("PAYLOAD_SCOPES_INVALID");
+        }
+    }
+}
+exports.DcdrSessionToken = DcdrSessionToken;
+function normalizePayloadTimes(p) {
+    // Accept legacy unix seconds timestamps: heuristic based on magnitude.
+    // - unix seconds in 2026 ~ 1.7e9
+    // - unix milliseconds in 2026 ~ 1.7e12
+    const normalize = (n) => {
+        if (!Number.isFinite(n))
+            return n;
+        if (n < 100_000_000_000)
+            return Math.floor(n * 1000); // likely seconds
+        return Math.floor(n); // milliseconds
+    };
+    if (p && typeof p === "object") {
+        p.iat = normalize(p.iat);
+        p.exp = normalize(p.exp);
+    }
+    return p;
+}
+// -------------------------------------------------------------------------------------
+// Internal helpers (no direct "crypto" import)
+// -------------------------------------------------------------------------------------
+function safeEqualBase64(deps, aB64, bB64) {
+    if (aB64.length !== bB64.length)
+        return false;
+    if (deps.timingSafeEqual) {
+        const a = base64DecodeToBytes(aB64);
+        const b = base64DecodeToBytes(bB64);
+        if (a.length !== b.length)
+            return false;
+        return deps.timingSafeEqual(a, b);
+    }
+    // Fallback: normal compare (OK for internal usage)
+    return aB64 === bB64;
+}
+function base64ToBase64url(b64) {
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64urlToBase64(b64url) {
+    const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - (b64.length % 4)) % 4;
+    return b64 + "=".repeat(pad);
+}
+function base64urlEncode(bytes) {
+    return base64ToBase64url(base64Encode(bytes));
+}
+function base64urlDecodeToBytes(b64url) {
+    return base64DecodeToBytes(base64urlToBase64(b64url));
+}
+function base64Encode(bytes) {
+    // Node runtime (dynamic access avoids bundler static detection)
+    const g = globalThis;
+    if (g.Buffer && typeof g.Buffer.from === "function") {
+        return g.Buffer.from(bytes).toString("base64");
+    }
+    // Browser fallback
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    // eslint-disable-next-line no-undef
+    return btoa(bin);
+}
+function base64DecodeToBytes(b64) {
+    // Node runtime (dynamic access avoids bundler static detection)
+    const g = globalThis;
+    if (g.Buffer && typeof g.Buffer.from === "function") {
+        return new Uint8Array(g.Buffer.from(b64, "base64"));
+    }
+    // Browser fallback
+    // eslint-disable-next-line no-undef
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function utf8ToBytes(s) {
+    // Prefer standard API first (works in modern Node and browsers)
+    // eslint-disable-next-line no-undef
+    if (typeof TextEncoder !== "undefined")
+        return new TextEncoder().encode(s);
+    // Node fallback without referencing Buffer symbol directly
+    const g = globalThis;
+    if (g.Buffer && typeof g.Buffer.from === "function") {
+        return new Uint8Array(g.Buffer.from(s, "utf8"));
+    }
+    throw new Error("UTF8_ENCODER_UNAVAILABLE");
+}
+function bytesToUtf8(bytes) {
+    // Prefer standard API first (works in modern Node and browsers)
+    // eslint-disable-next-line no-undef
+    if (typeof TextDecoder !== "undefined")
+        return new TextDecoder("utf-8").decode(bytes);
+    // Node fallback without referencing Buffer symbol directly
+    const g = globalThis;
+    if (g.Buffer && typeof g.Buffer.from === "function") {
+        return g.Buffer.from(bytes).toString("utf8");
+    }
+    throw new Error("UTF8_DECODER_UNAVAILABLE");
+}

package/dist/subscription.contract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subscription/contract status for customer entitlements.
+ *
+ * Notes
+ * - Kept in contracts to avoid scattering status lists across services.
+ * - This aligns with backend contract lifecycle, but uses a generic name to reduce collisions.
+ */
+export declare enum SubscriptionStatus {
+    DRAFT = "DRAFT",
+    TRIAL = "TRIAL",
+    ACTIVE = "ACTIVE",
+    ENDED = "ENDED",
+    SUSPENDED = "SUSPENDED",
+    CANCELED = "CANCELED"
+}
+/**
+ * Centralized policy helpers for {@link SubscriptionStatus}.
+ */
+export declare class SubscriptionStatusPolicy {
+    /**
+     * Returns the statuses that are considered valid for a contract to exist for downstream consumers.
+     *
+     * Notes
+     * - Some surfaces (e.g. BI) may allow ENDED contracts to remain visible.
+     * - Keep this centralized to avoid scattering status lists across the codebase.
+     */
+    static validStatuses(): SubscriptionStatus[];
+    /**
+     * Returns the statuses that are considered valid to show *current* data.
+     *
+     * Notes
+     * - This excludes ENDED/SUSPENDED/CANCELED.
+     * - Keep this centralized to avoid scattering status lists across the codebase.
+     */
+    static validStatusesToShowCurrentData(): SubscriptionStatus[];
+}
+//# sourceMappingURL=subscription.contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.contract.d.ts","sourceRoot":"","sources":["../src/subscription.contract.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oBAAY,kBAAkB;IAC5B,KAAK,UAAU;IACf,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,qBAAa,wBAAwB;IACnC;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,IAAI,kBAAkB,EAAE;IAI5C;;;;;;OAMG;IACH,MAAM,CAAC,8BAA8B,IAAI,kBAAkB,EAAE;CAG9D"}

package/dist/subscription.contract.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionStatusPolicy = exports.SubscriptionStatus = void 0;
+/**
+ * Subscription/contract status for customer entitlements.
+ *
+ * Notes
+ * - Kept in contracts to avoid scattering status lists across services.
+ * - This aligns with backend contract lifecycle, but uses a generic name to reduce collisions.
+ */
+var SubscriptionStatus;
+(function (SubscriptionStatus) {
+    SubscriptionStatus["DRAFT"] = "DRAFT";
+    SubscriptionStatus["TRIAL"] = "TRIAL";
+    SubscriptionStatus["ACTIVE"] = "ACTIVE";
+    SubscriptionStatus["ENDED"] = "ENDED";
+    SubscriptionStatus["SUSPENDED"] = "SUSPENDED";
+    SubscriptionStatus["CANCELED"] = "CANCELED";
+})(SubscriptionStatus || (exports.SubscriptionStatus = SubscriptionStatus = {}));
+/**
+ * Centralized policy helpers for {@link SubscriptionStatus}.
+ */
+class SubscriptionStatusPolicy {
+    /**
+     * Returns the statuses that are considered valid for a contract to exist for downstream consumers.
+     *
+     * Notes
+     * - Some surfaces (e.g. BI) may allow ENDED contracts to remain visible.
+     * - Keep this centralized to avoid scattering status lists across the codebase.
+     */
+    static validStatuses() {
+        return [SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIAL, SubscriptionStatus.ENDED];
+    }
+    /**
+     * Returns the statuses that are considered valid to show *current* data.
+     *
+     * Notes
+     * - This excludes ENDED/SUSPENDED/CANCELED.
+     * - Keep this centralized to avoid scattering status lists across the codebase.
+     */
+    static validStatusesToShowCurrentData() {
+        return [SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIAL];
+    }
+}
+exports.SubscriptionStatusPolicy = SubscriptionStatusPolicy;

package/dist/utils.contract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared utilities for `@dcdr/contracts`.
+ */
+/**
+ * Stable JSON stringify with deterministic object key ordering.
+ *
+ * Why
+ * - Used to compute semantic hashes over JSON payloads (e.g. registries) in a
+ *   way that is invariant to JavaScript object insertion order.
+ * - Arrays preserve order.
+ * - Object keys are sorted lexicographically (recursively).
+ *
+ * Semantics (intentionally mirrors JSON.stringify behavior where relevant)
+ * - Object properties with values `undefined`, functions, or symbols are omitted.
+ * - Array slots with `undefined`, functions, or symbols become `null`.
+ * - `bigint` is serialized as a JSON string.
+ * - `toJSON()` is honored.
+ * - Circular references throw.
+ */
+export declare function stableJsonStringify(value: unknown): string;
+//# sourceMappingURL=utils.contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.contract.d.ts","sourceRoot":"","sources":["../src/utils.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmE1D"}

package/dist/utils.contract.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Shared utilities for `@dcdr/contracts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableJsonStringify = stableJsonStringify;
+/**
+ * Stable JSON stringify with deterministic object key ordering.
+ *
+ * Why
+ * - Used to compute semantic hashes over JSON payloads (e.g. registries) in a
+ *   way that is invariant to JavaScript object insertion order.
+ * - Arrays preserve order.
+ * - Object keys are sorted lexicographically (recursively).
+ *
+ * Semantics (intentionally mirrors JSON.stringify behavior where relevant)
+ * - Object properties with values `undefined`, functions, or symbols are omitted.
+ * - Array slots with `undefined`, functions, or symbols become `null`.
+ * - `bigint` is serialized as a JSON string.
+ * - `toJSON()` is honored.
+ * - Circular references throw.
+ */
+function stableJsonStringify(value) {
+    const seen = new Set();
+    const walk = (v) => {
+        if (v === null)
+            return "null";
+        const t = typeof v;
+        if (t === "string" || t === "number" || t === "boolean") {
+            return JSON.stringify(v);
+        }
+        if (t === "bigint")
+            return JSON.stringify(v.toString());
+        if (t === "undefined" || t === "function" || t === "symbol") {
+            // Match JSON.stringify behavior for array slots.
+            return "null";
+        }
+        if (typeof v === "object") {
+            const maybeToJson = v.toJSON;
+            if (typeof maybeToJson === "function") {
+                return walk(maybeToJson.call(v));
+            }
+        }
+        if (Array.isArray(v)) {
+            if (seen.has(v)) {
+                throw new Error("stableJsonStringify: circular reference");
+            }
+            // Arrays are objects in JS; safe to track for circular refs.
+            seen.add(v);
+            const out = `[${v.map((item) => walk(item)).join(",")}]`;
+            seen.delete(v);
+            return out;
+        }
+        if (t === "object") {
+            if (seen.has(v)) {
+                throw new Error("stableJsonStringify: circular reference");
+            }
+            seen.add(v);
+            const obj = v;
+            const keys = Object.keys(obj).sort();
+            const parts = [];
+            for (const key of keys) {
+                const next = obj[key];
+                const nextType = typeof next;
+                if (nextType === "undefined" ||
+                    nextType === "function" ||
+                    nextType === "symbol") {
+                    continue;
+                }
+                parts.push(`${JSON.stringify(key)}:${walk(next)}`);
+            }
+            const out = `{${parts.join(",")}}`;
+            seen.delete(v);
+            return out;
+        }
+        return JSON.stringify(v);
+    };
+    return walk(value);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dcdr/contracts",
+  "version": "1.9.6",
+  "description": "Interfaces for Dcdr Platform",
+  "private": false,
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "check": "tsc --noEmit",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build && jest",
+    "test:ci": "npm run build && jest --runInBand"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.3.0",
+    "jest-junit": "^16.0.0",
+    "ts-jest": "^29.4.9",
+    "typescript": "^5.7.2"
+  },
+  "volta": {
+    "node": "22.22.0"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./runtime.client": "./dist/runtime.client.js",
+    "./capabilities.contract": "./dist/capabilities.contract.js",
+    "./control.contract": "./dist/control.contract.js",
+    "./credentials.contract": "./dist/credentials.contract.js",
+    "./subscription.contract": "./dist/subscription.contract.js",
+    "./utils.contract": "./dist/utils.contract.js",
+    "./prompt-variable-schema.contract": "./dist/prompt-variable-schema.contract.js",
+    "./registry.stats.contract": "./dist/registry.stats.contract.js",
+    "./http.contract": "./dist/http.contract.js",
+    "./entitlements.contract": "./dist/entitlements.contract.js",
+    "./errors.contract": "./dist/errors.contract.js",
+    "./execution.contract": "./dist/execution.contract.js",
+    "./implementations.contract": "./dist/implementations.contract.js",
+    "./intent.contract": "./dist/intent.contract.js",
+    "./logs.contract": "./dist/logs.contract.js",
+    "./messages.contract": "./dist/messages.contract.js",
+    "./policies.contract": "./dist/policies.contract.js",
+    "./prompts.contract": "./dist/prompts.contract.js",
+    "./provider.contract": "./dist/provider.contract.js",
+    "./service-tokens.contract": "./dist/service-tokens.contract.js",
+    "./session.contract": "./dist/session.contract.js"
+  },
+  "dependencies": {
+    "class-validator": "^0.15.1"
+  }
+}