@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/authorization/index.d.ts

@@ -0,0 +1,129 @@
+import { f as Policy$1, A as AuthUser, a as AuthorizationResponse, G as Gate, b as AuthorizeOptions } from '../Gate-CNkBYf8m.js';
+export { c as GateCallback, d as GateDefinition, e as GateOptions, P as PolicyClass, g as PolicyMethod, h as PolicyRegistration, i as ResourceAction, R as Response, j as ResponseBuilder, k as authorize, l as can, m as cannot, n as createGate, o as defineGate, p as getGate, s as setGate } from '../Gate-CNkBYf8m.js';
+import { Context } from 'hono';
+import { M as Middleware } from '../index-9_Jzj5jo.js';
+
+/**
+ * Base policy class for model authorization.
+ *
+ * @example
+ * ```typescript
+ * class PostPolicy extends Policy {
+ *   // Runs before all checks - return true/false to short-circuit
+ *   before(user: AuthUser | null, ability: string) {
+ *     if (user?.role === 'admin') {
+ *       return true // Admins can do anything
+ *     }
+ *     return undefined // Continue to specific check
+ *   }
+ *
+ *   viewAny(user: AuthUser | null) {
+ *     return true // Anyone can view posts list
+ *   }
+ *
+ *   view(user: AuthUser | null, post: Post) {
+ *     return post.published || user?.id === post.authorId
+ *   }
+ *
+ *   create(user: AuthUser | null) {
+ *     return user !== null
+ *   }
+ *
+ *   update(user: AuthUser | null, post: Post) {
+ *     return user?.id === post.authorId
+ *   }
+ *
+ *   delete(user: AuthUser | null, post: Post) {
+ *     return user?.id === post.authorId
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Policy implements Policy$1 {
+    /**
+     * Perform pre-authorization checks.
+     * Return true to allow, false to deny, undefined to continue to specific check.
+     */
+    before?(user: AuthUser | null, ability: string): boolean | undefined | Promise<boolean | undefined>;
+    /**
+     * Allow the action.
+     */
+    protected allow(message?: string): AuthorizationResponse;
+    /**
+     * Deny the action.
+     */
+    protected deny(message?: string, code?: string): AuthorizationResponse;
+    /**
+     * Deny with a specific HTTP status.
+     */
+    protected denyWithStatus(status: number, message?: string): AuthorizationResponse & {
+        status: number;
+    };
+    /**
+     * Deny as not found (404).
+     */
+    protected denyAsNotFound(message?: string): AuthorizationResponse & {
+        status: 404;
+    };
+}
+/**
+ * Create a simple policy from an object.
+ */
+declare function definePolicy<T>(definition: {
+    before?: (user: AuthUser | null, ability: string) => boolean | undefined | Promise<boolean | undefined>;
+    viewAny?: (user: AuthUser | null) => boolean | Promise<boolean>;
+    view?: (user: AuthUser | null, model: T) => boolean | Promise<boolean>;
+    create?: (user: AuthUser | null) => boolean | Promise<boolean>;
+    update?: (user: AuthUser | null, model: T) => boolean | Promise<boolean>;
+    delete?: (user: AuthUser | null, model: T) => boolean | Promise<boolean>;
+    restore?: (user: AuthUser | null, model: T) => boolean | Promise<boolean>;
+    forceDelete?: (user: AuthUser | null, model: T) => boolean | Promise<boolean>;
+} & Record<string, ((user: AuthUser | null, ...args: any[]) => boolean | undefined | Promise<boolean | undefined>) | undefined>): new () => Policy;
+
+/**
+ * Middleware to authorize an ability.
+ *
+ * @example
+ * ```typescript
+ * // Authorize a simple ability
+ * app.get('/admin', authorizeMiddleware('admin'), adminHandler)
+ *
+ * // Authorize with model (from route param)
+ * app.put('/posts/:id', authorizeMiddleware('update', getPost), updateHandler)
+ *
+ * // Multiple abilities (any)
+ * app.get('/dashboard', authorizeMiddleware(['admin', 'moderator']), dashboardHandler)
+ * ```
+ */
+declare function authorizeMiddleware(ability: string | string[], modelResolver?: (ctx: Context) => unknown | Promise<unknown>, options?: AuthorizeOptions): Middleware;
+/**
+ * Middleware to authorize all given abilities.
+ */
+declare function authorizeAllMiddleware(abilities: string[], modelResolver?: (ctx: Context) => unknown | Promise<unknown>, options?: AuthorizeOptions): Middleware;
+/**
+ * Middleware factory for resource authorization.
+ * Automatically maps HTTP methods to policy abilities.
+ *
+ * @example
+ * ```typescript
+ * // Authorize resource actions based on HTTP method
+ * app.use('/posts/:id', authorizeResourceMiddleware(getPost))
+ * // GET -> view, POST -> create, PUT/PATCH -> update, DELETE -> delete
+ * ```
+ */
+declare function authorizeResourceMiddleware(modelResolver: (ctx: Context) => unknown | Promise<unknown>, options?: AuthorizeOptions): Middleware;
+/**
+ * Create a gate-aware context with authorization helpers.
+ */
+declare function withAuthorization(gate: Gate): Middleware;
+/**
+ * Helper type for context with authorization.
+ */
+interface AuthorizedContext extends Context {
+    get(key: 'gate'): Gate;
+    get(key: 'can'): (ability: string, ...args: unknown[]) => Promise<boolean>;
+    get(key: 'cannot'): (ability: string, ...args: unknown[]) => Promise<boolean>;
+    get(key: 'authorize'): (ability: string, ...args: unknown[]) => Promise<void>;
+}
+
+export { AuthUser, AuthorizationResponse, AuthorizeOptions, type AuthorizedContext, Gate, Policy, Policy$1 as PolicyInterface, authorizeAllMiddleware, authorizeMiddleware, authorizeResourceMiddleware, definePolicy, withAuthorization };