@lastshotlabs/bunshot 0.0.10 → 0.0.16

package/dist/lib/session.js

@@ -1,8 +1,8 @@
 import { getRedis } from "./redis";
 import { appConnection, mongoose } from "./mongo";
-import { getAppName, getPersistSessionMetadata, getIncludeInactiveSessions } from "./appConfig";
-import { sqliteCreateSession, sqliteGetSession, sqliteDeleteSession, sqliteGetUserSessions, sqliteGetActiveSessionCount, sqliteEvictOldestSession, sqliteUpdateSessionLastActive, } from "../adapters/sqliteAuth";
-import { memoryCreateSession, memoryGetSession, memoryDeleteSession, memoryGetUserSessions, memoryGetActiveSessionCount, memoryEvictOldestSession, memoryUpdateSessionLastActive, } from "../adapters/memoryAuth";
+import { getAppName, getPersistSessionMetadata, getIncludeInactiveSessions, getRotationGraceSeconds, getRefreshTokenExpiry } from "./appConfig";
+import { sqliteCreateSession, sqliteGetSession, sqliteDeleteSession, sqliteGetUserSessions, sqliteGetActiveSessionCount, sqliteEvictOldestSession, sqliteUpdateSessionLastActive, sqliteSetRefreshToken, sqliteGetSessionByRefreshToken, sqliteRotateRefreshToken, } from "../adapters/sqliteAuth";
+import { memoryCreateSession, memoryGetSession, memoryDeleteSession, memoryGetUserSessions, memoryGetActiveSessionCount, memoryEvictOldestSession, memoryUpdateSessionLastActive, memorySetRefreshToken, memoryGetSessionByRefreshToken, memoryRotateRefreshToken, } from "../adapters/memoryAuth";
 function getSessionModel() {
     if (appConnection.models["Session"])
         return appConnection.models["Session"];
@@ -16,7 +16,11 @@ function getSessionModel() {
         expiresAt: { type: Date, required: true },
         ipAddress: { type: String },
         userAgent: { type: String },
+        refreshToken: { type: String, default: null, sparse: true },
+        prevRefreshToken: { type: String, default: null },
+        prevTokenExpiresAt: { type: Date, default: null },
     }, { collection: "sessions", timestamps: false });
+    sessionSchema.index({ refreshToken: 1 }, { sparse: true, unique: true });
     // Add TTL index only when metadata is not persisted — docs auto-delete at expiresAt.
     // When persisting, token is nulled (soft-delete) but the row is kept indefinitely.
     if (!getPersistSessionMetadata()) {
@@ -40,6 +44,9 @@ function redisSessionKey(sessionId) {
 function redisUserSessionsKey(userId) {
     return `usersessions:${getAppName()}:${userId}`;
 }
+function redisRefreshTokenKey(refreshToken) {
+    return `refreshtoken:${getAppName()}:${refreshToken}`;
+}
 async function redisCreateSession(userId, token, sessionId, metadata) {
     const now = Date.now();
     const expiresAt = now + TTL_MS;
@@ -78,8 +85,13 @@ async function redisDeleteSession(sessionId) {
         return;
     const rec = JSON.parse(raw);
     const persist = getPersistSessionMetadata();
+    // Clean up refresh token reverse-lookup keys
+    if (rec.refreshToken)
+        await redis.del(redisRefreshTokenKey(rec.refreshToken));
+    if (rec.prevRefreshToken)
+        await redis.del(redisRefreshTokenKey(rec.prevRefreshToken));
     if (persist) {
-        const updated = { ...JSON.parse(raw), token: null };
+        const updated = { ...rec, token: null, refreshToken: null, prevRefreshToken: null, prevTokenExpiresAt: null };
         await redis.set(redisSessionKey(sessionId), JSON.stringify(updated));
     }
     else {
@@ -169,6 +181,64 @@ async function redisUpdateSessionLastActive(sessionId) {
         await redis.set(redisSessionKey(sessionId), JSON.stringify(rec), "EX", ttlRemaining);
     }
 }
+async function redisSetRefreshToken(sessionId, refreshToken) {
+    const redis = getRedis();
+    const raw = await redis.get(redisSessionKey(sessionId));
+    if (!raw)
+        return;
+    const rec = JSON.parse(raw);
+    rec.refreshToken = refreshToken;
+    const refreshExpiry = getRefreshTokenExpiry();
+    await redis.set(redisSessionKey(sessionId), JSON.stringify(rec));
+    await redis.set(redisRefreshTokenKey(refreshToken), sessionId, "EX", refreshExpiry);
+}
+async function redisGetSessionByRefreshToken(refreshToken) {
+    const redis = getRedis();
+    const sessionId = await redis.get(redisRefreshTokenKey(refreshToken));
+    if (!sessionId)
+        return null;
+    const raw = await redis.get(redisSessionKey(sessionId));
+    if (!raw)
+        return null;
+    const rec = JSON.parse(raw);
+    // Current refresh token matches
+    if (rec.refreshToken === refreshToken) {
+        return { sessionId: rec.sessionId, userId: rec.userId, newRefreshToken: refreshToken };
+    }
+    // Check grace window: old token used within grace period
+    if (rec.prevRefreshToken === refreshToken && rec.prevTokenExpiresAt && rec.prevTokenExpiresAt > Date.now()) {
+        // Return current refresh token — client missed the rotation response
+        return { sessionId: rec.sessionId, userId: rec.userId, newRefreshToken: rec.refreshToken };
+    }
+    // Old token used after grace window — token family theft detected, invalidate session
+    if (rec.prevRefreshToken === refreshToken) {
+        await redisDeleteSession(sessionId);
+        return null;
+    }
+    return null;
+}
+async function redisRotateRefreshToken(sessionId, newRefreshToken, newAccessToken) {
+    const redis = getRedis();
+    const raw = await redis.get(redisSessionKey(sessionId));
+    if (!raw)
+        return;
+    const rec = JSON.parse(raw);
+    const graceSeconds = getRotationGraceSeconds();
+    const refreshExpiry = getRefreshTokenExpiry();
+    // Move current to prev with grace window
+    const oldRefreshToken = rec.refreshToken;
+    rec.prevRefreshToken = oldRefreshToken;
+    rec.prevTokenExpiresAt = Date.now() + graceSeconds * 1000;
+    rec.refreshToken = newRefreshToken;
+    rec.token = newAccessToken;
+    await redis.set(redisSessionKey(sessionId), JSON.stringify(rec));
+    // Set new reverse-lookup with full refresh expiry
+    await redis.set(redisRefreshTokenKey(newRefreshToken), sessionId, "EX", refreshExpiry);
+    // Update old reverse-lookup to expire after grace window
+    if (oldRefreshToken) {
+        await redis.expire(redisRefreshTokenKey(oldRefreshToken), graceSeconds);
+    }
+}
 // ---------------------------------------------------------------------------
 // Mongo helpers
 // ---------------------------------------------------------------------------
@@ -201,6 +271,45 @@ async function mongoGetUserSessions(userId) {
     }
     return results;
 }
+async function mongoSetRefreshToken(sessionId, refreshToken) {
+    await getSessionModel().updateOne({ sessionId }, { $set: { refreshToken } });
+}
+async function mongoGetSessionByRefreshToken(refreshToken) {
+    const Session = getSessionModel();
+    // Check current refresh token
+    let doc = await Session.findOne({ refreshToken }).lean();
+    if (doc) {
+        return { sessionId: doc.sessionId, userId: doc.userId, newRefreshToken: refreshToken };
+    }
+    // Check previous refresh token (grace window)
+    doc = await Session.findOne({ prevRefreshToken: refreshToken }).lean();
+    if (!doc)
+        return null;
+    if (doc.prevTokenExpiresAt && doc.prevTokenExpiresAt > new Date()) {
+        // Within grace window — return current refresh token
+        return { sessionId: doc.sessionId, userId: doc.userId, newRefreshToken: doc.refreshToken };
+    }
+    // Grace window expired — token family theft detected, invalidate session
+    if (getPersistSessionMetadata()) {
+        await Session.updateOne({ sessionId: doc.sessionId }, { $set: { token: null, refreshToken: null, prevRefreshToken: null, prevTokenExpiresAt: null } });
+    }
+    else {
+        await Session.deleteOne({ sessionId: doc.sessionId });
+    }
+    return null;
+}
+async function mongoRotateRefreshToken(sessionId, newRefreshToken, newAccessToken) {
+    const graceSeconds = getRotationGraceSeconds();
+    const Session = getSessionModel();
+    const doc = await Session.findOne({ sessionId });
+    if (!doc)
+        return;
+    doc.prevRefreshToken = doc.refreshToken;
+    doc.prevTokenExpiresAt = new Date(Date.now() + graceSeconds * 1000);
+    doc.refreshToken = newRefreshToken;
+    doc.token = newAccessToken;
+    await doc.save();
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -255,7 +364,7 @@ export const deleteSession = async (sessionId) => {
     }
     // mongo
     if (getPersistSessionMetadata()) {
-        await getSessionModel().updateOne({ sessionId }, { $set: { token: null } });
+        await getSessionModel().updateOne({ sessionId }, { $set: { token: null, refreshToken: null, prevRefreshToken: null, prevTokenExpiresAt: null } });
     }
     else {
         await getSessionModel().deleteOne({ sessionId });
@@ -303,6 +412,10 @@ export const evictOldestSession = async (userId) => {
     if (oldest)
         await deleteSession(oldest.sessionId);
 };
+export const deleteUserSessions = async (userId) => {
+    const sessions = await getUserSessions(userId);
+    await Promise.all(sessions.map((s) => deleteSession(s.sessionId)));
+};
 export const updateSessionLastActive = async (sessionId) => {
     if (_store === "memory") {
         memoryUpdateSessionLastActive(sessionId);
@@ -319,3 +432,48 @@ export const updateSessionLastActive = async (sessionId) => {
     // mongo
     await getSessionModel().updateOne({ sessionId }, { $set: { lastActiveAt: new Date() } });
 };
+// ---------------------------------------------------------------------------
+// Refresh token API
+// ---------------------------------------------------------------------------
+/** Store a refresh token on an existing session (called after session creation). */
+export const setRefreshToken = async (sessionId, refreshToken) => {
+    if (_store === "memory") {
+        memorySetRefreshToken(sessionId, refreshToken);
+        return;
+    }
+    if (_store === "sqlite") {
+        sqliteSetRefreshToken(sessionId, refreshToken);
+        return;
+    }
+    if (_store === "redis") {
+        await redisSetRefreshToken(sessionId, refreshToken);
+        return;
+    }
+    await mongoSetRefreshToken(sessionId, refreshToken);
+};
+/** Look up a session by refresh token. Handles grace window and theft detection. */
+export const getSessionByRefreshToken = async (refreshToken) => {
+    if (_store === "memory")
+        return memoryGetSessionByRefreshToken(refreshToken);
+    if (_store === "sqlite")
+        return sqliteGetSessionByRefreshToken(refreshToken);
+    if (_store === "redis")
+        return redisGetSessionByRefreshToken(refreshToken);
+    return mongoGetSessionByRefreshToken(refreshToken);
+};
+/** Rotate the refresh token: move current to prev with grace window, set new token + access token. */
+export const rotateRefreshToken = async (sessionId, newRefreshToken, newAccessToken) => {
+    if (_store === "memory") {
+        memoryRotateRefreshToken(sessionId, newRefreshToken, newAccessToken);
+        return;
+    }
+    if (_store === "sqlite") {
+        sqliteRotateRefreshToken(sessionId, newRefreshToken, newAccessToken);
+        return;
+    }
+    if (_store === "redis") {
+        await redisRotateRefreshToken(sessionId, newRefreshToken, newAccessToken);
+        return;
+    }
+    await mongoRotateRefreshToken(sessionId, newRefreshToken, newAccessToken);
+};

package/dist/lib/tenant.d.ts

@@ -0,0 +1,15 @@
+export interface TenantInfo {
+    tenantId: string;
+    displayName?: string;
+    config?: Record<string, unknown>;
+    createdAt: Date;
+    deletedAt?: Date | null;
+}
+export interface CreateTenantOptions {
+    displayName?: string;
+    config?: Record<string, unknown>;
+}
+export declare const createTenant: (tenantId: string, options?: CreateTenantOptions) => Promise<void>;
+export declare const deleteTenant: (tenantId: string) => Promise<void>;
+export declare const getTenant: (tenantId: string) => Promise<TenantInfo | null>;
+export declare const listTenants: () => Promise<TenantInfo[]>;

package/dist/lib/tenant.js

@@ -0,0 +1,65 @@
+import { authConnection, mongoose } from "./mongo";
+let _TenantModel = null;
+function getTenantModel() {
+    if (!_TenantModel) {
+        const { Schema } = mongoose;
+        const schema = new Schema({
+            tenantId: { type: String, required: true, unique: true },
+            displayName: { type: String },
+            config: { type: Schema.Types.Mixed },
+            deletedAt: { type: Date, default: null },
+        }, { timestamps: true });
+        _TenantModel = authConnection.model("Tenant", schema);
+    }
+    return _TenantModel;
+}
+// Proxy for lazy model resolution (same pattern as AuthUser)
+const Tenant = new Proxy({}, {
+    get(_, prop) {
+        const model = getTenantModel();
+        const val = model[prop];
+        return typeof val === "function" ? val.bind(model) : val;
+    },
+});
+export const createTenant = async (tenantId, options) => {
+    const existing = await Tenant.findOne({ tenantId }).lean();
+    if (existing && !existing.deletedAt) {
+        throw new Error(`Tenant "${tenantId}" already exists`);
+    }
+    if (existing && existing.deletedAt) {
+        // Reactivate soft-deleted tenant
+        await Tenant.findOneAndUpdate({ tenantId }, { deletedAt: null, displayName: options?.displayName, config: options?.config });
+        return;
+    }
+    await Tenant.create({
+        tenantId,
+        displayName: options?.displayName,
+        config: options?.config,
+    });
+};
+export const deleteTenant = async (tenantId) => {
+    const { invalidateTenantCache } = await import("../middleware/tenant");
+    // Soft-delete
+    await Tenant.findOneAndUpdate({ tenantId }, { deletedAt: new Date() });
+    invalidateTenantCache(tenantId);
+};
+export const getTenant = async (tenantId) => {
+    const doc = await Tenant.findOne({ tenantId, deletedAt: null }).lean();
+    if (!doc)
+        return null;
+    return {
+        tenantId: doc.tenantId,
+        displayName: doc.displayName,
+        config: doc.config,
+        createdAt: doc.createdAt,
+    };
+};
+export const listTenants = async () => {
+    const docs = await Tenant.find({ deletedAt: null }).lean();
+    return docs.map((doc) => ({
+        tenantId: doc.tenantId,
+        displayName: doc.displayName,
+        config: doc.config,
+        createdAt: doc.createdAt,
+    }));
+};

package/dist/lib/zodToMongoose.d.ts

@@ -0,0 +1,38 @@
+import { Schema } from "mongoose";
+type ZodSchema = any;
+export type ZodToMongooseRefConfig = {
+    /** DB field name (e.g., "account") */
+    dbField: string;
+    /** Referenced model name (e.g., "Account") */
+    ref: string;
+};
+export type ZodToMongooseConfig = {
+    /** DB-only fields not in the Zod schema (e.g., user ref) */
+    dbFields?: Record<string, unknown>;
+    /** API fields that map to ObjectId refs: { accountId: { dbField: "account", ref: "Account" } } */
+    refs?: Record<string, ZodToMongooseRefConfig>;
+    /** Override Mongoose type for specific fields (e.g., { date: { type: Date, required: true } }) */
+    typeOverrides?: Record<string, unknown>;
+    /** Subdocument array fields: { items: mongooseSubSchema } */
+    subdocSchemas?: Record<string, Schema>;
+};
+/**
+ * Derive a Mongoose SchemaDefinition from a Zod object schema.
+ *
+ * Business fields are auto-converted from Zod types to Mongoose types.
+ * DB-specific concerns (ObjectId refs, type overrides, subdocuments) are declared via config.
+ *
+ * The `id` field is automatically excluded (Mongoose provides `_id`).
+ *
+ * @example
+ * ```ts
+ * const AccountMongoSchema = new Schema(
+ *   zodToMongoose(AccountSchema, {
+ *     dbFields: { user: { type: Schema.Types.ObjectId, ref: "UserProfile", required: true } },
+ *   }),
+ *   { timestamps: true }
+ * );
+ * ```
+ */
+export declare function zodToMongoose(zodSchema: ZodSchema, config?: ZodToMongooseConfig): Record<string, unknown>;
+export {};

package/dist/lib/zodToMongoose.js

@@ -0,0 +1,84 @@
+import { Schema } from "mongoose";
+/** Unwrap nullable, optional, and default wrappers to get the core Zod type */
+function unwrap(zodType) {
+    let t = zodType;
+    let required = true;
+    while (true) {
+        const defType = t._zod?.def?.type;
+        if (defType === "nullable") {
+            t = t._zod.def.innerType;
+            required = false;
+        }
+        else if (defType === "optional") {
+            t = t._zod.def.innerType;
+            required = false;
+        }
+        else if (defType === "default") {
+            t = t._zod.def.innerType;
+            required = false;
+        }
+        else
+            break;
+    }
+    return { core: t, required };
+}
+/** Convert a single Zod type to a Mongoose field definition */
+function toMongooseField(zodType) {
+    const { core, required } = unwrap(zodType);
+    const defType = core._zod?.def?.type;
+    if (defType === "string")
+        return { type: String, required };
+    if (defType === "number")
+        return { type: Number, required };
+    if (defType === "boolean")
+        return { type: Boolean, required };
+    if (defType === "date")
+        return { type: Date, required };
+    if (defType === "enum")
+        return { type: String, enum: core.options, required };
+    return { type: Schema.Types.Mixed, required };
+}
+/**
+ * Derive a Mongoose SchemaDefinition from a Zod object schema.
+ *
+ * Business fields are auto-converted from Zod types to Mongoose types.
+ * DB-specific concerns (ObjectId refs, type overrides, subdocuments) are declared via config.
+ *
+ * The `id` field is automatically excluded (Mongoose provides `_id`).
+ *
+ * @example
+ * ```ts
+ * const AccountMongoSchema = new Schema(
+ *   zodToMongoose(AccountSchema, {
+ *     dbFields: { user: { type: Schema.Types.ObjectId, ref: "UserProfile", required: true } },
+ *   }),
+ *   { timestamps: true }
+ * );
+ * ```
+ */
+export function zodToMongoose(zodSchema, config = {}) {
+    const shape = zodSchema.shape;
+    const fields = {};
+    for (const [apiField, zodType] of Object.entries(shape)) {
+        if (apiField === "id")
+            continue;
+        if (config.refs?.[apiField]) {
+            const { dbField, ref } = config.refs[apiField];
+            fields[dbField] = { type: Schema.Types.ObjectId, ref, required: true };
+            continue;
+        }
+        if (config.typeOverrides?.[apiField]) {
+            fields[apiField] = config.typeOverrides[apiField];
+            continue;
+        }
+        if (config.subdocSchemas?.[apiField]) {
+            fields[apiField] = [config.subdocSchemas[apiField]];
+            continue;
+        }
+        fields[apiField] = toMongooseField(zodType);
+    }
+    if (config.dbFields) {
+        Object.assign(fields, config.dbFields);
+    }
+    return fields;
+}

package/dist/middleware/cacheResponse.js

@@ -134,7 +134,10 @@ export const cacheResponse = ({ ttl, key, store = _defaultCacheStore }) => {
     return async (c, next) => {
         const appName = getAppName();
         const rawKey = typeof key === "function" ? key(c) : key;
-        const cacheKey = `cache:${appName}:${rawKey}`;
+        // Per-tenant namespacing: prevents two tenants caching the same key from colliding
+        const tenantId = c.get("tenantId");
+        const tenantSegment = tenantId ? `${tenantId}:` : "";
+        const cacheKey = `cache:${appName}:${tenantSegment}${rawKey}`;
         const cached = await storeGet(store, cacheKey);
         if (cached) {
             const { status, headers, body } = JSON.parse(cached);

package/dist/middleware/rateLimit.d.ts

@@ -1,8 +1,9 @@
 import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
 export interface RateLimitOptions {
     windowMs: number;
     max: number;
     /** Also rate-limit by HTTP fingerprint in addition to IP. Default: false */
     fingerprintLimit?: boolean;
 }
-export declare const rateLimit: ({ windowMs, max, fingerprintLimit, }: RateLimitOptions) => MiddlewareHandler;
+export declare const rateLimit: ({ windowMs, max, fingerprintLimit, }: RateLimitOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/rateLimit.js

@@ -6,12 +6,15 @@ export const rateLimit = ({ windowMs, max, fingerprintLimit = false, }) => {
         // Take the leftmost (client) IP from x-forwarded-for
         const raw = c.req.header("x-forwarded-for") ?? "";
         const ip = raw.split(",")[0]?.trim() || "unknown";
-        if (await trackAttempt(`ip:${ip}`, opts)) {
+        // Per-tenant namespacing: each tenant gets independent rate limit buckets
+        const tenantId = c.get("tenantId");
+        const prefix = tenantId ? `t:${tenantId}:` : "";
+        if (await trackAttempt(`${prefix}ip:${ip}`, opts)) {
             return c.json({ error: "Too Many Requests" }, 429);
         }
         if (fingerprintLimit) {
             const fp = await buildFingerprint(c.req.raw);
-            if (await trackAttempt(`fp:${fp}`, opts)) {
+            if (await trackAttempt(`${prefix}fp:${fp}`, opts)) {
                 return c.json({ error: "Too Many Requests" }, 429);
             }
         }

package/dist/middleware/requireRole.d.ts

@@ -3,9 +3,11 @@ import type { AppEnv } from "../lib/context";
 /**
  * Middleware factory that enforces role-based access.
  * Requires `identify` to have run first (authUserId must be set).
- * Roles are fetched lazily on the first role-checked route and cached on the context.
  *
- * The adapter must implement `getRoles` for this to work.
+ * When tenant context exists (`tenantId` set on context), checks tenant-scoped roles.
+ * Falls back to app-wide roles when no tenant context is present.
+ *
+ * The adapter must implement `getRoles` (and `getTenantRoles` for tenant-scoped checks).
  *
  * @example
  * // Allow any authenticated user with the "admin" role
@@ -14,4 +16,13 @@ import type { AppEnv } from "../lib/context";
  * // Allow users with either "admin" or "moderator"
  * app.get("/mod", userAuth, requireRole("admin", "moderator"), handler)
  */
-export declare const requireRole: (...roles: string[]) => MiddlewareHandler<AppEnv>;
+export declare const requireRole: ((...roles: string[]) => MiddlewareHandler<AppEnv>) & {
+    /**
+     * Always checks app-wide roles regardless of tenant context.
+     * Use for super-admin gates that should ignore tenant scoping.
+     *
+     * @example
+     * app.get("/super-admin", userAuth, requireRole.global("superadmin"), handler)
+     */
+    global: (...roles: string[]) => MiddlewareHandler<AppEnv>;
+};

package/dist/middleware/requireRole.js

@@ -2,9 +2,11 @@ import { getAuthAdapter } from "../lib/authAdapter";
 /**
  * Middleware factory that enforces role-based access.
  * Requires `identify` to have run first (authUserId must be set).
- * Roles are fetched lazily on the first role-checked route and cached on the context.
  *
- * The adapter must implement `getRoles` for this to work.
+ * When tenant context exists (`tenantId` set on context), checks tenant-scoped roles.
+ * Falls back to app-wide roles when no tenant context is present.
+ *
+ * The adapter must implement `getRoles` (and `getTenantRoles` for tenant-scoped checks).
  *
  * @example
  * // Allow any authenticated user with the "admin" role
@@ -13,15 +15,25 @@ import { getAuthAdapter } from "../lib/authAdapter";
  * // Allow users with either "admin" or "moderator"
  * app.get("/mod", userAuth, requireRole("admin", "moderator"), handler)
  */
-export const requireRole = (...roles) => async (c, next) => {
+export const requireRole = Object.assign((...roles) => async (c, next) => {
     const userId = c.get("authUserId");
     if (!userId) {
         return c.json({ error: "Unauthorized" }, 401);
     }
-    // Lazy-fetch roles and cache on context so multiple requireRole calls in a chain only hit the adapter once
+    const adapter = getAuthAdapter();
+    const tenantId = c.get("tenantId");
+    // When tenant context exists and adapter supports tenant roles, check tenant-scoped roles
+    if (tenantId && adapter.getTenantRoles) {
+        const tenantRoles = await adapter.getTenantRoles(userId, tenantId);
+        const hasRole = roles.some((role) => tenantRoles.includes(role));
+        if (!hasRole) {
+            return c.json({ error: "Forbidden" }, 403);
+        }
+        return next();
+    }
+    // Fall back to app-wide roles
     let userRoles = c.get("roles");
     if (userRoles === null) {
-        const adapter = getAuthAdapter();
         if (!adapter.getRoles) {
             throw new Error("requireRole used but auth adapter does not implement getRoles");
         }
@@ -33,4 +45,32 @@ export const requireRole = (...roles) => async (c, next) => {
         return c.json({ error: "Forbidden" }, 403);
     }
     await next();
-};
+}, {
+    /**
+     * Always checks app-wide roles regardless of tenant context.
+     * Use for super-admin gates that should ignore tenant scoping.
+     *
+     * @example
+     * app.get("/super-admin", userAuth, requireRole.global("superadmin"), handler)
+     */
+    global: (...roles) => async (c, next) => {
+        const userId = c.get("authUserId");
+        if (!userId) {
+            return c.json({ error: "Unauthorized" }, 401);
+        }
+        let userRoles = c.get("roles");
+        if (userRoles === null) {
+            const adapter = getAuthAdapter();
+            if (!adapter.getRoles) {
+                throw new Error("requireRole.global used but auth adapter does not implement getRoles");
+            }
+            userRoles = await adapter.getRoles(userId);
+            c.set("roles", userRoles);
+        }
+        const hasRole = roles.some((role) => userRoles.includes(role));
+        if (!hasRole) {
+            return c.json({ error: "Forbidden" }, 403);
+        }
+        await next();
+    },
+});

package/dist/middleware/tenant.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+import type { TenancyConfig } from "../app";
+export declare const invalidateTenantCache: (tenantId: string) => void;
+export declare const createTenantMiddleware: (config: TenancyConfig) => MiddlewareHandler<AppEnv>;