@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/packages/bunshot-core/src/pagination.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { registerSchema } from './createRoute';
+export function offsetParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const defaultOffset = defaults?.offset ?? 0;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1-${maxLimit}, default ${defaultLimit})`),
+        offset: z.string().optional().describe(`Number of items to skip (default ${defaultOffset})`),
+    });
+}
+export function parseOffsetParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const defaultOffset = defaults?.offset ?? 0;
+    const rawLimit = parseInt(raw.limit ?? '', 10);
+    const rawOffset = parseInt(raw.offset ?? '', 10);
+    const limit = isNaN(rawLimit) ? defaultLimit : Math.min(Math.max(rawLimit, 1), maxLimit);
+    const offset = isNaN(rawOffset) ? defaultOffset : Math.max(rawOffset, 0);
+    return { limit, offset };
+}
+export function paginatedResponse(itemSchema, name) {
+    const wrapper = z.object({
+        items: z.array(itemSchema),
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+    });
+    registerSchema(name, wrapper);
+    return wrapper;
+}
+export function cursorParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1-${maxLimit}, default ${defaultLimit})`),
+        cursor: z.string().optional().describe('Opaque pagination cursor from a previous response'),
+    });
+}
+export function parseCursorParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const rawLimit = parseInt(raw.limit ?? '', 10);
+    const limit = isNaN(rawLimit) ? defaultLimit : Math.min(Math.max(rawLimit, 1), maxLimit);
+    const cursor = raw.cursor || undefined;
+    return { limit, cursor };
+}
+export function cursorPaginatedResponse(itemSchema, name) {
+    const wrapper = z.object({
+        items: z.array(itemSchema),
+        nextCursor: z.string().optional(),
+    });
+    registerSchema(name, wrapper);
+    return wrapper;
+}

package/dist/packages/bunshot-core/src/permissions.d.ts

@@ -0,0 +1,64 @@
+export type SubjectType = 'user' | 'group' | 'service-account';
+export type GrantEffect = 'allow' | 'deny';
+export interface SubjectRef {
+    subjectId: string;
+    subjectType: SubjectType;
+}
+export interface PermissionGrant {
+    id: string;
+    subjectId: string;
+    subjectType: SubjectType;
+    tenantId: string | null;
+    resourceType: string | null;
+    resourceId: string | null;
+    roles: string[];
+    effect: GrantEffect;
+    grantedBy: string;
+    grantedAt: Date;
+    reason?: string;
+    expiresAt?: Date;
+    revokedBy?: string;
+    revokedAt?: Date;
+}
+export interface TestablePermissionsAdapter extends PermissionsAdapter {
+    clear(): Promise<void>;
+}
+export interface EvaluationScope {
+    tenantId?: string;
+    resourceType?: string;
+    resourceId?: string;
+}
+export interface PermissionsAdapter {
+    createGrant(grant: Omit<PermissionGrant, 'id' | 'grantedAt'>): Promise<string>;
+    revokeGrant(grantId: string, revokedBy: string, tenantScope?: string): Promise<boolean>;
+    getGrantsForSubject(subjectId: string, subjectType?: SubjectType, scope?: Partial<Pick<PermissionGrant, 'tenantId' | 'resourceType' | 'resourceId'>>): Promise<PermissionGrant[]>;
+    getEffectiveGrantsForSubject(subjectId: string, subjectType: SubjectType, scope?: EvaluationScope): Promise<PermissionGrant[]>;
+    listGrantHistory(subjectId: string, subjectType: SubjectType): Promise<PermissionGrant[]>;
+    listGrantsOnResource(resourceType: string, resourceId: string, tenantId?: string | null): Promise<PermissionGrant[]>;
+    deleteAllGrantsForSubject(subject: SubjectRef): Promise<void>;
+}
+export interface ResourceTypeDefinition {
+    resourceType: string;
+    actions: string[];
+    roles: {
+        [roleName: string]: string[];
+    };
+}
+export interface PermissionRegistry {
+    register(definition: ResourceTypeDefinition): void;
+    getActionsForRole(resourceType: string, role: string): string[];
+    getDefinition(resourceType: string): ResourceTypeDefinition | null;
+    listResourceTypes(): ResourceTypeDefinition[];
+}
+export interface GroupResolver {
+    getGroupsForUser(userId: string, tenantId: string | null): Promise<string[]>;
+}
+export interface PermissionEvaluator {
+    can(subject: SubjectRef, action: string, scope?: {
+        tenantId?: string;
+        resourceType?: string;
+        resourceId?: string;
+    }): Promise<boolean>;
+}
+export declare const SUPER_ADMIN_ROLE = "super-admin";
+export declare function validateGrant(grant: Omit<PermissionGrant, 'id' | 'grantedAt'>): void;

package/dist/packages/bunshot-core/src/permissions.js

@@ -0,0 +1,27 @@
+// ── Models ──────────────────────────────────────────────────────────────────
+// ── Constants ───────────────────────────────────────────────────────────────
+export const SUPER_ADMIN_ROLE = 'super-admin';
+// ── Validation ──────────────────────────────────────────────────────────────
+export function validateGrant(grant) {
+    if (grant.resourceId !== null && grant.resourceType === null) {
+        throw new Error('resourceId requires resourceType to be set');
+    }
+    if (!grant.roles || grant.roles.length === 0) {
+        throw new Error('grant must have at least one role');
+    }
+    if (grant.effect !== 'allow' && grant.effect !== 'deny') {
+        throw new Error("effect must be 'allow' or 'deny'");
+    }
+    if (grant.expiresAt !== undefined) {
+        if (!(grant.expiresAt instanceof Date)) {
+            throw new Error('expiresAt must be a Date object');
+        }
+        if (grant.expiresAt < new Date()) {
+            throw new Error('expiresAt must be in the future');
+        }
+    }
+    const validSubjectTypes = ['user', 'group', 'service-account'];
+    if (!validSubjectTypes.includes(grant.subjectType)) {
+        throw new Error('invalid subjectType');
+    }
+}

package/dist/packages/bunshot-core/src/plugin.d.ts

@@ -0,0 +1,44 @@
+import type { Hono } from 'hono';
+import type { BunshotFrameworkConfig } from './context/frameworkConfig';
+import type { BunshotEventBus } from './eventBus';
+export interface BunshotPlugin {
+    name: string;
+    dependencies?: string[];
+    /**
+     * Called after framework middleware (requestId, metrics, logger, secureHeaders, cors, bot,
+     * rateLimit) and before tenant/custom middleware. Use this for request middleware that must
+     * run early in the chain (e.g. auth, CSRF, MFA enforcement).
+     */
+    setupMiddleware?(app: Hono<any>, config: BunshotFrameworkConfig, bus: BunshotEventBus): void | Promise<void>;
+    /**
+     * Called after tenant and custom middleware, before framework route mounting and user route
+     * discovery. Use this to mount plugin routes so they receive tenant context.
+     *
+     * Auth routes receive tenant context because tenant middleware runs before this phase.
+     */
+    setupRoutes?(app: Hono<any>, config: BunshotFrameworkConfig, bus: BunshotEventBus): void | Promise<void>;
+    /**
+     * Called after all routes, OpenAPI docs, and error handlers are registered.
+     * Use this for post-assembly inspection, metrics registration, or other post-startup work.
+     *
+     * NOT for registering routes or request middleware — routes registered here are invisible
+     * to OpenAPI and unreachable by app.onError.
+     */
+    setupPost?(app: Hono<any>, config: BunshotFrameworkConfig, bus: BunshotEventBus): void | Promise<void>;
+    /**
+     * Standalone convenience — the framework NEVER calls this method.
+     *
+     * Plain Hono apps (without the full Bunshot framework orchestrator) call `setup()` directly
+     * to register middleware and routes in one call. A typical implementation calls
+     * `setupMiddleware` then `setupRoutes` in sequence.
+     *
+     * Define `setupMiddleware`/`setupRoutes`/`setupPost` for framework integration.
+     * Define `setup` for standalone usage. Both can coexist without double-execution risk —
+     * the framework calls only the phase methods, never `setup()`.
+     */
+    setup?(app: Hono<any>, config: BunshotFrameworkConfig, bus: BunshotEventBus): void | Promise<void>;
+    teardown?(): void | Promise<void>;
+}
+export interface StandalonePlugin extends BunshotPlugin {
+    setup(app: Hono<any>, config: BunshotFrameworkConfig, bus: BunshotEventBus): void | Promise<void>;
+}

package/dist/packages/bunshot-core/src/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/rateLimit.d.ts

@@ -0,0 +1,5 @@
+import { type ContextCarrier } from './context/contextAccess';
+import type { FingerprintBuilder, RateLimitAdapter } from './coreContracts';
+export type { FingerprintBuilder, RateLimitAdapter };
+export declare function getRateLimitAdapter(input: ContextCarrier): RateLimitAdapter;
+export declare function getFingerprintBuilder(input: ContextCarrier): FingerprintBuilder;

package/dist/packages/bunshot-core/src/rateLimit.js

@@ -0,0 +1,18 @@
+import { resolveContext } from './context/contextAccess';
+// ---------------------------------------------------------------------------
+// RateLimitAdapter + FingerprintBuilder -- rate limiting contracts.
+// ---------------------------------------------------------------------------
+export function getRateLimitAdapter(input) {
+    const adapter = resolveContext(input).rateLimitAdapter;
+    if (adapter === null) {
+        throw new Error('No RateLimitAdapter registered for this app instance.');
+    }
+    return adapter;
+}
+export function getFingerprintBuilder(input) {
+    const builder = resolveContext(input).fingerprintBuilder;
+    if (builder === null) {
+        throw new Error('No FingerprintBuilder registered for this app instance.');
+    }
+    return builder;
+}

package/dist/packages/bunshot-core/src/redis.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical Redis client interface used across all bunshot packages.
+ * Concrete implementations (ioredis, etc.) satisfy this contract.
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    mget(...keys: string[]): Promise<Array<string | null>>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    setex(key: string, seconds: number, value: string): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    zadd(key: string, score: number, member: string): Promise<number>;
+    zrem(key: string, ...members: string[]): Promise<number>;
+    lpush(key: string, value: string): Promise<number>;
+    ltrim(key: string, start: number, stop: number): Promise<string>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    getdel?(key: string): Promise<string | null>;
+    eval(script: string, numkeys: number, ...args: unknown[]): Promise<unknown>;
+}

package/dist/packages/bunshot-core/src/redis.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/routeAuth.d.ts

@@ -0,0 +1,5 @@
+import { type ContextCarrier } from './context/contextAccess';
+import type { RouteAuthRegistry } from './coreContracts';
+export type { RouteAuthRegistry };
+export declare function getRouteAuth(input: ContextCarrier): RouteAuthRegistry;
+export declare function getRouteAuthOrNull(input: ContextCarrier): RouteAuthRegistry | null;

package/dist/packages/bunshot-core/src/routeAuth.js

@@ -0,0 +1,11 @@
+import { resolveContext } from './context/contextAccess';
+export function getRouteAuth(input) {
+    const registry = resolveContext(input).routeAuth;
+    if (registry === null) {
+        throw new Error('No RouteAuthRegistry registered for this app instance. The auth plugin must be registered when using auth: "userAuth" in jobs, metrics, or uploads config.');
+    }
+    return registry;
+}
+export function getRouteAuthOrNull(input) {
+    return resolveContext(input).routeAuth;
+}

package/dist/packages/bunshot-core/src/routeOverrides.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Typed route key: "METHOD /path" (method always uppercased).
+ * Constructed exclusively via routeKey() — never hand-typed — to prevent drift.
+ */
+export type RouteKey<M extends string, P extends string> = `${Uppercase<M>} ${P}`;
+/**
+ * Constructs a typed route key from method and path.
+ *
+ * Use this to define ROUTES constants and nowhere else:
+ *   export const MY_ROUTES = [routeKey('GET', '/items'), routeKey('POST', '/items')] as const;
+ *
+ * shouldMountRoute() calls routeKey() internally with the same arguments, so
+ * the constant values and the runtime check are always identical.
+ */
+export declare function routeKey<M extends string, P extends string>(method: M, path: P): RouteKey<M, P>;
+/**
+ * Returns true if the route should be mounted (i.e. NOT in disabledRoutes).
+ * Pass the same method/path you used when defining the ROUTES constant.
+ *
+ * @example
+ * if (shouldMountRoute('GET', '/items', config.disableRoutes))
+ *   router.openapi(listRoute, handler);
+ */
+export declare function shouldMountRoute(method: string, path: string, disabledRoutes?: readonly string[]): boolean;

package/dist/packages/bunshot-core/src/routeOverrides.js

@@ -0,0 +1,25 @@
+/**
+ * Constructs a typed route key from method and path.
+ *
+ * Use this to define ROUTES constants and nowhere else:
+ *   export const MY_ROUTES = [routeKey('GET', '/items'), routeKey('POST', '/items')] as const;
+ *
+ * shouldMountRoute() calls routeKey() internally with the same arguments, so
+ * the constant values and the runtime check are always identical.
+ */
+export function routeKey(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+}
+/**
+ * Returns true if the route should be mounted (i.e. NOT in disabledRoutes).
+ * Pass the same method/path you used when defining the ROUTES constant.
+ *
+ * @example
+ * if (shouldMountRoute('GET', '/items', config.disableRoutes))
+ *   router.openapi(listRoute, handler);
+ */
+export function shouldMountRoute(method, path, disabledRoutes) {
+    if (!disabledRoutes?.length)
+        return true;
+    return !disabledRoutes.includes(routeKey(method, path));
+}

package/dist/packages/bunshot-core/src/routerAdapter.d.ts

@@ -0,0 +1,6 @@
+import type { BunshotEventBus } from './eventBus';
+export interface RouterAdapterOptions {
+    default: BunshotEventBus;
+    namespaces?: Record<string, BunshotEventBus>;
+}
+export declare function createRouterAdapter(opts: RouterAdapterOptions): BunshotEventBus;

package/dist/packages/bunshot-core/src/routerAdapter.js

@@ -0,0 +1,56 @@
+function resolveAdapter(event, opts) {
+    if (!opts.namespaces)
+        return opts.default;
+    // Longest prefix wins
+    let bestMatch = '';
+    let bestAdapter;
+    for (const [prefix, adapter] of Object.entries(opts.namespaces)) {
+        if (event.startsWith(prefix) && prefix.length > bestMatch.length) {
+            bestMatch = prefix;
+            bestAdapter = adapter;
+        }
+    }
+    return bestAdapter ?? opts.default;
+}
+export function createRouterAdapter(opts) {
+    function allAdapters() {
+        const seen = new Set();
+        seen.add(opts.default);
+        if (opts.namespaces) {
+            for (const adapter of Object.values(opts.namespaces)) {
+                seen.add(adapter);
+            }
+        }
+        return [...seen];
+    }
+    return {
+        emit(event, payload) {
+            resolveAdapter(event, opts).emit(event, payload);
+        },
+        on(event, listener, subscriptionOpts) {
+            resolveAdapter(event, opts).on(event, listener, subscriptionOpts);
+        },
+        off(event, listener) {
+            resolveAdapter(event, opts).off(event, listener);
+        },
+        async shutdown() {
+            await Promise.all(allAdapters().map(adapter => adapter.shutdown?.()));
+        },
+        get clientSafeKeys() {
+            const keys = new Set();
+            for (const adapter of allAdapters()) {
+                for (const key of adapter.clientSafeKeys)
+                    keys.add(key);
+            }
+            return keys;
+        },
+        registerClientSafeEvents(keys) {
+            for (const adapter of allAdapters()) {
+                adapter.registerClientSafeEvents(keys);
+            }
+        },
+        ensureClientSafeEventKey(key, source) {
+            return resolveAdapter(key, opts).ensureClientSafeEventKey(key, source);
+        },
+    };
+}

package/dist/packages/bunshot-core/src/secrets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Secret repository contracts — read-only abstraction for resolving
+ * credentials, API keys, and signing secrets from any backing store.
+ *
+ * Resolved at startup BEFORE database connections are established.
+ * Implementations must be self-contained (no DB dependencies).
+ */
+export type SecretStoreType = 'env' | 'ssm' | 'file';
+/**
+ * Read-only secret repository. Resolved at startup before any DB connections.
+ * Implementations must be self-contained (no DB dependencies).
+ */
+export interface ISecretRepository {
+    readonly name: string;
+    /** Get a single secret by path/key. Returns null if not found. */
+    get(key: string): Promise<string | null>;
+    /** Get multiple secrets by key list. */
+    getMany(keys: string[]): Promise<ReadonlyMap<string, string>>;
+    /**
+     * Eagerly load all secrets (called once at startup).
+     * Implementations that support batch loading (SSM GetParametersByPath)
+     * should prefetch here to avoid N+1 latency.
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Refresh cached secrets from the backing store.
+     * Called on rotation events or periodic refresh. No-op for env provider.
+     */
+    refresh?(): Promise<void>;
+    /** Release resources (close connections, clear caches). */
+    destroy?(): Promise<void>;
+}
+export interface SecretDefinition {
+    /** The path/key in the secret store (e.g., '/app/prod/db/password' or 'MONGO_PASSWORD') */
+    path: string;
+    /** Whether startup should fail if this secret is missing. Default: true */
+    required?: boolean;
+    /** Default value when not found and not required. */
+    default?: string;
+}
+export type SecretSchema = Record<string, SecretDefinition>;
+/**
+ * Resolved secrets — keys from the schema, values are the secret strings.
+ * Returned as a frozen plain object for direct property access.
+ */
+export type ResolvedSecrets<S extends SecretSchema> = {
+    readonly [K in keyof S]: string;
+};

package/dist/packages/bunshot-core/src/secrets.js

@@ -0,0 +1,8 @@
+/**
+ * Secret repository contracts — read-only abstraction for resolving
+ * credentials, API keys, and signing secrets from any backing store.
+ *
+ * Resolved at startup BEFORE database connections are established.
+ * Implementations must be self-contained (no DB dependencies).
+ */
+export {};

package/dist/packages/bunshot-core/src/signing.d.ts

@@ -0,0 +1,41 @@
+export interface SigningConfig {
+    /**
+     * HMAC secret. Defaults to JWT_SECRET env var if omitted.
+     * Pass string[] to support key rotation - first element signs, all elements verify.
+     */
+    secret?: string | string[];
+    /** Sign/verify cookie values set via exported helpers. Default: false. */
+    cookies?: boolean;
+    /** Sign pagination cursor tokens to prevent client tampering. Default: false. */
+    cursors?: boolean;
+    /** HMAC-based stateless presigned URLs (no DB lookup). Default: false. */
+    presignedUrls?: boolean | {
+        defaultExpiry?: number;
+    };
+    /** Require clients to HMAC-sign requests (method+path+timestamp+body). Default: false. */
+    requestSigning?: boolean | {
+        tolerance?: number;
+        header?: string;
+        timestampHeader?: string;
+    };
+    /** Hash idempotency keys before storage. Default: false. */
+    idempotencyKeys?: boolean;
+    /**
+     * Bind sessions to a client fingerprint so a stolen JWT+session pair cannot
+     * be replayed from a different browser or IP.
+     *
+     * - `true` — bind to IP + User-Agent (strictest; may false-positive on mobile
+     *   users or deployments that terminate TLS at a CDN/proxy that rewrites IPs).
+     * - `{ fields: ['ua'], onMismatch: 'log-only' }` — UA-only binding in
+     *   observation mode; safe starting point for mobile or CDN-heavy deployments.
+     * - `{ fields: ['ip', 'ua'], onMismatch: 'reject' }` — hard reject on mismatch
+     *   (most aggressive; returns 401 instead of silently unauthenticating).
+     *
+     * **Not enabled by default.** Production deployments are warned at startup when
+     * this is absent. Explicitly set to `false` to silence the warning.
+     */
+    sessionBinding?: boolean | {
+        fields?: Array<'ip' | 'ua' | 'accept-language'>;
+        onMismatch?: 'unauthenticate' | 'reject' | 'log-only';
+    };
+}

package/dist/packages/bunshot-core/src/signing.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/sse.d.ts

@@ -0,0 +1,36 @@
+import type { ClientSafeEventKey } from './eventBus';
+/**
+ * Generic client data attached to each SSE connection.
+ * Same pattern as SocketData<T> in ws/index.ts.
+ */
+export type SseClientData<T extends object = object> = {
+    id: string;
+    userId: string | null;
+    endpoint: string;
+} & T;
+/**
+ * Per-client, per-event filter for SSE fanout.
+ * Return false to suppress delivery to this client.
+ */
+export type SseFilter<T extends object = object> = (client: SseClientData<T>, event: ClientSafeEventKey, payload: unknown) => boolean | Promise<boolean>;
+/**
+ * Configuration for a single SSE endpoint.
+ * Used in CreateServerConfig.sse.endpoints.
+ */
+export interface SseEndpointConfig<T extends object = object> {
+    /** Client-safe event keys this endpoint forwards. */
+    events: ClientSafeEventKey[];
+    /**
+     * Auth hook. Return SseClientData<T> to accept. Return a Response to reject.
+     * Default: createSseUpgradeHandler(endpoint) — resolves userId from cookie/token,
+     * returns userId: null on auth failure (permissive, mirrors WS default).
+     */
+    upgrade?: (req: Request) => Promise<SseClientData<T> | Response>;
+    /**
+     * Per-client, per-event filter. Return false to suppress.
+     * Called async per fanout call — keep it fast.
+     */
+    filter?: SseFilter<T>;
+    /** Keep-alive heartbeat interval ms. false = disabled. Default: 30_000 */
+    heartbeat?: number | false;
+}

package/dist/packages/bunshot-core/src/sse.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/storageAdapter.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/storeInfra.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical store infrastructure contract shared across all bunshot packages.
+ *
+ * Plugin authors import these types from `@lastshotlabs/bunshot-core` to declare
+ * repository factories without depending on framework or auth internals.
+ *
+ * The pattern:
+ *   1. Declare `RepoFactories<YourRepo>` with one factory per StoreType
+ *   2. Call `resolveRepo(factories, storeType, infra)` at startup
+ *   3. The framework provides `StoreInfra` — your factory receives it
+ */
+import type { Database } from 'bun:sqlite';
+import type { Connection } from 'mongoose';
+import type { Pool } from 'pg';
+import type { RedisLike } from './redis';
+import type { StoreType } from './storeType';
+/**
+ * Postgres bundle passed through StoreInfra.
+ * The concrete implementation (`DrizzlePostgresDb`) lives in
+ * @lastshotlabs/bunshot-postgres and satisfies this interface.
+ * `db` is typed as `unknown` here to avoid pulling drizzle-orm into core;
+ * import from bunshot-postgres for the full `NodePgDatabase` type.
+ */
+export interface PostgresBundle {
+    readonly pool: Pool;
+    readonly db: unknown;
+}
+export interface StoreInfra {
+    readonly appName: string;
+    readonly getRedis: () => RedisLike;
+    readonly getMongo: () => {
+        conn: Connection;
+        mg: typeof import('mongoose');
+    };
+    readonly getSqliteDb: () => Database;
+    readonly getPostgres: () => PostgresBundle;
+}
+export type RepoFactories<T> = Record<StoreType, (infra: StoreInfra) => T>;
+export declare function resolveRepo<T>(factories: RepoFactories<T>, storeType: StoreType, infra: StoreInfra): T;
+/**
+ * Like resolveRepo but supports factories that return a Promise.
+ * Use this when the selected adapter requires async initialisation (e.g. migrations).
+ */
+export declare function resolveRepoAsync<T>(factories: Record<StoreType, (infra: StoreInfra) => T | Promise<T>>, storeType: StoreType, infra: StoreInfra): Promise<T>;

package/dist/packages/bunshot-core/src/storeInfra.js

@@ -0,0 +1,18 @@
+export function resolveRepo(factories, storeType, infra) {
+    const factory = factories[storeType];
+    if (!factory) {
+        throw new Error(`[bunshot] Unsupported store type: ${storeType}`);
+    }
+    return factory(infra);
+}
+/**
+ * Like resolveRepo but supports factories that return a Promise.
+ * Use this when the selected adapter requires async initialisation (e.g. migrations).
+ */
+export async function resolveRepoAsync(factories, storeType, infra) {
+    const factory = factories[storeType];
+    if (!factory) {
+        throw new Error(`[bunshot] Unsupported store type: ${storeType}`);
+    }
+    return factory(infra);
+}

package/dist/packages/bunshot-core/src/storeType.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical store-type union shared across bunshot packages.
+ *
+ * Add new backing stores here — auth and framework both derive from this type,
+ * so a single addition keeps them in sync.
+ */
+export type StoreType = 'redis' | 'mongo' | 'sqlite' | 'memory' | 'postgres';

package/dist/packages/bunshot-core/src/storeType.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/testing.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/testing.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/uploadRegistry.d.ts

@@ -0,0 +1,23 @@
+export interface UploadRecord {
+    key: string;
+    ownerUserId?: string;
+    tenantId?: string;
+    mimeType?: string;
+    bucket?: string;
+    createdAt: number;
+}
+/**
+ * UploadRegistryRepository — storage contract for upload ownership tracking.
+ *
+ * Implementations store upload metadata keyed by the storage key.
+ * Used to verify ownership and tenancy when users request presigned
+ * download URLs or delete operations.
+ */
+export interface UploadRegistryRepository {
+    /** Store a new upload record. Keyed by record.key. */
+    register(record: UploadRecord): Promise<void>;
+    /** Retrieve an upload record by key. Returns null if not found. */
+    get(key: string): Promise<UploadRecord | null>;
+    /** Delete an upload record by key. Returns true if it existed. */
+    delete(key: string): Promise<boolean>;
+}

package/dist/packages/bunshot-core/src/uploadRegistry.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Upload Registry — repository contract and types
+// ---------------------------------------------------------------------------
+export {};