audioproxy-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ae5b13fb6a5adc46eb6e975cdc682cf27244c316624891072a31f2447a1257
-  data.tar.gz: fe648c6c0cc0552d30dfd4cdcdf7878ebf68fdb7961c7363b6bf2b62725c50bf
+  metadata.gz: e2c006e53f916a943195a3887a184f3fa141e086227ecc03919199a335f32df7
+  data.tar.gz: 110cc6e5eb81d7fb34d3688b2c56953d822792157a27e9669d1f25c17b86d1e1
 SHA512:
-  metadata.gz: 2c46a5ef917dca8990e4d565cd14b283a0c0592b36ca95e4cd6e81cb4fe06d2bd3ac823353e22efb5486a0d41749f0631c32faf45f4fef18b3866dba182fedfa
-  data.tar.gz: 878b41e27ab71a8b4e69cc8d6d0f27c1a5d79e011307508f32d8a589e99397710a2bbca8fa71df979d42c09560690914fd5f8f188332ebea096a1c03c7402097
+  metadata.gz: 8c506590e9344488d0cc4222aec06ae92315628e685526fd8a7b2c1ab7692997dadba3b84294d7bcf1f1c4d653c5b6b8320e695c88ce86d571a83d0e5561ab4b
+  data.tar.gz: a1a54ccb83749af4b65339ba42d29c11ae76d1cc914376461388dcf70707febf0771159df327b54b26ad00692371b5980829e8b7031f1077235ab31546168dff

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.2.0
+
+* Expiring URLs. `url_for` and every view helper accept `expires_in:` (a duration or Integer
+  seconds from now) and `expires_at:` (the instant itself), mutually exclusive, rendering the
+  proxy's `exp:` option. `config.expires_in` sets a global default; a per-call `expires_in: nil`
+  opts one URL out of it.
+
+  Because `exp` is a request option on the proxy rather than a variant option, it is signed but
+  excluded from the cache key: minting a fresh short-lived URL on every render costs no extra
+  render and no extra cached variant at the origin.
+
+  Every input that would produce a valid-looking URL the proxy refuses raises at the call site
+  instead: both keywords together, a non-positive window, an `expires_at` at or before now, a
+  fractional duration, a millisecond timestamp, a `Date`, and `exp:` written as a plain option key
+  or in `default_options`.
+
+  Requires audioproxy 0.6.0 or newer, the release that added the `exp` option. Older proxies
+  answer `exp:` with a `422`. Every other feature in this gem still works against 0.5.0.
+
+* `Audioproxy::Signer` is unchanged, and so is the isolation test that pins its extraction seam:
+  `exp` is ordinary path bytes to the signer.
+
 ## 0.1.0
 
 First release.

data/README.md

@@ -12,6 +12,8 @@ Full Rails is a development dependency only. `require "audioproxy"` works in a p
 
 Core signing and typed options work, in both the proxy's short spellings and their aliases, as do the Railtie's credentials/ENV wiring, the view helpers — URL, `<audio>` tag and preload hint — and ActiveStorage resolution for the S3 and Disk services. Blobs on any other service raise; see [ActiveStorage](#activestorage) for what to do about that.
 
+[Expiring URLs](#expiring-urls) work too, against [audioproxy 0.6.0 or newer](#minimum-proxy-version). One caveat worth knowing either way: everything in this gem is verified against the proxy's published signature vectors and its source, but no test here has yet asked a running proxy whether a generated URL is accepted. That round-trip is the next change.
+
 ## Installation
 
 ```ruby
@@ -63,17 +65,24 @@ Where to go from here:
 ```ruby
 Audioproxy.configure do |config|
   config.endpoint = "https://audio.example.com"   # absolute http(s) URL, path prefix allowed
-  config.key      = ENV["AUDIOPROXY_KEY"]         # hex string, decoded at assignment
-  config.salt     = ENV["AUDIOPROXY_SALT"]        # hex string, decoded at assignment
+  config.key      = ENV["AP_KEY"]                 # hex string, decoded at assignment
+  config.salt     = ENV["AP_SALT"]                # hex string, decoded at assignment
 end
 ```
 
+Writing this out is optional. Under Rails the railtie already reads `audioproxy:` from credentials
+and `AP_ENDPOINT`, `AP_KEY`, `AP_SALT` and `AP_ALLOW_INSECURE` from the environment, so an app that
+uses either needs no initializer at all; see [ENV parity with the proxy](#env-parity-with-the-proxy)
+and [Rails](#rails). Configure by hand when you want to override those, or when there is no Rails.
+
 `key` and `salt` are hex strings, validated eagerly: a typo raises `ArgumentError` at boot rather than in a mailer six hours later. The endpoint must be an absolute `http`/`https` URL. A path prefix (`https://cdn.example.com/audio`, for a CDN routing that prefix to the proxy) is supported and does not disturb signing, because the signature covers only the path after the signature segment. Userinfo, a query and a fragment are rejected: a base URL is scheme, host and optional path prefix, and `https://user:pass@host` would put credentials into every URL you generate.
 
 The gem is deliberately strict about input, because the alternative is not an exception but a 403 from the proxy at request time, far from the call that caused it. A `nil` or non-String source, a `default_options` value that is not a Hash, an unrecognized option key, and a `raw:` string bracketed by `/` all raise.
 
 In development, `config.unsigned = true` emits the literal `insecure` signature segment instead of an HMAC, matching the proxy's `AP_ALLOW_INSECURE` mode. No key or salt is needed in that mode.
 
+`config.default_options` sets options applied to every URL, and `config.expires_in` sets a global expiry; both are covered in [Options](#options) and [Expiring URLs](#expiring-urls).
+
 ## Generating URLs
 
 ```ruby
@@ -207,6 +216,66 @@ Audioproxy.url_for("local://a.wav", unsigned: true)
 
 `Audioproxy.url_for` is Rails-free: it works in jobs, mailers, serializers, and plain Ruby scripts.
 
+## Expiring URLs
+
+A signed URL is otherwise an eternal bearer capability: the signature covers the path and nothing else, so a leaked URL works forever and the only revocation is rotating the key, which kills every URL you ever issued. `expires_in:` and `expires_at:` time-box one URL without touching any other.
+
+```ruby
+Audioproxy.url_for(source, format: "opus", expires_in: 1.hour)
+# => ".../f:opus/exp:1767229200/enc/..."
+
+Audioproxy.url_for(source, format: "opus", expires_at: 1.day.from_now)
+```
+
+`expires_in:` takes an ActiveSupport duration or a positive Integer of seconds, added to the current time when the URL is built. `expires_at:` takes a `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, or an Integer unix timestamp, used as the instant itself. They are mutually exclusive. Past the expiry the proxy answers `410 Gone`, checked after the signature and before it touches your storage, so an expired URL costs a render of nothing.
+
+Every view helper forwards both keywords:
+
+```erb
+<%= audioproxy_audio_tag @recording.audio, format: "opus", expires_in: 30.minutes, html: { controls: true } %>
+```
+
+### Rotation is free at the origin
+
+On the proxy's side `exp` is a *request* option: it is signed as part of the path, but excluded from the cache key and from the ffmpeg arguments. Two URLs that differ only in their expiry are one variant and one render, so minting a fresh short-lived URL on every page render costs nothing at the origin. Each user can carry their own URL while all of them share one cached variant.
+
+That guarantee is origin-side only. Two URLs differing in `exp` are still two distinct URLs to a CDN, which stores them separately, so a short expiry on a heavily shared page trades edge cache entries for revocability. That is the trade whichever syntax carries the expiry, not a cost of this spelling.
+
+### A global default
+
+```ruby
+Audioproxy.configure { |c| c.expires_in = 1.hour }
+```
+
+`config.expires_in` is `nil` by default, and `nil` means URLs carry no expiry at all. When it is set, every URL this process builds carries one, measured from each call rather than from boot. A per-call `expires_in:`/`expires_at:` overrides it, and a per-call `expires_in: nil` opts a single URL out:
+
+```ruby
+Audioproxy.url_for(source, expires_in: 5.minutes)   # overrides the default
+Audioproxy.url_for(source, expires_in: nil)         # no expiry on this one
+```
+
+It is a duration rather than an instant on purpose: an absolute timestamp applied process-globally would expire every URL the app will ever mint at the same second. There is no `config.expires_at`, and `exp:` is refused in `default_options` for the same reason.
+
+### What raises, and why
+
+An expiry the proxy will not accept produces a URL that looks perfectly valid and fails at request time, far from the call that built it. So every one of these raises `ArgumentError` at the call site instead:
+
+```ruby
+Audioproxy.url_for(source, expires_in: 1.hour, expires_at: 1.day.from_now)  # both keywords
+Audioproxy.url_for(source, expires_in: 0)                                   # non-positive window
+Audioproxy.url_for(source, expires_at: 1.hour.ago)                          # already dead
+Audioproxy.url_for(source, expires_in: 1.5.seconds)                         # not whole seconds
+Audioproxy.url_for(source, expires_at: 1.hour.from_now.to_i * 1000)         # milliseconds
+Audioproxy.url_for(source, expires_at: Date.tomorrow)                       # local midnight, not an instant
+Audioproxy.url_for(source, exp: 1767229200)                                 # use the keywords
+```
+
+An expiry composes with `raw:` rather than replacing it, since `exp` is not a variant option: `url_for(source, raw: "f:opus/br:96", expires_in: 1.hour)` renders `f:opus/br:96/exp:…`. A `raw:` string that already spells out its own `exp:` raises when an expiry is also in force, because the proxy rejects a duplicated option and, under a global default, that is a failure you never wrote.
+
+### Minimum proxy version
+
+Expiring URLs need **audioproxy 0.6.0 or newer**, the release that added the `exp` option. `0.5.0` and earlier answer `exp:` with a `422 invalid option`. That failure is loud and server-side, so pointing this gem at an older proxy breaks visibly rather than silently ignoring the expiry, and every other feature here works against `0.5.0` unchanged. This gem does not version-sniff.
+
 ## Rails
 
 In a Rails app there is nothing to mount and, usually, nothing to write: a railtie reads your configuration and mixes the view helpers into ActionView.

data/lib/audioproxy/config.rb

@@ -1,6 +1,7 @@
 require "uri"
 require "active_support/core_ext/hash/keys"
 require "audioproxy/options"
+require "audioproxy/expiry"
 
 module Audioproxy
   # Raised when a URL is requested but the configuration cannot produce one the
@@ -18,9 +19,16 @@ module Audioproxy
     # spelled-out aliases, plus the pre-rendered +raw:+ escape hatch. An
     # unrecognized key is a typo, and a typo that is silently dropped emits a
     # valid URL for the wrong variant.
-    OPTION_KEYS = ([ :raw ] + Options::KEYS + Options::ALIASES.values).uniq.freeze
-
-    attr_reader :endpoint, :key, :salt, :default_options
+    #
+    # exp is subtracted deliberately (D1). It is an absolute instant, so a
+    # default would expire every URL the process ever mints at one second, and
+    # it would skip the validation the keywords run. +expires_in+ below is the
+    # default that makes sense.
+    EXPIRY_KEYS = (Options::REQUEST_KEYS + Options::REQUEST_KEYS.filter_map { |key| Options::ALIASES[key] })
+      .uniq.freeze
+    OPTION_KEYS = (([ :raw ] + Options::KEYS + Options::ALIASES.values).uniq - EXPIRY_KEYS).freeze
+
+    attr_reader :endpoint, :key, :salt, :default_options, :expires_in
     attr_accessor :unsigned
 
     def initialize
@@ -29,6 +37,18 @@ module Audioproxy
       @salt = nil
       @unsigned = false
       @default_options = {}
+      @expires_in = nil
+    end
+
+    # How long a URL stays valid, applied to every URL this process builds.
+    # nil — the default — means URLs carry no expiry and remain the eternal
+    # bearer capabilities they have always been.
+    #
+    # A duration rather than an instant, and validated here so a typo fails at
+    # boot rather than in a mailer. A call site overrides it with its own
+    # +expires_in:+/+expires_at:+, or opts one URL out with +expires_in: nil+.
+    def expires_in=(value)
+      @expires_in = value.nil? ? nil : Expiry.seconds(value, source: "config expires_in")
     end
 
     # Full base URL of the proxy: scheme + host, optionally with a path prefix
@@ -128,6 +148,15 @@ module Audioproxy
 
         normalized = value.symbolize_keys
 
+        # Before the generic unknown-key message, which would report exp as a
+        # typo when it is a real option reached a different way (D1).
+        unless (expiry = normalized.keys & EXPIRY_KEYS).empty?
+          raise ArgumentError,
+            "Audioproxy config default_options must not carry #{expiry.first.inspect}: it is an " \
+            "absolute instant, so every URL this process builds would expire at the same second. " \
+            "Set config.expires_in to a duration instead, or pass expires_in:/expires_at: per call"
+        end
+
         # Not assert_valid_keys: its message lists the aliases among the valid
         # keys without saying they are aliases, so a caller who guessed
         # bit_rate: sees :bitrate in a flat list and cannot tell the two
@@ -135,7 +164,7 @@ module Audioproxy
         unless (unknown = normalized.keys - OPTION_KEYS).empty?
           raise ArgumentError,
             "unknown Audioproxy option #{unknown.first.inspect} in default_options; known keys are " \
-            "#{([ :raw ] + Options::KEYS).join(", ")}, each also accepted as its spelled-out alias " \
+            "#{([ :raw ] + Options::KEYS - EXPIRY_KEYS).join(", ")}, each also accepted as its spelled-out alias " \
             "(#{Options::ALIASES[:br]}, #{Options::ALIASES[:sr]}, #{Options::ALIASES[:pk_fmt]}, …)"
         end
 

data/lib/audioproxy/expiry.rb

@@ -0,0 +1,160 @@
+require "date"
+require "active_support/duration"
+require "audioproxy/options"
+
+module Audioproxy
+  # Turns the two Rails-shaped expiry spellings — +expires_in: 1.hour+ and
+  # +expires_at: some_time+ — into the single Integer of unix seconds the
+  # proxy's +exp+ option takes.
+  #
+  # Every method here raises rather than coercing. The proxy answers a URL whose
+  # +exp+ has passed with 410 and one out of bounds with 422, both at request
+  # time and neither anywhere near the call that built it, so an input this
+  # module cannot read exactly is an error at the call site (D5).
+  module Expiry
+    # Sentinel for "this keyword was not passed". nil cannot do the job: it is
+    # the documented per-call opt-out from a configured default (D6).
+    UNSET = Object.new.freeze
+
+    class << self
+      # The +exp+ value for one URL, or nil for no expiry at all. +now+ is
+      # supplied by the caller and read once per URL, so the arithmetic below
+      # and the past-check cannot straddle a second boundary (D4).
+      def timestamp(expires_in:, expires_at:, default_expires_in:, now:)
+        if given?(expires_in) && given?(expires_at)
+          raise ArgumentError,
+            "Audioproxy url_for takes either expires_in: or expires_at:, not both; " \
+            "expires_in: is a window from now, expires_at: is the instant itself"
+        end
+
+        return at(expires_at, now: now) if given?(expires_at)
+        return within(expires_in, now: now, source: "url_for expires_in:") if given?(expires_in)
+        return nil if default_expires_in.nil?
+
+        # Already validated at assignment, so this is arithmetic and nothing
+        # else — but it still goes through the bound check that `within` runs.
+        within(default_expires_in, now: now, source: "config expires_in")
+      end
+
+      # A window of whole positive seconds, as an Integer. Shared by the keyword
+      # and by Config#expires_in= so that a value accepted at boot is exactly a
+      # value accepted per call.
+      def seconds(value, source:)
+        case value
+        # #value is the exact number of seconds the Duration stands for (3600
+        # for 1.hour), and it stays an Integer where the caller wrote one, so a
+        # far-future window does not lose digits to a double on the way past.
+        when ActiveSupport::Duration then whole_seconds(value, value.value, source: source)
+        when Integer then value
+        else
+          raise ArgumentError,
+            "Audioproxy #{source} must be an ActiveSupport::Duration or an Integer of seconds, " \
+            "got #{value.inspect}"
+        end.tap do |seconds|
+          unless seconds.positive?
+            raise ArgumentError,
+              "Audioproxy #{source} must be a positive number of seconds, got #{value.inspect}; " \
+              "a window of #{seconds} mints a URL that is already expired"
+          end
+        end
+      end
+
+      private
+        def given?(value)
+          !value.equal?(UNSET)
+        end
+
+        def within(value, now:, source:)
+          return nil if value.nil?
+
+          window = seconds(value, source: source)
+
+          bounded(now + window, source: source, window: window)
+        end
+
+        def at(value, now:)
+          return nil if value.nil?
+
+          seconds = bounded(unix_seconds(value), source: "url_for expires_at:")
+
+          # The proxy's own check is `now > exp`, so the second exp names is
+          # still served and only a strictly-past value is dead on arrival.
+          # Refusing equality too costs one second and makes the rule statable
+          # as "expires_at: must be in the future" (D5).
+          unless seconds > now
+            raise ArgumentError,
+              "Audioproxy url_for expires_at: must be in the future, got #{value.inspect} " \
+              "(#{seconds}, and it is now #{now}); the proxy would answer that URL with 410"
+          end
+
+          seconds
+        end
+
+        # Time, DateTime and ActiveSupport::TimeWithZone, or an Integer already
+        # in unix seconds.
+        #
+        # is_a? rather than case/when, and the reason is narrower than the one
+        # Options gives for Duration. TimeWithZone overrides is_a? to answer
+        # truthfully about what it stands for, and Module#=== ignores that
+        # override — but ActiveSupport patches Time.=== to cover the gap
+        # (core_ext/time/calculations.rb), so under full Rails a case/when Time
+        # matches a TimeWithZone after all.
+        #
+        # It matches only where that core_ext is loaded, and this file does not
+        # require it: after a bare `require "audioproxy"`, Time.=== is still
+        # Module's. Since url_for is documented as usable with no Rails loaded,
+        # case/when here would accept a TimeWithZone in an app and reject it in
+        # a plain Ruby script. is_a? is TimeWithZone's own override and needs
+        # nothing else loaded, so it answers the same in both.
+        #
+        # Date is not on the list. Date#to_time is local midnight, so the same
+        # `expires_at: Date.tomorrow` means a different instant on every machine
+        # that renders it.
+        def unix_seconds(value)
+          return value if value.is_a?(Integer)
+
+          unless value.is_a?(Time) || value.is_a?(DateTime)
+            raise ArgumentError,
+              "Audioproxy url_for expires_at: must be a Time, DateTime, " \
+              "ActiveSupport::TimeWithZone or an Integer of unix seconds, got #{value.class}" \
+              "#{" (a Date is local midnight, which is a different instant per machine; pass a Time)" if value.is_a?(Date)}"
+          end
+
+          # Truncates sub-second, which moves the expiry at most one second
+          # earlier — the fail-safe direction.
+          value.to_time.to_i
+        end
+
+        # The proxy caps exp and 422s past it, which is where the millisecond
+        # typo (`some_time.to_i * 1000`) lands: a clean-looking URL that never
+        # works.
+        #
+        # +window+ is set only on the expires_in: path, where the caller wrote a
+        # duration rather than a timestamp — advising them about milliseconds
+        # there would name a mistake they did not make.
+        def bounded(seconds, source:, window: nil)
+          if seconds > Options::MAX_EXPIRES_AT
+            raise ArgumentError,
+              "Audioproxy #{source} produced #{seconds}, past the proxy's limit of " \
+              "#{Options::MAX_EXPIRES_AT} (9999-12-31T23:59:59Z); " \
+              "#{window ? "a window of #{window} seconds reaches past the year 9999" : "unix seconds, not milliseconds"}"
+          end
+
+          seconds
+        end
+
+        # A Duration whose total is not a whole number of seconds has no exact
+        # rendering here, and truncating one silently is the class of thing this
+        # gem raises about everywhere else — see Options.format_decimal.
+        def whole_seconds(value, total, source:)
+          unless total == total.to_i
+            raise ArgumentError,
+              "Audioproxy #{source} must be a whole number of seconds, got #{value.inspect} " \
+              "(#{total}); round explicitly at the call site if that is what you mean"
+          end
+
+          total.to_i
+        end
+    end
+  end
+end

data/lib/audioproxy/options.rb

@@ -11,8 +11,16 @@ module Audioproxy
   # carrying a separator — because a mangled segment is a valid-looking URL for
   # the wrong variant, and it fails at request time, far from here.
   module Options
-    # The proxy's fourteen option keys, canonical short spellings.
-    KEYS = %i[bd br cb ch dl f fade gain norm pk_fmt pts q sr t].freeze
+    # The proxy's fifteen option keys, canonical short spellings.
+    KEYS = %i[bd br cb ch dl exp f fade gain norm pk_fmt pts q sr t].freeze
+
+    # The one *request* option in the grammar: signed as path bytes, but
+    # excluded from the proxy's canonical options string, its cache key and its
+    # ffmpeg args, so two URLs differing only here are one variant and one
+    # render. Nothing in this module treats it specially beyond D1b below; the
+    # distinction is the proxy's, and it is recorded here because it is the
+    # reason exp may be appended to a raw: string that variant options may not.
+    REQUEST_KEYS = %i[exp].freeze
 
     # A spelled-out spelling for each canonical key, for call sites that would
     # rather read than decode. Total over KEYS, so "does this key have an alias"
@@ -34,7 +42,8 @@ module Audioproxy
       pts: :peak_count,
       pk_fmt: :peak_format,
       dl: :download,
-      cb: :cache_buster
+      cb: :cache_buster,
+      exp: :expires_at
     }.freeze
 
     # Every accepted spelling to the canonical key it renders as. Canonical
@@ -60,6 +69,13 @@ module Audioproxy
     # normalized options string into its cache key.
     MAX_DECIMALS = 3
 
+    # The proxy's own bound on exp (@max_expires_at in its Options module):
+    # 9999-12-31T23:59:59Z. Past it, the proxy answers 422 invalid-option. The
+    # grammar fact lives here; UrlBuilder is what checks a caller's value
+    # against it, because that is where an out-of-range timestamp can still be
+    # reported against the keyword the caller actually wrote.
+    MAX_EXPIRES_AT = 253_402_300_799
+
     # Characters a rendered value may not carry. The builder supplies '/' and
     # ':', so a value containing either silently invents a segment or a part.
     # '?' and '#' end the path as far as a browser is concerned, which truncates
@@ -186,6 +202,7 @@ module Audioproxy
           # Without this, t: 30.seconds is rejected as "not a number" by
           # something that says it is one.
           return render_duration(key, value) if value.is_a?(ActiveSupport::Duration)
+          return render_expiry(value) if key == :exp
           return format_number(value) unless OPAQUE_KEYS.include?(key)
 
           case value
@@ -196,6 +213,23 @@ module Audioproxy
           end
         end
 
+        # exp is unix seconds, and the proxy's grammar has no decimal there:
+        # exp:1.5 parses as an invalid option and 422s. So this is one of the
+        # values the module cannot render faithfully, and it raises rather than
+        # emitting a segment that looks like a timestamp and is not one (D1b).
+        # Integer only — not a numeric String, because the two inputs that reach
+        # this key in practice are Time#to_i and an arithmetic result, and both
+        # are Integers.
+        def render_expiry(value)
+          unless value.is_a?(Integer)
+            raise ArgumentError,
+              "Audioproxy option exp: must be an Integer of unix seconds, got #{value.inspect}; " \
+              "pass expires_in: or expires_at: to url_for and let it do the arithmetic"
+          end
+
+          value.to_s
+        end
+
         # A Duration is the Rails spelling of a number of seconds, so it is
         # accepted where the value *is* seconds and refused everywhere else:
         # br: 3.seconds rendering br:3 would be a valid-looking URL for the

data/lib/audioproxy/url_builder.rb

@@ -1,5 +1,6 @@
 require "base64"
 require "active_support/core_ext/object/blank"
+require "audioproxy/expiry"
 
 module Audioproxy
   # Assembles +{endpoint}/{signature}/{options}/{source}+ URLs, byte-compatible
@@ -29,11 +30,23 @@ module Audioproxy
     # spelled-out alias (+format:+, +bitrate:+, +trim:+ …), resolved to the
     # canonical key before anything is rendered. A keyword that is neither a
     # builder option nor a proxy option key raises rather than being ignored.
-    def url_for(source, raw: nil, endpoint: nil, unsigned: nil, **typed)
+    #
+    # +expires_in:+ (a duration or Integer seconds from now) and +expires_at:+
+    # (the instant itself) are mutually exclusive and time-box this one URL,
+    # overriding +config.expires_in+; either given as nil opts out of it (D6).
+    def url_for(source, raw: nil, endpoint: nil, unsigned: nil,
+                expires_in: Expiry::UNSET, expires_at: Expiry::UNSET, **typed)
       base = endpoint.nil? ? config.endpoint : Config.new.tap { |c| c.endpoint = endpoint }.endpoint
       raise ConfigurationError, "Audioproxy has no endpoint configured" if base.nil?
 
-      rest_of_path = "/#{options_segment(raw, typed)}/#{source_segment(source)}"
+      # Once per URL, so the window arithmetic and the past-check cannot
+      # straddle a second boundary (D4).
+      expiry = Expiry.timestamp(
+        expires_in: expires_in, expires_at: expires_at,
+        default_expires_in: config.expires_in, now: Time.now.to_i
+      )
+
+      rest_of_path = "/#{options_segment(raw, typed, expiry)}/#{source_segment(source)}"
       insecure = unsigned.nil? ? config.unsigned : unsigned
 
       "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
@@ -55,7 +68,11 @@ module Audioproxy
       # configured defaults entirely; typed per-call keys merge over typed
       # defaults key-by-key, keeping the defaults' position and appending the
       # rest in caller order.
-      def options_segment(raw, typed)
+      def options_segment(raw, typed, expiry)
+        with_expiry(variant_segment(raw, typed), expiry)
+      end
+
+      def variant_segment(raw, typed)
         unless raw.nil? || typed.empty?
           raise ArgumentError,
             "Audioproxy url_for takes either raw: or typed option keys, not both " \
@@ -69,6 +86,7 @@ module Audioproxy
         # overrides rather than two segments that both render (D3). Defaults
         # were resolved at assignment.
         typed = Options.resolve(typed)
+        reject_expiry_option!(typed)
 
         defaults = config.default_options
         typed_defaults = defaults.except(:raw)
@@ -80,6 +98,40 @@ module Audioproxy
         FALLBACK_OPTIONS
       end
 
+      # exp is a *request* option: signed as path bytes, but excluded from the
+      # proxy's cache key, so it is orthogonal to the variant options that
+      # raw: and the typed keys describe and composes with either (D3). It goes
+      # last, which leaves the variant prefix byte-identical to the same call
+      # without an expiry.
+      def with_expiry(segment, expiry)
+        return segment if expiry.nil?
+
+        # A raw: string that already spells out exp: would give the proxy two of
+        # them and a duplicate-option 422 — a failure the caller never wrote if
+        # the second one came from config.expires_in.
+        prefixes = Options::REQUEST_KEYS.map { |key| "#{key}:" }
+        if segment.split("/").any? { |part| prefixes.any? { |prefix| part.start_with?(prefix) } }
+          raise ArgumentError,
+            "Audioproxy url_for was given raw options that already carry an exp: segment " \
+            "(#{segment.inspect}) and an expiry to apply; the proxy rejects a duplicated option. " \
+            "Drop the exp: from raw:, or pass expires_in: nil to opt this URL out"
+        end
+
+        "#{segment}/#{Options.segment(:exp, expiry)}"
+      end
+
+      # exp: written as an ordinary option skips every check in Expiry, and the
+      # two mistakes it invites — a timestamp already past, a millisecond
+      # timestamp — both render a URL that looks right and never works (D1).
+      def reject_expiry_option!(typed)
+        return unless typed.key?(:exp)
+
+        raise ArgumentError,
+          "Audioproxy url_for does not take exp: as an option key; " \
+          "pass expires_in: (a duration from now) or expires_at: (the instant), " \
+          "which validate the value and do the arithmetic"
+      end
+
       def raw_segment(raw)
         segment = String.try_convert(raw)
         if segment.nil?

data/lib/audioproxy/version.rb

@@ -1,3 +1,3 @@
 module Audioproxy
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: audioproxy-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Julian Rubisch
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -70,6 +70,7 @@ files:
 - README.md
 - lib/audioproxy.rb
 - lib/audioproxy/config.rb
+- lib/audioproxy/expiry.rb
 - lib/audioproxy/options.rb
 - lib/audioproxy/rails.rb
 - lib/audioproxy/rails/blob_resolver.rb