@lastshotlabs/bunshot 0.0.20 → 0.0.25

package/dist/lib/context.d.ts

@@ -1,12 +1,30 @@
-import { OpenAPIHono } from "@hono/zod-openapi";
+import { OpenAPIHono, type Hook } from "@hono/zod-openapi";
+import type { ZodIssue } from "zod";
+import type { UploadResult } from "./storageAdapter";
+export interface ValidationErrorDetail {
+    path: string;
+    message: string;
+}
+export interface DefaultValidationErrorBody {
+    error: string;
+    details: ValidationErrorDetail[];
+    requestId: string;
+}
+export type ValidationErrorFormatter = (issues: ZodIssue[], requestId: string) => unknown;
+export declare const defaultValidationErrorFormatter: ValidationErrorFormatter;
 export type AppVariables = {
+    requestId: string;
     authUserId: string | null;
     roles: string[] | null;
     sessionId: string | null;
     tenantId: string | null;
     tenantConfig: Record<string, unknown> | null;
+    validationErrorFormatter: ValidationErrorFormatter;
+    uploadResults: UploadResult[] | null;
+    uploadBucket: string | undefined;
 };
 export type AppEnv = {
     Variables: AppVariables;
 };
+export declare const defaultHook: Hook<any, AppEnv, any, any>;
 export declare const createRouter: () => OpenAPIHono<AppEnv, {}, "/">;

package/dist/lib/context.js

@@ -1,8 +1,22 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-const defaultHook = (result, c) => {
+export const defaultValidationErrorFormatter = (issues, requestId) => {
+    const error = issues.map((i) => i.message).join(", ");
+    const details = issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    return { error, details, requestId };
+};
+export const defaultHook = (result, c) => {
     if (!result.success) {
-        const message = result.error.issues.map((i) => i.message).join(", ");
-        return c.json({ error: message }, 400);
+        const requestId = c.get("requestId") ?? "unknown";
+        const formatter = c.get("validationErrorFormatter") ?? defaultValidationErrorFormatter;
+        try {
+            return c.json(formatter(result.error.issues, requestId), 400);
+        }
+        catch {
+            return c.json(defaultValidationErrorFormatter(result.error.issues, requestId), 400);
+        }
     }
 };
 export const createRouter = () => new OpenAPIHono({ defaultHook });

package/dist/lib/createRoute.d.ts

@@ -1,5 +1,27 @@
 import type { RouteConfig } from "@hono/zod-openapi";
 import type { ZodType } from "zod";
+/**
+ * Sets the active version prefix for schema name generation and creates a unique
+ * Symbol token for interleaving detection. Call before importing a version's route files.
+ */
+export declare function setVersionPrefix(version: string): void;
+/**
+ * Clears the active version prefix and token. Call after each version's route files
+ * have been fully imported.
+ */
+export declare function clearVersionPrefix(): void;
+/** Returns the current version token for assertion after import. */
+export declare function getVersionToken(): symbol | null;
+/**
+ * Drains and returns all tokens captured by createRoute() calls since the last drain.
+ * Used by versioned route discovery to detect interleaving.
+ */
+export declare function drainCapturedTokens(): (symbol | null)[];
+/**
+ * Asserts that all tokens in the array match the expected token.
+ * Throws a clear startup error if any mismatch is detected.
+ */
+export declare function assertCapturedTokens(tokens: (symbol | null)[], expectedToken: symbol | null): void;
 /**
  * Registers a Zod schema as a named entry in `components/schemas`.
  *
@@ -53,9 +75,13 @@ export declare const withSecurity: <T extends RouteConfig>(route: T, ...schemes:
  * OpenAPI components so they appear in `components/schemas` instead of being
  * inlined at every use site. Generated names follow the convention:
  *
- *   {Method}{PathSegments}Body         — request body
- *   {Method}{PathSegments}{StatusCode} — response body
+ *   {Version}{Method}{PathSegments}Request — request body (when versioning is active)
+ *   {Version}{Method}{PathSegments}{Status} — response body (when versioning is active)
  *
  * Schemas already named via `.openapi("Name")` are never overwritten.
+ *
+ * When `setVersionPrefix` has been called, the version prefix is prepended to all
+ * generated schema names and the current version token is captured for interleaving
+ * detection via `drainCapturedTokens()` / `assertCapturedTokens()`.
  */
 export declare const createRoute: <T extends RouteConfig>(config: T) => T;

package/dist/lib/createRoute.js

@@ -1,5 +1,50 @@
 import { createRoute as _createRoute } from "@hono/zod-openapi";
 import { getRefId, zodToOpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+// ---------------------------------------------------------------------------
+// Version prefix state — set once per version batch before importing route files
+// ---------------------------------------------------------------------------
+let _versionPrefix = "";
+let _versionToken = null;
+/** Tokens captured by createRoute() calls since the last drainCapturedTokens() call. */
+const _capturedTokens = [];
+/**
+ * Sets the active version prefix for schema name generation and creates a unique
+ * Symbol token for interleaving detection. Call before importing a version's route files.
+ */
+export function setVersionPrefix(version) {
+    _versionPrefix = version.charAt(0).toUpperCase() + version.slice(1);
+    _versionToken = Symbol(version);
+}
+/**
+ * Clears the active version prefix and token. Call after each version's route files
+ * have been fully imported.
+ */
+export function clearVersionPrefix() {
+    _versionPrefix = "";
+    _versionToken = null;
+}
+/** Returns the current version token for assertion after import. */
+export function getVersionToken() {
+    return _versionToken;
+}
+/**
+ * Drains and returns all tokens captured by createRoute() calls since the last drain.
+ * Used by versioned route discovery to detect interleaving.
+ */
+export function drainCapturedTokens() {
+    return _capturedTokens.splice(0);
+}
+/**
+ * Asserts that all tokens in the array match the expected token.
+ * Throws a clear startup error if any mismatch is detected.
+ */
+export function assertCapturedTokens(tokens, expectedToken) {
+    for (const tok of tokens) {
+        if (tok !== expectedToken) {
+            throw new Error("Route file imported with wrong version prefix — avoid unbounded top-level await in versioned route files");
+        }
+    }
+}
 const STATUS_SUFFIX = {
     "200": "Response",
     "201": "Response",
@@ -128,13 +173,19 @@ export const withSecurity = (route, ...schemes) => Object.assign(route, { securi
  * OpenAPI components so they appear in `components/schemas` instead of being
  * inlined at every use site. Generated names follow the convention:
  *
- *   {Method}{PathSegments}Body         — request body
- *   {Method}{PathSegments}{StatusCode} — response body
+ *   {Version}{Method}{PathSegments}Request — request body (when versioning is active)
+ *   {Version}{Method}{PathSegments}{Status} — response body (when versioning is active)
  *
  * Schemas already named via `.openapi("Name")` are never overwritten.
+ *
+ * When `setVersionPrefix` has been called, the version prefix is prepended to all
+ * generated schema names and the current version token is captured for interleaving
+ * detection via `drainCapturedTokens()` / `assertCapturedTokens()`.
  */
 export const createRoute = (config) => {
-    const base = toBaseName(config.method, config.path);
+    const base = (_versionPrefix ? `${_versionPrefix}` : "") + toBaseName(config.method, config.path);
+    // Capture the current version token for interleaving detection
+    _capturedTokens.push(_versionToken);
     // Auto-name the JSON request body schema if present and unnamed
     const bodySchema = config.request?.body?.content?.["application/json"]?.schema;
     maybeRegister(bodySchema, `${base}Request`);

package/dist/lib/deletionCancelToken.d.ts

@@ -0,0 +1,12 @@
+type CancelStore = "redis" | "mongo" | "sqlite" | "memory";
+export declare const setDeletionCancelTokenStore: (store: CancelStore) => void;
+/** Create a cancel token. Returns the raw token (to embed in the cancel link).
+ *  Only the SHA-256 hash is persisted. TTL is gracePeriod + a 5-minute buffer. */
+export declare const createDeletionCancelToken: (userId: string, jobId: string, gracePeriodSeconds: number) => Promise<string>;
+/** Atomically consume a cancel token — returns its payload and deletes it.
+ *  Returns null if the token is invalid, expired, or already used. */
+export declare const consumeDeletionCancelToken: (token: string) => Promise<{
+    userId: string;
+    jobId: string;
+} | null>;
+export {};

package/dist/lib/deletionCancelToken.js

@@ -0,0 +1,88 @@
+import { getRedis } from "./redis";
+import { appConnection, mongoose } from "./mongo";
+import { getAppName } from "./appConfig";
+import { sqliteCreateDeletionCancelToken, sqliteConsumeDeletionCancelToken, } from "../adapters/sqliteAuth";
+import { memoryCreateDeletionCancelToken, memoryConsumeDeletionCancelToken, } from "../adapters/memoryAuth";
+import { sha256 as hashToken } from "./crypto";
+function getCancelModel() {
+    if (appConnection.models["DeletionCancelToken"])
+        return appConnection.models["DeletionCancelToken"];
+    const { Schema } = mongoose;
+    const schema = new Schema({
+        token: { type: String, required: true, unique: true },
+        userId: { type: String, required: true },
+        jobId: { type: String, required: true },
+        expiresAt: { type: Date, required: true, index: { expireAfterSeconds: 0 } },
+    }, { collection: "deletion_cancel_tokens" });
+    return appConnection.model("DeletionCancelToken", schema);
+}
+// ---------------------------------------------------------------------------
+// Redis helpers
+// ---------------------------------------------------------------------------
+async function redisGetDel(key) {
+    const redis = getRedis();
+    if (typeof redis.getdel === "function") {
+        try {
+            return await redis.getdel(key);
+        }
+        catch (err) {
+            const msg = err?.message ?? "";
+            if (!/unknown command|ERR unknown command/i.test(msg))
+                throw err;
+        }
+    }
+    const result = await redis.eval("local v = redis.call('GET', KEYS[1])\nif v then redis.call('DEL', KEYS[1]) end\nreturn v", 1, key);
+    return result ?? null;
+}
+let _store = "redis";
+export const setDeletionCancelTokenStore = (store) => { _store = store; };
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Create a cancel token. Returns the raw token (to embed in the cancel link).
+ *  Only the SHA-256 hash is persisted. TTL is gracePeriod + a 5-minute buffer. */
+export const createDeletionCancelToken = async (userId, jobId, gracePeriodSeconds) => {
+    const token = crypto.randomUUID();
+    const hash = hashToken(token);
+    const ttl = gracePeriodSeconds + 300; // 5-min buffer after grace period expires
+    if (_store === "memory") {
+        memoryCreateDeletionCancelToken(hash, userId, jobId, ttl);
+        return token;
+    }
+    if (_store === "sqlite") {
+        sqliteCreateDeletionCancelToken(hash, userId, jobId, ttl);
+        return token;
+    }
+    if (_store === "mongo") {
+        await getCancelModel().create({
+            token: hash,
+            userId,
+            jobId,
+            expiresAt: new Date(Date.now() + ttl * 1000),
+        });
+        return token;
+    }
+    await getRedis().set(`delcancel:${getAppName()}:${hash}`, JSON.stringify({ userId, jobId }), "EX", ttl);
+    return token;
+};
+/** Atomically consume a cancel token — returns its payload and deletes it.
+ *  Returns null if the token is invalid, expired, or already used. */
+export const consumeDeletionCancelToken = async (token) => {
+    const hash = hashToken(token);
+    if (_store === "memory")
+        return memoryConsumeDeletionCancelToken(hash);
+    if (_store === "sqlite")
+        return sqliteConsumeDeletionCancelToken(hash);
+    if (_store === "mongo") {
+        const doc = await getCancelModel()
+            .findOneAndDelete({ token: hash, expiresAt: { $gt: new Date() } })
+            .lean();
+        if (!doc)
+            return null;
+        return { userId: doc.userId, jobId: doc.jobId };
+    }
+    const raw = await redisGetDel(`delcancel:${getAppName()}:${hash}`);
+    if (!raw)
+        return null;
+    return JSON.parse(raw);
+};

package/dist/lib/groups.d.ts

@@ -0,0 +1,113 @@
+export interface GroupRecord {
+    id: string;
+    /** Machine-readable slug: /^[a-z0-9_-]+$/, unique within scope (app-wide or per-tenant). */
+    name: string;
+    displayName?: string;
+    description?: string;
+    /** Baseline roles granted to every member of this group. */
+    roles: string[];
+    /** null = app-wide group, string = tenant-scoped group. Immutable after creation. */
+    tenantId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface GroupMembershipRecord {
+    userId: string;
+    groupId: string;
+    /** Per-member extra roles on top of the group's baseline roles. */
+    roles: string[];
+    /**
+     * Denormalized from the group at insert time for efficient tenant-scoped queries.
+     * Immutable: the group's tenantId cannot change after creation, so this is always consistent.
+     */
+    tenantId: string | null;
+    createdAt: number;
+}
+export interface PaginationOpts {
+    /** Default: 50, max: 200 */
+    limit?: number;
+    /** Default: 0 */
+    offset?: number;
+}
+export interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Create a new group. tenantId null = app-wide, string = tenant-scoped.
+ * The group name must be a slug (/^[a-z0-9_-]+$/) and unique within its scope.
+ * Returns the new group's id.
+ */
+export declare const createGroup: (group: Omit<GroupRecord, "id" | "createdAt" | "updatedAt">) => Promise<{
+    id: string;
+}>;
+/**
+ * Delete a group by ID. All memberships are cascade-deleted by the adapter.
+ */
+export declare const deleteGroup: (groupId: string) => Promise<void>;
+/**
+ * Get a group by ID. Returns null if not found.
+ */
+export declare const getGroup: (groupId: string) => Promise<GroupRecord | null>;
+/**
+ * List groups scoped to a tenant (tenantId string) or app-wide (tenantId null).
+ * Results are paginated.
+ */
+export declare const listGroups: (tenantId: string | null, opts?: PaginationOpts) => Promise<PaginatedResult<GroupRecord>>;
+/**
+ * Update a group's mutable fields: name, displayName, description, roles.
+ * tenantId is NOT in the update type — it is immutable after creation.
+ */
+export declare const updateGroup: (groupId: string, updates: Partial<Pick<GroupRecord, "roles" | "name" | "displayName" | "description">>) => Promise<void>;
+/**
+ * Add a user to a group. Optionally supply per-membership roles (extras on top of group.roles).
+ *
+ * CONTRACT: throws if the user is already a member (unique constraint).
+ * Use updateGroupMembership to change roles on an existing membership.
+ * All adapters surface this as a thrown error, not a silent no-op.
+ */
+export declare const addGroupMember: (groupId: string, userId: string, roles?: string[]) => Promise<void>;
+/**
+ * Update the per-membership roles for an existing member.
+ * This replaces the member's roles[] entirely (not an additive operation).
+ */
+export declare const updateGroupMembership: (groupId: string, userId: string, roles: string[]) => Promise<void>;
+/**
+ * Remove a user from a group. No-op if the user is not a member.
+ */
+export declare const removeGroupMember: (groupId: string, userId: string) => Promise<void>;
+/**
+ * List members of a group, with their per-membership roles. Paginated.
+ */
+export declare const getGroupMembers: (groupId: string, opts?: PaginationOpts) => Promise<PaginatedResult<{
+    userId: string;
+    roles: string[];
+}>>;
+/**
+ * List all groups a user belongs to, with their per-membership roles.
+ * Pass tenantId=null for app-wide groups, tenantId=string for tenant-scoped groups.
+ */
+export declare const getUserGroups: (userId: string, tenantId: string | null) => Promise<Array<{
+    group: GroupRecord;
+    membershipRoles: string[];
+}>>;
+/**
+ * Return all roles a user effectively has in the given scope, combining:
+ *   1. Direct roles (app-wide or tenant-scoped)
+ *   2. Group baseline roles (from all groups the user belongs to in that scope)
+ *   3. Per-membership roles (user-specific extras within each group)
+ *
+ * SCOPE CONTRACT:
+ *   - tenantId = null  → app-wide direct roles + app-wide group roles
+ *   - tenantId = string → tenant-scoped direct roles + tenant-scoped group roles
+ *
+ * Tenant-scoped group roles NEVER appear in app-wide effective roles and vice versa.
+ * This is intentional: a user who is "admin" only in a tenant-scoped group is NOT
+ * a global admin. Assign roles app-wide for global access.
+ *
+ * Used internally by requireRole and requireRole.global. Also exported for use in
+ * custom middleware, route handlers, or GET /auth/me enrichment.
+ */
+export declare const getEffectiveRoles: (userId: string, tenantId: string | null) => Promise<string[]>;

package/dist/lib/groups.js

@@ -0,0 +1,133 @@
+import { getAuthAdapter } from "./authAdapter";
+// ---------------------------------------------------------------------------
+// Group CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Create a new group. tenantId null = app-wide, string = tenant-scoped.
+ * The group name must be a slug (/^[a-z0-9_-]+$/) and unique within its scope.
+ * Returns the new group's id.
+ */
+export const createGroup = async (group) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.createGroup)
+        throw new Error("Auth adapter does not implement createGroup");
+    return adapter.createGroup(group);
+};
+/**
+ * Delete a group by ID. All memberships are cascade-deleted by the adapter.
+ */
+export const deleteGroup = async (groupId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.deleteGroup)
+        throw new Error("Auth adapter does not implement deleteGroup");
+    return adapter.deleteGroup(groupId);
+};
+/**
+ * Get a group by ID. Returns null if not found.
+ */
+export const getGroup = async (groupId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getGroup)
+        throw new Error("Auth adapter does not implement getGroup");
+    return adapter.getGroup(groupId);
+};
+/**
+ * List groups scoped to a tenant (tenantId string) or app-wide (tenantId null).
+ * Results are paginated.
+ */
+export const listGroups = async (tenantId, opts) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.listGroups)
+        throw new Error("Auth adapter does not implement listGroups");
+    return adapter.listGroups(tenantId, opts);
+};
+/**
+ * Update a group's mutable fields: name, displayName, description, roles.
+ * tenantId is NOT in the update type — it is immutable after creation.
+ */
+export const updateGroup = async (groupId, updates) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.updateGroup)
+        throw new Error("Auth adapter does not implement updateGroup");
+    return adapter.updateGroup(groupId, updates);
+};
+// ---------------------------------------------------------------------------
+// Membership management
+// ---------------------------------------------------------------------------
+/**
+ * Add a user to a group. Optionally supply per-membership roles (extras on top of group.roles).
+ *
+ * CONTRACT: throws if the user is already a member (unique constraint).
+ * Use updateGroupMembership to change roles on an existing membership.
+ * All adapters surface this as a thrown error, not a silent no-op.
+ */
+export const addGroupMember = async (groupId, userId, roles) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.addGroupMember)
+        throw new Error("Auth adapter does not implement addGroupMember");
+    return adapter.addGroupMember(groupId, userId, roles);
+};
+/**
+ * Update the per-membership roles for an existing member.
+ * This replaces the member's roles[] entirely (not an additive operation).
+ */
+export const updateGroupMembership = async (groupId, userId, roles) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.updateGroupMembership)
+        throw new Error("Auth adapter does not implement updateGroupMembership");
+    return adapter.updateGroupMembership(groupId, userId, roles);
+};
+/**
+ * Remove a user from a group. No-op if the user is not a member.
+ */
+export const removeGroupMember = async (groupId, userId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.removeGroupMember)
+        throw new Error("Auth adapter does not implement removeGroupMember");
+    return adapter.removeGroupMember(groupId, userId);
+};
+/**
+ * List members of a group, with their per-membership roles. Paginated.
+ */
+export const getGroupMembers = async (groupId, opts) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getGroupMembers)
+        throw new Error("Auth adapter does not implement getGroupMembers");
+    return adapter.getGroupMembers(groupId, opts);
+};
+/**
+ * List all groups a user belongs to, with their per-membership roles.
+ * Pass tenantId=null for app-wide groups, tenantId=string for tenant-scoped groups.
+ */
+export const getUserGroups = async (userId, tenantId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getUserGroups)
+        throw new Error("Auth adapter does not implement getUserGroups");
+    return adapter.getUserGroups(userId, tenantId);
+};
+// ---------------------------------------------------------------------------
+// Effective role resolution
+// ---------------------------------------------------------------------------
+/**
+ * Return all roles a user effectively has in the given scope, combining:
+ *   1. Direct roles (app-wide or tenant-scoped)
+ *   2. Group baseline roles (from all groups the user belongs to in that scope)
+ *   3. Per-membership roles (user-specific extras within each group)
+ *
+ * SCOPE CONTRACT:
+ *   - tenantId = null  → app-wide direct roles + app-wide group roles
+ *   - tenantId = string → tenant-scoped direct roles + tenant-scoped group roles
+ *
+ * Tenant-scoped group roles NEVER appear in app-wide effective roles and vice versa.
+ * This is intentional: a user who is "admin" only in a tenant-scoped group is NOT
+ * a global admin. Assign roles app-wide for global access.
+ *
+ * Used internally by requireRole and requireRole.global. Also exported for use in
+ * custom middleware, route handlers, or GET /auth/me enrichment.
+ */
+export const getEffectiveRoles = async (userId, tenantId) => {
+    const adapter = getAuthAdapter();
+    if (!adapter.getEffectiveRoles)
+        throw new Error("Auth adapter does not implement getEffectiveRoles");
+    return adapter.getEffectiveRoles(userId, tenantId);
+};

package/dist/lib/idempotency.d.ts

@@ -0,0 +1,22 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "./context";
+export interface IdempotencyOptions {
+    /** TTL in seconds for cached responses. Default: 86400 (24 hours). */
+    ttl?: number;
+}
+type IdempotencyStore = "redis" | "mongo" | "sqlite" | "memory";
+export declare const setIdempotencyStore: (store: IdempotencyStore) => void;
+export declare const clearIdempotencyMemoryStore: () => void;
+/**
+ * Idempotency middleware. Reads the `Idempotency-Key` header and returns a
+ * cached response if one exists for this user + key combination. Otherwise
+ * calls the next handler, stores the response, and returns it.
+ *
+ * On write collision (two concurrent identical requests), the second request
+ * re-reads and returns the first-stored result.
+ *
+ * When `signing.idempotencyKeys: true`, keys are HMAC'd before storage to
+ * prevent enumeration. When off, raw keys are stored (slight enumeration risk).
+ */
+export declare const idempotent: (opts?: IdempotencyOptions) => MiddlewareHandler<AppEnv>;
+export {};