ffp-sql-sandbox 0.1.0

package/dist/image.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default runner image. Digest-pinned in code; do not use a floating tag.
+ *
+ * This pin is the v1 identity of `sandbox/Dockerfile`. It is **not** a
+ * GHCR-pullable digest until the runner is published. `executeSql` without
+ * `image` returns `IMAGE_UNAVAILABLE` if Docker cannot find it. After the
+ * first GHCR publish, replace this with `docker buildx imagetools inspect`.
+ * Custom `image` overrides are untrusted.
+ *
+ * Content identity (sha256 of the runner files at this freeze):
+ * sandbox/Dockerfile + execute.js + stream-limit.js + session-setup.js +
+ * secrets.js + events.js + package.json.
+ */
+export declare const DEFAULT_SANDBOX_IMAGE = "ghcr.io/ffp-tech-lab/ffp-sql-sandbox-runner@sha256:861dd5eb53f5c3eb468b73b6068385f0688910fc10ba68610d20bb3de9f78952";
+export declare function isDigestPinnedImage(image: string): boolean;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,wHACqF,CAAC;AAExH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/image.js

@@ -0,0 +1,19 @@
+const DIGEST_PINNED = /^.+@sha256:[a-f0-9]{64}$/i;
+/**
+ * Default runner image. Digest-pinned in code; do not use a floating tag.
+ *
+ * This pin is the v1 identity of `sandbox/Dockerfile`. It is **not** a
+ * GHCR-pullable digest until the runner is published. `executeSql` without
+ * `image` returns `IMAGE_UNAVAILABLE` if Docker cannot find it. After the
+ * first GHCR publish, replace this with `docker buildx imagetools inspect`.
+ * Custom `image` overrides are untrusted.
+ *
+ * Content identity (sha256 of the runner files at this freeze):
+ * sandbox/Dockerfile + execute.js + stream-limit.js + session-setup.js +
+ * secrets.js + events.js + package.json.
+ */
+export const DEFAULT_SANDBOX_IMAGE = 'ghcr.io/ffp-tech-lab/ffp-sql-sandbox-runner@sha256:861dd5eb53f5c3eb468b73b6068385f0688910fc10ba68610d20bb3de9f78952';
+export function isDigestPinnedImage(image) {
+    return DIGEST_PINNED.test(image.trim());
+}
+//# sourceMappingURL=image.js.map

package/dist/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAAG,2BAA2B,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,qHAAqH,CAAC;AAExH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { ExecuteSqlInput, ExecuteSqlResult } from './types.js';
+export { validateSql } from './validate-sql.js';
+export { DEFAULT_SANDBOX_IMAGE } from './image.js';
+export { DEFAULT_SANDBOX_LIMITS } from './types.js';
+export type { ExecuteSqlFailure, ExecuteSqlInput, ExecuteSqlResult, ExecuteSqlSuccess, QueryResultData, SandboxConnection, SandboxLimits, SqlDialect, ValidateSqlFailure, ValidateSqlResult, ValidateSqlSuccess, } from './types.js';
+/** Public executeSql: Docker client injection is not part of the supported API. */
+export declare function executeSql(input: ExecuteSqlInput): Promise<ExecuteSqlResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAE5E"}

package/dist/index.js

@@ -0,0 +1,9 @@
+import { executeSql as executeSqlWithDeps } from './execute-sql.js';
+export { validateSql } from './validate-sql.js';
+export { DEFAULT_SANDBOX_IMAGE } from './image.js';
+export { DEFAULT_SANDBOX_LIMITS } from './types.js';
+/** Public executeSql: Docker client injection is not part of the supported API. */
+export function executeSql(input) {
+    return executeSqlWithDeps(input);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAepD,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/limits.d.ts

@@ -0,0 +1,11 @@
+import { type SandboxLimits } from './types.js';
+export type LimitsError = {
+    ok: false;
+    error: string;
+};
+export type LimitsOk = {
+    ok: true;
+    limits: SandboxLimits;
+};
+export declare function mergeLimits(partial?: Partial<SandboxLimits>): LimitsOk | LimitsError;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACvD,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAU3D,wBAAgB,WAAW,CACzB,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC/B,QAAQ,GAAG,WAAW,CAiBxB"}

package/dist/limits.js

@@ -0,0 +1,25 @@
+import { DEFAULT_SANDBOX_LIMITS, } from './types.js';
+const LIMIT_KEYS = [
+    'timeoutMs',
+    'memoryMb',
+    'nanoCpus',
+    'maxRows',
+    'maxBytes',
+];
+export function mergeLimits(partial) {
+    const limits = {
+        ...DEFAULT_SANDBOX_LIMITS,
+        ...partial,
+    };
+    for (const key of LIMIT_KEYS) {
+        const value = limits[key];
+        if (!Number.isInteger(value) || value <= 0) {
+            return {
+                ok: false,
+                error: `${key} must be a positive integer`,
+            };
+        }
+    }
+    return { ok: true, limits };
+}
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAKpB,MAAM,UAAU,GAAG;IACjB,WAAW;IACX,UAAU;IACV,UAAU;IACV,SAAS;IACT,UAAU;CACF,CAAC;AAEX,MAAM,UAAU,WAAW,CACzB,OAAgC;IAEhC,MAAM,MAAM,GAAkB;QAC5B,GAAG,sBAAsB;QACzB,GAAG,OAAO;KACX,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAC3C,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,GAAG,GAAG,6BAA6B;aAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/password-tar.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build a ustar archive containing a single file `db_password`.
+ * Used to drop the DB password onto the container tmpfs (never Env).
+ */
+export declare function createPasswordTar(password: string, uid?: number): Buffer;
+//# sourceMappingURL=password-tar.d.ts.map

package/dist/password-tar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-tar.d.ts","sourceRoot":"","sources":["../src/password-tar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAuBtE"}

package/dist/password-tar.js

@@ -0,0 +1,29 @@
+/**
+ * Build a ustar archive containing a single file `db_password`.
+ * Used to drop the DB password onto the container tmpfs (never Env).
+ */
+export function createPasswordTar(password, uid = 1000) {
+    const content = Buffer.from(password, 'utf8');
+    const header = Buffer.alloc(512);
+    header.write('db_password', 0, 100, 'utf8');
+    header.write('0000400\0', 100, 8, 'utf8');
+    header.write(octal(uid, 7) + '\0', 108, 8, 'utf8');
+    header.write(octal(uid, 7) + '\0', 116, 8, 'utf8');
+    header.write(octal(content.length, 11) + '\0', 124, 12, 'utf8');
+    header.write(octal(0, 11) + '\0', 136, 12, 'utf8');
+    header.write('        ', 148, 8, 'utf8');
+    header.write('0', 156, 1, 'utf8');
+    header.write('ustar\0', 257, 6, 'utf8');
+    header.write('00', 263, 2, 'utf8');
+    let checksum = 0;
+    for (let i = 0; i < header.length; i += 1) {
+        checksum += header[i] ?? 0;
+    }
+    header.write(octal(checksum, 6) + '\0 ', 148, 8, 'utf8');
+    const pad = content.length % 512 === 0 ? 0 : 512 - (content.length % 512);
+    return Buffer.concat([header, content, Buffer.alloc(pad), Buffer.alloc(1024)]);
+}
+function octal(value, width) {
+    return value.toString(8).padStart(width, '0');
+}
+//# sourceMappingURL=password-tar.js.map

package/dist/password-tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-tar.js","sourceRoot":"","sources":["../src/password-tar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,GAAG,GAAG,IAAI;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAEnC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAEzD,MAAM,GAAG,GACP,OAAO,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,KAAK,CAAC,KAAa,EAAE,KAAa;IACzC,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/rewrite-host.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Private container DNS rewrite. Not part of the public API.
+ * Allowlisting happens on the caller-supplied host before this is applied.
+ */
+export declare function rewriteLoopbackHost(host: string): string;
+//# sourceMappingURL=rewrite-host.d.ts.map

package/dist/rewrite-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-host.d.ts","sourceRoot":"","sources":["../src/rewrite-host.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/rewrite-host.js

@@ -0,0 +1,16 @@
+const LOOPBACK_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '::1',
+    '[::1]',
+    '0.0.0.0',
+]);
+/**
+ * Private container DNS rewrite. Not part of the public API.
+ * Allowlisting happens on the caller-supplied host before this is applied.
+ */
+export function rewriteLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return LOOPBACK_HOSTS.has(normalized) ? 'host.docker.internal' : host.trim();
+}
+//# sourceMappingURL=rewrite-host.js.map

package/dist/rewrite-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-host.js","sourceRoot":"","sources":["../src/rewrite-host.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,WAAW;IACX,WAAW;IACX,KAAK;IACL,OAAO;IACP,SAAS;CACV,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7C,OAAO,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AAC/E,CAAC"}

package/dist/stream-consumer.d.ts

@@ -0,0 +1,31 @@
+export type RunnerEvent = {
+    type: 'meta';
+    columns: string[];
+} | {
+    type: 'row';
+    values: unknown[];
+} | {
+    type: 'end';
+    truncated?: boolean;
+    reason?: string;
+} | {
+    type: 'error';
+    error: string;
+};
+export type ConsumeLimits = {
+    maxRows: number;
+    maxBytes: number;
+    abort: () => void;
+};
+export type ConsumeResult = {
+    columns: string[];
+    rows: unknown[][];
+    truncated: boolean;
+    error?: string;
+};
+/**
+ * Incrementally parse runner NDJSON from a live stream.
+ * Limits are applied as chunks arrive — not after buffering the full result.
+ */
+export declare function consumeNdjsonResult(stream: AsyncIterable<Buffer | string>, limits: ConsumeLimits): Promise<ConsumeResult>;
+//# sourceMappingURL=stream-consumer.d.ts.map

package/dist/stream-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-consumer.d.ts","sourceRoot":"","sources":["../src/stream-consumer.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,EACtC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAsFxB"}

package/dist/stream-consumer.js

@@ -0,0 +1,139 @@
+/**
+ * Incrementally parse runner NDJSON from a live stream.
+ * Limits are applied as chunks arrive — not after buffering the full result.
+ */
+export async function consumeNdjsonResult(stream, limits) {
+    const rows = [];
+    let columns = [];
+    let truncated = false;
+    let error;
+    let bytes = 0;
+    let lineBuf = '';
+    let aborted = false;
+    const abortOnce = () => {
+        if (aborted) {
+            return;
+        }
+        aborted = true;
+        truncated = true;
+        limits.abort();
+    };
+    try {
+        for await (const chunk of stream) {
+            if (aborted) {
+                break;
+            }
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buf.byteLength;
+            if (bytes > limits.maxBytes) {
+                abortOnce();
+                break;
+            }
+            lineBuf += buf.toString('utf8');
+            let newline = lineBuf.indexOf('\n');
+            while (newline !== -1) {
+                const line = lineBuf.slice(0, newline).trim();
+                lineBuf = lineBuf.slice(newline + 1);
+                if (line.length > 0) {
+                    const event = parseRunnerEvent(line);
+                    if (event) {
+                        switch (event.type) {
+                            case 'meta':
+                                columns = event.columns;
+                                break;
+                            case 'row':
+                                if (rows.length >= limits.maxRows) {
+                                    abortOnce();
+                                    break;
+                                }
+                                rows.push(event.values);
+                                if (rows.length >= limits.maxRows) {
+                                    abortOnce();
+                                }
+                                break;
+                            case 'end':
+                                if (event.truncated) {
+                                    truncated = true;
+                                }
+                                break;
+                            case 'error':
+                                error = event.error;
+                                break;
+                            default: {
+                                const _never = event;
+                                void _never;
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (aborted) {
+                    break;
+                }
+                newline = lineBuf.indexOf('\n');
+            }
+            if (aborted) {
+                break;
+            }
+        }
+    }
+    catch {
+        // Stream destroy / abort is expected when limits fire.
+    }
+    const result = { columns, rows, truncated };
+    if (error !== undefined) {
+        result.error = error;
+    }
+    return result;
+}
+function parseRunnerEvent(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || !('type' in parsed)) {
+        return null;
+    }
+    const record = parsed;
+    switch (record.type) {
+        case 'meta': {
+            const columns = parsed.columns;
+            if (!Array.isArray(columns) || !columns.every((c) => typeof c === 'string')) {
+                return null;
+            }
+            return { type: 'meta', columns };
+        }
+        case 'row': {
+            const values = parsed.values;
+            if (!Array.isArray(values)) {
+                return null;
+            }
+            return { type: 'row', values };
+        }
+        case 'end': {
+            const truncated = parsed.truncated;
+            const reason = parsed.reason;
+            const event = { type: 'end' };
+            if (typeof truncated === 'boolean') {
+                event.truncated = truncated;
+            }
+            if (typeof reason === 'string') {
+                event.reason = reason;
+            }
+            return event;
+        }
+        case 'error': {
+            const error = parsed.error;
+            if (typeof error !== 'string') {
+                return null;
+            }
+            return { type: 'error', error };
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=stream-consumer.js.map

package/dist/stream-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-consumer.js","sourceRoot":"","sources":["../src/stream-consumer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export type SqlDialect = 'postgres' | 'mysql';
+export type SandboxLimits = {
+    timeoutMs: number;
+    memoryMb: number;
+    nanoCpus: number;
+    maxRows: number;
+    maxBytes: number;
+};
+export declare const DEFAULT_SANDBOX_LIMITS: SandboxLimits;
+export type SandboxConnection = {
+    type: SqlDialect;
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+};
+export type ValidateSqlSuccess = {
+    ok: true;
+};
+export type ValidateSqlFailure = {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type ValidateSqlResult = ValidateSqlSuccess | ValidateSqlFailure;
+export type ExecuteSqlInput = {
+    sql: string;
+    connection: SandboxConnection;
+    hostAllowlist: string[];
+    limits?: Partial<SandboxLimits>;
+    /** Custom runner image. Treated as untrusted; the default image is digest-pinned. */
+    image?: string;
+};
+export type QueryResultData = {
+    columns: string[];
+    rows: unknown[][];
+    truncated?: boolean;
+};
+export type ExecuteSqlSuccess = {
+    ok: true;
+    data: QueryResultData;
+};
+export type ExecuteSqlFailure = {
+    ok: false;
+    code: string;
+    error: string;
+};
+export type ExecuteSqlResult = ExecuteSqlSuccess | ExecuteSqlFailure;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,aAMpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAExE,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,iBAAiB,CAAC;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3E,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export const DEFAULT_SANDBOX_LIMITS = {
+    timeoutMs: 10_000,
+    memoryMb: 128,
+    nanoCpus: 500_000_000,
+    maxRows: 1_000,
+    maxBytes: 1_000_000,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,SAAS;CACpB,CAAC"}

package/dist/validate-sql.d.ts

@@ -0,0 +1,8 @@
+export declare function validateSql(sql: string): {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+//# sourceMappingURL=validate-sql.d.ts.map

package/dist/validate-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-sql.d.ts","sourceRoot":"","sources":["../src/validate-sql.ts"],"names":[],"mappings":"AAUA,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,GACV;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4B5D"}

package/dist/validate-sql.js

@@ -0,0 +1,30 @@
+const ALLOWED_PREFIX = /^\s*(SELECT|WITH|SHOW|DESCRIBE|EXPLAIN)\b/i;
+const FORBIDDEN_KEYWORD = /\b(DROP|DELETE|UPDATE|INSERT|ALTER|TRUNCATE|CREATE|GRANT|REVOKE|EXEC|EXECUTE|xp_)\b/i;
+const MULTI_STATEMENT = /;\s*\S/;
+const PREFIX_REASON = 'Only SELECT / WITH / SHOW / DESCRIBE / EXPLAIN statements are allowed';
+export function validateSql(sql) {
+    const trimmed = sql.trim();
+    if (!ALLOWED_PREFIX.test(trimmed)) {
+        return {
+            ok: false,
+            code: 'NOT_READ_ONLY_PREFIX',
+            reason: PREFIX_REASON,
+        };
+    }
+    if (FORBIDDEN_KEYWORD.test(trimmed)) {
+        return {
+            ok: false,
+            code: 'FORBIDDEN_KEYWORD',
+            reason: 'Forbidden SQL keyword detected',
+        };
+    }
+    if (MULTI_STATEMENT.test(trimmed)) {
+        return {
+            ok: false,
+            code: 'MULTI_STATEMENT',
+            reason: 'Multi-statement SQL is not allowed',
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=validate-sql.js.map

package/dist/validate-sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-sql.js","sourceRoot":"","sources":["../src/validate-sql.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,4CAA4C,CAAC;AAEpE,MAAM,iBAAiB,GACrB,sFAAsF,CAAC;AAEzF,MAAM,eAAe,GAAG,QAAQ,CAAC;AAEjC,MAAM,aAAa,GACjB,uEAAuE,CAAC;AAE1E,MAAM,UAAU,WAAW,CACzB,GAAW;IAEX,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAE3B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,sBAAsB;YAC5B,MAAM,EAAE,aAAa;SACtB,CAAC;IACJ,CAAC;IAED,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,mBAAmB;YACzB,MAAM,EAAE,gCAAgC;SACzC,CAAC;IACJ,CAAC;IAED,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,oCAAoC;SAC7C,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ffp-sql-sandbox",
+  "version": "0.1.0",
+  "description": "Read-only SQL sandbox primitives: fail-fast validateSql + Docker executeSql with hard limits",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "sandbox",
+    "README.md",
+    "INTEGRATION.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.33.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FFP-Tech-Lab/ffp-sql-sandbox.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/**/*.test.ts",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "dockerode": "^4.0.7"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.44",
+    "@types/node": "^22.18.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/sandbox/Dockerfile

@@ -0,0 +1,13 @@
+# Digest-pinned Node 22 slim (linux index digest from Docker Hub, 2026-08-25).
+FROM node:22-bookworm-slim@sha256:83f487e0a63425e5b4d146fb5e5be574bcbe1b7b843d3ebafdd95eaf7767a7e5
+
+WORKDIR /sandbox
+
+COPY package.json ./
+RUN npm install --omit=dev && npm cache clean --force
+
+COPY execute.js stream-limit.js session-setup.js secrets.js events.js ./
+
+USER node
+
+ENTRYPOINT ["node", "execute.js"]

package/sandbox/events.d.ts

@@ -0,0 +1,12 @@
+export function encodeRunnerEvent(event: {
+  type: string;
+  [key: string]: unknown;
+}): string;
+export function writeEvent(
+  event: { type: string; [key: string]: unknown },
+  stream?: NodeJS.WritableStream,
+): void;
+export function writeRunnerError(
+  err: unknown,
+  stream?: NodeJS.WritableStream,
+): void;

package/sandbox/events.js

@@ -0,0 +1,14 @@
+import { stdout } from 'node:process';
+
+export function encodeRunnerEvent(event) {
+  return JSON.stringify(event) + '\n';
+}
+
+export function writeEvent(event, stream = stdout) {
+  stream.write(encodeRunnerEvent(event));
+}
+
+export function writeRunnerError(err, stream = stdout) {
+  const message = err instanceof Error ? err.message : String(err);
+  writeEvent({ type: 'error', error: message }, stream);
+}