@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/src/framework/routes/uploads.js

@@ -0,0 +1,262 @@
+import { createRoute } from '../lib/createRoute';
+import { generateUploadKeyFromFilename, getStorageAdapter } from '../lib/upload';
+import { deleteUploadRecord, getUploadRecord, registerUpload } from '../lib/uploadRegistry';
+import { createPresignedUrl } from '../../lib/signing';
+import { z } from 'zod';
+import { createRouter, getBunshotCtx, getRouteAuth } from '../../../packages/bunshot-core/src/index.js';
+const tags = ['Uploads'];
+async function checkUploadAccess(action, key, userId, tenantId, config, app) {
+    const record = await getUploadRecord(key, app);
+    const authorize = config.authorization?.authorize;
+    const allowExternalKeys = config.allowExternalKeys ?? false;
+    if (record) {
+        // If the registry record has a tenantId, the requester must match — period.
+        if (record.tenantId && record.tenantId !== tenantId) {
+            return { allowed: false, notFound: false };
+        }
+        // Owner match → allow
+        if (record.ownerUserId && record.ownerUserId === userId) {
+            return { allowed: true, notFound: false };
+        }
+        // No owner or owner mismatch → try callback
+        if (authorize) {
+            const ok = await authorize({
+                action,
+                key,
+                userId: userId ?? undefined,
+                tenantId: tenantId ?? undefined,
+            });
+            return { allowed: ok, notFound: false };
+        }
+        return { allowed: false, notFound: false };
+    }
+    // Record not in registry
+    if (allowExternalKeys) {
+        if (authorize) {
+            const ok = await authorize({
+                action,
+                key,
+                userId: userId ?? undefined,
+                tenantId: tenantId ?? undefined,
+            });
+            return { allowed: ok, notFound: false };
+        }
+        return { allowed: false, notFound: false };
+    }
+    return { allowed: false, notFound: true };
+}
+export const createUploadsRouter = (config) => {
+    const router = createRouter();
+    const basePath = (config.path ?? '/uploads').replace(/\/$/, '');
+    router.use(`${basePath}/*`, async (c, next) => getRouteAuth(getBunshotCtx(c)).userAuth(c, next));
+    const BLOCKED_MIME_TYPES = new Set([
+        'application/x-executable',
+        'application/x-sh',
+        'application/x-msdownload',
+        'text/html',
+        'application/x-httpd-php',
+        'application/javascript',
+        'text/javascript',
+    ]);
+    const presignRoute = createRoute({
+        method: 'post',
+        path: `${basePath}/presign`,
+        tags,
+        summary: 'Generate presigned upload URL',
+        request: {
+            body: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            filename: z
+                                .string()
+                                .optional()
+                                .describe('Original filename (used to derive the storage key extension)'),
+                            mimeType: z.string().optional().describe('MIME type of the file'),
+                            expirySeconds: z
+                                .number()
+                                .int()
+                                .positive()
+                                .optional()
+                                .describe('URL expiry in seconds'),
+                            maxBytes: z
+                                .number()
+                                .int()
+                                .positive()
+                                .max(100 * 1024 * 1024)
+                                .optional()
+                                .describe('Maximum allowed file size in bytes (client-enforced via Content-Length header). Defaults to 10MB. Maximum: 100MB.'),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                description: 'Presigned URL generated',
+                content: {
+                    'application/json': {
+                        schema: z.object({ url: z.string(), key: z.string(), maxBytes: z.number().optional() }),
+                    },
+                },
+            },
+            400: {
+                description: 'File type not allowed',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+            501: {
+                description: 'Not implemented by adapter',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+        },
+    });
+    router.openapi(presignRoute, async (c) => {
+        const bunshotCtx = c.get('bunshotCtx');
+        const adapter = getStorageAdapter(bunshotCtx);
+        if (!adapter?.presignPut) {
+            return c.json({ error: 'Presigned URLs not supported by the configured storage adapter' }, 501);
+        }
+        const { filename, mimeType, expirySeconds, maxBytes } = c.req.valid('json');
+        if (mimeType && BLOCKED_MIME_TYPES.has(mimeType)) {
+            return c.json({ error: 'File type not allowed.' }, 400);
+        }
+        const app = bunshotCtx.app;
+        const userId = c.get('authUserId') ?? undefined;
+        const tenantId = c.get('tenantId') ?? undefined;
+        // Server-generates the key — client cannot control the storage path
+        const key = generateUploadKeyFromFilename(filename, { userId, tenantId }, undefined, bunshotCtx);
+        const expiry = expirySeconds ?? (typeof config.expirySeconds === 'number' ? config.expirySeconds : 3600);
+        const url = await adapter.presignPut(key, { expirySeconds: expiry, mimeType });
+        // Register the upload for ownership tracking
+        await registerUpload({
+            key,
+            ownerUserId: userId,
+            tenantId,
+            mimeType,
+            bucket: c.get('uploadBucket') ?? undefined,
+            createdAt: Date.now(),
+        }, app);
+        return c.json({ url, key, ...(maxBytes !== undefined ? { maxBytes } : {}) }, 200);
+    });
+    const presignGetRoute = createRoute({
+        method: 'get',
+        path: `${basePath}/presign/:key{.+}`,
+        tags,
+        summary: 'Generate presigned download URL',
+        request: {
+            params: z.object({ key: z.string() }),
+            query: z.object({
+                expiry: z.string().optional().describe('URL expiry in seconds (default: 3600)'),
+            }),
+        },
+        responses: {
+            200: {
+                description: 'Presigned download URL',
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            url: z.string(),
+                            expiresAt: z.number().describe('Unix timestamp (seconds) when the URL expires'),
+                        }),
+                    },
+                },
+            },
+            403: {
+                description: 'Forbidden — not the owner or unauthorized',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+            404: {
+                description: 'Key not found in upload registry',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+            501: {
+                description: 'Not implemented',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+        },
+    });
+    router.openapi(presignGetRoute, async (c) => {
+        const { key } = c.req.valid('param');
+        const { expiry: expiryStr } = c.req.valid('query');
+        const userId = c.get('authUserId');
+        const tenantId = c.get('tenantId');
+        const app = c.get('bunshotCtx').app;
+        const { allowed, notFound } = await checkUploadAccess('read', key, userId, tenantId, config, app);
+        if (notFound)
+            return c.json({ error: 'Not found' }, 404);
+        if (!allowed)
+            return c.json({ error: 'Forbidden' }, 403);
+        const expirySeconds = expiryStr
+            ? parseInt(expiryStr, 10)
+            : typeof config.expirySeconds === 'number'
+                ? config.expirySeconds
+                : 3600;
+        const signingCfg = c.get('bunshotCtx').signing;
+        if (signingCfg?.presignedUrls) {
+            const secret = signingCfg.secret ?? null;
+            if (!secret)
+                return c.json({ error: 'Signing secret not configured' }, 501);
+            const defaultExpiry = typeof signingCfg.presignedUrls === 'object'
+                ? (signingCfg.presignedUrls.defaultExpiry ?? expirySeconds)
+                : expirySeconds;
+            const base = new URL(c.req.url);
+            base.pathname = `${basePath}/download/${key}`;
+            base.search = '';
+            const url = createPresignedUrl(base.toString(), key, { method: 'GET', expiry: defaultExpiry }, secret);
+            const expiresAt = Math.floor(Date.now() / 1000) + defaultExpiry;
+            return c.json({ url, expiresAt }, 200);
+        }
+        // Fallback: adapter.presignGet (S3 only)
+        const adapter = getStorageAdapter(c.get('bunshotCtx'));
+        if (!adapter?.presignGet) {
+            return c.json({
+                error: 'Presigned download URLs not supported. Enable signing.presignedUrls or use an S3 adapter.',
+            }, 501);
+        }
+        const url = await adapter.presignGet(key, { expirySeconds });
+        const expiresAt = Math.floor(Date.now() / 1000) + expirySeconds;
+        return c.json({ url, expiresAt }, 200);
+    });
+    const deleteRoute = createRoute({
+        method: 'delete',
+        path: `${basePath}/:key{.+}`,
+        tags,
+        summary: 'Delete an uploaded file',
+        request: {
+            params: z.object({ key: z.string() }),
+        },
+        responses: {
+            204: { description: 'Deleted' },
+            403: {
+                description: 'Forbidden — not the owner or unauthorized',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+            404: {
+                description: 'Key not found in upload registry',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+            500: {
+                description: 'No storage adapter configured',
+                content: { 'application/json': { schema: z.object({ error: z.string() }) } },
+            },
+        },
+    });
+    router.openapi(deleteRoute, async (c) => {
+        const adapter = getStorageAdapter(c.get('bunshotCtx'));
+        if (!adapter)
+            return c.json({ error: 'No storage adapter configured' }, 500);
+        const { key } = c.req.valid('param');
+        const userId = c.get('authUserId');
+        const tenantId = c.get('tenantId');
+        const app = c.get('bunshotCtx').app;
+        const { allowed, notFound } = await checkUploadAccess('delete', key, userId, tenantId, config, app);
+        if (notFound)
+            return c.json({ error: 'Not found' }, 404);
+        if (!allowed)
+            return c.json({ error: 'Forbidden' }, 403);
+        await adapter.delete(key);
+        await deleteUploadRecord(key, app);
+        return c.body(null, 204);
+    });
+    return router;
+};

package/dist/src/framework/runPluginLifecycle.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Plugin lifecycle execution — extracted from createApp().
+ *
+ * Handles plugin dependency validation, topological sorting,
+ * and execution of the three framework lifecycle phases.
+ */
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { AppEnv, BunshotEventBus, BunshotPlugin } from '../../packages/bunshot-core/src/index.js';
+import type { FrameworkConfig } from './createInfrastructure';
+/**
+ * Validate the plugin dependency graph and return plugins in topological order.
+ * Throws on circular dependencies, missing dependencies, lifecycle-less plugins,
+ * and cross-phase dependency violations.
+ */
+export declare function validateAndSortPlugins(plugins: BunshotPlugin[]): BunshotPlugin[];
+/**
+ * Run the setupMiddleware phase for all sorted plugins.
+ */
+export declare function runPluginMiddleware(sortedPlugins: BunshotPlugin[], app: OpenAPIHono<AppEnv>, frameworkConfig: FrameworkConfig, bus: BunshotEventBus): Promise<void>;
+/**
+ * Run the setupRoutes phase for all sorted plugins.
+ */
+export declare function runPluginRoutes(sortedPlugins: BunshotPlugin[], app: OpenAPIHono<AppEnv>, frameworkConfig: FrameworkConfig, bus: BunshotEventBus): Promise<void>;
+/**
+ * Run the setupPost phase for all sorted plugins.
+ */
+export declare function runPluginPost(sortedPlugins: BunshotPlugin[], app: OpenAPIHono<AppEnv>, frameworkConfig: FrameworkConfig, bus: BunshotEventBus): Promise<void>;

package/dist/src/framework/runPluginLifecycle.js

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// Topological sort
+// ---------------------------------------------------------------------------
+function topologicalSort(plugins) {
+    const nameToPlugin = new Map(plugins.map(p => [p.name, p]));
+    const completed = new Set();
+    const inProgress = new Set();
+    const result = [];
+    function visit(name, path) {
+        if (completed.has(name))
+            return;
+        if (inProgress.has(name)) {
+            const cycleStart = path.indexOf(name);
+            const cycle = [...path.slice(cycleStart), name];
+            throw new Error(`[bunshot] Circular plugin dependency detected: ${cycle.join(' → ')}`);
+        }
+        const plugin = nameToPlugin.get(name);
+        if (!plugin) {
+            throw new Error(`[bunshot] Plugin dependency "${name}" not found (required by "${path[path.length - 1] ?? 'root'}").`);
+        }
+        inProgress.add(name);
+        for (const dep of plugin.dependencies ?? []) {
+            visit(dep, [...path, name]);
+        }
+        inProgress.delete(name);
+        completed.add(name);
+        result.push(plugin);
+    }
+    for (const plugin of plugins) {
+        visit(plugin.name, []);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Plugin validation
+// ---------------------------------------------------------------------------
+function getEarliestPhase(p) {
+    if (p.setupMiddleware)
+        return 0;
+    if (p.setupRoutes)
+        return 1;
+    if (p.setupPost)
+        return 2;
+    return 3; // setup-only (standalone)
+}
+const PHASE_NAMES = ['setupMiddleware', 'setupRoutes', 'setupPost', 'setup-only (standalone)'];
+/**
+ * Validate the plugin dependency graph and return plugins in topological order.
+ * Throws on circular dependencies, missing dependencies, lifecycle-less plugins,
+ * and cross-phase dependency violations.
+ */
+export function validateAndSortPlugins(plugins) {
+    if (plugins.length === 0)
+        return [];
+    const pluginNames = new Set(plugins.map(p => p.name));
+    const nameToPlugin = new Map(plugins.map(p => [p.name, p]));
+    for (const plugin of plugins) {
+        // Validate all declared dependencies are present
+        for (const dep of plugin.dependencies ?? []) {
+            if (!pluginNames.has(dep)) {
+                throw new Error(`[bunshot] Plugin "${plugin.name}" declares dependency "${dep}" but it is not in the plugins array.`);
+            }
+        }
+        // Each plugin must define at least one lifecycle method
+        if (!plugin.setupMiddleware && !plugin.setupRoutes && !plugin.setupPost && !plugin.setup) {
+            throw new Error(`[bunshot] Plugin "${plugin.name}" must define at least one of: setupMiddleware, setupRoutes, setupPost, or setup.`);
+        }
+        // setup()-only plugins are standalone-only — the framework skips them
+        if (!plugin.setupMiddleware && !plugin.setupRoutes && !plugin.setupPost && plugin.setup) {
+            console.info(`[bunshot] Plugin "${plugin.name}" defines only setup() — standalone-only, skipped by framework. Use setupMiddleware(), setupRoutes(), or setupPost() for framework integration.`);
+        }
+    }
+    // Cross-phase dependency validation
+    for (const plugin of plugins) {
+        const pluginPhase = getEarliestPhase(plugin);
+        if (pluginPhase === 3)
+            continue; // standalone-only: no framework phase to validate
+        for (const depName of plugin.dependencies ?? []) {
+            const dep = nameToPlugin.get(depName);
+            const depPhase = getEarliestPhase(dep);
+            if (depPhase > pluginPhase) {
+                throw new Error(`[bunshot] Plugin "${plugin.name}" (earliest phase: ${PHASE_NAMES[pluginPhase]}) ` +
+                    `depends on "${depName}" (earliest phase: ${PHASE_NAMES[depPhase]}). ` +
+                    `A dependency's earliest phase must be ≤ the dependent's earliest phase.`);
+            }
+        }
+    }
+    // Topological sort — only include plugins that participate in at least one framework phase
+    const frameworkPlugins = plugins.filter(p => p.setupMiddleware || p.setupRoutes || p.setupPost);
+    return topologicalSort(frameworkPlugins);
+}
+// ---------------------------------------------------------------------------
+// Plugin lifecycle execution
+// ---------------------------------------------------------------------------
+/**
+ * Run the setupMiddleware phase for all sorted plugins.
+ */
+export async function runPluginMiddleware(sortedPlugins, app, frameworkConfig, bus) {
+    for (const plugin of sortedPlugins) {
+        if (plugin.setupMiddleware)
+            await plugin.setupMiddleware(app, frameworkConfig, bus);
+    }
+}
+/**
+ * Run the setupRoutes phase for all sorted plugins.
+ */
+export async function runPluginRoutes(sortedPlugins, app, frameworkConfig, bus) {
+    for (const plugin of sortedPlugins) {
+        if (plugin.setupRoutes)
+            await plugin.setupRoutes(app, frameworkConfig, bus);
+    }
+}
+/**
+ * Run the setupPost phase for all sorted plugins.
+ */
+export async function runPluginPost(sortedPlugins, app, frameworkConfig, bus) {
+    for (const plugin of sortedPlugins) {
+        if (plugin.setupPost)
+            await plugin.setupPost(app, frameworkConfig, bus);
+    }
+}

package/dist/src/framework/secrets/frameworkSecretSchema.d.ts

@@ -0,0 +1,58 @@
+export declare const frameworkSecretSchema: {
+    readonly jwtSecret: {
+        readonly path: "JWT_SECRET";
+        readonly required: false;
+    };
+    readonly bearerToken: {
+        readonly path: "BEARER_TOKEN";
+        readonly required: false;
+    };
+    readonly dataEncryptionKey: {
+        readonly path: "BUNSHOT_DATA_ENCRYPTION_KEY";
+        readonly required: false;
+    };
+    readonly redisHost: {
+        readonly path: "REDIS_HOST";
+        readonly required: false;
+    };
+    readonly redisUser: {
+        readonly path: "REDIS_USER";
+        readonly required: false;
+    };
+    readonly redisPassword: {
+        readonly path: "REDIS_PASSWORD";
+        readonly required: false;
+    };
+    readonly mongoUser: {
+        readonly path: "MONGO_USER";
+        readonly required: false;
+    };
+    readonly mongoPassword: {
+        readonly path: "MONGO_PASSWORD";
+        readonly required: false;
+    };
+    readonly mongoHost: {
+        readonly path: "MONGO_HOST";
+        readonly required: false;
+    };
+    readonly mongoDb: {
+        readonly path: "MONGO_DB";
+        readonly required: false;
+    };
+    readonly mongoAuthUser: {
+        readonly path: "MONGO_AUTH_USER";
+        readonly required: false;
+    };
+    readonly mongoAuthPassword: {
+        readonly path: "MONGO_AUTH_PASSWORD";
+        readonly required: false;
+    };
+    readonly mongoAuthHost: {
+        readonly path: "MONGO_AUTH_HOST";
+        readonly required: false;
+    };
+    readonly mongoAuthDb: {
+        readonly path: "MONGO_AUTH_DB";
+        readonly required: false;
+    };
+};

package/dist/src/framework/secrets/frameworkSecretSchema.js

@@ -0,0 +1,20 @@
+export const frameworkSecretSchema = {
+    // Signing & encryption
+    jwtSecret: { path: 'JWT_SECRET', required: false },
+    bearerToken: { path: 'BEARER_TOKEN', required: false },
+    dataEncryptionKey: { path: 'BUNSHOT_DATA_ENCRYPTION_KEY', required: false },
+    // Redis
+    redisHost: { path: 'REDIS_HOST', required: false },
+    redisUser: { path: 'REDIS_USER', required: false },
+    redisPassword: { path: 'REDIS_PASSWORD', required: false },
+    // Mongo (primary / single mode)
+    mongoUser: { path: 'MONGO_USER', required: false },
+    mongoPassword: { path: 'MONGO_PASSWORD', required: false },
+    mongoHost: { path: 'MONGO_HOST', required: false },
+    mongoDb: { path: 'MONGO_DB', required: false },
+    // Mongo (auth — separate mode)
+    mongoAuthUser: { path: 'MONGO_AUTH_USER', required: false },
+    mongoAuthPassword: { path: 'MONGO_AUTH_PASSWORD', required: false },
+    mongoAuthHost: { path: 'MONGO_AUTH_HOST', required: false },
+    mongoAuthDb: { path: 'MONGO_AUTH_DB', required: false },
+};

package/dist/src/framework/secrets/index.d.ts

@@ -0,0 +1,9 @@
+export { resolveSecrets } from './resolveSecrets';
+export { frameworkSecretSchema } from './frameworkSecretSchema';
+export { resolveSecretBundle, resolveSecretRepo_fromInput, resolveSecretRepo, secretRepositoryFactories, } from './resolveSecretBundle';
+export type { SecretStoreConfig, SecretRepositoryFactories, SecretStoreInput, SecretStoreInfra, SecretRepoFactories, ResolvedSecretBundle, RegisteredSecretRepository, EnvSecretStoreConfig, SsmSecretStoreConfig, FileSecretStoreConfig, } from './resolveSecretBundle';
+export { createEnvSecretRepository } from './providers/envProvider';
+export { createSsmSecretRepository } from './providers/ssmProvider';
+export type { SsmProviderOptions } from './providers/ssmProvider';
+export { createFileSecretRepository } from './providers/fileProvider';
+export type { FileProviderOptions } from './providers/fileProvider';

package/dist/src/framework/secrets/index.js

@@ -0,0 +1,7 @@
+// Barrel export for framework secrets module
+export { resolveSecrets } from './resolveSecrets';
+export { frameworkSecretSchema } from './frameworkSecretSchema';
+export { resolveSecretBundle, resolveSecretRepo_fromInput, resolveSecretRepo, secretRepositoryFactories, } from './resolveSecretBundle';
+export { createEnvSecretRepository } from './providers/envProvider';
+export { createSsmSecretRepository } from './providers/ssmProvider';
+export { createFileSecretRepository } from './providers/fileProvider';

package/dist/src/framework/secrets/providers/envProvider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Environment variable secret repository.
+ *
+ * Reads secrets from process.env. Covers:
+ * - Local .env files (loaded by Bun automatically)
+ * - GitHub Actions secrets (injected as env vars in CI)
+ * - Any platform that maps secrets to environment variables
+ *
+ * Factory pattern: closure-owned prefix, no module-level state.
+ */
+import type { ISecretRepository } from '../../../../packages/bunshot-core/src/index.js';
+export declare function createEnvSecretRepository(opts?: {
+    /** Optional prefix stripped from env var names (e.g., 'MYAPP_') */
+    prefix?: string;
+}): ISecretRepository;

package/dist/src/framework/secrets/providers/envProvider.js

@@ -0,0 +1,18 @@
+export function createEnvSecretRepository(opts) {
+    const prefix = opts?.prefix ?? '';
+    return {
+        name: 'env',
+        async get(key) {
+            return process.env[prefix + key] ?? null;
+        },
+        async getMany(keys) {
+            const result = new Map();
+            for (const key of keys) {
+                const val = process.env[prefix + key];
+                if (val !== undefined)
+                    result.set(key, val);
+            }
+            return result;
+        },
+    };
+}

package/dist/src/framework/secrets/providers/fileProvider.d.ts

@@ -0,0 +1,8 @@
+import type { ISecretRepository } from '../../../../packages/bunshot-core/src/index.js';
+export interface FileProviderOptions {
+    /** Directory containing secret files (e.g., '/run/secrets') */
+    directory: string;
+    /** File extension to strip when deriving key names. Default: none. */
+    extension?: string;
+}
+export declare function createFileSecretRepository(opts: FileProviderOptions): ISecretRepository;

package/dist/src/framework/secrets/providers/fileProvider.js

@@ -0,0 +1,82 @@
+/**
+ * File-based secret repository.
+ *
+ * Reads secrets from individual files in a directory. Each file name is the
+ * secret key, file content is the secret value (trailing newline trimmed).
+ *
+ * Use cases:
+ * - Docker Swarm secrets mounted at /run/secrets/
+ * - Kubernetes mounted secret volumes
+ * - Any file-based secret injection
+ *
+ * Factory pattern: closure-owned cache + directory ref, no module-level state.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export function createFileSecretRepository(opts) {
+    const { directory, extension } = opts;
+    // Closure-owned cache — populated on initialize(), keyed by secret name
+    const cache = new Map();
+    let initialized = false;
+    function stripExtension(filename) {
+        if (extension && filename.endsWith(extension)) {
+            return filename.slice(0, -extension.length);
+        }
+        return filename;
+    }
+    async function readSecret(key) {
+        const filename = extension ? key + extension : key;
+        try {
+            const content = await readFile(join(directory, filename), 'utf-8');
+            return content.replace(/\n$/, '');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    return {
+        name: 'file',
+        async initialize() {
+            try {
+                const files = await readdir(directory);
+                for (const file of files) {
+                    const key = stripExtension(file);
+                    const content = await readFile(join(directory, file), 'utf-8');
+                    cache.set(key, content.replace(/\n$/, ''));
+                }
+                initialized = true;
+            }
+            catch (err) {
+                if (err.code === 'ENOENT') {
+                    throw new Error(`[secrets/file] Directory not found: ${directory}`);
+                }
+                throw err;
+            }
+        },
+        async get(key) {
+            if (initialized)
+                return cache.get(key) ?? null;
+            return readSecret(key);
+        },
+        async getMany(keys) {
+            const result = new Map();
+            for (const key of keys) {
+                const value = initialized ? (cache.get(key) ?? null) : await readSecret(key);
+                if (value !== null)
+                    result.set(key, value);
+            }
+            return result;
+        },
+        async refresh() {
+            cache.clear();
+            initialized = false;
+            await this.initialize?.();
+        },
+        async destroy() {
+            cache.clear();
+            initialized = false;
+        },
+    };
+}

package/dist/src/framework/secrets/providers/ssmProvider.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AWS Systems Manager Parameter Store secret repository.
+ *
+ * Batch-loads parameters by path prefix on initialize(), caches locally.
+ * Lazy SDK import — @aws-sdk/client-ssm is only loaded when this repository is used.
+ *
+ * Factory pattern: closure-owned cache + client, no module-level state.
+ */
+import type { ISecretRepository } from '../../../../packages/bunshot-core/src/index.js';
+export interface SsmProviderOptions {
+    /** SSM path prefix, e.g., '/myapp/prod/' — must end with '/' */
+    pathPrefix: string;
+    /** AWS region. Defaults to AWS_REGION env var or 'us-east-1'. */
+    region?: string;
+    /** Cache TTL in milliseconds. Default: 300_000 (5 min). */
+    cacheTtlMs?: number;
+    /** Whether to decrypt SecureString params. Default: true. */
+    withDecryption?: boolean;
+}
+export declare function createSsmSecretRepository(opts: SsmProviderOptions): ISecretRepository;