kit-policy

Un marco de autorización flexible y componible para Kit, inspirado en Action Policy de Ruby.

[TOC]

Archivos

Archivo	Descripción
`.editorconfig`	Configuración de formato del editor
`.gitignore`	Reglas de ignorado de Git para artefactos de compilación y dependencias
`.tool-versions`	Versiones de herramientas asdf (Zig, Kit)
`LICENSE`	Archivo de licencia MIT
`README.md`	Este archivo
`examples/blog-policy.kit`	Ejemplo de autorización de blog
`kit.toml`	Manifiesto del paquete con metadatos, tareas y configuración de lint
`src/core.kit`	Helpers de autorización principales
`src/error.kit`	Errores de autorización, tipos de resultado y motivos de fallo
`src/main.kit`	Módulo raíz del paquete
`src/scope.kit`	Helpers de ámbito, predicado y paginación
`tests/policy.test.kit`	Pruebas de comportamiento de políticas de extremo a extremo
`tests/types.test.kit`	Pruebas de tipos y helpers de políticas

Dependencias

Sin dependencias de paquetes Kit.

Instalación

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

Uso

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

Resumen de la API

Policy.Core

Helpers principales para funciones de política que devuelven 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

Los helpers de pre-verificación devuelven Option Bool: Some true permite, Some false deniega y None continúa con la regla principal.

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

Los helpers de acción proporcionan grupos de acciones comunes y alias.

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

Los helpers de composición de políticas combinan varios resultados de autorización.

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

Policy.Scope

Los helpers de ámbito filtran colecciones antes de devolver datos a quien llama.

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

Los combinadores de predicados son útiles para construir verificaciones de ámbito reutilizables.

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

Los helpers de paginación están indexados desde 1.

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

Policy.Error

Tipos de error y resultado para fallos de autorización.

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

Las funciones helper se exportan desde el módulo, por lo que cuando se importan como PolicyError se llaman como funciones del módulo.

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

Notas de diseño

Las políticas son funciones simples, por lo que son fáciles de probar y componer.
La autorización es explícita: los helpers devuelven Result Bool PolicyError en lugar de lanzar excepciones.
Los ámbitos están separados de las verificaciones de política para que el filtrado de listas pueda ocurrir antes de la renderización o serialización.
Las acciones comunes usan palabras clave como :index, :show, :create, :update y :destroy.
El paquete es independiente del framework y se puede usar con cualquier código de aplicación Kit.

Desarrollo

Ejecutar ejemplos

Ejecute el ejemplo de política de blog con el intérprete:

kit run examples/blog-policy.kit

Compile el ejemplo a un binario nativo:

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

Ejecutar pruebas

Ejecute el conjunto de pruebas:

kit test

Ejecute el conjunto de pruebas con cobertura:

kit test --coverage

Ejecutar kit dev

Ejecute el flujo de trabajo de desarrollo estándar (formatear, verificar, probar):

kit dev

Esto hará:

Formatear y verificar los archivos fuente en src/
Verificar tipos en los ejemplos en examples/
Ejecutar pruebas en tests/ con cobertura

Verificar paridad intérprete/compilador

Ejecute verificaciones de paridad para ejemplos:

kit parity --failures-only

Generar documentación

Genere documentación de la API a partir de comentarios de documentación:

kit doc

Nota: Los fuentes de Kit con comentarios de documentación (##) generarán documentos HTML en docs/*.html.

Limpiar artefactos de compilación

Elimine archivos generados, cachés y artefactos de compilación:

kit task clean

Nota: Definido en kit.toml.

Instalación local

Para instalar este paquete localmente para desarrollo:

kit install

Esto instala el paquete en ~/.kit/packages/@kit/policy/, haciéndolo disponible para importar como Kit.Policy en otros proyectos.

Licencia

Este paquete se publica bajo la licencia MIT; consulte LICENSE para más detalles.

kit-policy v2026.7.12

Categorías