PermissionManager.java

package dev.aceclaw.security;

import dev.aceclaw.security.audit.CapabilityAuditLog;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.time.Instant;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;

/**
 * Central permission manager that evaluates permission requests
 * against the active policy and tracks session-level approvals.
 *
 * <p>Thread-safe: may be called from multiple virtual threads concurrently.
 *
 * <h3>Per-session "remember" scope (issue #456)</h3>
 *
 * <p>Earlier versions kept a single shared {@code Set<String>} of
 * approved tool names for the entire daemon, which meant clicking
 * "Always allow" in session A silently disabled the prompt for that
 * tool in every other concurrent session — including sessions for
 * unrelated workspaces. Fix: keyed by sessionId so each session's
 * "remember" decision stays in its own scope. Sessions clear their
 * entry on destroy via {@link #clearSessionApprovals(String)}.
 */
public final class PermissionManager {

    private static final Logger log = LoggerFactory.getLogger(PermissionManager.class);

    private final PermissionPolicy policy;

    /**
     * Per-session blanket approvals: {@code sessionId → toolName set}.
     * Empty entries are pruned by {@link #clearSessionApprovals(String)}
     * so a long-lived daemon doesn't leak state for ended sessions.
     */
    private final Map<String, Set<String>> sessionApprovals = new ConcurrentHashMap<>();

    /**
     * Optional signed audit log of every decision (#465 Layer 8 v1).
     * Null = audit disabled (default for unit tests that construct a
     * manager without disk I/O setup). When non-null, every call to
     * {@link #check} records one entry — best-effort, never throws.
     */
    private final CapabilityAuditLog auditLog;

    public PermissionManager(PermissionPolicy policy) {
        this(policy, null);
    }

    /**
     * Constructs a manager that signs and persists every decision to
     * {@code auditLog}. Pass {@code null} to disable auditing (this is
     * what the single-arg constructor does).
     */
    public PermissionManager(PermissionPolicy policy, CapabilityAuditLog auditLog) {
        this.policy = policy;
        this.auditLog = auditLog;
    }

    /**
     * Checks whether the given request is permitted within the given
     * session. <strong>Legacy entry point</strong> retained for callers that
     * still construct flat {@link PermissionRequest}s; under the hood it
     * wraps the request as a {@link Capability.LegacyToolUse} and delegates
     * to {@link #check(Capability, Provenance)}, so legacy and structured
     * paths share one decision-and-audit pipeline (#480 Layer 1, PR 2).
     *
     * <p>Order is unchanged: session-level blanket approval → policy. The
     * blanket-approval lookup is per-session — a tool approved in session A
     * is NOT auto-approved in session B (issue #456).
     *
     * @param request   the permission request
     * @param sessionId the session this check belongs to. {@code null}
     *                  skips the per-session allow-list lookup — daemon-
     *                  internal checks (cron, boot scripts) use this.
     * @return the decision
     */
    public PermissionDecision check(PermissionRequest request, String sessionId) {
        Objects.requireNonNull(request, "request");
        var capability = new Capability.LegacyToolUse(request.toolName(), request.level());
        var provenance = Provenance.fromNullableSessionId(sessionId);
        // Legacy callers' allowlist key is already the tool name — pass it
        // through unchanged so existing "always allow X" approvals stay valid.
        return check(capability, provenance, request.toolName(), request.description());
    }

    /**
     * Structured-capability entry point introduced by #480 PR 2. Takes a
     * {@link Capability} (one of the sealed variants) plus the
     * {@link Provenance} that records how the agent arrived at this check,
     * and returns the same decision the legacy method does.
     *
     * <p>This convenience overload uses the capability's
     * {@link Capability#allowlistKey() default allowlist key} (the variant
     * class name) and {@link Capability#displayLabel()} as the prompt
     * description. Tool dispatchers should prefer
     * {@link #check(Capability, Provenance, String, String)} so existing
     * tool-name-keyed allowlists keep working through migration and the
     * user sees a richer prompt than the synthetic {@code displayLabel()}.
     */
    public PermissionDecision check(Capability capability, Provenance provenance) {
        Objects.requireNonNull(capability, "capability");
        Objects.requireNonNull(provenance, "provenance");
        return check(capability, provenance, capability.allowlistKey(), capability.displayLabel());
    }

    /**
     * Full structured-capability entry point. Caller supplies an explicit
     * {@code allowlistKey} (typically the originating tool's name) and a
     * {@code description} (typically the dispatcher's rich human-readable
     * tool summary). Used by the dispatcher in {@code StreamingAgentHandler}
     * so that:
     *
     * <ul>
     *   <li>"Always allow {@code write_file}" approvals granted before #480
     *       keep auto-approving even after {@code WriteFileTool} migrates
     *       to {@code CapabilityAware} — the allowlist is keyed by tool
     *       name, not by capability variant.</li>
     *   <li>The user sees the same prompt for both legacy and migrated
     *       tools — no UX regression during migration.</li>
     * </ul>
     *
     * <h4>Pipeline (#480 PR 4 / #495)</h4>
     *
     * <ol>
     *   <li><b>Structural denial</b> ({@link PermissionPolicy#evaluateStructural}):
     *       cross-cutting refusals like "never write to {@code .env}" run
     *       FIRST so they cannot be bypassed by a prior "always allow X"
     *       approval. Audited and returned immediately when matched.</li>
     *   <li><b>Session blanket approval</b>: if the originating tool has been
     *       blanket-approved in this session (per-session, #456), auto-approve
     *       and audit with the {@code session-blanket-approval} marker.</li>
     *   <li><b>Policy evaluation</b> ({@link PermissionPolicy#evaluate}):
     *       the structured {@link Capability} + {@link Provenance} +
     *       description go to the policy directly — no flat-record bridge.
     *       Result audited.</li>
     * </ol>
     */
    public PermissionDecision check(
            Capability capability,
            Provenance provenance,
            String allowlistKey,
            String description) {
        Objects.requireNonNull(capability, "capability");
        Objects.requireNonNull(provenance, "provenance");
        Objects.requireNonNull(allowlistKey, "allowlistKey");
        Objects.requireNonNull(description, "description");

        // Structural denials (sensitive paths like .env, .ssh/, /etc/*) MUST
        // fire BEFORE the session-blanket lookup. Otherwise a user who clicked
        // "always allow write_file" earlier could route a FileWrite(.env) past
        // the rule — defeating the "overrides all modes" invariant of the
        // hard-denial layer (Codex P1 on #495).
        var structural = policy.evaluateStructural(capability);
        if (structural != null) {
            log.debug("Permission denied (structural): key={}, reason={}",
                    allowlistKey, structural.reason());
            audit(allowlistKey, capability, provenance, structural, null);
            return structural;
        }

        String sessionIdOrNull = provenance.sessionId().map(s -> s.value()).orElse(null);
        if (sessionIdOrNull != null) {
            var allow = sessionApprovals.get(sessionIdOrNull);
            if (allow != null && allow.contains(allowlistKey)) {
                log.debug("Permission auto-approved (session blanket): key={}, sessionId={}",
                        allowlistKey, sessionIdOrNull);
                var decision = new PermissionDecision.Approved();
                audit(allowlistKey, capability, provenance, decision, "session-blanket-approval");
                return decision;
            }
        }

        // PolicyEngine now consumes the structured capability + provenance
        // directly (#465 Scope #2 / #480 PR 4). The flat PermissionRequest
        // bridge is gone — policies pattern-match on the sealed variant and
        // can reach fields like FileWrite.path, HttpFetch.url, etc.
        // `description` is the dispatcher's rich human-readable phrasing,
        // forwarded so the policy can produce a user-facing prompt that
        // matches the tool side rather than the variant's synthetic
        // displayLabel.
        var decision = policy.evaluate(capability, provenance, description);
        log.debug("Permission check: key={}, level={}, sessionId={}, decision={}",
                allowlistKey, capability.risk(), sessionIdOrNull,
                decision.getClass().getSimpleName());
        audit(allowlistKey, capability, provenance, decision, null);
        return decision;
    }

    /**
     * Writes one v2 audit entry — structured {@link Capability} and full
     * {@link Provenance} (#480 PR 3). Flattens the sealed
     * {@link PermissionDecision} into the on-disk string form
     * ({@code APPROVED} / {@code DENIED} / {@code NEEDS_APPROVAL}) and
     * chooses the {@code reason} field: caller-supplied note (for the
     * session-blanket branch), the denial reason (for Denied), the prompt
     * (for NeedsUserApproval), or null.
     *
     * <p>The on-disk record carries:
     *
     * <ul>
     *   <li>{@code allowlistKey} → {@code toolName} field — keeps v1 query
     *       tooling that filters by tool name working unchanged across the
     *       schema bump (e.g. "show me all bash decisions" still works).</li>
     *   <li>{@code capability.risk()} → {@code level} field — same reason.
     *       For migrated tools this matches the variant's structural risk
     *       (and reflects {@code BashExec}'s self-escalation to
     *       {@code DANGEROUS}); for legacy callers (the
     *       {@link #check(PermissionRequest, String)} shim wraps as
     *       {@link Capability.LegacyToolUse}) it carries the
     *       declared level.</li>
     *   <li>{@code capability} and {@code provenance} → typed JSON nested
     *       objects, so PolicyEngine and the dashboard timeline see paths,
     *       URLs, plan-step IDs, etc. directly without having to parse the
     *       human prompt.</li>
     * </ul>
     */
    private void audit(
            String allowlistKey,
            Capability capability,
            Provenance provenance,
            PermissionDecision decision,
            String approvalNote) {
        if (auditLog == null) return;
        // Audit is best-effort by contract — a degraded log must not abort
        // the agent. CapabilityAuditLog.appendEntry already swallows
        // IOException internally, but the v2 path's signablePayload(...)
        // can surface a serialisation IllegalStateException through here,
        // and any other unchecked exception would propagate out of the
        // permission check. Wrap the whole branch so audit failures
        // produce a warning, not a turn-killing error.
        try {
            String kind;
            String reason;
            switch (decision) {
                case PermissionDecision.Approved _ -> {
                    kind = "APPROVED";
                    reason = approvalNote;
                }
                case PermissionDecision.Denied d -> {
                    kind = "DENIED";
                    reason = d.reason();
                }
                case PermissionDecision.NeedsUserApproval n -> {
                    kind = "NEEDS_APPROVAL";
                    reason = n.prompt();
                }
            }
            auditLog.record(Instant.now(), allowlistKey, capability, provenance, kind, reason);
        } catch (RuntimeException auditFailure) {
            log.warn("Audit log write failed for tool={}, level={}: {}",
                    allowlistKey, capability.risk(), auditFailure.getMessage());
        }
    }

    /**
     * Runs only the structural / system-invariant denial layer of the policy
     * — no session-blanket lookup, no mode-based decision. Used by the
     * sub-agent permission path (which previously consulted only the
     * session-approval boolean, bypassing the structural rules entirely —
     * Codex P1 on #495). Returns {@code null} when no structural rule
     * applies; the caller then routes through whatever approval logic is
     * appropriate for its context.
     *
     * <p>When the structural layer denies, an audit entry is written so
     * sub-agent attempts to write {@code .env} / {@code .ssh/} / etc. are
     * observable in the same on-disk record as main-dispatcher denials.
     * Without this entry, a successful structural denial on the sub-agent
     * path would be invisible to forensics — the caller (the sub-agent
     * permission checker) can't audit because it doesn't depend on
     * {@code aceclaw-security}'s audit types.
     *
     * <p>No double-audit risk on the main dispatcher path: that path runs
     * {@code policy.evaluateStructural} directly inside
     * {@link #check(Capability, Provenance, String, String)} (which has its
     * own audit hook) and does NOT route through this method.
     *
     * @param capability  the structured capability to test
     * @param provenance  audit context recorded when a denial is written.
     *                    {@code null} is allowed for callers that have no
     *                    session in scope; uses
     *                    {@link Provenance#daemonInternal()} as a stand-in.
     * @param allowlistKey audit context — the originating tool name, so
     *                     {@code grep toolName=...} on the on-disk log
     *                     keeps working uniformly across denial sources.
     */
    public PermissionDecision.Denied checkStructural(
            Capability capability,
            Provenance provenance,
            String allowlistKey) {
        Objects.requireNonNull(capability, "capability");
        var denial = policy.evaluateStructural(capability);
        if (denial != null) {
            var prov = provenance != null ? provenance : Provenance.daemonInternal();
            String key = allowlistKey != null ? allowlistKey : capability.allowlistKey();
            log.debug("Permission denied (structural, out-of-band): key={}, reason={}",
                    key, denial.reason());
            audit(key, capability, prov, denial, null);
        }
        return denial;
    }

    /**
     * Records a blanket session-level approval for a tool. After this
     * call, future requests for this tool from THIS session are
     * auto-approved (other sessions are unaffected — see #456).
     */
    public void approveForSession(String sessionId, String toolName) {
        Objects.requireNonNull(sessionId, "sessionId");
        Objects.requireNonNull(toolName, "toolName");
        sessionApprovals
                .computeIfAbsent(sessionId, k -> ConcurrentHashMap.newKeySet())
                .add(toolName);
        log.info("Session-level approval granted: tool={}, sessionId={}",
                toolName, sessionId);
    }

    /**
     * Clears the allow-list for a single session. Intended to be wired
     * to the daemon's session-destroy hook so allow-lists for ended
     * sessions don't leak indefinitely.
     */
    public void clearSessionApprovals(String sessionId) {
        Objects.requireNonNull(sessionId, "sessionId");
        var removed = sessionApprovals.remove(sessionId);
        if (removed != null) {
            log.debug("Session approvals cleared for sessionId={}", sessionId);
        }
    }

    /**
     * Clears every session's allow-list. Test/admin helper — use
     * {@link #clearSessionApprovals(String)} for normal session
     * teardown.
     */
    public void clearAllSessionApprovals() {
        sessionApprovals.clear();
        log.debug("All session approvals cleared");
    }

    /**
     * Returns whether the tool has blanket approval in the given session.
     */
    public boolean hasSessionApproval(String sessionId, String toolName) {
        Objects.requireNonNull(sessionId, "sessionId");
        Objects.requireNonNull(toolName, "toolName");
        var allow = sessionApprovals.get(sessionId);
        return allow != null && allow.contains(toolName);
    }

}