Usage on client

Install the @kilpi/client package

npm install @kilpi/client

yarn add @kilpi/client

pnpm add @kilpi/client

bun add @kilpi/client

Setup environment variables

Create public environment variables (e.g. with PUBLIC_, NEXT_PUBLIC_ or similar prefix to ensure they are included in the client bundle).

PUBLIC_KILPI_URL=http://localhost:3000/api/kilpi
PUBLIC_KILPI_SECRET=generate-secret

Install EndpointPlugin

The Kilpi client requires an endpoint for fetching authorization decisions. Use the EndpointPlugin from @kilpi/core to create an authorization endpoint. It exposes the Kilpi.$createPostEndpoint() function, which constructs a web-standard request-response function to use as your endpoint.

import { createKilpi, EndpointPlugin } from "@kilpi/core";

export const Kilpi = createKilpi({
  ...,
  plugins: [
   EndpointPlugin({
     secret: process.env.PUBLIC_KILPI_SECRET,
     // Optional
     getContext(request) { ... },
     async onBeforeHandleRequest(request) { ... },
     async onBeforeProcessItem(requestItem) { ... },
   })
 ]
})

Read more about the EndpointPlugin for more information on the setup options.

Setup the authorization endpoint

Expose the endpoint using your framework of choice.

export const POST = Kilpi.$createPostEndpoint();

const endpoint = Kilpi.$createPostEndpoint();

app.post('/api/kilpi', async (c) => await endpoint(c.req.raw));

Create your KilpiClient instance

Create your KilpiClient instance with createKilpiClient. This object is used to fetch authorization decisions from the server.

Optionally, pass infer for improved type safety, and add any plugins via plugins.

import type { Kilpi } from "./kilpi.ts";

export const KilpiClient = createKilpiClient({
  // Infer subject and policies from server instance
  infer: {} as typeof Kilpi,
  // Connect to the endpoint
  connect: {
    endpointUrl: process.env.PUBLIC_KILPI_URL,
    secret: process.env.PUBLIC_KILPI_SECRET,
  },
});

Fetch authorization decisions on the client

Now you can use KilpiClient to fetch authorization decisions from the server with a similar API as on the server.

KilpiClient automatically provides request caching, batching and deduplication for performance.

// Similar decision object as on the server
const decision = await KilpiClient.posts.edit(myPost).authorize();

Use with your frontend framework

You can use @kilpi/client with your frontend framework of choice or use one of the provided plugins that provide e.g. components and other useful bindings for KilpiClient.

import { KilpiClient } from "./kilpi-client";
const { AuthorizeClient } = KilpiClient.$createReactClientComponents();

export function Component({ post }: { post: Post }) {
  // Use via hooks
  const { granted } = KilpiClient.posts.create().useAuthorize();

  // Or components
  return (
    <AuthorizeClient policy={KilpiClient.posts.delete(post)}>
      <DeletePostForm />
    </AuthorizeClient>
  );
}