@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/keys/keys.d.ts

@@ -1,4 +1,4 @@
-import type { EnvironmentSecretView, HostModelView, McpPreview, McpPreviewRequest, PutEnvironmentSecretRequest, PutHostModelRequest, SelectHostModelRequest, SigningKeyView } from "@nylorun/core/contracts";
+import type { AgentSecretView, HostModelView, McpPreview, McpPreviewRequest, PutAgentSecretRequest, PutHostModelRequest, SelectHostModelRequest, SigningKeyView } from "@nylorun/core/contracts";
 import type { SessionStore } from "../store/types.js";
 import type { OutboundPolicy } from "../tenant/outbound.js";
 import { type SigningKeys } from "../tenant/signing-keys.js";
@@ -13,9 +13,10 @@ export interface Signed {
     /** The signing key's id, the token's `kid`. */
     readonly keyId: string;
 }
+import { type SealedWebhookSecret, type WebhookDelivery } from "./webhooks.js";
 export interface Keys {
-    /** `PUT /v1/environments/{id}/secrets/{name}` (`VaultService.putEnvironmentSecret`). */
-    putEnvironmentSecret(environmentId: string, name: string, body: PutEnvironmentSecretRequest, actor: string): Promise<EnvironmentSecretView>;
+    /** `PUT /v1/agents/{id}/secrets/{name}` (`VaultService.putEnvironmentSecret`). */
+    putEnvironmentSecret(environmentId: string, name: string, body: PutAgentSecretRequest, actor: string): Promise<AgentSecretView>;
     putHostModel(body: PutHostModelRequest): Promise<HostModelView>;
     selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>;
     /**
@@ -46,9 +47,19 @@ export interface Keys {
      * egress CA (R2c). The leaf's private key never reaches keys; the CA's never leaves it.
      */
     signEgressLeaf(host: string, publicKey: string): Promise<string>;
+    /**
+     * A new Standard Webhooks secret for Agent `agentId`'s trigger `triggerId` (track T4, D75), and
+     * the same sealed with the vault key for the trigger's row. The secret leaves keys this once.
+     */
+    makeWebhookSecret(agentId: string, triggerId: string): Promise<{
+        secret: string;
+        sealed: SealedWebhookSecret;
+    }>;
+    /** Whether a delivery to that trigger carries a signature its sealed secret made. */
+    verifyWebhook(agentId: string, triggerId: string, sealed: SealedWebhookSecret, delivery: WebhookDelivery): Promise<boolean>;
 }
 /** The operations, by the name the HTTP route carries. */
-export declare const KEYS_OPERATIONS: readonly ["putEnvironmentSecret", "putHostModel", "selectHostModel", "sealEnvironmentSecretCopies", "sign", "rotateSigningKeys", "ensureSigningKeys", "previewMcp", "egressCa", "signEgressLeaf"];
+export declare const KEYS_OPERATIONS: readonly ["putEnvironmentSecret", "putHostModel", "selectHostModel", "sealEnvironmentSecretCopies", "sign", "rotateSigningKeys", "ensureSigningKeys", "previewMcp", "egressCa", "signEgressLeaf", "makeWebhookSecret", "verifyWebhook"];
 export type KeysOperation = (typeof KEYS_OPERATIONS)[number];
 export interface InProcessKeysOptions {
     readonly store: SessionStore;

package/dist/keys/keys.js

@@ -18,6 +18,8 @@ import { SignJWT } from "jose";
 import { previewMcpServer } from "../mcp/preview.js";
 import { readRuntimeLimits } from "../tenant/runtime-limits.js";
 import { signingKeyView } from "../tenant/signing-keys.js";
+import { makeWebhookSecret, verifyWebhook } from "./webhooks.js";
+import { VaultCryptoError } from "../vault/crypto.js";
 /** The operations, by the name the HTTP route carries. */
 export const KEYS_OPERATIONS = [
     "putEnvironmentSecret",
@@ -30,6 +32,8 @@ export const KEYS_OPERATIONS = [
     "previewMcp",
     "egressCa",
     "signEgressLeaf",
+    "makeWebhookSecret",
+    "verifyWebhook",
 ];
 export function inProcessKeys(options) {
     const { store, vault, signingKeys, kek } = options;
@@ -64,5 +68,17 @@ export function inProcessKeys(options) {
         }),
         egressCa: () => egress.certificate(),
         signEgressLeaf: (host, publicKey) => egress.signLeaf(host, publicKey),
+        makeWebhookSecret: async (agentId, triggerId) => makeWebhookSecret(kek(), agentId, triggerId),
+        verifyWebhook: async (agentId, triggerId, sealed, delivery) => {
+            try {
+                return verifyWebhook(kek(), agentId, triggerId, sealed, delivery);
+            }
+            catch (error) {
+                // A secret sealed with another vault key, or not one: it verifies nothing.
+                if (error instanceof VaultCryptoError)
+                    return false;
+                throw error;
+            }
+        },
     };
 }

package/dist/keys/webhooks.d.ts

@@ -0,0 +1,25 @@
+/** A secret sealed with the vault key, as the trigger's row keeps it. */
+export interface SealedWebhookSecret {
+    readonly nonce: string;
+    readonly ciphertext: string;
+    readonly wrappedDek: string;
+    readonly kekId: string;
+}
+/** What a delivery says, as it arrived: its headers, and its body in base64. */
+export interface WebhookDelivery {
+    readonly id: string;
+    readonly timestamp: string;
+    readonly signature: string;
+    readonly body: string;
+}
+/** A new secret for Agent `agentId`'s trigger `triggerId`, and the same sealed for its row. */
+export declare function makeWebhookSecret(kek: Buffer, agentId: string, triggerId: string): {
+    secret: string;
+    sealed: SealedWebhookSecret;
+};
+/** The signature of `delivery`'s id, timestamp and body with `key` (base64). */
+export declare function signWebhook(key: Buffer, id: string, timestamp: string, body: Buffer): string;
+/** The key bytes of a `whsec_` secret. */
+export declare function webhookKeyOf(secret: string): Buffer;
+/** Whether `delivery` carries a signature the sealed secret made. */
+export declare function verifyWebhook(kek: Buffer, agentId: string, triggerId: string, sealed: SealedWebhookSecret, delivery: WebhookDelivery): boolean;

package/dist/keys/webhooks.js

@@ -0,0 +1,62 @@
+/**
+ * Webhook signing secrets (track T4, D75): the keys service makes a trigger's Standard Webhooks
+ * secret, seals it with the Tenant's vault key for the trigger's row, and is the only place that
+ * opens it, to verify a delivery. The secret leaves keys once, when it is made, for its owner.
+ *
+ * Standard Webhooks (https://www.standardwebhooks.com): the secret is `whsec_` and the base64 of
+ * its key bytes; a delivery's `webhook-signature` is space-separated `v1,<base64>` entries, each an
+ * HMAC-SHA256 with the key over `<webhook-id>.<webhook-timestamp>.<body>`. One that matches, in
+ * constant time, verifies it. The timestamp's tolerance is the route's to check.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { decryptSecret, encryptSecret } from "../vault/crypto.js";
+/** The Standard Webhooks secret format: the prefix, and 32 random bytes of key. */
+const SECRET_PREFIX = "whsec_";
+const SECRET_BYTES = 32;
+const aadOf = (agentId, triggerId) => Buffer.from(`nylorun-webhook:${agentId}:${triggerId}`, "utf8");
+/** A new secret for Agent `agentId`'s trigger `triggerId`, and the same sealed for its row. */
+export function makeWebhookSecret(kek, agentId, triggerId) {
+    const key = randomBytes(SECRET_BYTES);
+    try {
+        const sealed = encryptSecret(kek, aadOf(agentId, triggerId), key);
+        return {
+            secret: `${SECRET_PREFIX}${key.toString("base64")}`,
+            sealed: {
+                nonce: sealed.nonce.toString("base64"),
+                ciphertext: sealed.ciphertext.toString("base64"),
+                wrappedDek: sealed.wrappedDek.toString("base64"),
+                kekId: sealed.kekId,
+            },
+        };
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/** The signature of `delivery`'s id, timestamp and body with `key` (base64). */
+export function signWebhook(key, id, timestamp, body) {
+    return createHmac("sha256", key).update(`${id}.${timestamp}.`).update(body).digest("base64");
+}
+/** The key bytes of a `whsec_` secret. */
+export function webhookKeyOf(secret) {
+    return Buffer.from(secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret, "base64");
+}
+/** Whether `delivery` carries a signature the sealed secret made. */
+export function verifyWebhook(kek, agentId, triggerId, sealed, delivery) {
+    const key = decryptSecret(kek, aadOf(agentId, triggerId), Buffer.from(sealed.nonce, "base64"), Buffer.from(sealed.ciphertext, "base64"), Buffer.from(sealed.wrappedDek, "base64"), sealed.kekId);
+    try {
+        const expected = Buffer.from(signWebhook(key, delivery.id, delivery.timestamp, Buffer.from(delivery.body, "base64")), "base64");
+        for (const entry of delivery.signature.split(" ")) {
+            const [version, value] = entry.split(",", 2);
+            if (version !== "v1" || !value)
+                continue;
+            const given = Buffer.from(value, "base64");
+            if (given.length === expected.length && timingSafeEqual(given, expected))
+                return true;
+        }
+        return false;
+    }
+    finally {
+        key.fill(0);
+    }
+}