futu_auth/

audit.rs

//! 审计事件发射 helpers + JSONL 订阅层
//!
//! ## 设计
//!
//! 所有 interface（grpc / rest / ws / mcp）把 auth 决策和下单事件都走同一组
//! helper，emit 的 `tracing::event!` 使用固定 `target = "futu_audit"`。这样：
//!
//! - 正常日志订阅（stderr / 文件）照常能看到它们（没过滤就全走）
//! - 专用 audit JSONL 文件订阅层走 `filter_fn(meta.target() == TARGET)` 只收这些
//!
//! JSONL 每条一行，字段固定 —— 字段顺序由 tracing-subscriber 的 json formatter
//! 决定（level / timestamp / target / message / 其它 fields），方便 `jq`/`duckdb`
//! 后处理。
//!
//! ## 事件形状（field 命名）
//!
//! | 字段       | 含义                                        |
//! |-----------|---------------------------------------------|
//! | iface     | `"grpc"` / `"rest"` / `"ws"` / `"mcp"`    |
//! | endpoint  | 具体接口：路径 / proto_id / tool 名         |
//! | key_id    | API key id，或 `<missing>` / `<invalid>`   |
//! | outcome   | `"allow"` / `"reject"`                     |
//! | reason    | reject 时的文字原因（allow 时也可选）       |
//! | args_hash | 下单工具额外附：args 的 SHA-256 前 8 hex   |
//! | scope     | 校验的 scope（allow 时可选）                |

use std::path::Path;

use tracing::Level;

/// 固定 target，供 tracing filter 使用
pub const TARGET: &str = "futu_audit";

/// auth 拒绝事件
pub fn reject(iface: &str, endpoint: &str, key_id: &str, reason: &str) {
    tracing::event!(
        target: TARGET,
        Level::WARN,
        iface = iface,
        endpoint = endpoint,
        key_id = key_id,
        outcome = "reject",
        reason = reason,
        "auth reject"
    );
    crate::metrics::bump_auth_event(iface, "reject", key_id);
    // 限额类的 reject 额外分桶计数（reason 以 "limit: " 开头是 guard 产生的）
    if let Some(rest) = reason.strip_prefix("limit: ") {
        crate::metrics::bump_limit_reject(iface, key_id, rest);
    } else if reason.starts_with("rate limit")
        || reason.starts_with("daily value")
        || reason.starts_with("order value")
    {
        crate::metrics::bump_limit_reject(iface, key_id, reason);
    }
}

/// auth 通过事件（用 INFO 级别；debug 模式会看到量比较大，由 EnvFilter 过滤）
pub fn allow(iface: &str, endpoint: &str, key_id: &str, scope: Option<&str>) {
    tracing::event!(
        target: TARGET,
        Level::INFO,
        iface = iface,
        endpoint = endpoint,
        key_id = key_id,
        outcome = "allow",
        scope = scope.unwrap_or(""),
        "auth allow"
    );
    crate::metrics::bump_auth_event(iface, "allow", key_id);
}

/// 交易事件（下单 / 改单 / 撤单）—— 无论 allow / reject 都记录
pub fn trade(
    iface: &str,
    tool: &str,
    key_id: &str,
    args_hash: &str,
    outcome: &str,
    reason: Option<&str>,
) {
    tracing::event!(
        target: TARGET,
        Level::WARN,
        iface = iface,
        endpoint = tool,
        key_id = key_id,
        outcome = outcome,
        args_hash = args_hash,
        reason = reason.unwrap_or(""),
        "trade event"
    );
    crate::metrics::bump_auth_event(iface, outcome, key_id);
}

// -------- JSONL 层安装 --------
//
// 这里不直接返回一个 `impl Layer<S>` 是因为 tracing-subscriber 的类型签名挺拗，
// 放在 main.rs 里现场拼装反而清爽。下面这对 helper 把 "打开文件 + non-blocking
// 包装" 抽成一个函数，并在退出时保留 guard 防止 flush 丢失。

/// 打开 audit 输出路径，返回一个非阻塞 writer 和 guard（guard 必须活到进程退出）
///
/// - 如果 path 以 `.jsonl` / `.log` 等后缀结尾，直接当成单文件 append 打开
/// - 否则视为目录，使用每日滚动，文件名 `futu-audit.log`
pub fn open_writer(
    path: &Path,
) -> std::io::Result<(
    tracing_appender::non_blocking::NonBlocking,
    tracing_appender::non_blocking::WorkerGuard,
)> {
    // 启发式：
    //   - 已存在的目录 → 目录
    //   - 以 '/' 结尾 → 目录
    //   - 没有扩展名 → 目录
    //   - 有扩展名 → 单文件
    // 想明确语义的话用户可以直接 `mkdir -p /foo/bar` 再传路径。
    let is_dir_hint = path.is_dir()
        || path.as_os_str().to_string_lossy().ends_with('/')
        || path.extension().is_none();

    // v1.4.87 CLAUDE.md 坑 #49: /tmp/ 是 world-readable (1777). audit log 可能
    // 含 redacted token 占位 + timestamp + account id 等 metadata, 放 /tmp 对
    // skill / 其他 local user 可读, 不安全. 硬约定在 stderr 打 warn 提醒用户.
    warn_if_world_readable_path(path);

    if is_dir_hint {
        // 目录：每日滚动
        std::fs::create_dir_all(path)?;
        tighten_dir_perms(path); // v1.4.87: 0700 on Unix
        // v1.4.93 BUG-5318-001 (跨 4 版半修补完): tracing_appender::rolling 创建
        // 滚动 log file 时使用默认 OpenOptions, 不接受 mode 参数 → 文件 mode 是
        // umask-dependent (典型 0644). v1.4.87 / 88 / 89 / 90 changelog 都承诺
        // "audit log 文件 0600", 但 dir-rolling 路径下从未生效, 仅 0700 dir 真修.
        // 修法: 立即 tighten 现有文件 (启动时 dir 里可能已有老文件 0644) +
        // 包一层 Mode0600Appender 在每次 write 后 best-effort tighten 当前 file.
        tighten_log_files_in_dir(path); // v1.4.93: 启动 sweep 老文件
        let appender = tracing_appender::rolling::daily(path, "futu-audit.log");
        let wrapped = Mode0600Appender::new(appender, path.to_path_buf());
        Ok(tracing_appender::non_blocking(wrapped))
    } else {
        // 单文件：append
        if let Some(parent) = path.parent()
            && !parent.as_os_str().is_empty()
        {
            std::fs::create_dir_all(parent)?;
            tighten_dir_perms(parent); // v1.4.87: 0700 on Unix
        }
        let file = open_file_0600(path)?; // v1.4.87: 0600 on Unix
        Ok(tracing_appender::non_blocking(file))
    }
}

/// v1.4.87 CLAUDE.md 坑 #49: Audit log dir 0700 permission (Unix only).
///
/// Windows/其他 OS no-op. 已有目录如果是更严的 perm (例如 0500), 不动 — best-effort
/// tighten, 不 loosen.
pub(crate) fn tighten_dir_perms(path: &Path) {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        if let Ok(meta) = std::fs::metadata(path) {
            let cur = meta.permissions().mode() & 0o777;
            // 只收紧, 不 loosen. cur > 0o700 → 收到 0700. cur <= 0o700 不动.
            if cur & 0o077 != 0 {
                let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700));
            }
        }
    }
    #[cfg(not(unix))]
    {
        let _ = path;
    }
}

/// v1.4.87 CLAUDE.md 坑 #49: Open audit log file with 0600 permission (Unix).
///
/// 等价于 `OpenOptions::new().append(true).create(true).open(path)` + 0600 mode.
/// 已有文件如果已有更严 perm 也不动. Windows no-op.
pub(crate) fn open_file_0600(path: &Path) -> std::io::Result<std::fs::File> {
    let mut opts = std::fs::OpenOptions::new();
    opts.append(true).create(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        opts.mode(0o600);
    }
    let file = opts.open(path)?;
    // 已存在文件 create=true 不会改 mode. 所以需 set_permissions 收紧.
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        if let Ok(meta) = file.metadata() {
            let cur = meta.permissions().mode() & 0o777;
            if cur & 0o077 != 0 {
                let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
            }
        }
    }
    Ok(file)
}

/// v1.4.87 CLAUDE.md 坑 #49: stderr warn if log path 是 world-readable 目录
/// (典型 `/tmp/`, `/var/tmp/`, `/private/tmp/`).
fn warn_if_world_readable_path(path: &Path) {
    let s = path.as_os_str().to_string_lossy();
    let world_readable_prefixes = ["/tmp/", "/var/tmp/", "/private/tmp/", "/tmp"];
    for prefix in &world_readable_prefixes {
        if s == *prefix || s.starts_with(prefix) {
            eprintln!(
                "⚠️  audit log path {s:?} 位于 world-readable 目录 (mode 1777). \
                 audit log 含账户 id + redacted token 占位 + timestamp, 同机其他\n\
                 用户 (包括 agent skill) 可读. 建议改用 ~/.futu-opend-rs/logs/ \
                 或 /var/log/futu/ 等 0700 目录."
            );
            break;
        }
    }
}

/// v1.4.93 BUG-5318-001: 包装 `RollingFileAppender`, 每次 write 之后 best-effort
/// 把 dir 中的 `futu-audit.log*` 文件 chmod 0o600 (Unix only). 1s debounce 避免
/// 高频 chmod 带来的 IO 抖动.
///
/// 必须包 `RollingFileAppender` 而不是 inject `OpenOptionsExt::mode(0o600)` 是因为
/// tracing-appender 0.2.5 没有 builder 暴露 OpenOptions custom mode (`create_writer`
/// hardcoded `OpenOptions::new().append(true).create(true).open(path)`). 等 upstream
/// 加 builder 后可改用更优方案.
struct Mode0600Appender {
    inner: tracing_appender::rolling::RollingFileAppender,
    dir: std::path::PathBuf,
    last_tighten: std::sync::atomic::AtomicU64, // last tighten epoch second
}

impl Mode0600Appender {
    fn new(inner: tracing_appender::rolling::RollingFileAppender, dir: std::path::PathBuf) -> Self {
        Self {
            inner,
            dir,
            last_tighten: std::sync::atomic::AtomicU64::new(0),
        }
    }

    /// 1s debounce: 每秒最多 chmod 一次, 避免每行都 stat/chmod
    fn maybe_tighten(&self) {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let last = self.last_tighten.load(std::sync::atomic::Ordering::Relaxed);
        if now > last
            && self
                .last_tighten
                .compare_exchange(
                    last,
                    now,
                    std::sync::atomic::Ordering::Relaxed,
                    std::sync::atomic::Ordering::Relaxed,
                )
                .is_ok()
        {
            tighten_log_files_in_dir(&self.dir);
        }
    }
}

impl std::io::Write for Mode0600Appender {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        let n = self.inner.write(buf)?;
        // 在第一次写入或日期翻滚后, RollingFileAppender 才创建新文件. 我们
        // best-effort 在 write 后立即 tighten — 1s debounce 内不重复.
        self.maybe_tighten();
        Ok(n)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.inner.flush()
    }
}

/// v1.4.93 BUG-5318-001: 把 dir 中所有 `futu-audit.log*` 文件 chmod 0o600 (Unix only).
/// 已经更严 (e.g. 0o400) 不动, best-effort tighten.
pub(crate) fn tighten_log_files_in_dir(dir: &Path) {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let Ok(rd) = std::fs::read_dir(dir) else {
            return;
        };
        for entry in rd.flatten() {
            let p = entry.path();
            let name = match p.file_name().and_then(|n| n.to_str()) {
                Some(n) => n,
                None => continue,
            };
            // 只处理 futu-audit.log* (含日期后缀)
            if !name.starts_with("futu-audit.log") {
                continue;
            }
            if let Ok(meta) = std::fs::metadata(&p) {
                if !meta.is_file() {
                    continue;
                }
                let cur = meta.permissions().mode() & 0o777;
                if cur & 0o077 != 0 {
                    let _ = std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o600));
                }
            }
        }
    }
    #[cfg(not(unix))]
    {
        let _ = dir;
    }
}

#[cfg(test)]
mod tests;