panda_pal 5.19.0 → 5.19.2

data/README.md

@@ -1,733 +1,182 @@
-# PandaPal
-
-## LTI Configuration
-A standard Canvas LTI may have a configuration similar to the one below
+# PandaPal.
+
+PandaPal is a mountable Rails engine for building LTI tools (primarily for Canvas). It handles
+launches, sessions that work inside `<iframe>`s, per-customer data separation, and installing the
+tool into Canvas, so your app can focus on what the tool does.
+
+## Features.
+
+Each feature lists its key APIs, so you can spot them without opening the page. Before you write a
+helper of your own, check [before-you-build.md](docs/before-you-build.md).
+
+- **LTI 1.3 launches:** OIDC login, `id_token` validation against the platform JWKS, trusted-issuer
+  checks, and a public JWKS endpoint. See [routing-and-launches.md](docs/routing-and-launches.md).
+  - Key APIs: `lti_nav`, `validate_launch!`, `current_session.launch_params`, `current_lti_platform`
+- **LTI 1.0/1.1 launches:** OAuth 1.0a signature validation, plus Basic Outcomes
+  [grade passback](docs/grade-passback.md).
+  - Key APIs: `validate_launch!(version: :v1p0)`, `PandaPal::Jobs::GradePassbackJob`
+- **Tool configuration:** LTI 1.3 JSON and LTI 1.0 XML configs, generated from your placements and
+  routes. See [configuration.md](docs/configuration.md).
+  - Key APIs: `PandaPal.lti_options`, `PandaPal.stage_placement`, `PandaPal.lti_custom_params`,
+    `PandaPal.lti_environments`
+- **Deep Linking (LTI 1.3):** content-item builders and the signed response.
+  See [deep-linking.md](docs/deep-linking.md).
+  - Key APIs: `PandaPal::DeepLinkingHelpers`, `build_link_content_item`, `render_deep_linking_response`
+- **Assignment and Grade Services (LTI 1.3):** post scores, and read line items and results.
+  See [ags.md](docs/ags.md).
+  - Key APIs: `PandaPal::AgsHelpers`, `ags_client.post_score`, `ags_client.line_items`,
+    `ags_client.results`, `PandaPal.lti_scopes`
+- **Multiple tools per app:** each with its own Developer Key, placements, and custom params.
+  See [multiple-tools.md](docs/multiple-tools.md).
+  - Key APIs: `PandaPal.define_tool`, `lti_nav ..., tool:`, `current_session.lti_tool`,
+    `PandaPal::LtiRegistration`
+- **Cookieless sessions:** database-backed sessions carried by signed panda tokens, with
+  single-use, IP-locked, expiring, and single-URL variants. See [sessions.md](docs/sessions.md).
+  - Key APIs: `current_session`, `current_session.session_key`, `redirect_with_session_to`,
+    `url_with_session`, `link_nonce`, `current_session.cache`
+- **Multi-tenancy:** one Postgres schema per Organization, with optional multi-database sharding.
+  See [multi-tenancy.md](docs/multi-tenancy.md).
+  - Key APIs: `org.switch_tenant`, `switch_tenant(org)`, `org.tenant_name`, `current_organization`,
+    `PandaPal::SpecHelper.with_multiple_shards`
+- **Canvas installs:** create the Developer Key and install the tool from the console or a rake task,
+  with install callbacks. See [installation.md](docs/installation.md).
+  - Key APIs: `org.install_lti`, `after_lti_install`, `current_lti_install`, `panda_pal:org:new`,
+    `panda_pal:org:install`
+- **Organizations and settings:** encrypted, schema-validated settings per Organization, plus Canvas
+  helpers. See [organizations.md](docs/organizations.md).
+  - Key APIs: `OrganizationExtension`, `settings_structure`, `define_setting`, `org.bearcat_client`,
+    `org.canvas_lti_launch_url`
+- **Roles:** parsed LTI roles, Canvas role labels, inherited account admin roles, and CanCan ability
+  helpers. See [roles-and-abilities.md](docs/roles-and-abilities.md).
+  - Key APIs: `lti_roles`, `canvas_role_labels`, `canvas_account_role_labels(inherited:)`,
+    `canvas_site_admin?`, `PandaPal::Concerns::AbilityHelper`, `cache_on_session`
+- **ActionCable:** session lookup on connections, tenant-scoped broadcasts, and CanCan in channels.
+  See [action-cable.md](docs/action-cable.md).
+  - Key APIs: `connection.panda_session`, `authorize!` in channels, `Apartment::Tenant.with_lazy_tenant`
+- **Scheduled tasks:** per-Organization cron tasks. See [task-scheduling.md](docs/task-scheduling.md).
+  - Key APIs: `scheduled_task`, `settings[:task_schedules]`
+- **Generated API calls:** console-minted URLs that run code for UAT. See
+  [api-calls.md](docs/api-calls.md).
+  - Key APIs: `org.create_api`, `PandaPal::ApiCall`
+- **Frontend support:** `@inst_proserv/toolkit` handles tokens, API calls, and ActionCable in the
+  browser. See [frontend.md](docs/frontend.md).
+  - Key APIs: `APIBase`, `signURL`, `subscribe_channel`, `useModelSubscription`, `createLtiHistory`
+- **Security defaults:** secure headers, iframe-friendly cookies, and session enforcement. See
+  [security.md](docs/security.md).
+  - Key APIs: `forbid_access_if_lacking_session`, `valid_session?`, `PandaPal::SecureHeaders.apply_defaults`
+
+## What PandaPal integrates with.
+
+PandaPal sets these up for you when they're present:
+
+| Tool | What PandaPal does |
+| --- | --- |
+| Canvas | Launches, trusted issuers (production, beta, test, and loadtest), beta/test environment forwarding, Developer Key and external tool installs, and handling of deploy-locked LTI Registrations. |
+| [ros-apartment](https://github.com/rails-on-services/apartment) | Tenant schemas, a request elevator, tenant-scoped `Rails.cache`, `load_async` support, and multi-database sharding. |
+| Sidekiq | Requires `ros-apartment-sidekiq`, so jobs run in the tenant that enqueued them. |
+| sidekiq-scheduler | Per-Organization scheduled tasks, plus daily session cleanup. |
+| Delayed Job | A plugin that runs jobs in the tenant that enqueued them. |
+| ActionCable | Session lookup on connections, lazy per-tenant workers, and tenant-scoped broadcasts. See [action-cable.md](docs/action-cable.md). |
+| CanCan | `authorize!` and `authorized?` in ActionCable channels, and rejected subscriptions on `AccessDenied`. |
+| Bearcat and CanvasSync | Canvas API calls for installs and role lookups. CanvasSync's `canvas_sync_client` is used when it's defined. |
+| secure_headers | A default, LTI-friendly header config. |
+| [@inst_proserv/toolkit](docs/frontend.md) | The frontend half: reads the session from a `js-env` meta tag, sends it on API calls, signs `T-URL` tokens in the browser, and opens authenticated ActionCable connections that refresh their own tokens. |
+| Rails console (IRB and Pry) | A prompt that shows the app, environment, and tenant, and auto-switching to the local Organization. |
+
+## Quick start.
+
+```ruby
+# Gemfile
+gem 'panda_pal'
+gem 'bearcat'                # Optional: installs into Canvas
+gem 'ros-apartment-sidekiq'  # Required if you use Sidekiq
+```
 
 ```ruby
 # config/initializers/lti.rb
 PandaPal.lti_options = { title: 'Teacher Reports' }
-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' }
-# :user_navigation, :course_navigation for user context and course context endpoints respectively
-PandaPal::stage_navigation(:account_navigation, {
-  enabled: true,
-  # url: :account_index, # Optional if using lti_nav
-  text: 'Teacher Reports',
-  visibility: 'admins',
-})
-```
-
-Configuration data for an installation can be set by creating a `PandaPal::Organization` record.  Due to the nature of the data segregation, once created, the name of the organization should not be changed (and will raise a validation error).
-
-### Canvas Installation
-As of version 5.5.0, LTIs can be installed into Canvas via the console:
-```ruby
-org.install_lti(
-  host: "https://your_lti.herokuapp.com",
-  context: "account/self", # (Optional) Or "account/3", "course/1", etc
-  exists: :error, # (Optional) Action to take if an LTI with the same Key already exists. Options are :error, :replace, :duplicate, :update
-  version: "v1p3", # (Optional, default `v1p3`) LTI Version. Accepts `v1p0` or `v1p3`.
-  dedicated_deployment: false, # (Optional) If true, the Organization will be updated to link to a single deployment rather then to the general LTI Key. (experimental, LTI 1.3 only)
-  tool: :default, # (Optional) Which tool to install - see Multiple Tools below
-)
-```
-
-### 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, 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 URL: `/v1p3/config?tool=translate` and `/v1p0/config?tool=translate`. The default tool's URLs are unchanged.
-- **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.
-- **Install hooks:** `before_lti_install` / `after_lti_install` callbacks can read `current_lti_install` (`tool`, `host`, `context`, `version`, `exists`, `dedicated_deployment`, and, in `after_lti_install`, the resulting Canvas `installation`). That lets you install a second tool alongside the default one:
-  ```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. 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-link redirect, using that tool's placements.
-- **Registering by hand:** if a tool's Developer Key was set up outside `install_lti`, register it yourself: `org.lti_registrations.create!(tool: 'translate', client_id: '10000000000123', deployment_id: nil)`. A registration with a `deployment_id` takes priority over one without.
-
-### LTI 1.3 Configuration
-LTI 1.3 has some additional configuration steps required to setup an LTI:
-
-1. If you're running Canvas locally, make sure the `config/redis.yml` and `config/dynamic_settings.yml` files exist in Canvas.
-2. Also make sure `config/security.yml` is present and set `development.lti_iss` to `'http://localhost:3000'` (where 3000 is the port you're running Canvas on).
-3. In prod, you'll need to generate a RSA Private Key for the LTI to use. You have several options:
-   - Set the `LTI_PRIVATE_KEY` environment variable with the PEM-encoded private key content
-   - Set the `LTI_PRIVATE_KEY_PATH` environment variable with the path to your private key file (relative to Rails.root or absolute path)
-   - For encrypted private keys, set the `LTI_PRIVATE_KEY_PASSWORD` environment variable with the decryption password
-   - Manually set `PandaPal.lti_private_key = OpenSSL::PKey::RSA.new(key)`
-4. Make sure you have Redis installed and linked correctly
-5. Your PandaPal::Organization's `key` should be `CLIENT_ID/DEPLOYMENT_ID` (which can be found in Canvas). If a Deployment ID is not given, the key should just be `CLIENT_ID`.
-
-
-To generate an encrypted private key using OpenSSL:
-```bash
-# Generate new encrypted private key
-openssl genrsa -aes256 -out encrypted_private_key.pem 2048
-
-# Or encrypt existing private key
-openssl rsa -aes256 -in existing_private_key.pem -out encrypted_private_key.pem
-```
-
-**Note**: The private key file path supports both relative paths (relative to Rails.root) and absolute paths.
-
-### Launch URL property
-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 is now validating that this launch URL exists and requires it per the LTI spec. As of PandaPal 3.1.0, you now have 6 options to use this.
-Use one of these 6 options in `PandaPal.lti_options` hash.
-1. Use option `secure_launch_url: 'http://domain.com/path'` when a full static secure domain is needed.
-2. Use option `secure_launch_path: '/path'` when you need the secure options and want the host to be dynamic and just need to provide a path.
-3. Use option `launch_url: 'http://domain.com/path'` when a full static domain is needed.
-4. Use option `launch_path: '/path'` when you don't need the secure options and want the host to be dynamic and just need to provide a path.
-5. Leave this property off, and you will get the dynamic host with the root path ('http://appdomain.com/') by default.
-6. If you really do not want this property use the option `launch_url: false` for it to be left off.
-
-### Task Scheduling
-`PandaPal` includes an integration with `sidekiq-scheduler`. You can define tasks on an Organization class Stub like so:
-```ruby
-# <your_app>/app/models/organization_extension.rb
-module OrganizationExtension
-  extend ActiveSupport::Concern
-
-  # Will invoke CanvasSyncStarterWorker.perform_async() according to the cron schedule
-  scheduled_task '0 15 05 * * *', :identifier, worker: CanvasSyncStarterWorker
-
-  # Will invoke the method 'organization_method' on the Organization
-  scheduled_task '0 15 05 * * *', :organization_method_and_identifier
-
-  # If you need to invoke the same method on multiple schedules
-  scheduled_task '0 15 05 * * *', :identifier, worker: :organization_method
-
-  # You can also use a block
-  scheduled_task '0 15 05 * * *', :identifier do
-    # Do Stuff
-  end
-
-  # You can use a Proc (called in the context of the Organization) to determine the schedule
-  scheduled_task -> { settings[:cron] }, :identifier
-
-  # You can specify a timezone. If a TZ is not coded and settings[:timezone] is present, it will be appended automatically
-  scheduled_task '0 15 05 * * * America/Denver', :identifier, worker: :organization_method
-
-  # Setting settings[:task_schedules][:identifier] will override the code cron schedule. Setting it to false will disable the Task
-  # :identifer values _must_ be unique, but can be nil, in which case they will be determined by where (lineno etc) scheduled_task is called
-end
-```
-
-### Organization Attributes
-  `id`: Primary Key
-  `name`: Name of the organization. Used to on requests to select the tenant
-  `key`: Key field from CanvasLMS
-  `secret`: Secret field from CanvasLMS
-  `canvas_account_id`: ID of the corresponding Canvas account.
-  `settings`: Hash of settings for this Organization
-  `salesforce_id`: ID of this organization in Salesforce
-
-XML for an installation can be generated by visiting `/lti/config` in your application.
-
-### Generated API Methods
-It's common to need to manually trigger logic during UAT. PandaPal 5.6.0+ adds a feature to enable clients to do this themselves.
-This is done by a deployer accessing the console and creating a `PandaPal::ApiCall`. This can be done like so:
-```ruby
-org.create_api(<<~RUBY, expiration: 30.days.from_now, uses: 10)
-  arg1 = p[:some_param] # `p` is an in-scope variable that is a Hash of the params sent to the triggering request.
-  PandaPal::Organization.current.trigger_canvas_sync()
-  { foo: "bar" } # Will be returned to the client. Can be anything that is JSON serializable.
-RUBY
-# OR
-org.create_api(:symbol_of_method_on_organization, expiration: 30.days.from_now, uses: 10)
-```
-This will return a URL like such: `/panda_pal/call_logic?some_param=TODO&token=JWT.TOKEN.IS.HERE` that can be either GET'd or POST'd.
-The URL generator will *attempt* to determine which params the logic accepts and insert them as `param=TODO` in the generated URL.
-
-When triggered, the return value of the code will be wrapped and sent to the client:
-```json
-{
-  "status": "ok",
-  "uses_remaining": 9,
-  "result": {
-    "foo": "bar",
-  }
+PandaPal.lti_custom_params = {
+  custom_canvas_user_id: '$Canvas.user.id',
+  custom_canvas_role: '$Canvas.membership.roles',
 }
+PandaPal.stage_placement(:account_navigation, text: 'Teacher Reports', visibility: 'admins')
 ```
 
-#### Revoking
-A Call URI may be revoked by deleting the `PandaPal::ApiCall` object. `uses:` and logic are stored in the DB (and can thus be altered), but `expiration:` is stored in the JWT and is thus immutable.
-
-### Routing
-
-The following routes should be added to the routes.rb file of the implementing LTI. (substituting `account_navigation` with the other staged navigation routes, if necessary)
-
 ```ruby
 # config/routes.rb
 mount PandaPal::Engine, at: '/lti'
-root to: 'panda_pal/lti#launch'
-
-# Add Launch Endpoints:
-lti_nav account_navigation: 'accounts#launch', auto_launch: false # (LTI <1.3 Default)
-# -- OR --
-scope '/organizations/:organization_id' do
-  lti_nav account_navigation: 'accounts#launch_landing', auto_launch: true # (LTI 1.3 Default)
-  lti_nav account_navigation: 'accounts#launch_landing' # Automatically sets auto_launch to true because :organization_id is part of the path
-  # ...
-end
-```
 
-`auto_launch`: Setting to `true` will tell PandaPal to handle all of the launch details and session creation, and then pass off to
-the defined action. Setting it to `false` indicates that the defined action handles launch validation and setup itself (this has been the legacy approach).
-Because `auto_launch: false` is most similar to the previous behavior, it is the default for LTI 1.0/1.1 LTIs. For LTI 1.3 LTIs, `auto_launch: true` is the default. If not specified and `:organization_id` is detected in the Route Path, `auto_launch` will be set to `true`
+# The route an account_navigation launch lands on
+lti_nav account_navigation: 'accounts#launch'
 
-## Deep Linking (LTI 1.3)
-
-PandaPal provides comprehensive support for LTI 1.3 Deep Linking, allowing tools to be configured for content selection that can be placed directly into Canvas courses.
-
-### Quick Start
-
-1. **Configure placements** in your LTI initializer:
-```ruby
-# config/initializers/lti.rb
-PandaPal.stage_placement(:content_selection, {
-  deep_linking: true,
-  deep_link_redirect_url: :content_selection_url,
-  text: 'Select Content',
-  enabled: true
-})
-```
-
-2. **Include helpers** in your controller and build content items with **required `launch_type`**:
-```ruby
-class ContentSelectionController < ApplicationController
-  include PandaPal::DeepLinkingHelpers
-
-  def create
-    content_items = [
-      build_link_content_item(
-        url: panda_pal.v1p3_resource_link_request_url,
-        title: 'Selected Content',
-        custom: {
-          content_id: params[:content_id],
-          launch_type: :content_launch  # REQUIRED for proper routing
-        }
-      )
-    ]
-    render_deep_linking_response(content_items)
-  end
-end
-```
-
-3. **Add corresponding launch routes**:
-```ruby
-# config/routes.rb
-lti_nav content_launch: 'content#launch'
-```
-
-**⚠️ IMPORTANT**: All content items **MUST** include `launch_type` in the `custom` hash. This is used by the `resource_link_request` action to determine which route to redirect to when Canvas launches your content.
-
-**For complete configuration options, implementation examples, helper method documentation, and troubleshooting, see [DEEP_LINKING.md](DEEP_LINKING.md).**
-
-## Assignment and Grade Services (LTI 1.3)
-
-PandaPal can post scores and read line items and results through LTI Advantage AGS.
-
-1. **Request the scopes** in your LTI initializer (published in `/v1p3/config`):
-```ruby
-# config/initializers/lti.rb
-PandaPal.lti_scopes = [PandaPal::LtiConstants::AgsScopes::SCORE]
-```
-
-2. **Post a score** from a controller serving the launched session:
-```ruby
-class QuizController < ApplicationController
-  include PandaPal::AgsHelpers
-
-  def submit
-    ags_client.post_score(score_given: 8, score_maximum: 10)
-  end
-end
-```
-
-**For scopes, line items, results, service tokens, background jobs and error handling, see [AGS.md](AGS.md).**
-
-## Implementating data segregation
-This engine uses Apartment to keep data segregated between installations of the implementing LTI tool.
-By default, it does this by inspecting the path of the request, and matching URLs containing `orgs` or `organizations`,
-followed by the numeric ID of the organization (path such as `/organizations/123/accounts`).
-As such, all URLs should be built on top of a routing scope, such as the example below.
-
-```ruby
 scope '/organizations/:organization_id' do
-  resources :accounts, only: :index do
-    collection do
-      get 'teachers' => 'accounts#teachers'
-    end
-  end
-end
-```
-
-This can be overriden by creating an initializer, and adding a custom elevator
-
-```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]).try(:name)
-  end
-}
-```
-
-It is also possible to switch tenants by implementing `around_action :switch_tenant` in the controller.
-However, it should be noted that calling `switch_tenant` must be used in an `around_action` hook (or given a block), and is only intended to be used for LTI launches, and not subsequent requests.
-
-### Sharding
-PandaPal 5.12 added support for multi-DB sharding. If you wish to use this, add a `shard` column to the `PandaPal::Organization` model. The implementation should be fairly transparent and should behave as normal PandaPal/Apartment - the only difference is that tenants can be created on different DB shards.
-
-The list of available shards is computed from the Environment variables. On startup, the application looks for variables with the following formats:
-- `SHARD_DB_XYZ_URL`
-- `HEROKU_POSTGRESQL_XYZ_URL`
-(where `XYZ` is the shard identifier)
-
-When an `Organization` is created, it is assigned to a random shard (or if no shards were discovered, it is placed in the default database as normal). Alternatively, a specific shard can be specified: `PandaPal::Organization.new(shard: "shard_a")`. An `Organization` can be added to the primary shard with `shard: "default"`
-
-The `PandaPal::Organization` record is still created in the `public` schema of the default database, as per usual.
-
-### Rake tasks and jobs
-**Delayed Job Support has been removed. This allows each project to assess it's need to handle background jobs.**
-
-The Apartment Gem makes it so background jobs need to be run within the current tenant. If using sidekiq, there is a gem that
-does this automatically called `apartment-sidkiq`. If Delayed Jobs, see how it's done in version 1 of PandaPal.
-
-For rake tasks, the current tenant will be set to `public`, and thus special handling must be taken when running the task or queueing jobs as part of it.
-
-One potential solution is to create a method with switches between tenants, and invoke the job for each individual organization as necessary.
-
-```ruby
-# config/initializers/global_methods.rb
-def switch_tenant(tenant, &block)
-  if block_given?
-    Apartment::Tenant.switch(tenant, &block)
-  else
-    Apartment::Tenant.switch! tenant
-  end
-end
-```
 
-```ruby
-# lib/tasks/lti_tasks.rake
-namespace :lti_tasks do
-  desc 'some rake task'
-  task some_rake_task: :environment do
-    PandaPal::Organization.all.each do |org|
-      org.switch_tenant do
-        SomeJob.perform_later
-      end
-    end
-  end
+  resources :reports
 end
 ```
 
-## Controller helper methods
-Controllers will automatically have access to a number of methods that can be helpful to implement.  A list with descriptions is provided below.
-
-* `validate_launch!` - should be used in any tool launch points, and will verify that the launch request received from Canvas is legitimate based on the saved key and secret.
-* `current_session` - PandaPal provides support to use database persisted sessions, rather than the standard rails variety, as these play better when the tool is launched in an `iframe`.  The `session_key` attribute from the returned object needs to be served to the client at some point during the launch and during subsequent requests.  The benefit from this is that sessions will exist entirely in the frame used to launch the tool, and will not be visible should the user be accessing the tool in other contexts simultaneously.  See section below for more information about this method.
-* `current_organization` - Used to return the organization related to the currently selected tenant.  See section below for more information about this method.
-* `session_changed?` - returns true if the session given by `current_session` has been modified during the request.
-* `save_session` - Saves the session given by `current_session` to the database.
-
-## Sessions and `current_session`
-Because of the ever-increasing security around `<iframe>`s and cookies, a custom session implementation has been rolled into `PandaPal`.
-The implementation is mostly passive, but requires some changes and caveats as opposed to the native Rails implementation.
-
-The current session object can be accessed from any controller using `current_session`.
-Session data can be accessed and modified using `current_session[:key]`.
-
-Because cookies are unreliable, it becomes the responsibility of the LTI developer to ensure that a custom "cookie" is passed to the frontend with each response and returned to the backend with each request, otherwise the backend won't be able to access the current session. There are a few ways to do this.
-
-Generally, the method for passing the session "cookie" to the frontend looks something like:
-```html
-<meta name="session_key" content="<%= current_session.session_key %>">
-```
-
-### Panda Token Format
-The `session_key` used to be a single value secret, but as of PandaPal 5.14, it is formatted as such (and referred to as a "Full-Key Panda Token"):
-`<Base64({ v: TOKEN FORMAT, o: ORG ID, s: SESSION ID, typ: "KEY" })>.<SESSION SECRET>`
-
-Additionally as of 5.14, "session_tokens" were dissolved into the Panda Token format (and now referred to as "Limited-Use Panda Tokens").
-These Limited-Use tokens are formatted as such:
-`<Base64({ v: TOKEN FORMAT, o: ORG ID, s: SESSION ID, typ: "X", ... })>.<HMAC(key: SESSION_SECRET, content: Base64(...))>`
-
-Currently, there is support for these `typ`es (also noted with any other params to be included in the B64 content):
-- `T-URL` `{ usig: HMAC(key: SESSION_SECRET, content: URL_PATH_AND_QUERY) }` - Use to authenticate `GET`ting a single URL.
-  - May be generated on the client using `@inst_proserv/toolkit/panda_tokens`
-- `T-NONCE` `{ nnc: NONCE }` - Stores a single-use nonce in the Session. Can only be used once and will expire as soon as another `T-NONCE` token is created in another request.
-- `T-IP` `{ ip: 1.2.3.4 }` - Token restricted to use by a single IP address
-- `T-EXP` `{ exp: }` - Basic, time-limited token
-
-All Limited-Use tokens may also include these parameters:
-- `exp` - ISO8601 Expiration timestamp
-
-### Passing the Session
-PandaPal looks for Session information in multiple places (in order of precedence):
-- `X-Panda-Token` Header
-- `Authorization: Bearer <PANDA TOKEN>` Header
-- `Authorization: token=<PANDA TOKEN>` Header (Deprecated; legacy-use only). Supports use of legacy or new-format
-- `panda_token` param
-- `session_key` param (Deprecated; legacy-use only). Supports use of legacy or new-format
-- `session_token` param (Deprecated; legacy-use only)
-
-Use of one of the supported HTTP Headers is preferred.
-`panda_token=<Full-Use Token>` param may be used for (non-`GET`) HTML `<form>`s.
-`panda_token=<Limited-Use Token>` param should be used for `GET` requests in-which you cannot control a Header.
-
-### Redirecting and Multi-Page Applications
-Special instructions must be followed when using `link_to` or `redirect_to` to ensure that the Session is passed correctly:
-
-Add a `session_token:` (notice the use of _`_token`_ as opposed to _`_key`_!) parameter when using `link_to` or `redirect_to`:
-```ruby
-  link_to "Link Name", somewhere_else_path(panda_token: link_nonce)
-  redirect_to somewhere_else_path(panda_token: link_nonce)
-```
-You can also use the `redirect_with_session_to` helper, which will automatically the `panda_token:` param (and, to support legacy apps, an `organization_id:` param if needed):
-```ruby
-  redirect_with_session_to :somewhere_else_path, other_param: 1
-```
-
-For each request (not each call), `link_nonce` Limited-Use Token.
-The default `typ`e is `T-NONCE`, but this can be controlled by passing a `type:` param, or by setting `link_nonce_type` in the controller, eg:
-```ruby
-link_nonce_type "T-IP"
-
-def action
-  redirect_to somewhere_else_path(panda_token: link_nonce(type: "T-IP"))
-end
-```
-
-### Persisting the session
-The session is automatically saved using an `after_action` callback. This callback is poised to run last, but if that causes issues
-(eg some other callback running afterwards and needing to modify the session), `skip_after_action :auto_save_session` can be used
-and a custom implementation can be supplemented.
-
-### Session cleanup
-Over time, the sessions table will become bloated with sessions that are no longer active.
-If `sidekiq-scheduler` and `TaskScheduling` are enabled, cleanup will be performed automatically. Otherwise you should schedule, `rake panda_pal:clean_sessions` to run periodically (recommend weekly).
-
-## Organizations and `current_organization`
-Similar to `current_session`, `current_organization` can be returned with a number of methods, shown below
-
-## Rake Tasks
-
-### `panda_pal:org:new`
-Opens `$EDITOR` and creates a new `Organization`. The opened editor is prefilled with all of the available Settings with optional settings pre-commented.
-
-### `panda_pal:org:dev`
-Similar to `panda_pal:org:new`, but is somewhat preconfigured for development environments.
-
-You can create a `~/pandapalrc.yml` file to specify additional defaults:
-```yml
-lti_host: http://localhost:5000
-settings:
-  canvas:
-    base_url: http://localhost:3000
-    api_token: Uo5yckRQuPl96qVxgt2IVxDAa5oSUo1dqbb2dBVOnpId18aTmjSXdYkn4BN9JF2k
-```
-NB: `settings` entries present in `~/pandapalrc.yml` that are not defined in the `settings_structure` will be ignored.
-
-### `panda_pal:org:edit[name]`
-Similar to `panda_pal:org:new` but for editing an existing Organization.
-
-### `panda_pal:org:install[orgname, http://url.of.lti]`
-Install the LTI into Canvas. Must specify the Organization and the host of the LTI
-
-### `panda_pal:org:reinstall[orgname, http://url.of.lti]`
-Same as `panda_pal:org:install`, but first deletes an existing installation
-
-## Security
-
-### Tool Launches
-Any time a tool launch request is received, we should **always** validate that it originated from within Canvas and that it wasn't spoofed.
-The easiest way to do this is to call `validate_launch!` in any controller action that is expecting to receive launch requests.
-
-### Validate active session is present
-It is easier to implement this if a purely javascript frontend is used (such as React).
-Any controller actions that are not designated as launch points, or externally available API endpoints (such as in the case where an endpoint should be exposed outside the context of a tool launch, and has its own authentication mechanisms in place) should implement a line similar to the one below in `application_controller.rb`
-
 ```ruby
 # app/controllers/application_controller.rb
-prepend_before_action :forbid_access_if_lacking_session
-```
-
-This will render an unauthorized message any time a request is received and a valid session is not present.
-It can be overridden on a action-by-action basis by using `skip_before_action`.
-
-```ruby
-skip_before_action :forbid_access_if_lacking_session, only: :launch
-```
-
-### Secure Headers
-PandaPal bundles the `secure_headers` Gem and provides a default config. The PandaPal default works for really basic apps, but you may need to provide
-a custom configuration. This can be done by creating a `secure_headers.rb` initializer in you App like so:
-```ruby
-SecureHeaders::Configuration.default do |config|
-  PandaPal::SecureHeaders.apply_defaults(config) # Optional, but recommended
-  # ...
+class ApplicationController < ActionController::Base
+  prepend_before_action :forbid_access_if_lacking_session
 end
-```
-
-## Validating settings in your LTI.
-
-You can specify a structure that you would like to have enforced for your settings.
-
-In your panda_pal initializer (i.e. `config/initializers/panda_pal.rb` or `config/initializers/lti.rb`)
-
-You can specify options that can include a structure for your settings.  If specified, PandaPal will
-enforce this structure on any new / updated organizations.
-
-```ruby
-PandaPal.lti_options = {
-  title: 'LBS Gradebook',
-  settings_structure: {
-    allow_additional: true, # Allow additional properties that aren't included in the :properties Hash.
-    allow_additional: { type: 'String' }, # You can also set :allow_additional to a settings specification that will be used to validate each additional setting
-    validate: ->(value, spec, **kwargs) {
-      # kwargs currently includes:
-      #   :errors => [An array to push errors to]
-      #   :path => [An array representation of the current path in the settings object]
-
-      # To add errors, you may:
-      # Push strings to the kwargs[:errors] Array:
-      kwargs[:errors] << "Your error message at <path>" unless value < 10
-      # Or return a string or string array:
-      value.valid? ? nil : "Your error message at <path>" # <path> will be replaced with the actual path that the error occurred at
-    },
-    properties: {
-      canvas_api_token: { type: 'String', required: true, },
-      catalog: { # :validate, :allow_additional, :properties keys are all supported at this level as well
-        type: 'Hash',
-        required: false,
-        validate: -> (*args) {},
-        allow_additional: false,
-        properties: {
 
-        },
-      }
-    }
-  },
-}
-```
-
-#### Legacy Settings Structure:
-Here is an example options specification:
-
-```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
-      base_url:
-        is_required: true
-        data_type: String
-    reports:
-      is_required: true
-      data_type: Hash
-      active_term_allowance:
-      submissions_report_time_length:
-        is_required: true
-        data_type: ActiveSupport::Duration
-      recheck_wait:
-        data_type: ActiveSupport::Duration
-      max_recheck_time:
-        is_required: true
-  ").deep_symbolize_keys
-}
-```
-(This loads the structure in from YAML, but you can specify a hash directly if you prefer.)
-
-Each data attribute can have two children attributes to describe desired structure:
-
-is_required: If specified, and specified as true, the parent attribute is required in the settings hash.
-
-data_type: If specified, and a settings hash contains this attribute, attribute data type will be compared
-           to the specified data type.  If you are not sure how to derive your class data type, you can
-           use `class` to determine data type.  For example:  30.minutes.class.to_s => "ActiveSupport::Duration"
-
-## Bridge vs Canvas
-As of 3.2.0, the LTI XML config can have subtle differences based on whether your platform is bridge, or canvas.
-This is determined by `PandaPal.lti_options[:platform]`.
-Set this to `platform: 'canvas.instructure.com'` (default)
-OR `platform: 'bridgeapp.com'`
-
-## Development:
-### Running Specs:
-Initialize the Specs DB:
-`cd spec/dummy; bundle exec rails db:drop; bundle exec rails db:create; RAILS_ENV=test rails db:migrate`
-Then `bundle exec rspec`
-
-## Safari Support
-Safari is weird (it blocks cookies in `<iframe>`s unless the site has set a cookie _outside_ of an `<iframe>` first), and you'll run into
-issues with Rails-native Sessions and CSRF because of that.
-
-This means that safari will likely refuse to send info about your rails session
-back to the LTI, and the application will start up a new session each time the
-browser navigates.  This likely means a new session each time the LTI launches.
-
-### PandaPal 5
-It has been a constant struggle to force safari to store and allow
-access to a rails session while the application is embedded in Canvas.
-
-As of PandaPal 5, a session cookie is no longer required by panda_pal.
-
-See the Section on [Sessions and `current_session`](#sessions-and-current_session)
-
-You will want to watch out for a few scenarios:
-1) Make sure you are using `redirect_with_session_to` if you need to redirect
-   and have your PandaPal session_key persisted server side.
-2) Use the `Authorization` header with `token={session_key}` to send your
-   PandaPal session info into api calls.
-3) If you use `link_to` and navigate in your LTI (apps that are not single page)
-   make sure you include the `link_nonce` like so:
-    ```ruby
-      link_to "Link Name", somewhere_else_path(arg, session_token: link_nonce)
-    ```
-    NB: As of PandaPal 5.2.6, you can instead use
-    ```ruby
-      link_to "Name", url_with_session(:somewhere_else_path, arg, kwarg: 1)
-    ```
-
-Persistent sessions have session_tokens as a way to safely communicate a session key in a way that is hopefully not too persistent in case it is logged somewhere.
-Options for communicating session_token -
-:nonce (default) - each nonce is good for exactly one communication with the backend server.  Once the nonce is used, it is no longer valid.
-:fixed_ip - each session_token is good until it expires.  It must be used from the same ip the LTI launched from.
-:expiring - this is the least secure.  Each token is good until it expires.
-
-For :fixed_ip and :expiring tokens you can override the default expiration period of 15 minutes.
-
-See the following example of how to override the link_nonce_type and token expiration length.
-
-```ruby
-class ApplicationController < ActionController::Base
-  link_nonce_type :fixed_ip
-  def session_expiration_period_minutes
-    120
+# app/controllers/accounts_controller.rb
+class AccountsController < ApplicationController
+  def launch
+    # PandaPal already validated the launch, started a session, and switched tenants
+    @user_id = current_session.canvas_user_id
+    @roles = current_session.canvas_role_labels
   end
-...
 end
 ```
 
-### Previous Safari Instructions
-Safari is weird and you'll potentially run into issues getting `POST` requests to properly validate CSRF if you don't do the following:
-
-- Make sure you have both a `launch` controller and your normal controllers. The `launch` controller should call `before_action :validate_launch!` and then redirect
-  to your other controller.
-- Make sure your other controller calls `before_action :forbid_access_if_lacking_session`
-
-This will allow `PandaPal` to apply an iframe cookie fix that will allow CSRF validation to work.
-
-## Migrating Major Versions
-
-### Upgrading to version 3
-
-Before upgrading save existing settings somewhere safe in case you need to
-restore them for whatever reason.
-
-panda_pal v3 introduces an encrypted settings hash.  This should provide more security in the case where a
-customer may have gained access to Organization information in the database.  Settings cannot be decrypted
-without knowing the secret decryption key.  For panda_pal, we are relying on the secret_key_base to be set
-(`typically in config/secrets.yml`), if that is not available we are falling back to directly use
-`ENV['SECRET_KEY_BASE']`.  For production environments, `config/secrets.yml` should not have a plain-text secret,
-it should be referencing an ENV variable.  Make sure your secret is not plain-text committed to a repository!
-
-The secret key is used to encrypt / decrypt the settings hash as necessary.
-
-Before upgrading to version 3, you should confirm that the secret key is set to a consistent value (if the
-value is lost your settings will be hosed).
-
-You should also rollback any local encryption you have done on the settings hash.  The settings hash
-should just be plainly visible when you upgrade to V3.  Otherwise the panda_pal migrations will
-probably fail.
-
-Once you have upgraded your gem, you will need to run migrations.  Before doing that, I would store off your
-unencrypted settings (just in case).
-
-`rake db:migrate`
-
-If all goes well, you should be set!  Log into console, and verify that you can still access settings:
-
-`PandaPal::Organization.first.settings`
-
-should show unencrypted settings in your console.
-
-If anything goes wrong, you should be able to rollback the change:
-
-`rake db:rollback STEP=2`
-
-If you need to give up on the change, just make sure to change your gem version for panda_pal to be < 3.
-
-### Upgrading from PandaPal 4 to 5:
-
-If your tool is setup according to a pretty standard pattern (see pace_plans,
-canvas_group_enrollment, etc), you shouldn't have to do anything to upgrade.
-
-You will want to make sure that IF your launch controller is redirecting, it is
-using "redirect_with_session_to".
-
-Here is an example launch / account controller setup, assuming an account launch.
-
-```ruby
-class LaunchController < ApplicationController
-  # We don't verify CSRF on launch because the LTI launch is done via a POST
-  # request, and Canvas wouldn't know anything about the CSRF
-  skip_before_action :verify_authenticity_token
-  skip_before_action :forbid_access_if_lacking_session # We don't have a session yet
-  before_action :validate_launch!
-  around_action :switch_tenant
-  before_action :handle_launch
+```erb
+<%# app/views/layouts/application.html.erb — hand the session token to the frontend %>
+<%= csrf_meta_tags %>
+<meta name="js-env" content="<%= { session_key: current_session&.session_key }.to_json %>">
+```
 
-  def handle_launch
-    current_session[:canvas_user_id] = params[:custom_canvas_user_id]
-    current_session[:canvas_course_id] = params[:custom_canvas_course_id]
-  end
+```ts
+// With @inst_proserv/toolkit, API calls and ActionCable pick up the token automatically
+import { APIBase } from "@inst_proserv/toolkit/api";
+const api = new APIBase({ subURL: "/organizations/1" });
+await api.get("/reports");
+```
 
-  def account
-    redirect_with_session_to :accounts_url
-  end
-end
+Without toolkit, send the token back on every request as an `X-Panda-Token` header. See
+[frontend.md](docs/frontend.md) and [sessions.md](docs/sessions.md).
 
-class AccountController < ApplicationController
-  prepend_before_action :forbid_access_if_lacking_session
+Then create an Organization and install the tool:
 
-  def index
-  end
-end
-```
+```bash
+rails db:migrate
+rails "panda_pal:org:new[acme]"
+rails "panda_pal:org:install[acme,https://reports.example.com]"
+```
+
+## Docs.
+
+| Topic | Page |
+| --- | --- |
+| How the pieces fit together, with request flow diagrams | [architecture.md](docs/architecture.md) |
+| Common needs PandaPal already handles | [before-you-build.md](docs/before-you-build.md) |
+| Initializer options, placements, environments, and the private key | [configuration.md](docs/configuration.md) |
+| Engine routes, `lti_nav`, `auto_launch`, and validating launches | [routing-and-launches.md](docs/routing-and-launches.md) |
+| Installing into Canvas, install callbacks, and rake tasks | [installation.md](docs/installation.md) |
+| More than one tool per app | [multiple-tools.md](docs/multiple-tools.md) |
+| Sessions, panda tokens, links, and redirects | [sessions.md](docs/sessions.md) |
+| Organization attributes, settings, and Canvas helpers | [organizations.md](docs/organizations.md) |
+| Tenants, background jobs, and sharding | [multi-tenancy.md](docs/multi-tenancy.md) |
+| LTI roles, Canvas role labels, and ability helpers | [roles-and-abilities.md](docs/roles-and-abilities.md) |
+| Frontend with `@inst_proserv/toolkit` | [frontend.md](docs/frontend.md) |
+| ActionCable | [action-cable.md](docs/action-cable.md) |
+| Deep Linking (LTI 1.3) | [deep-linking.md](docs/deep-linking.md) |
+| Assignment and Grade Services (LTI 1.3) | [ags.md](docs/ags.md) |
+| Grade passback (LTI 1.1) | [grade-passback.md](docs/grade-passback.md) |
+| Scheduled tasks | [task-scheduling.md](docs/task-scheduling.md) |
+| Generated API calls | [api-calls.md](docs/api-calls.md) |
+| Security | [security.md](docs/security.md) |
+| Upgrading between versions | [upgrading.md](docs/upgrading.md) |
+| Working on PandaPal itself | [development.md](docs/development.md) |