0
# OAuth Sign
1

2
OAuth Sign is a standalone OAuth 1.0 signature generation library for Node.js. It provides comprehensive support for all standard OAuth 1.0 signature methods including HMAC-SHA1, HMAC-SHA256, RSA-SHA1, and PLAINTEXT, with full RFC 5849 compliance for parameter normalization and signature base string generation.
3

4
## Package Information
5

6
- **Package Name**: oauth-sign
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install oauth-sign`
10

11
## Core Imports
12

13
```javascript
14
const { sign, hmacsign, hmacsign256, rsasign, plaintext, rfc3986, generateBase } = require("oauth-sign");
15
```
16

17
For specific functions:
18

19
```javascript
20
const { hmacsign } = require("oauth-sign"); // Most common usage
21
const { sign } = require("oauth-sign"); // Universal signature function
22
```
23

24
## Basic Usage
25

26
```javascript
27
const { hmacsign, sign } = require("oauth-sign");
28

29
// HMAC-SHA1 signature (most common)
30
const signature = hmacsign(
31
  'POST',
32
  'https://api.twitter.com/oauth/request_token',
33
  {
34
    oauth_callback: 'http://localhost:3005/callback',
35
    oauth_consumer_key: 'your_consumer_key',
36
    oauth_nonce: 'generated_nonce',
37
    oauth_signature_method: 'HMAC-SHA1',
38
    oauth_timestamp: '1234567890',
39
    oauth_version: '1.0'
40
  },
41
  'consumer_secret',
42
  'token_secret'
43
);
44

45
// Universal signature function
46
const signature2 = sign(
47
  'HMAC-SHA1',
48
  'POST', 
49
  'https://api.twitter.com/oauth/request_token',
50
  { /* oauth parameters */ },
51
  'consumer_secret',
52
  'token_secret'
53
);
54
```
55

56
## Architecture
57

58
OAuth Sign implements OAuth 1.0 signature generation with these core components:
59

60
- **Signature Methods**: Four supported OAuth 1.0 signature methods with dedicated functions
61
- **Universal Interface**: Single `sign()` function that delegates to appropriate signature method
62
- **RFC 5849 Compliance**: Proper parameter normalization, sorting, and encoding per OAuth 1.0 specification
63
- **Utility Functions**: RFC 3986 URL encoding and signature base string generation
64
- **Pure Node.js**: Uses only built-in `crypto` module with no external dependencies
65

66
## Capabilities
67

68
### HMAC-SHA1 Signature Generation
69

70
Generates OAuth 1.0 signatures using HMAC-SHA1 cryptographic method.
71

72
```javascript { .api }
73
/**
74
 * Generate HMAC-SHA1 OAuth signature
75
 * @param {string} httpMethod - HTTP method (GET, POST, etc.)
76
 * @param {string} base_uri - Base URL for the request
77
 * @param {Object} params - OAuth parameters and request parameters
78
 * @param {string} consumer_secret - OAuth consumer secret
79
 * @param {string} [token_secret] - OAuth token secret (optional)
80
 * @returns {string} Base64-encoded HMAC-SHA1 signature
81
 */
82
function hmacsign(httpMethod, base_uri, params, consumer_secret, token_secret);
83
```
84

85
**Usage Example:**
86

87
```javascript
88
const { hmacsign } = require("oauth-sign");
89

90
const signature = hmacsign(
91
  'POST',
92
  'https://api.twitter.com/oauth/access_token',
93
  {
94
    oauth_consumer_key: 'GDdmIQH6jhtmLUypg82g',
95
    oauth_nonce: '9zWH6qe0qG7Lc1telCn7FhUbLyVdjEaL3MO5uHxn8',
96
    oauth_signature_method: 'HMAC-SHA1',
97
    oauth_token: '8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc',
98
    oauth_timestamp: '1272323047',
99
    oauth_verifier: 'pDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY',
100
    oauth_version: '1.0'
101
  },
102
  'MCD8BKwGdgPHvAuvgvz4EQpqDAtx89grbuNMRd7Eh98',
103
  'x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA'
104
);
105
```
106

107
### HMAC-SHA256 Signature Generation
108

109
Generates OAuth 1.0 signatures using HMAC-SHA256 cryptographic method for enhanced security.
110

111
```javascript { .api }
112
/**
113
 * Generate HMAC-SHA256 OAuth signature
114
 * @param {string} httpMethod - HTTP method (GET, POST, etc.)
115
 * @param {string} base_uri - Base URL for the request
116
 * @param {Object} params - OAuth parameters and request parameters
117
 * @param {string} consumer_secret - OAuth consumer secret
118
 * @param {string} [token_secret] - OAuth token secret (optional)
119
 * @returns {string} Base64-encoded HMAC-SHA256 signature
120
 */
121
function hmacsign256(httpMethod, base_uri, params, consumer_secret, token_secret);
122
```
123

124
**Usage Example:**
125

126
```javascript
127
const { hmacsign256 } = require("oauth-sign");
128

129
const signature = hmacsign256(
130
  'POST',
131
  'http://api.twitter.com/1/statuses/update.json',
132
  {
133
    oauth_consumer_key: 'GDdmIQH6jhtmLUypg82g',
134
    oauth_nonce: 'oElnnMTQIZvqvlfXM56aBLAf5noGD0AQR3Fmi7Q6Y',
135
    oauth_signature_method: 'HMAC-SHA256',
136
    oauth_token: '819797-Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw',
137
    oauth_timestamp: '1272325550',
138
    oauth_version: '1.0',
139
    status: 'setting up my twitter 私のさえずりを設定する'
140
  },
141
  'MCD8BKwGdgPHvAuvgvz4EQpqDAtx89grbuNMRd7Eh98',
142
  'J6zix3FfA9LofH0awS24M3HcBYXO5nI1iYe8EfBA'
143
);
144
```
145

146
### RSA-SHA1 Signature Generation
147

148
Generates OAuth 1.0 signatures using RSA-SHA1 cryptographic method with private key.
149

150
```javascript { .api }
151
/**
152
 * Generate RSA-SHA1 OAuth signature using private key
153
 * @param {string} httpMethod - HTTP method (GET, POST, etc.)
154
 * @param {string} base_uri - Base URL for the request
155
 * @param {Object} params - OAuth parameters and request parameters
156
 * @param {string} private_key - RSA private key in PEM format
157
 * @param {string} [token_secret] - OAuth token secret (unused for RSA)
158
 * @returns {string} Base64-encoded RSA-SHA1 signature
159
 */
160
function rsasign(httpMethod, base_uri, params, private_key, token_secret);
161
```
162

163
### PLAINTEXT Signature Generation
164

165
Generates OAuth 1.0 PLAINTEXT signatures by concatenating consumer and token secrets.
166

167
```javascript { .api }
168
/**
169
 * Generate PLAINTEXT OAuth signature (simple key concatenation)
170
 * @param {string} consumer_secret - OAuth consumer secret
171
 * @param {string} [token_secret] - OAuth token secret (optional)
172
 * @returns {string} RFC 3986 encoded concatenated key string
173
 */
174
function plaintext(consumer_secret, token_secret);
175
```
176

177
**Usage Example:**
178

179
```javascript
180
const { plaintext } = require("oauth-sign");
181

182
const signature = plaintext('consumer_secret', 'token_secret');
183
// Result: 'consumer_secret&token_secret'
184
```
185

186
### Universal Signature Function
187

188
Universal signature function that delegates to the appropriate signature method based on the first parameter.
189

190
```javascript { .api }
191
/**
192
 * Universal signature function supporting all OAuth 1.0 signature methods
193
 * @param {string} signMethod - Signature method ('HMAC-SHA1', 'HMAC-SHA256', 'RSA-SHA1', 'PLAINTEXT')
194
 * @param {string} httpMethod - HTTP method (GET, POST, etc.)
195
 * @param {string} base_uri - Base URL for the request
196
 * @param {Object} params - OAuth parameters and request parameters
197
 * @param {string} consumer_secret - OAuth consumer secret or RSA private key for RSA-SHA1
198
 * @param {string} [token_secret] - OAuth token secret (optional)
199
 * @returns {string} Signature string in appropriate format for the selected method
200
 * @throws {Error} If unsupported signature method is provided
201
 */
202
function sign(signMethod, httpMethod, base_uri, params, consumer_secret, token_secret);
203
```
204

205
**Usage Example:**
206

207
```javascript
208
const { sign } = require("oauth-sign");
209

210
// HMAC-SHA1
211
const hmacSignature = sign(
212
  'HMAC-SHA1',
213
  'POST',
214
  'https://api.example.com/endpoint',
215
  { oauth_consumer_key: 'key', oauth_nonce: 'nonce' },
216
  'consumer_secret',
217
  'token_secret'
218
);
219

220
// PLAINTEXT
221
const plaintextSignature = sign(
222
  'PLAINTEXT',
223
  'GET',
224
  'http://example.com',
225
  {},
226
  'consumer_secret',
227
  'token_secret'
228
);
229

230
// Error handling
231
try {
232
  const invalidSignature = sign('INVALID-METHOD', 'GET', 'http://example.com', {}, 'secret');
233
} catch (error) {
234
  console.error('Unsupported signature method:', error.message);
235
}
236
```
237

238
### RFC 3986 URL Encoding
239

240
RFC 3986 compliant URL encoding function with stricter encoding than standard `encodeURIComponent`.
241

242
```javascript { .api }
243
/**
244
 * RFC 3986 compliant URL encoding function
245
 * @param {string} str - String to encode
246
 * @returns {string} RFC 3986 encoded string
247
 */
248
function rfc3986(str);
249
```
250

251
**Usage Example:**
252

253
```javascript
254
const { rfc3986 } = require("oauth-sign");
255

256
const encoded = rfc3986("Hello World! (test)");
257
// Result: "Hello%20World%21%20%28test%29"
258

259
// More strict than encodeURIComponent
260
const standard = encodeURIComponent("Hello!");
261
const rfc = rfc3986("Hello!");
262
console.log(standard); // "Hello!"
263
console.log(rfc);      // "Hello%21"
264
```
265

266
### OAuth Signature Base String Generation
267

268
Generates OAuth signature base string according to RFC 5849 with proper parameter normalization.
269

270
```javascript { .api }
271
/**
272
 * Generate OAuth signature base string according to RFC 5849
273
 * @param {string} httpMethod - HTTP method (normalized to uppercase)
274
 * @param {string} base_uri - Base URL for the request
275
 * @param {Object} params - Parameters to include in signature base string
276
 * @returns {string} OAuth signature base string
277
 */
278
function generateBase(httpMethod, base_uri, params);
279
```
280

281
**Usage Example:**
282

283
```javascript
284
const { generateBase } = require("oauth-sign");
285

286
const baseString = generateBase(
287
  'POST',
288
  'https://api.twitter.com/oauth/request_token',
289
  {
290
    oauth_callback: 'http://localhost:3005/callback',
291
    oauth_consumer_key: 'GDdmIQH6jhtmLUypg82g',
292
    oauth_nonce: 'QP70eNmVz8jvdPevU3oJD2AfF7R7odC2XJcn4XlZJqk',
293
    oauth_signature_method: 'HMAC-SHA1',
294
    oauth_timestamp: '1272323042',
295
    oauth_version: '1.0'
296
  }
297
);
298
// Result: normalized and encoded base string for signature generation
299
```
300

301
## Parameter Handling
302

303
OAuth Sign handles complex parameter structures with full OAuth 1.0 compliance:
304

305
### Nested Objects
306

307
Objects in parameters are flattened using bracket notation:
308

309
```javascript
310
const params = {
311
  oauth_consumer_key: 'key',
312
  filter: { number: "-1", active: "true" }
313
};
314
// Becomes: oauth_consumer_key=key&filter[number]=-1&filter[active]=true
315
```
316

317
### Array Values
318

319
Array values are expanded into multiple key-value pairs:
320

321
```javascript
322
const params = {
323
  oauth_consumer_key: 'key',
324
  tags: ['javascript', 'oauth', 'nodejs']
325
};
326
// Becomes: oauth_consumer_key=key&tags=javascript&tags=oauth&tags=nodejs
327
```
328

329
### Empty and Undefined Values
330

331
Empty or undefined parameter values are handled gracefully:
332

333
```javascript
334
const params = {
335
  oauth_consumer_key: 'key',
336
  optional_param: '',
337
  undefined_param: undefined
338
};
339
// Empty strings are included, undefined values are handled safely
340
```
341

342
## Error Handling
343

344
OAuth Sign provides clear error handling for invalid inputs:
345

346
### Unsupported Signature Methods
347

348
```javascript
349
const { sign } = require("oauth-sign");
350

351
try {
352
  sign('INVALID-METHOD', 'GET', 'http://example.com', {}, 'secret');
353
} catch (error) {
354
  console.error(error.message); // "Signature method not supported: INVALID-METHOD"
355
}
356
```
357

358
### Cryptographic Errors
359

360
Invalid private keys or malformed cryptographic inputs will throw Node.js crypto module errors:
361

362
```javascript
363
const { rsasign } = require("oauth-sign");
364

365
try {
366
  rsasign('POST', 'http://example.com', {}, 'invalid_private_key');
367
} catch (error) {
368
  // Handle crypto module errors for invalid keys
369
}
370
```