gatehouse 0.1.0

package/README.md

@@ -0,0 +1,321 @@
+# Gatehouse
+
+Drop-in RBAC for Next.js. Define roles once, protect everything.
+
+```bash
+npm install gatehouse
+```
+
+## Quick Start
+
+### 1. Define your roles (one file, once)
+
+```ts
+// lib/gatehouse.ts
+import { createGatehouse } from "gatehouse";
+
+export const gh = createGatehouse({
+  roles: {
+    owner:  ["*"],
+    admin:  ["project:*", "member:invite", "member:remove"],
+    member: ["project:read", "project:create", "task:*"],
+    viewer: ["project:read", "task:read"],
+  },
+});
+```
+
+Roles are hierarchical — first is highest. Wildcards work: `project:*` matches `project:read`, `project:create`, etc. `*` matches everything.
+
+### 2. Protect your UI
+
+```tsx
+import { Gate } from "gatehouse/react";
+
+<Gate allow="project:create">
+  <CreateButton />
+</Gate>
+
+<Gate role="admin" fallback={<span>Admin only</span>}>
+  <AdminPanel />
+</Gate>
+```
+
+### 3. Protect your API routes
+
+```ts
+// lib/gate.ts
+import { createServerGate } from "gatehouse/next";
+import { gh } from "./gatehouse";
+import { auth } from "./auth";
+
+export const gate = createServerGate({
+  gatehouse: gh,
+  resolve: async () => {
+    const session = await auth();
+    if (!session) return null;
+    return { role: session.user.role };
+  },
+});
+```
+
+```ts
+// app/api/projects/route.ts
+import { withGate } from "gatehouse/next";
+import { gate } from "@/lib/gate";
+
+export const POST = withGate(async () => {
+  await gate("project:create");
+  return Response.json({ ok: true });
+});
+```
+
+That's it. Three files, working RBAC.
+
+---
+
+## Auth Provider Adapters
+
+### Clerk
+
+```ts
+import { createServerGate } from "gatehouse/next";
+import { clerkResolver } from "gatehouse/adapters/clerk";
+import { gh } from "./gatehouse";
+
+export const gate = createServerGate({
+  gatehouse: gh,
+  resolve: clerkResolver(), // reads from publicMetadata.role
+});
+```
+
+### Supabase
+
+```ts
+import { createServerGate } from "gatehouse/next";
+import { supabaseResolver } from "gatehouse/adapters/supabase";
+import { gh } from "./gatehouse";
+import { createClient } from "@/lib/supabase/server";
+
+export const gate = createServerGate({
+  gatehouse: gh,
+  resolve: supabaseResolver({ createClient }),
+});
+```
+
+### Auth.js (NextAuth)
+
+```ts
+import { createServerGate } from "gatehouse/next";
+import { authjsResolver } from "gatehouse/adapters/authjs";
+import { gh } from "./gatehouse";
+import { auth } from "./auth";
+
+export const gate = createServerGate({
+  gatehouse: gh,
+  resolve: authjsResolver({ auth }),
+});
+```
+
+---
+
+## React Components & Hooks
+
+### `<GatehouseProvider>`
+
+Wrap your app to provide RBAC context:
+
+```tsx
+// app/layout.tsx
+import { GatehouseProvider } from "gatehouse/react";
+import { gh } from "@/lib/gatehouse";
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <GatehouseProvider
+      gatehouse={gh}
+      resolve={async () => {
+        const res = await fetch("/api/me");
+        if (!res.ok) return null;
+        return res.json(); // { role: "admin" }
+      }}
+    >
+      {children}
+    </GatehouseProvider>
+  );
+}
+```
+
+### `<Gate>`
+
+Declarative permission gate:
+
+```tsx
+import { Gate } from "gatehouse/react";
+
+// Single permission
+<Gate allow="project:create">
+  <CreateButton />
+</Gate>
+
+// Role check
+<Gate role="admin">
+  <AdminPanel />
+</Gate>
+
+// Multiple permissions (all required)
+<Gate allOf={["project:edit", "project:delete"]}>
+  <DangerZone />
+</Gate>
+
+// Multiple permissions (any sufficient)
+<Gate anyOf={["project:edit", "project:create"]}>
+  <EditMenu />
+</Gate>
+
+// With fallback and loading state
+<Gate allow="billing:manage" fallback={<UpgradePrompt />} loading={<Skeleton />}>
+  <BillingDashboard />
+</Gate>
+```
+
+### Hooks
+
+```tsx
+import { useGate, useRole, usePermissions, useGatehouse } from "gatehouse/react";
+
+function MyComponent() {
+  const canCreate = useGate("project:create");
+  const role = useRole();           // "admin" | null
+  const perms = usePermissions();   // ["project:*", "member:invite", ...]
+  const { gatehouse, subject, loading } = useGatehouse();
+}
+```
+
+---
+
+## Next.js Middleware
+
+Protect routes at the edge:
+
+```ts
+// middleware.ts
+import { createMiddleware } from "gatehouse/next";
+
+export default createMiddleware({
+  protected: ["/dashboard/:path*", "/api/projects/:path*"],
+  isAuthenticated: (req) => !!req.cookies.get("session"),
+  loginUrl: "/login", // default
+});
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/projects/:path*"],
+};
+```
+
+---
+
+## Server-Side Gate API
+
+```ts
+import { gate } from "@/lib/gate";
+
+// Require authentication (throws 401 if not logged in)
+const subject = await gate();
+
+// Require specific permission (throws 403 if denied)
+const subject = await gate("project:create");
+
+// Require all permissions
+const subject = await gate.all(["project:edit", "project:delete"]);
+
+// Require any permission
+const subject = await gate.any(["project:edit", "project:create"]);
+
+// Require minimum role
+const subject = await gate.role("admin");
+
+// Soft check (returns null instead of throwing)
+const subject = await gate.check("project:create");
+```
+
+---
+
+## Core API (Framework-Agnostic)
+
+Use Gatehouse without React or Next.js:
+
+```ts
+import { createGatehouse } from "gatehouse";
+
+const gh = createGatehouse({
+  roles: {
+    owner:  ["*"],
+    admin:  ["project:*", "member:invite"],
+    member: ["project:read", "task:*"],
+    viewer: ["project:read", "task:read"],
+  },
+});
+
+gh.can("admin", "project:create");        // true (matches project:*)
+gh.can("viewer", "project:create");       // false
+gh.canAll("member", ["task:read", "task:create"]); // true
+gh.canAny("viewer", ["task:create", "project:read"]); // true
+gh.isAtLeast("admin", "member");          // true
+gh.isAtLeast("viewer", "admin");          // false
+gh.permissionsFor("admin");               // ["project:*", "member:invite"]
+gh.roles;                                 // ["owner", "admin", "member", "viewer"]
+```
+
+---
+
+## Wildcard Permissions
+
+```
+"*"           → matches everything
+"project:*"   → matches project:read, project:create, project:delete, etc.
+"project:read" → exact match only
+```
+
+---
+
+## Role Hierarchy
+
+Roles are ordered by definition — first role is highest rank:
+
+```ts
+const gh = createGatehouse({
+  roles: {
+    owner:  ["*"],          // rank 0 (highest)
+    admin:  ["project:*"],  // rank 1
+    member: ["task:*"],     // rank 2
+    viewer: ["task:read"],  // rank 3 (lowest)
+  },
+});
+
+gh.isAtLeast("owner", "admin");   // true — owner outranks admin
+gh.isAtLeast("viewer", "member"); // false — viewer is below member
+```
+
+---
+
+## TypeScript
+
+Full type inference from your config:
+
+```ts
+const gh = createGatehouse({
+  roles: {
+    owner: ["*"],
+    admin: ["project:*"],
+    viewer: ["project:read"],
+  },
+});
+
+// gh.can() only accepts roles you defined
+gh.can("owner", "anything");  // OK
+gh.can("superadmin", "x");    // Type error: "superadmin" is not a valid role
+```
+
+## License
+
+MIT

package/dist/adapters/authjs.d.ts

@@ -0,0 +1,32 @@
+import { c as GatehouseSubject } from '../types-1JY9ADLk.js';
+
+/**
+ * Auth.js (NextAuth) adapter for Gatehouse.
+ *
+ * Reads role from `session.user.role` (requires extending the session callback).
+ *
+ * ```ts
+ * // lib/gate.ts
+ * import { createServerGate } from "gatehouse/next";
+ * import { authjsResolver } from "gatehouse/adapters/authjs";
+ * import { gh } from "./gatehouse";
+ * import { auth } from "./auth"; // your Auth.js auth() export
+ *
+ * export const gate = createServerGate({
+ *   gatehouse: gh,
+ *   resolve: authjsResolver({ auth }),
+ * });
+ * ```
+ */
+declare function authjsResolver(options: {
+    /** The Auth.js `auth()` function. */
+    auth: () => Promise<{
+        user?: {
+            role?: string;
+        };
+    } | null>;
+    /** Default role for authenticated users. Default: "viewer" */
+    defaultRole?: string;
+}): () => Promise<GatehouseSubject | null>;
+
+export { authjsResolver };

package/dist/adapters/authjs.js

@@ -0,0 +1,14 @@
+// src/adapters/authjs.ts
+function authjsResolver(options) {
+  const defaultRole = options.defaultRole ?? "viewer";
+  return async () => {
+    const session = await options.auth();
+    if (!session?.user) return null;
+    return {
+      role: session.user.role ?? defaultRole
+    };
+  };
+}
+export {
+  authjsResolver
+};

package/dist/adapters/clerk.d.ts

@@ -0,0 +1,27 @@
+import { c as GatehouseSubject } from '../types-1JY9ADLk.js';
+
+/**
+ * Clerk adapter for Gatehouse.
+ *
+ * Reads role from Clerk's `publicMetadata.role` (the standard pattern).
+ *
+ * ```ts
+ * // lib/gate.ts
+ * import { createServerGate } from "gatehouse/next";
+ * import { clerkResolver } from "gatehouse/adapters/clerk";
+ * import { gh } from "./gatehouse";
+ *
+ * export const gate = createServerGate({
+ *   gatehouse: gh,
+ *   resolve: clerkResolver(),
+ * });
+ * ```
+ */
+declare function clerkResolver(options?: {
+    /** Custom metadata key for the role. Default: "role" */
+    roleKey?: string;
+    /** Default role for authenticated users with no role set. Default: "viewer" */
+    defaultRole?: string;
+}): () => Promise<GatehouseSubject | null>;
+
+export { clerkResolver };

package/dist/adapters/clerk.js

@@ -0,0 +1,15 @@
+// src/adapters/clerk.ts
+function clerkResolver(options) {
+  const roleKey = options?.roleKey ?? "role";
+  const defaultRole = options?.defaultRole ?? "viewer";
+  return async () => {
+    const { currentUser } = await import("@clerk/nextjs/server");
+    const user = await currentUser();
+    if (!user) return null;
+    const role = user.publicMetadata?.[roleKey];
+    return { role: role ?? defaultRole };
+  };
+}
+export {
+  clerkResolver
+};

package/dist/adapters/supabase.d.ts

@@ -0,0 +1,35 @@
+import { c as GatehouseSubject } from '../types-1JY9ADLk.js';
+
+/**
+ * Supabase adapter for Gatehouse.
+ *
+ * Reads role from `app_metadata.role` or a custom profiles table.
+ *
+ * ```ts
+ * // lib/gate.ts
+ * import { createServerGate } from "gatehouse/next";
+ * import { supabaseResolver } from "gatehouse/adapters/supabase";
+ * import { gh } from "./gatehouse";
+ * import { createClient } from "@/lib/supabase/server";
+ *
+ * export const gate = createServerGate({
+ *   gatehouse: gh,
+ *   resolve: supabaseResolver({ createClient }),
+ * });
+ * ```
+ */
+declare function supabaseResolver(options: {
+    /** Function that creates a Supabase server client. */
+    createClient: () => any;
+    /** Where to read the role from. Default: "app_metadata" */
+    source?: "app_metadata" | "user_metadata" | {
+        table: string;
+        column?: string;
+    };
+    /** Metadata key for the role. Default: "role" */
+    roleKey?: string;
+    /** Default role for authenticated users. Default: "viewer" */
+    defaultRole?: string;
+}): () => Promise<GatehouseSubject | null>;
+
+export { supabaseResolver };

package/dist/adapters/supabase.js

@@ -0,0 +1,27 @@
+// src/adapters/supabase.ts
+function supabaseResolver(options) {
+  const roleKey = options.roleKey ?? "role";
+  const defaultRole = options.defaultRole ?? "viewer";
+  return async () => {
+    const supabase = options.createClient();
+    const {
+      data: { user }
+    } = await supabase.auth.getUser();
+    if (!user) return null;
+    let role;
+    const source = options.source ?? "app_metadata";
+    if (source === "app_metadata") {
+      role = user.app_metadata?.[roleKey];
+    } else if (source === "user_metadata") {
+      role = user.user_metadata?.[roleKey];
+    } else {
+      const column = source.column ?? "role";
+      const { data } = await supabase.from(source.table).select(column).eq("user_id", user.id).single();
+      role = data?.[column];
+    }
+    return { role: role ?? defaultRole };
+  };
+}
+export {
+  supabaseResolver
+};

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { R as RoleDefinitions, G as GatehouseConfig, a as Gatehouse, P as PermissionPattern } from './types-1JY9ADLk.js';
+export { E as ExtractPermissions, b as ExtractRoles, c as GatehouseSubject } from './types-1JY9ADLk.js';
+
+/**
+ * Create a Gatehouse instance.
+ *
+ * ```ts
+ * const gh = createGatehouse({
+ *   roles: {
+ *     owner:  ["*"],
+ *     admin:  ["project:*", "member:invite", "member:remove"],
+ *     member: ["project:read", "project:create", "task:*"],
+ *     viewer: ["project:read", "task:read"],
+ *   },
+ * });
+ * ```
+ *
+ * Roles are hierarchical — first role is highest. An `owner` is "at least" an `admin`.
+ */
+declare function createGatehouse<T extends RoleDefinitions>(config: GatehouseConfig<T>): Gatehouse<T>;
+
+/**
+ * Check if a permission pattern matches a concrete permission.
+ *
+ * Patterns:
+ *   "*"           → matches everything
+ *   "project:*"   → matches "project:read", "project:create", etc.
+ *   "project:read" → exact match only
+ */
+declare function matchesPermission(pattern: PermissionPattern, permission: string): boolean;
+/**
+ * Check if any pattern in a list matches the given permission.
+ */
+declare function hasPermission(patterns: readonly PermissionPattern[], permission: string): boolean;
+
+export { Gatehouse, GatehouseConfig, PermissionPattern, RoleDefinitions, createGatehouse, hasPermission, matchesPermission };

package/dist/index.js

@@ -0,0 +1,66 @@
+// src/core/permissions.ts
+function matchesPermission(pattern, permission) {
+  if (pattern === "*") return true;
+  if (pattern === permission) return true;
+  if (pattern.endsWith(":*")) {
+    const prefix = pattern.slice(0, -1);
+    return permission.startsWith(prefix);
+  }
+  return false;
+}
+function hasPermission(patterns, permission) {
+  return patterns.some((p) => matchesPermission(p, permission));
+}
+
+// src/core/gatehouse.ts
+function createGatehouse(config) {
+  const roleNames = Object.keys(config.roles);
+  const roleRank = /* @__PURE__ */ new Map();
+  roleNames.forEach((name, i) => roleRank.set(name, i));
+  function resolveSubject(input) {
+    if (typeof input === "string") return { role: input };
+    return input;
+  }
+  function getPatterns(subject) {
+    const rolePatterns = config.roles[subject.role] ?? [];
+    if (!subject.permissions?.length) return rolePatterns;
+    return [...rolePatterns, ...subject.permissions];
+  }
+  function can(roleOrSubject, permission) {
+    const subject = resolveSubject(roleOrSubject);
+    return hasPermission(getPatterns(subject), permission);
+  }
+  function canAll(roleOrSubject, permissions) {
+    const subject = resolveSubject(roleOrSubject);
+    const patterns = getPatterns(subject);
+    return permissions.every((p) => hasPermission(patterns, p));
+  }
+  function canAny(roleOrSubject, permissions) {
+    const subject = resolveSubject(roleOrSubject);
+    const patterns = getPatterns(subject);
+    return permissions.some((p) => hasPermission(patterns, p));
+  }
+  function isAtLeast(roleA, roleB) {
+    const rankA = roleRank.get(roleA);
+    const rankB = roleRank.get(roleB);
+    if (rankA === void 0 || rankB === void 0) return false;
+    return rankA <= rankB;
+  }
+  function permissionsFor(role) {
+    return [...config.roles[role] ?? []];
+  }
+  return {
+    can,
+    canAll,
+    canAny,
+    isAtLeast,
+    permissionsFor,
+    roles: roleNames,
+    config: config.roles
+  };
+}
+export {
+  createGatehouse,
+  hasPermission,
+  matchesPermission
+};

package/dist/next.d.ts

@@ -0,0 +1,103 @@
+import { R as RoleDefinitions, a as Gatehouse, c as GatehouseSubject, b as ExtractRoles } from './types-1JY9ADLk.js';
+import { NextRequest, NextResponse } from 'next/server.js';
+
+/** Options for creating a server-side gate. */
+interface CreateServerGateOptions<T extends RoleDefinitions> {
+    gatehouse: Gatehouse<T>;
+    /**
+     * Resolve the current user from the request context.
+     * Return null if unauthenticated.
+     */
+    resolve: () => Promise<GatehouseSubject<ExtractRoles<T>> | null>;
+}
+declare class GatehouseError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Create a server-side gate for Next.js API routes and Server Components.
+ *
+ * ```ts
+ * // lib/gate.ts
+ * import { createServerGate } from "gatehouse/next";
+ * import { gh } from "./gatehouse";
+ * import { auth } from "./auth";
+ *
+ * export const gate = createServerGate({
+ *   gatehouse: gh,
+ *   resolve: async () => {
+ *     const session = await auth();
+ *     if (!session) return null;
+ *     return { role: session.user.role };
+ *   },
+ * });
+ * ```
+ *
+ * Then in API routes:
+ * ```ts
+ * export async function POST() {
+ *   const subject = await gate("project:create");
+ *   // subject is typed — guaranteed to have permission
+ * }
+ * ```
+ */
+declare function createServerGate<T extends RoleDefinitions>(options: CreateServerGateOptions<T>): {
+    (permission: string): Promise<GatehouseSubject<ExtractRoles<T>>>;
+    (): Promise<GatehouseSubject<ExtractRoles<T>>>;
+    all(permissions: string[]): Promise<GatehouseSubject<ExtractRoles<T>>>;
+    any(permissions: string[]): Promise<GatehouseSubject<ExtractRoles<T>>>;
+    role(role: ExtractRoles<T>): Promise<GatehouseSubject<ExtractRoles<T>>>;
+    check(permission?: string): Promise<GatehouseSubject<ExtractRoles<T>> | null>;
+};
+
+interface GatehouseMiddlewareConfig {
+    /**
+     * Routes that require authentication. Supports Next.js matcher patterns.
+     * e.g. ["/dashboard/:path*", "/api/projects/:path*"]
+     */
+    protected: string[];
+    /** Where to redirect unauthenticated users. Default: "/login" */
+    loginUrl?: string;
+    /**
+     * Check if the request is authenticated.
+     * Return true if authenticated, false otherwise.
+     */
+    isAuthenticated: (request: NextRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Create a Next.js middleware that protects routes.
+ *
+ * ```ts
+ * // middleware.ts
+ * import { createMiddleware } from "gatehouse/next";
+ *
+ * export default createMiddleware({
+ *   protected: ["/dashboard/:path*", "/api/projects/:path*"],
+ *   isAuthenticated: (req) => !!req.cookies.get("session"),
+ * });
+ *
+ * export const config = {
+ *   matcher: ["/dashboard/:path*", "/api/projects/:path*"],
+ * };
+ * ```
+ */
+declare function createMiddleware(options: GatehouseMiddlewareConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+/**
+ * Wrap a Next.js route handler to automatically catch GatehouseErrors
+ * and return proper HTTP responses.
+ *
+ * ```ts
+ * import { withGate } from "gatehouse/next";
+ * import { gate } from "@/lib/gate";
+ *
+ * export const POST = withGate(async () => {
+ *   const subject = await gate("project:create");
+ *   // ... create project
+ *   return NextResponse.json({ ok: true });
+ * });
+ * ```
+ */
+declare function withGate(handler: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+
+export { type CreateServerGateOptions, GatehouseError, type GatehouseMiddlewareConfig, createMiddleware, createServerGate, withGate };

package/dist/next.js

@@ -0,0 +1,105 @@
+// src/next/server.ts
+var GatehouseError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "GatehouseError";
+  }
+};
+function createServerGate(options) {
+  async function gate(permission) {
+    const subject = await options.resolve();
+    if (!subject) {
+      throw new GatehouseError("Unauthorized", 401);
+    }
+    if (permission && !options.gatehouse.can(subject, permission)) {
+      throw new GatehouseError("Forbidden", 403);
+    }
+    return subject;
+  }
+  gate.all = async function gateAll(permissions) {
+    const subject = await options.resolve();
+    if (!subject) throw new GatehouseError("Unauthorized", 401);
+    if (!options.gatehouse.canAll(subject, permissions)) {
+      throw new GatehouseError("Forbidden", 403);
+    }
+    return subject;
+  };
+  gate.any = async function gateAny(permissions) {
+    const subject = await options.resolve();
+    if (!subject) throw new GatehouseError("Unauthorized", 401);
+    if (!options.gatehouse.canAny(subject, permissions)) {
+      throw new GatehouseError("Forbidden", 403);
+    }
+    return subject;
+  };
+  gate.role = async function gateRole(role) {
+    const subject = await options.resolve();
+    if (!subject) throw new GatehouseError("Unauthorized", 401);
+    if (!options.gatehouse.isAtLeast(subject.role, role)) {
+      throw new GatehouseError("Forbidden", 403);
+    }
+    return subject;
+  };
+  gate.check = async function gateCheck(permission) {
+    const subject = await options.resolve();
+    if (!subject) return null;
+    if (permission && !options.gatehouse.can(subject, permission)) return null;
+    return subject;
+  };
+  return gate;
+}
+
+// src/next/middleware.ts
+import { NextResponse } from "next/server.js";
+function createMiddleware(options) {
+  const loginUrl = options.loginUrl ?? "/login";
+  return async function middleware(request) {
+    const isProtected = options.protected.some((pattern) => {
+      const regex = patternToRegex(pattern);
+      return regex.test(request.nextUrl.pathname);
+    });
+    if (!isProtected) {
+      return NextResponse.next();
+    }
+    const authenticated = await options.isAuthenticated(request);
+    if (!authenticated) {
+      if (request.nextUrl.pathname.startsWith("/api/")) {
+        return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+      }
+      const url = request.nextUrl.clone();
+      url.pathname = loginUrl;
+      url.searchParams.set("from", request.nextUrl.pathname);
+      return NextResponse.redirect(url);
+    }
+    return NextResponse.next();
+  };
+}
+function patternToRegex(pattern) {
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/:path\\\*/g, ".*").replace(/:\\w+/g, "[^/]+");
+  return new RegExp(`^${escaped}$`);
+}
+
+// src/next/catch.ts
+import { NextResponse as NextResponse2 } from "next/server.js";
+function withGate(handler) {
+  return async function wrappedHandler(request) {
+    try {
+      return await handler(request);
+    } catch (error) {
+      if (error instanceof GatehouseError) {
+        return NextResponse2.json(
+          { error: error.message },
+          { status: error.status }
+        );
+      }
+      throw error;
+    }
+  };
+}
+export {
+  GatehouseError,
+  createMiddleware,
+  createServerGate,
+  withGate
+};

package/dist/react.d.ts

@@ -0,0 +1,100 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { R as RoleDefinitions, a as Gatehouse, c as GatehouseSubject } from './types-1JY9ADLk.js';
+
+interface GatehouseContextValue<T extends RoleDefinitions = RoleDefinitions> {
+    gatehouse: Gatehouse<T>;
+    subject: GatehouseSubject | null;
+    loading: boolean;
+}
+interface GatehouseProviderProps<T extends RoleDefinitions> {
+    children: ReactNode;
+    gatehouse: Gatehouse<T>;
+    /**
+     * Resolve the current user's role. Called once on mount.
+     * Return `null` if user is not authenticated.
+     */
+    resolve: () => Promise<GatehouseSubject | null> | GatehouseSubject | null;
+}
+/**
+ * Provide RBAC context to your app.
+ *
+ * ```tsx
+ * <GatehouseProvider gatehouse={gh} resolve={() => ({ role: "admin" })}>
+ *   {children}
+ * </GatehouseProvider>
+ * ```
+ */
+declare function GatehouseProvider<T extends RoleDefinitions>({ children, gatehouse, resolve, }: GatehouseProviderProps<T>): react_jsx_runtime.JSX.Element;
+
+interface GateProps {
+    children: ReactNode;
+    /**
+     * Permission required. e.g. "project:create"
+     * Use `allow` for single permission, `allOf` for all, `anyOf` for any.
+     */
+    allow?: string;
+    /** Require ALL of these permissions. */
+    allOf?: string[];
+    /** Require ANY of these permissions. */
+    anyOf?: string[];
+    /** Require this role or higher. */
+    role?: string;
+    /** Shown when permission is denied. */
+    fallback?: ReactNode;
+    /** Shown while resolve() is loading. */
+    loading?: ReactNode;
+}
+/**
+ * Declarative permission gate.
+ *
+ * ```tsx
+ * <Gate allow="project:create">
+ *   <CreateButton />
+ * </Gate>
+ *
+ * <Gate role="admin" fallback={<p>Admin only</p>}>
+ *   <AdminPanel />
+ * </Gate>
+ *
+ * <Gate anyOf={["project:edit", "project:delete"]}>
+ *   <EditMenu />
+ * </Gate>
+ * ```
+ */
+declare function Gate({ children, allow, allOf, anyOf, role, fallback, loading: loadingFallback, }: GateProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Check a single permission.
+ *
+ * ```ts
+ * const canCreate = useGate("project:create");
+ * ```
+ */
+declare function useGate(permission: string): boolean;
+/**
+ * Get the current user's role.
+ *
+ * ```ts
+ * const role = useRole(); // "admin" | null
+ * ```
+ */
+declare function useRole(): string | null;
+/**
+ * Get all permissions for the current user's role.
+ *
+ * ```ts
+ * const perms = usePermissions(); // ["project:read", "project:create", ...]
+ * ```
+ */
+declare function usePermissions(): string[];
+/**
+ * Full access to the Gatehouse instance and current subject.
+ *
+ * ```ts
+ * const { gatehouse, subject, loading } = useGatehouse();
+ * ```
+ */
+declare function useGatehouse(): GatehouseContextValue<RoleDefinitions>;
+
+export { Gate, type GateProps, GatehouseProvider, type GatehouseProviderProps, useGate, useGatehouse, usePermissions, useRole };

package/dist/react.js

@@ -0,0 +1,108 @@
+// src/react/context.tsx
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var GatehouseContext = createContext(null);
+function GatehouseProvider({
+  children,
+  gatehouse,
+  resolve
+}) {
+  const [subject, setSubject] = useState(null);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    let cancelled = false;
+    Promise.resolve(resolve()).then((result) => {
+      if (!cancelled) {
+        setSubject(result);
+        setLoading(false);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [resolve]);
+  return /* @__PURE__ */ jsx(
+    GatehouseContext.Provider,
+    {
+      value: {
+        gatehouse,
+        subject,
+        loading
+      },
+      children
+    }
+  );
+}
+function useGatehouseContext() {
+  const ctx = useContext(GatehouseContext);
+  if (!ctx) {
+    throw new Error("useGatehouseContext must be used within <GatehouseProvider>");
+  }
+  return ctx;
+}
+
+// src/react/gate.tsx
+import { Fragment, jsx as jsx2 } from "react/jsx-runtime";
+function Gate({
+  children,
+  allow,
+  allOf,
+  anyOf,
+  role,
+  fallback = null,
+  loading: loadingFallback = null
+}) {
+  const { gatehouse, subject, loading } = useGatehouseContext();
+  if (loading) return /* @__PURE__ */ jsx2(Fragment, { children: loadingFallback });
+  if (!subject) return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  if (role && !gatehouse.isAtLeast(subject.role, role)) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  if (allow && !gatehouse.can(subject, allow)) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  if (allOf && !gatehouse.canAll(subject, allOf)) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  if (anyOf && !gatehouse.canAny(subject, anyOf)) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ jsx2(Fragment, { children });
+}
+
+// src/react/hooks.ts
+import { useMemo } from "react";
+function useGate(permission) {
+  const { gatehouse, subject } = useGatehouseContext();
+  return useMemo(
+    () => subject ? gatehouse.can(subject, permission) : false,
+    [gatehouse, subject, permission]
+  );
+}
+function useRole() {
+  const { subject } = useGatehouseContext();
+  return subject?.role ?? null;
+}
+function usePermissions() {
+  const { gatehouse, subject } = useGatehouseContext();
+  return useMemo(
+    () => subject ? gatehouse.permissionsFor(subject.role) : [],
+    [gatehouse, subject]
+  );
+}
+function useGatehouse() {
+  return useGatehouseContext();
+}
+export {
+  Gate,
+  GatehouseProvider,
+  useGate,
+  useGatehouse,
+  usePermissions,
+  useRole
+};

package/dist/types-1JY9ADLk.d.ts

@@ -0,0 +1,41 @@
+/** A permission string like "project:read" or "project:*" or "*" */
+type PermissionPattern = string;
+/** Role-to-permissions mapping. Keys are role names, values are permission arrays. */
+type RoleDefinitions = Record<string, readonly PermissionPattern[]>;
+/**
+ * Extract all concrete permission strings from a role definitions object.
+ * Excludes wildcards — those are matching patterns, not concrete permissions.
+ */
+type ExtractPermissions<T extends RoleDefinitions> = T[keyof T][number] extends infer P ? P extends `${string}*` ? never : P extends string ? P : never : never;
+/** Extract role names from a role definitions object. */
+type ExtractRoles<T extends RoleDefinitions> = keyof T & string;
+/** The resolved identity for permission checks. */
+interface GatehouseSubject<R extends string = string> {
+    role: R;
+    /** Optional extra permissions beyond what the role grants. */
+    permissions?: string[];
+}
+/** Configuration for createGatehouse(). */
+interface GatehouseConfig<T extends RoleDefinitions> {
+    /** Role definitions. First role is highest rank. Order defines hierarchy. */
+    roles: T;
+}
+/** The Gatehouse instance returned by createGatehouse(). */
+interface Gatehouse<T extends RoleDefinitions> {
+    /** Check if a role (or subject) has a specific permission. */
+    can: (roleOrSubject: ExtractRoles<T> | GatehouseSubject<ExtractRoles<T>>, permission: string) => boolean;
+    /** Check if a role has ALL listed permissions. */
+    canAll: (roleOrSubject: ExtractRoles<T> | GatehouseSubject<ExtractRoles<T>>, permissions: string[]) => boolean;
+    /** Check if a role has ANY of the listed permissions. */
+    canAny: (roleOrSubject: ExtractRoles<T> | GatehouseSubject<ExtractRoles<T>>, permissions: string[]) => boolean;
+    /** Check if roleA is at least as high as roleB in the hierarchy. */
+    isAtLeast: (roleA: ExtractRoles<T>, roleB: ExtractRoles<T>) => boolean;
+    /** Get all concrete permissions for a role. */
+    permissionsFor: (role: ExtractRoles<T>) => string[];
+    /** Ordered role names from highest to lowest. */
+    roles: ExtractRoles<T>[];
+    /** The raw role definitions. */
+    config: T;
+}
+
+export type { ExtractPermissions as E, GatehouseConfig as G, PermissionPattern as P, RoleDefinitions as R, Gatehouse as a, ExtractRoles as b, GatehouseSubject as c };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "gatehouse",
+  "version": "0.1.0",
+  "description": "Drop-in RBAC for Next.js. 5 lines to working permissions.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./adapters/clerk": {
+      "types": "./dist/adapters/clerk.d.ts",
+      "import": "./dist/adapters/clerk.js"
+    },
+    "./adapters/supabase": {
+      "types": "./dist/adapters/supabase.d.ts",
+      "import": "./dist/adapters/supabase.js"
+    },
+    "./adapters/authjs": {
+      "types": "./dist/adapters/authjs.d.ts",
+      "import": "./dist/adapters/authjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "next": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/node": "^22.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "rbac",
+    "permissions",
+    "authorization",
+    "nextjs",
+    "react",
+    "access-control",
+    "roles",
+    "gate"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatehouse-rbac/gatehouse"
+  }
+}