feat(*): revoke cookie sessions by subject and sid

README.md

@@ -200,6 +200,8 @@ http {
         * [session.start](#sessionstart)
         * [session.logout](#sessionlogout)
         * [session.destroy](#sessiondestroy)
+        * [session.revoke_subject](#sessionrevoke_subject)
+        * [session.revoke_sid](#sessionrevoke_sid)
     * [Instance Methods](#instance-methods)
         * [session:open](#sessionopen-1)
         * [session:save](#sessionsave)
@@ -216,6 +218,8 @@ http {
         * [session:get_audience](#sessionget_audience)
         * [session:set_subject](#sessionset_subject)
         * [session:get_subject](#sessionget_subject)
+        * [session:set_sid](#sessionset_sid)
+        * [session:get_sid](#sessionget_sid)
         * [session:get_property](#sessionget_property)
         * [session:set_remember](#sessionset_remember)
         * [session:get_remember](#sessionget_remember)
@@ -330,7 +334,7 @@ Here are the possible session configuration options:
 | `storage`                   |    `nil`     | Storage is responsible of storing session data, use `nil` or `"cookie"` (data is stored in cookie), `"dshm"`, `"file"`, `"memcached"`, `"mysql"`, `"postgres"`, `"redis"`, or `"shm"`, or give a name of custom module (`"custom-storage"`), or a `table` that implements session storage interface. |
 | `revocation`                |    `nil`     | Storage used for cookie session revocation records. Use `nil` or `false` to disable, a storage name such as `"shm"`, `"redis"`, `"mysql"`, or `"postgres"`, a custom storage module name, or a storage `table` with `set`/`get` methods.                                                                |
 | `revocation_fail_mode`          |   `"open"`   | Behavior when the revocation store is unreachable, use `"open"` (treat as not revoked) or `"closed"` (reject the session).                                                                                                                                                                           |
-| `revocation_cache_ttl`          |     `5`      | Worker-local cache TTL for successful revocation lookups (`true`/`false`) (in seconds). Set to `0` to disable. This is the maximum stale window before a worker observes a revocation written elsewhere.                                                                                             |
+| `revocation_cache_ttl`          |     `5`      | Worker-local cache TTL for successful revocation lookups (in seconds). Set to `0` to disable. This is the maximum stale window before a worker observes a revocation written elsewhere.                                                                                             |
 | `revocation_error_cache_ttl`    |     `5`      | Worker-local cache TTL for revocation store errors (in seconds). Set to `0` to disable. `"open"` caches not-revoked; `"closed"` caches the error.                                                                                                                                                  |
 | `dshm`                      |    `nil`     | Configuration for dshm storage, e.g. `{ prefix = "sessions" }` (see below)                                                                                                                                                                                                                           |
 | `file`                      |    `nil`     | Configuration for file storage, e.g. `{ path = "/tmp", suffix = "session" }` (see below)                                                                                                                                                                                                             |
@@ -380,6 +384,41 @@ is cached for the same identifier under `revocation_error_cache_ttl`, so the
 next lookup sees it instead of the store. The revocation mark is a lightweight
 sentinel; no session payload is stored.
 
+Sessions can also be revoked by their subject (`session:set_subject`) or by an
+identity provider session id (`session:set_sid`, e.g. the OpenID Connect `sid`
+claim). `session.revoke_subject(subject, ttl, configuration)` and
+`session.revoke_sid(sid, ttl, configuration)` write a mark without an open
+session; sessions carrying the value that were created at or before the mark
+are rejected on `session:open`, later ones are not. `ttl` must cover the
+sessions' absolute timeout (`remember_absolute_timeout` when remember cookies
+are used). Subject marks use `subject:` plus `hash_subject(subject)`; sid marks
+use `sid:` plus the sid. Both keys go through `hash_storage_key`. Enable hashing
+when the values may contain personal data. Both functions always return write errors; `revocation_fail_mode`
+applies to `session:open` and `session:destroy` only.
+
+Subject and sid revocation lookups cache the timestamp, which is compared with
+each session's creation time. Cache entries are isolated by revocation storage
+instance. A successful revocation updates that instance's local worker cache
+immediately. Other workers or storage instances observe it when their cached lookup expires;
+set `revocation_cache_ttl = 0` to check the store on every request. Store errors
+still follow `revocation_error_cache_ttl` and `revocation_fail_mode`.
+
+These marks are shared by sessions using the same cookie name and revocation
+store namespace. Applications using multiple identity providers must qualify
+their subject and sid values with the issuer consistently when setting and
+revoking them. The sid is carried in the encrypted session payload; it is not
+added to the subject/audience indexes maintained by `store_metadata`. These
+APIs use revocation marks rather than enumerating or deleting stored sessions.
+
+```lua
+-- On login
+session:set_subject(id_token.sub)
+session:set_sid(id_token.sid)
+
+-- In a back-channel logout handler, without an open session
+require("resty.session").revoke_sid(logout_token.sid, 86400)
+```
+
 Use `revocation_fail_mode` to control behavior when the storage is unavailable:
 
 - `"open"` (default): log a warning and treat the session as not revoked.
@@ -897,6 +936,40 @@ local ok, err, exists, destroyed = require "resty.session".destroy({
 See [configuration](#configuration) for possible configuration settings.
 
 
+### session.revoke_subject
+
+**syntax:** *ok, err = session.revoke_subject(subject, ttl, configuration)*
+
+It marks a subject (see `session:set_subject`) as revoked without an open
+session; sessions carrying the subject that were created at or before the mark
+are rejected on `session:open`. `ttl` (in seconds) must cover the sessions'
+absolute timeout (`remember_absolute_timeout` when remember cookies are used).
+Write errors are always returned.
+
+```lua
+local ok, err = require "resty.session".revoke_subject("john@doe.com", 86400)
+```
+
+See [configuration](#configuration) for possible configuration settings.
+
+
+### session.revoke_sid
+
+**syntax:** *ok, err = session.revoke_sid(sid, ttl, configuration)*
+
+It marks an identity provider session id (see `session:set_sid`) as revoked
+without an open session; sessions carrying the sid that were created at or
+before the mark are rejected on `session:open`. `ttl` (in seconds) must cover
+the sessions' absolute timeout (`remember_absolute_timeout` when remember
+cookies are used). Write errors are always returned.
+
+```lua
+local ok, err = require "resty.session".revoke_sid(logout_token.sid, 86400)
+```
+
+See [configuration](#configuration) for possible configuration settings.
+
+
 ## Instance Methods
 
 ### session:open
@@ -1130,6 +1203,33 @@ end
 ```
 
 
+### session:set_sid
+
+**syntax:** *session:set_sid(sid)*
+
+Set an identity provider session id (e.g. the OpenID Connect `sid` claim) so
+that `session.revoke_sid` can revoke the session by it.
+
+```lua
+local session = require "resty.session".new()
+session:set_sid(id_token.sid)
+```
+
+
+### session:get_sid
+
+**syntax:** *sid = session:get_sid()*
+
+Get the identity provider session id.
+
+```lua
+local session, err, exists = require "resty.session".open()
+if exists then
+  local sid = session:get_sid()
+end
+```
+
+
 ### session:get_property
 
 **syntax:** *value = session:get_property(name)*