@tealbrick/deliver 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tealbrick contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,5 @@
+Independently authored for Teal Brick. Behavior reference: installed
+@kybernesis/engineer 0.6.2 deliver tool and @kybernesis/exe preflight.
+No donor implementation copied or imported. Uses official AWS and Vercel SDKs
+for provider transport, shared Teal Brick bounded waits, and Eve 0.49.0 tools.
+Dependencies retain their respective licenses.

package/README.md

@@ -0,0 +1,110 @@
+# @tealbrick/deliver
+
+Deliver sandbox files to chat recipients using a provider chosen during setup.
+Node 24+, native Eve 0.55.0 tool adapter. Host-independent byte delivery API.
+
+## First-time setup
+
+After installing this package in your Eve project, run:
+
+```sh
+npx tealbrick-deliver setup
+```
+
+1. Select R2, AWS S3, custom S3-compatible storage (including self-hosted MinIO),
+   Vercel Blob, or a directory already served by your web server.
+2. Enter provider-specific endpoint/bucket/region and masked credentials.
+3. Select signed or public access where supported; explicitly accept public links.
+4. Optionally verify a disposable upload/download/delete before saving.
+
+Creates `.tealbrick/deliver.json`, owner-only `.tealbrick/deliver.credentials.json`,
+and `agent/tools/deliver.ts`. Adds `/.tealbrick/` to the project's `.gitignore` before
+saving. Existing settings/tools are never overwritten. Config stores environment
+variable names, not credentials. Local credential-file permissions are checked.
+Windows hosts must additionally restrict access using their account ACLs.
+
+Deploy settings separately from source. Supply referenced credentials as runtime
+secrets, or explicitly provision the protected credentials file. Do not put secrets
+in the agent mount, image, browser, sandbox or chat. Runtime working directory must
+contain `.tealbrick/`, or pass absolute paths to `configuredDeliverTool`.
+
+```sh
+npx tealbrick-deliver check
+```
+
+`check` creates a disposable object, fetches its recipient-facing URL, compares the
+bytes and deletes it. Failure is explicit. A failed cleanup returns only the object
+key for operator reconciliation. This checks the host's network reachability;
+mobile/desktop/Telegram acceptance must also be tested from those clients.
+No buckets or web servers are provisioned by setup.
+
+## Providers
+
+| Provider | Required target and credentials | Delivery |
+|---|---|---|
+| R2 | HTTPS S3 endpoint, bucket, key ID and secret; region `auto` | Signed (default), or configured public base URL |
+| AWS S3 | Bucket, region, key ID and secret | Signed (default), or configured public base URL |
+| S3-compatible / MinIO | HTTPS endpoint, bucket, region, addressing style, key pair | Signed or public base URL |
+| Vercel Blob | Public-store token | Public URL |
+| Served directory | Absolute operator-owned directory and HTTPS serving URL | Public URL |
+
+Provider selection is explicit. `BLOB_READ_WRITE_TOKEN`, `DELIVER_DIR` and other
+legacy variables do not silently select a provider. Custom endpoints require HTTPS;
+self-hosted services can terminate TLS through a reverse proxy. Private tailnet
+hosts are reachable only to recipients on that network.
+
+Signed URLs default to 24 hours; configure 60 seconds through seven days. An object
+can outlive its link. This package does not renew links or run a retention job.
+Configure bucket lifecycle separately. R2 signed URLs use the S3 endpoint, not a
+custom domain. Public URLs require an already configured public bucket/domain.
+No bucket ACL changes are made. Temporary S3 credentials may expire before the
+requested link lifetime; direct config supports `sessionTokenEnv`.
+
+## Eve tool
+
+Setup creates this mount:
+
+```ts
+import {configuredDeliverTool} from '@tealbrick/deliver/eve';
+export default configuredDeliverTool();
+```
+
+The agent calls `deliver({path:'/workspace/report.pdf',filename:'report.pdf'})`.
+Only the current Eve sandbox is read. Mount this capability only on authorized
+agents; the host owns session authorization. No local host-file read tool is exposed.
+
+Result: `{url, objectKey, filename, contentType, byteSize, sha256, access, expiresAt?, note}`.
+The chat client can display/open the URL. Native Telegram attachment uploads and
+stable Teal Brick link renewal are future channel/gateway work, not implemented
+by this package. Signed links are bearer capabilities; no Portal cookie is needed.
+Treat them as sensitive when logging or forwarding.
+
+## Programmatic use
+
+```ts
+import {createDeliver,validateDeliveryConfig} from '@tealbrick/deliver';
+const config=validateDeliveryConfig({
+  version:1,provider:'r2',endpoint:'https://ACCOUNT.r2.cloudflarestorage.com',
+  bucket:'my-deliveries',region:'auto',forcePathStyle:true,
+  accessKeyIdEnv:'TEALBRICK_DELIVER_ACCESS_KEY_ID',
+  secretAccessKeyEnv:'TEALBRICK_DELIVER_SECRET_ACCESS_KEY',
+  access:'signed',expiresIn:86400,
+});
+const deliver=createDeliver(config);
+const result=await deliver({data:new Uint8Array([1,2,3]),filename:'export.bin'});
+```
+
+Defaults: 100 MiB per file, 30-second timeout (configurable up to 120 seconds).
+The Eve sandbox API returns the whole file before the size check; this is not a
+streaming upload implementation. Cancellation bounds waits; ambiguous failures
+report the generated object key so an operator can reconcile whether an upload exists. Do not blindly retry them. Unique delivery keys
+prevent overwrite; setup cleanup only addresses its own generated key.
+
+Unknown formats, HTML and SVG use download MIME rather than active web content.
+Serve directory files as downloads with `X-Content-Type-Options: nosniff` in your
+web server. The directory and parents must be operator-owned, outside the sandbox;
+symlinked child directories are rejected. Files must be readable by your web server.
+
+This package is the file-delivery adapter, not Knowledge document ingestion.
+Tests use temporary directories, injected SDK transports and local credentials.
+Fresh tarball Eve discovery/build is distinct from live provider/client validation.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { select, input, password, confirm } from '@inquirer/prompts';
+import { collectSetup, saveSetup, loadCredentialFile } from './setup.js';
+import { loadDeliveryConfig, verifyDelivery } from './index.js';
+import { mkdir } from 'node:fs/promises';
+async function main() {
+    const command = process.argv[2];
+    if (command === 'setup') {
+        console.log('Teal Brick file delivery setup. Run in your Eve agent project. Local credentials are stored separately with owner-only permissions; deploy them as runtime secrets.');
+        const prompt = { select: (message, choices) => select({ message, choices }), input: (message, defaultValue) => input({ message, default: defaultValue }), password: (message) => password({ message, mask: '*' }), confirm: (message) => confirm({ message, default: false }) };
+        const result = await collectSetup(prompt);
+        if (await prompt.confirm('Upload, download and delete a disposable test file now?')) {
+            if (result.config.provider === 'directory')
+                await mkdir(result.config.directory, { recursive: true });
+            const check = await verifyDelivery(result.config, { env: result.credentials });
+            console.log(JSON.stringify(check));
+            if (!check.ok)
+                throw Error('delivery_verification_failed_settings_not_saved');
+        }
+        else
+            console.log('Delivery reachability is unverified. Run tealbrick-deliver check after configuring hosting.');
+        console.log(JSON.stringify(await saveSetup(process.cwd(), result.config, result.credentials)));
+    }
+    else if (command === 'check') {
+        const config = await loadDeliveryConfig('.tealbrick/deliver.json');
+        const env = { ...process.env, ...await loadCredentialFile('.tealbrick/deliver.credentials.json') };
+        const result = await verifyDelivery(config, { env });
+        console.log(JSON.stringify(result));
+        if (!result.ok)
+            process.exitCode = 1;
+    }
+    else {
+        console.log('Usage: tealbrick-deliver setup | check\nsetup: choose provider and mount the Eve deliver tool\ncheck: upload/read/delete a disposable object to verify the recipient URL');
+        if (command && command !== '--help')
+            process.exitCode = 1;
+    }
+}
+main().catch(() => { console.error('Delivery setup/check failed. Check settings, permissions and connectivity. Provider details and credentials are omitted.'); process.exitCode = 1; });

package/dist/config.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+export declare const configSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    provider: z.ZodLiteral<"r2">;
+    region: z.ZodLiteral<"auto">;
+    endpoint: z.ZodString;
+    bucket: z.ZodString;
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    accessKeyIdEnv: z.ZodString;
+    secretAccessKeyEnv: z.ZodString;
+    sessionTokenEnv: z.ZodOptional<z.ZodString>;
+    access: z.ZodDefault<z.ZodEnum<{
+        signed: "signed";
+        public: "public";
+    }>>;
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    publicBaseUrl: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"s3">;
+    endpoint: z.ZodOptional<z.ZodString>;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    accessKeyIdEnv: z.ZodString;
+    secretAccessKeyEnv: z.ZodString;
+    sessionTokenEnv: z.ZodOptional<z.ZodString>;
+    access: z.ZodDefault<z.ZodEnum<{
+        signed: "signed";
+        public: "public";
+    }>>;
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    publicBaseUrl: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"s3-compatible">;
+    endpoint: z.ZodString;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    accessKeyIdEnv: z.ZodString;
+    secretAccessKeyEnv: z.ZodString;
+    sessionTokenEnv: z.ZodOptional<z.ZodString>;
+    access: z.ZodDefault<z.ZodEnum<{
+        signed: "signed";
+        public: "public";
+    }>>;
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    publicBaseUrl: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"vercel-blob">;
+    access: z.ZodLiteral<"public">;
+    tokenEnv: z.ZodString;
+    version: z.ZodLiteral<1>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"directory">;
+    access: z.ZodLiteral<"public">;
+    directory: z.ZodString;
+    publicBaseUrl: z.ZodString;
+    version: z.ZodLiteral<1>;
+    maxBytes: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    prefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>], "provider">;
+export type DeliveryConfig = z.infer<typeof configSchema>;
+export declare function validateDeliveryConfig(value: unknown): DeliveryConfig;
+export declare function secret(env: NodeJS.ProcessEnv, name: string): string;
+export declare function publicUrl(base: string, key: string): string;

package/dist/config.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { isAbsolute } from 'node:path';
+const url = z.string().url().refine(v => { const u = new URL(v); return u.protocol === 'https:' && !u.username && !u.password && !u.search && !u.hash; }, 'Use HTTPS without credentials, query or fragment');
+const env = z.string().regex(/^[A-Z][A-Z0-9_]*$/);
+const common = { version: z.literal(1), maxBytes: z.number().int().min(1).max(104857600).default(104857600), timeoutMs: z.number().int().min(1).max(120000).default(30000), prefix: z.string().regex(/^(?:[a-zA-Z0-9_-]+\/)*$/).default('deliveries/') };
+const s3 = { ...common, endpoint: url.optional(), bucket: z.string().regex(/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/), region: z.string().min(1), forcePathStyle: z.boolean().default(false), accessKeyIdEnv: env, secretAccessKeyEnv: env, sessionTokenEnv: env.optional(), access: z.enum(['signed', 'public']).default('signed'), expiresIn: z.number().int().min(60).max(604800).default(86400), publicBaseUrl: url.optional() };
+export const configSchema = z.discriminatedUnion('provider', [
+    z.object({ ...s3, provider: z.literal('r2'), region: z.literal('auto'), endpoint: url }).strict(),
+    z.object({ ...s3, provider: z.literal('s3') }).strict(),
+    z.object({ ...s3, provider: z.literal('s3-compatible'), endpoint: url }).strict(),
+    z.object({ ...common, provider: z.literal('vercel-blob'), access: z.literal('public'), tokenEnv: env }).strict(),
+    z.object({ ...common, provider: z.literal('directory'), access: z.literal('public'), directory: z.string().refine(isAbsolute, 'Use an absolute directory'), publicBaseUrl: url }).strict(),
+]).superRefine((c, ctx) => { if ('bucket' in c && c.access === 'public' && !c.publicBaseUrl)
+    ctx.addIssue({ code: 'custom', message: 'Public delivery requires publicBaseUrl' }); });
+export function validateDeliveryConfig(value) { return configSchema.parse(value); }
+export function secret(env, name) {
+    const value = env[name];
+    if (!value || /[\r\n\0]/.test(value))
+        throw new Error('delivery_credential_missing_or_invalid');
+    return value;
+}
+export function publicUrl(base, key) { return `${base.replace(/\/$/, '')}/${key.split('/').map(encodeURIComponent).join('/')}`; }

package/dist/eve.d.ts

@@ -0,0 +1,24 @@
+import { type DeliveryConfig, type DriverOptions } from './index.js';
+/** Mount only on an authorized agent. Reads its own sandbox, never host file paths. */
+export declare function deliverTool(options: {
+    config: DeliveryConfig | string;
+    driverOptions?: DriverOptions;
+}): import("eve/tools").ToolDefinition<{
+    path: string;
+    filename?: string | undefined;
+}, import("./index.js").DeliveryResult> & {
+    execute(input: {
+        path: string;
+        filename?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<import("./index.js").DeliveryResult>;
+};
+/** Setup-generated mount. Paths resolve on the trusted host, not in the sandbox. */
+export declare function configuredDeliverTool(configPath?: string, credentialsPath?: string): import("eve/tools").ToolDefinition<{
+    path: string;
+    filename?: string | undefined;
+}, import("./index.js").DeliveryResult | AsyncIterable<import("./index.js").DeliveryResult>> & {
+    execute(input: {
+        path: string;
+        filename?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<import("./index.js").DeliveryResult | AsyncIterable<import("./index.js").DeliveryResult>>;
+};

package/dist/eve.js

@@ -0,0 +1,23 @@
+import { defineTool } from 'eve/tools';
+import { z } from 'zod';
+import { boundedWait } from '@tealbrick/provider-transport';
+import { createDeliver, loadDeliveryConfig } from './index.js';
+/** Mount only on an authorized agent. Reads its own sandbox, never host file paths. */
+export function deliverTool(options) {
+    return defineTool({ description: 'Deliver a file from this sandbox to the user through the configured storage provider. Returns a downloadable link and its access/expiry. Use for requested documents, reports and exports.', inputSchema: z.object({ path: z.string().startsWith('/').max(4096), filename: z.string().max(180).optional() }).strict(),
+        async execute({ path, filename }, context) {
+            const c = typeof options.config === 'string' ? await loadDeliveryConfig(options.config) : options.config;
+            const signal = AbortSignal.any([context.abortSignal, AbortSignal.timeout(c.timeoutMs)]);
+            const sandbox = await boundedWait(context.getSandbox(), signal);
+            const data = await boundedWait(Promise.resolve(sandbox.readBinaryFile({ path })), signal);
+            if (!data)
+                throw Error('delivery_file_not_found');
+            return createDeliver(c, options.driverOptions)({ data, filename: filename ?? path.split('/').pop() ?? 'file' }, signal);
+        } });
+}
+/** Setup-generated mount. Paths resolve on the trusted host, not in the sandbox. */
+export function configuredDeliverTool(configPath = '.tealbrick/deliver.json', credentialsPath = '.tealbrick/deliver.credentials.json') {
+    // Lazy loading allows consumer discovery/build without production secrets.
+    return defineTool({ description: 'Deliver a requested sandbox file as a downloadable link using the configured Teal Brick provider. Report link expiry when present.', inputSchema: z.object({ path: z.string().startsWith('/').max(4096), filename: z.string().max(180).optional() }).strict(),
+        async execute(input, context) { const { loadCredentialFile } = await import('./setup.js'); const env = { ...process.env, ...await loadCredentialFile(credentialsPath) }; return deliverTool({ config: configPath, driverOptions: { env } }).execute(input, context); } });
+}

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { put, del } from '@vercel/blob';
+import { type DeliveryConfig } from './config.js';
+export { validateDeliveryConfig, type DeliveryConfig } from './config.js';
+export interface DeliveryResult {
+    url: string;
+    objectKey: string;
+    filename: string;
+    contentType: string;
+    byteSize: number;
+    sha256: string;
+    access: 'public' | 'signed';
+    expiresAt?: string;
+    note: string;
+}
+export interface DeliveryDriver {
+    upload(key: string, data: Uint8Array, contentType: string, filename: string, signal: AbortSignal): Promise<{
+        url: string;
+        expiresAt?: string;
+    }>;
+    remove(key: string, signal: AbortSignal): Promise<void>;
+}
+export interface DriverOptions {
+    env?: NodeJS.ProcessEnv;
+    s3Client?: S3Client;
+    blob?: {
+        put: typeof put;
+        del: typeof del;
+    };
+}
+export declare function createDeliveryDriver(config: DeliveryConfig, options?: DriverOptions): DeliveryDriver;
+export declare function deliveryFilename(value: string): string;
+export declare function createDeliver(config: DeliveryConfig, options?: DriverOptions & {
+    driver?: DeliveryDriver;
+}): (input: {
+    data: Uint8Array;
+    filename: string;
+}, signal?: AbortSignal) => Promise<DeliveryResult>;
+export declare function loadDeliveryConfig(path: string): Promise<{
+    provider: "r2";
+    region: "auto";
+    endpoint: string;
+    bucket: string;
+    forcePathStyle: boolean;
+    accessKeyIdEnv: string;
+    secretAccessKeyEnv: string;
+    access: "signed" | "public";
+    expiresIn: number;
+    version: 1;
+    maxBytes: number;
+    timeoutMs: number;
+    prefix: string;
+    sessionTokenEnv?: string | undefined;
+    publicBaseUrl?: string | undefined;
+} | {
+    provider: "s3";
+    bucket: string;
+    region: string;
+    forcePathStyle: boolean;
+    accessKeyIdEnv: string;
+    secretAccessKeyEnv: string;
+    access: "signed" | "public";
+    expiresIn: number;
+    version: 1;
+    maxBytes: number;
+    timeoutMs: number;
+    prefix: string;
+    endpoint?: string | undefined;
+    sessionTokenEnv?: string | undefined;
+    publicBaseUrl?: string | undefined;
+} | {
+    provider: "s3-compatible";
+    endpoint: string;
+    bucket: string;
+    region: string;
+    forcePathStyle: boolean;
+    accessKeyIdEnv: string;
+    secretAccessKeyEnv: string;
+    access: "signed" | "public";
+    expiresIn: number;
+    version: 1;
+    maxBytes: number;
+    timeoutMs: number;
+    prefix: string;
+    sessionTokenEnv?: string | undefined;
+    publicBaseUrl?: string | undefined;
+} | {
+    provider: "vercel-blob";
+    access: "public";
+    tokenEnv: string;
+    version: 1;
+    maxBytes: number;
+    timeoutMs: number;
+    prefix: string;
+} | {
+    provider: "directory";
+    access: "public";
+    directory: string;
+    publicBaseUrl: string;
+    version: 1;
+    maxBytes: number;
+    timeoutMs: number;
+    prefix: string;
+}>;
+/** Explicit setup check: uploads disposable bytes, verifies the recipient URL, deletes its own object. */
+export declare function verifyDelivery(config: DeliveryConfig, options?: DriverOptions & {
+    driver?: DeliveryDriver;
+    fetch?: typeof fetch;
+}): Promise<{
+    cleanupKey?: string | undefined;
+    ok: boolean;
+    downloadVerified: boolean;
+    cleanupVerified: boolean;
+}>;

package/dist/index.js

@@ -0,0 +1,86 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, writeFile, unlink } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { put, del } from '@vercel/blob';
+import { boundedWait, bytes } from '@tealbrick/provider-transport';
+import { validateDeliveryConfig, secret, publicUrl } from './config.js';
+export { validateDeliveryConfig } from './config.js';
+function checkedUrl(value) { const u = new URL(value); if (u.protocol !== 'https:' || u.username || u.password)
+    throw new Error('delivery_invalid_result_url'); return u.href; }
+export function createDeliveryDriver(config, options = {}) {
+    const c = validateDeliveryConfig(config), env = options.env ?? process.env;
+    if (c.provider === 'directory') {
+        const directory = c.directory;
+        // Directory and its parents are operator-owned, never writable by sandbox users.
+        async function target(key) { const root = await realpath(directory); const path = resolve(root, key); if (!path.startsWith(root + sep))
+            throw Error('delivery_path_invalid'); await mkdir(dirname(path), { recursive: true, mode: 0o755 }); if (await realpath(dirname(path)) !== dirname(path))
+            throw Error('delivery_directory_symlink'); return path; }
+        return { async upload(key, data) { const path = await target(key); await writeFile(path, data, { flag: 'wx', mode: 0o644 }); return { url: publicUrl(c.publicBaseUrl, key) }; }, async remove(key) { await unlink(await target(key)); } };
+    }
+    if (c.provider === 'vercel-blob') {
+        const sdk = options.blob ?? { put, del }, token = secret(env, c.tokenEnv);
+        return { async upload(key, data, contentType, _filename, signal) { const result = await sdk.put(key, Buffer.from(data), { token, access: 'public', addRandomSuffix: false, contentType, abortSignal: signal }); return { url: checkedUrl(result.url) }; }, async remove(key) { await sdk.del(key, { token }); } };
+    }
+    const client = options.s3Client ?? new S3Client({ region: c.region, endpoint: c.endpoint, forcePathStyle: c.forcePathStyle, maxAttempts: 1, credentials: { accessKeyId: secret(env, c.accessKeyIdEnv), secretAccessKey: secret(env, c.secretAccessKeyEnv), ...(c.sessionTokenEnv ? { sessionToken: secret(env, c.sessionTokenEnv) } : {}) } });
+    return {
+        async upload(key, data, contentType, filename, signal) {
+            await client.send(new PutObjectCommand({ Bucket: c.bucket, Key: key, Body: data, ContentType: contentType, ContentDisposition: `attachment; filename="${filename}"` }), { abortSignal: signal });
+            if (c.access === 'public')
+                return { url: publicUrl(c.publicBaseUrl, key) };
+            const url = await getSignedUrl(client, new GetObjectCommand({ Bucket: c.bucket, Key: key }), { expiresIn: c.expiresIn });
+            return { url: checkedUrl(url), expiresAt: new Date(Date.now() + c.expiresIn * 1000).toISOString() };
+        },
+        async remove(key, signal) { await client.send(new DeleteObjectCommand({ Bucket: c.bucket, Key: key }), { abortSignal: signal }); },
+    };
+}
+const mime = { pdf: 'application/pdf', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', zip: 'application/zip', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' };
+export function deliveryFilename(value) { const name = value.replace(/[^a-zA-Z0-9._()+ -]/g, '_').replace(/^\.+/, '').slice(0, 180); return name || 'file'; }
+export function createDeliver(config, options = {}) {
+    const c = validateDeliveryConfig(config);
+    return async (input, signal = new AbortController().signal) => {
+        if (!(input.data instanceof Uint8Array) || input.data.byteLength > c.maxBytes)
+            throw Error('delivery_file_too_large_or_invalid');
+        signal = AbortSignal.any([signal, AbortSignal.timeout(c.timeoutMs)]);
+        signal.throwIfAborted();
+        const filename = deliveryFilename(input.filename), ext = filename.split('.').pop().toLowerCase();
+        // Unknown/text/HTML/SVG formats are downloads, never executable web pages.
+        const contentType = mime[ext] ?? 'application/octet-stream';
+        const key = `${c.prefix}${randomUUID()}/${filename}`;
+        try {
+            const driver = options.driver ?? createDeliveryDriver(c, options);
+            const result = await boundedWait(driver.upload(key, input.data, contentType, filename, signal), signal);
+            return { ...result, objectKey: key, url: checkedUrl(result.url), filename, contentType, byteSize: input.data.byteLength, sha256: createHash('sha256').update(input.data).digest('hex'), access: c.access, note: c.access === 'public' ? 'Anyone with this link can download the file.' : 'This download link expires; use expiresAt. Anyone with the link can download until then.' };
+        }
+        catch {
+            const code = signal.aborted ? 'delivery_cancelled_or_timed_out_upload_may_exist' : 'delivery_failed_upload_may_exist';
+            throw Object.assign(new Error(`${code}; reconcile object ${key} before retrying`), { code, objectKey: key });
+        }
+    };
+}
+export async function loadDeliveryConfig(path) { return validateDeliveryConfig(JSON.parse(await readFile(path, 'utf8'))); }
+/** Explicit setup check: uploads disposable bytes, verifies the recipient URL, deletes its own object. */
+export async function verifyDelivery(config, options = {}) {
+    const c = validateDeliveryConfig(config), driver = options.driver ?? createDeliveryDriver(c, options), key = `${c.prefix}setup-check-${randomUUID()}.txt`, data = Buffer.from(`Teal Brick delivery check ${randomUUID()}`);
+    const signal = AbortSignal.timeout(c.timeoutMs);
+    let verified = false, cleaned = false;
+    try {
+        const result = await boundedWait(driver.upload(key, data, 'text/plain', 'setup-check.txt', signal), signal);
+        const response = await boundedWait((options.fetch ?? fetch)(checkedUrl(result.url), { redirect: 'error', signal }), signal);
+        if (!response.ok)
+            throw Error('delivery_check_download_failed');
+        const received = await bytes(response.body, 4096, signal);
+        verified = Buffer.from(received).equals(data);
+    }
+    catch { /* Return redacted result, never a URL or SDK error with credentials. */ }
+    finally {
+        try {
+            const cleanupSignal = AbortSignal.timeout(c.timeoutMs);
+            await boundedWait(driver.remove(key, cleanupSignal), cleanupSignal);
+            cleaned = true;
+        }
+        catch { }
+    }
+    return { ok: verified && cleaned, downloadVerified: verified, cleanupVerified: cleaned, ...(!cleaned ? { cleanupKey: key } : {}) };
+}

package/dist/setup.d.ts

@@ -0,0 +1,83 @@
+import { type DeliveryConfig } from './index.js';
+export interface SetupPrompt {
+    select(message: string, choices: string[]): Promise<string>;
+    input(message: string, defaultValue?: string): Promise<string>;
+    password(message: string): Promise<string>;
+    confirm(message: string): Promise<boolean>;
+}
+/** Provider is chosen before any provider-specific questions. Secrets are separate. */
+export declare function collectSetup(prompt: SetupPrompt): Promise<{
+    config: {
+        provider: "r2";
+        region: "auto";
+        endpoint: string;
+        bucket: string;
+        forcePathStyle: boolean;
+        accessKeyIdEnv: string;
+        secretAccessKeyEnv: string;
+        access: "signed" | "public";
+        expiresIn: number;
+        version: 1;
+        maxBytes: number;
+        timeoutMs: number;
+        prefix: string;
+        sessionTokenEnv?: string | undefined;
+        publicBaseUrl?: string | undefined;
+    } | {
+        provider: "s3";
+        bucket: string;
+        region: string;
+        forcePathStyle: boolean;
+        accessKeyIdEnv: string;
+        secretAccessKeyEnv: string;
+        access: "signed" | "public";
+        expiresIn: number;
+        version: 1;
+        maxBytes: number;
+        timeoutMs: number;
+        prefix: string;
+        endpoint?: string | undefined;
+        sessionTokenEnv?: string | undefined;
+        publicBaseUrl?: string | undefined;
+    } | {
+        provider: "s3-compatible";
+        endpoint: string;
+        bucket: string;
+        region: string;
+        forcePathStyle: boolean;
+        accessKeyIdEnv: string;
+        secretAccessKeyEnv: string;
+        access: "signed" | "public";
+        expiresIn: number;
+        version: 1;
+        maxBytes: number;
+        timeoutMs: number;
+        prefix: string;
+        sessionTokenEnv?: string | undefined;
+        publicBaseUrl?: string | undefined;
+    } | {
+        provider: "vercel-blob";
+        access: "public";
+        tokenEnv: string;
+        version: 1;
+        maxBytes: number;
+        timeoutMs: number;
+        prefix: string;
+    } | {
+        provider: "directory";
+        access: "public";
+        directory: string;
+        publicBaseUrl: string;
+        version: 1;
+        maxBytes: number;
+        timeoutMs: number;
+        prefix: string;
+    };
+    credentials: Record<string, string>;
+}>;
+export declare function loadCredentialFile(path: string): Promise<NodeJS.ProcessEnv>;
+export declare function saveSetup(root: string, config: DeliveryConfig, credentials: Record<string, string>): Promise<{
+    configPath: string;
+    credentialsPath: string;
+    mountPath: string;
+}>;

package/dist/setup.js

@@ -0,0 +1,96 @@
+import { mkdir, writeFile, readFile, lstat, access } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { validateDeliveryConfig } from './index.js';
+/** Provider is chosen before any provider-specific questions. Secrets are separate. */
+export async function collectSetup(prompt) {
+    const provider = await prompt.select('File delivery provider', ['r2', 's3', 's3-compatible', 'vercel-blob', 'directory']);
+    const c = { version: 1, provider };
+    const credentials = {};
+    if (provider === 'directory') {
+        c.directory = await prompt.input('Absolute directory served by your web server');
+        c.publicBaseUrl = await prompt.input('HTTPS URL serving that directory');
+        c.access = 'public';
+    }
+    else if (provider === 'vercel-blob') {
+        c.tokenEnv = 'TEALBRICK_DELIVER_BLOB_TOKEN';
+        credentials[c.tokenEnv] = await prompt.password('Vercel Blob token (public store)');
+        c.access = 'public';
+    }
+    else {
+        if (provider !== 's3')
+            c.endpoint = await prompt.input('S3 HTTPS endpoint', provider === 'r2' ? 'https://<account-id>.r2.cloudflarestorage.com' : undefined);
+        c.bucket = await prompt.input('Bucket name');
+        c.region = provider === 'r2' ? 'auto' : await prompt.input('Region', 'us-east-1');
+        c.forcePathStyle = provider === 's3-compatible' ? await prompt.confirm('Use path-style addressing?') : provider === 'r2';
+        c.accessKeyIdEnv = 'TEALBRICK_DELIVER_ACCESS_KEY_ID';
+        c.secretAccessKeyEnv = 'TEALBRICK_DELIVER_SECRET_ACCESS_KEY';
+        credentials[c.accessKeyIdEnv] = await prompt.password('Access key ID');
+        credentials[c.secretAccessKeyEnv] = await prompt.password('Secret access key');
+        c.access = await prompt.select('Download access', ['signed', 'public']);
+        if (c.access === 'signed')
+            c.expiresIn = Number(await prompt.input('Link lifetime in seconds (60–604800)', '86400'));
+        else
+            c.publicBaseUrl = await prompt.input('Public HTTPS base URL for this bucket');
+    }
+    if (c.access === 'public' && !await prompt.confirm('Anyone with a delivery link can download it. Use public delivery?'))
+        throw Error('setup_cancelled');
+    c.prefix = await prompt.input('Object prefix (end with /)', 'deliveries/');
+    for (const value of Object.values(credentials))
+        if (!value || /[\r\n\0]/.test(value))
+            throw Error('invalid_credentials');
+    return { config: validateDeliveryConfig(c), credentials };
+}
+export async function loadCredentialFile(path) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || (process.platform !== 'win32' && (info.mode & 0o077) !== 0))
+            throw Error('delivery_credentials_permissions');
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        if (!data || Array.isArray(data) || typeof data !== 'object' || Object.entries(data).some(([k, v]) => !/^TEALBRICK_DELIVER_[A-Z_]+$/.test(k) || typeof v !== 'string' || /[\r\n\0]/.test(v)))
+            throw Error('delivery_credentials_invalid');
+        return data;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+export async function saveSetup(root, config, credentials) {
+    config = validateDeliveryConfig(config);
+    if (Object.entries(credentials).some(([k, v]) => !/^TEALBRICK_DELIVER_[A-Z_]+$/.test(k) || typeof v !== 'string' || !v || /[\r\n\0]/.test(v)))
+        throw Error('delivery_credentials_invalid');
+    const dir = resolve(root, '.tealbrick');
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    if ((await lstat(dir)).isSymbolicLink())
+        throw Error('delivery_settings_symlink');
+    // Fail before touching existing setup; never replace an existing delivery tool.
+    const files = [join(dir, 'deliver.json'), join(dir, 'deliver.credentials.json'), resolve(root, 'agent/tools/deliver.ts')];
+    for (const file of files) {
+        try {
+            await access(file);
+            throw Error('delivery_setup_already_exists');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    const ignore = resolve(root, '.gitignore');
+    let old = '';
+    try {
+        old = await readFile(ignore, 'utf8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    // Protect local settings and secrets before creating them.
+    if (!old.split(/\r?\n/).includes('/.tealbrick/'))
+        await writeFile(ignore, `${old}${old.endsWith('\n') || !old ? '' : '\n'}/.tealbrick/\n`);
+    await writeFile(files[1], JSON.stringify(credentials, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await writeFile(files[0], JSON.stringify(config, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await mkdir(dirname(files[2]), { recursive: true });
+    await writeFile(files[2], `import {configuredDeliverTool} from '@tealbrick/deliver/eve';\nexport default configuredDeliverTool();\n`, { flag: 'wx' });
+    return { configPath: files[0], credentialsPath: files[1], mountPath: files[2] };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@tealbrick/deliver",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Provider-first file delivery for Eve and other Teal Brick hosts",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "bin": {
+    "tealbrick-deliver": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./eve": {
+      "types": "./dist/eve.d.ts",
+      "import": "./dist/eve.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build --workspace @tealbrick/provider-transport && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1132.0",
+    "@aws-sdk/s3-request-presigner": "3.1132.0",
+    "@vercel/blob": "2.8.0",
+    "@inquirer/prompts": "8.7.2",
+    "@tealbrick/provider-transport": "0.1.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "eve": ">=0.55.0 <0.56.0"
+  },
+  "peerDependenciesMeta": {
+    "eve": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Doppelabs/tealbrick-packages.git",
+    "directory": "packages/deliver"
+  }
+}