Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,89 @@
import { describe, expect, it } from "vitest";
import { generateDek, open, seal, envelopeKeyVersion } from "./envelope.js";
import { EnvKeyWrapper, setKeyWrapper } from "./key-wrapper.js";
// R-P5 — AD-8 envelope primitives. These lock in the security-critical
// round-trip + tamper-resistance contract.
describe("envelope seal/open", () => {
it("round-trips a value with the same DEK", () => {
const dek = generateDek();
const sealed = seal(dek, "hunter2");
expect(sealed).not.toContain("hunter2");
expect(open(dek, sealed)).toBe("hunter2");
});
it("generates a 32-byte (AES-256) DEK", () => {
expect(generateDek()).toHaveLength(32);
});
it("fails to open with a different DEK (authenticated)", () => {
const sealed = seal(generateDek(), "secret");
expect(() => open(generateDek(), sealed)).toThrow();
});
it("rejects a tampered ciphertext (GCM tag)", () => {
const dek = generateDek();
const sealed = seal(dek, "secret");
const parts = sealed.split(":");
// Flip a byte in the ciphertext segment.
const ct = Buffer.from(parts[4], "base64url");
ct[0] ^= 0xff;
parts[4] = ct.toString("base64url");
expect(() => open(dek, parts.join(":"))).toThrow();
});
it("rejects a malformed envelope", () => {
expect(() => open(generateDek(), "not-an-envelope")).toThrow(/malformed/);
});
it("encodes and reads back the key version", () => {
const sealed = seal(generateDek(), "x", 7);
expect(envelopeKeyVersion(sealed)).toBe(7);
});
it("produces a fresh IV each time (no deterministic ciphertext)", () => {
const dek = generateDek();
expect(seal(dek, "same")).not.toBe(seal(dek, "same"));
});
});
describe("EnvKeyWrapper", () => {
it("wraps and unwraps a DEK under CRYPTO_SECRET", async () => {
const prev = process.env.CRYPTO_SECRET;
process.env.CRYPTO_SECRET = "test-master-key-aaaaaaaaaaaaaaaaaaaa";
try {
const wrapper = new EnvKeyWrapper();
const dek = generateDek();
const blob = await wrapper.wrap(dek);
expect(Buffer.compare(blob, dek)).not.toBe(0); // wrapped != plaintext
expect(Buffer.compare(await wrapper.unwrap(blob), dek)).toBe(0);
} finally {
process.env.CRYPTO_SECRET = prev;
setKeyWrapper(null);
}
});
it("a blob wrapped under one secret cannot be unwrapped under another", async () => {
const prev = process.env.CRYPTO_SECRET;
try {
process.env.CRYPTO_SECRET = "secret-A-aaaaaaaaaaaaaaaaaaaaaaaaaaaa";
const blob = await new EnvKeyWrapper().wrap(generateDek());
process.env.CRYPTO_SECRET = "secret-B-bbbbbbbbbbbbbbbbbbbbbbbbbbbb";
await expect(new EnvKeyWrapper().unwrap(blob)).rejects.toThrow();
} finally {
process.env.CRYPTO_SECRET = prev;
setKeyWrapper(null);
}
});
it("throws a clear error when CRYPTO_SECRET is missing", async () => {
const prev = process.env.CRYPTO_SECRET;
delete process.env.CRYPTO_SECRET;
try {
await expect(new EnvKeyWrapper().wrap(generateDek())).rejects.toThrow(/CRYPTO_SECRET/);
} finally {
process.env.CRYPTO_SECRET = prev;
}
});
});
@@ -0,0 +1,66 @@
// R-P5 (P5) — AD-8 envelope-encryption primitives (pure, server-only).
//
// Field-level AES-256-GCM with a caller-supplied Data-Encryption-Key (DEK). This
// module knows nothing about tenants, Prisma or env — it only seals/opens a
// string with a 32-byte key. The per-tenant DEK lifecycle (load/create/wrap/
// cache) lives in packages/db/src/crypto/tenant-envelope.server.ts; the master-key
// wrapping lives in ./key-wrapper.ts.
//
// Exported via the `@hivegrid/foundation/crypto` SUBPATH only (never the main
// barrel) so `node:crypto` never reaches a browser bundle.
import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
const ALGORITHM = "aes-256-gcm";
const DEK_BYTES = 32; // AES-256
const IV_BYTES = 12; // GCM standard nonce length
const FORMAT_VERSION = "v1";
/** Generate a fresh random 256-bit Data-Encryption-Key. */
export function generateDek(): Buffer {
return randomBytes(DEK_BYTES);
}
function assertDek(dek: Buffer): void {
if (!Buffer.isBuffer(dek) || dek.length !== DEK_BYTES) {
throw new Error(`envelope: DEK must be a ${DEK_BYTES}-byte Buffer`);
}
}
/**
* Seal `plaintext` with `dek` (AES-256-GCM). Returns a self-describing string
* `v1:<keyVersion>:<iv>:<tag>:<ciphertext>` (all parts base64url). The
* `keyVersion` is carried so the wrapping scheme can rotate without re-encrypting
* fields.
*/
export function seal(dek: Buffer, plaintext: string, keyVersion = 1): string {
assertDek(dek);
const iv = randomBytes(IV_BYTES);
const cipher = createCipheriv(ALGORITHM, dek, iv);
const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
const tag = cipher.getAuthTag();
return [FORMAT_VERSION, String(keyVersion), iv.toString("base64url"), tag.toString("base64url"), ciphertext.toString("base64url")].join(":");
}
/** Open an envelope produced by {@link seal} with the matching `dek`. Throws on a
* malformed envelope or a failed authentication tag (tamper / wrong key). */
export function open(dek: Buffer, envelope: string): string {
assertDek(dek);
const parts = envelope.split(":");
if (parts.length !== 5 || parts[0] !== FORMAT_VERSION) {
throw new Error("envelope: malformed or unsupported payload");
}
const [, , ivB64, tagB64, ctB64] = parts;
const decipher = createDecipheriv(ALGORITHM, dek, Buffer.from(ivB64, "base64url"));
decipher.setAuthTag(Buffer.from(tagB64, "base64url"));
return Buffer.concat([decipher.update(Buffer.from(ctB64, "base64url")), decipher.final()]).toString("utf8");
}
/** Extract the keyVersion encoded in an envelope (for rotation bookkeeping). */
export function envelopeKeyVersion(envelope: string): number {
const parts = envelope.split(":");
if (parts.length !== 5 || parts[0] !== FORMAT_VERSION) {
throw new Error("envelope: malformed or unsupported payload");
}
return Number(parts[1]);
}
@@ -0,0 +1,5 @@
// R-P5 (P5) — `@hivegrid/foundation/crypto` subpath barrel (server-only, node:crypto).
// Kept OUT of the main foundation barrel so node builtins never reach a browser
// bundle.
export * from "./envelope.js";
export * from "./key-wrapper.js";
@@ -0,0 +1,103 @@
// R-P5 (P5) — master-key wrapping for the per-tenant DEK (AD-8, pure server-only).
//
// A KeyWrapper encrypts ("wraps") and decrypts ("unwraps") a tenant DEK with the
// APP MASTER KEY. The DEK itself never leaves the DB unwrapped. Swapping the
// wrapper (e.g. to a self-hosted Vault/OpenBao Transit engine later) re-wraps the
// DEKs but does NOT require re-encrypting any field ciphertext — that is the whole
// point of the envelope indirection.
//
// Today: EnvKeyWrapper, AES-256-GCM under CRYPTO_SECRET (EXT-06 app master key).
//
// Exported via the `@hivegrid/foundation/crypto` SUBPATH only.
import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
const ALGORITHM = "aes-256-gcm";
const IV_BYTES = 12;
/**
* Wraps/unwraps a tenant DEK with the app master key. Implementations must be
* deterministic in their unwrap and authenticated (GCM tag), so a tampered or
* foreign blob fails closed.
*/
export interface KeyWrapper {
/** Encrypt the plaintext DEK with the master key → opaque blob for storage. */
wrap(dek: Buffer): Promise<Buffer>;
/** Decrypt a blob produced by {@link wrap} back into the plaintext DEK. */
unwrap(blob: Buffer): Promise<Buffer>;
}
/**
* Master-key wrapper backed by the app secret `CRYPTO_SECRET` (EXT-06). The
* 256-bit wrapping key is derived as SHA-256(CRYPTO_SECRET) — same derivation as
* the legacy CryptoApi, so the master secret is a single source of truth. The
* stored blob is `iv(12) | tag(16) | ciphertext`.
*
* The secret is read LAZILY (per call), never at import time, so importing this
* module has no env requirement and stays test-friendly.
*/
export class EnvKeyWrapper implements KeyWrapper {
private readonly envVar: string;
constructor(envVar = "CRYPTO_SECRET") {
this.envVar = envVar;
}
private masterKey(): Buffer {
const secret = process.env[this.envVar];
if (!secret) {
// Klartext-mappable upstream; here a plain Error is fine (server boot/config).
throw new Error(`EnvKeyWrapper: ${this.envVar} env variable not set`);
}
return createHash("sha256").update(secret).digest();
}
// Bodies are sync but wrapped so EVERY failure (missing secret, auth-tag
// mismatch on a foreign/tampered blob) surfaces as a REJECTION, matching the
// async KeyWrapper contract a future network-backed wrapper will satisfy.
wrap(dek: Buffer): Promise<Buffer> {
try {
const iv = randomBytes(IV_BYTES);
const cipher = createCipheriv(ALGORITHM, this.masterKey(), iv);
const ciphertext = Buffer.concat([cipher.update(dek), cipher.final()]);
const tag = cipher.getAuthTag();
return Promise.resolve(Buffer.concat([iv, tag, ciphertext]));
} catch (error) {
return Promise.reject(error instanceof Error ? error : new Error(String(error)));
}
}
unwrap(blob: Buffer): Promise<Buffer> {
try {
if (blob.length < IV_BYTES + 16) {
throw new Error("EnvKeyWrapper: wrapped DEK blob too short");
}
const iv = blob.subarray(0, IV_BYTES);
const tag = blob.subarray(IV_BYTES, IV_BYTES + 16);
const ciphertext = blob.subarray(IV_BYTES + 16);
const decipher = createDecipheriv(ALGORITHM, this.masterKey(), iv);
decipher.setAuthTag(tag);
return Promise.resolve(Buffer.concat([decipher.update(ciphertext), decipher.final()]));
} catch (error) {
return Promise.reject(error instanceof Error ? error : new Error(String(error)));
}
}
}
let defaultWrapper: KeyWrapper | null = null;
/**
* The process-wide default wrapper (EnvKeyWrapper). A future self-hosted-KMS
* binding swaps this once; callers never construct a wrapper directly.
*/
export function getKeyWrapper(): KeyWrapper {
if (!defaultWrapper) {
defaultWrapper = new EnvKeyWrapper();
}
return defaultWrapper;
}
/** Override the default wrapper (tests, or the future Vault/OpenBao binding). */
export function setKeyWrapper(wrapper: KeyWrapper | null): void {
defaultWrapper = wrapper;
}
@@ -0,0 +1,59 @@
import { describe, expect, test } from "vitest";
import { CatalogError, foundationErrors, toPinoLogObject } from "./errors.js";
describe("CatalogError", () => {
test("derives message from the definition message when present and copies metadata", () => {
const definition = { code: "x.broken", status: 418, i18nKey: "x.errors.broken", message: "I am a teapot" };
const error = new CatalogError(definition, { teapot: true });
expect(error).toBeInstanceOf(Error);
expect(error.name).toBe("CatalogError");
expect(error.message).toBe("I am a teapot");
expect(error.code).toBe("x.broken");
expect(error.status).toBe(418);
expect(error.i18nKey).toBe("x.errors.broken");
expect(error.details).toEqual({ teapot: true });
});
test("falls back to the code as message when no definition message is set", () => {
const error = new CatalogError(foundationErrors.notFound);
expect(error.message).toBe(foundationErrors.notFound.code);
expect(error.status).toBe(404);
expect(error.details).toBeUndefined();
});
});
describe("toPinoLogObject", () => {
test("serializes a CatalogError into a structured catalog shape", () => {
const error = new CatalogError(foundationErrors.forbidden, { permission: "thing.view" });
expect(toPinoLogObject(error)).toEqual({
error: {
name: "CatalogError",
message: foundationErrors.forbidden.code,
code: "foundation.forbidden",
status: 403,
i18nKey: "foundation.errors.forbidden",
details: { permission: "thing.view" },
},
});
});
test("serializes a plain Error with its stack but no catalog fields", () => {
const error = new Error("plain boom");
const logged = toPinoLogObject(error) as { error: { name: string; message: string; stack?: string; code?: string } };
expect(logged.error.name).toBe("Error");
expect(logged.error.message).toBe("plain boom");
expect(typeof logged.error.stack).toBe("string");
expect(logged.error.code).toBeUndefined();
});
test("wraps non-Error throwables verbatim", () => {
expect(toPinoLogObject("just a string")).toEqual({ error: "just a string" });
expect(toPinoLogObject({ weird: 1 })).toEqual({ error: { weird: 1 } });
expect(toPinoLogObject(undefined)).toEqual({ error: undefined });
});
});
@@ -0,0 +1,76 @@
import { describe, expect, test } from "vitest";
import { defineFlag, featureFlag, normalizeFlagScope, selectFlagRecord } from "./flags.js";
describe("defineFlag", () => {
test("defaults defaultEnabled to false when omitted", () => {
expect(defineFlag({ key: "x.flag" }).defaultEnabled).toBe(false);
});
test("preserves an explicit defaultEnabled and description", () => {
expect(defineFlag({ key: "x.flag", defaultEnabled: true, description: "demo" })).toEqual({
key: "x.flag",
defaultEnabled: true,
description: "demo",
});
});
});
describe("featureFlag", () => {
test("short-circuits on an explicit boolean override regardless of records", () => {
expect(featureFlag({ key: "x.flag", override: false, defaultEnabled: true, records: [{ enabled: true }] })).toBe(false);
expect(featureFlag({ key: "x.flag", override: true, defaultEnabled: false })).toBe(true);
});
test("falls back to false when there is no record and no default", () => {
expect(featureFlag({ key: "x.flag" })).toBe(false);
});
test("falls back to the default when there is no matching record", () => {
expect(featureFlag({ key: "x.flag", defaultEnabled: true, records: [{ key: "other.flag", enabled: false }] })).toBe(true);
});
test("matches records that identify the flag through the legacy name field", () => {
expect(featureFlag({ key: "x.flag", records: [{ name: "x.flag", scope: "global", enabled: true }] })).toBe(true);
});
});
describe("normalizeFlagScope", () => {
test("classifies user scope by explicit scope or by userId", () => {
expect(normalizeFlagScope({ scope: "user", enabled: true })).toBe("user");
expect(normalizeFlagScope({ userId: "user_1", enabled: true })).toBe("user");
});
test("classifies tenant scope by explicit scope or by tenantId", () => {
expect(normalizeFlagScope({ scope: "tenant", enabled: true })).toBe("tenant");
expect(normalizeFlagScope({ tenantId: "tenant_1", enabled: true })).toBe("tenant");
});
test("classifies records without any scope hint as global", () => {
expect(normalizeFlagScope({ enabled: true })).toBe("global");
});
test("prefers user over tenant when both ids are present", () => {
expect(normalizeFlagScope({ tenantId: "tenant_1", userId: "user_1", enabled: true })).toBe("user");
});
});
describe("selectFlagRecord", () => {
test("prefers a user-scoped record over tenant and global records", () => {
const records = [
{ scope: "global", enabled: false, key: "x.flag" },
{ tenantId: "tenant_1", enabled: false, key: "x.flag" },
{ userId: "user_1", tenantId: "tenant_1", enabled: true, key: "x.flag" },
];
expect(selectFlagRecord({ key: "x.flag", records, tenantId: "tenant_1", userId: "user_1" })?.enabled).toBe(true);
});
test("returns null when no record matches the flag key", () => {
expect(selectFlagRecord({ key: "x.flag", records: [{ key: "other.flag", enabled: true }] })).toBeNull();
});
test("ignores a user-scoped record bound to a different tenant", () => {
const records = [{ scope: "user", userId: "user_1", tenantId: "tenant_2", enabled: true, key: "x.flag" }];
expect(selectFlagRecord({ key: "x.flag", records, tenantId: "tenant_1", userId: "user_1" })).toBeNull();
});
});
@@ -0,0 +1,186 @@
import { describe, expect, test, vi } from "vitest";
import { withIdempotency, type IdempotencyClient } from "./idempotency.js";
type StoredRow = {
requestHash: string;
responseStatus: number;
responseBody: Parameters<typeof JSON.stringify>[0] | null;
responseHeaders: Record<string, string> | null;
};
/** In-memory idempotency client backed by a Map, mirroring the Prisma contract. */
function memoryClient() {
const rows = new Map<string, StoredRow>();
const keyOf = (scope: string, key: string) => `${scope}:${key}`;
const client: IdempotencyClient = {
idempotencyKey: {
findUnique: vi.fn(async ({ where }) => rows.get(keyOf(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key)) ?? null),
create: vi.fn(async ({ data }) => {
const k = keyOf(data.scope, data.key);
if (rows.has(k)) throw Object.assign(new Error("unique"), { code: "P2002" });
rows.set(k, { requestHash: data.requestHash, responseStatus: data.responseStatus, responseBody: data.responseBody ?? null, responseHeaders: data.responseHeaders ?? null });
}),
update: vi.fn(async ({ where, data }) => {
const k = keyOf(where.idempotency_key_scope_key.scope, where.idempotency_key_scope_key.key);
const existing = rows.get(k);
if (!existing) throw new Error("missing reservation");
rows.set(k, { ...existing, responseStatus: data.responseStatus, responseBody: data.responseBody ?? null, responseHeaders: data.responseHeaders ?? null });
}),
deleteMany: vi.fn(async ({ where } = {}) => {
if (where?.scope && where.key) rows.delete(keyOf(where.scope, where.key));
}),
},
};
return { client, rows };
}
describe("withIdempotency key handling", () => {
test("runs the operation directly when no idempotency key is supplied", async () => {
const { client } = memoryClient();
const operation = vi.fn(async () => ({ status: 200, body: { ok: true } }));
await expect(withIdempotency({ key: undefined, fingerprint: { a: 1 } }, client, operation)).resolves.toEqual({ status: 200, body: { ok: true }, replayed: false });
expect(operation).toHaveBeenCalledTimes(1);
expect(client.idempotencyKey.findUnique).not.toHaveBeenCalled();
});
test("treats a whitespace-only key as no key", async () => {
const { client } = memoryClient();
const operation = vi.fn(async () => ({ status: 201 }));
await expect(withIdempotency({ key: " ", fingerprint: 1 }, client, operation)).resolves.toMatchObject({ status: 201, replayed: false });
expect(client.idempotencyKey.create).not.toHaveBeenCalled();
});
});
describe("withIdempotency fingerprinting", () => {
test("replays when a reordered object fingerprint stringifies identically", async () => {
const { client } = memoryClient();
const operation = vi.fn(async () => ({ status: 201, body: { ok: true } }));
await withIdempotency({ key: "k1", fingerprint: { a: 1, b: [2, 3] } }, client, operation);
const replay = await withIdempotency({ key: "k1", fingerprint: { b: [2, 3], a: 1 } }, client, operation);
expect(replay).toMatchObject({ replayed: true, status: 201, body: { ok: true } });
expect(operation).toHaveBeenCalledTimes(1);
});
test("replays stored response headers as well as the body", async () => {
const { client } = memoryClient();
await withIdempotency({ key: "kh", fingerprint: "a" }, client, async () => ({ status: 200, body: { ok: true }, headers: { "x-trace": "abc" } }));
const replay = await withIdempotency({ key: "kh", fingerprint: "a" }, client, async () => ({ status: 500 }));
expect(replay).toEqual({ status: 200, body: { ok: true }, headers: { "x-trace": "abc" }, replayed: true });
});
test("replays a stored no-content response without a body", async () => {
const { client } = memoryClient();
await withIdempotency({ key: "kn", fingerprint: "a" }, client, async () => ({ status: 204 }));
const replay = await withIdempotency({ key: "kn", fingerprint: "a" }, client, async () => ({ status: 500 }));
expect(replay).toEqual({ status: 204, body: undefined, headers: undefined, replayed: true });
});
test("rejects a replay whose fingerprint changed", async () => {
const { client } = memoryClient();
await withIdempotency({ key: "k2", fingerprint: "a" }, client, async () => ({ status: 200 }));
await expect(withIdempotency({ key: "k2", fingerprint: "b" }, client, async () => ({ status: 200 }))).rejects.toMatchObject({ code: "foundation.idempotency_conflict" });
});
});
describe("withIdempotency reservation states", () => {
test("surfaces an in-progress error when a matching reservation has no response yet", async () => {
const { rows, client } = memoryClient();
rows.set("default:k3", { requestHash: JSON.stringify("a"), responseStatus: 0, responseBody: null, responseHeaders: null });
const operation = vi.fn(async () => ({ status: 200 }));
await expect(withIdempotency({ key: "k3", fingerprint: "a" }, client, operation)).rejects.toMatchObject({ code: "foundation.idempotency_in_progress" });
expect(operation).not.toHaveBeenCalled();
});
test("replays the row reserved by a racing writer on a unique-constraint collision", async () => {
let findCalls = 0;
const reserved = { requestHash: JSON.stringify("a"), responseStatus: 201, responseBody: { ok: true }, responseHeaders: null };
const client: IdempotencyClient = {
idempotencyKey: {
findUnique: vi.fn(async () => (findCalls++ === 0 ? null : reserved)),
create: vi.fn(async () => {
throw Object.assign(new Error("unique"), { code: "P2002" });
}),
update: vi.fn(),
deleteMany: vi.fn(),
},
};
const operation = vi.fn(async () => ({ status: 500 }));
await expect(withIdempotency({ key: "race", fingerprint: "a" }, client, operation)).resolves.toMatchObject({ replayed: true, status: 201, body: { ok: true } });
expect(operation).not.toHaveBeenCalled();
});
test("rethrows a P2002 collision when no reservation can be re-read", async () => {
const p2002 = Object.assign(new Error("unique"), { code: "P2002" });
const client: IdempotencyClient = {
idempotencyKey: {
findUnique: vi.fn(async () => null),
create: vi.fn(async () => {
throw p2002;
}),
update: vi.fn(),
deleteMany: vi.fn(),
},
};
await expect(withIdempotency({ key: "race2", fingerprint: "a" }, client, async () => ({ status: 200 }))).rejects.toBe(p2002);
});
test("rethrows non-unique-constraint create failures untouched", async () => {
const client: IdempotencyClient = {
idempotencyKey: {
findUnique: vi.fn(async () => null),
create: vi.fn(async () => {
throw new Error("db unavailable");
}),
update: vi.fn(),
deleteMany: vi.fn(),
},
};
await expect(withIdempotency({ key: "boom", fingerprint: "a" }, client, async () => ({ status: 200 }))).rejects.toThrow("db unavailable");
});
});
describe("withIdempotency operation failures", () => {
test("releases the reservation and rethrows when the operation throws", async () => {
const { client } = memoryClient();
const error = new Error("operation failed");
await expect(
withIdempotency({ key: "k4", fingerprint: "a" }, client, async () => {
throw error;
}),
).rejects.toBe(error);
expect(client.idempotencyKey.deleteMany).toHaveBeenCalledWith({ where: { scope: "default", key: "k4" } });
// After rollback the same key can be reserved again (no lingering reservation).
await expect(withIdempotency({ key: "k4", fingerprint: "a" }, client, async () => ({ status: 200 }))).resolves.toMatchObject({ status: 200, replayed: false });
});
test("rethrows even when the client cannot delete the reservation", async () => {
const client: IdempotencyClient = {
idempotencyKey: {
findUnique: vi.fn(async () => null),
create: vi.fn(async () => undefined),
update: vi.fn(),
// deleteMany intentionally omitted to exercise the optional-call path.
},
};
await expect(
withIdempotency({ key: "k5", fingerprint: "a" }, client, async () => {
throw new Error("late failure");
}),
).rejects.toThrow("late failure");
});
});
@@ -19,7 +19,7 @@ import {
type NotificationInput,
} from "./index.js";
describe("@toolctrl/foundation", () => {
describe("@hivegrid/foundation", () => {
test("writes audit events through the provided DB boundary", async () => {
const client = { auditEvent: { create: vi.fn(async (args) => args.data) } };
await auditEvent({ action: "thing.changed", tenantId: "tenant_1" }, client);
@@ -4,6 +4,7 @@ export * from "./permissions.js";
export * from "./flags.js";
export * from "./idempotency.js";
export * from "./adapters.js";
export * from "./integration-adapters.js";
export * from "./notifications.js";
export * from "./workflows.js";
export * from "./concurrency.js";
@@ -0,0 +1,60 @@
import { beforeEach, describe, expect, it } from "vitest";
import {
checkCatalogDrift,
clearIntegrationAdapters,
getIntegrationAdapter,
listIntegrationAdapterKeys,
registerIntegrationAdapter,
type IntegrationAdapter,
} from "./integration-adapters.js";
// R-P5 — type-safe adapter registry + drift check (DoD #2). A new integration is
// added by registering an adapter (no core change); drift between registry and
// the App catalog surfaces a Klartext warning.
const fakeAdapter = (key: string): IntegrationAdapter => ({
key,
connectionType: "api_key",
validateConnection: () => Promise.resolve({ ok: true, health: "active", messageKey: "integrations.health.active" }),
healthCheck: () => Promise.resolve({ ok: true, health: "active", messageKey: "integrations.health.active" }),
sync: () => Promise.resolve({ items: [], summaryKey: "integrations.sync.summary.empty" }),
});
beforeEach(() => clearIntegrationAdapters());
describe("integration adapter registry", () => {
it("registers and looks up an adapter by key", () => {
registerIntegrationAdapter(fakeAdapter("acme-crm"));
expect(getIntegrationAdapter("acme-crm")?.connectionType).toBe("api_key");
expect(getIntegrationAdapter("missing")).toBeUndefined();
});
it("lists registered keys sorted", () => {
registerIntegrationAdapter(fakeAdapter("zeta"));
registerIntegrationAdapter(fakeAdapter("alpha"));
expect(listIntegrationAdapterKeys()).toEqual(["alpha", "zeta"]);
});
});
describe("checkCatalogDrift", () => {
it("reports in-sync when adapters and catalog match", () => {
const drift = checkCatalogDrift(["gmail", "mollie"], ["mollie", "gmail"]);
expect(drift.inSync).toBe(true);
expect(drift.missingAdapters).toEqual([]);
expect(drift.orphanAdapters).toEqual([]);
});
it("flags a catalog App with no adapter (cannot connect)", () => {
const drift = checkCatalogDrift(["gmail"], ["gmail", "aircall"]);
expect(drift.inSync).toBe(false);
expect(drift.missingAdapters).toEqual(["aircall"]);
expect(drift.orphanAdapters).toEqual([]);
});
it("flags an orphan adapter with no catalog App (invisible)", () => {
const drift = checkCatalogDrift(["gmail", "legacy"], ["gmail"]);
expect(drift.inSync).toBe(false);
expect(drift.missingAdapters).toEqual([]);
expect(drift.orphanAdapters).toEqual(["legacy"]);
});
});
@@ -0,0 +1,111 @@
// R-P5 (P5) — type-safe integration-adapter contract + registry (DoD #2).
//
// The Apps-Engine is "open": a new integration (Gmail, AirCall, Mollie, KWP, …)
// is added by dropping an adapter under apps/web/app/integrations/<key>/ that
// registers an IntegrationAdapter here — NO core change. The platform-admin
// surface (P19) shows a Klartext DRIFT warning when the registered adapters and
// the App catalog disagree (checkCatalogDrift).
//
// This module is PURE (interface + an in-memory Map + a pure drift comparison) so
// it lives in the foundation barrel. Concrete adapters do the network I/O; this
// only declares the shape they must satisfy. Every adapter result is Klartext
// (an i18n messageKey, M002/M003) — never a bare provider error.
export type AdapterConnectionType = "oauth2" | "api_key" | "rest_api" | "windows_client";
/** Health verdict of a connection probe / credential validation. */
export type AdapterHealth = "active" | "degraded" | "broken";
/** Klartext result of validateConnection / healthCheck. */
export interface AdapterResult {
readonly ok: boolean;
readonly health: AdapterHealth;
/** i18n key describing the state + next action (M002/M003). */
readonly messageKey: string;
}
/** One synced object reported by an adapter's sync(). */
export interface AdapterSyncItemResult {
readonly entityType: string;
readonly entityId?: string | null;
readonly externalId: string;
readonly operation: "created" | "updated" | "deleted" | "skipped";
readonly status: "synced" | "failed" | "skipped";
readonly errorText?: string | null;
}
/** Aggregate outcome of an adapter sync run. */
export interface AdapterSyncOutcome {
readonly items: readonly AdapterSyncItemResult[];
/** i18n key for the run summary (Klartext). */
readonly summaryKey: string;
}
/** Result of refreshing an OAuth token. */
export interface AdapterTokenRefresh<Creds> {
readonly creds: Creds;
readonly expiresAt: Date | null;
}
/**
* The contract every integration must satisfy. `Creds` is the adapter-specific
* decrypted credential shape (the engine handles envelope crypto + storage).
*/
export interface IntegrationAdapter<Creds = Record<string, unknown>> {
readonly key: string;
readonly connectionType: AdapterConnectionType;
/** Validate freshly entered/authorised credentials (connect wizard). */
validateConnection(creds: Creds): Promise<AdapterResult>;
/** Probe an existing connection's live health. */
healthCheck(creds: Creds): Promise<AdapterResult>;
/** Refresh an expiring OAuth token (oauth2 adapters only). */
refreshToken?(creds: Creds): Promise<AdapterTokenRefresh<Creds>>;
/** Run a sync, returning per-item results for AppSyncRun aggregation. */
sync(creds: Creds): Promise<AdapterSyncOutcome>;
}
const registry = new Map<string, IntegrationAdapter>();
/** Register an integration adapter (idempotent by key; last registration wins). */
export function registerIntegrationAdapter<Creds>(adapter: IntegrationAdapter<Creds>): IntegrationAdapter<Creds> {
registry.set(adapter.key, adapter as IntegrationAdapter);
return adapter;
}
/** Look up a registered adapter by key, or undefined. */
export function getIntegrationAdapter<Creds = Record<string, unknown>>(key: string): IntegrationAdapter<Creds> | undefined {
return registry.get(key) as IntegrationAdapter<Creds> | undefined;
}
/** All registered adapter keys (sorted, for deterministic drift diffs). */
export function listIntegrationAdapterKeys(): string[] {
return [...registry.keys()].sort();
}
/** Test/registry reset hook. */
export function clearIntegrationAdapters(): void {
registry.clear();
}
/** A Klartext drift finding between the adapter registry and the App catalog. */
export interface CatalogDrift {
/** Catalog Apps that have NO registered adapter (cannot connect). */
readonly missingAdapters: readonly string[];
/** Registered adapters with NO catalog App (orphan; won't appear in the UI). */
readonly orphanAdapters: readonly string[];
/** True when the registry and catalog fully agree. */
readonly inSync: boolean;
}
/**
* Pure drift comparison: the registered adapter keys vs. the App-catalog keys.
* The platform admin renders a Klartext warning when `inSync` is false. Build
* time can run the same check (scripts/scan-integrations.mjs) to fail fast.
*/
export function checkCatalogDrift(adapterKeys: readonly string[], catalogKeys: readonly string[]): CatalogDrift {
const adapters = new Set(adapterKeys);
const catalog = new Set(catalogKeys);
const missingAdapters = [...catalog].filter((key) => !adapters.has(key)).sort();
const orphanAdapters = [...adapters].filter((key) => !catalog.has(key)).sort();
return { missingAdapters, orphanAdapters, inSync: missingAdapters.length === 0 && orphanAdapters.length === 0 };
}
@@ -0,0 +1,47 @@
import { describe, expect, test } from "vitest";
import { assertMassActionAllowed, massActionErrors, previewMassAction } from "./mass-action.js";
import { CatalogError } from "./errors.js";
describe("previewMassAction sampling edge cases", () => {
test("yields an empty sample when no items are supplied", () => {
const preview = previewMassAction({ affected: 120, policy: { confirmThreshold: 50 } });
expect(preview.sample).toEqual([]);
expect(preview.requiresConfirmation).toBe(true);
expect(preview.exceedsHardLimit).toBe(false);
});
test("clamps a negative sample size to zero", () => {
const preview = previewMassAction({ affected: 3, items: [1, 2, 3], sampleSize: -5, policy: { confirmThreshold: 50 } });
expect(preview.sample).toEqual([]);
});
test("does not require confirmation once the hard limit is exceeded", () => {
const preview = previewMassAction({ affected: 9000, items: [], policy: { confirmThreshold: 50, hardLimit: 5000 } });
expect(preview.exceedsHardLimit).toBe(true);
expect(preview.requiresConfirmation).toBe(false);
});
});
describe("assertMassActionAllowed detail propagation", () => {
test("merges caller-supplied details into a hard-limit error", () => {
try {
assertMassActionAllowed({ affected: 6000, policy: { confirmThreshold: 50, hardLimit: 5000 } }, { tenantId: "tenant_1" });
throw new Error("expected throw");
} catch (error) {
expect(error).toBeInstanceOf(CatalogError);
expect((error as CatalogError).code).toBe(massActionErrors.exceedsLimit.code);
expect((error as CatalogError).details).toMatchObject({ affected: 6000, hardLimit: 5000, tenantId: "tenant_1" });
}
});
test("merges caller-supplied details into a confirmation-required error", () => {
try {
assertMassActionAllowed({ affected: 200, policy: { confirmThreshold: 50 } }, { actor: "user_1" });
throw new Error("expected throw");
} catch (error) {
expect((error as CatalogError).code).toBe(massActionErrors.confirmationRequired.code);
expect((error as CatalogError).details).toMatchObject({ affected: 200, confirmThreshold: 50, actor: "user_1" });
}
});
});
@@ -0,0 +1,176 @@
import { describe, expect, test, vi } from "vitest";
import {
assertI18nKey,
bundleNotifications,
isNotificationEnabled,
notify,
type NotificationClient,
type NotificationInput,
} from "./notifications.js";
function createClient() {
return {
notificationDelivery: {
create: vi.fn(async (args: { data: unknown }) => args.data),
upsert: vi.fn(async (args: { create: unknown }) => args.create),
},
} satisfies NotificationClient;
}
describe("assertI18nKey", () => {
test("returns valid dotted/dashed lowercase keys", () => {
expect(assertI18nKey("foundation.errors.not-found")).toBe("foundation.errors.not-found");
expect(assertI18nKey("a")).toBe("a");
});
test("rejects keys that do not match the i18n key grammar", () => {
expect(() => assertI18nKey("Foundation.Bad")).toThrow(/Invalid i18n key/);
expect(() => assertI18nKey("1leading.digit")).toThrow(/Invalid i18n key/);
expect(() => assertI18nKey("trailing.")).toThrow(/Invalid i18n key/);
expect(() => assertI18nKey("")).toThrow(/Invalid i18n key/);
});
});
describe("notify payload sanitization", () => {
test("keeps boolean and null metadata values while dropping empty keys", async () => {
const client = createClient();
await notify(
{
tenantId: "tenant_1",
userId: "user_1",
messageKey: "foundation.notifications.flags",
payloadMetadata: { active: true, dismissed: false, cleared: null, " ": "ignored" },
},
client,
);
expect(client.notificationDelivery.create).toHaveBeenCalledWith({
data: expect.objectContaining({ payloadMetadata: { active: true, dismissed: false, cleared: null } }),
});
});
test("drops non-serializable values and yields null metadata when nothing survives", async () => {
const client = createClient();
await notify(
{
tenantId: "tenant_1",
userId: "user_1",
messageKey: "foundation.notifications.empty",
payloadMetadata: { nested: { deep: 1 }, infinite: Number.POSITIVE_INFINITY, broken: Number.NaN },
},
client,
);
expect(client.notificationDelivery.create).toHaveBeenCalledWith({ data: expect.objectContaining({ payloadMetadata: null }) });
});
test("truncates over-long string metadata to the configured maximum", async () => {
const client = createClient();
await notify(
{ tenantId: "tenant_1", userId: "user_1", messageKey: "foundation.notifications.long", payloadMetadata: { note: "x".repeat(600) } },
client,
);
const call = client.notificationDelivery.create.mock.calls[0][0] as { data: { payloadMetadata: { note: string } } };
expect(call.data.payloadMetadata.note).toHaveLength(500);
});
});
describe("notify status mapping", () => {
test("queues EMAIL deliveries as PENDING with no send timestamp", async () => {
const client = createClient();
await notify({ tenantId: "tenant_1", userId: "user_1", channel: "EMAIL", category: "billing", messageKey: "foundation.notifications.invoice" }, client);
expect(client.notificationDelivery.create).toHaveBeenCalledWith({
data: expect.objectContaining({ channel: "EMAIL", status: "PENDING", attemptsMade: 0, sentAt: null, lastError: null }),
});
});
test("marks deliveries SKIPPED when a preference disables the channel", async () => {
const client = createClient();
await notify(
{ tenantId: "tenant_1", userId: "user_1", channel: "EMAIL", category: "billing", messageKey: "foundation.notifications.invoice" },
client,
[{ tenantId: "tenant_1", userId: "user_1", channel: "EMAIL", category: "billing", enabled: false }],
);
expect(client.notificationDelivery.create).toHaveBeenCalledWith({
data: expect.objectContaining({ status: "SKIPPED", attemptsMade: 0, lastError: "preference_disabled", sentAt: null }),
});
});
test("persists a null user id for tenant-wide deliveries", async () => {
const client = createClient();
await notify({ tenantId: "tenant_1", messageKey: "foundation.notifications.broadcast" }, client);
expect(client.notificationDelivery.create).toHaveBeenCalledWith({ data: expect.objectContaining({ userId: null, channel: "IN_APP", status: "SENT" }) });
// Without a userId the source-key upsert path is never taken.
expect(client.notificationDelivery.upsert).not.toHaveBeenCalled();
});
test("rejects an unscoped tenant before any write", async () => {
const client = createClient();
await expect(notify({ tenantId: " ", userId: "user_1", messageKey: "foundation.notifications.x" }, client)).rejects.toThrow(
"Notification delivery tenant scope is required.",
);
expect(client.notificationDelivery.create).not.toHaveBeenCalled();
});
});
describe("isNotificationEnabled", () => {
test("defaults to enabled when no preference exists for the scope", () => {
expect(isNotificationEnabled({ tenantId: "tenant_1", userId: "user_1", messageKey: "k" }, [])).toBe(true);
});
test("normalizes the category before matching preferences", () => {
const input: NotificationInput = { tenantId: "tenant_1", userId: "user_1", channel: "IN_APP", category: " Ops ", messageKey: "k" };
expect(isNotificationEnabled(input, [{ tenantId: "tenant_1", userId: "user_1", channel: "IN_APP", category: "ops", enabled: false }])).toBe(false);
});
test("treats a null userId distinctly from a concrete user", () => {
const input: NotificationInput = { tenantId: "tenant_1", userId: null, channel: "IN_APP", category: "ops", messageKey: "k" };
expect(isNotificationEnabled(input, [{ tenantId: "tenant_1", userId: "user_1", channel: "IN_APP", category: "ops", enabled: false }])).toBe(true);
});
});
describe("bundleNotifications", () => {
test("merges same-scope messages and deduplicates message keys", () => {
const bundles = bundleNotifications([
{ tenantId: "tenant_1", userId: "user_1", messageKey: "a" },
{ tenantId: "tenant_1", userId: "user_1", messageKey: "a" },
{ tenantId: "tenant_1", userId: "user_1", messageKey: "b", payloadMetadata: { count: 2 } },
]);
expect(bundles).toEqual([
{
tenantId: "tenant_1",
userId: "user_1",
channel: "IN_APP",
category: "default",
messageKeys: ["a", "b"],
payloadMetadata: { count: 2 },
},
]);
});
test("bundles tenant-wide messages under a null user id", () => {
const bundles = bundleNotifications([
{ tenantId: "tenant_1", messageKey: "a" },
{ tenantId: "tenant_1", messageKey: "b" },
]);
expect(bundles).toHaveLength(1);
expect(bundles[0]).toMatchObject({ userId: null, messageKeys: ["a", "b"] });
});
test("separates bundles across distinct channel/category scopes", () => {
const bundles = bundleNotifications([
{ tenantId: "tenant_1", userId: "user_1", channel: "IN_APP", category: "ops", messageKey: "a" },
{ tenantId: "tenant_1", userId: "user_1", channel: "EMAIL", category: "ops", messageKey: "b" },
]);
expect(bundles).toHaveLength(2);
expect(bundles.map((bundle) => bundle.channel)).toEqual(["IN_APP", "EMAIL"]);
});
});
@@ -0,0 +1,189 @@
import { describe, expect, test, vi } from "vitest";
import { fetchOutboundHttpWithRedirects, readLimitedResponseText, validateOutboundHttpUrl } from "./outbound-http.js";
const publicResolver = vi.fn(async () => ["93.184.216.34"]);
describe("validateOutboundHttpUrl input validation", () => {
test("rejects non-absolute URLs", () => {
expect(() => validateOutboundHttpUrl("not-a-url")).toThrow("Outbound HTTP endpoint must be an absolute URL.");
expect(() => validateOutboundHttpUrl("/relative/path")).toThrow("Outbound HTTP endpoint must be an absolute URL.");
});
test("rejects non-http(s) protocols", () => {
expect(() => validateOutboundHttpUrl("ftp://example.com/file")).toThrow("Outbound HTTP endpoint must use http or https.");
expect(() => validateOutboundHttpUrl("file:///etc/passwd")).toThrow("Outbound HTTP endpoint must use http or https.");
});
test("rejects an empty host and bare single-label hosts", () => {
expect(() => validateOutboundHttpUrl("http:///path")).toThrow("Outbound HTTP endpoint host is not allowed.");
expect(() => validateOutboundHttpUrl("http://intranet/path")).toThrow("Outbound HTTP endpoint host is not allowed.");
});
test("rejects internal host suffixes", () => {
expect(() => validateOutboundHttpUrl("http://payments.svc/charge")).toThrow("Outbound HTTP endpoint host is not allowed.");
expect(() => validateOutboundHttpUrl("https://db.lan/query")).toThrow("Outbound HTTP endpoint host is not allowed.");
});
test("allows a public hostname", () => {
expect(validateOutboundHttpUrl("https://api.example.com/v1")).toBe("https://api.example.com/v1");
});
});
describe("validateOutboundHttpUrl IPv4 SSRF ranges", () => {
test.each([
["http://0.0.0.0/", "this-network"],
["http://10.1.2.3/", "private-A"],
["http://127.0.0.1/", "loopback"],
["http://100.64.0.1/", "carrier-grade-NAT"],
["http://169.254.169.254/", "link-local-metadata"],
["http://172.16.5.4/", "private-B"],
["http://192.168.1.1/", "private-C"],
["http://198.18.0.1/", "benchmarking"],
["http://224.0.0.1/", "multicast"],
])("blocks %s (%s)", (url) => {
expect(() => validateOutboundHttpUrl(url)).toThrow("Outbound HTTP endpoint host is not allowed.");
});
test("allows a routable public IPv4 literal", () => {
expect(validateOutboundHttpUrl("http://93.184.216.34/")).toBe("http://93.184.216.34/");
});
test("treats a dotted host with the wrong segment count as a normal hostname", () => {
// Five labels cannot be an IPv4 literal, so the multi-label public host is allowed through.
expect(validateOutboundHttpUrl("http://a.b.c.d.e/")).toBe("http://a.b.c.d.e/");
});
});
describe("validateOutboundHttpUrl IPv6 SSRF ranges", () => {
test.each([
["http://[::1]/", "loopback"],
["http://[::]/", "unspecified"],
["http://[fc00::1]/", "unique-local"],
["http://[fe80::1]/", "link-local"],
["http://[::ffff:7f00:1]/", "ipv4-mapped-loopback"],
["http://[::7f00:1]/", "ipv4-compatible-loopback"],
])("blocks %s (%s)", (url) => {
expect(() => validateOutboundHttpUrl(url)).toThrow(/Outbound HTTP endpoint host is not allowed\./);
});
test("allows a public IPv6 literal", () => {
expect(validateOutboundHttpUrl("http://[2606:4700:4700::1111]/")).toBe("http://[2606:4700:4700::1111]/");
});
test("allows a fully-expanded eight-group public IPv6 literal", () => {
// No zero-run means the URL parser keeps all eight groups, exercising the non-"::" parse path.
expect(validateOutboundHttpUrl("http://[2001:db8:1:2:3:4:5:6]/")).toBe("http://[2001:db8:1:2:3:4:5:6]/");
});
test("does not misclassify malformed IPv6 with multiple :: groups", () => {
// Two "::" sequences make this an invalid IPv6 literal; the URL parser rejects it outright.
expect(() => validateOutboundHttpUrl("http://[1::2::3]/")).toThrow("Outbound HTTP endpoint must be an absolute URL.");
});
});
describe("fetchOutboundHttpWithRedirects redirect handling", () => {
test("returns the redirect response unchanged when no location header is present", async () => {
const fetchImpl = vi.fn(async () => new Response("redirect-without-location", { status: 302 }));
const result = await fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "GET" }, { fetchImpl, addressResolver: publicResolver });
expect(result.status).toBe(302);
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test("throws once the redirect limit is exhausted", async () => {
const fetchImpl = vi.fn(async () => new Response(null, { status: 302, headers: { location: "https://hooks.example.com/loop" } }));
await expect(
fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "GET" }, { fetchImpl, addressResolver: publicResolver, redirectLimit: 0 }),
).rejects.toThrow("Outbound HTTP redirect limit exceeded.");
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test("converts a 303 redirect into a bodyless GET and strips content headers", async () => {
const fetchImpl = vi
.fn()
.mockResolvedValueOnce(new Response(null, { status: 303, headers: { location: "https://hooks.example.com/result" } }))
.mockResolvedValueOnce(new Response("ok", { status: 200 }));
await expect(
fetchOutboundHttpWithRedirects(
"https://api.example.com/start",
{ method: "POST", body: "payload", headers: { "content-type": "application/json", "content-length": "7", "x-trace": "keep" } },
{ fetchImpl, addressResolver: publicResolver },
),
).resolves.toMatchObject({ status: 200 });
const secondInit = fetchImpl.mock.calls[1][1] as RequestInit & { headers: Headers };
expect(secondInit.method).toBe("GET");
expect(secondInit.body).toBeUndefined();
expect(secondInit.headers.get("content-type")).toBeNull();
expect(secondInit.headers.get("content-length")).toBeNull();
expect(secondInit.headers.get("x-trace")).toBe("keep");
});
test("preserves the method and body for a 307-style redirect", async () => {
const fetchImpl = vi
.fn()
.mockResolvedValueOnce(new Response(null, { status: 307, headers: { location: "https://hooks.example.com/again" } }))
.mockResolvedValueOnce(new Response("ok", { status: 200 }));
await fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "PUT", body: "payload" }, { fetchImpl, addressResolver: publicResolver });
const secondInit = fetchImpl.mock.calls[1][1] as RequestInit;
expect(secondInit.method).toBe("PUT");
expect(secondInit.body).toBe("payload");
});
test("rejects a redirect to a literal private IPv4 target", async () => {
const fetchImpl = vi.fn(async () => new Response(null, { status: 301, headers: { location: "http://192.168.0.5/internal" } }));
await expect(fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "GET" }, { fetchImpl, addressResolver: publicResolver })).rejects.toThrow(
"Outbound HTTP endpoint host is not allowed.",
);
});
test("surfaces a resolver failure as an unresolved-host error", async () => {
const fetchImpl = vi.fn(async () => new Response("nope", { status: 200 }));
const addressResolver = vi.fn(async () => {
throw new Error("ENOTFOUND");
});
await expect(fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "GET" }, { fetchImpl, addressResolver })).rejects.toThrow(
"Outbound HTTP endpoint host could not be resolved.",
);
expect(fetchImpl).not.toHaveBeenCalled();
});
test("rejects a host that resolves to zero addresses", async () => {
const fetchImpl = vi.fn(async () => new Response("nope", { status: 200 }));
const addressResolver = vi.fn(async () => []);
await expect(fetchOutboundHttpWithRedirects("https://api.example.com/start", { method: "GET" }, { fetchImpl, addressResolver })).rejects.toThrow(
"Outbound HTTP endpoint host could not be resolved.",
);
});
test("skips DNS resolution for literal IP endpoints", async () => {
const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
const addressResolver = vi.fn(async () => ["should.not.be.called"]);
await fetchOutboundHttpWithRedirects("http://93.184.216.34/", { method: "GET" }, { fetchImpl, addressResolver });
expect(addressResolver).not.toHaveBeenCalled();
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
});
describe("readLimitedResponseText", () => {
test("returns an empty body when the response has no stream", async () => {
await expect(readLimitedResponseText(new Response(null), 100)).resolves.toEqual({ body: "", truncated: false });
});
test("reads a full short body without truncation", async () => {
await expect(readLimitedResponseText(new Response("ab"), 100)).resolves.toEqual({ body: "ab", truncated: false });
});
test("truncates a body that exceeds the byte limit", async () => {
await expect(readLimitedResponseText(new Response("abcdef"), 3)).resolves.toEqual({ body: "abc", truncated: true });
});
});
@@ -57,4 +57,30 @@ describe("outbound HTTP guard", () => {
const response = new Response("abcdef");
await expect(readLimitedResponseText(response, 3)).resolves.toEqual({ body: "abc", truncated: true });
});
test("pins the connection to the DNS-validated address to defeat rebinding", async () => {
const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
const addressResolver = vi.fn(async () => ["93.184.216.34"]);
await fetchOutboundHttpWithRedirects(
"https://hooks.example.com/webhook",
{ method: "GET" },
{ fetchImpl, addressResolver, pinResolvedAddress: true },
);
// The request must carry a pinned undici dispatcher so undici connects to
// the validated IP instead of re-resolving the hostname at connect time.
const init = fetchImpl.mock.calls[0]?.[1] as (RequestInit & { dispatcher?: unknown }) | undefined;
expect(init?.dispatcher).toBeDefined();
});
test("does not pin when a custom fetchImpl is used without opting in", async () => {
const fetchImpl = vi.fn(async () => new Response("ok", { status: 200 }));
const addressResolver = vi.fn(async () => ["93.184.216.34"]);
await fetchOutboundHttpWithRedirects("https://hooks.example.com/webhook", { method: "GET" }, { fetchImpl, addressResolver });
const init = fetchImpl.mock.calls[0]?.[1] as (RequestInit & { dispatcher?: unknown }) | undefined;
expect(init?.dispatcher).toBeUndefined();
});
});
@@ -1,3 +1,5 @@
import type { LookupFunction } from "node:net";
const DEFAULT_OUTBOUND_HTTP_TIMEOUT_MS = 10_000;
const DEFAULT_OUTBOUND_HTTP_REDIRECT_LIMIT = 5;
const DEFAULT_OUTBOUND_HTTP_RESPONSE_LIMIT_BYTES = 16_384;
@@ -15,6 +17,14 @@ export type OutboundHttpFetchOptions = {
addressResolver?: OutboundHttpAddressResolver;
timeoutMs?: number;
redirectLimit?: number;
/**
* Pin the TCP connection to the DNS-validated IP so a low-TTL hostname cannot
* answer a public address to the guard and an internal one to the connect
* (DNS-rebinding TOCTOU). Defaults to true when the default fetch is used and
* false when a custom fetchImpl is injected (unit tests), which keeps the
* guard mock-driven without pulling in the pinning dispatcher.
*/
pinResolvedAddress?: boolean;
};
export type LimitedResponseBody = {
@@ -25,15 +35,26 @@ export type LimitedResponseBody = {
export type OutboundHttpAddressResolver = (hostname: string) => Promise<ReadonlyArray<string>>;
export async function fetchOutboundHttpWithRedirects(input: string, init: RequestInit, options: OutboundHttpFetchOptions = {}): Promise<Response> {
const fetchImpl = options.fetchImpl ?? fetch;
const usingDefaultFetch = !options.fetchImpl;
const pin = options.pinResolvedAddress ?? usingDefaultFetch;
// When pinning we must use undici's own fetch so the pinned Agent dispatcher
// is recognised (Node's global fetch rejects an Agent from a different undici
// instance). With a custom fetchImpl (tests) we never pin.
const fetchImpl = options.fetchImpl ?? (pin ? await getUndiciFetch() : fetch);
const addressResolver = options.addressResolver ?? resolveOutboundHttpAddresses;
const redirectLimit = options.redirectLimit ?? DEFAULT_OUTBOUND_HTTP_REDIRECT_LIMIT;
let currentUrl = validateOutboundHttpUrl(input);
let currentInit = init;
for (let redirects = 0; redirects <= redirectLimit; redirects += 1) {
await assertOutboundHttpResolvedAddresses(currentUrl, addressResolver);
const response = await fetchOutboundHttpWithTimeout(fetchImpl, currentUrl, currentInit, options.timeoutMs ?? DEFAULT_OUTBOUND_HTTP_TIMEOUT_MS);
const validatedAddresses = await assertOutboundHttpResolvedAddresses(currentUrl, addressResolver);
const response = await fetchOutboundHttpWithTimeout(
fetchImpl,
currentUrl,
currentInit,
options.timeoutMs ?? DEFAULT_OUTBOUND_HTTP_TIMEOUT_MS,
pin ? validatedAddresses : null,
);
if (!isRedirectResponse(response.status)) {
return response;
}
@@ -108,11 +129,13 @@ export function validateOutboundHttpUrl(endpoint: string): string {
return url.toString();
}
async function assertOutboundHttpResolvedAddresses(endpoint: string, addressResolver: OutboundHttpAddressResolver): Promise<void> {
async function assertOutboundHttpResolvedAddresses(endpoint: string, addressResolver: OutboundHttpAddressResolver): Promise<ReadonlyArray<string>> {
const url = new URL(endpoint);
const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
// An IP literal has already been vetted by validateOutboundHttpUrl and needs
// no DNS resolution — return it so the connection pins to exactly that IP.
if (parseIpv4Address(hostname) || parseIpv6Address(hostname)) {
return;
return [hostname];
}
let addresses: ReadonlyArray<string>;
@@ -129,6 +152,8 @@ async function assertOutboundHttpResolvedAddresses(endpoint: string, addressReso
if (addresses.some((address) => isBlockedOutboundHostname(address))) {
throw new OutboundHttpUrlValidationError("Outbound HTTP endpoint resolved to a blocked address.");
}
return addresses;
}
async function resolveOutboundHttpAddresses(hostname: string): Promise<ReadonlyArray<string>> {
@@ -137,17 +162,63 @@ async function resolveOutboundHttpAddresses(hostname: string): Promise<ReadonlyA
return addresses.map((address) => address.address);
}
async function fetchOutboundHttpWithTimeout(fetchImpl: typeof fetch, input: Parameters<typeof fetch>[0], init: RequestInit, timeoutMs: number): Promise<Response> {
async function fetchOutboundHttpWithTimeout(
fetchImpl: typeof fetch,
input: Parameters<typeof fetch>[0],
init: RequestInit,
timeoutMs: number,
pinnedAddresses: ReadonlyArray<string> | null,
): Promise<Response> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetchImpl(input, { ...init, redirect: "manual", signal: controller.signal });
const baseInit = { ...init, redirect: "manual" as const, signal: controller.signal };
if (pinnedAddresses && pinnedAddresses.length > 0) {
// `dispatcher` is a Node/undici extension to RequestInit; the pinned Agent
// forces the socket to the DNS-validated IP while undici keeps the URL
// hostname as the TLS SNI/servername.
const dispatcher = await buildPinnedDispatcher(pinnedAddresses);
return await fetchImpl(input, { ...baseInit, dispatcher } as RequestInit);
}
return await fetchImpl(input, baseInit);
} finally {
clearTimeout(timeout);
}
}
let undiciModulePromise: Promise<typeof import("undici")> | null = null;
function loadUndici(): Promise<typeof import("undici")> {
undiciModulePromise ??= import("undici");
return undiciModulePromise;
}
async function getUndiciFetch(): Promise<typeof fetch> {
const { fetch: undiciFetch } = await loadUndici();
return undiciFetch as unknown as typeof fetch;
}
/**
* Build a one-shot undici dispatcher whose connect step resolves the hostname
* to the already-validated IP set instead of doing its own DNS lookup. This
* closes the rebinding TOCTOU: the connection can only reach an address the
* blocklist already cleared.
*/
async function buildPinnedDispatcher(addresses: ReadonlyArray<string>): Promise<unknown> {
const { Agent } = await loadUndici();
const vetted = addresses.map((address) => ({ address, family: address.includes(":") ? 6 : 4 }));
const [primary] = vetted;
const lookup: LookupFunction = (_hostname, lookupOptions, callback) => {
if (lookupOptions && typeof lookupOptions === "object" && lookupOptions.all) {
callback(null, vetted);
return;
}
callback(null, primary?.address ?? "", primary?.family ?? 4);
};
return new Agent({ connect: { lookup } });
}
function resolveOutboundHttpRedirect(currentUrl: string, location: string): string {
let redirectUrl: URL;
try {
@@ -0,0 +1,83 @@
import { describe, expect, test, vi } from "vitest";
import { CatalogError } from "./errors.js";
import { requirePermission, withOwnerCheck, withPermission, withTenantScope } from "./permissions.js";
describe("requirePermission", () => {
test("returns the context unchanged when the permission is present in an array", () => {
const context = { permissions: ["resource.view", "resource.edit"] };
expect(requirePermission(context, "resource.edit")).toBe(context);
});
test("accepts a ReadonlySet of permissions", () => {
const context = { permissions: new Set(["resource.view"]) };
expect(requirePermission(context, "resource.view")).toBe(context);
});
test("throws a not-found catalog error when the permission is missing", () => {
try {
requirePermission({ permissions: ["resource.view"] }, "resource.delete");
throw new Error("expected throw");
} catch (error) {
expect(error).toBeInstanceOf(CatalogError);
expect((error as CatalogError).code).toBe("foundation.not_found");
expect((error as CatalogError).details).toEqual({ permission: "resource.delete" });
}
});
test("treats an absent permissions field as an empty permission set", () => {
expect(() => requirePermission({}, "resource.view")).toThrow(CatalogError);
});
});
describe("withPermission", () => {
test("invokes the handler with the original arguments when the permission is granted", () => {
const handler = vi.fn((a: number, b: number) => a + b);
const guarded = withPermission(
"calc.run",
() => ({ permissions: ["calc.run"] }),
handler,
);
expect(guarded(2, 3)).toBe(5);
expect(handler).toHaveBeenCalledWith(2, 3);
});
test("rejects before the handler runs when the permission is missing", () => {
const handler = vi.fn();
const guarded = withPermission("calc.run", () => ({ permissions: [] }), handler);
expect(() => guarded()).toThrow(CatalogError);
expect(handler).not.toHaveBeenCalled();
});
});
describe("withOwnerCheck", () => {
test("returns the value when the owner matches the acting user", () => {
const value = { ownerId: "user_1", payload: "secret" };
expect(withOwnerCheck({ userId: "user_1" }, value)).toBe(value);
});
test("hides ownership mismatches behind a not-found error", () => {
expect(() => withOwnerCheck({ userId: "user_1" }, { ownerId: "user_2" })).toThrow(/foundation.not_found/);
});
test("rejects when the value is null or undefined", () => {
expect(() => withOwnerCheck({ userId: "user_1" }, null)).toThrow(CatalogError);
expect(() => withOwnerCheck({ userId: "user_1" }, undefined)).toThrow(CatalogError);
});
test("rejects when the context has no acting user", () => {
expect(() => withOwnerCheck({}, { ownerId: "user_1" })).toThrow(CatalogError);
});
});
describe("withTenantScope", () => {
test("attaches the tenant id without mutating the source object", () => {
const value = { id: "row_1" };
const scoped = withTenantScope("tenant_9", value);
expect(scoped).toEqual({ id: "row_1", tenantId: "tenant_9" });
expect(value).not.toHaveProperty("tenantId");
});
});
@@ -0,0 +1,180 @@
import { describe, expect, test } from "vitest";
import {
extractWorkflowReferences,
getNativeWorkflowTriggerCapabilityErrors,
getWorkflowBlockContract,
validateWorkflowRequiredInputs,
type WorkflowBlockType,
type WorkflowNativeCapabilityBlock,
type WorkflowPreflightBlock,
} from "./workflows.js";
function nativeBlock(overrides: Partial<WorkflowNativeCapabilityBlock>): WorkflowNativeCapabilityBlock {
return { id: "block_1", type: "manual", input: {}, conditionGroups: [], toBlocks: [], ...overrides };
}
const trigger = nativeBlock({ id: "trigger", type: "event", isTrigger: true, input: { event: "row.updated" } });
describe("getWorkflowBlockContract", () => {
test("throws on an unregistered block type", () => {
expect(() => getWorkflowBlockContract("nope" as WorkflowBlockType)).toThrow("Unknown workflow block contract: nope");
});
});
describe("native trigger capability: switch blocks", () => {
test("accepts a well-formed switch with matching case and default edges", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({
id: "sw",
type: "switch",
conditionGroups: [{ index: 0, conditions: [{ variable: "{{$vars.plan}}", value: "pro" }] }],
toBlocks: [
{ id: "c1", condition: "case1" },
{ id: "d", condition: "default" },
],
}),
]),
).toEqual([]);
});
test("flags a missing default edge and a missing case edge", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({
id: "sw",
type: "switch",
conditionGroups: [{ index: 0, conditions: [{ variable: "{{$vars.plan}}", value: "pro" }] }],
toBlocks: [],
}),
]),
).toEqual(["switch block sw is missing default edge", "switch block sw is missing case1 edge"]);
});
test("flags a switch condition group that has no conditions", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({
id: "sw",
type: "switch",
conditionGroups: [{ index: 0, conditions: [] }],
toBlocks: [
{ id: "c1", condition: "case1" },
{ id: "d", condition: "default" },
],
}),
]),
).toEqual(["switch block sw condition group 1 must have at least one condition"]);
});
});
describe("native trigger capability: if blocks", () => {
test("flags an empty condition group and a missing true edge", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({
id: "if1",
type: "if",
conditionGroups: [{ index: 0, conditions: [] }],
toBlocks: [{ id: "f", condition: "false" }],
}),
]),
).toEqual(["if block if1 must have at least one condition", "if block if1 is missing true edge"]);
});
test("reads condition groups from the legacy conditionsGroups alias", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({
id: "if2",
type: "if",
conditionGroups: undefined,
conditionsGroups: [{ index: 0, conditions: [{ variable: "{{$vars.plan}}", value: "pro" }] }],
toBlocks: [
{ id: "t", condition: "true" },
{ id: "f", condition: "false" },
],
}),
]),
).toEqual([]);
});
});
describe("native trigger capability: persisted block input", () => {
test("parses a JSON-string block input and detects its credential references", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({ id: "log", type: "log", input: '{"message":"{{$credentials.apiToken}}"}' }),
]),
).toEqual(['unsupported credential reference "apiToken" on block log']);
});
test("ignores unparseable JSON-string input instead of scanning the raw string", () => {
expect(getNativeWorkflowTriggerCapabilityErrors([trigger, nativeBlock({ id: "log", type: "log", input: "not json {{$credentials.x}}" })])).toEqual([]);
});
test("ignores JSON-string input that decodes to a non-object", () => {
expect(getNativeWorkflowTriggerCapabilityErrors([trigger, nativeBlock({ id: "log", type: "log", input: '["{{$credentials.x}}"]' })])).toEqual([]);
});
});
describe("native trigger capability: edges", () => {
test("flags a non-empty edge condition on a block type that has no branching semantics", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({ id: "log", type: "log", input: { message: "hi" }, toBlocks: [{ id: "e1", condition: "weird" }] }),
]),
).toEqual(['unsupported conditional edge "e1" from block log']);
});
test("ignores blank edge conditions", () => {
expect(
getNativeWorkflowTriggerCapabilityErrors([
trigger,
nativeBlock({ id: "log", type: "log", input: { message: "hi" }, toBlocks: [{ id: "e1", condition: " " }, { id: "e2", condition: null }] }),
]),
).toEqual([]);
});
});
describe("validateWorkflowRequiredInputs edge cases", () => {
test("skips blocks whose type is not part of the contract registry", () => {
expect(validateWorkflowRequiredInputs({ blocks: [{ id: "x", type: "unknownType", input: {} }] })).toEqual([]);
});
test("treats a non-record block input as an empty input object", () => {
expect(validateWorkflowRequiredInputs({ blocks: [{ id: "http", type: "httpRequest", input: "not-an-object" }] })).toEqual([
{ blockId: "http", blockType: "httpRequest", missingInputs: ["url", "method"] },
]);
});
test("accepts non-string, non-null required input values as present", () => {
expect(
validateWorkflowRequiredInputs({
blocks: [{ id: "iter", type: "iterator", input: { variableName: 0 } }],
}),
).toEqual([]);
});
});
describe("extractWorkflowReferences variable definition edge cases", () => {
test("ignores variable blocks whose input is not a record when collecting local names", () => {
const references = extractWorkflowReferences({
blocks: [
{ id: "define", type: "variable", input: "not-a-record" } as WorkflowPreflightBlock,
{ id: "use", type: "log", input: { message: "{{$vars.localName}}" } },
],
});
// The malformed variable block defines no local name, so the reference stays unresolved/global.
expect(references.variables).toEqual(["localName"]);
});
});