Tls Sig Api V2 Laravel Package

Getting Started

tencent/tls-sig-api-v2 is a single-purpose library: it computes the UserSig (a signed JWT) that Tencent Cloud services such as TRTC, IM, and live streaming require to authenticate a user. That is the entire surface area — do not expect SDK wrappers, HTTP clients, or session management.

Install

composer require tencent/tls-sig-api-v2

Where to look first

• The repo README shows the canonical two-line example; that is genuinely all the API you need to learn.
• The only class you will touch is Tencent\TLSSigAPIv2\TLSSigAPIv2.
• Get your SDKAppID and secret key from the Tencent Cloud console (TRTC or IM application settings). The secret key is a server-side credential — never ship it to browsers or mobile apps.

Minimal first use case

Generate a signature for a user when they authenticate against your own backend:

use Tencent\TLSSigAPIv2\TLSSigAPIv2;

$api = new TLSSigAPIv2(
    (int) config('services.tencent.sdk_app_id'),
    config('services.tencent.secret_key')
);

$userSig = $api->genUserSig($userId); // default expiry, see below

Return $userSig to your frontend alongside your own auth token, and pass it into the Tencent client SDK's login({ sdkAppId, userId, userSig }) call. Keep the SDKAppID and the userId consistent between signature generation and the client login — a mismatch produces a login failure that looks like an auth error but is really a config error.

Implementation Patterns

Wrap it in a dedicated service. The raw class takes constructor args you should not sprinkle through controllers. A thin Laravel service or a bound singleton keeps the key in config and makes the generation point swappable and testable:

class UserSignatureService
{
    public function __construct(private TLSSigAPIv2 $api) {}

    public function forUser(string $userId): string
    {
        return $this->api->genUserSig($userId);
    }
}

Bind TLSSigAPIv2 in a service provider using config('services.tencent.*').

Generate server-side, on demand. The signature is a credential. The standard workflow is: user authenticates to your app → your backend mints the UserSig → the client hands it to the Tencent SDK. Never generate signatures in the browser or bundle the secret.

Choose expiry deliberately. The default expiry is long (on the order of 180 days in the upstream algorithm). For most applications that is too generous — Tencent's own guidance is to favour short-lived signatures and re-issue them. Practically: mint on login, and re-issue via a refresh endpoint if the session outlives the signature. Pass the expire argument explicitly rather than relying on the default so the value lives in your config, not the library.

Cache within the validity window when appropriate. If you generate a signature per request you are re-computing the same HMAC pointlessly. Cache the result keyed by userId for slightly less than its expiry (a Cache::remember with a TTL a few minutes under the signature lifetime is a common pattern). Invalidate the cache entry if you rotate the secret key.

Treat the secret key like any other secret. Load it from environment/config, exclude it from VCS, and support rotation — when rotated, old signatures remain valid until they expire, so allow overlap.

Local development ergonomics. Point different environments at different Tencent applications (dev/staging/prod) so that a leaked dev key is harmless and so test users don't pollute production analytics. Keep sdk_app_id and secret_key paired per environment.

Testing. Because the output is a deterministic function of (appId, key, userId, expiry), you can assert shape and stability in tests. Freeze time if your wrapper embeds generation timestamps, and assert that the signature verifies with a known-good reference implementation (Tencent publishes an online UserSig generator for exactly this).

Gotchas and Tips

• This library is small and stale. Last release was December 2020 and it has essentially no dependents. It works because the signing algorithm is fixed, but do not expect PHP 8.x-specific fixes, security patches, or responsive maintainers. Audit it, pin the version, and be prepared to inline the ~100-line algorithm yourself if it ever breaks.
• Signature is not a session token. It proves to Tencent that your backend vouched for a userId. It carries no permissions beyond that. Do not use it as your own auth token or log users in with it.
• UserId rules are strict. Certain characters (and length limits) are rejected or cause silent login failures on the SDK side. Restrict userIds to a safe alphanumeric subset at your registration boundary rather than discovering the rules at login time.
• Time skew. The signature embeds an issue time and an expiry. If your server clock is significantly off, signatures can appear already-expired or not-yet-valid to Tencent. Keep servers NTP-synced — this is the classic cause of "UserSig expired" immediately after generation.
• Expiry is not a security boundary you can shorten retroactively. Once issued, a signature is valid until it expires. If a user is banned or a key is compromised, you cannot revoke an outstanding signature; rotate the key (killing all signatures) or rely on Tencent-side account controls.
• The output looks like a JWT but do not assume it is a standard one. It follows Tencent's own composition; don't try to validate or decode it with a generic firebase/php-jwt in your own code. If you need to inspect it, use Tencent's decoder.
• Error handling is thin. The library mostly returns strings and does not throw rich exceptions for bad input. Validate sdk_app_id and user_id yourself before calling; empty or malformed inputs can produce a signature that fails only later on the client.
• Debugging checklist when the client rejects a signature: confirm the SDKAppID used to sign matches the client's, confirm the userId matches exactly (whitespace, case), confirm the key is the secret key (not the SDKAppID or an API key), and confirm the clock. Compare against Tencent's online generator with the same inputs — if they match, the problem is client-side config, not this library.
• Extension points are minimal. There is no pluggable signer or event system. If you need custom claims or a different signing backend, fork the class or wrap it; don't fight it.