Signing Helpers

Signing helpers provide functions to cryptographically sign and verify data using HMAC-SHA256.

Basic Usage

import { function getSignedValue(signedValue: string | undefined | null): string | undefined
Extracts the value part from a signed string without verification.

This function simply extracts the original value from a signed string
without performing any signature verification. It's useful when you need
to access the value quickly without the overhead of cryptographic verification.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const value = getSignedValue(signedValue)
expect(value).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}getSignedValue, function sign(value: string, secret: string): Promise<string>
Signs a string value using HMAC-SHA256 with a secret key.

This function creates a cryptographic signature that can be used to verify
the integrity and authenticity of the data. The signature is appended to
the original value, separated by a dot, using base64url encoding (no padding).
@example```ts
const signedValue = await sign("user123", "my-secret-key")
expect(signedValue).toEqual("user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}sign, function unsign(signedValue: string | undefined | null, secret: string): Promise<string | undefined>
Verifies and extracts the original value from a signed string.

This function validates the signature of a previously signed value using the same
secret key. If the signature is valid, it returns the original value. If the
signature is invalid or the format is incorrect, it returns undefined.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const originalValue = await unsign(signedValue, "my-secret-key")
expect(originalValue).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}unsign } from '@orpc/server/helpers'

const const secret: "your-secret-key"secret = 'your-secret-key'
const const userData: "user123"userData = 'user123'

const const signedValue: stringsignedValue = await function sign(value: string, secret: string): Promise<string>
Signs a string value using HMAC-SHA256 with a secret key.

This function creates a cryptographic signature that can be used to verify
the integrity and authenticity of the data. The signature is appended to
the original value, separated by a dot, using base64url encoding (no padding).
@example```ts
const signedValue = await sign("user123", "my-secret-key")
expect(signedValue).toEqual("user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}sign(const userData: "user123"userData, const secret: "your-secret-key"secret)
// 'user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA'
// ↑ Original data is visible to users

const const verifiedValue: string | undefinedverifiedValue = await function unsign(signedValue: string | undefined | null, secret: string): Promise<string | undefined>
Verifies and extracts the original value from a signed string.

This function validates the signature of a previously signed value using the same
secret key. If the signature is valid, it returns the original value. If the
signature is invalid or the format is incorrect, it returns undefined.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const originalValue = await unsign(signedValue, "my-secret-key")
expect(originalValue).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}unsign(const signedValue: stringsignedValue, const secret: "your-secret-key"secret) // 'user123'

// Extract value without verification
const const extractedValue: string | undefinedextractedValue = function getSignedValue(signedValue: string | undefined | null): string | undefined
Extracts the value part from a signed string without verification.

This function simply extracts the original value from a signed string
without performing any signature verification. It's useful when you need
to access the value quickly without the overhead of cryptographic verification.
@example```ts
const signedValue = "user123.oneQsU0r5dvwQFHFEjjV1uOI_IR3gZfkYHij3TRauVA"
const value = getSignedValue(signedValue)
expect(value).toEqual("user123")
```@see{@link https://orpc.dev/docs/helpers/signing Signing Helpers}getSignedValue(const signedValue: stringsignedValue) // 'user123'