@notionhq/workers 0.7.0 → 0.8.1

package/src/credential.test.ts

@@ -0,0 +1,324 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+	CredentialConfiguration,
+	CredentialHeaderTransform,
+	CredentialKey,
+	CredentialNetworkRule,
+} from "./credential.js";
+import {
+	CREDENTIAL_VALUE,
+	createCredentialDeclaration,
+	validateCredentialDeclarationConflicts,
+} from "./credential.js";
+
+describe("credential declarations", () => {
+	it("serializes symbolic header templates without a credential value", () => {
+		const key: CredentialKey = "LINEAR_API_TOKEN";
+		const network = [
+			{
+				domain: "API.LINEAR.COM.",
+				transform: [
+					{
+						headers: {
+							Authorization: `Bearer ${CREDENTIAL_VALUE}`,
+							"x-api-key": CREDENTIAL_VALUE,
+							Cookie: `session=${CREDENTIAL_VALUE}; Secure`,
+						},
+					},
+				],
+			},
+		] satisfies readonly CredentialNetworkRule[];
+		const declaration = createCredentialDeclaration(key, { network });
+
+		expect(declaration).toEqual({
+			key: "LINEAR_API_TOKEN",
+			network: [
+				{
+					domain: "api.linear.com",
+					transform: [
+						{
+							headers: {
+								Authorization: "Bearer {{credential}}",
+								"x-api-key": "{{credential}}",
+								Cookie: "session={{credential}}; Secure",
+							},
+						},
+					],
+				},
+			],
+		});
+		expect(JSON.stringify(declaration)).not.toContain("lin_api_123");
+	});
+
+	it("supports pre-encoded Basic auth and Vercel wildcard domains", () => {
+		const declaration = createCredentialDeclaration("BASIC_CREDENTIAL", {
+			network: [
+				{
+					domain: "*.github.com",
+					transform: [
+						{
+							headers: {
+								Authorization: `Basic ${CREDENTIAL_VALUE}`,
+							},
+						},
+					],
+				},
+			],
+		});
+
+		expect(declaration.network[0]?.domain).toBe("*.github.com");
+	});
+
+	it.each([
+		["invalid key", "1TOKEN"],
+		["reserved key", "NOTION_PRIVATE_TOKEN"],
+		["case-insensitive reserved key", "notion_private_token"],
+	])("rejects %s", (_testCase, key) => {
+		expect(() =>
+			createCredentialDeclaration(key, {
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: { Authorization: CREDENTIAL_VALUE },
+							},
+						],
+					},
+				],
+			}),
+		).toThrow();
+	});
+
+	it.each(["NOTION_API_TOKEN", "notion_api_token"])(
+		"allows credential keys supported by the existing secret store: %s",
+		(key) => {
+			expect(
+				createCredentialDeclaration(key, {
+					network: [
+						{
+							domain: "api.notion.com",
+							transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+						},
+					],
+				}).key,
+			).toBe(key);
+		},
+	);
+
+	it("rejects unsafe domains, header names, and header templates", () => {
+		const validTransform = [
+			{
+				headers: { Authorization: CREDENTIAL_VALUE },
+			},
+		] satisfies readonly CredentialHeaderTransform[];
+		const configuration: CredentialConfiguration = {
+			network: [
+				{
+					domain: "api.example.com",
+					transform: validTransform,
+				},
+			],
+		};
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				...configuration,
+				network: [
+					{
+						domain: "https://evil.com",
+						transform: validTransform,
+					},
+				],
+			}),
+		).toThrow("must be an exact hostname");
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				...configuration,
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: { "bad header": CREDENTIAL_VALUE },
+							},
+						],
+					},
+				],
+			}),
+		).toThrow("Invalid credential header name");
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				...configuration,
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: `Bearer\r\nX-Leak: ${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow("cannot contain control characters");
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				...configuration,
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: `Bearer\t${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow("cannot contain control characters");
+
+		for (const template of ["Bearer token", `${CREDENTIAL_VALUE}${CREDENTIAL_VALUE}`]) {
+			expect(() =>
+				createCredentialDeclaration("TOKEN", {
+					...configuration,
+					network: [
+						{
+							domain: "api.example.com",
+							transform: [{ headers: { Authorization: template } }],
+						},
+					],
+				}),
+			).toThrow("must contain CREDENTIAL_VALUE exactly once");
+		}
+	});
+
+	it("detects header conflicts across overlapping wildcard domains", () => {
+		const existing = createCredentialDeclaration("FIRST_TOKEN", {
+			network: [
+				{
+					domain: "*.example.com",
+					transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+				},
+			],
+		});
+		const overlapping = createCredentialDeclaration("SECOND_TOKEN", {
+			network: [
+				{
+					domain: "api.example.com",
+					transform: [{ headers: { authorization: CREDENTIAL_VALUE } }],
+				},
+			],
+		});
+		const unrelated = createCredentialDeclaration("THIRD_TOKEN", {
+			network: [
+				{
+					domain: "api.example.net",
+					transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+				},
+			],
+		});
+
+		expect(() => validateCredentialDeclarationConflicts([existing], overlapping)).toThrow(
+			'conflicts with credential "FIRST_TOKEN"',
+		);
+		expect(() => validateCredentialDeclarationConflicts([existing], unrelated)).not.toThrow();
+	});
+
+	it("rejects duplicate domains and empty transforms", () => {
+		const transform = [{ headers: { Authorization: CREDENTIAL_VALUE } }];
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				network: [
+					{ domain: "API.EXAMPLE.COM", transform },
+					{ domain: "api.example.com.", transform },
+				],
+			}),
+		).toThrow("more than once");
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				network: [{ domain: "api.example.com", transform: [] }],
+			}),
+		).toThrow("must declare 1-20 transforms");
+
+		expect(() =>
+			createCredentialDeclaration("TOKEN", {
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{ headers: { Authorization: CREDENTIAL_VALUE } },
+							{ headers: { authorization: CREDENTIAL_VALUE } },
+						],
+					},
+				],
+			}),
+		).toThrow("declares header");
+	});
+
+	it("matches the service bounds for transforms, headers, and strings", () => {
+		const tooManyTransforms = Array.from({ length: 21 }, (_, index) => ({
+			headers: { [`X-Token-${index}`]: CREDENTIAL_VALUE },
+		}));
+		const tooManyHeaders = Object.fromEntries(
+			Array.from({ length: 21 }, (_, index) => [`X-Token-${index}`, CREDENTIAL_VALUE]),
+		);
+		const configurations: CredentialConfiguration[] = [
+			{
+				network: [{ domain: "api.example.com", transform: tooManyTransforms }],
+			},
+			{
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [{ headers: tooManyHeaders }],
+					},
+				],
+			},
+			{
+				network: [
+					{
+						domain: `${"a.".repeat(126)}com`,
+						transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			},
+			{
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [{ headers: { ["X".repeat(257)]: CREDENTIAL_VALUE } }],
+					},
+				],
+			},
+			{
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: `${"x".repeat(8 * 1024)}${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			},
+		];
+
+		for (const configuration of configurations) {
+			expect(() => createCredentialDeclaration("TOKEN", configuration)).toThrow();
+		}
+	});
+});

package/src/credential.ts

@@ -0,0 +1,238 @@
+/**
+ * A symbolic marker for the declared credential value. It is safe to include
+ * in Worker source and manifests because it never contains the stored secret.
+ */
+export const CREDENTIAL_VALUE = "{{credential}}";
+
+/** @internal */
+export const MAX_CREDENTIALS = 100;
+
+/** @internal */
+export const MAX_CREDENTIAL_DECLARATIONS_BYTES = 256 * 1024;
+
+const MAX_NETWORK_RULES_PER_CREDENTIAL = 20;
+const MAX_TRANSFORMS_PER_NETWORK_RULE = 20;
+const MAX_HEADERS_PER_NETWORK_RULE = 20;
+const MAX_DOMAIN_LENGTH = 253;
+const MAX_HEADER_NAME_LENGTH = 256;
+const MAX_HEADER_TEMPLATE_BYTES = 8 * 1024;
+const ALLOWED_NOTION_CREDENTIAL_KEYS = new Set(["NOTION_API_TOKEN", "NOTION_API_BASE_URL"]);
+const CREDENTIAL_DOMAIN_PATTERN =
+	/^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export type CredentialKey = string;
+
+/** A Vercel-compatible collection of headers to add or replace. */
+export type CredentialHeaderTransform = {
+	readonly headers: Readonly<Record<string, string>>;
+};
+
+/**
+ * Limits credential injection to a domain. This does not grant or deny general
+ * network egress; the sandbox's egress policy remains a separate concern.
+ */
+export type CredentialNetworkRule = {
+	readonly domain: string;
+	readonly transform: readonly CredentialHeaderTransform[];
+};
+
+export type CredentialConfiguration = {
+	/** Destinations and header templates where the credential may be injected. */
+	readonly network: readonly CredentialNetworkRule[];
+};
+
+export type CredentialDeclaration = CredentialConfiguration & {
+	readonly key: CredentialKey;
+};
+
+/** @internal */
+export function createCredentialDeclaration(
+	key: CredentialKey,
+	config: CredentialConfiguration,
+): CredentialDeclaration {
+	validateCredentialKey(key);
+
+	if (config.network.length === 0) {
+		throw new Error(`Credential "${key}" must declare at least one network rule`);
+	}
+	if (config.network.length > MAX_NETWORK_RULES_PER_CREDENTIAL) {
+		throw new Error(
+			`Credential "${key}" cannot declare more than ${MAX_NETWORK_RULES_PER_CREDENTIAL} domains`,
+		);
+	}
+
+	const domains = new Set<string>();
+	const network = config.network.map((rule) => {
+		const domain = normalizeDomain(rule.domain);
+		if (domains.has(domain)) {
+			throw new Error(`Credential "${key}" declares domain "${domain}" more than once`);
+		}
+		domains.add(domain);
+
+		if (rule.transform.length === 0 || rule.transform.length > MAX_TRANSFORMS_PER_NETWORK_RULE) {
+			throw new Error(
+				`Credential "${key}" must declare 1-${MAX_TRANSFORMS_PER_NETWORK_RULE} transforms for domain "${domain}"`,
+			);
+		}
+
+		const headerNames = new Set<string>();
+		return {
+			domain,
+			transform: rule.transform.map((transform) => {
+				const headers = normalizeHeaders({
+					credentialKey: key,
+					domain,
+					headers: transform.headers,
+				});
+				for (const headerName of Object.keys(headers)) {
+					const normalizedHeaderName = headerName.toLowerCase();
+					if (headerNames.has(normalizedHeaderName)) {
+						throw new Error(
+							`Credential "${key}" declares header "${headerName}" more than once for domain "${domain}"`,
+						);
+					}
+					headerNames.add(normalizedHeaderName);
+					if (headerNames.size > MAX_HEADERS_PER_NETWORK_RULE) {
+						throw new Error(
+							`Credential "${key}" cannot inject more than ${MAX_HEADERS_PER_NETWORK_RULE} headers for domain "${domain}"`,
+						);
+					}
+				}
+				return { headers };
+			}),
+		};
+	});
+
+	return {
+		key,
+		network,
+	};
+}
+
+/** @internal */
+export function validateCredentialDeclarationConflicts(
+	existingDeclarations: Iterable<CredentialDeclaration>,
+	declaration: CredentialDeclaration,
+): void {
+	for (const existing of existingDeclarations) {
+		for (const rule of declaration.network) {
+			for (const existingRule of existing.network) {
+				if (!credentialDomainsOverlap(rule.domain, existingRule.domain)) {
+					continue;
+				}
+
+				const existingHeaders = new Set(
+					existingRule.transform.flatMap((transform) =>
+						Object.keys(transform.headers).map((name) => name.toLowerCase()),
+					),
+				);
+				for (const transform of rule.transform) {
+					for (const headerName of Object.keys(transform.headers)) {
+						if (existingHeaders.has(headerName.toLowerCase())) {
+							throw new Error(
+								`Credential "${declaration.key}" conflicts with credential "${existing.key}" for header "${headerName}" on overlapping domains "${rule.domain}" and "${existingRule.domain}"`,
+							);
+						}
+					}
+				}
+			}
+		}
+	}
+}
+
+function validateCredentialKey(key: CredentialKey): void {
+	if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key)) {
+		throw new Error(
+			`Credential key "${key}" must start with a letter, contain only letters, numbers, or underscores, and be at most 64 characters`,
+		);
+	}
+	const normalizedKey = key.toUpperCase();
+	if (normalizedKey.startsWith("NOTION_") && !ALLOWED_NOTION_CREDENTIAL_KEYS.has(normalizedKey)) {
+		throw new Error(`Credential key "${key}" uses the reserved NOTION_ prefix`);
+	}
+}
+
+function normalizeDomain(value: string): string {
+	const domain = value.trim().toLowerCase().replace(/\.$/, "");
+	if (domain.length > MAX_DOMAIN_LENGTH || !CREDENTIAL_DOMAIN_PATTERN.test(domain)) {
+		throw new Error(
+			`Credential network domain "${value}" must be an exact hostname or a leading wildcard such as "*.example.com"`,
+		);
+	}
+	return domain;
+}
+
+function credentialDomainsOverlap(first: string, second: string): boolean {
+	if (first === second) {
+		return true;
+	}
+
+	const firstBase = first.startsWith("*.") ? first.slice(2) : undefined;
+	const secondBase = second.startsWith("*.") ? second.slice(2) : undefined;
+	if (firstBase === undefined && secondBase === undefined) {
+		return false;
+	}
+	if (firstBase !== undefined && secondBase === undefined) {
+		return second.endsWith(`.${firstBase}`);
+	}
+	if (firstBase === undefined && secondBase !== undefined) {
+		return first.endsWith(`.${secondBase}`);
+	}
+
+	return (
+		firstBase !== undefined &&
+		secondBase !== undefined &&
+		(firstBase.endsWith(`.${secondBase}`) || secondBase.endsWith(`.${firstBase}`))
+	);
+}
+
+function normalizeHeaders(args: {
+	credentialKey: string;
+	domain: string;
+	headers: Readonly<Record<string, string>>;
+}): Readonly<Record<string, string>> {
+	const entries = Object.entries(args.headers);
+	if (entries.length === 0) {
+		throw new Error(
+			`Credential "${args.credentialKey}" has an empty header transform for domain "${args.domain}"`,
+		);
+	}
+
+	return Object.fromEntries(
+		entries.map(([name, template]) => {
+			if (name.length > MAX_HEADER_NAME_LENGTH || !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) {
+				throw new Error(`Invalid credential header name "${name}"`);
+			}
+			if (typeof template !== "string") {
+				throw new Error(`Credential header "${name}" must use a string template`);
+			}
+			validateHeaderTemplate(name, template);
+			return [name, template];
+		}),
+	);
+}
+
+function validateHeaderTemplate(name: string, template: string): void {
+	if (hasControlCharacters(template)) {
+		throw new Error(`Credential header "${name}" template cannot contain control characters`);
+	}
+
+	const markerCount = template.split(CREDENTIAL_VALUE).length - 1;
+	if (markerCount !== 1) {
+		throw new Error(
+			`Credential header "${name}" template must contain CREDENTIAL_VALUE exactly once`,
+		);
+	}
+	if (new TextEncoder().encode(template).byteLength > MAX_HEADER_TEMPLATE_BYTES) {
+		throw new Error(
+			`Credential header "${name}" template must be at most ${MAX_HEADER_TEMPLATE_BYTES} bytes`,
+		);
+	}
+}
+
+function hasControlCharacters(value: string): boolean {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0);
+		return codePoint !== undefined && (codePoint <= 0x1f || codePoint === 0x7f);
+	});
+}

package/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+	CustomBlockCapability,
+	CustomBlockCapabilityConfig,
+	CustomBlockConfiguration,
+	CustomBlockManifest,
+	CustomBlockManifestDataSource,
+} from "./capabilities/custom-block.js";
 export { emojiIcon, imageCover, imageIcon, notionIcon, place } from "./builder.js";
 export type {
 	AiConnectorArchetype,
@@ -51,6 +58,14 @@ export type {
 	WorkflowEventForTrigger,
 	WorkflowEventForTriggers,
 } from "./capabilities/workflow.js";
+export type {
+	CredentialConfiguration,
+	CredentialDeclaration,
+	CredentialHeaderTransform,
+	CredentialKey,
+	CredentialNetworkRule,
+} from "./credential.js";
+export { CREDENTIAL_VALUE } from "./credential.js";
 export { RateLimitError } from "./error.js";
 export type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
 export type { Infer, SchemaBuilder } from "./schema-builder.js";