kit-policy

Гибкая, компонуемая система авторизации для Kit, вдохновлённая Action Policy из Ruby.

[TOC]

Файлы

Файл	Описание
`.editorconfig`	Настройки форматирования редактора
`.gitignore`	Правила игнорирования Git для артефактов сборки и зависимостей
`.tool-versions`	Версии инструментов asdf (Zig, Kit)
`LICENSE`	Файл лицензии MIT
`README.md`	Этот файл
`examples/blog-policy.kit`	Пример авторизации блога
`kit.toml`	Манифест пакета с метаданными, задачами и конфигурацией линтинга
`src/core.kit`	Базовые хелперы авторизации
`src/error.kit`	Ошибки авторизации, типы результатов и причины отказов
`src/main.kit`	Корневой модуль пакета
`src/scope.kit`	Хелперы для области видимости, предикатов и пагинации
`tests/policy.test.kit`	Сквозные тесты поведения политик
`tests/types.test.kit`	Тесты типов и хелперов политик

Зависимости

Нет зависимостей от пакетов Kit.

Установка

kit add gitlab.com/kit-lang/packages/kit-policy.git

Использование

import Kit.Policy.Core as PolicyCore
import Kit.Policy.Error as PolicyError
import Kit.Policy.Scope as PolicyScope

type Post = {id: Int, author-id: Int, published?: Bool, title: String}
type User = {id: Int, admin?: Bool}
type AuthContext = {user: User}

post-policy = fn(post, ctx, action) =>
  if ctx.user.admin? then
    PolicyCore.allow
  else
    match PolicyCore.resolve-alias action
      | :show -> PolicyCore.allow-if post.published?
      | :update -> PolicyCore.allow-if (ctx.user.id == post.author-id)
      | :destroy -> PolicyCore.allow-if (ctx.user.id == post.author-id)
      | _ -> PolicyCore.no-rule action

post-scope = fn(posts, ctx) =>
  if ctx.user.admin? then
    posts
  else
    posts |>> List.filter (fn(post) => post.published?)

main = fn =>
  user = {id: 1, admin?: false}
  ctx = {user: user}
  post = {id: 1, author-id: 1, published?: true, title: "Hello"}
  posts = [post]

  if PolicyCore.can-with? post-policy post ctx :update then
    println "Can update post"
  else
    println "Cannot update post"

  visible-posts = PolicyScope.scope-with post-scope posts ctx
  page = PolicyScope.paginate 1 10 visible-posts
  info = PolicyScope.pagination-info 1 10 visible-posts

  println "Visible posts: ${page}"
  println "Pages: ${info.pages}"

  err = PolicyError.not-authorized "Post" :update "not the author"
  println (PolicyError.message err)

main

Обзор API

Policy.Core

Базовые хелперы для функций политик, возвращающих Result Bool PolicyError.

PolicyCore.can-with? policy resource context action
PolicyCore.may-with? policy resource context action

PolicyCore.allow
PolicyCore.deny
PolicyCore.allow-if condition
PolicyCore.deny-if condition
PolicyCore.no-rule action
PolicyCore.allow-or-deny condition resource-name reason action

Хелперы предварительной проверки возвращают Option Bool: Some true разрешает, Some false запрещает, а None передаёт управление основному правилу.

PolicyCore.admin-bypass is-admin? ctx
PolicyCore.owner-check is-owner? resource ctx
PolicyCore.first-pre-check [check1, check2, check3]

Хелперы действий предоставляют распространённые группы действий и псевдонимы.

PolicyCore.crud-actions
PolicyCore.read-actions
PolicyCore.write-actions

PolicyCore.read-action? action
PolicyCore.write-action? action

PolicyCore.resolve-alias :new     # :create
PolicyCore.resolve-alias :edit    # :update
PolicyCore.resolve-alias :delete  # :destroy
PolicyCore.resolve-alias :view    # :show

Хелперы композиции политик объединяют несколько результатов авторизации.

PolicyCore.all-allowed? [result1, result2, result3]
PolicyCore.any-allowed? [result1, result2, result3]

Policy.Scope

Хелперы области видимости фильтруют коллекции перед возвратом данных вызывающему коду.

PolicyScope.scope-with scope-fn items ctx
PolicyScope.filter-by predicate items

PolicyScope.is-owned-by? get-owner-id get-user-id item ctx
PolicyScope.is-published? get-published item
PolicyScope.is-in-state? get-state target-state item
PolicyScope.is-admin-or? check-admin fallback-check ctx item

Комбинаторы предикатов полезны для создания переиспользуемых проверок области видимости.

PolicyScope.both? pred1 pred2 item
PolicyScope.either? pred1 pred2 item
PolicyScope.not-matching? pred item

Хелперы пагинации индексируются с 1.

page1 = PolicyScope.paginate 1 10 items
pages = PolicyScope.total-pages 10 items
info = PolicyScope.pagination-info 1 10 items

Policy.Error

Типы ошибок и результатов для сбоев авторизации.

type PolicyError =
  | NotAuthorized {resource: String, action: Keyword, reason: String}
  | RuleNotFound {action: Keyword}
  | ContextMissing {field: String}
  | PolicyNotFound {resource-type: String}
  | CustomError String

type FailureReason = FailureReason {
  policy: String,
  action: Keyword,
  details: String
}

type AuthResult =
  | Allowed
  | Denied String

Вспомогательные функции экспортируются из модуля, поэтому при импорте как PolicyError они вызываются как функции модуля.

PolicyError.not-authorized resource action reason
PolicyError.rule-not-found action
PolicyError.context-missing field
PolicyError.policy-not-found resource-type
PolicyError.custom message

PolicyError.message err
PolicyError.kind err
PolicyError.is-not-authorized? err
PolicyError.is-rule-not-found? err

PolicyError.new policy action
PolicyError.with-details policy action details
PolicyError.policy reason
PolicyError.action reason
PolicyError.details reason
PolicyError.format reason

PolicyError.allowed
PolicyError.denied reason
PolicyError.is-allowed? result
PolicyError.is-denied? result
PolicyError.reason result
PolicyError.to-result resource-name action result

Замечания по проектированию

Политики — это обычные функции, поэтому их легко тестировать и компоновать.
Авторизация явная: хелперы возвращают Result Bool PolicyError, а не выбрасывают исключения.
Области видимости отделены от проверок политик, поэтому фильтрацию списков можно выполнять до рендеринга или сериализации.
Общие действия используют ключевые слова, такие как :index, :show, :create, :update и :destroy.
Пакет не привязан к фреймворку и может использоваться с любым приложением на Kit.

Разработка

Запуск примеров

Запустите пример политики блога через интерпретатор:

kit run examples/blog-policy.kit

Скомпилируйте пример в нативный бинарник:

kit build examples/blog-policy.kit && ./blog-policy

Запуск тестов

Запустите набор тестов:

kit test

Запустите тесты с покрытием:

kit test --coverage

Запуск kit dev

Запустите стандартный рабочий процесс разработки (форматирование, проверка, тестирование):

kit dev

Это выполнит:

Форматирование и проверку исходных файлов в src/
Проверку типов в примерах из examples/
Запуск тестов из tests/ с покрытием

Проверка соответствия интерпретатора и компилятора

Запустите проверки на соответствие для примеров:

kit parity --failures-only

Генерация документации

Сгенерируйте документацию по API из комментариев:

kit doc

Примечание: Исходники Kit с комментариями (##) создадут HTML-документы в docs/*.html.

Очистка артефактов сборки

Удалите сгенерированные файлы, кеши и артефакты сборки:

kit task clean

Примечание: Определено в kit.toml.

Локальная установка

Для локальной установки этого пакета в целях разработки:

kit install

Это установит пакет в ~/.kit/packages/@kit/policy/, сделав его доступным для импорта как Kit.Policy в других проектах.

Лицензия

Этот пакет выпущен под лицензией MIT — см. файл LICENSE для подробностей.

kit-policy v2026.7.12

Категории