panda_pal 5.19.0 → 5.19.2

data/app/models/panda_pal/organization.rb

@@ -160,7 +160,7 @@ module PandaPal
 
       # Trust issuers added to the Org settings
       if (issuer = platform.platform_uri rescue nil).present?
-        trusted_issuers = settings.dig(:lti, :trusted_platforms) || []
+        trusted_issuers = settings&.dig(:lti, :trusted_platforms) || []
         return true if trusted_issuers.include?(issuer)
       end
 

data/app/models/panda_pal/platform/canvas.rb

@@ -427,7 +427,7 @@ module PandaPal
         end
 
         canvas_uri = URI.parse(self.canvas_url)
-        lti_id ||= self.settings.dig(:canvas, :external_tool_id)
+        lti_id ||= self.settings&.dig(:canvas, :external_tool_id)
         canvas_uri.path = "/#{context_path}/external_tools/#{lti_id}"
 
         canvas_params = {}

data/app/models/panda_pal/platform.rb

@@ -192,7 +192,7 @@ module PandaPal
     def self.find_org_setting(paths, org = current_organization)
       paths.each do |p|
         p = p.split('.').map(&:to_sym)
-        val = org.settings.dig(*p)
+        val = org.settings&.dig(*p)
         return val if val.present?
       end
       nil

data/config/initializers/apartment.rb

@@ -58,7 +58,7 @@ module Apartment
     # connection is actually acquired, and only then.
     #
     # For anything that runs app code on a worker thread outside a normal request/job cycle --
-    # ActionCable's `:work` callback below, CableRoom's `Room#around_work` below, or a similar
+    # ActionCable's `:work` callback below, or a similar
     # hook of your own -- this is the one place that logic lives; call it instead of
     # reimplementing the stage/release/restore dance yourself.
     def self.with_lazy_tenant(tenant_name)
@@ -382,17 +382,6 @@ ActiveSupport.on_load(:action_cable) do
   end
 end
 
-# cable_room runs a Room's own code -- message handlers, startup, shutdown, snapshotting -- on a
-# Host worker thread, never inside ActionCable's `:work` callback (its worker pool deliberately
-# isn't an ActionCable::Server::Worker subclass, so it doesn't share that callback chain).
-# `Room#around_work` is its equivalent seam; hook it the same lazy way, on every Room, via
-# CableRoom::Room::Base so every app Room picks it up.
-if defined?(CableRoom)
-  CableRoom::Room::Base.around_work do |room, blk|
-    Apartment::Tenant.with_lazy_tenant(room.tenant, &blk)
-  end
-end
-
 if defined?(Delayed)
   module PandaPal::Plugins
     class ApartmentDelayedJobsPlugin < ::Delayed::Plugin
@@ -437,3 +426,20 @@ if defined?(Delayed)
 
   Delayed::Worker.plugins << PandaPal::Plugins::ApartmentDelayedJobsPlugin
 end
+
+if defined?(Apartment::Sidekiq::Middleware::Client)
+  module PandaPal::Plugins
+    module ApartmentSidekiqClientConnectionRelease
+      def call(*args, &block)
+        pool = ActiveRecord::Base.connection_pool
+        if pool.method(:with_connection).parameters.any? { |_, name| name == :prevent_permanent_checkout }
+          pool.with_connection(prevent_permanent_checkout: true) { super }
+        else
+          pool.with_connection { super }
+        end
+      end
+    end
+  end
+
+  Apartment::Sidekiq::Middleware::Client.prepend(PandaPal::Plugins::ApartmentSidekiqClientConnectionRelease)
+end

data/db/migrate/20171205194657_remove_old_organization_settings.rb

@@ -35,6 +35,7 @@ class RemoveOldOrganizationSettings < PandaPal::MiscHelper::MigrationClass
     end
 
     remove_column :panda_pal_organizations, :old_settings
+    PandaPal::Organization.reset_column_information
   end
 
   def down

data/docs/action-cable.md

@@ -0,0 +1,60 @@
+# ActionCable.
+
+PandaPal patches ActionCable so channels run in the right tenant and can read the PandaPal session.
+
+## Authenticating a connection.
+
+`connection.panda_session` reads the panda token from the cable request (header or `panda_token`
+param), validates it, and switches the connection to the session's tenant. Channels delegate
+`panda_session` to the connection.
+
+```ruby
+# app/channels/application_cable/connection.rb
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_session
+
+    def connect
+      self.current_session = panda_session || reject_unauthorized_connection
+    rescue PandaPal::Session::SessionNonceMismatch # Invalid or expired token
+      reject_unauthorized_connection
+    end
+
+    # Needed for authorize!/authorized? in channels (CanCan only)
+    def current_ability
+      @current_ability ||= Ability.new(panda_session)
+    end
+  end
+end
+```
+
+On the frontend, use `@inst_proserv/toolkit/cable`. It connects to `/cable` with a short-lived,
+signed `T-URL` panda token, and refreshes the token before every reconnect. See
+[frontend.md](frontend.md#actioncable). A full-key token in a `panda_token` param also works, but
+it puts the session secret in server logs.
+
+To set the tenant yourself, assign `self.tenant = org.tenant_name` on the connection.
+
+## Tenant handling.
+
+- **Lazy switching.** Channel work runs in the connection's tenant. PandaPal only stages the tenant
+  and applies it when the work actually checks out a database connection, so messages that never
+  touch the database don't pay for a `SET search_path`.
+- **Scoped broadcasts.** `broadcasting_for` (and so `broadcast_to` and `stream_for`) includes the
+  tenant, so a broadcast in one Organization never reaches another.
+
+## CanCan.
+
+When CanCan is loaded, channels get `authorize!` and `authorized?`, which call
+`connection.current_ability`. A `CanCan::AccessDenied` raised during `subscribed` rejects the
+subscription instead of raising an error.
+
+```ruby
+class ReportChannel < ApplicationCable::Channel
+  def subscribed
+    report = Report.find(params[:id])
+    authorize! :read, report
+    stream_for report
+  end
+end
+```

data/docs/api-calls.md

@@ -0,0 +1,39 @@
+# Generated API calls.
+
+During UAT, clients often need to trigger logic by hand. A deployer can mint a URL in the console
+that runs a piece of code when someone visits it. No console access is needed after that.
+
+```ruby
+org.create_api(<<~RUBY, expiration: 30.days.from_now, uses: 10)
+  arg1 = p[:some_param] # `p` is a Hash of the params sent to the request
+  PandaPal::Organization.current.trigger_canvas_sync()
+  { foo: "bar" } # Returned to the client. Anything JSON serializable works.
+RUBY
+
+# Or call a method on the Organization
+org.create_api(:symbol_of_method_on_organization, expiration: 30.days.from_now, uses: 10)
+```
+
+`create_api` returns a URL like `/panda_pal/call_logic?some_param=TODO&token=JWT.TOKEN.IS.HERE`. You
+can `GET` or `POST` it. PandaPal tries to work out which params the logic reads and adds them as
+`param=TODO`. Pass `host:` to get an absolute URL.
+
+The code runs in the Organization's tenant. The response wraps its return value:
+
+```json
+{
+  "status": "ok",
+  "uses_remaining": 9,
+  "result": {
+    "foo": "bar"
+  }
+}
+```
+
+Errors come back as `{ "status": "error", "message": "..." }` with a 500 status, or a 403 when the
+token is invalid.
+
+## Revoking.
+
+Delete the `PandaPal::ApiCall` record to revoke the URL. The logic and `uses:` live in the database,
+so you can change them. `expiration:` is part of the token, so it can't change.

data/docs/architecture.md

@@ -0,0 +1,210 @@
+# Architecture.
+
+PandaPal is a mountable Rails engine. Your app mounts it, declares placements and launch routes, and
+gets back validated launches, a session that works inside an `<iframe>`, and a database schema per
+customer. This page explains how those pieces fit together. For how to use each one, follow the
+links.
+
+## The big pieces.
+
+```mermaid
+flowchart TB
+  subgraph Canvas
+    LMS[Canvas LMS]
+  end
+
+  subgraph App["Your Rails app"]
+    direction TB
+    Elevator["Apartment elevator<br/>(picks the tenant)"]
+    subgraph Engine["PandaPal engine (mounted at /lti)"]
+      V13[LtiV1P3Controller<br/>OIDC login, launch, JWKS]
+      V10[LtiV1P0Controller<br/>LTI 1.0 launch, XML config]
+      ApiCall[ApiCallController]
+    end
+    Helpers["ControllerHelper and SessionReplacement<br/>(mixed into every controller)"]
+    AppCtl[Your controllers]
+    Cable[ActionCable patches]
+    Install["Organization#install_lti<br/>(console or rake)"]
+  end
+
+  subgraph DB[Postgres]
+    Public[("public schema<br/>Organization, LtiRegistration,<br/>login sessions")]
+    Tenants[("one schema per Organization<br/>Session, your models")]
+  end
+
+  LMS -- launches --> Elevator --> Engine
+  Elevator --> AppCtl
+  Engine -- redirect with panda token --> AppCtl
+  AppCtl --- Helpers
+  Engine --> Public
+  AppCtl --> Tenants
+  Cable --> Tenants
+  Install -- "Canvas API (Bearcat)" --> LMS
+```
+
+| Piece | Lives in | Job |
+| --- | --- | --- |
+| Engine controllers | `app/controllers/panda_pal/` | Tool config, OIDC login, launch validation, Deep Linking, JWKS, and API calls. |
+| Controller helpers | `lib/panda_pal/helpers/controller_helper.rb`, `session_replacement.rb` | `validate_launch!`, `current_session`, `switch_tenant`, `redirect_with_session_to`, and friends. Included in every controller at boot. |
+| Route helper | `lib/panda_pal/helpers/route_helper.rb` | `lti_nav`: declares a placement and its launch route together. |
+| Models | `app/models/panda_pal/` | `Organization`, `Session`, `LtiRegistration`, `ApiCall`, and `Platform`. |
+| Platform | `app/models/panda_pal/platform.rb`, `platform/canvas.rb` | Issuer URLs, JWKS fetching, service tokens, and the Canvas install API. |
+| Tenancy | `config/initializers/apartment.rb` | Apartment config, the elevator, sharding, tenant-scoped cache, ActionCable, and Delayed Job hooks. |
+| Global config | `lib/panda_pal.rb` | `PandaPal.lti_options`, placements, tools, scopes, and the signing key. |
+
+## Two kinds of data.
+
+PandaPal splits data across Postgres schemas with ros-apartment:
+
+- **`public`** holds what PandaPal needs before it knows the customer: `PandaPal::Organization`,
+  `PandaPal::LtiRegistration`, and short-lived login sessions created during the LTI 1.3 OIDC step.
+- **Each Organization's schema** (named after `Organization#name`) holds its `PandaPal::Session`
+  rows and all of your app's tenant models.
+
+With [sharding](multi-tenancy.md#sharding), an Organization's schema can live on another database.
+Its tenant name becomes `shard:name`, and the `Organization` row stays in `public` on the default
+database.
+
+## LTI 1.3 launch flow.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant B as Browser (Canvas iframe)
+  participant C as Canvas
+  participant P as PandaPal engine
+  participant DB as Postgres
+  participant A as Your controller
+
+  B->>P: POST /lti/v1p3/oidc_login (iss, login_hint, client_id)
+  Note over P: Forward to beta/test domain if needed
+  P->>DB: Create login Session in public (org 0, nonce)
+  P-->>B: Auto-submit form to Canvas auth URL (state = login session's panda token)
+  B->>C: OIDC authorization request
+  C-->>B: Auto-submit form with id_token and state
+  B->>P: POST /lti/v1p3/resource_link_request
+  P->>DB: Look up LtiRegistration, then Organization by client and deployment ID
+  Note over P: Check trusted issuer, JWT signature (JWKS), state, nonce, aud, exp, and replay
+  P->>DB: Move the session into the Organization's schema and set its tool
+  Note over P: Store launch params, placement, and LTI version on the session
+  P-->>B: Redirect to the lti_nav route with a single-use panda token
+  B->>A: GET /organizations/:id/... ?panda_token=...
+  A-->>B: Render the app with the full session key
+```
+
+What happens at each stage:
+
+1. **Login (steps 1 to 3).** PandaPal resolves the platform from the issuer and starts a session in
+   `public`, because it doesn't know the Organization yet. The session's panda token becomes the
+   OIDC `state`, and a random nonce goes into the session.
+2. **Launch (steps 7 to 9).** `validate_launch!` decodes the `id_token`. It finds the Organization
+   through `PandaPal::LtiRegistration` (client ID plus optional deployment ID), then falls back to
+   `Organization#key`. It verifies the token against the platform's cached JWKS, refetching once if
+   the key ID is new, and checks `state`, `nonce`, audience, expiration, and nonce replay. Then it
+   copies the login session into the Organization's schema and deletes the original.
+3. **Hand-off (steps 10 to 12).** `resource_link_request` stores the launch on the session and
+   redirects to the route `lti_nav` declared for that placement and tool. The redirect carries a
+   single-use `T-NONCE` panda token instead of the session secret. (In development, it carries the
+   full session key, so page reloads keep working.)
+
+Deep Linking launches follow the same path through `deep_link_request`, and redirect to the
+placement's `deep_link_redirect_url` instead.
+
+## LTI 1.0/1.1 launch flow.
+
+LTI 1.0 has no login step. Canvas posts the launch to `/lti/v1p0/launch` (auto launch) or straight
+to your route (`auto_launch: false`). `validate_launch!` checks the OAuth 1.0a signature and
+timestamp against the Organization found by `oauth_consumer_key`. It reads the tool from the signed
+`custom_panda_pal_tool` field, switches to the Organization's tenant, and starts the session there.
+From then on, it's the same as LTI 1.3.
+
+## Every request after the launch.
+
+```mermaid
+flowchart TD
+  R["Request from the iframe<br/>(X-Panda-Token header, or panda_token param)"] --> E{Apartment elevator}
+  E -- "/organizations/:id or /o/:name in path" --> T[Switch to that tenant]
+  E -- "panda token present" --> TT["Switch to the tenant in the token header (o)"]
+  E -- neither --> PUB[Stay in public]
+  T --> F
+  TT --> F
+  PUB --> F
+  F["forbid_access_if_lacking_session"] --> S["current_session<br/>Session.for_panda_token"]
+  S --> V{"Token valid?<br/>signature, type, expiry, tenant"}
+  V -- no --> X[401]
+  V -- yes --> O{"Session belongs to<br/>current Organization and tenant?"}
+  O -- no --> X
+  O -- yes --> AC[Your action runs]
+  AC --> AS[after_action saves the session if it changed]
+```
+
+The elevator only picks a schema. It decodes the token's header without checking the signature.
+Authentication happens later, when `current_session` verifies the token and `valid_session?`
+checks that the session, Organization, and tenant all agree. That's why every non-launch action
+needs `forbid_access_if_lacking_session`.
+
+## Sessions and panda tokens.
+
+Browsers block third-party cookies in `<iframe>`s, so PandaPal doesn't depend on the Rails session
+cookie. Each `PandaPal::Session` row has a random `session_secret`, and the client proves it holds a
+session with a panda token:
+
+- A **full-key token** (`typ: KEY`) contains the secret. The page gets it once, usually in the
+  `js-env` meta tag, and sends it in a header.
+- A **limited-use token** (`T-NONCE`, `T-IP`, `T-EXP`, or `T-URI`) contains only an HMAC of its
+  header, signed with the secret. These go in URLs, where they might be logged.
+
+Every token's header carries the Organization ID (`o`) and session ID (`s`). That's how the
+elevator can pick a tenant before any database lookup, and how `T-URI` tokens minted in the browser
+by `@inst_proserv/toolkit` can be verified on the server. See [sessions.md](sessions.md) for the
+formats.
+
+## Finding the tool.
+
+One app can serve several tools (see [multiple-tools.md](multiple-tools.md)). PandaPal works out
+which tool was launched once, at launch time, and stores it in `panda_pal_sessions.tool`:
+
+- **LTI 1.3:** from the `PandaPal::LtiRegistration` that matches the launch's client ID and
+  deployment ID. If there's no registration, it's the default tool.
+- **LTI 1.0:** from the signed `custom_panda_pal_tool` launch param.
+
+After that, placements, custom params, launch routes, and Deep Linking redirects are all looked up
+through the session's tool.
+
+## Outside the request cycle.
+
+| Context | How it gets a tenant |
+| --- | --- |
+| Sidekiq jobs | `ros-apartment-sidekiq` records the tenant on enqueue and switches on perform. |
+| Delayed Job | PandaPal's plugin does the same, using a `tenant` column. |
+| Scheduled tasks | `ScheduledTaskExecutor` switches to each Organization before running its task. |
+| ActionCable | `connection.panda_session` switches the connection to the token's tenant. Worker threads apply it lazily, on first database checkout. |
+| Rake tasks and the console | Start in `public`. Use `org.switch_tenant`. The console auto-switches in development. |
+
+`Rails.cache` keys are prefixed with the current tenant everywhere, so a cached value never crosses
+Organizations.
+
+## Shared state that needs a shared cache.
+
+Several things live in `Rails.cache`:
+
+- Platform JWKS (24 hours)
+- LTI 1.3 launch nonces, for replay protection
+- AGS service access tokens
+- Canvas account admin lookups (one hour)
+
+In production, use a cache store that every app process shares, such as Redis or Memcached. With a
+per-process store, a replayed `id_token` could slip past the nonce check on another process.
+
+## Extension points.
+
+| Hook | Use it to | Docs |
+| --- | --- | --- |
+| `OrganizationExtension` | Add methods, callbacks, and scheduled tasks to `PandaPal::Organization`. | [organizations.md](organizations.md#extending-the-model) |
+| `PandaPal.register_extension` | Do the same from a gem. | [organizations.md](organizations.md#settings-validation) |
+| `define_setting`, `settings_structure` | Declare and validate Organization settings. | [organizations.md](organizations.md#settings-validation) |
+| `before_lti_install`, `after_lti_install`, `around_lti_install` | Run code around Canvas installs. | [installation.md](installation.md#install-callbacks) |
+| `panda_pal_interactive_install` callbacks | Run code around the interactive install. | [installation.md](installation.md#install-callbacks) |
+| `PandaPal::Organization.extend_platform_api` | Add methods to the platform API. | [organizations.md](organizations.md#canvas-helpers) |
+| `PandaPal::SecureHeaders.apply_defaults` | Start from PandaPal's headers and customize. | [security.md](security.md#secure-headers) |
+| `PandaPal.jwk=` | Sign with a different key. | [configuration.md](configuration.md#lti-13-private-key) |

data/docs/before-you-build.md

@@ -0,0 +1,83 @@
+# Before you build it.
+
+PandaPal apps often reimplement things PandaPal already does. Check this list before you write a
+helper of your own.
+
+## Launches and links.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Link from an email or notification into the tool in Canvas | `org.canvas_lti_launch_url(placement_or_context, params:)` | [organizations.md](organizations.md#canvas-helpers) |
+| Redirect without losing the session | `redirect_with_session_to :some_url` | [sessions.md](sessions.md#links-and-redirects) |
+| Build a link that keeps the session | `url_with_session(:some_path)` or `link_nonce` | [sessions.md](sessions.md#links-and-redirects) |
+| Make a signed `GET` link (download, image, new tab) on the server | `link_nonce(url, type: :url)` | [sessions.md](sessions.md#links-and-redirects) |
+| Make a signed `GET` link in the browser | `signURL(url)` or `api.download_file(url)` | [frontend.md](frontend.md#minting-panda-tokens-in-the-browser) |
+| Route the user to Canvas beta or test domains | `PandaPal.lti_environments` (forwarding is automatic) | [routing-and-launches.md](routing-and-launches.md#canvas-beta-and-test) |
+| Send launches from one placement to a different screen | `lti_nav placement: 'controller#action'` | [routing-and-launches.md](routing-and-launches.md#launch-routes-with-lti_nav) |
+| Ship a second tool (another label, placement, or audience) | `PandaPal.define_tool` | [multiple-tools.md](multiple-tools.md) |
+
+## Users and roles.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Find the launching user's record | `current_session.user` | [sessions.md](sessions.md#reading-launch-data) |
+| Read a custom param, ignoring unsubstituted `$Canvas...` values | `current_session.get_lti_cust_param(:name)` | [configuration.md](configuration.md#custom-params) |
+| Check whether the user is a Canvas Site Admin | `current_session.canvas_site_admin?` | [roles-and-abilities.md](roles-and-abilities.md#roles-from-the-launch) |
+| Parse LTI role URNs (`Instructor`, `Learner`, and so on) | `current_session.lti_roles` | [roles-and-abilities.md](roles-and-abilities.md#roles-from-the-launch) |
+| Check account admin roles, including on parent accounts | `canvas_account_role_labels(account, inherited: true)` | [roles-and-abilities.md](roles-and-abilities.md#canvas-role-labels) |
+| Memoize a permission check for the session | `cache_on_session :method_name` | [roles-and-abilities.md](roles-and-abilities.md#ability-helpers) |
+
+## Data and tenants.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Store per-user state across requests | `current_session[:key]` | [sessions.md](sessions.md#using-the-session) |
+| Cache a value for the rest of the session | `current_session.cache(:key) { ... }` | [sessions.md](sessions.md#reading-launch-data) |
+| Keep `Rails.cache` from leaking across customers | Nothing. Keys are tenant-scoped automatically. | [multi-tenancy.md](multi-tenancy.md#rails-cache) |
+| Run a background job in the right tenant | Nothing, with `ros-apartment-sidekiq`. Delayed Job needs a `tenant` column. | [multi-tenancy.md](multi-tenancy.md#background-jobs) |
+| Run code for every Organization in a rake task | `org.switch_tenant { ... }` | [multi-tenancy.md](multi-tenancy.md#rake-tasks) |
+| Run code in a tenant on your own worker thread | `Apartment::Tenant.with_lazy_tenant(org.tenant_name) { ... }` | [multi-tenancy.md](multi-tenancy.md) |
+| Clean up old sessions | Nothing, with `sidekiq-scheduler`. Otherwise `rake panda_pal:clean_sessions`. | [sessions.md](sessions.md#session-cleanup) |
+| Test across database shards | `with_multiple_shards(...)` | [multi-tenancy.md](multi-tenancy.md#testing-with-shards) |
+
+## Organizations and Canvas.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Call the Canvas API for an Organization | `org.bearcat_client` | [organizations.md](organizations.md#canvas-helpers) |
+| Read the Organization's Canvas URL or token | `org.canvas_url`, `org.canvas_api_token` | [organizations.md](organizations.md#canvas-helpers) |
+| Validate Organization settings | `settings_structure` or `define_setting` | [organizations.md](organizations.md#settings-validation) |
+| Add methods or callbacks to Organizations | `OrganizationExtension` | [organizations.md](organizations.md#extending-the-model) |
+| Create an Organization with a guided editor | `rake panda_pal:org:new` | [installation.md](installation.md#rake-tasks) |
+| Install or update the tool in Canvas | `org.install_lti` or `rake panda_pal:org:install` | [installation.md](installation.md) |
+| Run setup after an install | `after_lti_install` | [installation.md](installation.md#install-callbacks) |
+| Run a cron job per Organization | `scheduled_task` | [task-scheduling.md](task-scheduling.md) |
+| Let a client trigger logic during UAT | `org.create_api(...)` | [api-calls.md](api-calls.md) |
+
+## Grades and content.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Post a grade from an LTI 1.3 launch | `ags_client.post_score(...)` | [ags.md](ags.md) |
+| Post a grade from an LTI 1.1 launch | `PandaPal::Jobs::GradePassbackJob` | [grade-passback.md](grade-passback.md) |
+| Let teachers pick content to embed in Canvas | `PandaPal::DeepLinkingHelpers` | [deep-linking.md](deep-linking.md) |
+| Sign a JWT with the tool's key | `PandaPal.jwk` | [configuration.md](configuration.md#lti-13-private-key) |
+
+## Realtime and frontend.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Authenticate an ActionCable connection | `connection.panda_session` | [action-cable.md](action-cable.md#authenticating-a-connection) |
+| Check permissions in a channel | `authorize!` in `subscribed` | [action-cable.md](action-cable.md#cancan) |
+| Keep cable broadcasts inside one Organization | Nothing. Broadcasts are tenant-scoped automatically. | [action-cable.md](action-cable.md#tenant-handling) |
+| Open a cable connection from the browser | `subscribe_channel` or `useModelSubscription` | [frontend.md](frontend.md#actioncable) |
+| Call your API with the session and CSRF token | `APIBase` | [frontend.md](frontend.md#api-calls) |
+| Use client-side routing without changing the iframe URL | `createLtiHistory` or `<LtiRouter>` | [frontend.md](frontend.md#routing-inside-the-iframe) |
+
+## Security.
+
+| If you need to... | Use | Docs |
+| --- | --- | --- |
+| Block requests that don't come from a launch | `prepend_before_action :forbid_access_if_lacking_session` | [security.md](security.md#require-a-session) |
+| Allow Canvas to frame the tool | Nothing. The default secure headers allow it. | [security.md](security.md#secure-headers) |
+| Accept launches only from trusted platforms | Nothing. It's checked on every LTI 1.3 launch. | [configuration.md](configuration.md#trusted-platforms) |

data/docs/configuration.md

@@ -0,0 +1,120 @@
+# Configuration.
+
+All tool-level configuration lives in an initializer, usually `config/initializers/lti.rb` or `config/initializers/panda_pal.rb`.
+
+```ruby
+# config/initializers/lti.rb
+PandaPal.lti_options = {
+  title: 'Teacher Reports',
+  description: 'Reports for teachers',
+}
+PandaPal.lti_properties = { oauth_compliant: 'true' }
+
+# Environments reflect those used by Canvas
+PandaPal.lti_environments = {
+  domain: ENV['PROD_DOMAIN'],
+  beta_domain: ENV['BETA_DOMAIN'],
+  test_domain: ENV['TEST_DOMAIN'],
+}
+
+PandaPal.lti_custom_params = { custom_canvas_role: '$Canvas.membership.roles' }
+
+# LTI 1.3 scopes to request on the Developer Key (see ags.md)
+PandaPal.lti_scopes = [PandaPal::LtiConstants::AgsScopes::SCORE]
+
+PandaPal.stage_placement(:account_navigation, {
+  enabled: true,
+  text: 'Teacher Reports',
+  visibility: 'admins',
+})
+```
+
+## `lti_options`.
+
+| Key | Purpose |
+| --- | --- |
+| `title`, `description` | Tool name and description in the tool config and the Canvas install. |
+| `lti_spec_version` | Default LTI version for `install_lti` (`'v1p3'` if unset). |
+| `platform` | `'canvas.instructure.com'` (default) or `'bridgeapp.com'`. See [Bridge vs. Canvas](#bridge-vs-canvas). |
+| `settings_structure` | Validation schema for `Organization#settings`. See [organizations.md](organizations.md#settings-validation). |
+| `launch_url`, `secure_launch_url`, `launch_path`, `secure_launch_path` | LTI 1.0 launch URL. See [Launch URL property](#launch-url-property). |
+
+## Placements.
+
+`PandaPal.stage_placement(placement, options)` registers a Canvas placement (`:account_navigation`,
+`:course_navigation`, `:user_navigation`, `:editor_button`, and so on). The options become that
+placement's settings in the tool config. Pass `tool:` to attach the placement to a
+[non-default tool](multiple-tools.md), and `deep_linking: true` to make it a
+[Deep Linking](deep-linking.md) placement.
+
+`PandaPal.stage_navigation` is a deprecated alias of `stage_placement`.
+
+Most apps don't call `stage_placement` for launch routes directly. `lti_nav` in `routes.rb` does it
+for you. See [routing-and-launches.md](routing-and-launches.md).
+
+## Environments.
+
+`lti_environments` maps Canvas environments to your app's domains. PandaPal uses it to:
+
+- Forward an LTI 1.3 OIDC login that carries `canvas_environment=beta` (or `test`) to the matching
+  domain.
+- Add every placement's `target_link_uri`, rewritten for each environment domain, to the Developer
+  Key's redirect URIs on install.
+
+## Custom params.
+
+`lti_custom_params` is the set of custom fields sent in every launch. Read them back with
+`current_session.get_lti_cust_param(:canvas_role)`. By default, that returns `nil` when Canvas didn't
+substitute the variable (the raw `$Canvas...` string came back). Pass `default: true` to fall back to
+the configured value, or `default: false` to return `nil` whenever the value equals the configured
+one.
+
+## Launch URL property.
+
+From the LTI spec: "The launch_url contains the URL to which the LTI Launch is to be sent. The
+secure_launch_url is the URL to use if secure http is required. One of either the launch_url or the
+secure_launch_url must be specified."
+
+Bridge validates that this URL exists. Set one of these in `PandaPal.lti_options`:
+
+1. `secure_launch_url: 'https://domain.com/path'` for a full, static, secure URL.
+2. `secure_launch_path: '/path'` for a secure URL on the current host.
+3. `launch_url: 'http://domain.com/path'` for a full, static URL.
+4. `launch_path: '/path'` for a URL on the current host.
+5. Nothing, to get the current host with the root path (`http://appdomain.com/`).
+6. `launch_url: false` to leave the property out.
+
+## Bridge vs. Canvas.
+
+The LTI 1.0 XML config differs slightly by platform. `PandaPal.lti_options[:platform]` controls it:
+`'canvas.instructure.com'` (default) or `'bridgeapp.com'`.
+
+## LTI 1.3 private key.
+
+LTI 1.3 signs tokens (the JWKS endpoint, Deep Linking responses, and AGS service tokens) with an RSA
+private key. PandaPal looks for it in this order:
+
+1. `PandaPal.lti_private_key = OpenSSL::PKey::RSA.new(key)`
+2. The `LTI_PRIVATE_KEY` environment variable (PEM content)
+3. The `LTI_PRIVATE_KEY_PATH` environment variable (absolute, or relative to `Rails.root`)
+4. In development only, a bundled dev key
+
+Set `LTI_PRIVATE_KEY_PASSWORD` if the key is encrypted. To generate one:
+
+```bash
+# Generate a new encrypted private key
+openssl genrsa -aes256 -out encrypted_private_key.pem 2048
+
+# Or encrypt an existing private key
+openssl rsa -aes256 -in existing_private_key.pem -out encrypted_private_key.pem
+```
+
+The public half is served at `<mount>/v1p3/public_jwks`. To sign with a different JWK, set
+`PandaPal.jwk = JWT::JWK.new(...)`.
+
+## Trusted platforms.
+
+LTI 1.3 launches are only accepted from trusted issuers. Instructure-hosted Canvas (production, beta,
+test, and loadtest) is trusted by default, and any Canvas issuer is trusted when Rails runs in
+development or test. To
+trust another issuer for one Organization, add it to `settings[:lti][:trusted_platforms]`.