@vauban-org/agent-sdk 0.16.0

package/dist/ports/messaging.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.contract.test.d.ts","sourceRoot":"","sources":["../../src/ports/messaging.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAc3D;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,oBAAoB,EACnC,IAAI,GAAE;IACJ,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;CACV,GACL,IAAI,CA2DN"}

package/dist/ports/messaging.contract.test.js

@@ -0,0 +1,296 @@
+/**
+ * MessagingChannelPort contract test suite.
+ *
+ * Applied to all 5 adapters: Telegram, Slack, Discord, Console, MCP.
+ * HTTP adapters use vitest mock fetch — no real API calls.
+ *
+ * sprint-615:quick-2
+ */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { InvalidTargetError } from "./messaging.js";
+import { TelegramChannel, TelegramRateLimitError, } from "../adapters/messaging/telegram.js";
+import { SlackChannel } from "../adapters/messaging/slack.js";
+import { DiscordChannel } from "../adapters/messaging/discord.js";
+import { ConsoleChannel } from "../adapters/messaging/console.js";
+import { MCPChannel } from "../adapters/messaging/mcp.js";
+// ─── Contract suite ───────────────────────────────────────────────────────────
+/**
+ * Shared contract applied to every MessagingChannelPort implementation.
+ *
+ * @param factory - Returns a fresh adapter instance for each test.
+ * @param opts    - Per-adapter overrides for special cases.
+ */
+export function messagingChannelContract(factory, opts = {}) {
+    describe(`MessagingChannelPort contract${opts.name ? ` — ${opts.name}` : ""}`, () => {
+        test("sendAlert critical formats title prominently", async () => {
+            // Verify the adapter does not throw and the level is communicated
+            const channel = factory();
+            // No throw = correct; we capture output via mock in per-adapter tests
+            await expect(channel.sendAlert("critical", "System down", "All services unreachable")).resolves.toBeUndefined();
+        });
+        test("sendAlert info|warn|error|critical all callable without throw", async () => {
+            const channel = factory();
+            await expect(channel.sendAlert("info", "T", "B")).resolves.toBeUndefined();
+            await expect(channel.sendAlert("warn", "T", "B")).resolves.toBeUndefined();
+            await expect(channel.sendAlert("error", "T", "B")).resolves.toBeUndefined();
+            await expect(channel.sendAlert("critical", "T", "B")).resolves.toBeUndefined();
+        });
+        test("sendMessage with valid target succeeds", async () => {
+            const channel = factory();
+            await expect(channel.sendMessage("target-123", "hello")).resolves.toBeUndefined();
+        });
+        test("sendMessage with empty target throws InvalidTargetError", async () => {
+            const channel = factory();
+            await expect(channel.sendMessage("", "hello")).rejects.toThrow(InvalidTargetError);
+        });
+        test("sendMessage with whitespace-only target throws InvalidTargetError", async () => {
+            const channel = factory();
+            await expect(channel.sendMessage("   ", "hello")).rejects.toThrow(InvalidTargetError);
+        });
+        if (!opts.skipRateLimit) {
+            test("rate limit handling returns or throws clear error (no silent drop)", async () => {
+                // Each adapter suite overrides fetch to return 429 — verified there
+                // This baseline ensures the contract documents the requirement.
+                // Per-adapter tests exercise the actual throw path.
+                expect(true).toBe(true);
+            });
+        }
+    });
+}
+// ─── Telegram ─────────────────────────────────────────────────────────────────
+describe("TelegramChannel", () => {
+    beforeEach(() => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({ ok: true, result: { message_id: 1 } }),
+        }));
+    });
+    messagingChannelContract(() => new TelegramChannel({
+        botToken: "test-token",
+        defaultChatId: "123456",
+    }), { name: "TelegramChannel" });
+    test("sendAlert posts to Telegram API with correct level emoji", async () => {
+        const channel = new TelegramChannel({
+            botToken: "tok",
+            defaultChatId: "42",
+        });
+        await channel.sendAlert("critical", "Down", "All gone");
+        expect(vi.mocked(fetch)).toHaveBeenCalledOnce();
+        const [url, init] = vi.mocked(fetch).mock.calls[0];
+        expect(url).toContain("/bot tok/sendMessage");
+        const body = JSON.parse(init.body);
+        expect(body["chat_id"]).toBe("42");
+        expect(body["text"]).toContain("🚨");
+        expect(body["text"]).toContain("CRITICAL");
+    });
+    test("sendMessage uses target as chat_id", async () => {
+        const channel = new TelegramChannel({ botToken: "tok" });
+        await channel.sendMessage("@mychannel", "hi");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body["chat_id"]).toBe("@mychannel");
+    });
+    test("sendAlert throws InvalidTargetError when no defaultChatId", async () => {
+        const channel = new TelegramChannel({ botToken: "tok" });
+        await expect(channel.sendAlert("info", "T", "B")).rejects.toThrow(InvalidTargetError);
+    });
+    test("rate limit (429) throws TelegramRateLimitError", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+            ok: false,
+            status: 429,
+            json: async () => ({ parameters: { retry_after: 30 } }),
+        }));
+        const channel = new TelegramChannel({
+            botToken: "tok",
+            defaultChatId: "42",
+        });
+        await expect(channel.sendAlert("info", "T", "B")).rejects.toThrow(TelegramRateLimitError);
+    });
+});
+// ─── Slack ────────────────────────────────────────────────────────────────────
+describe("SlackChannel", () => {
+    beforeEach(() => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            text: async () => "ok",
+        }));
+    });
+    messagingChannelContract(() => new SlackChannel({ webhookUrl: "https://hooks.slack.com/test" }), { name: "SlackChannel" });
+    test("sendAlert posts Block Kit attachment with correct color", async () => {
+        const channel = new SlackChannel({
+            webhookUrl: "https://hooks.slack.com/test",
+        });
+        await channel.sendAlert("warn", "Watch out", "Details here");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body.attachments[0].color).toBe("warning");
+        expect(body.attachments[0].title).toContain("WARN");
+        expect(body.attachments[0].title).toContain("⚠️");
+    });
+    test("sendMessage prepends target to text", async () => {
+        const channel = new SlackChannel({
+            webhookUrl: "https://hooks.slack.com/test",
+        });
+        await channel.sendMessage("general", "hello team");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body.text).toContain("general");
+        expect(body.text).toContain("hello team");
+    });
+    test("rate limit (429) throws with clear message", async () => {
+        vi.stubGlobal("fetch", vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 429, text: async () => "" }));
+        const channel = new SlackChannel({
+            webhookUrl: "https://hooks.slack.com/test",
+        });
+        await expect(channel.sendAlert("info", "T", "B")).rejects.toThrow(/rate limit/i);
+    });
+});
+// ─── Discord ──────────────────────────────────────────────────────────────────
+describe("DiscordChannel", () => {
+    beforeEach(() => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+            ok: true,
+            status: 204,
+            text: async () => "",
+        }));
+    });
+    messagingChannelContract(() => new DiscordChannel({
+        webhookUrl: "https://discord.com/api/webhooks/test",
+    }), { name: "DiscordChannel" });
+    test("sendAlert posts embed with correct color for info", async () => {
+        const channel = new DiscordChannel({
+            webhookUrl: "https://discord.com/api/webhooks/test",
+        });
+        await channel.sendAlert("info", "Hello", "World");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body.embeds[0].color).toBe(0x3498db);
+        expect(body.embeds[0].title).toContain("INFO");
+        expect(body.embeds[0].title).toContain("ℹ️");
+    });
+    test("sendAlert critical uses 0xff0000 color", async () => {
+        const channel = new DiscordChannel({
+            webhookUrl: "https://discord.com/api/webhooks/test",
+        });
+        await channel.sendAlert("critical", "FATAL", "System down");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body.embeds[0].color).toBe(0xff0000);
+    });
+    test("sendMessage includes target as context label", async () => {
+        const channel = new DiscordChannel({
+            webhookUrl: "https://discord.com/api/webhooks/test",
+        });
+        await channel.sendMessage("ops-team", "deploy done");
+        const [, init] = vi.mocked(fetch).mock.calls[0];
+        const body = JSON.parse(init.body);
+        expect(body.content).toContain("ops-team");
+        expect(body.content).toContain("deploy done");
+    });
+    test("rate limit (429) throws with clear message", async () => {
+        vi.stubGlobal("fetch", vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 429, text: async () => "" }));
+        const channel = new DiscordChannel({
+            webhookUrl: "https://discord.com/api/webhooks/test",
+        });
+        await expect(channel.sendAlert("info", "T", "B")).rejects.toThrow(/rate limit/i);
+    });
+});
+// ─── Console ──────────────────────────────────────────────────────────────────
+describe("ConsoleChannel", () => {
+    function makeMockStream() {
+        let buf = "";
+        const stream = {
+            write: (data) => {
+                buf += data;
+                return true;
+            },
+        };
+        return { stream, output: () => buf };
+    }
+    messagingChannelContract(() => new ConsoleChannel(), {
+        name: "ConsoleChannel",
+    });
+    test("sendAlert writes [LEVEL] tag with ANSI codes", async () => {
+        const { stream, output } = makeMockStream();
+        const channel = new ConsoleChannel({ stream });
+        await channel.sendAlert("error", "Crash", "Segfault");
+        expect(output()).toContain("[ERROR]");
+        expect(output()).toContain("Crash");
+        expect(output()).toContain("Segfault");
+        // ANSI reset code present
+        expect(output()).toContain("\x1b[0m");
+    });
+    test("sendAlert critical uses bold+red ANSI", async () => {
+        const { stream, output } = makeMockStream();
+        const channel = new ConsoleChannel({ stream });
+        await channel.sendAlert("critical", "FATAL", "boom");
+        expect(output()).toContain("\x1b[1m\x1b[31m");
+        expect(output()).toContain("[CRITICAL]");
+    });
+    test("sendMessage writes MSG→target prefix", async () => {
+        const { stream, output } = makeMockStream();
+        const channel = new ConsoleChannel({ stream });
+        await channel.sendMessage("ops", "hello");
+        expect(output()).toContain("[MSG→ops]");
+        expect(output()).toContain("hello");
+    });
+    test("constructor with no args uses process.stdout (no throw)", () => {
+        expect(() => new ConsoleChannel()).not.toThrow();
+    });
+    // ConsoleChannel has no HTTP calls — skip rate limit test
+});
+// ─── MCPChannel ───────────────────────────────────────────────────────────────
+describe("MCPChannel", () => {
+    function makeMockClient() {
+        const calls = [];
+        const client = {
+            callTool: async (name, args) => {
+                calls.push({ name, args });
+                return { ok: true };
+            },
+        };
+        return { client, calls };
+    }
+    messagingChannelContract(() => {
+        const { client } = makeMockClient();
+        return new MCPChannel({
+            mcpClient: client,
+            toolName: "send_notification",
+        });
+    }, { name: "MCPChannel" });
+    test("sendAlert calls mcpClient.callTool with level/title/body", async () => {
+        const { client, calls } = makeMockClient();
+        const channel = new MCPChannel({ mcpClient: client, toolName: "notify" });
+        await channel.sendAlert("critical", "Down", "All gone");
+        expect(calls).toHaveLength(1);
+        expect(calls[0].name).toBe("notify");
+        expect(calls[0].args).toEqual({
+            level: "critical",
+            title: "Down",
+            body: "All gone",
+        });
+    });
+    test("sendMessage calls mcpClient.callTool with target/text", async () => {
+        const { client, calls } = makeMockClient();
+        const channel = new MCPChannel({ mcpClient: client, toolName: "notify" });
+        await channel.sendMessage("ops", "deploy done");
+        expect(calls).toHaveLength(1);
+        expect(calls[0].args).toEqual({ target: "ops", text: "deploy done" });
+    });
+    test("rate limit: callTool rejection propagates as clear error (no silent drop)", async () => {
+        const client = {
+            callTool: async () => {
+                throw new Error("MCP tool error: 429 rate limit");
+            },
+        };
+        const channel = new MCPChannel({ mcpClient: client, toolName: "notify" });
+        await expect(channel.sendAlert("info", "T", "B")).rejects.toThrow(/429 rate limit/);
+    });
+});
+//# sourceMappingURL=messaging.contract.test.js.map

package/dist/ports/messaging.contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.contract.test.js","sourceRoot":"","sources":["../../src/ports/messaging.contract.test.ts"],"names":[],"mappings":"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"}

package/dist/ports/messaging.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MessagingChannelPort — SDK v0.16.0 (sprint-615:quick-2)
+ *
+ * Generic channel abstraction for alerts and messages.
+ * HITL (human-in-the-loop approval) is intentionally excluded;
+ * that belongs to HITLPort per plan v6 §3.5.
+ *
+ * @public
+ */
+/** Alert severity levels, ordered by escalation. */
+export type AlertLevel = "info" | "warn" | "error" | "critical";
+/**
+ * Port for sending alerts and messages via any channel.
+ *
+ * Implementations: TelegramChannel, SlackChannel, DiscordChannel,
+ * ConsoleChannel, MCPChannel.
+ *
+ * @public
+ */
+export interface MessagingChannelPort {
+    /**
+     * Send a structured alert to the default channel for this adapter.
+     *
+     * @param level - Severity: info < warn < error < critical
+     * @param title - Short summary (shown prominently)
+     * @param body  - Detailed message body
+     */
+    sendAlert(level: AlertLevel, title: string, body: string): Promise<void>;
+    /**
+     * Send a free-form message to a specific target (channel, chat, user).
+     *
+     * @param target - Channel/chat/user identifier (adapter-specific format)
+     * @param text   - Message content
+     * @throws {InvalidTargetError} If target is empty or invalid
+     */
+    sendMessage(target: string, text: string): Promise<void>;
+}
+/**
+ * Thrown when `target` is empty or structurally invalid for the adapter.
+ *
+ * @public
+ */
+export declare class InvalidTargetError extends Error {
+    readonly target: string;
+    constructor(message: string, target: string);
+}
+//# sourceMappingURL=messaging.d.ts.map

package/dist/ports/messaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../src/ports/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aACE,MAAM,EAAE,MAAM;gBAA/C,OAAO,EAAE,MAAM,EAAkB,MAAM,EAAE,MAAM;CAK5D"}

package/dist/ports/messaging.js

@@ -0,0 +1,24 @@
+/**
+ * MessagingChannelPort — SDK v0.16.0 (sprint-615:quick-2)
+ *
+ * Generic channel abstraction for alerts and messages.
+ * HITL (human-in-the-loop approval) is intentionally excluded;
+ * that belongs to HITLPort per plan v6 §3.5.
+ *
+ * @public
+ */
+/**
+ * Thrown when `target` is empty or structurally invalid for the adapter.
+ *
+ * @public
+ */
+export class InvalidTargetError extends Error {
+    target;
+    constructor(message, target) {
+        super(message);
+        this.target = target;
+        this.name = "InvalidTargetError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=messaging.js.map

package/dist/ports/messaging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../src/ports/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiCH;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACE;IAA7C,YAAY,OAAe,EAAkB,MAAc;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,WAAM,GAAN,MAAM,CAAQ;QAEzD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/ports/outcome.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OutcomePort — post-run outcome instrumentation.
+ *
+ * Host attributes a monetary value to each agent run via its
+ * domain-specific rules (config/outcomes.yaml in CC). The agent simply
+ * calls recordOutcomeAsync after its tracker.finish() — fire-and-forget.
+ */
+export interface AgentRunRef {
+    /** agent_run.id (UUID) produced by AgentRunTracker. */
+    id: string;
+    /** Logical agent identity, matches AgentDescriptor.id. */
+    agent_id: string;
+    /** Hash / caller-generated run id for trace correlation. */
+    run_id?: string;
+    /** Already-linked outcome id; idempotency guard. */
+    outcome_id?: string | null;
+}
+export interface OutcomePort {
+    /**
+     * Enqueue outcome attribution. Fire-and-forget: never throws,
+     * never blocks the agent lifecycle. Errors are logged by the impl.
+     */
+    recordOutcomeAsync(run: AgentRunRef): void;
+}
+//# sourceMappingURL=outcome.d.ts.map

package/dist/ports/outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../src/ports/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5C"}

package/dist/ports/outcome.js

@@ -0,0 +1,9 @@
+/**
+ * OutcomePort — post-run outcome instrumentation.
+ *
+ * Host attributes a monetary value to each agent run via its
+ * domain-specific rules (config/outcomes.yaml in CC). The agent simply
+ * calls recordOutcomeAsync after its tracker.finish() — fire-and-forget.
+ */
+export {};
+//# sourceMappingURL=outcome.js.map

package/dist/ports/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../src/ports/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/ports/timestamp.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TimestampPort — RFC 3161 TSA interface for the agent-sdk core.
+ *
+ * R8-B1 constraint: only the interface + NullTimestampPort live here.
+ * Concrete adapters (FreeTSAAdapter, etc.) and all ASN.1/DER/PKCS#7
+ * parsing belong in `@vauban-org/agent-sdk-verify` (external package).
+ *
+ * @module ports/timestamp
+ */
+import type { SignedReceipt } from "../trace/schema.js";
+/**
+ * Port for requesting and verifying RFC 3161 TSA timestamps.
+ * Injected by the host at boot time.
+ */
+export interface TimestampPort {
+    /**
+     * Request a signed timestamp for `rootHash` from a TSA.
+     *
+     * @param rootHash - Hex-encoded SHA-256 root hash to timestamp.
+     * @returns Resolved SignedReceipt on success.
+     * @throws On TSA communication failure or rejection.
+     */
+    request(rootHash: string): Promise<SignedReceipt>;
+    /**
+     * Verify a receipt locally against `rootHash`.
+     * MUST NOT require an online OCSP check — offline verification only.
+     *
+     * @param receipt  - The SignedReceipt to verify.
+     * @param rootHash - Expected hex-encoded SHA-256 root hash.
+     * @returns { valid: true } on success or { valid: false, reason } on failure.
+     */
+    verify(receipt: SignedReceipt, rootHash: string): Promise<{
+        valid: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * No-op TimestampPort for tests and development.
+ *
+ * `request()` always throws — configure a real TimestampPort
+ * (e.g. `FreeTSAAdapter` from `@vauban-org/agent-sdk-verify`) for production.
+ *
+ * `verify()` always returns `{ valid: false }` — it cannot verify receipts
+ * it never issued.
+ */
+export declare class NullTimestampPort implements TimestampPort {
+    request(_rootHash: string): Promise<SignedReceipt>;
+    verify(_receipt: SignedReceipt, _rootHash: string): Promise<{
+        valid: boolean;
+        reason: string;
+    }>;
+}
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/ports/timestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../src/ports/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElD;;;;;;;OAOG;IACH,MAAM,CACJ,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAOlD,MAAM,CACV,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAG/C"}

package/dist/ports/timestamp.js

@@ -0,0 +1,28 @@
+/**
+ * TimestampPort — RFC 3161 TSA interface for the agent-sdk core.
+ *
+ * R8-B1 constraint: only the interface + NullTimestampPort live here.
+ * Concrete adapters (FreeTSAAdapter, etc.) and all ASN.1/DER/PKCS#7
+ * parsing belong in `@vauban-org/agent-sdk-verify` (external package).
+ *
+ * @module ports/timestamp
+ */
+/**
+ * No-op TimestampPort for tests and development.
+ *
+ * `request()` always throws — configure a real TimestampPort
+ * (e.g. `FreeTSAAdapter` from `@vauban-org/agent-sdk-verify`) for production.
+ *
+ * `verify()` always returns `{ valid: false }` — it cannot verify receipts
+ * it never issued.
+ */
+export class NullTimestampPort {
+    async request(_rootHash) {
+        throw new Error("NullTimestampPort: configure a real TimestampPort " +
+            "(e.g., FreeTSAAdapter from @vauban-org/agent-sdk-verify) for production.");
+    }
+    async verify(_receipt, _rootHash) {
+        return { valid: false, reason: "NullTimestampPort cannot verify receipts" };
+    }
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/ports/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../src/ports/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgCH;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,OAAO,CAAC,SAAiB;QAC7B,MAAM,IAAI,KAAK,CACb,oDAAoD;YAClD,0EAA0E,CAC7E,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CACV,QAAuB,EACvB,SAAiB;QAEjB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IAC9E,CAAC;CACF"}