@apifuse/connector-sdk 2.0.0-beta.1

package/src/runtime/session.ts

@@ -0,0 +1,573 @@
+import { Database } from "bun:sqlite";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { SessionStore } from "../types";
+
+const DEFAULT_NAMESPACE = "default";
+const SQLITE_MEMORY_PATH = ":memory:";
+const SQLITE_TABLE_SQL = `
+	CREATE TABLE IF NOT EXISTS connector_sessions (
+		key TEXT PRIMARY KEY,
+		value TEXT NOT NULL,
+		expires_at INTEGER
+	)
+`;
+
+const TTL_UNITS = {
+	ms: 1,
+	s: 1_000,
+	m: 60_000,
+	h: 3_600_000,
+	d: 86_400_000,
+} as const;
+
+export type SessionStoreBackend = "sqlite" | "supabase";
+
+export type SessionStoreOptions = {
+	backend?: SessionStoreBackend;
+	connectionId?: string;
+	databasePath?: string;
+	dbPath?: string;
+	encryptionKey?: string;
+	fetch?: SessionFetch;
+	namespace?: string;
+	supabaseKey?: string;
+	supabaseUrl?: string;
+};
+
+type InternalSessionStoreOptions = SessionStoreOptions & {
+	databasePath?: string;
+};
+
+type SessionEnvelope = {
+	v: 1;
+	data: Record<string, string>;
+	version: number;
+};
+
+type SupabaseSessionRecord = {
+	encrypted_blob: string;
+	encryption_key_version: number;
+	iv: string;
+	tag: string;
+};
+
+export type SessionFetch = (
+	input: string | URL | Request,
+	init?: RequestInit,
+) => Promise<Response>;
+
+export type SupabaseSessionStoreConfig = {
+	connectionId: string;
+	encryptionKey: string;
+	fetch?: SessionFetch;
+	supabaseKey: string;
+	supabaseUrl: string;
+};
+
+type SessionRow = {
+	value: string;
+	expires_at: number | null;
+};
+
+export type SqliteSessionInspection = {
+	storedKey: string;
+	value: string;
+	expiresAt: number | null;
+};
+
+export type SqliteSessionStore = SessionStore & {
+	__unsafeInspect(key: string): SqliteSessionInspection | null;
+};
+
+const SUPABASE_SESSION_VERSION = 1;
+const SUPABASE_IV_LENGTH = 12;
+const SUPABASE_KEY_LENGTH = 32;
+const SUPABASE_TABLE = "connection_secrets";
+
+function createSupabaseHeaders(apiKey: string): Headers {
+	return new Headers({
+		Accept: "application/json",
+		Authorization: `Bearer ${apiKey}`,
+		apikey: apiKey,
+	});
+}
+
+function createSessionEnvelope(data: Record<string, string>): SessionEnvelope {
+	return {
+		v: SUPABASE_SESSION_VERSION,
+		data,
+		version: 0,
+	};
+}
+
+function decodeEncryptionKey(encryptionKey: string): Buffer {
+	const trimmedKey = encryptionKey.trim();
+	const utf8Key = Buffer.from(trimmedKey, "utf8");
+	if (utf8Key.byteLength === SUPABASE_KEY_LENGTH) {
+		return utf8Key;
+	}
+
+	if (/^[0-9a-f]{64}$/i.test(trimmedKey)) {
+		return Buffer.from(trimmedKey, "hex");
+	}
+
+	const base64Key = Buffer.from(trimmedKey, "base64");
+	if (base64Key.byteLength === SUPABASE_KEY_LENGTH) {
+		return base64Key;
+	}
+
+	throw new TypeError(
+		"Supabase session encryption key must decode to exactly 32 bytes.",
+	);
+}
+
+function encryptSessionEnvelope(
+	encryptionKey: Buffer,
+	envelope: SessionEnvelope,
+): SupabaseSessionRecord {
+	const iv = randomBytes(SUPABASE_IV_LENGTH);
+	const cipher = createCipheriv("aes-256-gcm", encryptionKey, iv);
+	const encrypted = Buffer.concat([
+		cipher.update(JSON.stringify(envelope), "utf8"),
+		cipher.final(),
+	]);
+
+	return {
+		encrypted_blob: encrypted.toString("base64"),
+		encryption_key_version: SUPABASE_SESSION_VERSION,
+		iv: iv.toString("base64"),
+		tag: cipher.getAuthTag().toString("base64"),
+	};
+}
+
+function decryptSessionEnvelope(
+	encryptionKey: Buffer,
+	record: SupabaseSessionRecord,
+): SessionEnvelope {
+	if (record.encryption_key_version !== SUPABASE_SESSION_VERSION) {
+		throw new Error(
+			`Unsupported session encryption key version: ${record.encryption_key_version}`,
+		);
+	}
+
+	const iv = Buffer.from(record.iv, "base64");
+	if (iv.byteLength !== SUPABASE_IV_LENGTH) {
+		throw new Error("Invalid AES-GCM IV length.");
+	}
+
+	const tag = Buffer.from(record.tag, "base64");
+	if (tag.byteLength !== 16) {
+		throw new Error("Invalid AES-GCM authentication tag length.");
+	}
+
+	const decipher = createDecipheriv("aes-256-gcm", encryptionKey, iv);
+	decipher.setAuthTag(tag);
+	const decrypted = Buffer.concat([
+		decipher.update(Buffer.from(record.encrypted_blob, "base64")),
+		decipher.final(),
+	]);
+	const parsed = JSON.parse(
+		decrypted.toString("utf8"),
+	) as Partial<SessionEnvelope>;
+
+	if (parsed.v !== SUPABASE_SESSION_VERSION) {
+		throw new Error("Invalid session payload version.");
+	}
+
+	if (
+		typeof parsed.data !== "object" ||
+		parsed.data === null ||
+		Array.isArray(parsed.data)
+	) {
+		throw new Error("Invalid session payload data.");
+	}
+
+	return {
+		v: SUPABASE_SESSION_VERSION,
+		data: parsed.data,
+		version:
+			typeof parsed.version === "number" && Number.isInteger(parsed.version)
+				? parsed.version
+				: 0,
+	};
+}
+
+async function readSupabaseJson<T>(response: Response): Promise<T> {
+	const responseText = await response.text();
+	if (!response.ok) {
+		throw new Error(
+			`Supabase session request failed (${response.status}): ${responseText || response.statusText}`,
+		);
+	}
+
+	if (!responseText) {
+		return [] as T;
+	}
+
+	return JSON.parse(responseText) as T;
+}
+
+async function selectSecretRecord(
+	fetchImpl: SessionFetch,
+	supabaseUrl: string,
+	headers: Headers,
+	connectionId: string,
+): Promise<SupabaseSessionRecord | null> {
+	const query = new URLSearchParams({
+		connection_id: `eq.${connectionId}`,
+		select: "encrypted_blob,encryption_key_version,iv,tag",
+	});
+	const response = await fetchImpl(
+		`${supabaseUrl}/rest/v1/${SUPABASE_TABLE}?${query.toString()}`,
+		{
+			headers,
+			method: "GET",
+		},
+	);
+	const rows = await readSupabaseJson<SupabaseSessionRecord[]>(response);
+	return rows[0] ?? null;
+}
+
+async function upsertSecretRecord(
+	fetchImpl: SessionFetch,
+	supabaseUrl: string,
+	headers: Headers,
+	connectionId: string,
+	record: SupabaseSessionRecord,
+): Promise<void> {
+	const response = await fetchImpl(
+		`${supabaseUrl}/rest/v1/${SUPABASE_TABLE}?on_conflict=connection_id`,
+		{
+			body: JSON.stringify([
+				{
+					connection_id: connectionId,
+					...record,
+				},
+			]),
+			headers,
+			method: "POST",
+		},
+	);
+	await readSupabaseJson<unknown>(response);
+}
+
+async function deleteSecretRecord(
+	fetchImpl: SessionFetch,
+	supabaseUrl: string,
+	headers: Headers,
+	connectionId: string,
+): Promise<void> {
+	const query = new URLSearchParams({
+		connection_id: `eq.${connectionId}`,
+	});
+	const response = await fetchImpl(
+		`${supabaseUrl}/rest/v1/${SUPABASE_TABLE}?${query.toString()}`,
+		{
+			headers,
+			method: "DELETE",
+		},
+	);
+	await readSupabaseJson<unknown>(response);
+}
+
+export class SupabaseSessionStore implements SessionStore {
+	private readonly encryptionKey: Buffer;
+
+	private cachedEnvelope: SessionEnvelope | null = null;
+
+	private readonly fetchImpl: SessionFetch;
+
+	private readonly readHeaders: Headers;
+
+	private readonly mutationHeaders: Headers;
+
+	private readonly deleteHeaders: Headers;
+
+	private readonly supabaseUrl: string;
+
+	constructor(private readonly config: SupabaseSessionStoreConfig) {
+		this.encryptionKey = decodeEncryptionKey(config.encryptionKey);
+		this.fetchImpl = config.fetch ?? fetch;
+		this.readHeaders = createSupabaseHeaders(config.supabaseKey);
+		this.mutationHeaders = createSupabaseHeaders(config.supabaseKey);
+		this.mutationHeaders.set("Content-Type", "application/json");
+		this.mutationHeaders.set(
+			"Prefer",
+			"resolution=merge-duplicates,return=minimal",
+		);
+		this.deleteHeaders = createSupabaseHeaders(config.supabaseKey);
+		this.deleteHeaders.set("Prefer", "return=minimal");
+		this.supabaseUrl = config.supabaseUrl.replace(/\/$/, "");
+	}
+
+	async get(key: string): Promise<string | null> {
+		const envelope = await this.loadEnvelopeCached();
+		return envelope.data[key] ?? null;
+	}
+
+	async set(key: string, value: string): Promise<void> {
+		const envelope = await this.loadEnvelopeCached();
+		const nextEnvelope: SessionEnvelope = {
+			...envelope,
+			data: {
+				...envelope.data,
+				[key]: value,
+			},
+			version: envelope.version + 1,
+		};
+
+		await this.persistEnvelope(nextEnvelope, envelope.version);
+	}
+
+	async delete(key: string): Promise<void> {
+		const envelope = await this.loadEnvelopeCached();
+		if (!(key in envelope.data)) {
+			return;
+		}
+
+		const nextData = { ...envelope.data };
+		delete nextData[key];
+
+		if (Object.keys(nextData).length === 0) {
+			await deleteSecretRecord(
+				this.fetchImpl,
+				this.supabaseUrl,
+				this.deleteHeaders,
+				this.config.connectionId,
+			);
+			this.cachedEnvelope = null;
+			return;
+		}
+
+		await this.persistEnvelope(
+			{
+				...envelope,
+				data: nextData,
+				version: envelope.version + 1,
+			},
+			envelope.version,
+		);
+	}
+
+	async loadAll(): Promise<Record<string, string>> {
+		const envelope = await this.loadEnvelopeCached();
+		return { ...envelope.data };
+	}
+
+	private async loadEnvelope(): Promise<SessionEnvelope> {
+		const record = await selectSecretRecord(
+			this.fetchImpl,
+			this.supabaseUrl,
+			this.readHeaders,
+			this.config.connectionId,
+		);
+		if (!record) {
+			return createSessionEnvelope({});
+		}
+
+		return decryptSessionEnvelope(this.encryptionKey, record);
+	}
+
+	private async loadEnvelopeCached(): Promise<SessionEnvelope> {
+		if (this.cachedEnvelope) {
+			return this.cachedEnvelope;
+		}
+
+		this.cachedEnvelope = await this.loadEnvelope();
+		return this.cachedEnvelope;
+	}
+
+	private async persistEnvelope(
+		envelope: SessionEnvelope,
+		expectedPreviousVersion: number,
+	): Promise<void> {
+		const latestRecord = await selectSecretRecord(
+			this.fetchImpl,
+			this.supabaseUrl,
+			this.readHeaders,
+			this.config.connectionId,
+		);
+		const latestVersion = latestRecord
+			? decryptSessionEnvelope(this.encryptionKey, latestRecord).version
+			: 0;
+
+		if (latestVersion !== expectedPreviousVersion) {
+			console.warn(
+				`SupabaseSessionStore version mismatch for connection ${this.config.connectionId}: expected ${expectedPreviousVersion}, got ${latestVersion}`,
+			);
+		}
+
+		await upsertSecretRecord(
+			this.fetchImpl,
+			this.supabaseUrl,
+			this.mutationHeaders,
+			this.config.connectionId,
+			encryptSessionEnvelope(this.encryptionKey, envelope),
+		);
+
+		this.cachedEnvelope = envelope;
+	}
+}
+
+function resolveDatabasePath(options?: InternalSessionStoreOptions): string {
+	if (options?.dbPath) {
+		return options.dbPath;
+	}
+
+	if (options?.databasePath) {
+		return options.databasePath;
+	}
+
+	return join(process.cwd(), ".apifuse", "sessions.db");
+}
+
+function ensureDatabaseDirectory(databasePath: string): void {
+	if (databasePath === SQLITE_MEMORY_PATH) {
+		return;
+	}
+
+	mkdirSync(dirname(databasePath), { recursive: true });
+}
+
+function toStorageKey(namespace: string | undefined, key: string): string {
+	return `${namespace ?? DEFAULT_NAMESPACE}:${key}`;
+}
+
+export function parseSessionTtl(ttl?: string): number | null {
+	if (!ttl) {
+		return null;
+	}
+
+	const match = ttl.trim().match(/^(-?\d+)(ms|s|m|h|d)$/);
+	if (!match) {
+		throw new TypeError(`Invalid session ttl: ${ttl}`);
+	}
+
+	const [, rawValue, unit] = match;
+	return Number(rawValue) * TTL_UNITS[unit as keyof typeof TTL_UNITS];
+}
+
+function resolveExpiresAt(ttl?: string): number | null {
+	const ttlMs = parseSessionTtl(ttl);
+	if (ttlMs === null) {
+		return null;
+	}
+
+	return Date.now() + ttlMs;
+}
+
+export function resolveBackend(
+	options?: SessionStoreOptions,
+): SessionStoreBackend {
+	if (options?.backend) {
+		return options.backend;
+	}
+
+	return process.env.SUPABASE_URL ? "supabase" : "sqlite";
+}
+
+export function createSqliteSessionStore(
+	options?: InternalSessionStoreOptions,
+): SqliteSessionStore {
+	const databasePath = resolveDatabasePath(options);
+	ensureDatabaseDirectory(databasePath);
+
+	const database = new Database(databasePath, { create: true });
+	database.exec(SQLITE_TABLE_SQL);
+
+	const selectQuery = database.query(
+		"SELECT value, expires_at FROM connector_sessions WHERE key = ?",
+	);
+	const upsertQuery = database.query(
+		"INSERT OR REPLACE INTO connector_sessions (key, value, expires_at) VALUES (?, ?, ?)",
+	);
+	const deleteQuery = database.query(
+		"DELETE FROM connector_sessions WHERE key = ?",
+	);
+
+	function inspectRecord(key: string): SqliteSessionInspection | null {
+		const storedKey = toStorageKey(options?.namespace, key);
+		const row = selectQuery.get(storedKey) as SessionRow | null;
+
+		if (!row) {
+			return null;
+		}
+
+		return {
+			storedKey,
+			value: row.value,
+			expiresAt: row.expires_at,
+		};
+	}
+
+	return {
+		async get(key) {
+			const storedKey = toStorageKey(options?.namespace, key);
+			const row = selectQuery.get(storedKey) as SessionRow | null;
+
+			if (!row) {
+				return null;
+			}
+
+			if (row.expires_at !== null && row.expires_at <= Date.now()) {
+				deleteQuery.run(storedKey);
+				return null;
+			}
+
+			return row.value;
+		},
+		async set(key, value, ttl) {
+			const storedKey = toStorageKey(options?.namespace, key);
+			const expiresAt = resolveExpiresAt(ttl);
+
+			upsertQuery.run(storedKey, value, expiresAt);
+		},
+		async delete(key) {
+			deleteQuery.run(toStorageKey(options?.namespace, key));
+		},
+		__unsafeInspect: inspectRecord,
+	};
+}
+
+export function createSessionStore(
+	options?: SessionStoreOptions,
+): SessionStore {
+	if (resolveBackend(options) === "supabase") {
+		if (!options?.supabaseUrl) {
+			throw new TypeError(
+				"Supabase session store requires supabaseUrl when backend is 'supabase'.",
+			);
+		}
+
+		if (!options.supabaseKey) {
+			throw new TypeError(
+				"Supabase session store requires supabaseKey when backend is 'supabase'.",
+			);
+		}
+
+		if (!options.encryptionKey) {
+			throw new TypeError(
+				"Supabase session store requires encryptionKey when backend is 'supabase'.",
+			);
+		}
+
+		if (!options.connectionId) {
+			throw new TypeError(
+				"Supabase session store requires connectionId when backend is 'supabase'.",
+			);
+		}
+
+		return new SupabaseSessionStore({
+			connectionId: options.connectionId,
+			encryptionKey: options.encryptionKey,
+			fetch: options.fetch,
+			supabaseKey: options.supabaseKey,
+			supabaseUrl: options.supabaseUrl,
+		});
+	}
+
+	return createSqliteSessionStore(options);
+}

package/src/runtime/state.ts

@@ -0,0 +1,124 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import type { StateContext } from "../types";
+import { parseSessionTtl } from "./session";
+
+type SealedPayload = {
+	data: unknown;
+	exp: number | null;
+};
+
+function toBase64Url(value: string): string {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function fromBase64Url(value: string): string | null {
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+		return null;
+	}
+
+	try {
+		return Buffer.from(value, "base64url").toString("utf8");
+	} catch {
+		return null;
+	}
+}
+
+function signPayload(payload: string, secret: string): string {
+	return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+function hasValidSignature(
+	payload: string,
+	signature: string,
+	secret: string,
+): boolean {
+	const expectedSignature = signPayload(payload, secret);
+	const expectedBuffer = Buffer.from(expectedSignature, "utf8");
+	const receivedBuffer = Buffer.from(signature, "utf8");
+
+	if (expectedBuffer.length !== receivedBuffer.length) {
+		return false;
+	}
+
+	return timingSafeEqual(expectedBuffer, receivedBuffer);
+}
+
+function isSealedPayload(value: unknown): value is SealedPayload {
+	if (!value || typeof value !== "object") {
+		return false;
+	}
+
+	const payload = value as Record<string, unknown>;
+
+	return (
+		"data" in payload &&
+		"exp" in payload &&
+		(payload.exp === null ||
+			(typeof payload.exp === "number" && Number.isFinite(payload.exp)))
+	);
+}
+
+export function createStateContext(secret?: string): StateContext {
+	const resolvedSecret = process.env.APIFUSE_STATE_SECRET ?? secret;
+	if (!resolvedSecret) {
+		console.warn(
+			"[apifuse] Warning: APIFUSE_STATE_SECRET is not set. " +
+				"Using insecure dev secret. Set APIFUSE_STATE_SECRET in production.",
+		);
+	}
+	const effectiveSecret = resolvedSecret ?? "dev-secret";
+
+	return {
+		async seal(data, options) {
+			const ttlMs = parseSessionTtl(options?.ttl);
+			const payload = toBase64Url(
+				JSON.stringify({
+					data,
+					exp: ttlMs === null ? null : Date.now() + ttlMs,
+				} satisfies SealedPayload),
+			);
+
+			return `${payload}.${signPayload(payload, effectiveSecret)}`;
+		},
+		async unseal<T = unknown>(token: string): Promise<T | null> {
+			try {
+				const parts = token.split(".");
+
+				if (parts.length !== 2) {
+					return null;
+				}
+
+				const [payload, signature] = parts;
+
+				if (
+					!payload ||
+					!signature ||
+					!hasValidSignature(payload, signature, effectiveSecret)
+				) {
+					return null;
+				}
+
+				const decodedPayload = fromBase64Url(payload);
+
+				if (decodedPayload === null) {
+					return null;
+				}
+
+				const parsedPayload = JSON.parse(decodedPayload) as unknown;
+
+				if (!isSealedPayload(parsedPayload)) {
+					return null;
+				}
+
+				if (parsedPayload.exp !== null && parsedPayload.exp <= Date.now()) {
+					return null;
+				}
+
+				return parsedPayload.data as T;
+			} catch {
+				return null;
+			}
+		},
+	};
+}