Kilpi

https://github.com/jussinevavuori/kilpi
Admin
Kilpi is an open-source TypeScript authorization library offering flexible, powerful, and intuitive...
Tokens:35,622
Snippets:404
Trust Score:7.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Bootstrap the Kilpi Next.js demo with bun run bootstrap

Source: https://github.com/jussinevavuori/kilpi/blob/main/examples/next-js/README.md

Run this command in the project root to set up the demo. It initializes the .env file, migrates and seeds the local SQLite database at demo-db.sqlite, installs dependencies, and builds and starts the Next.js application. Requires Bun to be installed.

```bash
bun run bootstrap
```

--------------------------------

### Install @kilpi/client with bun

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Install the @kilpi/client package using bun.

```bash
bun add @kilpi/client
```

--------------------------------

### Initialize Kilpi instance

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/express.mdx

Create the Kilpi instance using the createKilpi function as described in the quickstart guide.

```ts
export const Kilpi = createKilpi({ ... })
```

--------------------------------

### Install @kilpi/client with npm

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Install the @kilpi/client package using npm.

```bash
npm install @kilpi/client
```

--------------------------------

### Install @kilpi/client with pnpm

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Install the @kilpi/client package using pnpm.

```bash
pnpm add @kilpi/client
```

--------------------------------

### Install @kilpi/client with yarn

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Install the @kilpi/client package using yarn.

```bash
yarn add @kilpi/client
```

--------------------------------

### Install Kilpi with bun

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

Install the Kilpi core library using the bun package manager.

```bash
bun add @kilpi/core
```

--------------------------------

### Kilpi setup: subject, policies, instance, and protected deletion

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-24-introducing-kilpi.mdx

Setup steps for Kilpi: define a subject, policies, create the Kilpi instance, and protect a deletion. The subject.ts file connects the auth provider; policies.ts defines the documents:delete policy; kilpi.ts creates the instance; document-service.ts uses Kilpi.authorize to protect deletion.

```ts
// subject.ts
import { getSessionFromMyAuthProvider } from "./my-auth-provider";

export type Subject = { id: string; name: string };

export async function getSubject() {
  const session = await getSessionFromMyAuthProvider();
  if (!session) return null;
  return { id: session.userId, name: session.userName };
}
```

```ts
// policies.ts
import { deny, grant, type Policyset } from "@kilpi/core";
import { Subject } from "./subject";

function hasOrgRole(subject: Subject, orgId: string, role: OrgRole): Promise<boolean> { ... }

export const policies = {
  documents: {
    async delete(user, doc: Document) {
      if (!user) return deny({ message: "Unauthenticated" });

      if (user.role === "superadmin") return grant(user);
      if (user.id === doc.authorId) return grant(user);
      if (await hasOrgRole(user, doc.orgId, "admin")) return grant(user);

      return deny();
    }
  }
} as const satisfies Policyset<Subject | null>
```

```ts
// kilpi.ts
import { createKilpi } from "@kilpi/core";
import { policies } from "./policies";
import { getSubject } from "./subject";

export const Kilpi = createKilpi({ policies, getSubject });
```

```ts
// document-service.ts
import { Kilpi } from "./kilpi";

async function deleteDocument(id: string) {
  const document = await db.getDocument(id);
  await Kilpi.authorize("documents:delete", document);
  await db.deleteDocument(id);
}
```

--------------------------------

### Install Kilpi with pnpm

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

Install the Kilpi core library using the pnpm package manager.

```bash
pnpm add @kilpi/core
```

--------------------------------

### Install @kilpi/react-client with npm, yarn, pnpm, or bun

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-client.mdx

Install the React Client Plugin with your preferred package manager. The plugin is required before using the provided components and hooks.

```bash
npm install @kilpi/react-client
```

```bash
yarn add @kilpi/react-client
```

```bash
pnpm add @kilpi/react-client
```

```bash
bun add @kilpi/react-client
```

--------------------------------

### Install Kilpi with yarn

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

Install the Kilpi core library using the yarn package manager.

```bash
yarn add @kilpi/core
```

--------------------------------

### Install Kilpi with npm

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

Install the Kilpi core library using the npm package manager.

```bash
npm install @kilpi/core
```

--------------------------------

### Install @kilpi/react-server with npm, yarn, pnpm, or bun

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/next-js.mdx

Install the @kilpi/react-server package using your preferred package manager. The plugin automatically caches the subject with React.cache, provides React Server Components, and adds the Kilpi.$onUnauthorizedRscAssert method.

```bash
npm install @kilpi/react-server
```

```bash
yarn add @kilpi/react-server
```

```bash
pnpm add @kilpi/react-server
```

```bash
bun add @kilpi/react-server
```

--------------------------------

### Install @kilpi/core@latest with npm, yarn, pnpm, or bun

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Install or update the latest version of @kilpi/core using your preferred package manager. The comment reminds you to also update other @kilpi/* packages to @latest.

```bash
# Update other @kilpi/* packages to @latest as well
npm install @kilpi/core@latest
```

```bash
# Update other @kilpi/* packages to @latest as well
yarn add @kilpi/core@latest
```

```bash
# Update other @kilpi/* packages to @latest as well
pnpm add @kilpi/core@latest
```

```bash
# Update other @kilpi/* packages to @latest as well
bun add @kilpi/core@latest
```

--------------------------------

### Protect UI with <Authorize />

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/next-js.mdx

Protect your UI with the <Authorize /> component. This example always allows access, but you can replace the policy with your own.

```tsx
export default async function DashboardPage() {
  return (
    <Authorize policy={Kilpi.always()}>
      <Dashboard />
    </Authorize>
  );
}
```

--------------------------------

### Future Datadog integration example

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Illustrates a potential future integration for Datadog built on top of AuditPlugin. This is an example of how an integration might look, not a current feature.

```ts
plugins: [
  DatadogAuditPlugin({
    apiKey: process.env.DATADOG_API_KEY,
    // ...
  }),
];
```

--------------------------------

### Create Kilpi authorization system

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

Creates a Kilpi instance with a subject adapter and example policies. Replace the getSubject implementation with a call to your authentication provider and add your policies or test with the example policies.

```ts
// src/kilpi.ts
import { createKilpi, Grant, Deny } from "@kilpi/core";

export const Kilpi = createKilpi({
  // (1) Your subject adapter with optional `ctx` param.
  async getSubject(ctx?: MyContextType) {
    return await myAuthenticationProvider.getCurrentUser(ctx);
  },

  // (2) Your policies
  policies: {
    posts: {
      // "All authenticated users can create posts"
      async create(subject) {
        if (!subject) return Deny();
        return Grant(subject);
      },
      // "Post can only be deleted by the author"
      async delete(subject, post: { authorId: string }) {
        if (!subject) return Deny();
        if (subject.id !== post.authorId) return Deny();
        return Grant(subject);
      },
    },
  },
});
```

--------------------------------

### Configure batch strategy with batchTimeoutSeconds

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Recommended strategy. Starts a batch on the first event, adds subsequent events until batchTimeoutSeconds expires, then sends all events in the batch. Use Kilpi.$audit.flush() to prematurely flush the current batch.

```ts
AuditPlugin({
  strategy: "batch",
  batchTimeoutSeconds: 5,
  async onFlushEvents(events) { ... },
})
```

--------------------------------

### Setup AsyncLocalStorage to provide Koa context (app.ts)

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/koa.mdx

Checks whether the runtime supports `async_hooks` before using this approach. This code exports an `AsyncLocalStorage` instance and uses a middleware to provide the context to all code running inside it.

```ts
// app.ts
import { AsyncLocalStorage } from "async_hooks";

export const ctxStorage = new AsyncLocalStorage<Context>();

app.use(async (ctx, next) => {
  await ctxStorage.run(ctx, async () => {
    await next();
  });
});
```

--------------------------------

### Server action with Kilpi.authorize

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-28-how-to-protect-nextjs-server-actions.mdx

Server action using Kilpi.authorize to replace the manual authentication and authorization checks. The action now delegates authorization to the centralized policy, making it a one-liner. This is the improved version of the earlier manual example.

```ts
"use server";

export async function deleteComment(id: string) {
  await Kilpi.authorize("comments:delete", id);

  await sql`DELETE FROM comments WHERE id = ${id}`;
}
```

--------------------------------

### Creating a custom client-side plugin with createKilpiClientPlugin

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/advanced/plugin.mdx

Creates a client-side Kilpi plugin that adds a $sayHello method to the client and a sayHello method to policies. It includes TypeScript boilerplate for extending the policy interface via module augmentation. Install it in the plugins array of createKilpiClient and use KilpiClient.$sayHello() or KilpiClient.posts.edit(post).sayHello().

```ts
import { createKilpiCorePlugin, type AnyKilpiCore } from "@kilpi/core";
import type { KilpiClient } from "@kilpi/client";
// Boilerplate if exteending the policy interface:
//   The type of a KilpiClientPolicy extension
export interface KilpiClientPolicyExtension_SayHelloPlugin<
  TClient extends AnyKilpiClient,
  TAction extends PolicysetActions<TClient["$$infer"]["policies"]>,
> {
  sayHello(): void;
}

// Boilerplate if exteending the policy interface:
//   Augment KilpiClientPolicy with extension.
declare module "@kilpi/client" {
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
  export interface IKilpiClientPolicy<
    TClient extends AnyKilpiClient,
    TAction extends PolicysetActions<TClient["$$infer"]["policies"]>,
  > extends KilpiClientPolicyExtension_SayHelloPlugin<TClient, TAction> {}
}
// Plugin constructor is a generic function of <T extends AnyKilpiCore>
// and can take any configuration options needed.
function SayHelloPlugin<T extends AnyKilpiCore>(opts: { name: string }) {
  // The constructor must return a kilpi client plugin with the `createKilpiClientPlugin`
  // function which provides the KilpiClient as an argument.
  return createKilpiClientPlugin((Client: KilpiClient<T>) => {
    // Return optional extensions on the public KilpiClient interface
    // and the policy interfaces.Please prefix at least your root-level APIs
    // with "$" to avoid naming conflicts (not requred for policies).
    return {
      // Function which returns an extension on the KilpiClient
      // instance itself.
      extendClient() {
        return {
          $sayHello() {
            console.log(`Hello from ${opts.name}`);
          },
        };
      },
      // Function which returns an extension on the policies.
      // This function must implement the extension defined in
      // `KilpiClientPolicyExtension_SayHelloPlugin` with access
      // to the policy.
      extendPolicy(policy) {
        return {
          sayHello() {
            console.log(`Hello from ${policy.$action}`);
          },
        } satisfies KilpiClientPolicyExtension_SayHelloPlugin<
          // Required TypeScript boilerplate
          KilpiClient<TCore>,
          PolicysetActions<TCore["$$infer"]["policies"]>
        >;
      },
    };
  });
}

// Install the plugin
const KilpiClient = createKilpiClient({
  ...,
  plugins: [SayHelloPlugin({ name: "MyKilpiClient" })],
});

// Use the plugin
KilpiClient.$sayHello(); // Hello from MyKilpiClient
KilpiClient.posts.edit(post).sayHello(); // Hello from posts.edit
```

--------------------------------

### Next.js page using protected queries and throwing

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/protected-queries.mdx

Example of a Next.js page that uses protected queries and throws on unauthorized, reducing boilerplate authorization logic.

```ts
export default async function PostPage(props: PageProps<"/posts/[id]">) {
  const { id } = await props.params;

  const { subject } = await Kilpi.authed().authorize().assert();

  const post = await getPost.authorized(id);
  const comments = await listComments.authorized(id);

  return (...);
}
```

--------------------------------

### Creating a custom server-side plugin with createKilpiCorePlugin

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/advanced/plugin.mdx

Creates a server-side Kilpi plugin that counts authorizations and exposes a $logCount method. The plugin uses the createKilpiCorePlugin function, hooks into onAfterAuthorization, and returns an extension via extendCoreApi. Install it in the plugins array of createKilpi and call Kilpi.$logCount() to log the count.

```ts
import { createKilpiCorePlugin, type AnyKilpiCore } from "@kilpi/core";

// Plugin constructor is a generic function of <T extends AnyKilpiCore>
// and can take any configuration options needed.
function CounterPlugin<T extends AnyKilpiCore>(opts: { message: string }) {
  // The constructor must return a kilpi core plugin with the `createKilpiCorePlugin`
  // function which provides the Kilpi instance as an argument.
  return createKilpiCorePlugin((Kilpi: T) => {
    // Internal state
    let count = 0;

    // Access hooks on the Kilpi instance itself
    Kilpi.$hooks.onAfterAuthorization(() => {
      count++;
    });

    // Return optional extensions on the public Kilpi interface.
    // Please prefix at least your root-level APIs with "$" to avoid
    // naming conflicts.
    return {
      // Function which returns an extension on the Kilpi instance itself
      extendCoreApi() {
        return {
          $logCount() {
            console.log(opts.message.replace("%", count.toString()));
          },
        };
      },
    };
  });
}

// Install the plugin
const Kilpi = createKilpi({
  getSubject,
  policies,
  plugins: [CounterPlugin({ message: "% authorizations made!" })],
});

// Use the plugin
Kilpi.$logCount(); // "10 authorizations made!"
```

--------------------------------

### Handle denial reasons with onUnauthorizedAssert and Deny()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/authorizing.mdx

Use this snippet to handle different denial reasons in the global onUnauthorizedAssert handler. The Deny() function can attach a reason and metadata, which are then used to customize the response, such as redirecting unauthenticated users to /sign-in or redirecting non-subscribed users to /subscribe with the required tier. The example shows a posts.save policy that denies with reason "UNAUTHENTICATED" when no subject is present and with reason "NOT_SUBSCRIBED" and metadata requiredTier when the subject's tier is not premium.

```ts
const Kilpi = createKilpi({
  // ...
  policies: {
    posts: {
      // Only signed-in premium users can save posts
      async save(subject, post: Post) {
        if (!subject) {
          return Deny({ reason: "UNAUTHENTICATED" });
        }
        if (subject.tier !== "premium") {
          return Deny({
            reason: "NOT_SUBSCRIBED",
            metadata: { requiredTier: "premium" },
          });
        }
        return Grant(subject);
      },
    },
  },

  // Customize behavior based on reason
  async onUnauthorizedAssert(denial) {
    switch (denial.reason) {
      case "UNAUTHENTICATED":
        throw new HttpRedirect("/sign-in");
      case "NOT_SUBSCRIBED":
        const tier = denial.metadata?.requiredTier;
        throw new HttpRedirect(`/subscribe?tier=${tier}`);
      default:
        throw new HttpForbiddenError();
    }
  },
});
```

--------------------------------

### Call a protected query with .authorized()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/protected-queries.mdx

Use the .authorized() method to execute the protected query and get the authorized output. The result may be null if unauthorized.

```ts
// Post or null
const post = await getPost.authorized("123");
```

--------------------------------

### Unprotected Authorization Logic in Component

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

An example of authorization logic mixed directly into a UI component, which leads to code duplication and maintenance challenges.

```ts
export async function DocumentPage({ id }) {

  // All this extra authorization logic shouldn't belong in the component.
  const user = await getCurrentUser();
  if (!user) {
    redirect("/login")
  };
  const document = await getDocument(id);
  if (!document) {
    redirect("/documents")
  };
  if (!(user.isAdmin || document.authorId === user.id)) {
    forbidden();
  }

  // Only now we're able to do what this component is supposed to do
  return <div>{document.title}</div>
}
```

--------------------------------

### Configure onFlushEvents callback

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Use the onFlushEvents callback to send events to your external service. This example posts the events to a hypothetical audit service endpoint.

```ts
AuditPlugin({
  async onFlushEvents(events) {
    await fetch(`https://my-audit-service.com/send-events`, {
      method: "POST",
      body: JSON.stringify(events),
      headers: { "Content-Type": "application/json" },
    });
  },
  // ...
});
```

--------------------------------

### Create Authorize component with Kilpi.$createReactServerComponents

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-server.mdx

Create the Authorize component from the Kilpi instance. This is required before using <Authorize /> in your server components.

```ts
const { Authorize } = Kilpi.$createReactServerComponents();
```

--------------------------------

### Define root-level utility policies

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/policy.mdx

Shows how to define simple, reusable policies like 'authed' or 'admin' at the root level and how to assert them.

```ts
export const Kilpi = createKilpi({ /* ... */,
  // ...
  policies: {
    authed: (subject) => subject ? Grant(subject) : Deny(),
    admin: (subject) => subject?.isAdmin ? Grant(subject) : Deny(),
    // ...
  }
})

// Get the current user (we can be sure they are an admin)
const { subject } = await Kilpi.admin().authorize().assert();
```

--------------------------------

### Filter events with shouldIncludeEvent

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Use the shouldIncludeEvent option to filter events. The example only includes denied decisions by returning the negation of event.authorization.granted.

```ts
AuditPlugin({
  ...,
  shouldIncludeEvent(event) {
    return !event.authorization.granted
  }
})
```

--------------------------------

### Apply ReactServerPlugin and create React Server Components

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/next-js.mdx

Apply the ReactServerPlugin in your Kilpi configuration and create the React Server Components. The diff shows the lines to add.

```diff
// kilpi.ts
+ import { ReactServerPlugin } from "@kilpi/react-server";

export const Kilpi = createKilpi({
  // ...
+  plugins: [ReactServerPlugin()]
})

+ const { Authorize } = Kilpi.$createReactServerComponents();
```

--------------------------------

### Define policies with createKilpi and authorize them

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/authorizing.mdx

Shows how to define policies with createKilpi, including root-level, namespaced, and nested policies. Policies are accessed via dot notation and called to instantiate them before calling authorize().

```ts
export const Kilpi = createKilpi({ /* ... */
  policies: {
    async admin(subject) {...},                // Root-level policy
    posts: {                                   // Namespace
      async create(subject) {...},             // No object
      write: {                                 // Nested namespaces
        async edit(subject, post: Post) {...}, // Needs "Post" object
      }
    },
  }
});

// Use as follows
await Kilpi.admin().authorize();
await Kilpi.posts.create().authorize();
await Kilpi.posts.write.edit(post).authorize();

```

--------------------------------

### Extract getSubject to infer Subject type

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/subject.mdx

Extract getSubject into its own function to infer the Subject type, useful when defining policies in separate objects. The example shows the function signature and the type extraction.

```ts
async function getSubject() { ... }

export type Subject = Awaited<ReturnType<typeof getSubject>>;

export const Kilpi = createKilpi({ getSubject, ... })
```

--------------------------------

### Configure immediate strategy for testing

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Sends every event separately and immediately as they come. Primarily for testing purposes. Calling Kilpi.$audit.flush() has no effect because no batching is done.

```ts
AuditPlugin({
  strategy: "immediate",
  async onFlushEvents(events) { ... },
})
```

--------------------------------

### Set public environment variables for Kilpi

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Create public environment variables for the Kilpi client, ensuring they are included in the client bundle.

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

--------------------------------

### Authorize a policy with Kilpi.posts.create().authorize()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Authorizes a policy with the .authorize() method, which can optionally receive the current ctx (passed to getSubject) or other authorization options. Returns a decision.

```ts
const decision = await Kilpi.posts.create().authorize();
```

--------------------------------

### Use useAuthorize hook in a component

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-client.mdx

Use the useAuthorize hook to get authorization status and decision. The hook automatically wraps the policy's authorize() call with query utilities like status, caching, and re-fetch on cache invalidation.

```tsx
export function DeleteCommentButton({ comment, onDelete }) {
  const {
    status, // "idle" | "pending" | "success" | "error"
    granted, // boolean (shorthand for decision?.granted)
    decision, // The full decision object
  } = KilpiClient.comments.delete(comment).useAuthorize();

  return (
    <button disabled={!granted} onClick={onDelete}>
      Delete comment
    </button>
  );
}
```

--------------------------------

### Define a stateful policy with database fetching

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/policy.mdx

Demonstrates an asynchronous policy that checks user tier and fetches post counts from a database to determine authorization.

```ts
export const Kilpi = createKilpi({
  // ...
  policies: {
    posts: {
      // A free user can create at most 3 posts
      async create(subject) {
        if (!subject) return Deny();
        if (subject.tier === "premium") return Grant(subject);

        // Fetch # of posts from DB
        const postsCount = await db.countPostsForUser(subject.id);
        return postsCount < 3 ? Grant(subject) : Deny();
      },
    },
  },
});
```

--------------------------------

### Create KilpiClient instance

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Create a KilpiClient instance with createKilpiClient, optionally passing infer for type safety and plugins.

```ts
// kilpi-client.ts
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,
  },
});
```

--------------------------------

### Protected Query Usage Comparison

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

This diff shows how the protected query simplifies the component logic by replacing manual authorization checks with a single protected call.

```ts
  async function UserDetailsComponent({ userId }) {
-   const currentUser = await getCurrentUser();
-   const userDetails = currentUser.id === userId || currentUser.isAdmin
-     ? await getFullUserDetails(userId)
-     : await getOnlyPublicUserDetails(userId);
+   const userDetails = await getUserDetails.protect(userId);
    return <div>...</div>
  }
```

--------------------------------

### Pseudocode for Kilpi.$query internals

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/protected-queries.mdx

Conceptual pseudocode showing how .unauthorized() and .authorized() work internally.

```ts
function unauthorized(input) {
  return query(input);
}

function authorized(input) {
  const output = query(input);
  const subject = getSubject();
  return authorize({ input, subject, output });
}
```

--------------------------------

### Create AuthorizeClient component

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-client.mdx

Create the AuthorizeClient component from the KilpiClient instance. This is required before using the component.

```ts
const { AuthorizeClient } = KilpiClient.$createReactClientComponents();
```

--------------------------------

### Authorize with Kilpi.posts.edit(post).authorize()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/authorizing.mdx

Use this snippet to authorize an action by referencing a policy with dot notation and calling its authorize() method. The returned decision must be checked for the granted property before accessing other properties.

```ts
const decision = await Kilpi.posts.edit(post).authorize();
if (decision.granted) {
  await db.posts.update(...);
}

```

--------------------------------

### Implement a protector for a single document query

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

Uses the Kilpi protector to authorize access to a specific document before returning it.

```ts
export const getDocument = Kilpi.query(
  cache((id: string) => db.documents.get(id)),
  {
    async protector({ output: document }) {
      if (document) await Kilpi.authorize("documents:read", document);
      return document;
    },
  },
);
```

--------------------------------

### Define a getSubject adapter

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/subject.mdx

Pass an async getSubject function to createKilpi. It should call your authentication provider and return the subject object or null if no authenticated subject. The subject type is automatically inferred by your policies.

```ts
export const Kilpi = createKilpi({
  async getSubject() {
    const user = await myAuthenticationProvider.getCurrentUser();
    if (!user) return null;
    return { id: user.id, name: user.name };
  },
  // ...
});
```

--------------------------------

### Integrate with Next.js route

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/endpoint.mdx

Use the Kilpi.$createPostEndpoint() function to construct a web-standard request-response handler for a Next.js API route.

```ts
// app/api/kilpi/route.ts
// (req: Request) => Promise<Response>
export const POST = Kilpi.$createPostEndpoint();
```

--------------------------------

### Logging with AuditPlugin vs onAfterAuthorization hook

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Shows the difference between using AuditPlugin for logging and using the onAfterAuthorization hook. The hook is easier for logging authorization decisions.

```diff
// kilpi.ts
  const Kilpi = createKilpi({
    ...,
-   // Logging using AuditPlugin
-   plugins: [
-     AuditPlugin({
-       strategy: "immediate",
-       async onFlushEvents(events) {
-         for (const e of events) {
-           console.log(format(e))
-         }
-       }
-     }),
-   ]
  });

+ // Logging using hooks
+ Kilpi.$hooks.onAfterAuthorization((e) => console.log(format(e)));
```

--------------------------------

### Define a protected query with Kilpi.$query

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/protected-queries.mdx

Pass the query function as the first argument and an object with an authorize method as the second. The authorize function receives the input, output, and subject, and returns the output the subject is authorized to see.

```ts
const getPost = Kilpi.$query(
  // Query function
  async (id: string) => {
    return await db.posts.findById(id);
  },
  // Separate but co-located authorization which runs after the query
  {
    async authorize({ input: [id], output: post, subject }) {
      if (!post) return null;
      const { granted } = await Kilpi.posts.read(post).authorize();
      if (!granted) return null;
      return post;
    },
  },
);
```

--------------------------------

### Authorize a function with Kilpi

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/getting-started/quickstart.mdx

References a policy (e.g., Kilpi.posts.delete(myPost)) and runs the authorization check with .authorize(). If the getSubject adapter takes a ctx parameter, pass it as shown. The granted result can be used to conditionally perform the action.

```ts
import { Kilpi } from "...";

async function deletePost(post: Post) {
  const { granted } = await Kilpi
    .posts               // (Policy namespace)
    .delete(post)        // Instantiate policy with object
    .authorize({ ctx }); // Run the authorization check

  if (granted) await db.posts.delete(post.id);
}
```

--------------------------------

### Assert authorization with Kilpi.posts.create().authorize().assert()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Asserts an authorization to receive a granted decision or throw. The subject is destructured from the returned decision. This replaces the old Kilpi.authorize, Kilpi.isAuthorized, Kilpi.unauthorized, and Kilpi.getAuthorizationDecision methods.

```ts
const { subject } = await Kilpi.posts.create().authorize().assert();
```

--------------------------------

### Simplified deleteDocument with Kilpi.authorize

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-24-introducing-kilpi.mdx

Shows the simplified deleteDocument function using Kilpi's authorize method. It fetches the document, calls Kilpi.authorize with the permission string and document, then deletes. This is the clean, centralized authorization approach that Kilpi provides.

```ts
async function deleteDocument(id: string) {
  const document = await db.getDocument(id);
  await Kilpi.authorize("documents:delete", document);
  await db.deleteDocument(id);
}
```

--------------------------------

### Configure periodical strategy with flushIntervalSeconds

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Sends events every flushIntervalSeconds seconds if there are any events to send. Use Kilpi.$audit.flush() to prematurely flush the current batch.

```ts
AuditPlugin({
  strategy: "periodical",
  flushIntervalSeconds: 5,
  async onFlushEvents(events) { ... },
})
```

--------------------------------

### Implement context via AsyncLocalStorage

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/subject.mdx

Use AsyncLocalStorage to provide context globally, reducing boilerplate by avoiding explicit ctx passing.

```ts
// app.ts
import { AsyncLocalStorage } from "async_hooks";

// Create an AsyncLocalStorage which can provide the `ctx`
export const ctxStorage = new AsyncLocalStorage<Context>();

// Provide the `ctx` in a middleware -- all code running inside
// this block has access to `const ctx = ctxStorage.getStore()`.
app.use(async (ctx, next) => {
  await ctxStorage.run(ctx, async () => {
    await next();
  });
});

// Later getSubject can use the ctxStorage to consume the ctx
async function getSubject() {
  const ctx = ctxStorage.getStore();
  if (!ctx) return null;

  // ...
}
```

--------------------------------

### Combine policies in createKilpi

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/policy.mdx

Register the modularized policy sets within the policies object of the createKilpi configuration.

```ts
export const Kilpi = createKilpi({
  // ...,
  policies: {
    posts: postPolicies,
    orgs: orgPolicies,
  },
});
```

--------------------------------

### Configure EndpointPlugin options

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/endpoint.mdx

Customize EndpointPlugin behavior using getContext, onBeforeHandleRequest, and onBeforeProcessItem hooks.

```ts
EndpointPlugin({
  secret: "...",

  // Extract the `ctx` parameter from the request for `getSubject`
  // if required.
  getContext(req) {
    return req;
  },

  // Before handling the request, run this hook. This hook may
  // optionally throw or return an early response to terminate
  // execution. Useful for e.g. rate-limiting.
  async onBeforeHandleRequest(req) {
    const allow = await rateLimit();
    if (!allow) {
      return Response.json({ error: "Too fast" }, { status: 429 });
    }
  },

  // Before handling each item in the request, run this hook.
  // Simply an "event-listener" type callback.
  async onBeforeProcessItem(item) {
    if (item.type === "fetchDecision") {
      console.log(`Deciding ${item.action} on ${item.object}`);
    }
  },
});
```

--------------------------------

### Customize <AuthorizeClient /> with Pending, Unauthorized, Idle, and Error components

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Use this to provide custom `Pending`, `Unauthorized`, `Idle`, and `Error` components, and to disable the query with `isDisabled`. The `Error` component receives the error as a render prop.

```tsx
<AuthorizeClient
  policy={KilpiClient.posts.delete(post)}
  Pending={<p>Loading...</p>}
  Unauthorized={<p>You are not allowed to delete this post</p>}
  Idle={<p>Authorization disabled</p>}
  Error={({ error }) => <p>Error: {error.message}</p>}
  isDisabled={shouldDisableQuery}
>
  <DeletePostForm post={post} />
</AuthorizeClient>
```

--------------------------------

### Use Deny() with metadata

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/policy.mdx

Deny() can accept an object containing user-facing messages, system-facing reasons, and custom metadata to handle unauthorized behavior.

```ts
export const Kilpi = createKilpi({
  // ...
  policies: {
    posts: {
      async edit(subject, post: Post) {
        if (!subject) {
          return Deny({
            message: "You are not signed in", // User-facing
            reason: "UNAUTHENTICATED", // System-facing
          });
        }

        if (subject.tier !== "premium") {
          return Deny({
            message: "Not subscribed", // User-facing
            reason: "NOT_SUBSCRIBED", // System-facing
            metadata: {
              requiredTier: "premium", // System-facing
            },
          });
        }

        return Grant(subject);
      },
    },
  },
});

// Customize unauthorized behavior based on denial details
const decision = await Kilpi.posts.edit(post).authorize();
if (!decision.granted) {
  showMessage(decision.message);
  if (decision.reason === "NOT_SUBSCRIBED") {
    redirect(`/subscribe?tier=${decision.metadata?.requiredTier}`);
  }
}
```

--------------------------------

### Update createKilpi settings

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Remove disableSubjectCaching and rename defaultOnUnauthorized to onUnauthorizedAssert.

```ts
  export const Kilpi = createKilpi({
    // ...
-   settings: {
-     async defaultOnUnauthorized(decision) {
-       await redirect(`/sign-in?message=${decision.message}`);
-     },
-     disableSubjectCaching: true,
-   },
+   async onUnauthorizedAssert(decision) {
+     await redirect(`/sign-in?message=${decision.message}`);
+   },
  })
```

--------------------------------

### Skip subject fetching during build time with PHASE_PRODUCTION_BUILD

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/next-js.mdx

Skip subject fetching during Next.js build time to avoid errors from calling headers() or cookies(). The diff shows the lines to add.

```diff
+ import { PHASE_PRODUCTION_BUILD } from "next/constants";

  export const Kilpi = createKilpi({
    async getSubject() {
+     if (process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD) return null;
    },
    // ...
  });
```

--------------------------------

### Update Kilpi.query to Kilpi.$query

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Rename query to $query and update the protector option to authorize, along with method name changes for protected/unsafe calls.

```ts
- const getPost = await Kilpi.query(
+ const getPost = await Kilpi.$query(
    async (id) => { ... },
    {
-     async protector({ subject, input, output }) { ... },
+     async authorize({ subject, input, output }) { ... },
    }
  )

- const post = await getPost.protect("1");
+ const post = await getPost.authorized("1");

- const post = await getPost.unsafe("1");
+ const post = await getPost.unauthorized("1");
```

--------------------------------

### Creating a Protected Query with Kilpi

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

Using Kilpi.query to wrap a pure, cacheable query function with a protector function that handles authorization logic.

```ts
const getDocument = Kilpi.query(
  cache(async (id: string) => {
    // Pure query function can be cached!
    const document = await getDocumentPure(id);
    return document;
  }),
  {
    // Kilpi automatically provides the `subject` (i.e. caller or user)
    async protector({ input, output: document, subject }) {
      if (subject.isAdmin || document.authorId === subject.id) {
        return document;
      }

      // Handle errors by e.g. throwing or returning null
      throw new Error("You are not allowed to view this document");
    },
  },
);
```

--------------------------------

### Rename ReactClientComponentPlugin to ReactClientPlugin

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Update the import and plugin initialization in your Kilpi client configuration.

```ts
- import { ReactClientComponentPlugin } from "@kilpi/react-client";
+ import { ReactClientPlugin } from "@kilpi/react-client";

  export const KilpiClient = createKilpiClient({
    // ...
-   plugins: [ReactClientComponentPlugin()],
+   plugins: [ReactClientPlugin()],
  })
```

--------------------------------

### Configure manual strategy and flush manually

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Collects all events and waits until Kilpi.$audit.flush() is manually called. Provides full developer control over when events are flushed.

```ts
AuditPlugin({
  strategy: "manual",
  async onFlushEvents(events) { ... },
})

await Kilpi.$audit.flush()
```

--------------------------------

### Rename deny() and grant() to Deny() and Grant()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Update imports and policy return values to use the new capitalized function names.

```ts
- import { deny, grant } from "@kilpi/core";
+ import { Deny, Grant } from "@kilpi/core";

export const Kilpi = createKilpi({
  policies: {
    async isAdmin(subject) {
-     if (subject.role === "admin") return grant(subject);
+     if (subject.role === "admin") return Grant(subject);
-     return deny({ message: "User is not an admin" });
+     return Deny({ message: "User is not an admin" });
    }
  }
})
```

--------------------------------

### Refactoring Component with Protected Query

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

A diff showing how the protected query pattern simplifies component code by replacing manual authorization checks with a single .protect() call.

```ts
  export async function DocumentPage({ id }) {

-   const user = await getCurrentUser();
-   if (!user) {
-     redirect("/login")
-   };
-
-   const document = await getDocument(id);
-   if (!document) {
-     redirect("/documents")
-   };
-   if (!(user.isAdmin || document.authorId === user.id)) {
-     forbidden();
-   }

+   const document = await getDocument.protect(id);
+   if (!document) redirect("/documents");

    return <div>{document.title}</div>
  }
```

--------------------------------

### Replace KilpiClient.fetchSubject with always policy

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

The fetchSubject method is removed; use an always policy to achieve similar behavior.

```ts
  export const Kilpi = createKilpi({
    // ...
    policies: {
+     always: (subject) => Grant(subject),
      // ...
    }
  })

- const subject = await KilpiClient.fetchSubject();
+ const decision = await KilpiClient.always().authorize();
+ const subject = decision.granted ? decision.subject : null; // Should always be granted
```

--------------------------------

### Access subject with Kilpi.$getSubject

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/subject.mdx

Retrieve the current subject using the Kilpi.$getSubject utility.

```ts
const subject = await Kilpi.$getSubject();
```

--------------------------------

### Render conditionally with server-side <Authorize /> component

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Use this server-side component to conditionally render children based on the authorization status. It is created via `Kilpi.$createReactServerComponents()` and takes a `policy` prop.

```tsx
const { Authorize } = Kilpi.$createReactServerComponents();

<Authorize policy={Kilpi.posts.edit(post)}>
  <PostEditForm post={post} />
</Authorize>;
```

--------------------------------

### Apply ReactClientPlugin in KilpiClient configuration

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-client.mdx

Apply the ReactClientPlugin in your KilpiClient configuration. The plugin must be added to the plugins array to enable the React components and hooks.

```ts
// kilpi.ts
import { createKilpiClient } from "@kilpi/client";
import { ReactClientPlugin } from "@kilpi/react-client";

export const KilpiClient = createKilpiClient({
  // ...
+  plugins: [ReactClientPlugin()]
})
```

--------------------------------

### Replace Kilpi.unauthorized() with never policy

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Since unauthorized() is removed, define a never policy that returns Deny() and use it with authorize().assert().

```ts
  export const Kilpi = createKilpi({
    // ...
    policies: {
+     never: () => Deny(),
      // ...
    }
  })

- await Kilpi.unauthorized();
+ await Kilpi.never().authorize().assert();
```

--------------------------------

### Dynamically enable or disable AuditPlugin

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Use the Kilpi.$audit.disable() and Kilpi.$audit.enable() methods to dynamically toggle the plugin at runtime.

```ts
Kilpi.$audit.disable();
Kilpi.$audit.enable();
```

--------------------------------

### Handle unauthorized assertions from `.assert()` (kilpi.ts)

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/installation/koa.mdx

Adds an `onUnauthorizedAssert` handler that uses `ctxStorage` to access the Koa `ctx` and throws a 403 Forbidden exception by default. Optionally customize behavior based on the decision reason.

```diff
  // kilpi.ts
  import { ctxStorage } from "./app";

  export const Kilpi = createKilpi({
    // ...,
+   async onUnauthorizedAssert(decision)  {
+     // Access the context if available
+     const ctx = ctxStorage.getStore();
+     if (!ctx) return;
+
+     // Optionally customize behavior based on the decision
+     switch (decision.reason) { ... }
+
+     // By default, throw a HTTP 403 Forbidden exception
+     ctx.throw(403, decision.message);
+   }
  })
```

--------------------------------

### AuthorizeClient with render props

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/react-client.mdx

Use render props to access the query and decision. The render prop types are narrowed, e.g., the query in Unauthorized is in a success state with a decision where granted is false.

```tsx
<AuthorizeClient
  policy={KilpiClient.posts.create()}
  Pending={(query) => <p>Query is {query.status}</p>}
  Unauthorized={({ decision }) => <p>{decision.message}</p>}
  Error={({ error }) => <p>Error: {error.message}</p>}
  Idle={({ status }) => <p>Query is {status}</p>}
>
  {({ decision }) => <CreatePostForm authorName={decision.subject.name} />}
</AuthorizeClient>
```

--------------------------------

### Use KilpiClient with React

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Use KilpiClient with React via hooks and components from @kilpi/react-client.

```tsx
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>
  );
}
```

--------------------------------

### Compare cache keys with areCacheKeysEqual

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Use KilpiClientCache.areCacheKeysEqual to compare two cache keys. Keys are of type unknown[] and must be serializable. The comparison uses stable stringification, so referentially different but structurally equal keys are considered equal.

```ts
const keyA = ["some-key", { value: 1 }];
const keyB = ["some-key", { value: 1 }];

// False due to referential equivalence
keyA === keyB;

// True, due to stable stringification
KilpiClientCache.areCacheKeysEqual(keyA, keyB);
```

--------------------------------

### Configure AuditPlugin with waitUntil for serverless

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/plugins/audit.mdx

Pass the waitUntil function from @vercel/functions to the AuditPlugin to ensure batch flushing completes before the serverless function terminates. All strategies respect the waitUntil option automatically. For Next.js, the after function is possible but only works in RSCs.

```ts
import { waitUntil } from "@vercel/functions";

AuditPlugin({
  strategy: "batch",
  batchTimeoutSeconds: 5,
  waitUntil, // (promise: Promise<unknown>) => void
  async onFlushEvents(events) { ... },
})
```

--------------------------------

### Error handling with next-safe-action and Kilpi

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-28-how-to-protect-nextjs-server-actions.mdx

A step-by-step pattern for handling errors in next-safe-action: define a UserReadableError class, create a custom error handler in the action client, throw user-readable errors in actions, toast them in the UI, and optionally apply a Kilpi middleware for authorization failures.

```ts
export class UserReadableError extends Error {
  constructor(message: string) {
    super(message);
  }
}
```

```ts
export const actionClient = createSafeActionClient({
  handleServerError(error) {
    if (error instanceof UserReadableError) return error.message;
    return "An unknown error occurred";
  }
})
```

```ts
"use server";

const myAction = actionClient.action(async ({}) => {
  // ...
  if (!comment) throw new UserReadableError("Comment not found")
  // ...
})
```

```tsx
"use client";

export function DeleteCommentButton({ commentId }: { commentId: string }) {
  const action = useSafeAction(deleteCommentAction);

  return (
    <button onClick={() => action.executeAsync({ commentId })}>
      Delete comment
    </button>
  );
}
```

```ts
import { Kilpi } from "./kilpi";
import { ClientSafeError } from "kilpi";

export const actionClient = createSafeActionClient({ ... })
  .use(async ({ next }) => {
    return await Kilpi.runInScope(async () => {
      Kilpi.onUnauthorized(({ message }) => {
        throw new UserReadableError(message ?? "Unauthorized");
      });
      return await next();
    });
  });
```

--------------------------------

### Authorize a client request with KilpiClient.posts.edit(post).authorize()

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-10-10-kilpi-v1-0.mdx

Use this to fetch an authorization decision from the server for a specific policy. It replaces the previous `fetchAuthorization` API.

```ts
// Fetches decision from the server
await KilpiClient.posts.edit(post).authorize();
```

--------------------------------

### Rename Kilpi.getSubject to Kilpi.$getSubject

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/upgrade/v1-0.mdx

Update all calls to the getSubject method to use the new $getSubject name.

```ts
- const subject = await Kilpi.getSubject();
+ const subject = await Kilpi.$getSubject();
```

--------------------------------

### Bad Pattern: Multiple functions for different access levels

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/blog/2025-03-27-introducing-the-protected-query-pattern.mdx

This approach results in duplicated authorization logic and increases the number of functions to maintain.

```ts
// BAD: Duplicated authorization logic, more functions to maintain.
async function UserDetailsComponent({ userId }) {
  const currentUser = await getCurrentUser();
  const userDetails = currentUser.id === userId || currentUser.isAdmin
    ? await getFullUserDetails(userId)
    : await getOnlyPublicUserDetails(userId);
  return <div>...</div>
}
```

--------------------------------

### Fetch authorization decision on client

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/usage-on-client.mdx

Use KilpiClient to fetch an authorization decision from the server.

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

--------------------------------

### Redact data with Kilpi.$query

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/concepts/protected-queries.mdx

Use the authorize function to return only public fields when unauthorized, and include private fields when authorized. TypeScript knows the email is optional.

```ts
const getUserDetails = Kilpi.$query(
  async (userId: string) => {
    return await db.users.findById(userId);
  },
  {
    async authorize({ output: user }) {
      if (!user) return null;
      const { granted } = await Kilpi.users.readPrivate(user).authorize();

      // Unauthorized: Only return public fields
      if (!granted) return { userId: user.id, name: user.name };

      // Authorized: Return also private fields
      return { userId: user.id, name: user.name, email: user.email };
    },
  },
);

// TS knows email is optional, as it may be redacted away
const userDetails = await getUserDetails.authorized(userId);
userDetails.email; // string | undefined
```

--------------------------------

### Enable strictNullChecks and strictFunctionTypes in tsconfig.json

Source: https://github.com/jussinevavuori/kilpi/blob/main/apps/docs/docs/resources/typescript.mdx

Minimal TypeScript options to enable when strict mode cannot be used. Without these, Kilpi fails to infer types properly and cannot guarantee full type-safety.

```json
// tsconfig.json
{
  "compilerOptions": {
    "strictNullChecks": true,
    "strictFunctionTypes": true
    // ...
  }
  // ...
}
```
Tokens:
Raw