perm.h File Reference

Pluggable permission/access-control (ACL) driver interface. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	csilk_perm_driver_t
	Virtual function table for a permission/ACL driver. More...
struct	csilk_perm_rule_t
	A single permission rule for the built-in RBAC driver. More...

Functions
void	csilk_perm_init (void)
	Initialise the permission subsystem. Safe to call multiple times. Must be called before any driver operations.
int	csilk_perm_register_driver (const char *name, csilk_perm_driver_t *driver)
	Register a permission driver implementation.
csilk_perm_driver_t *	csilk_perm_get_driver (const char *name)
	Look up a registered driver by name.
int	csilk_perm_set_default (const char *name)
	Set the default permission driver used by csilk_perm_check.
int	csilk_perm_check (csilk_ctx_t *c, const char *permission, const char *resource)
	Check the current request against the default permission driver.
void	csilk_perm_require (csilk_ctx_t *c, const char *permission, const char *resource)
	Abort the handler chain with 403 Forbidden if the check fails. Convenience wrapper: calls csilk_perm_check and csilk_abort on denial.
void	csilk_perm_simple_init (void)
	Initialise the built-in in-memory RBAC driver. Registers as "simple". Must be called before any simple_* functions.
int	csilk_perm_simple_allow (const char *role, const char *permission, const char *resource)
	Grant a permission on a resource to a role.
void	csilk_perm_simple_clear (void)
	Remove all rules from the simple driver. After calling this, all checks will deny until new rules are added.
void	csilk_perm_auto_middleware (csilk_ctx_t *c)
	Automatic permission-check middleware. Looks up the permission and resource from the route's metadata (registered via csilk_router_add_perm) and checks them. Aborts with 403 if the check fails. Safe to call even if the route has no permission metadata (passes through).

Detailed Description

Pluggable permission/access-control (ACL) driver interface.

Provides an abstraction layer for role-based access control (RBAC) or relationship-based access control (ReBAC). Routes can declare required permissions and resources via route-registration metadata (e.g., csilk_router_add_perm). A pluggable driver evaluates whether the authenticated user (identified in the request context) has the required permission on the target resource.

Built-in: csilk_perm_simple_* provides an in-memory RBAC implementation.

Copyright

MIT License

---

Data Structure Documentation

csilk_perm_rule_t

struct csilk_perm_rule_t

A single permission rule for the built-in RBAC driver.

Associates a role with a permission on a resource pattern. Rules are managed via csilk_perm_simple_allow / csilk_perm_simple_clear.

Data Fields
const char *	permission	Action/permission string (e.g., "read").
const char *	resource	Resource pattern (e.g., "articles:*").
const char *	role	Role identifier (e.g., "admin", "editor").

Function Documentation

csilk_perm_auto_middleware()

void csilk_perm_auto_middleware

(

csilk_ctx_t *

c

)

Automatic permission-check middleware. Looks up the permission and resource from the route's metadata (registered via csilk_router_add_perm) and checks them. Aborts with 403 if the check fails. Safe to call even if the route has no permission metadata (passes through).

Automatic permission-check middleware. Looks up the permission and resource from the route's metadata (registered via csilk_router_add_perm) and checks them. Aborts with 403 if the check fails. Safe to call even if the route has no permission metadata (passes through).

Reads perm_required and perm_resource from the current handler metadata (set via csilk_app_add_route_extended_perm or the *_perm variants). If the route has a permission requirement, enforces it via csilk_perm_require().

Parameters

c	The request context.

Note

This middleware is designed to be registered with csilk_app_use() or csilk_server_use(). It is a no-op for routes without permission metadata.

csilk_perm_check()

int csilk_perm_check	(	csilk_ctx_t *	c,
		const char *	permission,
		const char *	resource
	)

Check the current request against the default permission driver.

Parameters

c	Request context.
permission	Permission to check.
resource	Resource to check.

Returns

1 if allowed, 0 if denied, -1 on error (or no driver set).

Check the current request against the default permission driver.

Delegates to the default driver's check() callback.

Parameters

c	The request context.
permission	Permission identifier (e.g., "read", "write").
resource	Resource pattern (e.g., "users:*").

Returns

0 if allowed, non-zero if denied or no driver is set.

csilk_perm_get_driver()

csilk_perm_driver_t * csilk_perm_get_driver

(

const char *

name

)

Look up a registered driver by name.

Parameters

name	Driver identifier string.

Returns

The registered driver vtable, or NULL if not found.

Look up a registered driver by name.

Linear search of the driver registry.

Parameters

name	Driver name to find (case-sensitive).

Returns

Driver pointer, or NULL if not found.

csilk_perm_init()

void csilk_perm_init

(

void

)

Initialise the permission subsystem. Safe to call multiple times. Must be called before any driver operations.

Initialise the permission subsystem. Safe to call multiple times. Must be called before any driver operations.

Installs the built-in "simple" permission driver on first call. Idempotent via atomic CAS — subsequent calls are no-ops.

Note

Must be called before any authorization checks.

csilk_perm_register_driver()

int csilk_perm_register_driver	(	const char *	name,
		csilk_perm_driver_t *	driver
	)

Register a permission driver implementation.

Parameters

name	Unique driver name (must not already be registered).
driver	Pointer to driver vtable (must remain valid for program lifetime).

Returns

0 on success, -1 if name is already registered.

Register a permission driver implementation.

The first registered driver automatically becomes the default.

Parameters

name	Driver name (e.g., "simple", "rbac").
driver	Driver vtable with check() callback.

Returns

0 on success, -1 if name is NULL, driver is NULL, or the registry is full.

csilk_perm_require()

void csilk_perm_require	(	csilk_ctx_t *	c,
		const char *	permission,
		const char *	resource
	)

Abort the handler chain with 403 Forbidden if the check fails. Convenience wrapper: calls csilk_perm_check and csilk_abort on denial.

Parameters

c	Request context.
permission	Permission to check.
resource	Resource to check.

Abort the handler chain with 403 Forbidden if the check fails. Convenience wrapper: calls csilk_perm_check and csilk_abort on denial.

Calls csilk_perm_check() and sends a 403 Forbidden JSON response followed by csilk_abort() if the check fails.

Parameters

c	The request context.
permission	Permission to require.
resource	Resource to check against.

csilk_perm_set_default()

int csilk_perm_set_default

(

const char *

name

)

Set the default permission driver used by csilk_perm_check.

Parameters

name	Driver identifier.

Returns

0 on success, -1 if name is not registered.

Set the default permission driver used by csilk_perm_check.

Parameters

name	Driver name (must be already registered).

Returns

0 on success, -1 if the driver is not found.

csilk_perm_simple_allow()

int csilk_perm_simple_allow	(	const char *	role,
		const char *	permission,
		const char *	resource
	)

Grant a permission on a resource to a role.

Parameters

role	Role name (e.g., "admin").
permission	Permission string (e.g., "write").
resource	Resource pattern (e.g., "articles:*").

Returns

1 if the rule was added, 0 if it already existed.

Grant a permission on a resource to a role.

Parameters

role	Role identifier (may contain wildcards).
permission	Permission name (may contain wildcards).
resource	Resource pattern (may contain wildcards).

Returns

0 on success, -1 if the table is full or parameters are NULL.

csilk_perm_simple_clear()

void csilk_perm_simple_clear

(

void

)

Remove all rules from the simple driver. After calling this, all checks will deny until new rules are added.

Remove all rules from the simple driver. After calling this, all checks will deny until new rules are added.

csilk_perm_simple_init()

void csilk_perm_simple_init

(

void

)

Initialise the built-in in-memory RBAC driver. Registers as "simple". Must be called before any simple_* functions.

Initialise the built-in in-memory RBAC driver. Registers as "simple". Must be called before any simple_* functions.