lcp 0.1.0

data/docs/reference/monitoring.md

@@ -0,0 +1,222 @@
+# Monitoring Reference
+
+Monitoring provides health checks, Prometheus metrics, error logging, and AS::Notifications instrumentation for LCP Ruby applications.
+
+## Engine Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `health_check` | Boolean | `true` | Enable `GET /lcp_health` endpoint |
+| `metrics_endpoint` | Boolean | `true` | Enable `GET /metrics` Prometheus endpoint |
+| `metrics_histogram_buckets` | Array | `[0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]` | Histogram bucket boundaries (seconds) |
+| `error_log_enabled` | `:auto` / `true` / `false` | `:auto` | Enable error log persistence. `:auto` checks if `lcp_error_log` model exists |
+| `error_log_rate_limit` | Integer | `1` | Minimum seconds between DB writes for the same error fingerprint |
+| `error_log_capture_request_context` | Boolean | `false` | Include request context (IP, path) in error log |
+
+```ruby
+LcpRuby.configure do |c|
+  c.health_check = true
+  c.metrics_endpoint = true
+  c.error_log_enabled = :auto
+  c.error_log_rate_limit = 1
+end
+```
+
+## Routes
+
+| Method | Path | Controller | Auth | Description |
+|--------|------|------------|------|-------------|
+| GET | `/lcp_health` | `HealthController` | None | Health check |
+| GET | `/metrics` | `MetricsController` | None | Prometheus metrics |
+
+Both controllers inherit from `ActionController::Base` (no authentication, no presenter resolution).
+
+## Health Check
+
+**Response format:**
+
+```json
+// 200 OK
+{ "status": "ok", "checks": { "database": true, "booted": true } }
+
+// 503 Service Unavailable
+{ "status": "error", "checks": { "database": true, "booted": false } }
+```
+
+**Checks:**
+- `database` — `ActiveRecord::Base.connection.active?`
+- `booted` — `LcpRuby.booted?` (true after metadata loaded successfully)
+
+## Prometheus Metrics
+
+Requires the `prometheus-client` gem. Returns 404 if unavailable.
+
+All metrics use the `lcp_ruby_` prefix.
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `lcp_ruby_requests_total` | Counter | `presenter`, `view_group`, `model`, `action`, `method`, `status` | Total HTTP requests |
+| `lcp_ruby_request_duration_seconds` | Histogram | `presenter`, `view_group`, `model`, `action`, `method`, `status` | Request duration |
+| `lcp_ruby_errors_total` | Counter | `subsystem`, `error_class` | Errors recorded via `record_error` |
+| `lcp_ruby_cache_operations_total` | Counter | `cache`, `operation` | Cache hits, misses, invalidations |
+| `lcp_ruby_permission_checks_total` | Counter | `model`, `result` | Permission checks (granted/denied) |
+| `lcp_ruby_workflow_transitions_total` | Counter | `model`, `from_state`, `to_state` | Workflow transitions |
+| `lcp_ruby_boot_timestamp_seconds` | Gauge | — | Unix timestamp of last boot |
+| `lcp_ruby_models_loaded` | Gauge | — | Models loaded at boot |
+| `lcp_ruby_presenters_loaded` | Gauge | — | Presenters loaded at boot |
+| `lcp_ruby_pages_loaded` | Gauge | — | Pages loaded at boot |
+
+**Cardinality rules:** `status` is grouped (2xx/3xx/4xx/5xx). `presenter`, `view_group`, `model`, and `action` are bounded by metadata. `presenter`, `view_group`, and `model` use empty string `""` when not applicable.
+
+## Error Log Model
+
+Generated by `rails generate lcp_ruby:monitoring`. Fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fingerprint` | string | SHA256 of normalized error (unique index) |
+| `error_class` | string | Exception class name |
+| `message` | text | Error message (truncated to 1000 chars) |
+| `subsystem` | string | Source subsystem (top-level for efficient queries) |
+| `stacktrace` | json | First 20 stack frames |
+| `context` | json | Additional context (model, field, etc.) |
+| `occurrence_count` | integer | Total occurrences (atomic increment) |
+| `first_occurred_at` | datetime | First occurrence |
+| `last_occurred_at` | datetime | Most recent occurrence |
+
+### Fingerprint Algorithm
+
+1. Normalize message: replace UUIDs with `<UUID>`, multi-digit integers with `<ID>`
+2. Input: `"#{error_class}|#{normalized_message}|#{first_stack_frame}"`
+3. Output: SHA256 hex digest
+
+### Rate Limiting
+
+Duplicate errors (same fingerprint) are throttled to at most one DB write per `error_log_rate_limit` seconds. Occurrences between writes are accumulated in memory and flushed on next write or at process exit.
+
+### Atomic Upsert
+
+The error recorder uses an update-first pattern for concurrent safety: atomically increment `occurrence_count` via `UPDATE ... SET occurrence_count = occurrence_count + ?`, then `CREATE` on miss with `rescue ActiveRecord::RecordNotUnique` → retry.
+
+## `LcpRuby.record_error` API
+
+```ruby
+LcpRuby.record_error(exception, subsystem: "data_source", model: "order")
+```
+
+**Parameters:**
+- `exception` — the caught exception
+- `subsystem:` — string identifying the source (required)
+- `**context` — additional key-value pairs stored in the error log
+
+**Behavior:** Emits `error.lcp_ruby` AS::Notifications event (payload includes the `exception` object for host app subscribers, e.g., Sentry forwarding) → Prometheus counter increment + error log write (with rate limiting). When `error_log_capture_request_context` is enabled, also includes `request_url`, `user_id`, and `ip` in the payload. Dev/test re-raise is handled at the rescue site (not in the subscriber).
+
+**Subsystem values:**
+
+| Subsystem | Source |
+|-----------|--------|
+| `data_source` | `ResilientWrapper` — API data source errors |
+| `renderer` | `RendererRegistry` — renderer class resolution errors |
+| `condition_eval` | `ConditionEvaluator` — condition evaluation failures |
+| `broadcast` | `ResourcesController` — Turbo broadcast failures |
+| `eager_loading` | `ResourcesController` — association preloading failures |
+| `form_helper` | `FormHelper` — role/attachment/route errors |
+| `workflow` | `Workflow::ModelSource` — workflow loading errors |
+| `breadcrumbs` | `BreadcrumbBuilder` — breadcrumb resolution failures |
+| `collector` | `Metrics::CollectorRegistry` — custom collector errors |
+
+## AS::Notifications Events
+
+All events use the `.lcp_ruby` namespace suffix.
+
+| Event | Payload |
+|-------|---------|
+| `request.lcp_ruby` | `presenter`, `view_group`, `model`, `action`, `method`, `status` |
+| `error.lcp_ruby` | `exception`, `error_class`, `message`, `stacktrace`, `subsystem`, + context |
+| `authorization.lcp_ruby` | `user_id`, `roles`, `action`, `resource`, `detail`, `ip` |
+| `cache.lcp_ruby` | `cache`, `operation` |
+| `permission.lcp_ruby` | `model`, `result` |
+| `workflow_transition.lcp_ruby` | `model`, `from_state`, `to_state` |
+| `boot.lcp_ruby` | `models_count`, `presenters_count`, `pages_count` |
+
+## `value_source` for KPI Cards
+
+KPI card widgets can read from Prometheus metrics instead of model aggregates:
+
+```yaml
+widget:
+  type: kpi_card
+  value_source:
+    type: metric
+    name: lcp_ruby_requests_total
+  label_key: lcp_ruby.monitoring.total_requests
+```
+
+**Validation:** `value_source` and `model`+`aggregate` are mutually exclusive. `value_source` requires `type: metric` and `name`.
+
+## Custom Collectors
+
+Host apps can define collectors in `app/lcp_metrics/`:
+
+```ruby
+# app/lcp_metrics/erp_metrics.rb
+class ErpMetrics < LcpRuby::Metrics::Collector
+  gauge :erp_active_orders, "Number of active orders"
+  cache_ttl 60  # seconds (default: 30)
+
+  def collect
+    set(:erp_active_orders, Order.active.count)
+  end
+end
+```
+
+### DSL Methods
+
+| Method | Description |
+|--------|-------------|
+| `gauge(name, description, labels: [])` | Declare a gauge metric |
+| `counter(name, description, labels: [])` | Declare a counter metric |
+| `histogram(name, description, labels: [], buckets: nil)` | Declare a histogram metric |
+| `cache_ttl(seconds)` | Set cache TTL for `collect` (default: 30s) |
+| `subscribe(event_name, &block)` | Subscribe to AS::Notifications event |
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `set(name, value, labels: {})` | Set a gauge value |
+| `increment(name, by: 1, labels: {})` | Increment a counter |
+
+### Event Subscriptions
+
+Collectors can subscribe to AS::Notifications events for real-time metric updates:
+
+```ruby
+class PaymentMetrics < LcpRuby::Metrics::Collector
+  counter :payment_total, "Payment attempts", labels: [:status]
+
+  subscribe "payment.processed" do |event|
+    increment(:payment_total, labels: { status: event.payload[:status] })
+  end
+end
+```
+
+Subscriptions are activated at boot and cleaned up on `LcpRuby.reset!`.
+
+### Lifecycle
+
+Discovered at boot via `CollectorRegistry.discover!`. `collect` is called on each `/metrics` request with caching (default 30s) and 5-second timeout.
+
+## Generator
+
+```bash
+rails generate lcp_ruby:monitoring
+```
+
+| Output File | Purpose |
+|------------|---------|
+| `config/lcp_ruby/models/lcp_error_log.yml` | Error log model |
+| `config/lcp_ruby/presenters/lcp_error_logs.yml` | Error log presenter |
+| `config/lcp_ruby/permissions/lcp_error_log.yml` | Error log permissions |
+| `config/lcp_ruby/pages/monitoring_dashboard.yml` | Dashboard page |
+| `app/model_extensions/lcp_error_log_extension.rb` | Cleanup scope |

data/docs/reference/oidc-bearer.md

@@ -0,0 +1,269 @@
+# OIDC Bearer Validation (Phase 2)
+
+LCP can validate OAuth 2.0 bearer access tokens issued by the same OIDC
+providers configured for web login. A bearer-authenticated request
+behaves **identically** to a session-authenticated request for the same
+user — same `current_user`, same roles, same permissions.
+
+This page covers configuration, supported clients, the test-support helper
+for host-app specs, and rejection reasons. For the design rationale and
+out-of-scope items, see
+[`docs/design/oidc_auth.md`](../design/oidc_auth.md) "Phase 2 — Bearer
+Validation".
+
+## Activation
+
+Bearer validation is active for **any OIDC provider in `auth.yml` whose
+`audience:` is non-empty**. There is no separate enable switch.
+
+```yaml
+# config/lcp_ruby/auth.yml
+auth:
+  providers:
+    - name: entra
+      type: oidc
+      discovery_url: https://login.microsoftonline.com/<%= ENV["TENANT_ID"] %>/v2.0/.well-known/openid-configuration
+      client_id: <%= ENV["ENTRA_CLIENT_ID"] %>
+      client_secret: <%= ENV["ENTRA_CLIENT_SECRET"] %>
+      audience: api://lcp-prod          # ← required for bearer; web login works without it
+      claim_mappings: { external_id: oid, email: email, name: name, roles_from: roles }
+      role_source: yaml
+      role_mapping: { "LCP.Admin": admin, "LCP.Sales": sales }
+      default_role: viewer
+```
+
+Providers with no `audience:` get a boot-time warning ("no audience
+configured — Phase 2 bearer validation will skip this provider; web login
+still works") but are otherwise unaffected.
+
+The `audience` value must match the **Application ID URI** (or the scope
+audience) registered with your IdP for this LCP installation. For Microsoft
+Entra ID this is the value of the "Application ID URI" field on the app
+registration's Overview page, e.g. `api://lcp-prod`.
+
+## Token validation
+
+Required claims:
+
+| Claim | Header? | Validation |
+|---|---|---|
+| `iss` | payload | Must match a configured provider's discovery `issuer` |
+| `aud` | payload | String equality with `provider.audience` (multi-aud arrays are not supported in v2) |
+| `exp` | payload | `> now − 60s` (60 s clock skew tolerance) |
+| `nbf` | payload | If present, `<= now + 60s` |
+| `sub` | payload | Non-empty (used as `external_id` claim) |
+| `kid` | header | Used for JWKS lookup; missing → reject |
+| `alg` | header | Must be `RS256` (other algorithms are deferred to v3) |
+
+Tokens that pass validation flow through `UserResolver.from_claims`, which
+applies the same provisioning, `update_on_login`, role mapping
+(`role_source: yaml | host | db`), and `claims_synchronizer` host hook used
+by the web-login callback. The hook receives `auth: nil` in the bearer
+flow (no OmniAuth `auth_hash` exists).
+
+## Coexistence with API tokens (PATs)
+
+A deployment can register both `api_tokens` (LCP-native PATs) and OIDC
+bearer simultaneously. The resolvers are dispatched in priority order:
+
+| Resolver | Priority | Matcher |
+|---|---|---|
+| `:api_token` (PATs) | 100 | starts with `lcp_pat_` |
+| `:oidc_bearer` | 50 | three base64url segments + JSON header with `alg` |
+
+Tight matchers mean PATs and JWTs never collide. Configurators document
+per-tool guidance in their internal runbooks; the platform supports both
+paths first-class.
+
+## Supported clients
+
+### Power BI Desktop with a custom connector (canonical)
+
+The realistic Microsoft-stack story for accessing LCP feeds with Entra
+identities is a **Power Query custom connector** (`.mez`) that defines
+the OAuth flow against your Entra app registration explicitly:
+
+```pq
+[Version = "1.0.0"]
+section MyLcpConnector;
+
+[DataSource.Kind="MyLcpConnector"]
+shared MyLcpConnector.Feed = (url as text) =>
+    OData.Feed(url, null, [ ODataVersion = 4 ]);
+
+MyLcpConnector = [
+    Authentication = [
+        OAuth = [
+            StartLogin = StartLogin,
+            FinishLogin = FinishLogin,
+            Refresh = Refresh
+        ]
+    ]
+];
+
+// StartLogin / FinishLogin call Entra's authorize/token endpoints with:
+//   client_id     = <Entra app registration client_id>
+//   resource      = api://lcp-prod        (matches LCP audience)
+//   redirect_uri  = https://oauth.powerbi.com/views/oauthredirect.html
+```
+
+End users drop the `.mez` into
+`%USERPROFILE%\Documents\Power BI Desktop\Custom Connectors\` and select
+the new connector when adding a data source.
+
+> **Note: vanilla Excel.** Excel's built-in OData "Organizational account"
+> credential type is hard-wired to Microsoft-owned resources and cannot
+> generically acquire Entra access tokens for third-party APIs like LCP.
+> Excel users mint a [PAT](api-tokens.md) and paste it into Excel's
+> "Basic" credential dialog (password = token). This is **the supported
+> Excel path**, not OIDC bearer.
+
+### MSAL scripts (Python / .NET / PowerShell)
+
+Any script that performs a `client_credentials` (or device-code, or
+authorization-code) flow against the IdP and obtains an access token whose
+`aud` matches LCP's `audience` works:
+
+```python
+# Python — service account / client_credentials flow
+import msal, requests
+
+app = msal.ConfidentialClientApplication(
+    client_id="<entra-client-id>",
+    client_credential="<entra-client-secret>",
+    authority="https://login.microsoftonline.com/<tenant>"
+)
+result = app.acquire_token_for_client(scopes=["api://lcp-prod/.default"])
+token  = result["access_token"]
+
+resp = requests.get(
+    "https://lcp.example.com/api/deals.json",
+    headers={ "Authorization": f"Bearer {token}" }
+)
+```
+
+```powershell
+# PowerShell — interactive / device-code flow
+Connect-AzAccount
+$token = (Get-AzAccessToken -ResourceUrl "api://lcp-prod").Token
+Invoke-RestMethod -Uri "https://lcp.example.com/api/deals.json" `
+                  -Headers @{ Authorization = "Bearer $token" }
+```
+
+### Native desktop / mobile apps
+
+A .NET MAUI / Electron / iOS / Android app uses MSAL to sign the user in
+interactively against Entra, caches the token securely, and sends it as
+`Authorization: Bearer <token>` to LCP. From LCP's perspective this is
+identical to the script path above.
+
+## 401 challenge
+
+When a JSON request reaches LCP without an `Authorization` header (and at
+least one OIDC provider is configured), LCP responds:
+
+```
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer realm="lcp"
+Content-Type: application/json
+
+{"error":"Session expired. Please log in again."}
+```
+
+OAuth clients (Power BI, MSAL libraries) use this header to discover that
+bearer auth is acceptable. HTML requests still get the standard 302
+redirect to the login page.
+
+When a request **does** carry an `Authorization: Bearer …` header but the
+token fails verification, LCP responds with:
+
+```
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer error="invalid_token"
+```
+
+## Rejection reasons (logged at `info`)
+
+The verifier returns a generic 401 to the client (avoiding token-validation
+oracle leakage) and logs a single line at `info` level with the rejection
+reason. Common causes:
+
+- malformed JWT (not three base64url segments, header is not a JSON object)
+- algorithm not `RS256`
+- `iss` does not match any configured OIDC provider's discovery `issuer`
+- matched provider has no `audience:` configured (Phase 2 inactive for it)
+- `kid` not present in the JWKS even after a rate-limited refetch
+- signature does not verify with the JWK matching `kid`
+- `aud` mismatch (or array `aud` — multi-aud is v3)
+- `exp` more than 60 s in the past
+- `nbf` more than 60 s in the future
+- `sub` missing or empty
+
+Logs are PII-scrubbed: `iss`, `sub`, `kid`, error class — never the raw token.
+
+## Test support for host-app specs
+
+Phase 2 ships `LcpRuby::Authentication::TestSupport` so host-app specs can
+sign valid (and invalid) JWTs that LCP's bearer pipeline accepts, without
+spinning up a real IdP.
+
+```ruby
+# spec/support/lcp_oidc_bearer.rb
+require "lcp_ruby/authentication/test_support"
+
+RSpec.configure do |config|
+  config.before do
+    @oidc_signer = LcpRuby::Authentication::TestSupport.install_provider!(
+      "entra",
+      issuer:   "https://test-issuer.example/",
+      audience: "api://lcp-test"
+    )
+  end
+
+  config.after { LcpRuby::Authentication::TestSupport.reset! }
+end
+```
+
+```ruby
+# spec/integration/host_deals_oidc_spec.rb
+RSpec.describe "Deals API (OIDC bearer)", type: :request do
+  it "lists deals as the resolved user" do
+    token = @oidc_signer.sign(
+      sub:   "user-1",
+      email: "alice@example.com",
+      name:  "Alice",
+      roles: [ "LCP.Admin" ]
+    )
+
+    get "/api/deals.json", headers: { "Authorization" => "Bearer #{token}" }
+    expect(response).to have_http_status(:ok)
+  end
+
+  it "rejects an expired token" do
+    token = @oidc_signer.sign_expired(sub: "user-1")
+    get "/api/deals.json", headers: { "Authorization" => "Bearer #{token}" }
+    expect(response).to have_http_status(:unauthorized)
+  end
+end
+```
+
+Negative-case helpers on the Signer:
+
+| Method | Produces a token that fails on |
+|---|---|
+| `sign_expired(sub:)` | `exp` invariant |
+| `sign_wrong_audience(sub:)` | `aud` invariant |
+| `sign_unknown_kid(sub:)` | JWKS lookup |
+| `sign_tampered(sub:)` | signature verification |
+
+`install_provider!` can be called multiple times within a single example
+to register independent providers (e.g. `entra` + `google`). The helper
+raises `LcpRuby::Authentication::TestSupport::NotInTestEnv` if invoked
+outside `Rails.env.test?` — defense-in-depth against shipping the helper
+to production.
+
+## See also
+
+- [OIDC Authentication](oidc.md) — Phase 1 web-login configuration reference
+- [API Tokens](api-tokens.md) — complementary LCP-native bearer pipeline (PATs)
+- [`docs/design/oidc_auth.md`](../design/oidc_auth.md) — Phase 2 design spec, decisions, out-of-scope items