Безопасность и контроль доступа

Управление актёрами аутентификации, областями авторизации и политиками доступа.

Подключение

local security = require("security")

actor

Возвращает текущего актёра из контекста выполнения:

local actor = security.actor()
if actor then
    local id = actor:id()
    local meta = actor:meta()

    logger:info("Запрос от", {
        user_id = id,
        role = meta.role
    })
end

Возвращает: Actor|nil

scope

Возвращает текущую область безопасности из контекста выполнения:

local scope = security.scope()
if scope then
    local policies = scope:policies()
    for _, policy in ipairs(policies) do
        print("Активная политика:", policy:id())
    end
end

Возвращает: Scope|nil

can

Проверяет, разрешено ли действие над ресурсом в текущем контексте:

-- Проверка права на чтение
if not security.can("read", "user:" .. user_id) then
    return nil, errors.new("PERMISSION_DENIED", "Нет доступа к данным пользователя")
end

-- Проверка права на запись
if not security.can("write", "order:" .. order_id) then
    return nil, errors.new("PERMISSION_DENIED", "Нет доступа к изменению заказа")
end

-- Проверка с метаданными
local allowed = security.can("delete", "document:" .. doc_id, {
    owner_id = doc.owner_id,
    department = doc.department
})

Возвращает: boolean

new_actor

Создаёт нового актёра с идентификатором и метаданными:

-- Создание актёра-пользователя
local actor = security.new_actor("user:" .. user.id, {
    role = user.role,
    department = user.department,
    email = user.email
})

-- Создание актёра-сервиса
local service_actor = security.new_actor("service:payment-processor", {
    type = "service",
    version = "1.0.0"
})

Возвращает: Actor

new_scope

Создаёт новую область безопасности:

-- Пустая область
local scope = security.new_scope()

-- Область с политиками
local read_policy = security.policy("app:read-only")
local scope = security.new_scope({read_policy})

-- Построение области пошагово
local scope = security.new_scope()
local policy1 = security.policy("app:read")
local policy2 = security.policy("app:write")
scope = scope:with(policy1):with(policy2)

Возвращает: Scope

policy

Получает политику из реестра:

local policy, err = security.policy("app:admin-access")
if err then
    return nil, err
end

-- Вычисление политики
local result = policy:evaluate(actor, "delete", "user:123")
if result == "allow" then
    -- разрешено
elseif result == "deny" then
    -- запрещено
else
    -- не определено, проверить другие политики
end

Возвращает: Policy, error

named_scope

Получает предопределённую группу политик:

-- Получить область администратора
local admin_scope, err = security.named_scope("app:admin")
if err then
    return nil, err
end

-- Использовать для привилегированных операций
local result = admin_scope:evaluate(actor, "delete", "user:123")

Возвращает: Scope, error

token_store

Получает хранилище токенов для управления аутентификацией:

local store, err = security.token_store("app:tokens")
if err then
    return nil, err
end

-- Работа с хранилищем...
store:close()

Возвращает: TokenStore, error

Методы Actor

Методы Scope

with / without

Добавление или удаление политик из области:

local scope = security.new_scope()

-- Добавить политику
local write_policy = security.policy("app:write")
scope = scope:with(write_policy)

-- Удалить политику
scope = scope:without("app:read-only")

evaluate

Вычисление всех политик в области:

local result = scope:evaluate(actor, "read", "document:123")
-- "allow", "deny" или "undefined"

if result ~= "allow" then
    return nil, errors.new("PERMISSION_DENIED", "Доступ запрещён")
end

contains

Проверка наличия политики в области:

if scope:contains("app:admin") then
    show_admin_features()
end

policies

Возвращает все политики в области:

local policies = scope:policies()
for _, policy in ipairs(policies) do
    print(policy:id())
end

Возвращает: Policy[]

Методы Policy

Методы TokenStore

create

Создание токена аутентификации:

local actor = security.new_actor("user:123", {role = "user"})
local scope = security.named_scope("app:default")

local token, err = store:create(actor, scope, {
    expiration = "24h",  -- или миллисекунды
    meta = {
        login_ip = request_ip,
        user_agent = user_agent
    }
})

Возвращает: string, error

validate

Проверка токена и получение актёра/области:

local actor, scope, err = store:validate(token)
if err then
    return nil, errors.new("UNAUTHENTICATED", "Неверный токен")
end

Возвращает: Actor, Scope, error

revoke

Отзыв токена:

local ok, err = store:revoke(token)

Возвращает: boolean, error

close

Освобождение ресурса хранилища:

store:close()

Возвращает: boolean

Разрешения

Операции безопасности подчиняются политикам доступа.

Действия безопасности

Настройка политик описана в разделе Модель безопасности.

Ошибки

local store, err = security.token_store("app:tokens")
if err then
    if errors.is(err, errors.INVALID) then
        print("Неверный запрос:", err:message())
    end
    return nil, err
end

Подробнее см. Обработка ошибок.

См. также

• Модель безопасности — настройка актёров, политик и областей
• HTTP Middleware — файрвол эндпоинтов и ресурсов