);
}
```
### AuthorizeClient Component - Client-Side Conditional Rendering
Client component for conditional rendering based on authorization with render props and loading states.
```tsx
import { AuthorizeClient, KilpiClient } from "@/kilpi.client";
import type { Article } from "@/types";
function ArticleManagement({ article }: { article: Article }) {
return (
{/* Render update button only if authorized */}
Checking permissions...
}
Unauthorized={(decision) => (
)}
>
{/* Delete button with authorization */}
Loading...
}
Unauthorized={(decision) => (
Cannot delete: {decision?.message}
)}
>
{/* Using render function for more complex logic */}
}
Unauthorized={() => null}
>
{({ decision }) => (
Authorized as: {decision.subject.name}
)}
);
}
// Example: Combining with other client state
function EditableArticle({ article }: { article: Article }) {
const [isEditing, setIsEditing] = useState(false);
return (
);
}
```
### Custom Plugin Development - Extend Functionality
Create custom plugins to extend Kilpi's core and client functionality with type-safe APIs.
```typescript
import { createKilpiPlugin, type AnyKilpiCore } from "@kilpi/core";
import { createKilpiClientPlugin, type KilpiClient } from "@kilpi/client";
// Server-side plugin example
function RateLimitPlugin(options: { maxRequests: number; windowMs: number }) {
const requestCounts = new Map();
return createKilpiPlugin((Kilpi: AnyKilpiCore) => {
// Hook into authorization lifecycle
Kilpi.$hooks.onAfterAuthorization((event) => {
const subjectId = event.subject?.id || "anonymous";
const now = Date.now();
const record = requestCounts.get(subjectId);
if (!record || now > record.reset) {
requestCounts.set(subjectId, {
count: 1,
reset: now + options.windowMs
});
} else {
record.count++;
if (record.count > options.maxRequests) {
throw new Error("Rate limit exceeded");
}
}
});
return {
// Extend core instance with custom methods
extendCore() {
return {
$getRateLimitStatus(subjectId: string) {
return requestCounts.get(subjectId);
},
$resetRateLimit(subjectId: string) {
requestCounts.delete(subjectId);
}
};
}
};
});
}
// Client-side plugin example
function ClientMetricsPlugin() {
const metrics = {
totalRequests: 0,
cacheHits: 0,
cacheMisses: 0
};
return createKilpiClientPlugin((Client: KilpiClient) => {
return {
// Extend client instance
extendClient() {
return {
$getMetrics() {
return { ...metrics };
},
$resetMetrics() {
metrics.totalRequests = 0;
metrics.cacheHits = 0;
metrics.cacheMisses = 0;
}
};
},
// Extend each policy proxy
extendPolicy(policy) {
const originalAuthorize = policy.authorize;
return {
// Override authorize to track metrics
async authorize() {
metrics.totalRequests++;
const result = await originalAuthorize.call(policy);
return result;
}
};
}
};
});
}
// Usage
const Kilpi = createKilpi({
// ... config
plugins: [
RateLimitPlugin({ maxRequests: 100, windowMs: 60000 })
]
});
// Access custom methods
const status = Kilpi.$getRateLimitStatus("user-123");
Kilpi.$resetRateLimit("user-123");
const KilpiClient = createKilpiClient({
// ... config
plugins: [ClientMetricsPlugin()]
});
// Access custom methods
const metrics = KilpiClient.$getMetrics();
console.log("Cache hit rate:", metrics.cacheHits / metrics.totalRequests);
```
## Summary and Integration
Kilpi provides a comprehensive solution for implementing authorization in TypeScript applications with support for both server-side and client-side authorization checks. The framework excels in full-stack scenarios where you need to enforce authorization at multiple layers: protecting API endpoints and database queries on the server while also providing responsive UI that reflects user permissions. Common use cases include multi-tenant SaaS applications where different users have varying access levels to resources, content management systems with complex permission hierarchies, and collaborative platforms where access control is based on both roles and resource ownership.
The integration pattern follows a clear separation between server and client implementations. On the server, you define your authorization policies in `createKilpi()` with the `getSubject()` function connecting to your authentication provider. These policies evaluate permissions based on the subject (authenticated user) and optionally a resource object. The server exposes an HTTP endpoint via `EndpointPlugin` which the client SDK communicates with. On the client side, `createKilpiClient()` provides the same policy interface but makes requests to the server endpoint, intelligently batching multiple checks together and caching results. React integrations provide both server components (``) and client hooks (`useAuthorize()`) for conditional rendering, creating a seamless authorization experience across the full stack. The plugin architecture allows extending both core and client functionality for custom requirements like audit logging, rate limiting, or specialized caching strategies.