guard.hpp

Go to the documentation of this file.

// §10 route-guard interface + §11 declarative authorization helpers.
//
// Framework-agnostic: the host adapter (Crow / Pistache / any HTTP server) pulls
// the raw credential out of the request; turning it into an AxiamUser is the job
// of axiam::TokenAuthenticator in <axiam/authenticator.hpp>, which is the
// supported §10 verification path (signature + exp + nbf + tenant binding, fail
// closed). Do NOT build an AxiamUser straight from
// JwksVerifier::verify_signature_only_unchecked — that primitive validates the
// signature only, so a guard fed from it accepts expired and cross-tenant tokens.
//
// The helpers here run strictly AFTER that identity exists and compose on top of
// the client's check_access surface; they never re-implement token verification.
#pragma once
 
#include <functional>
#include <initializer_list>
#include <optional>
#include <string>
#include <vector>
 
#include "axiam/client.hpp"
#include "axiam/errors.hpp"
 
namespace axiam {
 
struct AxiamUser {
    std::string user_id;
    std::string tenant_id;
    std::vector<std::string> roles;
 
    bool has_role(const std::string& role) const {
        for (const auto& r : roles) {
            if (r == role) return true;
        }
        return false;
    }
};
 
inline const AxiamUser& require_auth(const std::optional<AxiamUser>& user) {
    if (!user.has_value()) {
        throw AuthError("authentication_failed");
    }
    return *user;
}
 
inline void require_role(const std::optional<AxiamUser>& user,
                         std::initializer_list<std::string> any_of) {
    const AxiamUser& u = require_auth(user);
    for (const auto& role : any_of) {
        if (u.has_role(role)) return;
    }
    throw AuthzError("authorization_denied: missing required role");
}
 
inline void require_access(Client& client, const std::optional<AxiamUser>& user,
                           const std::string& action, const std::string& resource_id,
                           std::optional<std::string> scope = std::nullopt) {
    const AxiamUser& u = require_auth(user);
    if (resource_id.empty()) {
        // §11.3: unresolvable resource id is a programming error (400).
        throw std::invalid_argument("invalid_request: unresolved resource id");
    }
    AccessDecision decision;
    try {
        decision = client.check_access(action, resource_id, std::move(scope), u.user_id);
    } catch (const AuthzError&) {
        throw;  // server said 403/409 → denied
    } catch (const NetworkError&) {
        // §11.5: fail closed on transport failure; never allow.
        throw AuthzError("authz_unavailable");
    }
    if (!decision.allowed) {
        throw AuthzError("authorization_denied");
    }
}
 
template <typename Request>
void require_access(Client& client, const std::optional<AxiamUser>& user,
                    const std::string& action,
                    const std::function<std::string(const Request&)>& resolver,
                    const Request& request, std::optional<std::string> scope = std::nullopt) {
    require_access(client, user, action, resolver(request), std::move(scope));
}
 
template <typename Request>
class AxiamGuard {
public:
    using Authenticator = std::function<std::optional<AxiamUser>(const Request&)>;
 
    explicit AxiamGuard(Authenticator auth) : auth_(std::move(auth)) {}
 
    AxiamUser operator()(const Request& request) const {
        auto user = auth_(request);
        return require_auth(user);
    }
 
private:
    Authenticator auth_;
};
 
}  // namespace axiam
 
#define AXIAM_REQUIRE_ACCESS(client, user, action, resource) \
    ::axiam::require_access((client), (user), (action), (resource))
 
#define AXIAM_REQUIRE_AUTH(user) ::axiam::require_auth((user))