panda_pal 5.19.1 → 5.20.0

data/docs/multi-tenancy.md

@@ -0,0 +1,117 @@
+# Multi-tenancy.
+
+PandaPal uses [ros-apartment](https://github.com/rails-on-services/apartment) to give each
+Organization its own Postgres schema. `PandaPal::Organization` and `PandaPal::LtiRegistration` live
+in the shared `public` schema. Everything else, including `PandaPal::Session`, lives in the
+Organization's schema.
+
+## How a request picks its tenant.
+
+PandaPal installs an Apartment elevator that checks, in order:
+
+1. A path like `/orgs/123` or `/organizations/123` (Organization ID)
+2. A path like `/o/acme`, `/orgs/acme`, or `/organizations/acme` (Organization name)
+3. A panda token in the request (see [sessions.md](sessions.md#passing-the-token-to-the-frontend))
+4. ActiveStorage blob URLs with an `organization_id` param
+
+If none match, the request runs in `public`. The elevator only picks a schema. Authentication still
+happens in `forbid_access_if_lacking_session` (see [security.md](security.md)).
+
+To replace it, delete the middleware and add your own:
+
+```ruby
+Rails.application.config.middleware.delete Apartment::Elevators::Generic
+Rails.application.config.middleware.use Apartment::Elevators::Generic, lambda { |request|
+  if match = request.path.match(/\/(?:orgs|organizations)\/(\d+)/)
+    PandaPal::Organization.find_by(id: match[1])&.tenant_name # tenant_name, not name, so shards work
+  end
+}
+```
+
+## Switching tenants in code.
+
+```ruby
+org.switch_tenant { ... }     # Run a block in the Organization's tenant
+org.switch_tenant             # Switch for the rest of the thread
+switch_tenant(org) { ... }    # Global helper. Takes an Organization or a name.
+switch_tenant("acme") { ... }
+```
+
+In controllers, `around_action :switch_tenant` switches to `current_organization`. It must run as an
+`around_action` (or with a block).
+
+Use `org.tenant_name` rather than `org.name` whenever you hand a tenant to Apartment yourself. With
+sharding, they differ.
+
+### Rails cache.
+
+`Rails.cache` keys are prefixed with the current tenant automatically, so cached values never leak
+between Organizations.
+
+### Console.
+
+The Rails console prompt shows the app, environment, and current tenant. On startup, the console
+switches to the `local` Organization (or the first one) in development, or to the only Organization
+when there's just one.
+
+## Background jobs.
+
+Jobs need to run in the tenant that enqueued them.
+
+- **Sidekiq**: add `ros-apartment-sidekiq` to your Gemfile. PandaPal raises an error at boot if
+  Sidekiq is present without it.
+- **Delayed Job**: PandaPal registers a Delayed Job plugin that records the tenant on enqueue and
+  switches to it on perform. Your `delayed_jobs` table needs a `tenant` column.
+
+## Rake tasks.
+
+Rake tasks start in `public`. Loop over Organizations and switch into each one:
+
+```ruby
+# lib/tasks/lti_tasks.rake
+namespace :lti_tasks do
+  task some_rake_task: :environment do
+    PandaPal::Organization.find_each do |org|
+      org.switch_tenant do
+        SomeJob.perform_later
+      end
+    end
+  end
+end
+```
+
+## Sharding.
+
+PandaPal can put tenants on more than one database. Add a `shard` string column to
+`panda_pal_organizations` to turn it on.
+
+On boot, PandaPal finds shards from environment variables named `SHARD_DB_<ID>_URL` or
+`HEROKU_POSTGRESQL_<ID>_URL`, where `<ID>` is the shard name. Each shard's config is merged over the
+default database config.
+
+- Pick a shard with `PandaPal::Organization.new(shard: "shard_a")`. A blank `shard` (or
+  `"default"`) means the default database. PandaPal doesn't pick a shard for you.
+- `panda_pal:org:new` lists the configured shards in its editor template.
+- Creating an Organization on a shard that isn't configured raises an error.
+- `shard` can't change after creation.
+- The Organization record itself always stays in the `public` schema of the default database.
+- `org.tenant_name` is `shard:name` (for example, `shard_a:acme`) for sharded Organizations.
+
+Sharding doesn't support Rails database roles. To use native Rails sharding for a model instead, add
+it to Apartment's `excluded_models`.
+
+### Testing with shards.
+
+```ruby
+# spec/spec_helper.rb
+require "panda_pal/spec_helper"
+RSpec.configure { |config| config.include PandaPal::SpecHelper }
+
+# spec/models/thing_spec.rb
+with_multiple_shards(
+  shards: { alt: "myapp_test2" },              # shard name => database name
+  tenant_names: %w[on_primary alt:on_alt],     # Schemas to drop before the run
+  transactional: false,
+  determine_shard: ->(org) { org.name.include?("alt") ? "alt" : nil },
+)
+```

data/docs/multiple-tools.md

@@ -0,0 +1,73 @@
+# Multiple tools.
+
+One app can publish more than one LTI tool. For example, a teacher-facing tool and a separate,
+student-facing editor button with its own label and visibility. In Canvas, each tool is its own
+Developer Key (LTI 1.3) or its own External Tool (LTI 1.0), with its own placements.
+
+Everything configured without a `tool:` belongs to the default tool (`PandaPal::DEFAULT_TOOL`), so
+single-tool apps don't change.
+
+```ruby
+# config/initializers/lti.rb
+PandaPal.define_tool(:translate,
+  title: 'Teacher Reports - Translate', # Merged over lti_options for this tool's config
+  custom_params: { mode: 'translate' }, # Merged over lti_custom_params for this tool's config
+)
+
+PandaPal.stage_placement(:editor_button, tool: :translate, text: 'Translate', visibility: 'public')
+```
+
+```ruby
+# config/routes.rb
+lti_nav editor_button: 'translate#editor_button', tool: :translate # Served at <mount>/translate/editor_button
+```
+
+## Config.
+
+Each tool has its own config URLs: `/v1p3/config?tool=translate` and `/v1p0/config?tool=translate`.
+The default tool's URLs don't change.
+
+## Install.
+
+`org.install_lti(host: ..., tool: :translate)`. On LTI 1.3, this creates (or reuses) the tool's own
+Developer Key and records it as a `PandaPal::LtiRegistration` on the Organization. The
+Organization's `key` keeps pointing at the default tool. On LTI 1.0, both tools share the
+Organization's consumer key and secret.
+
+To install a second tool along with the default one, use an install callback (see
+[installation.md](installation.md#install-callbacks)):
+
+```ruby
+# app/models/organization_extension.rb
+included do
+  after_lti_install :install_translate_tool
+end
+
+def install_translate_tool
+  install = current_lti_install
+  return unless install.tool == PandaPal::DEFAULT_TOOL # the nested :translate install runs these callbacks too
+  install_lti(**install.to_h.except(:installation), tool: :translate)
+end
+```
+
+## Launches.
+
+`current_session.lti_tool` says which tool was launched. It's stored in the `tool` column of
+`panda_pal_sessions`.
+
+- On LTI 1.3, the tool comes from the registration matching the launch's client ID (and deployment
+  ID).
+- On LTI 1.0, it comes from the signed `custom_panda_pal_tool` field that every non-default tool
+  config includes.
+
+PandaPal routes each launch, and each Deep Linking redirect, using that tool's placements.
+
+## Registering by hand.
+
+If a tool's Developer Key was set up outside `install_lti`, register it yourself:
+
+```ruby
+org.lti_registrations.create!(tool: 'translate', client_id: '10000000000123', deployment_id: nil)
+```
+
+A registration with a `deployment_id` takes priority over one without.

data/docs/organizations.md

@@ -0,0 +1,159 @@
+# Organizations.
+
+A `PandaPal::Organization` is one installation of your tool, usually one Canvas customer. Each
+Organization gets its own Postgres schema (see [multi-tenancy.md](multi-tenancy.md)).
+
+## Attributes.
+
+| Attribute | Purpose |
+| --- | --- |
+| `id` | Primary key. |
+| `name` | Unique name, also the tenant's schema name. Letters, numbers, and `_` only. It can't change after creation (use `rename!` if you must). |
+| `key` | LTI 1.0: the consumer key. LTI 1.3: `CLIENT_ID` or `CLIENT_ID/DEPLOYMENT_ID` of the default tool. |
+| `secret` | LTI 1.0: the shared secret. LTI 1.3: the Developer Key `api_key`. |
+| `canvas_account_id` | The Canvas account the tool belongs to. `install_lti` installs here by default. |
+| `settings` | Encrypted hash of settings. See [Settings validation](#settings-validation). |
+| `salesforce_id` | Unique ID of this Organization in Salesforce. |
+| `shard` | Optional. The database shard, if you use [sharding](multi-tenancy.md#sharding). |
+| `lti_registrations` | Extra LTI 1.3 Developer Keys or deployments (see [multiple-tools.md](multiple-tools.md)). |
+
+Create Organizations with the `panda_pal:org:new` rake task (see
+[installation.md](installation.md#rake-tasks)), or in the console.
+
+## `current_organization`.
+
+| Where | How it's found |
+| --- | --- |
+| Controllers | The session's Organization, then (deprecated) `oauth_consumer_key` or `organization_id` params, then the current tenant. |
+| Anywhere else | `current_organization` (a global helper) or `PandaPal::Organization.current` reads the current tenant. |
+
+`PandaPal::Organization.for_apt_tenant(tenant)` finds the Organization for a tenant name, including
+shard-qualified names like `shard_a:acme`.
+
+## Extending the model.
+
+Put app-specific Organization code in an `OrganizationExtension` concern. PandaPal includes it in
+`PandaPal::Organization` automatically.
+
+```ruby
+# app/models/organization_extension.rb
+module OrganizationExtension
+  extend ActiveSupport::Concern
+
+  included do
+    after_lti_install :configure_canvas
+  end
+
+  def sync_now
+    # ...
+  end
+end
+```
+
+## Canvas helpers.
+
+When the platform is Canvas, Organizations also get:
+
+| Method | Purpose |
+| --- | --- |
+| `install_lti`, `reinstall_lti!`, `lti_installations` | See [installation.md](installation.md). |
+| `canvas_url` | `settings[:canvas][:base_url]` (or a few common variants). |
+| `canvas_api_token` | `settings[:canvas][:api_token]` (or a few common variants). |
+| `bearcat_client` | A Bearcat client for the Canvas API. Uses `canvas_sync_client` when CanvasSync defines it. |
+| `root_account_info` | The Canvas root account, cached for 24 hours. |
+| `canvas_lti_launch_url(placement_or_context, ...)` | A Canvas URL that launches this tool. See below. |
+| `trusted_platform?(platform)` | Whether an LTI 1.3 issuer may launch into this Organization. |
+
+`canvas_lti_launch_url` builds a link into Canvas that launches the tool:
+
+```ruby
+org.canvas_lti_launch_url(:account_navigation)  # Into the Organization's account
+org.canvas_lti_launch_url(course)               # course_navigation in a course (anything with canvas_id)
+org.canvas_lti_launch_url("courses/12")         # A context path
+org.canvas_lti_launch_url(:global, params: { report_id: 1 }, host: request) # Launch with extra params
+```
+
+It needs `settings[:canvas][:external_tool_id]`, or pass `lti_id:`.
+
+To add your own methods to the platform API, use
+`PandaPal::Organization.extend_platform_api { def my_helper; end }`.
+
+## Settings validation.
+
+Describe the shape of `settings`, and PandaPal validates it on every save. The
+`panda_pal:org:new` editor is prefilled from it too.
+
+```ruby
+PandaPal.lti_options = {
+  title: 'LBS Gradebook',
+  settings_structure: {
+    allow_additional: true, # Allow keys that aren't in :properties
+    # Or validate each extra key against a spec:
+    # allow_additional: { type: 'String' },
+    validate: ->(value, spec, **kwargs) {
+      # kwargs[:errors] is an Array to push errors to; kwargs[:path] is the current path.
+      kwargs[:errors] << "Your error message at <path>" unless value.present?
+      # Or return a String (or Array of Strings). <path> is replaced with the real path.
+      nil
+    },
+    properties: {
+      canvas: {
+        type: 'Hash',
+        required: true,
+        properties: {
+          api_token: { type: 'String', required: true },
+          base_url: { type: 'String', required: true },
+        },
+      },
+      catalog: { # :validate, :allow_additional, and :properties work at every level
+        type: 'Hash',
+        required: false,
+        allow_additional: false,
+        properties: {},
+      },
+    },
+  },
+}
+```
+
+You can also add settings from code, which is handy in gems and extensions:
+
+```ruby
+PandaPal::Organization.define_setting("report_timezone", { type: 'String', required: false })
+```
+
+A dotted path (`"parent.child"`) adds a setting inside an existing `Hash` setting. PandaPal itself
+defines `lti` and `lti.trusted_platforms` this way. `PandaPal.register_extension('Organization',
+'::MyGem::OrgExtension')` includes more modules, the same way `OrganizationExtension` is included.
+
+### Legacy settings structure.
+
+The older YAML-style format still works. `is_required` maps to `required`, and `data_type` maps to
+`type`:
+
+```ruby
+PandaPal.lti_options = {
+  title: 'LBS Gradebook',
+  settings_structure: YAML.load("
+    canvas:
+      is_required: true
+      data_type: Hash
+      api_token:
+        is_required: true
+        data_type: String
+    reports:
+      submissions_report_time_length:
+        is_required: true
+        data_type: ActiveSupport::Duration
+  ").deep_symbolize_keys
+}
+```
+
+`data_type` is compared with the value's class name. For example, `30.minutes.class.to_s` is
+`"ActiveSupport::Duration"`.
+
+## Encryption.
+
+`settings` is encrypted with the first 32 characters of the app's `secret_key_base` (from
+`Rails.application.secret_key_base`, credentials, `secrets.yml` before Rails 7.2, or the
+`SECRET_KEY_BASE` environment variable). If that value changes, existing settings can't be read.

data/docs/roles-and-abilities.md

@@ -0,0 +1,82 @@
+# Roles and abilities.
+
+## Roles from the launch.
+
+```ruby
+roles = current_session.lti_roles # PandaPal::Session::RoleStore
+roles.system_roles       # e.g. ["sys_admin"]
+roles.institution_roles  # e.g. ["administrator"]
+roles.context_roles      # e.g. ["instructor", "teaching_assistant"]
+roles.context_types      # e.g. ["course_offering"]
+roles.other_roles        # Anything that didn't match a known role URN
+
+current_session.canvas_site_admin? # true if the user is a Canvas Site Admin
+```
+
+`lti_roles` reads the LTI 1.3 roles claim, or `ext_roles` on LTI 1.0. It understands both LIS v1
+URNs (`urn:lti:role:ims/lis/Instructor`) and LIS v2 URLs
+(`http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor`).
+
+## Canvas role labels.
+
+```ruby
+current_session.canvas_role_labels # Roles in the launch context
+```
+
+`canvas_role_labels` reads the `canvas_role` custom param. Add
+`custom_canvas_role: '$Canvas.membership.roles'` to `PandaPal.lti_custom_params` to use it.
+
+```ruby
+current_session.canvas_account_role_labels                    # Roles on the Organization's account
+current_session.canvas_account_role_labels(account)           # Roles on another account
+current_session.canvas_account_role_labels(account, inherited: true) # Include roles on parent accounts
+```
+
+`canvas_account_role_labels` returns the user's active admin roles on an account. `account` can be:
+
+- an object that responds to `canvas_id`
+- a Canvas account ID
+- `'self'` or `:root` (the default)
+
+It reads the app's `Admin` model when there is one, and `'self'` means the Organization's
+`canvas_account_id`. Otherwise, it calls the Canvas API through `canvas_sync_client`, passes
+`'self'` through to the API as is, and caches the result for one hour.
+
+With `inherited: true`, roles on any parent account count too, because an admin of a parent account
+administers everything beneath it. `canvas_account_ancestry(account)` returns that chain of account
+IDs, nearest first. It reads the app's `Account` model (`canvas_parent_account_id`) when there is one,
+and walks the Canvas API otherwise.
+
+## Ability helpers.
+
+Every controller, and any class that includes `PandaPal::Concerns::AbilityHelper` (like a CanCan
+`Ability`), gets:
+
+| Method | Purpose |
+| --- | --- |
+| `panda_pal_session` | The `PandaPal::Session`. Set `@panda_pal_session`, or `@controller` to read it from a controller. |
+| `rails_session` | The Rails session. Set `@rails_session` or `@controller`. |
+| `is_lti_launch?` | `true` if there's a PandaPal session. |
+| `cache_on_session(key) { ... }` | Memoize a value on the session. |
+| `launch_params`, `get_lti_cust_param`, `lti_launch_placement`, `canvas_site_admin?`, `lti_roles`, `canvas_role_labels`, `canvas_account_role_labels` | Delegated to `panda_pal_session`. |
+
+`cache_on_session` also works as a class macro, to cache a method's result on the session:
+
+```ruby
+class Ability
+  include CanCan::Ability
+  include PandaPal::Concerns::AbilityHelper
+
+  def initialize(controller)
+    @controller = controller
+    # ...
+  end
+
+  def admin?
+    canvas_account_role_labels(inherited: true).include?("AccountAdmin")
+  end
+  cache_on_session :admin?
+end
+```
+
+For CanCan in ActionCable channels, see [action-cable.md](action-cable.md).

data/docs/routing-and-launches.md

@@ -0,0 +1,108 @@
+# Routing and launches.
+
+## Mounting the engine.
+
+```ruby
+# config/routes.rb
+mount PandaPal::Engine, at: '/lti'
+```
+
+Mount the engine before any `lti_nav` routes. It serves:
+
+| Path | Purpose |
+| --- | --- |
+| `/v1p0/config`, `/v1p3/config` | Tool configuration (LTI 1.0 XML, LTI 1.3 JSON). Add `?tool=` for a [non-default tool](multiple-tools.md). |
+| `/config` | Legacy alias for `/v1p0/config`. |
+| `/v1p0/launch` | LTI 1.0/1.1 launch. |
+| `/v1p3/oidc_login` | LTI 1.3 OIDC login. |
+| `/v1p3/resource_link_request` | LTI 1.3 launch. |
+| `/v1p3/deep_link_request` | LTI 1.3 Deep Linking launch. |
+| `/v1p3/public_jwks` | The tool's public JWKS. |
+| `/call_logic` | [Generated API calls](api-calls.md). |
+
+## Launch routes with `lti_nav`.
+
+`lti_nav` declares a placement and the app route a launch lands on, in one line. It also calls
+`PandaPal.stage_placement` for you.
+
+```ruby
+# config/routes.rb
+mount PandaPal::Engine, at: '/lti'
+
+scope '/organizations/:organization_id' do
+  lti_nav account_navigation: 'accounts#launch_landing'
+  lti_nav course_navigation: 'courses#launch_landing'
+end
+
+# For a non-default tool, served at <mount>/translate/editor_button
+lti_nav editor_button: 'translate#editor_button', tool: :translate
+```
+
+### `auto_launch`.
+
+- **`auto_launch: true`** (the default for LTI 1.3): PandaPal validates the launch, creates the
+  session, switches to the Organization's tenant, and redirects to your action with a
+  `panda_token`. Your action just renders.
+- **`auto_launch: false`** (the default for LTI 1.0/1.1): Canvas posts straight to your action, and
+  your controller validates the launch itself (see below).
+
+When you don't set it and `:organization_id` is in the route path, `auto_launch` is `true`.
+
+## What an auto launch stores.
+
+After an auto launch, `current_session` holds:
+
+| Key | Value |
+| --- | --- |
+| `current_session.launch_params` | The decoded LTI 1.3 `id_token`, or the LTI 1.0 POST params. |
+| `current_session[:launch_url_params]` | Query params on the launch URL. |
+| `current_session.lti_launch_placement` | The placement that was launched. |
+| `current_session[:lti_version]` | `'v1p3'` or `'v1p0'`. |
+| `current_session.lti_tool` | Which [tool](multiple-tools.md) was launched. |
+| `current_session.lti_platform` | The LTI 1.3 platform (issuer, JWKS, and so on). |
+
+See [sessions.md](sessions.md#reading-launch-data) for the helpers that read these.
+
+## Validating launches yourself.
+
+For `auto_launch: false` routes, validate the launch in your controller:
+
+```ruby
+class LaunchController < ApplicationController
+  skip_before_action :verify_authenticity_token  # Canvas posts the launch without a CSRF token
+  skip_before_action :forbid_access_if_lacking_session, raise: false # No session yet
+  before_action :validate_launch!
+  around_action :switch_tenant
+
+  def account
+    current_session[:canvas_user_id] = params[:custom_canvas_user_id]
+    redirect_with_session_to :accounts_url
+  end
+end
+```
+
+`validate_launch!` checks the OAuth 1.0a signature (LTI 1.0/1.1) or the `id_token` JWT (LTI 1.3),
+and starts a session. Pass `version: :v1p0` or `version: :v1p3` to accept only one version. It
+renders a 401 when validation fails.
+
+`switch_tenant` must run as an `around_action` (or be given a block).
+
+## Canvas beta and test.
+
+When an LTI 1.3 login comes from Canvas beta or test (`canvas_environment` is set), PandaPal:
+
+1. Forwards the login to the matching domain in `PandaPal.lti_environments`, if there is one.
+2. Rejects the launch with a 400 error if the Organization's `canvas_url` doesn't point at that
+   environment (for example, a production Organization launched from beta).
+
+## Data segregation in routes.
+
+Put your app routes under an Organization scope, so every request switches to the right tenant:
+
+```ruby
+scope '/organizations/:organization_id' do
+  resources :accounts, only: :index
+end
+```
+
+See [multi-tenancy.md](multi-tenancy.md) for the other ways PandaPal picks a tenant.

data/docs/security.md

@@ -0,0 +1,60 @@
+# Security.
+
+## Validate every launch.
+
+Always check that a launch came from Canvas and wasn't spoofed. Auto-launch routes do this for you.
+For any other launch point, call `validate_launch!` (see
+[routing-and-launches.md](routing-and-launches.md#validating-launches-yourself)).
+
+LTI 1.3 launches also check that:
+
+- The issuer is trusted for the Organization (see
+  [configuration.md](configuration.md#trusted-platforms)).
+- The `id_token` signature matches the platform's JWKS. PandaPal refetches the JWKS once if the key
+  ID is unknown.
+- The `state` and `nonce` match the OIDC login.
+- The launch isn't from Canvas beta or test for a production Organization (see
+  [routing-and-launches.md](routing-and-launches.md#canvas-beta-and-test)).
+
+## Require a session.
+
+Every action that isn't a launch point or a public API endpoint should require a session:
+
+```ruby
+# app/controllers/application_controller.rb
+prepend_before_action :forbid_access_if_lacking_session
+```
+
+This renders a 401 unless the request carries a valid panda token for the current Organization and
+tenant. Skip it where needed:
+
+```ruby
+skip_before_action :forbid_access_if_lacking_session, only: :launch
+```
+
+This is easiest with a JavaScript frontend (such as React) that sends the token as a header.
+
+## CSRF.
+
+PandaPal skips the Rails CSRF check on requests that carry no cookies. Those requests authenticate
+with a panda token instead, and browsers often block cookies in `<iframe>`s anyway.
+
+## Secure headers.
+
+PandaPal bundles the `secure_headers` gem and applies a default config:
+
+- `X-Frame-Options: ALLOWALL`, so Canvas can frame the tool
+- `SameSite=None` cookies, which are `Secure` outside development and test
+- A Content Security Policy limited to `'self'`, with exceptions for Sentry when it's configured
+- In development, extra CSP exceptions for webpack-dev-server (port 3035), the Vite dev server (port
+  3036), React DevTools, rack-mini-profiler, and Scout APM (`SCOUT_DEV_TRACE`)
+
+To customize it, add your own initializer:
+
+```ruby
+# config/initializers/secure_headers.rb
+SecureHeaders::Configuration.default do |config|
+  PandaPal::SecureHeaders.apply_defaults(config) # Optional, but recommended
+  # ...
+end
+```