Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

24.8 KB
Raw Blame
//! `GET /api/projects/{project_id}/feature_flags/{key}/remote_config`
//!
//! Port of Django's `FeatureFlagViewSet.remote_config`. Returns a remote-config flag's
//! payload, decrypting encrypted payloads **only** for personal-API-key callers
//! (project-secret callers get the redacted marker), matching Django exactly.
//!
//! Auth/scoping mirrors Django's KLUDGE: `project_id` from the URL is used as a team id
//! for the credential check, and the flag is looked up by `team.project_id == project_id`.
//! Session-cookie auth is intentionally not ported (not an SDK path), same as
//! `flag_definitions`.
//!
//! Not ported, consistent with `flag_definitions`/`local_evaluation` (so "matches Django"
//! does not extend to these): per-flag access control (advanced RBAC) is not enforced.
//! Personal-key callers are checked for scope and team/org membership only, not role-based
//! feature flag access, even though this endpoint can return decrypted payloads. OAuth
//! access tokens are also not accepted — any non-`phs_` bearer goes through personal-key
//! validation and gets 401; only `phs_` and `phx_` credentials work.
//!
//! Supports `If-None-Match` conditional requests like `/flags/definitions`, but with a
//! content-derived ETag: no cache backs this endpoint (the payload is read from Postgres
//! per request), so the etag is a hash of the exact response body computed after payload
//! resolution. That makes it caller-dependent by construction — a secret-key caller's
//! redacted body and a personal-key caller's decrypted body hash to different etags, so a
//! 304 never validates one credential class's cached body against the other's. A match
//! saves the body transfer, not the DB read.
//!
//! Because the body varies by `Authorization` at the same URL, responses carry
//! `Cache-Control: private, no-cache` (revalidate on every reuse, not just when stale)
//! and `Vary: Authorization` — otherwise a private cache primed by a personal-key
//! request could replay the decrypted body to a secret-key caller without ever hitting
//! the etag check.

use crate::api::api_key_usage::ApiKeyKind;
use crate::{
    api::{auth, errors::FlagError, flag_definitions},
    database::get_connection_with_metrics,
    flags::flag_payload_decryptor::REDACTED_PAYLOAD_VALUE,
    metrics::consts::{REMOTE_CONFIG_AUTH_COUNTER, REMOTE_CONFIG_ETAG_COUNTER},
    router::State as AppState,
    team::team_models::Team,
    utils::python_truthiness::is_falsy,
};
use axum::{
    debug_handler,
    extract::{Path, Query, State},
    http::{HeaderMap, Method, StatusCode},
    response::{IntoResponse, Response},
};
use common_metrics::inc;
use serde::Deserialize;
use serde_json::Value;
use tracing::warn;

/// The body varies by `Authorization` at the same URL (decrypted vs redacted), so caches
/// must revalidate on every reuse (`no-cache`, stronger than the sibling endpoint's
/// `must-revalidate`) and key entries by credential (`Vary: Authorization`).
const CACHE_CONTROL: &str = "private, no-cache";
const VARY: &str = "Authorization";

/// Query params. SDKs pass `?token=phc_...` (the project key) and call this with `@current`
/// as the URL segment; the token resolves the project, matching Django. `api_key` is Django's
/// accepted alias for `token` (see `get_token`).
#[derive(Deserialize)]
pub struct RemoteConfigQuery {
    token: Option<String>,
    api_key: Option<String>,
}

enum AuthOutcome {
    Authorized {
        should_decrypt: bool,
        /// The team the request is scoped to, used for the throttle allowlist bypass.
        team_id: i32,
        /// Per-credential throttle key. `Some(pak_id)` for personal API keys (which Django
        /// throttles), `None` for secret keys (which Django does not throttle).
        rate_limit_key: Option<String>,
    },
    /// Credential is valid but not for this project (Django: 403 team mismatch).
    Forbidden,
    /// No team with the scoped id (Django: `view.team` raises -> 404 "Project not found").
    ProjectNotFound,
}

#[debug_handler]
pub async fn remote_config(
    State(state): State<AppState>,
    Path((project_segment, key)): Path<(String, String)>,
    Query(params): Query<RemoteConfigQuery>,
    method: Method,
    headers: HeaderMap,
) -> Result<Response, FlagError> {
    // Non-GET methods are handled before auth, matching the sibling endpoint: HEAD -> 200 and
    // unsupported methods -> 405 with an Allow header. A CORS *preflight* OPTIONS (one carrying
    // Access-Control-Request-Method) is answered upstream by the permissive CORS layer with 200; a
    // bare OPTIONS falls through to here and `handle_non_get_method` returns 204. HEAD diverges from
    // Django, which maps HEAD to the GET action and runs the full pipeline -- an unauthenticated
    // HEAD is 401 there, 200 here -- but no SDK sends either method.
    if method != Method::GET {
        return Ok(flag_definitions::handle_non_get_method(&method));
    }

    // Resolve the effective `?token=` (Django's `get_token`: an empty value is absent, and
    // `?api_key=` is an alias). SDKs call this with `@current` as the URL segment plus a
    // `?token=phc_...` project key; Django resolves the project from the token first, so the token
    // wins when present (and `@current` never needs interpreting). Without a token, a numeric
    // segment is the project id, and `@current` resolves to the bearer credential's project (see
    // `resolve_current_team`); any other non-numeric segment 404s (Django's `int()` ValueError).
    let token_param = params
        .token
        .as_deref()
        .filter(|t| !t.is_empty())
        .or_else(|| params.api_key.as_deref().filter(|t| !t.is_empty()));

    // Resolve only what auth needs here: the team id, and (on the `?token=` path) the resolved
    // team. The project id is needed solely for the flag lookup, so it is computed after auth and
    // the throttle — no DB read happens before an unauthenticated caller is rejected.
    // `verify_token_and_get_team` is cache-backed, so the `?token=` path does no uncached DB work
    // at this point either, and `resolve_current_team` goes through the shared auth-token cache so
    // the bearer-only `@current` path doesn't either.
    let (scope_team_id, resolved_team): (i32, Option<Team>) = if let Some(token) = token_param {
        match state.flag_service().verify_token_and_get_team(token).await {
            // Keep the team so the personal-key auth path and the project lookup below don't
            // re-query it. Django raises AuthenticationFailed for an invalid `?token=`.
            Ok(team) => (team.id, Some(team)),
            Err(_) => return Ok(StatusCode::UNAUTHORIZED.into_response()),
        }
    } else if project_segment == "@current" {
        // `@current` without a `?token=`: resolve the project from the bearer credential,
        // mirroring Django (`current_team = team_from_request or user.current_team`). Server
        // SDKs fetch remote config exactly this way — a `phs_`/`phx_` bearer, `@current`, no
        // query token — so this must resolve, not 404. `Ok(None)` is a valid credential with no
        // current team (Django: 404 "Project not found"); a missing credential surfaces as 401.
        match resolve_current_team(&state, &headers).await? {
            Some(team) => (team.id, Some(team)),
            None => return Ok(StatusCode::NOT_FOUND.into_response()),
        }
    } else {
        match project_segment.parse::<i32>() {
            Ok(id) => (id, None),
            Err(_) => return Ok(StatusCode::NOT_FOUND.into_response()),
        }
    };

    let (should_decrypt, team_id, rate_limit_key) =
        match authenticate(&state, scope_team_id, resolved_team.as_ref(), &headers).await? {
            AuthOutcome::Authorized {
                should_decrypt,
                team_id,
                rate_limit_key,
            } => (should_decrypt, team_id, rate_limit_key),
            AuthOutcome::Forbidden => return Ok(StatusCode::FORBIDDEN.into_response()),
            AuthOutcome::ProjectNotFound => return Ok(StatusCode::NOT_FOUND.into_response()),
        };

    // Throttle mirroring Django's RemoteConfigThrottle: only personal-API-key requests are
    // throttled, bucketed per credential, and allowlisted teams bypass. Secret-key requests
    // carry no `rate_limit_key` and are not throttled. Runs before the DB lookup to shield PG.
    if let Some(cred_key) = rate_limit_key {
        if !state
            .config
            .rate_limiting_allow_list_teams
            .0
            .contains(&team_id)
        {
            state.remote_config_limiter.check_rate_limit(cred_key)?;
        }
    }

    // Resolve the project to scope the flag lookup, now that the caller is authenticated and past
    // the throttle (deferred so no DB read precedes an unauthenticated rejection). On the
    // `?token=` path the cached team usually carries project_id; only entries predating that field
    // hit the DB, and a missing row means the team was deleted from Postgres but is still cached
    // -> 401 (as Django resolves the token against PG), not a 5xx. On the numeric path the segment
    // is itself the project id.
    let scope_project_id: i64 = match &resolved_team {
        Some(team) => match team.project_id {
            Some(pid) => pid,
            None => match project_id_for_team(&state, team.id).await? {
                Some(pid) => pid,
                None => return Ok(StatusCode::UNAUTHORIZED.into_response()),
            },
        },
        None => i64::from(scope_team_id),
    };

    // Flag lookup scoped to the project. 404 if missing or not a remote config flag (the query
    // filters on `is_remote_configuration`).
    // `resolved_key` is the flag's actual `key` column, not the URL segment (which may be a
    // numeric id when the caller addresses the flag by id), so decrypt-failure logs always carry
    // the human-readable key.
    let Some((filters, has_encrypted_payloads, resolved_key)) =
        load_remote_config_flag(&state, scope_project_id, &key).await?
    else {
        return Ok(StatusCode::NOT_FOUND.into_response());
    };

    // Raw filters, deliberately outside the fail-closed config-format boundary the
    // evaluation paths use: Django's own view reads `payloads["true"]` just as raw and is
    // shadow-compared against this one, so a Rust-only version guard would read as a
    // permanent mismatch.
    let stored = filters.get("payloads").and_then(|p| p.get("true"));

    // Resolve the payload, mirroring Django's `Response(payloads["true"] or None)`: the stored
    // value (unencrypted), the decrypted plaintext (personal key), or the redacted marker (secret
    // key on an encrypted flag).
    //
    // Deliberate divergence on malformed rows: an encrypted flag missing the "true" entry makes
    // Django 500 (both credential paths index `decrypted_payloads["true"]` -> KeyError); a
    // non-string stored value makes the decrypt path feed `str(value)` to Fernet and 500 on
    // InvalidToken. Both are shapes the serializer shouldn't allow. We return gracefully instead
    // -- a missing payload is an empty body on either credential, and the redact path only marks a
    // payload that actually exists -- so phase 2 reads these rare rows as a known diff, not a bug.
    let payload: Option<Value> = if has_encrypted_payloads != Some(true) {
        stored.cloned()
    } else if should_decrypt {
        resolve_decrypted_payload(&state, stored, scope_project_id, &resolved_key)?
    } else {
        stored.map(|_| Value::String(REDACTED_PAYLOAD_VALUE.to_string()))
    };

    // Django applies `or None` to the final value and renders None as an empty body, not
    // the JSON literal `null`. Apply the falsy check after decryption so an empty decrypted
    // string nulls out too. In practice the payload is always a JSON-encoded string.
    let payload = payload.filter(|v| !is_falsy(v));

    // `Value::to_string` produces the same compact JSON `Json(v)` would serialize, so the
    // etag hashes the exact bytes the client receives (empty payloads hash the empty body).
    let body = payload.as_ref().map(Value::to_string).unwrap_or_default();
    let current_etag = compute_etag(&body);

    let client_etag = flag_definitions::extract_etag_from_header(headers.get("if-none-match"));
    if client_etag.as_deref() == Some(current_etag.as_str()) {
        inc(
            REMOTE_CONFIG_ETAG_COUNTER,
            &[("result".to_string(), "hit".to_string())],
            1,
        );
        return Ok(not_modified(&current_etag));
    }
    inc(
        REMOTE_CONFIG_ETAG_COUNTER,
        &[(
            "result".to_string(),
            if client_etag.is_some() {
                "miss"
            } else {
                "none"
            }
            .to_string(),
        )],
        1,
    );

    match payload {
        Some(_) => Ok(json_ok_with_etag(body, &current_etag)),
        None => Ok(empty_ok_no_content_type(&current_etag)),
    }
}

/// Content-derived ETag over the exact response body, using the same HyperCache helper
/// that produces `/flags/definitions` etags, so SDKs see one etag format across both
/// endpoints.
fn compute_etag(body: &str) -> String {
    common_hypercache::writer::compute_etag(body)
}

/// The ETag/Cache-Control/Vary trio every response carries. Shared so the credential
/// isolation (`no-cache` + `Vary: Authorization`) can't silently drop off one response
/// path while surviving on the others.
fn revalidation_headers(etag: &str) -> [(&'static str, String); 3] {
    [
        ("etag", flag_definitions::format_weak_etag(etag)),
        ("cache-control", CACHE_CONTROL.to_string()),
        ("vary", VARY.to_string()),
    ]
}

/// 200 with a pre-serialized JSON body plus the revalidation headers.
fn json_ok_with_etag(body: String, etag: &str) -> Response {
    (
        StatusCode::OK,
        [("content-type", "application/json")],
        revalidation_headers(etag),
        body,
    )
        .into_response()
}

/// 304 carrying the same revalidation headers as the 200s — not the sibling endpoint's
/// `not_modified_response`, whose `must-revalidate` would weaken the stored entry's
/// policy when a cache updates its headers from the 304.
fn not_modified(etag: &str) -> Response {
    (StatusCode::NOT_MODIFIED, revalidation_headers(etag)).into_response()
}

/// Decrypts the stored ciphertext on the personal-key path. Returns `None` when there is no
/// stored value or it is not a string (Django 500s on those malformed rows; we render an empty
/// body instead). Errors (500) on a decrypt failure or a missing decryptor.
///
/// `project_id`/`flag_key` are logged on failure only for correlation (which flag keeps
/// failing) -- never the token or any key material, which `FlagPayloadDecryptorError`'s
/// `Display` already excludes by construction (see `flag_payload_decryptor.rs`).
fn resolve_decrypted_payload(
    state: &AppState,
    stored: Option<&Value>,
    project_id: i64,
    flag_key: &str,
) -> Result<Option<Value>, FlagError> {
    let Some(Value::String(token)) = stored else {
        return Ok(None);
    };
    let Some(decryptor) = state.flag_payload_decryptor.as_ref() else {
        warn!(
            project_id,
            flag_key, "remote_config: no FLAGS_SECRET_KEYS configured; cannot decrypt payload"
        );
        return Err(FlagError::RemoteConfigDecryptFailed(
            "no decryption keys configured".to_string(),
        ));
    };
    decryptor
        .decrypt(token)
        .map(|plaintext| Some(Value::String(plaintext)))
        .map_err(|e| {
            warn!(
                project_id,
                flag_key, "remote_config payload decrypt failed: {e}"
            );
            FlagError::RemoteConfigDecryptFailed(e.to_string())
        })
}

/// 200 with an empty body and no Content-Type (NOT a JSON `null`), matching DRF's `Response(None)`:
/// the renderer emits no bytes and DRF then deletes the Content-Type header. Still carries the
/// revalidation headers so a client polling a not-yet-set payload can 304 too.
fn empty_ok_no_content_type(etag: &str) -> Response {
    (StatusCode::OK, revalidation_headers(etag)).into_response()
}

/// Authenticates and resolves the decrypt gate against the already-resolved scope team,
/// mirroring Django.
///
/// - `phs_` (team/project secret): the token's team must be `scope_team_id`. On mismatch,
///   403 if that team exists, 404 if it does not (Django's `view.team` raises). Never decrypts.
/// - `phx_` (personal API key): validated (scopes + access) against `Team(scope_team_id)`.
///   Decrypts.
async fn authenticate(
    state: &AppState,
    scope_team_id: i32,
    resolved_team: Option<&Team>,
    headers: &HeaderMap,
) -> Result<AuthOutcome, FlagError> {
    if let Some(token) = auth::extract_team_secret_token(headers) {
        let secret = auth::validate_secret_api_token(state, &token).await?;
        let team_id = secret.team_id;
        // Django: authenticated_team.id == view.team.id.
        if team_id != scope_team_id {
            // Mismatch resolves like Django: 403 when a real (different) team owns the
            // project, 404 when no such team exists (Django's `view.team` raises). The
            // lookup only runs on this error path, never on the matching hot path.
            return match state.flag_service().get_team_by_id(scope_team_id).await {
                Ok(_) => Ok(AuthOutcome::Forbidden),
                Err(FlagError::SecretApiTokenInvalid) | Err(FlagError::RowNotFound) => {
                    Ok(AuthOutcome::ProjectNotFound)
                }
                Err(e) => Err(e),
            };
        }
        // Mirror the sibling's per-method auth counter; the secret-vs-personal split matters here
        // because it decides redact-vs-decrypt, so the mix is worth watching during phase 2/3.
        inc(
            REMOTE_CONFIG_AUTH_COUNTER,
            &[("method".to_string(), secret.method_label().to_string())],
            1,
        );
        state
            .record_project_secret_key_usage(secret.project_secret_key_id)
            .await;
        // Secret-key requests are not throttled by Django's RemoteConfigThrottle.
        return Ok(AuthOutcome::Authorized {
            should_decrypt: false,
            team_id,
            rate_limit_key: None,
        });
    }

    if let Some(key) = auth::extract_personal_api_key(headers)? {
        // view.team = Team(scope_team_id); missing -> 404. Reuse the team the handler already
        // fetched on the `?token=` path; only query on the numeric-segment path where none was.
        let fetched;
        let team: &Team = match resolved_team {
            Some(t) => t,
            None => {
                fetched = match state.flag_service().get_team_by_id(scope_team_id).await {
                    Ok(team) => team,
                    Err(FlagError::SecretApiTokenInvalid) | Err(FlagError::RowNotFound) => {
                        return Ok(AuthOutcome::ProjectNotFound)
                    }
                    Err(e) => return Err(e),
                };
                &fetched
            }
        };
        let pak_id =
            auth::validate_personal_api_key_with_scopes_for_team(state, &key, team).await?;
        inc(
            REMOTE_CONFIG_AUTH_COUNTER,
            &[("method".to_string(), "personal_api_key".to_string())],
            1,
        );
        // Per-credential throttle bucket (Django keys on the hashed bearer token; the stable
        // pak id is an equivalent per-credential identifier for our in-memory limiter).
        let rate_limit_key = Some(pak_id.clone());

        // Track PAK usage so a key used only for remote config doesn't look dormant and get
        // rotated as unused. Shared with flag_definitions via the State helper.
        state
            .record_api_key_last_used(ApiKeyKind::Personal, pak_id)
            .await;

        return Ok(AuthOutcome::Authorized {
            should_decrypt: true,
            team_id: scope_team_id,
            rate_limit_key,
        });
    }

    Err(FlagError::NoAuthenticationProvided)
}

/// Resolves the project scope for an `@current` request that has no `?token=`, from the bearer
/// credential — mirroring Django's `current_team = team_from_request or user.current_team`: a
/// team/project secret token (`phs_`) resolves its own team; a personal API key (`phx_`) resolves
/// its user's current team. `Ok(None)` means the credential is valid but has no current team
/// (Django: 404 "Project not found"); an absent or invalid credential surfaces as 401 via the
/// propagated error. The resolved team is re-validated by `authenticate`, so this only establishes scope.
async fn resolve_current_team(
    state: &AppState,
    headers: &HeaderMap,
) -> Result<Option<Team>, FlagError> {
    if let Some(token) = auth::extract_team_secret_token(headers) {
        let team_id = auth::validate_secret_api_token(state, &token)
            .await?
            .team_id;
        return Ok(Some(state.flag_service().get_team_by_id(team_id).await?));
    }
    if let Some(key) = auth::extract_personal_api_key(headers)? {
        return match auth::current_team_id_for_personal_api_key(state, &key).await? {
            Some(team_id) => Ok(Some(state.flag_service().get_team_by_id(team_id).await?)),
            None => Ok(None),
        };
    }
    Err(FlagError::NoAuthenticationProvided)
}

/// Resolves a team's `project_id`. Used on the `?token=` path only for cache entries that predate
/// the cached `project_id`, where the flag is scoped to the token team's project, not its team id.
/// Returns `None` when no such team exists (stale cache: team deleted from Postgres). `project_id`
/// is non-null (validated constraint), matching the flag-lookup JOINs that compare it directly.
async fn project_id_for_team(state: &AppState, team_id: i32) -> Result<Option<i64>, FlagError> {
    let client: common_database::PostgresReader = state.database_pools.non_persons_reader.clone();
    let mut conn = get_connection_with_metrics(&client, "non_persons_reader", "remote_config")
        .await
        .map_err(|e| {
            warn!("remote_config: failed to get db connection: {e}");
            FlagError::DatabaseUnavailable
        })?;
    let row: Option<(i64,)> =
        sqlx::query_as("SELECT project_id::bigint FROM posthog_team WHERE id = $1")
            .bind(team_id)
            .fetch_optional(&mut *conn)
            .await
            .map_err(|e| {
                warn!("remote_config project lookup failed: {e}");
                FlagError::DatabaseUnavailable
            })?;
    Ok(row.map(|r| r.0))
}

/// Loads `(filters, has_encrypted_payloads, key)` for a remote-config flag matched by numeric id
/// (if `key` is all digits) or key, scoped to `team.project_id == project_id`. The returned `key`
/// is the flag's canonical key column, which is why it is selected even though the caller may have
/// addressed the flag by id. The query filters on `is_remote_configuration IS TRUE`, so a
/// non-remote-config flag returns `None` and the caller 404s. Uses its own query, not the
/// flag-list path, which excludes encrypted RC flags.
async fn load_remote_config_flag(
    state: &AppState,
    project_id: i64,
    key: &str,
) -> Result<Option<(Value, Option<bool>, String)>, FlagError> {
    let client: common_database::PostgresReader = state.database_pools.non_persons_reader.clone();
    let mut conn = get_connection_with_metrics(&client, "non_persons_reader", "remote_config")
        .await
        .map_err(|e| {
            warn!("remote_config: failed to get db connection: {e}");
            FlagError::DatabaseUnavailable
        })?;

    // Treat the segment as a flag id only if it is all digits AND fits in i64. An
    // oversized all-digits segment can't match any real flag id, so it's a 404 — and
    // parsing it must not panic on user-controlled input.
    let parsed_id: Option<i64> = if !key.is_empty() && key.bytes().all(|b| b.is_ascii_digit()) {
        match key.parse::<i64>() {
            Ok(id) => Some(id),
            Err(_) => return Ok(None),
        }
    } else {
        None
    };

    let result = if let Some(id) = parsed_id {
        sqlx::query_as::<_, (Value, Option<bool>, String)>(
            "SELECT f.filters, f.has_encrypted_payloads, f.key \
             FROM posthog_featureflag f JOIN posthog_team t ON f.team_id = t.id \
             WHERE t.project_id = $1 AND f.deleted = false AND f.is_remote_configuration IS TRUE \
             AND f.id = $2 LIMIT 1",
        )
        .bind(project_id)
        .bind(id)
        .fetch_optional(&mut *conn)
        .await
    } else {
        sqlx::query_as::<_, (Value, Option<bool>, String)>(
            "SELECT f.filters, f.has_encrypted_payloads, f.key \
             FROM posthog_featureflag f JOIN posthog_team t ON f.team_id = t.id \
             WHERE t.project_id = $1 AND f.deleted = false AND f.is_remote_configuration IS TRUE \
             AND f.key = $2 LIMIT 1",
        )
        .bind(project_id)
        .bind(key)
        .fetch_optional(&mut *conn)
        .await
    };

    result.map_err(|e| {
        warn!("remote_config flag query failed: {e}");
        FlagError::DatabaseUnavailable
    })
}