tina4ruby 3.13.105 → 3.13.107

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab6d7ce15da93e814204665a8690be0cc2ac58dc1152fa75f050b91fcb0c4f0
-  data.tar.gz: 35fc27eb9d71c17a0049d983d34ed6c1584e014338192e5ace087e5e2bec0746
+  metadata.gz: ab8e75446e8ed41f28be0078b1f16de1e1c0be39ff83cefea98f2a5cc9a78cc2
+  data.tar.gz: b8d786867f6a37c87bbc0e242a615c7df8962ae8fd188d8bb8c381061ecba319
 SHA512:
-  metadata.gz: f2e66595ddcf7eca7d498428149ca38a83caf4871d8d5e29e31ef9d72f7f38f2ed9c3afe638ba2891bf9ffda5b00dbbf54883ddc704bf06787f9f06060b0603b
-  data.tar.gz: c45ab7892609d2be7e0b3dc432a8d54bef9dd8281e3594198b9fa93e9170ceeb60372624c69d49978884ef596cb7ff35eeb720216c4d240a176e372ffa33d803
+  metadata.gz: 7badcea95d972dfbc0171ed400722626d7d6565ff1b9328b1183dcedebe591c2c4fb2510fa67f8851614c4cd866c5b4db021351fdeea1bd016ce639ea1cb185f
+  data.tar.gz: b22a17a9907c81b37f1c22cb2d40e63c77eb62802f9db33ae749a747aa3d5eac5427523b2d5cec0a7ebda2b5d3c62ba88219fd906f0fab62da748a076f4b01e2

data/CHANGELOG.md

@@ -6,6 +6,15 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.107
+
+Feature: RBAC role and permission guards (parity across all four frameworks).
+`role(...)` / `can(...)` route guards read the cryptographically-verified JWT
+`roles` / `permissions` claims — OR within a guard, AND by stacking guards, with
+granted-side wildcards (`posts.*`, `*`) and a legacy singular `role` claim coerced
+to a list. A guarded route implies auth: no or invalid token → 401, authenticated
+but unauthorised → 403; the handler never runs on a miss. Feature 138 / ADR-0058.
+
 ## 3.13.105
 
 Bug release. Route inspection stops touching the app; Firebird's migration
@@ -26,6 +35,65 @@ filename that broke Windows checkouts.
   Firebird driver returns for the `migration_name` column.
 - Uses the atomic sequence table pattern already in place for other engines.
 
+### Queue and ORM audit bugs closed
+
+- **`Model.clear_cache()` cascades to `db.cache_clear()`.** Under both
+  `TINA4_AUTO_CACHING=true` and `TINA4_DB_CACHE=true`, a manual `clear_cache()`
+  used to leave the DB-layer cache holding stale rows (PY-06-22).
+- **`Queue.retry()` revives every dead letter.** The no-arg form used a
+  generator inside `any(...)` and short-circuited after the first success.
+  Now materialised so all N dead letters revive (PY-12-04).
+- **`Job.retry()` unlinks the dead-letter file.** Iterating `dead_letters()`
+  and calling `.retry()` on each used to leave the failed directory carrying
+  every revived job, so the next `dead_letters()` call re-reported them
+  (PY-12-05).
+- **MongoDB `retry_job(id)` searches the dead-letter namespace by data.id,
+  deletes the DL doc, and upserts the original back to pending.** The old
+  filter `{_id, self._topic, "failed"}` could never match a dead letter.
+- **MongoDB `purge(status)` returns `deleted_count`, honours every status, and
+  routes dead/failed/dead_letter aliases to the `.dead_letter` namespace.**
+  Previously returned None and only handled `pending` — via `clear()`, which
+  nuked every doc under the topic regardless of status.
+
+### Test-harness fixes
+
+- **SIGTERM port probe checks both interfaces.** The graceful-shutdown test
+  probed only `0.0.0.0`; on macOS with the framework's default `127.0.0.1`
+  listener holding the port, that bind succeeded and the pre-assertion
+  concluded the port was free. Now probes both interfaces.
+- **MySQL connect-timeout assertion parses the reported elapsed via regex**
+  and checks it against the configured bound instead of the outer clock;
+  mysql-connector's post-abort cleanup adds ~0.7s that the two stopwatches
+  legitimately disagreed on.
+- **AI installer tests sandbox `HOME` per-test.** `install_context()` writes
+  the global skills bundle to `Path.home()/.claude/skills` by design; in the
+  test suite that raced other tests and hit stale root-owned files from prior
+  sudo runs. `monkeypatch.setenv("HOME", ...)` redirects the global install
+  to a throwaway dir.
+
+### Developer skills — announce and 💩
+
+- **Announce before you act.** All four framework developer skills now
+  instruct: say what you are about to do in one line before doing it —
+  Plan / Next / Done. Never write more than two files between announcements.
+  Never run a schema migration, install a dependency, or edit the boot file
+  without a preceding "About to:" line.
+- **💩 stale-skill detection.** All four framework developer skills gained
+  `updated_for_version: 3.13.105` in the frontmatter and a self-check that
+  compares this to the latest published skill version at
+  `https://tina4.com/skills/<name>/version` (never against the project's
+  framework version — the framework version is the developer's call). If a
+  newer skill is available, 💩 rides beside 🤖 on every reply plus a one-time
+  update instruction.
+
+### Doc parity
+
+- `Queue.size()`, `Queue.failed()` and `Queue.dead_letters()` gained matching
+  in-source docstrings across Python, PHP, Ruby and Node: `size("failed")` /
+  `size("dead")` / `size("dead_letter")` are aliases for the dead-letter
+  count (== length of `dead_letters()`); `failed()` lists retryable-but-
+  attempted jobs, counted under `size("pending")`, NOT `size("failed")`.
+
 ## 3.13.103
 
 ### Metrics reports what it can prove

data/lib/tina4/rack_app.rb

@@ -1178,6 +1178,9 @@ module Tina4
         identity = sso.is_a?(Hash) ? sso["identity"] : nil
         if identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
           env["tina4.auth_payload"] = identity
+          deny = rbac_forbidden(route, identity)
+          return deny if deny
+
           return nil
         end
         session_token = session.get("token")
@@ -1207,9 +1210,63 @@ module Tina4
         return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
       end
 
+      # ── RBAC guards (Feature 138): authorization AFTER authentication ──
+      # Auth has passed (401 ruled out above). If the route carries role/
+      # permission guards, the verified payload must satisfy them, else 403.
+      deny = rbac_forbidden(route, env["tina4.auth_payload"])
+      return deny if deny
+
       nil
     end
 
+    # Build a 403 Rack tuple when a route's RBAC guards are not satisfied by the
+    # verified payload, else nil. AND across guard groups, OR within a group.
+    # Roles read the `roles` claim (legacy singular `role` coerced); permissions
+    # read `permissions` with granted-side wildcards. Feature 138 / ADR-0058.
+    def self.rbac_forbidden(route, payload)
+      required_roles = route.respond_to?(:roles) ? Array(route.roles) : []
+      required_perms = route.respond_to?(:perms) ? Array(route.perms) : []
+      return nil if required_roles.empty? && required_perms.empty?
+
+      subject = payload.is_a?(Hash) ? payload : {}
+      roles = _rbac_claim_list(subject, "roles", "role")
+      required_roles.each do |group|
+        return _rbac_forbidden_tuple unless group.any? { |r| roles.include?(r) }
+      end
+      perms = _rbac_claim_list(subject, "permissions", nil)
+      required_perms.each do |group|
+        return _rbac_forbidden_tuple unless group.any? { |req| _rbac_perm_granted(perms, req) }
+      end
+      nil
+    end
+
+    def self._rbac_forbidden_tuple
+      [403, { "content-type" => "application/json" }, [JSON.generate({ error: "Forbidden" })]]
+    end
+
+    # Read a claim as a list of strings; coerce a legacy singular string.
+    def self._rbac_claim_list(subject, key, legacy)
+      out = _rbac_coerce_list(subject[key])
+      out = _rbac_coerce_list(subject[legacy]) if out.empty? && legacy
+      out
+    end
+
+    def self._rbac_coerce_list(val)
+      case val
+      when String then val.empty? ? [] : [val]
+      when Array then val.map(&:to_s).reject(&:empty?)
+      else []
+      end
+    end
+
+    # True if any GRANTED permission satisfies the concrete REQUIRED one.
+    # `*` grants everything; `posts.*` grants `posts.<...>` on the dot boundary.
+    def self._rbac_perm_granted(granted, required)
+      granted.any? do |g|
+        g == "*" || g == required || (g.end_with?(".*") && required.start_with?(g[0..-2]))
+      end
+    end
+
     def self._read_rack_body(env)
       # Route through the capped reader so the running per-chunk upload cap is
       # enforced on the form-token / body path too: an over-limit body raises

data/lib/tina4/router.rb

@@ -8,6 +8,9 @@ module Tina4
     attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
                 :path_regex, :param_names, :template
     attr_accessor :auth_required, :cached
+    # RBAC guard groups (Feature 138 / ADR-0058). Each is an array of arrays:
+    # OR within a group, AND across groups (stacking).
+    attr_reader :roles, :perms
 
     def initialize(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
       @method = method.to_s.upcase.freeze
@@ -23,6 +26,8 @@ module Tina4
       # PY-10-02. Call .no_auth on the route to opt out explicitly.
       @auth_required = %w[POST PUT PATCH DELETE].include?(@method)
       @cached = false
+      @roles = []
+      @perms = []
       @param_names = []
       @path_regex = compile_pattern(@path)
       @param_names.freeze
@@ -42,6 +47,31 @@ module Tina4
       self
     end
 
+    # RBAC: require ONE of the named roles (OR). Reads the verified JWT `roles`
+    # claim. Stack .role/.can for AND. Implies auth. Feature 138 / ADR-0058.
+    # Returns self for chaining: Router.get("/admin") { ... }.role("admin")
+    def role(*names)
+      names = names.flatten.map(&:to_s).reject(&:empty?)
+      unless names.empty?
+        @roles << names
+        @auth_required = true
+      end
+      self
+    end
+
+    # RBAC: require ONE of the named permissions (OR). Reads the verified JWT
+    # `permissions` claim; granted-side wildcards (`posts.*`, `*`) satisfy a
+    # concrete requirement. Stack for AND. Implies auth. Feature 138.
+    # Returns self for chaining: Router.delete("/p") { ... }.can("posts.delete")
+    def can(*permissions)
+      permissions = permissions.flatten.map(&:to_s).reject(&:empty?)
+      unless permissions.empty?
+        @perms << permissions
+        @auth_required = true
+      end
+      self
+    end
+
     # Mark this route as cacheable.
     # Returns self for chaining: Router.get("/path") { ... }.cache
     def cache

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.105"
+  VERSION = "3.13.107"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.105
+  version: 3.13.107
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack