Edge Token

A simple and secure token utility for generating and verifying tokens with optional data and timing. Edge Runtime compatible, making it ideal for use in serverless environments like Vercel Edge Functions, Cloudflare Workers, and other edge computing platforms. Suitable for CSRF protection, URL validation, file integrity checks, and more.

Features

- Edge Runtime Compatible: Designed to work seamlessly in edge environments with limited APIs.
- Generate and Verify Tokens: Create tokens with or without embedded data and timestamps.
- Flexible Use Cases: Ideal for CSRF protection, secure URLs, file validation, and other token-based verification systems.
- Customizable Options: Configure HMAC algorithms, token length, separators, and data serializers.
- TypeScript Support: Fully typed for seamless integration in TypeScript projects.

Installation

Install the package via npm:

``bash
npm install @nartix/edge-token
`

Usage

$3

`typescript
import { edgeToken } from '@nartix/edge-token';
`

$3

Initialize the utility with your secret and optional configurations:

`typescript
const tokenUtility = await edgeToken({
secret: 'your-secure-secret', // Replace with a secure, random string
// Optional configurations:
algorithm: 'SHA-256', // Defaults to 'SHA-256'
tokenByteLength: 32, // Defaults to 32 bytes
separator: '.', // Defaults to '.'
dataSerializer: (data) => { // Optional custom serializer
// Your serialization logic
},
dataDecoder: (data) => { // Optional custom decoder
// Your decoding logic
},
});
`

$3

#### Simple Token

Generate a basic token without additional data or timing:

`typescript
const token = await tokenUtility.generate();
console.log(token);
// mnpyrx0myNxdmH1IenxAIhXa.ungwFmuHiNKc1CSXkp-nRZsH6Y3REaLdHE08WLy9FW8
`

#### Token with Data

Generate a token that includes embedded data (e.g., user ID, file identifier):

`typescript
const tokenWithData = await tokenUtility.generateWithData({ userId: 123, fileId: 'abc123' });
console.log(tokenWithData);
// eyJ1c2VySWQiOjEyMywiZmlsZUlkIjoiYWJjMTIzIn0.NrJERKP-kUwI0cbeKg5f_Fsb.4LlywnVckzY0FWj9R6yyX9JB_dPl8oyAiM8VEGFBFdg
`

#### Timed Token

Generate a token that includes a timestamp for expiration:

`typescript
const timedToken = await tokenUtility.generateTimed();
console.log(timedToken);
// MTczNjIzMzA0NDIzNg.CLXZYl-WOCByudOdXNMZI3oD.uYghfCFKBCFSxpYIVpLkwK51ZuBbC_DhExfpzxKZWr8
`

#### Timed Token with Data

Generate a token that includes both data and a timestamp:

`typescript
const timedTokenWithData = await tokenUtility.generateWithDataTimed({ userId: 123, action: 'upload' });
console.log(timedTokenWithData);
`

$3

#### Simple Token

Verify a basic token:

`typescript
const isValid = await tokenUtility.verify(submittedToken);
console.log(isValid); // true or false
`

#### Token with Data

Verify a token that includes embedded data:

`typescript
const isValidWithData = await tokenUtility.verifyWithData(submittedToken, { userId: 123, fileId: 'abc123' });
console.log(isValidWithData); // true or false
`

#### Timed Token

Verify a timed token with a maximum age (e.g., 5 minutes):

`typescript
const isValidTimed = await tokenUtility.verifyTimed(submittedToken, '', 5 60 1000);
console.log(isValidTimed); // true or false
`

#### Timed Token with Data

Verify a timed token that includes embedded data:

`typescript
const isValidTimedWithData = await tokenUtility.verifyWithDataTimed(submittedToken, { userId: 123, action: 'upload' }, 5 60 1000);
console.log(isValidTimedWithData); // true or false
`

Example Use Cases

$3

Generate and verify CSRF tokens to protect against Cross-Site Request Forgery attacks.

`typescript
// Generate CSRF token
const csrfToken = await tokenUtility.generate();

// Embed csrfToken in your forms or requests

// Verify CSRF token upon form submission
const isCsrfValid = await tokenUtility.verify(submittedCsrfToken);
`

$3

Create tokens that embed user or action data to generate secure, tamper-proof URLs.

`typescript
// Generate a secure URL token with user ID and action
const urlToken = await tokenUtility.generateWithData({ userId: 456, action: 'reset-password' });
const secureUrl = https://yourdomain.com/action?token=${urlToken};

// Verify the token when the URL is accessed
const isUrlValid = await tokenUtility.verifyWithData(submittedUrlToken, { userId: 456, action: 'reset-password' });
`

$3

Generate tokens for files to ensure they haven't been tampered with.

`typescript
// Generate a token for a file
const fileToken = await tokenUtility.generateWithData({ fileId: 'file123', checksum: 'abcde12345' });

// Store fileToken alongside the file

// Verify the token when accessing the file
const isFileValid = await tokenUtility.verifyWithData(submittedFileToken, { fileId: 'file123', checksum: 'abcde12345' });
`

Configuration Options

When initializing edgeToken, you can provide the following options:

- secret (string, required): The secret used to derive the HMAC key. Must be a secure, random string.
- algorithm (string, optional): Hash algorithm for HMAC. Supported values: SHA-1, SHA-256, SHA-384, SHA-512. Defaults to SHA-256.
- tokenByteLength (number, optional): Byte length of the random token portion. Defaults to 32.
- separator (string, optional): Character to separate token parts. Defaults to ..
- dataSerializer (function, optional): Function to serialize data into Uint8Array. Defaults handle strings, objects, and Uint8Array instances.
- dataDecoder (function, optional): Function to decode data from Uint8Array. Defaults handle JSON parsing and string decoding.

API Reference

$3

Creates a token utility with the specified options.

- Parameters:
- userOptions (Partial): User-provided configuration options.

- Returns:
- A promise that resolves to the token utility object.

$3

#### generate(data?: unknown): Promise

Generate a simple token with or without data and without timing.

- Parameters:
- data (unknown, optional): Data to include in the token. Defaults to an empty string if the data is an edge case.

- Returns:
- A promise that resolves to the generated token string.

#### verify(submitted: string, data?: unknown): Promise

Verify a simple token without data and without timing.

- Parameters:
- submitted (string): The token to verify.
- data (unknown, optional): The expected data to verify against. Defaults to an empty string if the data is an edge case.

- Returns:
- A promise that resolves to true if the token is valid, false otherwise.

#### generateWithData(data: unknown): Promise

Generate a token with embedded data.

- Parameters:
- data (unknown): Data to include in the token.

- Returns:
- A promise that resolves to the generated token string.

#### verifyWithData(submitted: string, data: unknown): Promise

Verify a token with embedded data.

- Parameters:
- submitted (string): The token to verify.
- data (unknown): The expected data to verify against.

- Returns:
- A promise that resolves to true if the token is valid, false otherwise.

#### generateTimed(data?: unknown): Promise

Generate a timed token without embedded data.

- Parameters:
- data (unknown, optional): Data to include in the token. Defaults to an empty string if the data is an edge case.

- Returns:
- A promise that resolves to the generated token string.

#### verifyTimed(submitted: string, data?: unknown, maxAgeMs: number): Promise

Verify a timed token without embedded data.

- Parameters:
- submitted (string): The token to verify.
- data (unknown, optional): The expected data to verify against. Defaults to an empty string if the data is an edge case.
- maxAgeMs (number): Maximum age in milliseconds for the token to be considered valid.

- Returns:
- A promise that resolves to true if the token is valid and not expired, false otherwise.

#### generateWithDataTimed(data: unknown): Promise

Generate a timed token with embedded data.

- Parameters:
- data (unknown): Data to include in the token.

- Returns:
- A promise that resolves to the generated token string.

#### verifyWithDataTimed(submitted: string, data: unknown, maxAgeMs: number): Promise

Verify a timed token with embedded data.

- Parameters:
- submitted (string): The token to verify.
- data (unknown): The expected data to verify against.
- maxAgeMs (number): Maximum age in milliseconds for the token to be considered valid.

- Returns:
- A promise that resolves to true if the token is valid and not expired, false otherwise.

Security Considerations

- Use a Strong Secret: Ensure the secret option is a strong, random string to maintain token security.
- Token Expiration: When using timed tokens, set an appropriate maxAgeMs` to balance security and usability.
- Data Integrity: Only include non-sensitive data within tokens and ensure proper serialization and decoding.
- Protect Secrets: Never expose your secret in client-side code or insecure environments.

Edge Runtime Compatibility

Edge Token is fully compatible with Edge Runtime environments, such as:

- Vercel Edge Functions
- Cloudflare Workers
- Netlify Edge Functions
- AWS Lambda@Edge

This compatibility ensures that you can leverage Edge Token for high-performance, low-latency applications deployed at the edge, taking advantage of secure token generation and verification without sacrificing speed or scalability.

License

MIT

---

Support

If you encounter any issues or have questions, please open an issue on GitHub.

---

Happy tokenizing! 🚀