extract_username_from_access_token lua

Author: shcherbak

charts/synapse/Chart.yaml

@@ -2,4 +2,4 @@ apiVersion: v2
 appVersion: 1.151.0
 description: matrix synapse kubernetes deployment
 name: synapse
-version: 2.4.13
+version: 2.4.14

charts/synapse/scripts/synapse.lua

@@ -123,6 +123,69 @@ local function extract_localpart(user_id)
     return string.sub(user_id, 2, colon_index - 1)
 end
 
+-- Pure-Lua decoder for unpadded standard base64 (the alphabet and padding
+-- behaviour produced by Synapse's `unpaddedbase64.encode_base64`). Used to
+-- decode the localpart embedded directly in Synapse-issued access tokens -
+-- see `extract_username_from_access_token` below.
+local b64_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+local function decode_unpadded_base64(data)
+    if string.find(data, "[^" .. b64_chars .. "=]") ~= nil then
+        return nil
+    end
+
+    local bits = (data:gsub(".", function(char)
+        if char == "=" then
+            return ""
+        end
+
+        local value = b64_chars:find(char, 1, true) - 1
+        local bit_string = ""
+        for i = 5, 0, -1 do
+            bit_string = bit_string .. (math.floor(value / 2 ^ i) % 2)
+        end
+        return bit_string
+    end))
+
+    return (bits:gsub("%d%d%d?%d?%d?%d?%d?%d?", function(byte_bits)
+        if string.len(byte_bits) ~= 8 then
+            return ""
+        end
+
+        local byte = 0
+        for i = 1, 8 do
+            byte = byte + (string.sub(byte_bits, i, i) == "1" and 2 ^ (8 - i) or 0)
+        end
+        return string.char(byte)
+    end))
+end
+
+-- Synapse-issued access tokens embed the user's localpart directly:
+-- syt_<unpadded-base64(localpart)>_<random string>_<base62 crc check>
+-- (see synapse/handlers/auth.py: AuthHandler.generate_access_token). Decoding
+-- it locally gives us a stable per-user X-Hash-Key - identical across all of
+-- a user's devices/sessions - without an internal whoami round-trip and its
+-- failure modes (timeouts, transient errors). Tokens that don't match this
+-- format (application-service tokens, delegated-auth/MSC3861 tokens, ...)
+-- return nil here and fall through to the whoami lookup below.
+local function extract_username_from_access_token(token)
+    if token == nil then
+        return nil
+    end
+
+    local _, _, b64local = string.find(token, "^syt_([A-Za-z0-9+/]+)_")
+    if b64local == nil then
+        return nil
+    end
+
+    local ok, localpart = pcall(decode_unpadded_base64, b64local)
+    if not ok or localpart == nil or string.len(localpart) == 0 then
+        return nil
+    end
+
+    return localpart
+end
+
 local function extract_user_id_from_whoami_body(body)
     local _, _, user_id = string.find(body, '"user_id"%s*:%s*"([^"]+)"')
 
@@ -213,6 +276,16 @@ local function get_user_identifier_from_request(request_handle, options)
         return nil
     end
 
+    -- Fast path: most tokens are issued by Synapse itself and embed the
+    -- localpart, so we can derive a stable per-user hash key with no network
+    -- call at all - this is what keeps a user's /sync traffic pinned to the
+    -- same httpd-user-hash worker regardless of how many devices they use.
+    local decoded_username = extract_username_from_access_token(token)
+    if decoded_username ~= nil then
+        log(request_handle, options, "warn", "decoded username from token " .. truncate_token(token, options) .. " -> " .. decoded_username)
+        return decoded_username
+    end
+
     local cached_username = get_cached_username(token, options)
     if cached_username ~= nil then
         log(request_handle, options, "warn", "cache hit for token " .. truncate_token(token, options) .. " -> " .. cached_username)
@@ -225,6 +298,10 @@ local function get_user_identifier_from_request(request_handle, options)
         return username
     end
 
+    -- Last resort: pin on the raw token. It's only stable per device/session
+    -- (not per user across devices), but that's still far better than
+    -- x-request-id - it keeps a given session's requests landing on the same
+    -- worker instead of scattering randomly on every single request.
     log(request_handle, options, "warn", "whoami lookup failed, falling back to token-based routing")
     return token
 end

charts/synapse/scripts/synapse_test.lua

@@ -76,6 +76,82 @@ local function test_access_token_from_query()
     )
 end
 
+local function test_username_decoded_from_synapse_token_without_whoami()
+    local request_handle = new_request_handle({
+        [":path"] = "/_matrix/client/v3/sync",
+        -- syt_<unpadded-base64("alice")>_<random>_<crc>
+        ["authorization"] = "Bearer syt_YWxpY2U_abcdefghij1234567890_crc123"
+    }, function()
+        error("decodable token should not call whoami")
+    end)
+
+    assert_equal(
+        synapse.get_user_identifier_from_request(request_handle, {}),
+        "alice",
+        "localpart should be decoded directly from a syt_ token"
+    )
+end
+
+local function test_username_decoded_consistent_across_devices()
+    local handle_a = new_request_handle({
+        [":path"] = "/_matrix/client/v3/sync",
+        ["authorization"] = "Bearer syt_Y2Fyb2wtdGVzdF85OQ_deviceAtokenAAAAAAA_crc111"
+    }, function()
+        error("decodable token should not call whoami")
+    end)
+    local handle_b = new_request_handle({
+        [":path"] = "/_matrix/client/v3/sync",
+        ["authorization"] = "Bearer syt_Y2Fyb2wtdGVzdF85OQ_deviceBtokenBBBBBBB_crc222"
+    }, function()
+        error("decodable token should not call whoami")
+    end)
+
+    local key_a = synapse.get_user_identifier_from_request(handle_a, {})
+    local key_b = synapse.get_user_identifier_from_request(handle_b, {})
+
+    assert_equal(key_a, "carol-test_99", "device A should decode to the localpart")
+    assert_equal(key_b, "carol-test_99", "device B should decode to the same localpart")
+    assert_equal(key_a, key_b, "the same user on different devices must hash to the same key")
+end
+
+local function test_non_synapse_token_falls_back_to_whoami()
+    local calls = 0
+    local request_handle = new_request_handle({
+        [":path"] = "/_matrix/client/v3/sync",
+        -- application-service / delegated-auth tokens don't follow the syt_ format
+        ["authorization"] = "Bearer as_some_opaque_appservice_token"
+    }, function(_, cluster, headers, body, timeout_ms)
+        calls = calls + 1
+        return { [":status"] = "200" }, '{"user_id":"@bridgebot:example.org"}'
+    end)
+
+    assert_equal(
+        synapse.get_user_identifier_from_request(request_handle, {}),
+        "bridgebot",
+        "non-syt tokens should resolve via whoami"
+    )
+    assert_equal(calls, 1, "whoami should be used for tokens that aren't locally decodable")
+end
+
+local function test_malformed_synapse_token_falls_back_to_whoami()
+    local calls = 0
+    local request_handle = new_request_handle({
+        [":path"] = "/_matrix/client/v3/sync",
+        -- looks like a syt_ token, but the middle segment isn't valid base64
+        ["authorization"] = "Bearer syt_!!!not-base64!!!_randomstring12345_crc999"
+    }, function(_, cluster, headers, body, timeout_ms)
+        calls = calls + 1
+        return { [":status"] = "200" }, '{"user_id":"@erin:example.org"}'
+    end)
+
+    assert_equal(
+        synapse.get_user_identifier_from_request(request_handle, {}),
+        "erin",
+        "malformed syt_ tokens should fall back to whoami rather than crash"
+    )
+    assert_equal(calls, 1, "whoami should be used when local decoding fails")
+end
+
 local function test_whoami_lookup_returns_localpart()
     local calls = 0
     local request_handle = new_request_handle({
@@ -214,6 +290,10 @@ local tests = {
     test_room_id_from_encoded_path,
     test_access_token_from_authorization_header,
     test_access_token_from_query,
+    test_username_decoded_from_synapse_token_without_whoami,
+    test_username_decoded_consistent_across_devices,
+    test_non_synapse_token_falls_back_to_whoami,
+    test_malformed_synapse_token_falls_back_to_whoami,
     test_whoami_lookup_returns_localpart,
     test_whoami_lookup_forwards_xff,
     test_whoami_lookup_without_xff,

charts/synapse/tests/golden/fixtures/test-envoy-configmap-msc4306.golden.yaml

@@ -1567,6 +1567,69 @@ data:
         return string.sub(user_id, 2, colon_index - 1)
     end
     
+    -- Pure-Lua decoder for unpadded standard base64 (the alphabet and padding
+    -- behaviour produced by Synapse's `unpaddedbase64.encode_base64`). Used to
+    -- decode the localpart embedded directly in Synapse-issued access tokens -
+    -- see `extract_username_from_access_token` below.
+    local b64_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    
+    local function decode_unpadded_base64(data)
+        if string.find(data, "[^" .. b64_chars .. "=]") ~= nil then
+            return nil
+        end
+    
+        local bits = (data:gsub(".", function(char)
+            if char == "=" then
+                return ""
+            end
+    
+            local value = b64_chars:find(char, 1, true) - 1
+            local bit_string = ""
+            for i = 5, 0, -1 do
+                bit_string = bit_string .. (math.floor(value / 2 ^ i) % 2)
+            end
+            return bit_string
+        end))
+    
+        return (bits:gsub("%d%d%d?%d?%d?%d?%d?%d?", function(byte_bits)
+            if string.len(byte_bits) ~= 8 then
+                return ""
+            end
+    
+            local byte = 0
+            for i = 1, 8 do
+                byte = byte + (string.sub(byte_bits, i, i) == "1" and 2 ^ (8 - i) or 0)
+            end
+            return string.char(byte)
+        end))
+    end
+    
+    -- Synapse-issued access tokens embed the user's localpart directly:
+    -- syt_<unpadded-base64(localpart)>_<random string>_<base62 crc check>
+    -- (see synapse/handlers/auth.py: AuthHandler.generate_access_token). Decoding
+    -- it locally gives us a stable per-user X-Hash-Key - identical across all of
+    -- a user's devices/sessions - without an internal whoami round-trip and its
+    -- failure modes (timeouts, transient errors). Tokens that don't match this
+    -- format (application-service tokens, delegated-auth/MSC3861 tokens, ...)
+    -- return nil here and fall through to the whoami lookup below.
+    local function extract_username_from_access_token(token)
+        if token == nil then
+            return nil
+        end
+    
+        local _, _, b64local = string.find(token, "^syt_([A-Za-z0-9+/]+)_")
+        if b64local == nil then
+            return nil
+        end
+    
+        local ok, localpart = pcall(decode_unpadded_base64, b64local)
+        if not ok or localpart == nil or string.len(localpart) == 0 then
+            return nil
+        end
+    
+        return localpart
+    end
+    
     local function extract_user_id_from_whoami_body(body)
         local _, _, user_id = string.find(body, '"user_id"%s*:%s*"([^"]+)"')
     
@@ -1657,6 +1720,16 @@ data:
             return nil
         end
     
+        -- Fast path: most tokens are issued by Synapse itself and embed the
+        -- localpart, so we can derive a stable per-user hash key with no network
+        -- call at all - this is what keeps a user's /sync traffic pinned to the
+        -- same httpd-user-hash worker regardless of how many devices they use.
+        local decoded_username = extract_username_from_access_token(token)
+        if decoded_username ~= nil then
+            log(request_handle, options, "warn", "decoded username from token " .. truncate_token(token, options) .. " -> " .. decoded_username)
+            return decoded_username
+        end
+    
         local cached_username = get_cached_username(token, options)
         if cached_username ~= nil then
             log(request_handle, options, "warn", "cache hit for token " .. truncate_token(token, options) .. " -> " .. cached_username)
@@ -1669,6 +1742,10 @@ data:
             return username
         end
     
+        -- Last resort: pin on the raw token. It's only stable per device/session
+        -- (not per user across devices), but that's still far better than
+        -- x-request-id - it keeps a given session's requests landing on the same
+        -- worker instead of scattering randomly on every single request.
         log(request_handle, options, "warn", "whoami lookup failed, falling back to token-based routing")
         return token
     end

charts/synapse/tests/golden/fixtures/test-envoy-configmap-no-mas.golden.yaml

@@ -1506,6 +1506,69 @@ data:
         return string.sub(user_id, 2, colon_index - 1)
     end
     
+    -- Pure-Lua decoder for unpadded standard base64 (the alphabet and padding
+    -- behaviour produced by Synapse's `unpaddedbase64.encode_base64`). Used to
+    -- decode the localpart embedded directly in Synapse-issued access tokens -
+    -- see `extract_username_from_access_token` below.
+    local b64_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    
+    local function decode_unpadded_base64(data)
+        if string.find(data, "[^" .. b64_chars .. "=]") ~= nil then
+            return nil
+        end
+    
+        local bits = (data:gsub(".", function(char)
+            if char == "=" then
+                return ""
+            end
+    
+            local value = b64_chars:find(char, 1, true) - 1
+            local bit_string = ""
+            for i = 5, 0, -1 do
+                bit_string = bit_string .. (math.floor(value / 2 ^ i) % 2)
+            end
+            return bit_string
+        end))
+    
+        return (bits:gsub("%d%d%d?%d?%d?%d?%d?%d?", function(byte_bits)
+            if string.len(byte_bits) ~= 8 then
+                return ""
+            end
+    
+            local byte = 0
+            for i = 1, 8 do
+                byte = byte + (string.sub(byte_bits, i, i) == "1" and 2 ^ (8 - i) or 0)
+            end
+            return string.char(byte)
+        end))
+    end
+    
+    -- Synapse-issued access tokens embed the user's localpart directly:
+    -- syt_<unpadded-base64(localpart)>_<random string>_<base62 crc check>
+    -- (see synapse/handlers/auth.py: AuthHandler.generate_access_token). Decoding
+    -- it locally gives us a stable per-user X-Hash-Key - identical across all of
+    -- a user's devices/sessions - without an internal whoami round-trip and its
+    -- failure modes (timeouts, transient errors). Tokens that don't match this
+    -- format (application-service tokens, delegated-auth/MSC3861 tokens, ...)
+    -- return nil here and fall through to the whoami lookup below.
+    local function extract_username_from_access_token(token)
+        if token == nil then
+            return nil
+        end
+    
+        local _, _, b64local = string.find(token, "^syt_([A-Za-z0-9+/]+)_")
+        if b64local == nil then
+            return nil
+        end
+    
+        local ok, localpart = pcall(decode_unpadded_base64, b64local)
+        if not ok or localpart == nil or string.len(localpart) == 0 then
+            return nil
+        end
+    
+        return localpart
+    end
+    
     local function extract_user_id_from_whoami_body(body)
         local _, _, user_id = string.find(body, '"user_id"%s*:%s*"([^"]+)"')
     
@@ -1596,6 +1659,16 @@ data:
             return nil
         end
     
+        -- Fast path: most tokens are issued by Synapse itself and embed the
+        -- localpart, so we can derive a stable per-user hash key with no network
+        -- call at all - this is what keeps a user's /sync traffic pinned to the
+        -- same httpd-user-hash worker regardless of how many devices they use.
+        local decoded_username = extract_username_from_access_token(token)
+        if decoded_username ~= nil then
+            log(request_handle, options, "warn", "decoded username from token " .. truncate_token(token, options) .. " -> " .. decoded_username)
+            return decoded_username
+        end
+    
         local cached_username = get_cached_username(token, options)
         if cached_username ~= nil then
             log(request_handle, options, "warn", "cache hit for token " .. truncate_token(token, options) .. " -> " .. cached_username)
@@ -1608,6 +1681,10 @@ data:
             return username
         end
     
+        -- Last resort: pin on the raw token. It's only stable per device/session
+        -- (not per user across devices), but that's still far better than
+        -- x-request-id - it keeps a given session's requests landing on the same
+        -- worker instead of scattering randomly on every single request.
         log(request_handle, options, "warn", "whoami lookup failed, falling back to token-based routing")
         return token
     end