@notionhq/apps 0.0.18 → 0.0.20

package/src/workflow-access.ts

@@ -0,0 +1,299 @@
+import type { CustomAgentHandle } from "./notion-as-code/custom-agent.js";
+import type {
+	DataSourceHandle,
+	DatabaseHandle,
+	SingleSourceDatabaseHandle,
+} from "./notion-as-code/database.js";
+import type { PageHandle } from "./notion-as-code/page.js";
+
+/** A Notion-as-Code resource that can provide a named workflow binding. */
+export type WorkflowAccessResource =
+	| PageHandle
+	| DatabaseHandle
+	| SingleSourceDatabaseHandle
+	| DataSourceHandle
+	| CustomAgentHandle;
+
+/** Resource kinds accepted by workflow access declarations. */
+export type WorkflowAccessResourceType = WorkflowAccessResource["resourceType"];
+
+/** Levels accepted by pages, databases, and data sources. */
+export type WorkflowAccessResourceLevel = "view" | "comment" | "edit" | "fullAccess";
+
+/** The only level accepted by a custom agent. */
+export type WorkflowAccessAgentLevel = "call";
+
+/** Every level accepted by at least one workflow access resource. */
+export type WorkflowAccessLevel = WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+
+/** The level set accepted by a particular resource kind. */
+export type WorkflowAccessLevelFor<TType extends WorkflowAccessResourceType> =
+	TType extends "customAgent" ? WorkflowAccessAgentLevel : WorkflowAccessResourceLevel;
+
+type AccessResourceFor<TType extends WorkflowAccessResourceType> = Extract<
+	WorkflowAccessResource,
+	{ resourceType: TType }
+>;
+
+/** A named binding declaration pairing one NaC handle with its allowed level. */
+export type WorkflowAccessDeclaration = {
+	[TType in WorkflowAccessResourceType]: {
+		readonly resource: AccessResourceFor<TType>;
+		readonly level: WorkflowAccessLevelFor<TType>;
+	};
+}[WorkflowAccessResourceType];
+
+/** Named binding declarations keyed by the names exposed on workflow context. */
+export type WorkflowAccessDeclarations = Readonly<Record<string, WorkflowAccessDeclaration>>;
+
+/** A normalized named-binding requirement, including the required NaC resourceId. */
+export type WorkflowAccessRequirement = {
+	[TType in WorkflowAccessResourceType]: {
+		readonly type: TType;
+		readonly resourceId: string;
+		readonly level: WorkflowAccessLevelFor<TType>;
+	};
+}[WorkflowAccessResourceType];
+
+/** Normalized named-binding requirements keyed by public alias. */
+export type WorkflowAccessRequirements = Readonly<Record<string, WorkflowAccessRequirement>>;
+
+/** The resolved NaC binding exposed to a workflow handler. */
+export type WorkflowAccessValue<
+	TType extends WorkflowAccessResourceType = WorkflowAccessResourceType,
+> = Readonly<{
+	type: TType;
+	id: string;
+}>;
+
+/** Resolved access values keyed by their public aliases. */
+export type WorkflowAccess<
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
+> = Readonly<{
+	[TKey in keyof TAccess]: TAccess[TKey] extends {
+		readonly resource: { readonly resourceType: infer TType };
+	}
+		? TType extends WorkflowAccessResourceType
+			? WorkflowAccessValue<TType>
+			: never
+		: never;
+}>;
+
+/** Resolved NaC bindings keyed by public aliases, without declaration metadata. */
+export type WorkflowAccessBindings = Readonly<Record<string, WorkflowAccessValue>>;
+
+const ACCESS_ALIAS_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/;
+const RESERVED_ACCESS_ALIASES = new Set<string>(["__proto__", "prototype", "constructor"]);
+const RESOURCE_TYPES: Record<WorkflowAccessResourceType, true> = {
+	page: true,
+	database: true,
+	dataSource: true,
+	customAgent: true,
+};
+
+/**
+ * Normalize public binding declarations without retaining the handle objects.
+ * Handles contain methods and schema objects, so they must never be cloned into
+ * the manifest or captured by the runtime transport. These declarations do not
+ * grant or change the workflow's existing Notion-module permissions.
+ */
+export function normalizeWorkflowAccess(
+	declarations: WorkflowAccessDeclarations | undefined,
+): WorkflowAccessRequirements {
+	const source = declarations ?? {};
+	assertPlainObject(source, "Workflow access must be an object keyed by alias.");
+	const keys = Object.keys(source);
+	if (Reflect.ownKeys(source).length !== keys.length) {
+		throw new Error("Workflow access aliases must be enumerable strings.");
+	}
+	if (keys.length > 100) {
+		throw new Error("Workflows support at most 100 access requirements.");
+	}
+
+	const normalized: Record<string, WorkflowAccessRequirement> = Object.create(null) as Record<
+		string,
+		WorkflowAccessRequirement
+	>;
+	for (const alias of keys) {
+		if (!ACCESS_ALIAS_PATTERN.test(alias) || RESERVED_ACCESS_ALIASES.has(alias)) {
+			throw new Error(`Invalid workflow access alias: ${alias}`);
+		}
+
+		const declaration: unknown = source[alias];
+		if (
+			!isRecord(declaration) ||
+			!Object.hasOwn(declaration, "resource") ||
+			!Object.hasOwn(declaration, "level")
+		) {
+			throw new Error(`Workflow access "${alias}" must declare a resource and level.`);
+		}
+		const resource: unknown = declaration.resource;
+		if (
+			!isRecord(resource) ||
+			!Object.hasOwn(resource, "resourceType") ||
+			!Object.hasOwn(resource, "resourceId") ||
+			typeof resource.resourceId !== "string" ||
+			resource.resourceId.length === 0 ||
+			!isWorkflowAccessResourceType(resource.resourceType)
+		) {
+			throw new Error(
+				`Workflow access "${alias}" must reference a supported NaC resource handle.`,
+			);
+		}
+
+		let requirement: WorkflowAccessRequirement;
+		if (resource.resourceType === "customAgent") {
+			if (declaration.level !== "call") {
+				throw new Error(
+					`Workflow access "${alias}" custom agents only support level "call".`,
+				);
+			}
+			requirement = {
+				type: resource.resourceType,
+				resourceId: resource.resourceId,
+				level: declaration.level,
+			};
+		} else {
+			if (!isWorkflowAccessResourceLevel(declaration.level)) {
+				throw new Error(
+					`Workflow access "${alias}" ${resource.resourceType} level must be view, comment, edit, or fullAccess.`,
+				);
+			}
+			requirement = {
+				type: resource.resourceType,
+				resourceId: resource.resourceId,
+				level: declaration.level,
+			};
+		}
+		normalized[alias] = Object.freeze(requirement);
+	}
+
+	return Object.freeze(normalized);
+}
+
+/**
+ * Resolve trusted per-invocation NaC bindings into the minimal context value.
+ * This exposes only declared aliases and does not determine Notion API
+ * authorization; the workflow's existing Notion-module permissions do that.
+ * The environment is deliberately not parsed when no binding is required.
+ */
+export function hydrateWorkflowAccess<TAccess extends WorkflowAccessDeclarations>(
+	requirements: WorkflowAccessRequirements | undefined,
+): WorkflowAccess<TAccess>;
+export function hydrateWorkflowAccess(
+	requirements: WorkflowAccessRequirements | undefined,
+): WorkflowAccessBindings {
+	const expected = requirements ?? {};
+	const aliases = Object.keys(expected);
+	const empty: Record<string, WorkflowAccessValue> = Object.create(null) as Record<
+		string,
+		WorkflowAccessValue
+	>;
+	if (aliases.length === 0) {
+		return Object.freeze(empty);
+	}
+
+	const rawBindings = process.env.NOTION_ACCESS_BINDINGS;
+	if (rawBindings === undefined) {
+		throw new Error(
+			"Workflow access requirements are not bound. Deploy and configure this requirement before running it.",
+		);
+	}
+	if (rawBindings.length === 0) {
+		throw new Error("Invalid NOTION_ACCESS_BINDINGS metadata.");
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(rawBindings);
+	} catch (error) {
+		throw new Error("Invalid NOTION_ACCESS_BINDINGS metadata.", { cause: error });
+	}
+	assertPlainObject(parsed, "Invalid NOTION_ACCESS_BINDINGS metadata.");
+	const bindingKeys = Object.keys(parsed);
+	if (
+		Reflect.ownKeys(parsed).length !== bindingKeys.length ||
+		bindingKeys.length !== aliases.length ||
+		bindingKeys.some((alias) => !Object.hasOwn(expected, alias))
+	) {
+		throw new Error(
+			"Invalid NOTION_ACCESS_BINDINGS metadata: aliases do not match workflow access.",
+		);
+	}
+
+	const resolved: Record<string, WorkflowAccessValue> = Object.create(null) as Record<
+		string,
+		WorkflowAccessValue
+	>;
+	for (const alias of aliases) {
+		const requirement = expected[alias];
+		if (!requirement) {
+			throw new Error(`Workflow access "${alias}" is not declared.`);
+		}
+		const binding: unknown = parsed[alias];
+		if (!isBinding(binding)) {
+			throw new Error(`Invalid NOTION_ACCESS_BINDINGS metadata for access "${alias}".`);
+		}
+		if (
+			binding.type !== requirement.type ||
+			binding.resourceId !== requirement.resourceId ||
+			binding.level !== requirement.level
+		) {
+			throw new Error(
+				`Workflow access "${alias}" binding does not match its declared type, resourceId, or level.`,
+			);
+		}
+		resolved[alias] = Object.freeze({ type: binding.type, id: binding.id });
+	}
+
+	return Object.freeze(resolved);
+}
+
+function isWorkflowAccessResourceType(value: unknown): value is WorkflowAccessResourceType {
+	return typeof value === "string" && Object.hasOwn(RESOURCE_TYPES, value);
+}
+
+function isWorkflowAccessResourceLevel(value: unknown): value is WorkflowAccessResourceLevel {
+	return value === "view" || value === "comment" || value === "edit" || value === "fullAccess";
+}
+
+function isBinding(value: unknown): value is {
+	type: WorkflowAccessResourceType;
+	resourceId: string;
+	level: WorkflowAccessResourceLevel | WorkflowAccessAgentLevel;
+	id: string;
+} {
+	if (!isRecord(value) || Reflect.ownKeys(value).length !== 4) return false;
+	const keys = Object.keys(value);
+	if (
+		keys.length !== 4 ||
+		!keys.includes("type") ||
+		!keys.includes("resourceId") ||
+		!keys.includes("level") ||
+		!keys.includes("id")
+	) {
+		return false;
+	}
+	return (
+		isWorkflowAccessResourceType(value.type) &&
+		typeof value.resourceId === "string" &&
+		value.resourceId.length > 0 &&
+		typeof value.level === "string" &&
+		(isWorkflowAccessResourceLevel(value.level) || value.level === "call") &&
+		typeof value.id === "string" &&
+		value.id.length > 0
+	);
+}
+
+function assertPlainObject(
+	value: unknown,
+	message: string,
+): asserts value is Record<string, unknown> {
+	if (!isRecord(value)) throw new Error(message);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error(message);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/workflow.test.ts

@@ -8,6 +8,9 @@ import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Moc
 import { ExecutionError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
+import { customAgent } from "./notion-as-code/custom-agent.js";
+import { database } from "./notion-as-code/database.js";
+import { page } from "./notion-as-code/page.js";
 import {
 	connections,
 	workflow,
@@ -22,6 +25,7 @@ let metadataDirectory: string | undefined;
 
 beforeEach(async () => {
 	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+	delete process.env.NOTION_ACCESS_BINDINGS;
 	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
 	process.env.NOTION_WORKFLOW_CAPABILITY_KEY = "workflow-key";
 	checkpointDirectory = undefined;
@@ -31,6 +35,7 @@ beforeEach(async () => {
 
 afterEach(async () => {
 	stdoutSpy.mockRestore();
+	delete process.env.NOTION_ACCESS_BINDINGS;
 	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
 	delete process.env.NOTION_WORKFLOW_CAPABILITY_KEY;
 	delete process.env.NOTION_INPUT_PAYLOAD_PATH;
@@ -1190,6 +1195,113 @@ describe("workflow", () => {
 			),
 		);
 	});
+	it("normalizes NaC access and hydrates all supported resource kinds", async () => {
+		const home = page({ resourceId: "home" });
+		const table = database("table", {
+			dataSourceResourceId: "table-source",
+			name: "Table",
+			schema: { Title: { resourceId: "title", type: "title" } },
+		});
+		const agent = customAgent({ resourceId: "agent", name: "Agent" });
+		let resolvedAccess:
+			| {
+					readonly home: { readonly type: "page"; readonly id: string };
+					readonly table: { readonly type: "database"; readonly id: string };
+					readonly source: { readonly type: "dataSource"; readonly id: string };
+					readonly agent: { readonly type: "customAgent"; readonly id: string };
+			  }
+			| undefined;
+		const definition = workflow({
+			name: "Access",
+			description: "Hydrates access",
+			triggers: [triggers.notionPageCreated()],
+			access: {
+				home: { resource: home, level: "view" },
+				table: { resource: table, level: "edit" },
+				source: { resource: table.dataSource, level: "comment" },
+				agent: { resource: agent, level: "call" },
+			},
+			handler: (_event, context) => {
+				expectTypeOf(context.access.home.type).toEqualTypeOf<"page">();
+				expectTypeOf(context.access.table.type).toEqualTypeOf<"database">();
+				expectTypeOf(context.access.source.type).toEqualTypeOf<"dataSource">();
+				expectTypeOf(context.access.agent.type).toEqualTypeOf<"customAgent">();
+				resolvedAccess = context.access;
+			},
+		});
+
+		expect(definition.config.access).toEqual({
+			home: { type: "page", resourceId: "home", level: "view" },
+			table: { type: "database", resourceId: "table", level: "edit" },
+			source: { type: "dataSource", resourceId: "table-source", level: "comment" },
+			agent: { type: "customAgent", resourceId: "agent", level: "call" },
+		});
+		process.env.NOTION_ACCESS_BINDINGS = JSON.stringify({
+			home: { type: "page", resourceId: "home", level: "view", id: "page-id" },
+			table: { type: "database", resourceId: "table", level: "edit", id: "database-id" },
+			source: {
+				type: "dataSource",
+				resourceId: "table-source",
+				level: "comment",
+				id: "data-source-id",
+			},
+			agent: { type: "customAgent", resourceId: "agent", level: "call", id: "agent-id" },
+		});
+
+		await definition.handler(event, { concreteOutput: true });
+
+		expect(resolvedAccess).toEqual({
+			home: { type: "page", id: "page-id" },
+			table: { type: "database", id: "database-id" },
+			source: { type: "dataSource", id: "data-source-id" },
+			agent: { type: "customAgent", id: "agent-id" },
+		});
+		expect(Object.isFrozen(resolvedAccess)).toBe(true);
+		expect(Object.isFrozen(resolvedAccess?.home)).toBe(true);
+	});
+
+	it("rejects missing or mismatched access bindings before the handler", async () => {
+		const handler = vi.fn();
+		const definition = workflow({
+			name: "Access",
+			description: "Requires access",
+			triggers: [triggers.notionPageCreated()],
+			access: { home: { resource: page({ resourceId: "home" }), level: "view" } },
+			handler,
+		});
+
+		await expect(definition.handler(event, { concreteOutput: true })).rejects.toThrow(
+			"not bound",
+		);
+		expect(handler).not.toHaveBeenCalled();
+
+		process.env.NOTION_ACCESS_BINDINGS = JSON.stringify({
+			home: { type: "page", resourceId: "other", level: "view", id: "page-id" },
+		});
+		await expect(definition.handler(event, { concreteOutput: true })).rejects.toThrow(
+			"does not match",
+		);
+		expect(handler).not.toHaveBeenCalled();
+	});
+
+	it("does not parse unused access metadata when no access is declared", async () => {
+		process.env.NOTION_ACCESS_BINDINGS = "{malformed";
+		let contextAccess: unknown;
+		const definition = workflow({
+			name: "No Access",
+			description: "Runs without access",
+			triggers: [triggers.notionPageCreated()],
+			handler: (_event, context) => {
+				contextAccess = context.access;
+			},
+		});
+
+		await expect(definition.handler(event, { concreteOutput: true })).resolves.toEqual({
+			status: "success",
+		});
+		expect(contextAccess).toEqual({});
+		expect(Object.isFrozen(contextAccess)).toBe(true);
+	});
 });
 
 describe("connection-bound triggers", () => {

package/src/workflow.ts

@@ -6,6 +6,13 @@ import {
 	type WorkflowConnectionRequirement,
 	type WorkflowConnections,
 } from "./connections.js";
+import {
+	hydrateWorkflowAccess,
+	normalizeWorkflowAccess,
+	type WorkflowAccess,
+	type WorkflowAccessDeclarations,
+	type WorkflowAccessRequirements,
+} from "./workflow-access.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -69,6 +76,21 @@ type WorkflowHandlerResult = { status: "success" } | WorkflowWaitUntilResult;
 
 const MAX_WORKFLOW_WAIT_MS = 7 * 24 * 60 * 60 * 1_000;
 
+export type {
+	WorkflowAccess,
+	WorkflowAccessAgentLevel,
+	WorkflowAccessBindings,
+	WorkflowAccessDeclaration,
+	WorkflowAccessDeclarations,
+	WorkflowAccessLevel,
+	WorkflowAccessLevelFor,
+	WorkflowAccessResource,
+	WorkflowAccessResourceLevel,
+	WorkflowAccessResourceType,
+	WorkflowAccessRequirement,
+	WorkflowAccessRequirements,
+	WorkflowAccessValue,
+} from "./workflow-access.js";
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
@@ -92,6 +114,7 @@ export {
 export type WorkflowConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
 > = {
 	/**
 	 * A human-readable name for the workflow, shown in the UI when viewing workflows
@@ -110,6 +133,13 @@ export type WorkflowConfiguration<
 	 */
 	triggers: TTriggers;
 
+	/**
+	 * Notion-as-Code resources whose access is configured during cloud deployment.
+	 * Deployment reconciles grants through the existing Notion-module permissions
+	 * and supplies named runtime bindings on `context.access`.
+	 */
+	access?: TAccess;
+
 	/**
 	 * Connections that must be set up before this workflow can run.
 	 */
@@ -117,7 +147,7 @@ export type WorkflowConfiguration<
 
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
-		context: WorkflowContext<TConnections>,
+		context: WorkflowContext<TConnections, TAccess>,
 	) => Promise<void> | void;
 };
 
@@ -125,7 +155,8 @@ export type WorkflowConfiguration<
 export type WorkflowTriggerConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	TConnections extends WorkflowConnectionDeclarations,
-> = Omit<WorkflowConfiguration<TTriggers, TConnections>, "triggers"> & {
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
+> = Omit<WorkflowConfiguration<TTriggers, TConnections, TAccess>, "triggers"> & {
 	triggers: (context: { triggers: WorkflowTriggerCreators<NoInfer<TConnections>> }) => TTriggers;
 };
 
@@ -147,6 +178,7 @@ export type Workflow<
 		description: string;
 		triggers: TTriggers;
 		connections?: readonly WorkflowConnectionRequirement[];
+		access?: WorkflowAccessRequirements;
 	};
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
@@ -186,20 +218,26 @@ export function workflow<
 		...WorkflowTriggerForConnections<NoInfer<TConnections>>[],
 	],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
->(configuration: WorkflowTriggerConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
+>(
+	configuration: WorkflowTriggerConfiguration<TTriggers, TConnections, TAccess>,
+): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
->(configuration: WorkflowConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
+>(configuration: WorkflowConfiguration<TTriggers, TConnections, TAccess>): Workflow<TTriggers>;
 export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
 	const TConnections extends WorkflowConnectionDeclarations = Record<never, never>,
+	const TAccess extends WorkflowAccessDeclarations = Record<never, never>,
 >(
 	configuration:
-		| WorkflowConfiguration<TTriggers, TConnections>
-		| WorkflowTriggerConfiguration<TTriggers, TConnections>,
+		| WorkflowConfiguration<TTriggers, TConnections, TAccess>
+		| WorkflowTriggerConfiguration<TTriggers, TConnections, TAccess>,
 ): Workflow<TTriggers> {
 	const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
+	const accessRequirements = normalizeWorkflowAccess(configuration.access);
 	const connectionDeclarations =
 		configuration.connections === undefined
 			? undefined
@@ -217,6 +255,7 @@ export function workflow<
 			description: configuration.description,
 			triggers,
 			...(configuration.connections === undefined ? {} : { connections: requirements }),
+			...(configuration.access === undefined ? {} : { access: accessRequirements }),
 		},
 		async handler(
 			event: WorkflowEventForTriggers<TTriggers>,
@@ -227,8 +266,9 @@ export function workflow<
 				const runMetadata = readRunMetadata();
 				const baseContext = createCapabilityContext();
 				const step = createStep(runMetadata);
-				const capabilityContext: WorkflowContext<TConnections> = {
+				const capabilityContext: WorkflowContext<TConnections, TAccess> = {
 					...baseContext,
+					access: hydrateWorkflowAccess<TAccess>(accessRequirements),
 					connections: createWorkflowConnections(
 						baseContext.notion,
 						connectionDeclarations,
@@ -324,7 +364,10 @@ type WorkflowWait = {
 /** Context passed to a workflow handler. */
 export type WorkflowContext<
 	TConnections extends WorkflowConnectionDeclarations = WorkflowConnectionDeclarations,
+	TAccess extends WorkflowAccessDeclarations = WorkflowAccessDeclarations,
 > = CapabilityContext & {
+	/** Resolved NaC bindings for this invocation; UI-granted resources are not added here. */
+	readonly access: WorkflowAccess<TAccess>;
 	connections: WorkflowConnections<TConnections>;
 } & RunMetadata & {
 		/**