Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
+89
@@ -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";
|
||||
+103
@@ -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";
|
||||
|
||||
+60
@@ -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"]);
|
||||
});
|
||||
});
|
||||
+111
@@ -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 };
|
||||
}
|
||||
+47
@@ -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" });
|
||||
}
|
||||
});
|
||||
});
|
||||
+176
@@ -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"]);
|
||||
});
|
||||
});
|
||||
+189
@@ -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 });
|
||||
});
|
||||
});
|
||||
+26
@@ -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");
|
||||
});
|
||||
});
|
||||
+180
@@ -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"]);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user