@flowdular/sdk 0.2.4 → 0.3.1

package/modules/connectors/src/services/egress.ts

@@ -0,0 +1,261 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+/*
+ * The address classification below, blockedIpv4, blockedAddress and
+ * normalizeHost, is byte-for-byte the block notifications.core delivers
+ * webhooks under, and so is the pinned lookup further down. The policy around
+ * them is this module's own and deliberately differs: a call-time assertHttps
+ * for a base URL a workspace saved before the rule, and an allowlist built from
+ * the instance's own host list rather than a comma separated environment value.
+ * The shared parts are the promotion candidate for packages/server; they stay
+ * copied until the platform owns one egress policy both modules call.
+ */
+
+export type ConnectorEgressErrorCode =
+	| 'CONNECTOR_URL_INVALID'
+	| 'CONNECTOR_URL_BLOCKED'
+	| 'CONNECTOR_HOST_NOT_ALLOWLISTED'
+	| 'CONNECTOR_HOST_UNRESOLVED'
+	| 'CONNECTOR_HOST_RESOLVES_PRIVATE';
+
+export class ConnectorEgressError extends Error {
+	constructor(
+		readonly code: ConnectorEgressErrorCode,
+		message: string,
+	) {
+		super(message);
+		this.name = 'ConnectorEgressError';
+	}
+}
+
+function blockedIpv4(value: string): boolean {
+	const parts = value.split('.').map(Number);
+	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) {
+		return true;
+	}
+	const [a, b] = parts as [number, number, number, number];
+	return (
+		a === 0 ||
+		a === 10 ||
+		a === 127 ||
+		(a === 169 && b === 254) ||
+		(a === 172 && b >= 16 && b <= 31) ||
+		(a === 192 && b === 168) ||
+		(a === 100 && b >= 64 && b <= 127) ||
+		a >= 224
+	);
+}
+
+/** True for loopback, link-local, private, multicast and reserved addresses. */
+export function blockedAddress(value: string): boolean {
+	if (isIP(value) === 4) return blockedIpv4(value);
+	if (isIP(value) !== 6) return true;
+	const normalized = value.toLowerCase();
+	if (normalized.startsWith('::ffff:')) {
+		const mapped = normalized.slice('::ffff:'.length);
+		return isIP(mapped) === 4 ? blockedIpv4(mapped) : true;
+	}
+	return (
+		normalized === '::' ||
+		normalized === '::1' ||
+		normalized.startsWith('fc') ||
+		normalized.startsWith('fd') ||
+		normalized.startsWith('fe8') ||
+		normalized.startsWith('fe9') ||
+		normalized.startsWith('fea') ||
+		normalized.startsWith('feb') ||
+		normalized.startsWith('ff')
+	);
+}
+
+export function connectorHostAllowlist(
+	hosts: readonly string[],
+): ReadonlySet<string> {
+	return new Set(
+		hosts.map((host) => host.trim().toLowerCase()).filter(Boolean),
+	);
+}
+
+/* URL.hostname keeps the brackets around an IPv6 literal, and isIP does not
+   accept them, so both checks would miss `https://[::1]/` without this. */
+export function normalizeHost(hostname: string): string {
+	const lowered = hostname.toLowerCase();
+	return lowered.startsWith('[') && lowered.endsWith(']')
+		? lowered.slice(1, -1)
+		: lowered;
+}
+
+export interface ResolvedAddress {
+	readonly address: string;
+}
+
+/**
+ * How a hostname becomes addresses. The default asks the system resolver; a
+ * test injects its own so a local server can be reached without an environment
+ * flag ever weakening the check in a deployment.
+ */
+export type HostAddressResolver = (
+	hostname: string,
+) => Promise<readonly ResolvedAddress[]>;
+
+export const systemHostResolver: HostAddressResolver = (hostname) =>
+	lookup(hostname, { all: true, verbatim: true });
+
+/* ---------------------------------------------------------------------------
+ * Pinned egress. This block is byte-for-byte identical in both modules that
+ * own this policy, connectors.core and notifications.core. Change both or
+ * neither: they run the same rule, and this block is the first piece to
+ * promote into packages/server once the platform owns one egress policy.
+ * ------------------------------------------------------------------------- */
+
+/** What `net.connect` asks before it opens a socket. */
+export type PinnedLookup = (
+	hostname: string,
+	options: { readonly all?: boolean | undefined },
+	callback: (
+		error: Error | null,
+		address: string | { address: string; family: number }[],
+		family?: number,
+	) => void,
+) => void;
+
+/**
+ * Answers only the addresses the policy already accepted for this host name.
+ * A connection opened through it cannot reach an address a second resolution
+ * would return, which is what closes the window between the check and the
+ * socket: a name answering publicly once and privately a moment later is no
+ * longer reachable. The host name is untouched, so the Host header, the TLS
+ * server name and certificate verification stay exactly as they were.
+ */
+export function pinnedLookup(
+	hostname: string,
+	addresses: readonly ResolvedAddress[],
+): PinnedLookup {
+	const expected = normalizeHost(hostname);
+	const pinned = addresses.map((entry) => ({
+		address: entry.address,
+		family: isIP(entry.address),
+	}));
+	return (asked, options, callback) => {
+		const first = pinned[0];
+		if (!first || normalizeHost(asked) !== expected) {
+			callback(new Error(`No verified address is pinned for ${asked}.`), '', 0);
+			return;
+		}
+		if (options.all === true) {
+			callback(null, pinned);
+			return;
+		}
+		callback(null, first.address, first.family);
+	};
+}
+
+/* ------------------------- end of the shared block ----------------------- */
+
+export interface ConnectorEgressPolicy {
+	readonly allowlist: ReadonlySet<string>;
+	/** Save-time check: scheme, shape and allowlist. Throws on refusal. */
+	assertUrl(value: string): URL;
+	/**
+	 * Call-time scheme check. The save-time rule already refused anything but
+	 * https, so this catches a row written before that rule and a caller that
+	 * reached the call path without one.
+	 */
+	assertHttps(url: URL): void;
+	/**
+	 * Resolution check, repeated before every call. Throws on refusal, and
+	 * answers the addresses it accepted so the connection can be pinned to
+	 * exactly them.
+	 */
+	assertResolvable(hostname: string): Promise<readonly ResolvedAddress[]>;
+}
+
+export interface ConnectorEgressPolicyOptions {
+	readonly allowlist?: ReadonlySet<string> | undefined;
+	readonly resolve?: HostAddressResolver | undefined;
+}
+
+export function createConnectorEgressPolicy(
+	options: ConnectorEgressPolicyOptions = {},
+): ConnectorEgressPolicy {
+	const allowlist = options.allowlist ?? new Set<string>();
+	const resolve = options.resolve ?? systemHostResolver;
+	return {
+		allowlist,
+		assertUrl(value) {
+			let url: URL;
+			try {
+				url = new URL(value);
+			} catch {
+				throw new ConnectorEgressError(
+					'CONNECTOR_URL_INVALID',
+					'The connector base URL is not a valid absolute URL.',
+				);
+			}
+			const hostname = normalizeHost(url.hostname);
+			if (
+				url.protocol !== 'https:' ||
+				url.username ||
+				url.password ||
+				!hostname ||
+				hostname === 'localhost' ||
+				hostname.endsWith('.local') ||
+				hostname.endsWith('.localhost') ||
+				isIP(hostname) !== 0
+			) {
+				throw new ConnectorEgressError(
+					'CONNECTOR_URL_BLOCKED',
+					'A connector base URL must be an https URL to a public host name.',
+				);
+			}
+			if (allowlist.size > 0 && !allowlist.has(hostname)) {
+				throw new ConnectorEgressError(
+					'CONNECTOR_HOST_NOT_ALLOWLISTED',
+					`Host ${hostname} is not on the connector host allowlist.`,
+				);
+			}
+			return url;
+		},
+		assertHttps(url) {
+			if (url.protocol !== 'https:') {
+				throw new ConnectorEgressError(
+					'CONNECTOR_URL_BLOCKED',
+					'A connector call must be an https request.',
+				);
+			}
+		},
+		async assertResolvable(hostname) {
+			const normalized = normalizeHost(hostname);
+			if (allowlist.size > 0 && !allowlist.has(normalized)) {
+				throw new ConnectorEgressError(
+					'CONNECTOR_HOST_NOT_ALLOWLISTED',
+					`Host ${normalized} is not on the connector host allowlist.`,
+				);
+			}
+			let addresses: readonly ResolvedAddress[];
+			try {
+				addresses = await resolve(normalized);
+			} catch {
+				/* A name that no longer resolves is a different operational fact from
+				   one that resolves into a blocked range; the call log keeps them apart. */
+				throw new ConnectorEgressError(
+					'CONNECTOR_HOST_UNRESOLVED',
+					`Host ${normalized} could not be resolved.`,
+				);
+			}
+			/* Every returned address is checked, not just the first: a host that
+			   answers with one public and one loopback address is still refused. */
+			if (
+				addresses.length === 0 ||
+				addresses.some((entry) => blockedAddress(entry.address))
+			) {
+				throw new ConnectorEgressError(
+					'CONNECTOR_HOST_RESOLVES_PRIVATE',
+					`Host ${normalized} resolves to a blocked network address.`,
+				);
+			}
+			return addresses;
+		},
+	};
+}

package/modules/connectors/src/services/index.ts

@@ -0,0 +1,19 @@
+export { ConnectorsService } from './connectors-service.ts';
+export type { ConnectorsServiceOptions } from './connectors-service.ts';
+export { ConnectorCallService } from './call-service.ts';
+export type {
+	ConnectorCallLimits,
+	ConnectorCallServiceOptions,
+} from './call-service.ts';
+export { ConnectorsServiceError } from './service-error.ts';
+export {
+	DuplicateConnectorNameError,
+	type ConnectorCallFilters,
+	type ConnectorsRepository,
+	type PendingConnectorAuditEvent,
+	type StoredConnectorInstance,
+} from './repository.ts';
+export {
+	DatabaseConnectorsRepository,
+	migrateConnectorsDatabase,
+} from './database-repository.ts';

package/modules/connectors/src/services/migration.ts

@@ -0,0 +1,202 @@
+import type {
+	DatabaseMigration,
+	ExistingMigrationState,
+} from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/* Mirrors migrations/0001_connectors_core.up.sql byte for byte. */
+export const CONNECTORS_MIGRATION_001 = `CREATE TABLE IF NOT EXISTS connectors_instances (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  definition_key TEXT NOT NULL,
+  name TEXT NOT NULL,
+  name_normalized TEXT NOT NULL,
+  base_url TEXT NOT NULL,
+  auth_kind TEXT NOT NULL CHECK (auth_kind IN ('none', 'api-key', 'bearer', 'oauth2-client-credentials')),
+  credential_key_id TEXT,
+  credential_iv TEXT,
+  credential_tag TEXT,
+  credential_ciphertext TEXT,
+  credential_fingerprint TEXT,
+  allowed_hosts_json TEXT NOT NULL,
+  allow_workflows SMALLINT NOT NULL DEFAULT 0 CHECK (allow_workflows IN (0, 1)),
+  allow_agents SMALLINT NOT NULL DEFAULT 0 CHECK (allow_agents IN (0, 1)),
+  status TEXT NOT NULL CHECK (status IN ('active', 'disabled')),
+  last_call_at BIGINT,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS connectors_instances_name_normalized_idx
+  ON connectors_instances (tenant_id, name_normalized);
+CREATE INDEX IF NOT EXISTS connectors_instances_tenant_status_idx
+  ON connectors_instances (tenant_id, status, name_normalized);
+ALTER TABLE connectors_instances ENABLE ROW LEVEL SECURITY;
+ALTER TABLE connectors_instances FORCE ROW LEVEL SECURITY;
+CREATE POLICY connectors_instances_tenant_policy ON connectors_instances
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS connectors_calls (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  instance_id TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  caller TEXT NOT NULL CHECK (caller IN ('test', 'workflow', 'agent')),
+  caller_ref TEXT,
+  outcome TEXT NOT NULL CHECK (outcome IN ('succeeded', 'failed', 'refused')),
+  status INTEGER,
+  error_class TEXT,
+  duration_ms INTEGER NOT NULL,
+  request_bytes INTEGER NOT NULL,
+  response_bytes INTEGER NOT NULL,
+  occurred_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS connectors_calls_tenant_time_idx
+  ON connectors_calls (tenant_id, occurred_at DESC, id DESC);
+CREATE INDEX IF NOT EXISTS connectors_calls_instance_idx
+  ON connectors_calls (tenant_id, instance_id, occurred_at DESC);
+ALTER TABLE connectors_calls ENABLE ROW LEVEL SECURITY;
+ALTER TABLE connectors_calls FORCE ROW LEVEL SECURITY;
+CREATE POLICY connectors_calls_tenant_policy ON connectors_calls
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS connectors_audit (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL CHECK (action IN ('instance.created', 'instance.updated', 'instance.consent-changed', 'instance.enabled', 'instance.disabled', 'instance.deleted')),
+  instance_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS connectors_audit_tenant_time_idx
+  ON connectors_audit (tenant_id, occurred_at DESC, id DESC);
+ALTER TABLE connectors_audit ENABLE ROW LEVEL SECURITY;
+ALTER TABLE connectors_audit FORCE ROW LEVEL SECURITY;
+CREATE POLICY connectors_audit_tenant_policy ON connectors_audit
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+/* Mirrors migrations/0002_connectors_call_keys.up.sql byte for byte. */
+export const CONNECTORS_MIGRATION_002 = `CREATE TABLE IF NOT EXISTS connectors_call_keys (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL CHECK (length(idempotency_key) BETWEEN 8 AND 128),
+  operation_id TEXT NOT NULL CHECK (length(operation_id) BETWEEN 3 AND 200),
+  input_digest TEXT NOT NULL CHECK (length(input_digest) = 64),
+  call_id TEXT,
+  claimed_at BIGINT NOT NULL,
+  completed_at BIGINT,
+  UNIQUE (tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS connectors_call_keys_tenant_claimed_idx
+  ON connectors_call_keys (tenant_id, claimed_at, id);
+ALTER TABLE connectors_call_keys ENABLE ROW LEVEL SECURITY;
+ALTER TABLE connectors_call_keys FORCE ROW LEVEL SECURITY;
+CREATE POLICY connectors_call_keys_tenant_policy ON connectors_call_keys
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+/** Every tenant table of one migration must be adopted, or none of it is. */
+async function combined(
+	states: readonly Promise<ExistingMigrationState>[],
+): Promise<ExistingMigrationState> {
+	const resolved: ExistingMigrationState[] = [];
+	for (const state of states) resolved.push(await state);
+	if (resolved.every((state) => state === 'complete')) return 'complete';
+	if (resolved.every((state) => state === 'absent')) return 'absent';
+	return 'partial';
+}
+
+/* Mirrors migrations/0003_connectors_rotation_inventory.up.sql byte for byte. */
+export const CONNECTORS_MIGRATION_003 = `-- The credential key rotation has to find the instances still sealed with a
+-- retired key before it knows whose they are, so the cross-tenant role may read
+-- the key id of every row that holds an envelope and nothing else: the nonce,
+-- the tag, the ciphertext and the fingerprint stay unreadable on this
+-- connection, and every row it re-seals is read again under the workspace that
+-- row named. PostgreSQL checks column privileges in WHERE too, so the key id is
+-- part of the grant.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coreloom_background') THEN
+    RAISE EXCEPTION 'The coreloom_background role must exist before this migration.';
+  END IF;
+END
+$$;
+CREATE POLICY connectors_instances_background_policy ON connectors_instances
+  FOR SELECT TO coreloom_background
+  USING (credential_key_id IS NOT NULL);
+REVOKE SELECT ON connectors_instances FROM coreloom_background;
+GRANT SELECT (tenant_id, credential_key_id) ON connectors_instances TO coreloom_background;
+`;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_connectors_core',
+		sql: { postgresql: CONNECTORS_MIGRATION_001 },
+		inspectExisting: (database) =>
+			combined([
+				postgresTenantTableState(
+					database,
+					'connectors_instances',
+					'connectors_instances_tenant_policy',
+					[
+						() =>
+							database.schema.hasIndex(
+								'connectors_instances_name_normalized_idx',
+							),
+						() =>
+							database.schema.hasIndex(
+								'connectors_instances_tenant_status_idx',
+							),
+					],
+				),
+				postgresTenantTableState(
+					database,
+					'connectors_calls',
+					'connectors_calls_tenant_policy',
+					[
+						() => database.schema.hasIndex('connectors_calls_tenant_time_idx'),
+						() => database.schema.hasIndex('connectors_calls_instance_idx'),
+					],
+				),
+				postgresTenantTableState(
+					database,
+					'connectors_audit',
+					'connectors_audit_tenant_policy',
+					[() => database.schema.hasIndex('connectors_audit_tenant_time_idx')],
+				),
+			]),
+	},
+	{
+		id: '0002_connectors_call_keys',
+		sql: { postgresql: CONNECTORS_MIGRATION_002 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'connectors_call_keys',
+				'connectors_call_keys_tenant_policy',
+				[
+					() =>
+						database.schema.hasIndex('connectors_call_keys_tenant_claimed_idx'),
+				],
+			),
+	},
+	{
+		id: '0003_connectors_rotation_inventory',
+		sql: { postgresql: CONNECTORS_MIGRATION_003 },
+		/* A policy and a column grant leave no schema object behind, so the
+		   privilege itself is what proves this migration ran. */
+		inspectExisting: async (database) => {
+			const result = await database.query<{ granted: boolean }>({
+				text: `SELECT CASE WHEN to_regclass('connectors_instances') IS NOT NULL THEN
+				  has_column_privilege('coreloom_background', 'connectors_instances', 'credential_key_id', 'SELECT')
+				ELSE false END AS granted`,
+			});
+			return result.rows[0]?.granted === true ? 'complete' : 'absent';
+		},
+	},
+];

package/modules/connectors/src/services/repository.ts

@@ -0,0 +1,175 @@
+import type {
+	ConnectorAuditEvent,
+	ConnectorCall,
+	ConnectorCallListRow,
+	ConnectorCallOutcome,
+	ConnectorInstance,
+	ConnectorInstanceStatus,
+} from '../domain/types.ts';
+import type { SealedCredential } from './credential-vault.ts';
+
+export class DuplicateConnectorNameError extends Error {
+	constructor() {
+		super('A connector instance with this name already exists in the tenant.');
+		this.name = 'DuplicateConnectorNameError';
+	}
+}
+
+/** The instance plus the sealed credential. Only the call path reads this. */
+export interface StoredConnectorInstance extends ConnectorInstance {
+	readonly credential: SealedCredential | null;
+}
+
+export interface ConnectorCallFilters {
+	readonly outcome?: ConnectorCallOutcome | undefined;
+	readonly instanceId?: string | undefined;
+	/** A term the operation must contain, case-insensitive. */
+	readonly search?: string | undefined;
+}
+
+export interface ConnectorInstanceFilters {
+	readonly status?: ConnectorInstanceStatus | undefined;
+	readonly definitionKey?: string | undefined;
+	/** A term the name or the base URL must contain, case-insensitive. */
+	readonly search?: string | undefined;
+}
+
+export type ConnectorListDirection = 'asc' | 'desc';
+
+/** The keyset the instance list orders by: the normalized name, then the id. */
+export interface ConnectorInstanceKeyset {
+	readonly name: string;
+	readonly id: string;
+}
+
+/** One keyset page of a list screen; `after` is the last row the caller saw. */
+export interface ConnectorPageRequest<Keyset> {
+	readonly direction: ConnectorListDirection;
+	readonly after: Keyset | null;
+	readonly limit: number;
+}
+
+/** Written in the same transaction as the change it describes. */
+export type PendingConnectorAuditEvent = Omit<ConnectorAuditEvent, 'id'>;
+
+/** What one attempt wants to bind an idempotency key to. */
+export interface ConnectorCallKeyClaim {
+	/** `<instanceId>:<operation>`; a key is never reused across operations. */
+	readonly operationId: string;
+	readonly inputDigest: string;
+	readonly claimedAt: number;
+	/** A claim older than this was abandoned and may be taken over. */
+	readonly staleBefore: number;
+}
+
+/**
+ * `claimed` means this attempt owns the key and must make the call; `replay`
+ * names the call a previous attempt already produced; `in-flight` means another
+ * attempt still holds the claim; `conflict` means the key is bound to a
+ * different operation or input.
+ */
+export type ConnectorCallKeyDecision =
+	| { readonly state: 'claimed' }
+	| { readonly state: 'in-flight' }
+	| { readonly state: 'conflict' }
+	| { readonly state: 'replay'; readonly callId: string };
+
+/** One keyset page of an export walk. */
+export interface ConnectorExportCursor {
+	readonly occurredAt: number;
+	readonly id: string;
+}
+
+/** The database-agnostic business port. No driver type crosses it. */
+export interface ConnectorsRepository {
+	listInstances(
+		tenantId: string,
+		filters: ConnectorInstanceFilters,
+		page: ConnectorPageRequest<ConnectorInstanceKeyset>,
+	): Promise<readonly ConnectorInstance[]>;
+	findInstance(
+		tenantId: string,
+		id: string,
+	): Promise<StoredConnectorInstance | null>;
+	createInstance(
+		record: StoredConnectorInstance,
+		audit: PendingConnectorAuditEvent,
+	): Promise<ConnectorInstance>;
+	updateInstance(
+		record: StoredConnectorInstance,
+		audit: PendingConnectorAuditEvent,
+	): Promise<ConnectorInstance>;
+	setConsent(
+		tenantId: string,
+		id: string,
+		consent: {
+			readonly allowWorkflows: boolean;
+			readonly allowAgents: boolean;
+			readonly updatedAt: number;
+		},
+		audit: PendingConnectorAuditEvent,
+	): Promise<ConnectorInstance | null>;
+	setStatus(
+		tenantId: string,
+		id: string,
+		status: ConnectorInstanceStatus,
+		updatedAt: number,
+		audit: PendingConnectorAuditEvent,
+	): Promise<ConnectorInstance | null>;
+	/** Refuses an instance that is not disabled; the call log is left behind. */
+	deleteInstance(
+		tenantId: string,
+		id: string,
+		audit: PendingConnectorAuditEvent,
+	): Promise<boolean>;
+	/**
+	 * Binds an idempotency key to this workspace before the call is made. The
+	 * caller makes the call only for `claimed`.
+	 */
+	claimCallKey(
+		tenantId: string,
+		key: string,
+		claim: ConnectorCallKeyClaim,
+	): Promise<ConnectorCallKeyDecision>;
+	findCall(tenantId: string, id: string): Promise<ConnectorCall | null>;
+	/**
+	 * Appends the call, moves the instance's last call time and binds the
+	 * claimed idempotency key to it, in one write.
+	 */
+	recordCall(call: ConnectorCall, idempotencyKey: string | null): Promise<void>;
+	/**
+	 * Removes at most `limit` calls older than `before`, together with the
+	 * idempotency keys claimed before it. A key is always claimed no later than
+	 * its call, so this never leaves a key pointing at a call that is gone.
+	 */
+	deleteCallsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	exportCallsPage(
+		tenantId: string,
+		after: ConnectorExportCursor | null,
+		limit: number,
+	): Promise<readonly ConnectorCall[]>;
+	exportAuditPage(
+		tenantId: string,
+		after: ConnectorExportCursor | null,
+		limit: number,
+	): Promise<readonly ConnectorAuditEvent[]>;
+	exportInstancesPage(
+		tenantId: string,
+		after: ConnectorExportCursor | null,
+		limit: number,
+	): Promise<readonly ConnectorInstance[]>;
+	listCalls(
+		tenantId: string,
+		filters: ConnectorCallFilters,
+		page: ConnectorPageRequest<ConnectorExportCursor>,
+	): Promise<readonly ConnectorCallListRow[]>;
+	listAudit(
+		tenantId: string,
+		instanceId: string,
+		limit: number,
+	): Promise<readonly ConnectorAuditEvent[]>;
+}

package/modules/connectors/src/services/service-error.ts

@@ -0,0 +1,46 @@
+export class ConnectorsServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'ConnectorsServiceError';
+	}
+}
+
+export function bounded(
+	value: string,
+	field: string,
+	minimum: number,
+	maximum: number,
+): string {
+	const normalized = value.trim();
+	if (normalized.length < minimum || normalized.length > maximum) {
+		throw new ConnectorsServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${minimum} and ${maximum} characters.`,
+		);
+	}
+	if (/[\u0000-\u001f\u007f]/.test(normalized)) {
+		throw new ConnectorsServiceError(
+			'INVALID_INPUT',
+			`${field} contains an unsupported character.`,
+		);
+	}
+	return normalized;
+}
+
+export function oneOf<T extends string>(
+	value: string,
+	field: string,
+	allowed: readonly T[],
+): T {
+	if (!(allowed as readonly string[]).includes(value)) {
+		throw new ConnectorsServiceError(
+			'INVALID_INPUT',
+			`${field} must be one of: ${allowed.join(', ')}.`,
+		);
+	}
+	return value as T;
+}