panda_pal 5.19.1 → 5.20.0

data/docs/sessions.md

@@ -0,0 +1,150 @@
+# Sessions and panda tokens.
+
+Browsers increasingly block cookies inside `<iframe>`s, so PandaPal doesn't rely on the Rails session
+cookie. Instead, it keeps sessions in the database (`PandaPal::Session`, one table per tenant) and
+identifies them with a signed **panda token** that your frontend sends back with every request.
+
+## Using the session.
+
+```ruby
+current_session             # The PandaPal::Session for this request, or nil
+current_session[:key]       # Read session data
+current_session[:key] = 1   # Write session data (saved automatically after the action)
+current_session.dig(:a, :b) # Dig into session data
+```
+
+| Helper | Purpose |
+| --- | --- |
+| `current_session` / `current_panda_session` | The session for this request, or `nil`. |
+| `start_panda_session!` | Start a new session. Launches do this for you. |
+| `session_changed?` | `true` if the session changed during the request. |
+| `save_session` | Save the session now. |
+| `valid_session?` | `true` if there's a saved session for the current Organization and tenant. |
+| `forbid_access_if_lacking_session` | `before_action` that renders a 401 unless `valid_session?`. See [security.md](security.md). |
+
+`current_session(create_missing: true)` and `current_session_data` are deprecated. Use
+`start_panda_session!` and `current_session[...]` instead.
+
+Outside a controller, use `PandaPal::Session.for_request(request)` or
+`PandaPal::Session.for_panda_token(token)`.
+
+## Passing the token to the frontend.
+
+Serve the full panda token, `current_session.session_key`, to the page. With
+`@inst_proserv/toolkit`, put it in the `js-env` meta tag as `session_key`, and toolkit sends it for
+you (see [frontend.md](frontend.md#passing-the-environment-to-the-page)):
+
+```erb
+<meta name="js-env" content="<%= { session_key: current_session.session_key }.to_json %>">
+```
+
+PandaPal looks for the token in these places, in order:
+
+1. `X-Panda-Token: <TOKEN>` header
+2. `Authorization: Bearer panda:<TOKEN>` header (note the `panda:` prefix)
+3. `Authorization: token=<TOKEN>` header (legacy, but toolkit `APIBase` still sends it)
+4. `panda_token` param
+5. `session_token` or `session_key` param (legacy, but toolkit `create_href` still uses `session_key`)
+
+Prefer a header. Use the `panda_token` param for non-`GET` HTML `<form>`s (with the full token) and for
+`GET` requests where you can't set a header (with a limited-use token, below).
+
+## Token format.
+
+A **full-key panda token** (`session_key`) looks like this:
+
+```
+<Base64({ v: 1, o: ORG ID, s: SESSION ID, typ: "KEY" })>.<SESSION SECRET>
+```
+
+A **limited-use panda token** carries a type and is signed with the session secret instead of
+containing it:
+
+```
+<Base64({ v: 1, o: ORG ID, s: SESSION ID, typ: TYPE, ... })>.<HMAC(SESSION SECRET, Base64(...))>
+```
+
+| `typ` | Extra fields | Behavior |
+| --- | --- | --- |
+| `T-NONCE` | `nnc` | Single use. Also expires as soon as another `T-NONCE` token is minted for the session. |
+| `T-IP` | `ip`, `exp` | Only valid from the IP address it was minted for. |
+| `T-EXP` | `exp` | Valid until it expires. |
+| `T-URI` | `usig` | Valid for `GET`ting exactly one URL (path and query). `T-URL` is accepted as an alias. Toolkit `signURL` mints these in the browser (see [frontend.md](frontend.md#minting-panda-tokens-in-the-browser)). |
+
+Any limited-use token may include `exp`, an ISO 8601 expiration timestamp.
+
+## Links and redirects.
+
+Each page navigation needs its own token. Use these helpers:
+
+```ruby
+redirect_with_session_to :somewhere_else_url, other_param: 1
+link_to "Name", url_with_session(:somewhere_else_path, arg, kwarg: 1)
+link_with_session_to :somewhere_else_path
+session_url_for(controller: 'reports', action: 'show')
+
+# Or add the token yourself
+redirect_to somewhere_else_path(panda_token: link_nonce)
+```
+
+These add `panda_token:` (and, for older apps whose routes need it, `organization_id:`). In
+development they use the full session key, so reloads keep working.
+
+`link_nonce` mints one limited-use token per type per request. The default type is `T-NONCE`. Change
+it per call or per controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  link_nonce_type "T-IP" # or "T-NONCE", "T-EXP"
+
+  # Lifetime of T-IP and T-EXP tokens. Defaults to 15.
+  def session_expiration_period_minutes
+    120
+  end
+end
+
+link_nonce(type: "T-EXP")
+link_nonce(report_url, type: :url) # A T-URI token for one URL
+```
+
+To mint a `T-URI` token, pass `type: :url` (or `"T-URL"`). `type: "T-URI"` raises
+`Unsupported link_nonce_type`.
+
+The older names `:nonce`, `:fixed_ip`, and `:expiring` still work as aliases.
+
+## Reading launch data.
+
+| Method | Returns |
+| --- | --- |
+| `launch_params` | The decoded LTI 1.3 `id_token`, or the LTI 1.0 launch params. Also available as `lti_launch_params` in controllers. |
+| `custom_lti_params` | The custom params, from either LTI version. |
+| `get_lti_cust_param(key, default:)` | One custom param. See [configuration.md](configuration.md#custom-params). |
+| `lti_launch_placement` | The placement that was launched. |
+| `lti_tool` | Which [tool](multiple-tools.md) was launched. |
+| `lti_platform` | The LTI 1.3 platform. |
+| `canvas_user_id` | The `canvas_user_id` custom param. |
+| `user` | `User.find_by(canvas_id: canvas_user_id)`, if the app has a `User` model. |
+| `ags_client` | An [AGS](ags.md) client for this launch. |
+| `cache(key) { ... }` | Memoize a value in the session. A `nil` result is cached too. |
+
+Roles have their own page: [roles-and-abilities.md](roles-and-abilities.md).
+
+## Persisting the session.
+
+An `after_action` saves the session automatically. It's set to run last. If another callback needs
+to change the session after that, `skip_after_action :auto_save_session` and save it yourself.
+
+## Session cleanup.
+
+Old sessions pile up. If `sidekiq-scheduler` is set up (see [task-scheduling.md](task-scheduling.md)),
+each Organization deletes sessions not updated in the last week, every day at 3:00. Otherwise,
+schedule `rake panda_pal:clean_sessions` to run regularly (weekly is fine).
+
+## Safari.
+
+Safari blocks cookies in `<iframe>`s unless the site already set one outside the frame. Panda tokens
+avoid that problem. Keep these rules in mind:
+
+1. Use `redirect_with_session_to` (or another helper above) when you redirect.
+2. Send the token in a header on API calls.
+3. Add a token to every `link_to` in multi-page apps.

data/docs/task-scheduling.md

@@ -0,0 +1,49 @@
+# Task scheduling.
+
+When `sidekiq-scheduler` is loaded, Organizations can declare cron tasks. PandaPal registers one
+schedule per Organization per task, and runs each task inside that Organization's tenant.
+
+```ruby
+# app/models/organization_extension.rb
+module OrganizationExtension
+  extend ActiveSupport::Concern
+
+  included do
+    # Calls CanvasSyncStarterWorker.perform_async on the cron schedule
+    scheduled_task '0 15 05 * * *', :identifier, worker: CanvasSyncStarterWorker
+
+    # Calls the Organization method `organization_method_and_identifier`
+    scheduled_task '0 15 05 * * *', :organization_method_and_identifier
+
+    # Calls the same method on more than one schedule
+    scheduled_task '0 15 05 * * *', :other_identifier, worker: :organization_method
+
+    # Runs a block (in the context of the Organization)
+    scheduled_task '0 15 05 * * *', :block_identifier do
+      # Do stuff
+    end
+
+    # Computes the schedule with a Proc (in the context of the Organization)
+    scheduled_task -> { settings[:cron] }, :proc_identifier
+
+    # Uses an explicit timezone, and a non-default Sidekiq queue
+    scheduled_task '0 15 05 * * * America/Denver', :tz_identifier, worker: :organization_method, queue: 'low'
+  end
+end
+```
+
+## Rules.
+
+- Identifiers must be unique. If you leave one out (`nil`), PandaPal makes one from the line number.
+- If the cron string has no timezone, PandaPal appends `settings[:timezone]`, or else
+  `settings[:canvas][:root_account_timezone]`, when either is set.
+- `settings[:task_schedules][:identifier]` overrides the schedule for one Organization. Set it to
+  `false` to turn the task off.
+- `task_scheduled?(:identifier)` and `remove_scheduled_task(:identifier)` check for and remove tasks
+  declared elsewhere, such as by a gem.
+- Schedules are registered but turned off in development.
+- Schedules re-sync each time the Sidekiq server boots or reloads, and schedules for deleted
+  Organizations are removed.
+
+PandaPal declares one task itself: `clean_old_sessions`, which runs every day at 3:00 (see
+[sessions.md](sessions.md#session-cleanup)).

data/docs/upgrading.md

@@ -0,0 +1,69 @@
+# Upgrading.
+
+PandaPal ships migrations. Apps pick them up automatically, so run `rails db:migrate` after every
+upgrade. Apartment runs the per-tenant migrations in each Organization's schema.
+
+## To 5.19.1.
+
+PandaPal no longer hooks CableRoom. The hook only ever applied to the CableRoom beta. If your app
+still relies on it, add it yourself:
+
+```ruby
+CableRoom::Room::Base.around_work do |room, blk|
+  Apartment::Tenant.with_lazy_tenant(room.tenant, &blk)
+end
+```
+
+## To 5.19.
+
+- **Migrations:** `create_panda_pal_lti_registrations` (in `public`) and
+  `add_tool_to_panda_pal_sessions` (per tenant).
+- **Multiple tools:** new and opt-in. Single-tool apps don't need to change. See
+  [multiple-tools.md](multiple-tools.md).
+- **`install_lti` default context** is now `:org_account` (the Organization's `canvas_account_id`)
+  instead of the API token's root account. Pass `context: :root_account` to keep the old behavior.
+
+## To 5.16.
+
+LTI 1.3 Deep Linking. Every content item must include `launch_type` in its `custom` hash. See
+[deep-linking.md](deep-linking.md).
+
+## To 5.14.
+
+- **Migration:** renames `panda_pal_sessions.session_key` to `session_secret`.
+- **Sessions moved into tenant schemas.** `PandaPal::Session` is no longer an Apartment excluded
+  model, so existing sessions aren't found after the upgrade. Users need to launch again.
+- **New panda token format.** `session_key` now returns a full-key panda token, and link tokens are
+  limited-use panda tokens. Old-style `session_key` and `session_token` params still work. See
+  [sessions.md](sessions.md).
+
+## To 5.13.
+
+- Use `current_session[:key]` instead of `current_session_data[:key]`.
+- Use `start_panda_session!` instead of `current_session(create_missing: true)`.
+- In launch controllers, put `before_action :validate_launch!` before `around_action :switch_tenant`.
+
+## To 5.12.
+
+Adds optional [sharding](multi-tenancy.md#sharding), and requires `ros-apartment ~> 3.0`.
+
+## From 4 to 5.
+
+If your tool follows a standard pattern (like `canvas_group_enrollment`), you shouldn't need to
+change anything. If your launch controller redirects, make sure it uses `redirect_with_session_to`.
+See [routing-and-launches.md](routing-and-launches.md#validating-launches-yourself) for a launch
+controller.
+
+## To 3.
+
+Version 3 encrypts `Organization#settings` with the app's `secret_key_base` (see
+[organizations.md](organizations.md#encryption)).
+
+1. Save your existing settings somewhere safe.
+2. Make sure `secret_key_base` is set to a stable value that isn't committed in plain text. If it's
+   lost, the settings can't be decrypted.
+3. Undo any encryption you applied to settings yourself. The migration expects plain settings.
+4. Run `rails db:migrate`.
+5. In the console, check that `PandaPal::Organization.first.settings` shows decrypted settings.
+
+To roll back, run `rails db:rollback STEP=2` and pin PandaPal below 3.

data/lib/panda_pal/version.rb

@@ -1,3 +1,3 @@
 module PandaPal
-  VERSION = '5.19.1'
+  VERSION = '5.20.0'
 end

data/panda_pal.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.summary     = "LTI mountable engine"
   s.license     = "MIT"
 
-  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "AGS.md", "panda_pal.gemspec"]
+  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md", "docs/**/*", "panda_pal.gemspec"]
   # s.test_files = Dir["spec/**/*"].reject{|f| f =~ /\/log\//}
 
   s.add_dependency "rails", ">= 4.2"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: panda_pal
 version: !ruby/object:Gem::Version
-  version: 5.19.1
+  version: 5.20.0
 platform: ruby
 authors:
 - Instructure CustomDev
@@ -147,7 +147,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AGS.md
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -200,6 +199,26 @@ files:
 - db/migrate/20250401214421_rename_session_session_key.rb
 - db/migrate/20261006000000_create_panda_pal_lti_registrations.rb
 - db/migrate/20261006000001_add_tool_to_panda_pal_sessions.rb
+- docs/action-cable.md
+- docs/ags.md
+- docs/api-calls.md
+- docs/architecture.md
+- docs/before-you-build.md
+- docs/configuration.md
+- docs/deep-linking.md
+- docs/development.md
+- docs/frontend.md
+- docs/grade-passback.md
+- docs/installation.md
+- docs/multi-tenancy.md
+- docs/multiple-tools.md
+- docs/organizations.md
+- docs/roles-and-abilities.md
+- docs/routing-and-launches.md
+- docs/security.md
+- docs/sessions.md
+- docs/task-scheduling.md
+- docs/upgrading.md
 - lib/panda_pal.rb
 - lib/panda_pal/concerns/ability_helper.rb
 - lib/panda_pal/engine.rb