@rehearsal-db/core 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/src/identity/provider_configuration.d.mts

@@ -0,0 +1,37 @@
+/** Render reviewed local OAuth declarations into the disposable Supabase runtime. */
+export interface SupabaseAuthenticationProvider {
+    name: "google" | "github";
+    clientIdEnvironmentVariable: string;
+    clientSecretEnvironmentVariable: string;
+    skipNonceCheck?: boolean;
+    emailOptional?: boolean;
+}
+export interface SupabaseAuthentication {
+    providers: readonly SupabaseAuthenticationProvider[];
+}
+interface TomlSection {
+    name: string;
+    start: number;
+    end: number;
+}
+interface ProviderReplacementSection extends TomlSection {
+    provider: string;
+}
+interface ProviderTransition {
+    readonly replacedProviders: readonly string[];
+    readonly replacementSections: readonly ProviderReplacementSection[];
+}
+export declare const inspectSupabaseAuthenticationProviderTransition: ({ source, authentication, }: {
+    source: string;
+    authentication: SupabaseAuthentication | null;
+}) => Readonly<ProviderTransition>;
+export declare const renderSupabaseAuthenticationProviders: ({ authentication, apiPort, }: {
+    authentication: SupabaseAuthentication | null;
+    apiPort: number;
+}) => string;
+export declare const applySupabaseAuthenticationProviders: ({ source, authentication, apiPort, }: {
+    source: string;
+    authentication: SupabaseAuthentication | null;
+    apiPort: number;
+}) => string;
+export {};

package/dist/src/identity/provider_configuration.mjs

@@ -0,0 +1,132 @@
+/** Render reviewed local OAuth declarations into the disposable Supabase runtime. */
+const escapePattern = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const LEGACY_PROVIDER_KEYS = new Set([
+    "client_id",
+    "email_optional",
+    "enabled",
+    "redirect_uri",
+    "secret",
+    "skip_nonce_check",
+]);
+const SAFE_BOOLEAN_PROVIDER_KEYS = new Set([
+    "email_optional",
+    "skip_nonce_check",
+]);
+const readTomlSections = (source) => {
+    const lines = source.split("\n");
+    const sections = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(lines[index]);
+        if (!match)
+            continue;
+        if (sections.length)
+            sections.at(-1).end = index;
+        sections.push({ name: match[1], start: index, end: lines.length });
+    }
+    return { lines, sections };
+};
+const validateLegacyProviderSection = ({ lines, section, provider, }) => {
+    const seen = new Set();
+    for (const line of lines.slice(section.start + 1, section.end)) {
+        if (!line.trim() || /^\s*#/u.test(line))
+            continue;
+        const assignment = /^\s*([A-Za-z0-9_]+)\s*=/u.exec(line);
+        if (!assignment || !LEGACY_PROVIDER_KEYS.has(assignment[1])) {
+            throw new Error(`The local Supabase template auth.external.${provider.name} section contains an unsupported setting. Rehearsal left the tracked template unchanged.`);
+        }
+        const key = assignment[1];
+        if (seen.has(key)) {
+            throw new Error(`The local Supabase template auth.external.${provider.name} section contains duplicate ${key} settings.`);
+        }
+        seen.add(key);
+        if (SAFE_BOOLEAN_PROVIDER_KEYS.has(key) &&
+            !new RegExp(`^\\s*${escapePattern(key)}\\s*=\\s*${key === "skip_nonce_check"
+                ? (provider.skipNonceCheck ?? false)
+                : (provider.emailOptional ?? false)}\\s*(?:#.*)?$`, "u").test(line)) {
+            throw new Error(`The local Supabase template auth.external.${provider.name}.${key} setting must match its explicit declarative authentication option before Rehearsal can replace the legacy provider in its disposable runtime copy.`);
+        }
+    }
+};
+export const inspectSupabaseAuthenticationProviderTransition = ({ source, authentication, }) => {
+    if (!authentication)
+        return Object.freeze({ replacedProviders: [], replacementSections: [] });
+    const { lines, sections } = readTomlSections(source);
+    const replacementSections = [];
+    for (const provider of authentication.providers) {
+        const sectionName = `auth.external.${provider.name}`;
+        const nested = sections.filter((section) => section.name.startsWith(`${sectionName}.`));
+        if (nested.length) {
+            throw new Error(`The local Supabase template contains unsupported nested ${sectionName} configuration. Rehearsal left the tracked template unchanged.`);
+        }
+        const matching = sections.filter((section) => section.name === sectionName);
+        if (matching.length > 1) {
+            throw new Error(`The local Supabase template declares ${sectionName} more than once.`);
+        }
+        if (matching.length === 1) {
+            validateLegacyProviderSection({
+                lines,
+                section: matching[0],
+                provider,
+            });
+            replacementSections.push({ ...matching[0], provider: provider.name });
+        }
+    }
+    return Object.freeze({
+        replacedProviders: Object.freeze(replacementSections.map(({ provider }) => provider)),
+        replacementSections: Object.freeze(replacementSections),
+    });
+};
+export const renderSupabaseAuthenticationProviders = ({ authentication, apiPort, }) => {
+    if (!authentication)
+        return "";
+    return authentication.providers
+        .map((provider) => `# Generated by Rehearsal from config.supabase.authentication.
+[auth.external.${provider.name}]
+enabled = true
+client_id = "env(${provider.clientIdEnvironmentVariable})"
+secret = "env(${provider.clientSecretEnvironmentVariable})"
+redirect_uri = "http://127.0.0.1:${apiPort}/auth/v1/callback"
+${provider.skipNonceCheck ? "skip_nonce_check = true\n" : ""}${provider.emailOptional ? "email_optional = true\n" : ""}
+`)
+        .join("\n");
+};
+const enableLocalSignup = (source) => {
+    const lines = source.split("\n");
+    let inAuth = false;
+    let authSections = 0;
+    let signupSettings = 0;
+    const updated = lines.map((line) => {
+        const section = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/u.exec(line);
+        if (section) {
+            inAuth = section[1] === "auth";
+            if (inAuth)
+                authSections += 1;
+            return line;
+        }
+        if (!inAuth || !/^\s*enable_signup\s*=/u.test(line))
+            return line;
+        signupSettings += 1;
+        const comment = line.match(/\s+#.*$/u)?.[0] ?? "";
+        return `enable_signup = true${comment}`;
+    });
+    if (authSections !== 1 || signupSettings !== 1) {
+        throw new Error("The local Supabase template must declare exactly one [auth] section with one enable_signup setting before Rehearsal can configure OAuth.");
+    }
+    return updated.join("\n");
+};
+export const applySupabaseAuthenticationProviders = ({ source, authentication, apiPort, }) => {
+    if (!authentication)
+        return source;
+    const transition = inspectSupabaseAuthenticationProviderTransition({
+        source,
+        authentication,
+    });
+    const { lines } = readTomlSections(source);
+    const replacedIndexes = new Set(transition.replacementSections.flatMap((section) => Array.from({ length: section.end - section.start }, (_, offset) => section.start + offset)));
+    const transitionedSource = lines
+        .filter((_, index) => !replacedIndexes.has(index))
+        .join("\n");
+    const runtimeSource = enableLocalSignup(transitionedSource);
+    const separator = runtimeSource.endsWith("\n") ? "\n" : "\n\n";
+    return `${runtimeSource}${separator}${renderSupabaseAuthenticationProviders({ authentication, apiPort })}`;
+};

package/dist/src/identity/storage.d.mts

@@ -0,0 +1,21 @@
+/** Copy and verify local Supabase Storage objects during an identity claim. */
+export interface StorageObjectReceipt {
+    readonly bytes: number;
+    readonly sha256: string;
+}
+export interface SupabaseStorageTransfer {
+    copyAndVerify(input: {
+        bucket: string;
+        source: string;
+        destination: string;
+    }): Promise<StorageObjectReceipt>;
+    remove(input: {
+        bucket: string;
+        paths: readonly string[];
+    }): Promise<void>;
+}
+export declare const createSupabaseStorageTransfer: ({ url, serviceRoleKey, fetchImpl, }: {
+    url: string;
+    serviceRoleKey: string;
+    fetchImpl?: typeof fetch;
+}) => SupabaseStorageTransfer;

package/dist/src/identity/storage.mjs

@@ -0,0 +1,122 @@
+/** Copy and verify local Supabase Storage objects during an identity claim. */
+import { createHash } from "node:crypto";
+import { assertLoopbackUrl } from "../shared/process_environment.mjs";
+const BUCKET = /^[a-z0-9][a-z0-9.-]{0,99}$/u;
+const MAXIMUM_VERIFICATION_BYTES = 100 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+const objectPath = (value) => {
+    if (typeof value !== "string" ||
+        !value ||
+        value.startsWith("/") ||
+        value.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new Error("A Storage identity-claim path is unsafe.");
+    }
+    return value.split("/").map(encodeURIComponent).join("/");
+};
+const readVerifiedObject = async ({ fetchImpl, baseUrl, headers, bucket, path, }) => {
+    const response = await fetchImpl(`${baseUrl}/storage/v1/object/${encodeURIComponent(bucket)}/${objectPath(path)}?rehearsal=${Date.now()}`, {
+        headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`Supabase Storage could not read an identity-claim object (HTTP ${response.status}).`);
+    }
+    const declaredBytes = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredBytes) &&
+        declaredBytes > MAXIMUM_VERIFICATION_BYTES) {
+        throw new Error("A Storage identity-claim object exceeds the 100 MiB verification limit.");
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAXIMUM_VERIFICATION_BYTES) {
+        throw new Error("A Storage identity-claim object exceeds the 100 MiB verification limit.");
+    }
+    return Object.freeze({
+        bytes: bytes.length,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+};
+export const createSupabaseStorageTransfer = ({ url, serviceRoleKey, fetchImpl = globalThis.fetch, }) => {
+    assertLoopbackUrl("Rehearsal Supabase Storage", url);
+    if (typeof serviceRoleKey !== "string" || !serviceRoleKey) {
+        throw new Error("The local runtime environment has no Storage service key.");
+    }
+    if (typeof fetchImpl !== "function") {
+        throw new Error("A Fetch implementation is required for Storage transfer.");
+    }
+    const baseUrl = url.replace(/\/$/u, "");
+    const headers = Object.freeze({
+        apikey: serviceRoleKey,
+        authorization: `Bearer ${serviceRoleKey}`,
+    });
+    const removePaths = async ({ bucket, paths, }) => {
+        if (!BUCKET.test(bucket ?? "") || !Array.isArray(paths) || !paths.length) {
+            throw new Error("A Storage identity-claim removal is invalid.");
+        }
+        paths.forEach(objectPath);
+        const response = await fetchImpl(`${baseUrl}/storage/v1/object/${encodeURIComponent(bucket)}`, {
+            method: "DELETE",
+            headers: { ...headers, "content-type": "application/json" },
+            body: JSON.stringify({ prefixes: paths }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(`Supabase Storage could not remove identity-claim objects (HTTP ${response.status}).`);
+        }
+    };
+    return Object.freeze({
+        async copyAndVerify({ bucket, source, destination, }) {
+            if (!BUCKET.test(bucket ?? "")) {
+                throw new Error("A Storage identity-claim bucket is invalid.");
+            }
+            objectPath(source);
+            objectPath(destination);
+            if (source === destination) {
+                throw new Error("A Storage identity-claim copy must change the path.");
+            }
+            const sourceReceipt = await readVerifiedObject({
+                fetchImpl,
+                baseUrl,
+                headers,
+                bucket,
+                path: source,
+            });
+            try {
+                const response = await fetchImpl(`${baseUrl}/storage/v1/object/copy`, {
+                    method: "POST",
+                    headers: { ...headers, "content-type": "application/json" },
+                    body: JSON.stringify({
+                        bucketId: bucket,
+                        sourceKey: source,
+                        destinationKey: destination,
+                    }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                if (!response.ok) {
+                    throw new Error(`Supabase Storage could not copy an identity-claim object (HTTP ${response.status}).`);
+                }
+                const destinationReceipt = await readVerifiedObject({
+                    fetchImpl,
+                    baseUrl,
+                    headers,
+                    bucket,
+                    path: destination,
+                });
+                if (sourceReceipt.bytes !== destinationReceipt.bytes ||
+                    sourceReceipt.sha256 !== destinationReceipt.sha256) {
+                    throw new Error("Supabase Storage copied an identity object with a different byte digest.");
+                }
+                return destinationReceipt;
+            }
+            catch (error) {
+                try {
+                    await removePaths({ bucket, paths: [destination] });
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "Storage identity-copy verification failed and destination cleanup needs attention.");
+                }
+                throw error;
+            }
+        },
+        remove: removePaths,
+    });
+};

package/dist/src/index.d.mts

@@ -0,0 +1,4 @@
+/** Public Rehearsal package entry point. */
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export type { DetectedProject, RehearsalConfig, RehearsalConfigPathOptions, RehearsalConfigVersion, } from "./project/configuration.mjs";
+export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

package/dist/src/index.mjs

@@ -0,0 +1,3 @@
+/** Public Rehearsal package entry point. */
+export { REHEARSAL_CONFIG_VERSION, defineRehearsalConfig, findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./project/configuration.mjs";
+export { EXCLUDED_VALUE, SANITIZATION_ACTIONS, applySanitizationAction, normalizeSanitizationAction, readBoundRuntimeSanitizationPolicy, validateSanitizationCoverage, validateRuntimeSanitizationPolicy, } from "./baseline/sanitization_policy.mjs";

package/dist/src/project/configuration.d.mts

@@ -0,0 +1,181 @@
+/**
+ * Purpose: Load and strictly validate the versioned, project-owned Rehearsal
+ * configuration contract. Do not run directly; this module is reusable script
+ * infrastructure.
+ */
+import type { RehearsalConfig, RehearsalConfigVersion } from "../../types/configuration.mjs";
+export type { RehearsalConfig, RehearsalConfigVersion };
+export declare const REHEARSAL_CONFIG_VERSION = 1;
+export declare const REHEARSAL_DEFAULTS: Readonly<{
+    baseline: Readonly<{
+        artifactDirectory: ".rehearsal";
+    }>;
+    containerRuntime: Readonly<{
+        autoStartColima: true;
+    }>;
+    cleanup: Readonly<{
+        retainBaselineGenerations: 2;
+    }>;
+    runtime: Readonly<{
+        applicationUrl: "http://localhost:5175";
+        projectId: "rehearsal-local";
+    }>;
+    safety: Readonly<{
+        allowedHosts: readonly string[];
+        blockedEnvironmentVariables: readonly string[];
+        hostedAccess: "disabled";
+        outboundNetwork: "deny";
+    }>;
+}>;
+export interface DetectedProject {
+    projectName: string;
+    packageManager: "npm" | "pnpm" | "yarn";
+    hasSupabaseConfig: boolean;
+    hasMigrations: boolean;
+    hasPostgresqlMigrations: boolean;
+    postgresqlMigrationDirectory: string;
+    applicationCommand: string;
+    verificationCommand: string;
+}
+export interface RehearsalConfigPathOptions {
+    projectRoot?: string;
+    configPath?: string;
+}
+export declare const defineRehearsalConfig: <const Config extends RehearsalConfig>(config: Config) => Config;
+export declare const findRehearsalConfigPath: ({ projectRoot, configPath, }?: RehearsalConfigPathOptions) => Promise<string>;
+export declare const loadRehearsalConfig: ({ projectRoot, configPath, }?: RehearsalConfigPathOptions) => Promise<Readonly<{
+    config: Readonly<{
+        schemaVersion: 1;
+        project: Readonly<{
+            name: string;
+        }>;
+        supabase: Readonly<{
+            workdir: string;
+            migrationDirectory: string;
+            rehearsalConfig: string;
+            runtimeWorkdir: string;
+            authentication: Readonly<{
+                enableLocalSignup: true;
+                environmentFile: string;
+                providers: readonly Readonly<{
+                    name: "github" | "google";
+                    clientIdEnvironmentVariable: string;
+                    clientSecretEnvironmentVariable: string;
+                    skipNonceCheck: boolean;
+                    emailOptional: boolean;
+                }>[];
+            }> | null;
+            serviceEnvironmentFile: string | null;
+            serviceEnvironmentVariables: readonly string[];
+        }> | null;
+        postgresql: Readonly<{
+            migrationDirectory: string;
+            runtimeWorkdir: string;
+            image: string;
+            database: string;
+            user: string;
+        }> | null;
+        baseline: Readonly<{
+            artifactDirectory: string;
+            sanitizationPolicy: string;
+        }>;
+        containerRuntime: Readonly<{
+            autoStartColima: boolean;
+        }>;
+        cleanup: Readonly<{
+            retainBaselineGenerations: number;
+        }>;
+        preparation: Readonly<{
+            sourcePolicy: string;
+            privacyKey: string;
+            batchRows: number;
+            maximumRows: number;
+            maximumBytes: number;
+            diskHeadroomBytes: number;
+        }> | null;
+        runtimePolicy: string | null;
+        identityPolicy: string | null;
+        dependentTargets: readonly Readonly<{
+            name: string;
+            configPath: string;
+            prepareCommand: string | null;
+        }>[];
+        application: Readonly<{
+            startCommand: string;
+            proofCommand: string;
+            environmentFile: string;
+            environmentVariables: Readonly<Record<string, string>>;
+            readiness: Readonly<{
+                url: string;
+                expectedStatus: number;
+                timeoutSeconds: number;
+            }> | null;
+            httpProofs: readonly Readonly<{
+                name: string;
+                kind: "positive" | "negative";
+                url: string;
+                method: string;
+                expectedStatus: number;
+                json: Readonly<{
+                    path: readonly string[];
+                    equals?: unknown;
+                    notEquals?: unknown;
+                    minimumItems?: number;
+                }> | null;
+            }>[];
+            runtimeAdapter: string | null;
+        }>;
+        runtime: Readonly<{
+            target: "postgresql" | "supabase";
+            applicationUrl: string;
+            projectId: string;
+            ports: Readonly<{
+                api?: number;
+                database: number;
+                studio?: number;
+            }>;
+        }>;
+        safety: Readonly<{
+            allowedHosts: readonly string[];
+            blockedEnvironmentVariables: readonly string[];
+            authenticationProviders: readonly string[];
+            hostedAccess: "disabled";
+            outboundNetwork: "deny";
+        }>;
+        verification: Readonly<{
+            commands: readonly string[];
+        }>;
+    }>;
+    configPath: string;
+    projectRoot: string;
+    paths: Readonly<{
+        artifactDirectory: string;
+        applicationEnvironment: string;
+        migrationDirectory: string;
+        rehearsalConfig: string | null;
+        runtimeWorkdir: string;
+        serviceEnvironment: string | null;
+        sanitizationPolicy: string;
+        sourcePolicy: string | null;
+        privacyKey: string | null;
+        runtimePolicy: string | null;
+        identityPolicy: string | null;
+        supabaseWorkdir: string | null;
+        runtimeAdapter: string | null;
+    }>;
+}>>;
+export declare const inspectDetectedProject: ({ projectRoot, }?: {
+    projectRoot?: string;
+}) => Promise<DetectedProject>;
+export declare const renderDetectedConfig: (detected: DetectedProject, { applicationUrl, ports, }?: {
+    applicationUrl?: string;
+    ports?: {
+        api: number;
+        database: number;
+        studio: number;
+    };
+}) => string;
+export declare const renderDetectedPostgresqlConfig: (detected: DetectedProject, { applicationUrl, databasePort }?: {
+    applicationUrl?: string | undefined;
+    databasePort?: number | undefined;
+}) => string;