@md-oss/security 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2026 Mirasaki Development
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @md-oss/security
+
+Cryptographic utilities for encryption, signed URLs, and secure streaming.
+
+## Features
+
+- **AES-256-GCM Encryption** - Secure string and buffer encryption with authentication
+- **Signed URLs** - Generate and verify cryptographically signed URLs with optional expiration
+- **Decryption Streams** - Stream-based decryption for large files with memory efficiency
+- **Range Streaming** - Support for partial file reads
+
+## Installation
+
+```bash
+pnpm add @md-oss/security
+```
+
+## Usage
+
+### Encryption & Decryption
+
+```typescript
+import { generateKey, encrypt, decrypt } from '@md-oss/security';
+
+// Generate a random encryption key (base64 encoded)
+const key = generateKey(32); // 32 bytes for AES-256
+
+// Encrypt a string
+const encrypted = encrypt('Hello, World!', key);
+console.log(encrypted); // Base64 encoded string
+
+// Decrypt it back
+const decrypted = decrypt(encrypted, key);
+console.log(decrypted); // 'Hello, World!'
+
+// Works with buffers too
+const buffer = Buffer.from('Binary data');
+const encryptedBuffer = encrypt(buffer, key);
+const decryptedBuffer = decrypt(encryptedBuffer, key);
+```
+
+#### How It Works
+
+- Uses **AES-256-GCM** (Galois/Counter Mode) for authenticated encryption
+- Generates a random 12-byte IV for each encryption
+- Automatically includes the IV and authentication tag in the encrypted output
+- Returns base64-encoded strings for safe transport
+- Provides authentication to prevent tampering
+
+### Signed URLs
+
+#### Generate Signed URLs
+
+```typescript
+import { generateSignedUrl } from '@md-oss/security';
+
+const secret = 'your-base64-encoded-secret';
+const path = '/api/files/document.pdf';
+const expires = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours from now
+
+const { url, expiresUnixTs, sig } = generateSignedUrl({
+  secret,
+  path,
+  expires
+});
+
+console.log(url); // /api/files/document.pdf?sig=abc123&expires=1234567890
+
+// URLs without expiration
+const permanentUrl = generateSignedUrl({
+  secret,
+  path,
+  expires: null
+});
+console.log(permanentUrl.url); // /api/files/document.pdf?sig=abc123
+```
+
+#### Verify Signed URLs
+
+```typescript
+import { verifySignedUrl } from '@md-oss/security';
+
+const result = verifySignedUrl({
+  secret,
+  path: '/api/files/document.pdf',
+  expires: 1234567890, // UNIX timestamp in seconds
+  sig: 'abc123'
+});
+
+if (result === 'InvalidSignatureError') {
+  console.log('Signature is invalid');
+} else if (result === 'ExpiredSignatureError') {
+  console.log('URL has expired');
+} else {
+  console.log('Verified:', result); // { path, expires, sig }
+}
+```
+
+#### Verify from Request
+
+```typescript
+import { verifySignedUrlFromRequest } from '@md-oss/security';
+
+// In your request handler
+const signedAccess = verifySignedUrlFromRequest({
+  secret: process.env.SIGNED_URL_SECRET || '',
+  expectedPath: req.path,
+  query: req.query
+});
+
+if (signedAccess.type === 'verified') {
+  // URL signature is valid
+  console.log('Access granted');
+} else {
+  // Handle invalid/expired signature
+  console.log('Access denied:', signedAccess.error);
+  // Possible errors: 'MISSING_SIGNATURE' | 'INVALID_SIGNATURE' | 'EXPIRED_SIGNATURE'
+}
+```
+
+#### With Access Control
+
+```typescript
+import { withSignedAccess } from '@md-oss/security';
+
+const result = await withSignedAccess(
+  signedAccess,
+  async () => {
+    // This runs if signature is missing or invalid
+    // Return true to continue without signature
+    // Return error or data to handle differently
+    return true; // Allow access without signature
+  }
+);
+
+if (result instanceof APIError) {
+  // Signature validation failed
+  res.status(result.statusCode).json(result.body);
+} else if (result === true) {
+  // Access granted (either verified or allowed without)
+  // Continue processing
+}
+```
+
+### Decryption Streams
+
+#### Basic Decryption Stream
+
+```typescript
+import { createDecryptionStream } from '@md-oss/security';
+
+const decryptionKey = 'your-base64-encoded-key';
+const filePath = '/path/to/encrypted/file';
+
+const decryptedStream = createDecryptionStream(filePath, decryptionKey);
+
+// Pipe to response for download
+res.setHeader('Content-Type', 'application/octet-stream');
+res.setHeader('Content-Disposition', 'attachment; filename="file.pdf"');
+decryptedStream.pipe(res);
+
+// Or save to file
+import { createWriteStream } from 'node:fs';
+const writeStream = createWriteStream('/path/to/decrypted/file');
+decryptedStream.pipe(writeStream);
+
+// Handle errors
+decryptedStream.on('error', (err) => {
+  console.error('Decryption error:', err);
+});
+```
+
+#### Range Streaming
+
+```typescript
+import { streamWithRange } from '@md-oss/security';
+
+// Stream specific byte range (e.g., for HTTP Range requests)
+const start = 0;
+const end = 1024 * 1024; // 1MB
+
+const rangeStream = streamWithRange(filePath, start, end);
+rangeStream.pipe(res);
+```
+
+## Security Best Practices
+
+### Key Management
+
+```typescript
+// Generate secure random keys
+const encryptionKey = generateKey(32); // 32 bytes for AES-256
+const signingSecret = generateKey(32);
+
+// Store securely (e.g., environment variables, KMS)
+process.env.ENCRYPTION_KEY = encryptionKey;
+process.env.SIGNED_URL_SECRET = signingSecret;
+
+// Never hardcode keys in source code
+// Rotate keys periodically
+// Use different keys for different purposes
+```
+
+### Signed URL Best Practices
+
+```typescript
+// Always set expiration times
+const shortLivedUrl = generateSignedUrl({
+  secret,
+  path,
+  expires: new Date(Date.now() + 30 * 60 * 1000) // 30 minutes
+});
+
+// Use different secrets for different purposes
+const downloadSecret = process.env.DOWNLOAD_SIGNED_URL_SECRET;
+const uploadSecret = process.env.UPLOAD_SIGNED_URL_SECRET;
+
+// Include path in signature to prevent URL manipulation
+// Verify path matches expected value
+const expectedPath = '/api/files/user-123/document.pdf';
+const userProvidedPath = req.query.path;
+
+if (expectedPath !== userProvidedPath) {
+  throw new Error('Path mismatch');
+}
+```
+
+### Encryption Best Practices
+
+```typescript
+// Use strong keys
+const key = generateKey(32); // 32 bytes = 256 bits for AES-256
+
+// Each encryption generates a new random IV
+const data1 = encrypt('secret', key); // Different each time
+const data2 = encrypt('secret', key);
+// data1 !== data2, both decrypt to 'secret'
+
+// Verify authenticity before decrypting
+// AES-GCM provides authentication automatically
+
+// Don't reuse keys across different purposes
+const userDataKey = generateKey(32);
+const sessionDataKey = generateKey(32);
+```
+
+## Types
+
+```typescript
+import type {
+  SignedUrlSchema,
+  VerifySignedUrlFromRequestOptions,
+  SignedAccessError,
+  SignedAccess
+} from '@md-oss/security';
+```
+
+## Error Handling
+
+```typescript
+import { createDecryptionStream } from '@md-oss/security';
+
+const stream = createDecryptionStream(filePath, key);
+
+stream.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('File not found');
+  } else if (err.code === 'ERR_OSSL_EVP_BAD_DECRYPT') {
+    console.error('Decryption failed - wrong key or corrupted data');
+  } else {
+    console.error('Unknown error:', err);
+  }
+});
+
+stream.pipe(destination);
+```
+
+## Performance Considerations
+
+- **Encryption/Decryption**: O(n) where n is data size
+- **Stream Processing**: Memory-efficient for large files (64KB chunks by default)
+- **Signed URLs**: O(1) - constant time verification
+- **Timing-safe Comparison**: Uses `crypto.timingSafeEqual` to prevent timing attacks
+
+## API Reference
+
+### Encryption
+
+- `generateKey(length?: number): string` - Generate base64-encoded random key
+- `encrypt<T>(input: T, key: string): T` - Encrypt string or buffer
+- `decrypt<T>(input: T, key: string): T` - Decrypt string or buffer
+
+### Signed URLs
+
+- `generateSignedUrl(options): { url, expiresUnixTs, sig }`
+- `verifySignedUrl(options): string | { path, expires, sig }`
+- `verifySignedUrlFromRequest(options): SignedAccess`
+- `withSignedAccess(access, callback): Promise`
+
+### Streams
+
+- `createDecryptionStream(filePath, key): PassThrough`
+- `streamWithRange(filePath, start, end): PassThrough`

package/dist/decryption-stream.cjs

@@ -0,0 +1,2 @@
+"use strict";var d=Object.defineProperty;var i=(n,o)=>d(n,"name",{value:o,configurable:!0});var m=require("node:crypto"),h=require("node:fs"),u=require("node:stream");function p(n,o){const e=h.createReadStream(n,{highWaterMark:65536});let a,r;const t=new u.PassThrough;return e.on("error",s=>{t.emit("error",s)}),e.on("end",()=>{t.end()}),e.once("readable",()=>{const s=e.read(28);if(!s)return;a=s.subarray(0,12),r=s.subarray(12,28);const c=m.createDecipheriv("aes-256-gcm",Buffer.from(o,"base64"),a);c.setAuthTag(r),e.pipe(c).pipe(t)}),t}i(p,"createDecryptionStream");function g(n,o,e){const a=h.createReadStream(n,{start:o,end:e,highWaterMark:65536}),r=new u.PassThrough;return a.on("error",t=>{r.emit("error",t)}),a.on("end",()=>{r.end()}),a.pipe(r),r}i(g,"streamWithRange"),exports.createDecryptionStream=p,exports.streamWithRange=g;
+//# sourceMappingURL=decryption-stream.cjs.map

package/dist/decryption-stream.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decryption-stream.cjs","sources":["../src/decryption-stream.ts"],"sourcesContent":["import { createDecipheriv } from 'node:crypto';\nimport { createReadStream } from 'node:fs';\nimport { PassThrough } from 'node:stream';\n\nexport function createDecryptionStream(\n\tfilePath: string,\n\tdecryptionKey: string\n): PassThrough {\n\tconst readStream = createReadStream(filePath, { highWaterMark: 64 * 1024 });\n\n\tlet iv: Buffer;\n\tlet authTag: Buffer;\n\n\tconst passthrough = new PassThrough();\n\n\treadStream.on('error', (error) => {\n\t\tpassthrough.emit('error', error);\n\t});\n\n\treadStream.on('end', () => {\n\t\tpassthrough.end();\n\t});\n\n\treadStream.once('readable', () => {\n\t\tconst header = readStream.read(28);\n\t\tif (!header) return;\n\n\t\tiv = header.subarray(0, 12);\n\t\tauthTag = header.subarray(12, 28);\n\n\t\tconst decipher = createDecipheriv(\n\t\t\t'aes-256-gcm',\n\t\t\tBuffer.from(decryptionKey, 'base64'),\n\t\t\tiv\n\t\t);\n\t\tdecipher.setAuthTag(authTag);\n\n\t\treadStream.pipe(decipher).pipe(passthrough);\n\t});\n\n\treturn passthrough;\n}\n\nexport function streamWithRange(\n\tfilePath: string,\n\tstart: number,\n\tend: number\n): PassThrough {\n\tconst readStream = createReadStream(filePath, {\n\t\tstart,\n\t\tend,\n\t\thighWaterMark: 64 * 1024,\n\t});\n\tconst passthrough = new PassThrough();\n\n\treadStream.on('error', (error) => {\n\t\tpassthrough.emit('error', error);\n\t});\n\n\treadStream.on('end', () => {\n\t\tpassthrough.end();\n\t});\n\n\treadStream.pipe(passthrough);\n\n\treturn passthrough;\n}\n"],"names":["createDecryptionStream","filePath","decryptionKey","readStream","createReadStream","iv","authTag","passthrough","PassThrough","error","header","decipher","createDecipheriv","__name","streamWithRange","start","end"],"mappings":"uKAIO,SAASA,EACfC,EACAC,EACc,CACd,MAAMC,EAAaC,EAAAA,iBAAiBH,EAAU,CAAE,cAAe,MAAW,EAE1E,IAAII,EACAC,EAEJ,MAAMC,EAAc,IAAIC,cAExB,OAAAL,EAAW,GAAG,QAAUM,GAAU,CACjCF,EAAY,KAAK,QAASE,CAAK,CAChC,CAAC,EAEDN,EAAW,GAAG,MAAO,IAAM,CAC1BI,EAAY,IAAA,CACb,CAAC,EAEDJ,EAAW,KAAK,WAAY,IAAM,CACjC,MAAMO,EAASP,EAAW,KAAK,EAAE,EACjC,GAAI,CAACO,EAAQ,OAEbL,EAAKK,EAAO,SAAS,EAAG,EAAE,EAC1BJ,EAAUI,EAAO,SAAS,GAAI,EAAE,EAEhC,MAAMC,EAAWC,EAAAA,iBAChB,cACA,OAAO,KAAKV,EAAe,QAAQ,EACnCG,CAAA,EAEDM,EAAS,WAAWL,CAAO,EAE3BH,EAAW,KAAKQ,CAAQ,EAAE,KAAKJ,CAAW,CAC3C,CAAC,EAEMA,CACR,CArCgBM,EAAAb,EAAA,0BAuCT,SAASc,EACfb,EACAc,EACAC,EACc,CACd,MAAMb,EAAaC,EAAAA,iBAAiBH,EAAU,CAC7C,MAAAc,EACA,IAAAC,EACA,cAAe,KAAK,CACpB,EACKT,EAAc,IAAIC,cAExB,OAAAL,EAAW,GAAG,QAAUM,GAAU,CACjCF,EAAY,KAAK,QAASE,CAAK,CAChC,CAAC,EAEDN,EAAW,GAAG,MAAO,IAAM,CAC1BI,EAAY,IAAA,CACb,CAAC,EAEDJ,EAAW,KAAKI,CAAW,EAEpBA,CACR,CAvBgBM,EAAAC,EAAA"}

package/dist/decryption-stream.d.cts

@@ -0,0 +1,6 @@
+import { PassThrough } from 'node:stream';
+
+declare function createDecryptionStream(filePath: string, decryptionKey: string): PassThrough;
+declare function streamWithRange(filePath: string, start: number, end: number): PassThrough;
+
+export { createDecryptionStream, streamWithRange };

package/dist/decryption-stream.d.mts

@@ -0,0 +1,6 @@
+import { PassThrough } from 'node:stream';
+
+declare function createDecryptionStream(filePath: string, decryptionKey: string): PassThrough;
+declare function streamWithRange(filePath: string, start: number, end: number): PassThrough;
+
+export { createDecryptionStream, streamWithRange };

package/dist/decryption-stream.mjs

@@ -0,0 +1,2 @@
+var p=Object.defineProperty;var s=(o,n)=>p(o,"name",{value:n,configurable:!0});import{createDecipheriv as u}from"node:crypto";import{createReadStream as h}from"node:fs";import{PassThrough as m}from"node:stream";function d(o,n){const r=h(o,{highWaterMark:65536});let t,e;const a=new m;return r.on("error",i=>{a.emit("error",i)}),r.on("end",()=>{a.end()}),r.once("readable",()=>{const i=r.read(28);if(!i)return;t=i.subarray(0,12),e=i.subarray(12,28);const c=u("aes-256-gcm",Buffer.from(n,"base64"),t);c.setAuthTag(e),r.pipe(c).pipe(a)}),a}s(d,"createDecryptionStream");function f(o,n,r){const t=h(o,{start:n,end:r,highWaterMark:65536}),e=new m;return t.on("error",a=>{e.emit("error",a)}),t.on("end",()=>{e.end()}),t.pipe(e),e}s(f,"streamWithRange");export{d as createDecryptionStream,f as streamWithRange};
+//# sourceMappingURL=decryption-stream.mjs.map

package/dist/decryption-stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decryption-stream.mjs","sources":["../src/decryption-stream.ts"],"sourcesContent":["import { createDecipheriv } from 'node:crypto';\nimport { createReadStream } from 'node:fs';\nimport { PassThrough } from 'node:stream';\n\nexport function createDecryptionStream(\n\tfilePath: string,\n\tdecryptionKey: string\n): PassThrough {\n\tconst readStream = createReadStream(filePath, { highWaterMark: 64 * 1024 });\n\n\tlet iv: Buffer;\n\tlet authTag: Buffer;\n\n\tconst passthrough = new PassThrough();\n\n\treadStream.on('error', (error) => {\n\t\tpassthrough.emit('error', error);\n\t});\n\n\treadStream.on('end', () => {\n\t\tpassthrough.end();\n\t});\n\n\treadStream.once('readable', () => {\n\t\tconst header = readStream.read(28);\n\t\tif (!header) return;\n\n\t\tiv = header.subarray(0, 12);\n\t\tauthTag = header.subarray(12, 28);\n\n\t\tconst decipher = createDecipheriv(\n\t\t\t'aes-256-gcm',\n\t\t\tBuffer.from(decryptionKey, 'base64'),\n\t\t\tiv\n\t\t);\n\t\tdecipher.setAuthTag(authTag);\n\n\t\treadStream.pipe(decipher).pipe(passthrough);\n\t});\n\n\treturn passthrough;\n}\n\nexport function streamWithRange(\n\tfilePath: string,\n\tstart: number,\n\tend: number\n): PassThrough {\n\tconst readStream = createReadStream(filePath, {\n\t\tstart,\n\t\tend,\n\t\thighWaterMark: 64 * 1024,\n\t});\n\tconst passthrough = new PassThrough();\n\n\treadStream.on('error', (error) => {\n\t\tpassthrough.emit('error', error);\n\t});\n\n\treadStream.on('end', () => {\n\t\tpassthrough.end();\n\t});\n\n\treadStream.pipe(passthrough);\n\n\treturn passthrough;\n}\n"],"names":["createDecryptionStream","filePath","decryptionKey","readStream","createReadStream","iv","authTag","passthrough","PassThrough","error","header","decipher","createDecipheriv","__name","streamWithRange","start","end"],"mappings":"mNAIO,SAASA,EACfC,EACAC,EACc,CACd,MAAMC,EAAaC,EAAiBH,EAAU,CAAE,cAAe,MAAW,EAE1E,IAAII,EACAC,EAEJ,MAAMC,EAAc,IAAIC,EAExB,OAAAL,EAAW,GAAG,QAAUM,GAAU,CACjCF,EAAY,KAAK,QAASE,CAAK,CAChC,CAAC,EAEDN,EAAW,GAAG,MAAO,IAAM,CAC1BI,EAAY,IAAA,CACb,CAAC,EAEDJ,EAAW,KAAK,WAAY,IAAM,CACjC,MAAMO,EAASP,EAAW,KAAK,EAAE,EACjC,GAAI,CAACO,EAAQ,OAEbL,EAAKK,EAAO,SAAS,EAAG,EAAE,EAC1BJ,EAAUI,EAAO,SAAS,GAAI,EAAE,EAEhC,MAAMC,EAAWC,EAChB,cACA,OAAO,KAAKV,EAAe,QAAQ,EACnCG,CAAA,EAEDM,EAAS,WAAWL,CAAO,EAE3BH,EAAW,KAAKQ,CAAQ,EAAE,KAAKJ,CAAW,CAC3C,CAAC,EAEMA,CACR,CArCgBM,EAAAb,EAAA,0BAuCT,SAASc,EACfb,EACAc,EACAC,EACc,CACd,MAAMb,EAAaC,EAAiBH,EAAU,CAC7C,MAAAc,EACA,IAAAC,EACA,cAAe,KAAK,CACpB,EACKT,EAAc,IAAIC,EAExB,OAAAL,EAAW,GAAG,QAAUM,GAAU,CACjCF,EAAY,KAAK,QAASE,CAAK,CAChC,CAAC,EAEDN,EAAW,GAAG,MAAO,IAAM,CAC1BI,EAAY,IAAA,CACb,CAAC,EAEDJ,EAAW,KAAKI,CAAW,EAEpBA,CACR,CAvBgBM,EAAAC,EAAA"}

package/dist/encryption.cjs

@@ -0,0 +1,2 @@
+"use strict";var g=Object.defineProperty;var a=(e,r)=>g(e,"name",{value:r,configurable:!0});var f=require("node:crypto");function i(e=32){return f.randomBytes(e).toString("hex")}a(i,"generateKey");function p(e,r){const t=f.randomBytes(12),s=Buffer.from(r,"base64"),c=f.createCipheriv("aes-256-gcm",s,t),u=typeof e=="string"?Buffer.from(e,"utf8"):e,y=Buffer.concat([c.update(u),c.final()]),n=c.getAuthTag(),o=Buffer.concat([t,n,y]);return typeof e=="string"?o.toString("base64"):o}a(p,"encrypt");function d(e,r){const t=typeof e=="string"?Buffer.from(e,"base64"):e,s=t.subarray(0,12),c=t.subarray(12,28),u=t.subarray(28),y=Buffer.from(r,"base64"),n=f.createDecipheriv("aes-256-gcm",y,s);n.setAuthTag(c);const o=Buffer.concat([n.update(u),n.final()]);return typeof e=="string"?o.toString("utf8"):o}a(d,"decrypt"),exports.decrypt=d,exports.encrypt=p,exports.generateKey=i;
+//# sourceMappingURL=encryption.cjs.map

package/dist/encryption.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.cjs","sources":["../src/encryption.ts"],"sourcesContent":["import crypto from 'node:crypto';\n\nexport function generateKey(length = 32): string {\n\treturn crypto.randomBytes(length).toString('hex');\n}\n\nexport function encrypt<T extends string | Buffer>(\n\tinput: T,\n\tencryptionKey: string\n): T {\n\tconst iv = crypto.randomBytes(12);\n\tconst key = Buffer.from(encryptionKey, 'base64');\n\tconst cipher = crypto.createCipheriv('aes-256-gcm', key, iv);\n\n\tconst bufferInput =\n\t\ttypeof input === 'string' ? Buffer.from(input, 'utf8') : input;\n\tconst encrypted = Buffer.concat([cipher.update(bufferInput), cipher.final()]);\n\tconst authTag = cipher.getAuthTag();\n\n\tconst output = Buffer.concat([iv, authTag, encrypted]);\n\n\treturn typeof input === 'string'\n\t\t? (output.toString('base64') as T)\n\t\t: (output as T);\n}\n\nexport function decrypt<T extends string | Buffer>(\n\tinput: T,\n\tdecryptionKey: string\n): T {\n\tconst encryptedBuffer =\n\t\ttypeof input === 'string'\n\t\t\t? Buffer.from(input, 'base64')\n\t\t\t: (input as Buffer);\n\n\tconst iv = encryptedBuffer.subarray(0, 12);\n\tconst authTag = encryptedBuffer.subarray(12, 28);\n\tconst encryptedData = encryptedBuffer.subarray(28);\n\n\tconst key = Buffer.from(decryptionKey, 'base64');\n\tconst decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);\n\tdecipher.setAuthTag(authTag);\n\n\tconst decrypted = Buffer.concat([\n\t\tdecipher.update(encryptedData),\n\t\tdecipher.final(),\n\t]);\n\n\treturn typeof input === 'string'\n\t\t? (decrypted.toString('utf8') as T)\n\t\t: (decrypted as T);\n}\n"],"names":["generateKey","length","crypto","__name","encrypt","input","encryptionKey","iv","key","cipher","bufferInput","encrypted","authTag","output","decrypt","decryptionKey","encryptedBuffer","encryptedData","decipher","decrypted"],"mappings":"yHAEO,SAASA,EAAYC,EAAS,GAAY,CAChD,OAAOC,EAAO,YAAYD,CAAM,EAAE,SAAS,KAAK,CACjD,CAFgBE,EAAAH,EAAA,eAIT,SAASI,EACfC,EACAC,EACI,CACJ,MAAMC,EAAKL,EAAO,YAAY,EAAE,EAC1BM,EAAM,OAAO,KAAKF,EAAe,QAAQ,EACzCG,EAASP,EAAO,eAAe,cAAeM,EAAKD,CAAE,EAErDG,EACL,OAAOL,GAAU,SAAW,OAAO,KAAKA,EAAO,MAAM,EAAIA,EACpDM,EAAY,OAAO,OAAO,CAACF,EAAO,OAAOC,CAAW,EAAGD,EAAO,MAAA,CAAO,CAAC,EACtEG,EAAUH,EAAO,WAAA,EAEjBI,EAAS,OAAO,OAAO,CAACN,EAAIK,EAASD,CAAS,CAAC,EAErD,OAAO,OAAON,GAAU,SACpBQ,EAAO,SAAS,QAAQ,EACxBA,CACL,CAlBgBV,EAAAC,EAAA,WAoBT,SAASU,EACfT,EACAU,EACI,CACJ,MAAMC,EACL,OAAOX,GAAU,SACd,OAAO,KAAKA,EAAO,QAAQ,EAC1BA,EAECE,EAAKS,EAAgB,SAAS,EAAG,EAAE,EACnCJ,EAAUI,EAAgB,SAAS,GAAI,EAAE,EACzCC,EAAgBD,EAAgB,SAAS,EAAE,EAE3CR,EAAM,OAAO,KAAKO,EAAe,QAAQ,EACzCG,EAAWhB,EAAO,iBAAiB,cAAeM,EAAKD,CAAE,EAC/DW,EAAS,WAAWN,CAAO,EAE3B,MAAMO,EAAY,OAAO,OAAO,CAC/BD,EAAS,OAAOD,CAAa,EAC7BC,EAAS,MAAA,CAAM,CACf,EAED,OAAO,OAAOb,GAAU,SACpBc,EAAU,SAAS,MAAM,EACzBA,CACL,CAzBgBhB,EAAAW,EAAA"}

package/dist/encryption.d.cts

@@ -0,0 +1,5 @@
+declare function generateKey(length?: number): string;
+declare function encrypt<T extends string | Buffer>(input: T, encryptionKey: string): T;
+declare function decrypt<T extends string | Buffer>(input: T, decryptionKey: string): T;
+
+export { decrypt, encrypt, generateKey };

package/dist/encryption.d.mts

@@ -0,0 +1,5 @@
+declare function generateKey(length?: number): string;
+declare function encrypt<T extends string | Buffer>(input: T, encryptionKey: string): T;
+declare function decrypt<T extends string | Buffer>(input: T, decryptionKey: string): T;
+
+export { decrypt, encrypt, generateKey };

package/dist/encryption.mjs

@@ -0,0 +1,2 @@
+var g=Object.defineProperty;var f=(t,r)=>g(t,"name",{value:r,configurable:!0});import a from"node:crypto";function i(t=32){return a.randomBytes(t).toString("hex")}f(i,"generateKey");function p(t,r){const e=a.randomBytes(12),s=Buffer.from(r,"base64"),o=a.createCipheriv("aes-256-gcm",s,e),u=typeof t=="string"?Buffer.from(t,"utf8"):t,y=Buffer.concat([o.update(u),o.final()]),c=o.getAuthTag(),n=Buffer.concat([e,c,y]);return typeof t=="string"?n.toString("base64"):n}f(p,"encrypt");function d(t,r){const e=typeof t=="string"?Buffer.from(t,"base64"):t,s=e.subarray(0,12),o=e.subarray(12,28),u=e.subarray(28),y=Buffer.from(r,"base64"),c=a.createDecipheriv("aes-256-gcm",y,s);c.setAuthTag(o);const n=Buffer.concat([c.update(u),c.final()]);return typeof t=="string"?n.toString("utf8"):n}f(d,"decrypt");export{d as decrypt,p as encrypt,i as generateKey};
+//# sourceMappingURL=encryption.mjs.map

package/dist/encryption.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.mjs","sources":["../src/encryption.ts"],"sourcesContent":["import crypto from 'node:crypto';\n\nexport function generateKey(length = 32): string {\n\treturn crypto.randomBytes(length).toString('hex');\n}\n\nexport function encrypt<T extends string | Buffer>(\n\tinput: T,\n\tencryptionKey: string\n): T {\n\tconst iv = crypto.randomBytes(12);\n\tconst key = Buffer.from(encryptionKey, 'base64');\n\tconst cipher = crypto.createCipheriv('aes-256-gcm', key, iv);\n\n\tconst bufferInput =\n\t\ttypeof input === 'string' ? Buffer.from(input, 'utf8') : input;\n\tconst encrypted = Buffer.concat([cipher.update(bufferInput), cipher.final()]);\n\tconst authTag = cipher.getAuthTag();\n\n\tconst output = Buffer.concat([iv, authTag, encrypted]);\n\n\treturn typeof input === 'string'\n\t\t? (output.toString('base64') as T)\n\t\t: (output as T);\n}\n\nexport function decrypt<T extends string | Buffer>(\n\tinput: T,\n\tdecryptionKey: string\n): T {\n\tconst encryptedBuffer =\n\t\ttypeof input === 'string'\n\t\t\t? Buffer.from(input, 'base64')\n\t\t\t: (input as Buffer);\n\n\tconst iv = encryptedBuffer.subarray(0, 12);\n\tconst authTag = encryptedBuffer.subarray(12, 28);\n\tconst encryptedData = encryptedBuffer.subarray(28);\n\n\tconst key = Buffer.from(decryptionKey, 'base64');\n\tconst decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);\n\tdecipher.setAuthTag(authTag);\n\n\tconst decrypted = Buffer.concat([\n\t\tdecipher.update(encryptedData),\n\t\tdecipher.final(),\n\t]);\n\n\treturn typeof input === 'string'\n\t\t? (decrypted.toString('utf8') as T)\n\t\t: (decrypted as T);\n}\n"],"names":["generateKey","length","crypto","__name","encrypt","input","encryptionKey","iv","key","cipher","bufferInput","encrypted","authTag","output","decrypt","decryptionKey","encryptedBuffer","encryptedData","decipher","decrypted"],"mappings":"0GAEO,SAASA,EAAYC,EAAS,GAAY,CAChD,OAAOC,EAAO,YAAYD,CAAM,EAAE,SAAS,KAAK,CACjD,CAFgBE,EAAAH,EAAA,eAIT,SAASI,EACfC,EACAC,EACI,CACJ,MAAMC,EAAKL,EAAO,YAAY,EAAE,EAC1BM,EAAM,OAAO,KAAKF,EAAe,QAAQ,EACzCG,EAASP,EAAO,eAAe,cAAeM,EAAKD,CAAE,EAErDG,EACL,OAAOL,GAAU,SAAW,OAAO,KAAKA,EAAO,MAAM,EAAIA,EACpDM,EAAY,OAAO,OAAO,CAACF,EAAO,OAAOC,CAAW,EAAGD,EAAO,MAAA,CAAO,CAAC,EACtEG,EAAUH,EAAO,WAAA,EAEjBI,EAAS,OAAO,OAAO,CAACN,EAAIK,EAASD,CAAS,CAAC,EAErD,OAAO,OAAON,GAAU,SACpBQ,EAAO,SAAS,QAAQ,EACxBA,CACL,CAlBgBV,EAAAC,EAAA,WAoBT,SAASU,EACfT,EACAU,EACI,CACJ,MAAMC,EACL,OAAOX,GAAU,SACd,OAAO,KAAKA,EAAO,QAAQ,EAC1BA,EAECE,EAAKS,EAAgB,SAAS,EAAG,EAAE,EACnCJ,EAAUI,EAAgB,SAAS,GAAI,EAAE,EACzCC,EAAgBD,EAAgB,SAAS,EAAE,EAE3CR,EAAM,OAAO,KAAKO,EAAe,QAAQ,EACzCG,EAAWhB,EAAO,iBAAiB,cAAeM,EAAKD,CAAE,EAC/DW,EAAS,WAAWN,CAAO,EAE3B,MAAMO,EAAY,OAAO,OAAO,CAC/BD,EAAS,OAAOD,CAAa,EAC7BC,EAAS,MAAA,CAAM,CACf,EAED,OAAO,OAAOb,GAAU,SACpBc,EAAU,SAAS,MAAM,EACzBA,CACL,CAzBgBhB,EAAAW,EAAA"}

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var i=require("./decryption-stream.cjs"),r=require("./encryption.cjs"),e=require("./signed-urls.cjs");require("node:crypto"),require("node:fs"),require("node:stream"),require("@md-oss/common/api/errors"),require("@md-oss/common/api/status-codes"),exports.createDecryptionStream=i.createDecryptionStream,exports.streamWithRange=i.streamWithRange,exports.decrypt=r.decrypt,exports.encrypt=r.encrypt,exports.generateKey=r.generateKey,exports.generateSignedUrl=e.generateSignedUrl,exports.verifySignedUrl=e.verifySignedUrl,exports.verifySignedUrlFromRequest=e.verifySignedUrlFromRequest,exports.withSignedAccess=e.withSignedAccess;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/index.d.cts

@@ -0,0 +1,5 @@
+export { createDecryptionStream, streamWithRange } from './decryption-stream.cjs';
+export { decrypt, encrypt, generateKey } from './encryption.cjs';
+export { SignedAccess, SignedAccessError, VerifySignedUrlFromRequestOptions, generateSignedUrl, verifySignedUrl, verifySignedUrlFromRequest, withSignedAccess } from './signed-urls.cjs';
+import 'node:stream';
+import '@md-oss/common/api/errors';

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+export { createDecryptionStream, streamWithRange } from './decryption-stream.mjs';
+export { decrypt, encrypt, generateKey } from './encryption.mjs';
+export { SignedAccess, SignedAccessError, VerifySignedUrlFromRequestOptions, generateSignedUrl, verifySignedUrl, verifySignedUrlFromRequest, withSignedAccess } from './signed-urls.mjs';
+import 'node:stream';
+import '@md-oss/common/api/errors';

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{createDecryptionStream as n,streamWithRange as g}from"./decryption-stream.mjs";import{decrypt as c,encrypt as y,generateKey as d}from"./encryption.mjs";import{generateSignedUrl as S,verifySignedUrl as s,verifySignedUrlFromRequest as l,withSignedAccess as x}from"./signed-urls.mjs";import"node:crypto";import"node:fs";import"node:stream";import"@md-oss/common/api/errors";import"@md-oss/common/api/status-codes";export{n as createDecryptionStream,c as decrypt,y as encrypt,d as generateKey,S as generateSignedUrl,g as streamWithRange,s as verifySignedUrl,l as verifySignedUrlFromRequest,x as withSignedAccess};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/signed-urls.cjs

@@ -0,0 +1,2 @@
+"use strict";var S=Object.defineProperty;var u=(r,e)=>S(r,"name",{value:e,configurable:!0});var a=require("node:crypto"),I=require("@md-oss/common/api/errors"),d=require("@md-oss/common/api/status-codes");const f=u((r,e,t)=>{const i=t===null?e:`${e}:${t}`;return a.createHmac("sha256",Buffer.from(r,"base64")).update(i).digest("hex")},"generateSignature");function g({secret:r,path:e,expires:t}){const i=t?t.valueOf():null,n=i?Math.floor(i/1e3):null,o=f(r,e,n);let l=`${e}?sig=${o}`;return n!==null&&(l+=`&expires=${n}`),{url:l,expiresUnixTs:n,sig:o}}u(g,"generateSignedUrl");function s({secret:r,path:e,expires:t,sig:i}){const n=f(r,e,t),o=Math.floor(Date.now()/1e3),l=typeof i!="string"?a.timingSafeEqual(Buffer.from(JSON.stringify(i)),Buffer.from(n)):i===n;return typeof i!="string"||!l?"InvalidSignatureError":t!==null&&(typeof t!="number"||t<o)?"ExpiredSignatureError":{path:e,expires:typeof t=="number"?t:o,sig:n}}u(s,"verifySignedUrl");function v({secret:r,expectedPath:e,query:t}){const{expires:i,sig:n}=t||{};if(!n)return{type:"invalid",error:"MISSING_SIGNATURE"};let o;try{o=s({secret:r,path:e,expires:i?Number(i):null,sig:n})}catch{return{type:"invalid",error:"INVALID_SIGNATURE"}}return typeof o=="string"?{type:"invalid",error:o==="InvalidSignatureError"?"INVALID_SIGNATURE":"EXPIRED_SIGNATURE"}:{type:"verified",sig:o.sig,expires:o.expires??null}}u(v,"verifySignedUrlFromRequest");function E(r,e){return r.type==="verified"?Promise.resolve(!0):r.error==="MISSING_SIGNATURE"||r.error!=="INVALID_SIGNATURE"&&r.error!=="EXPIRED_SIGNATURE"?e():Promise.resolve(new I.APIError(d.statusCodes.FORBIDDEN,{code:r.error,message:r.error==="INVALID_SIGNATURE"?"The provided signature is invalid.":"The provided signature has expired.",details:{error:r.error}}))}u(E,"withSignedAccess"),exports.generateSignedUrl=g,exports.verifySignedUrl=s,exports.verifySignedUrlFromRequest=v,exports.withSignedAccess=E;
+//# sourceMappingURL=signed-urls.cjs.map

package/dist/signed-urls.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-urls.cjs","sources":["../src/signed-urls.ts"],"sourcesContent":["import crypto from 'node:crypto';\nimport { APIError } from '@md-oss/common/api/errors';\nimport { statusCodes } from '@md-oss/common/api/status-codes';\n\ntype SignedUrlSchema = {\n\texpires?: number | undefined;\n\tsig?: string | undefined;\n\tref?: string | undefined;\n};\n\nconst generateSignature = (\n\tsecret: string,\n\tpath: string,\n\texpires: number | null\n): string => {\n\tconst payload = expires === null ? path : `${path}:${expires}`;\n\treturn crypto\n\t\t.createHmac('sha256', Buffer.from(secret, 'base64'))\n\t\t.update(payload)\n\t\t.digest('hex');\n};\n\nexport function generateSignedUrl({\n\tsecret,\n\tpath,\n\texpires,\n}: {\n\tsecret: string;\n\tpath: string;\n\texpires: Date | null;\n}): {\n\t/**\n\t * The signed URL.\n\t */\n\turl: string;\n\t/**\n\t * The expiration timestamp in UNIX format (seconds).\n\t */\n\texpiresUnixTs: number | null;\n\t/**\n\t * The signature used to verify the URL.\n\t */\n\tsig: string;\n} {\n\tconst expiresTs = expires ? expires.valueOf() : null;\n\tconst expiresTsUnix = expiresTs ? Math.floor(expiresTs / 1000) : null;\n\tconst signature = generateSignature(secret, path, expiresTsUnix);\n\n\tlet url = `${path}?sig=${signature}`;\n\n\tif (expiresTsUnix !== null) {\n\t\turl += `&expires=${expiresTsUnix}`;\n\t}\n\n\treturn {\n\t\turl,\n\t\texpiresUnixTs: expiresTsUnix,\n\t\tsig: signature,\n\t};\n}\n\nexport function verifySignedUrl({\n\tsecret,\n\tpath,\n\texpires,\n\tsig,\n}: {\n\t/**\n\t * The secret used to generate the signature.\n\t */\n\tsecret: string;\n\t/**\n\t * The path of the signed URL.\n\t */\n\tpath: string;\n\t/**\n\t * The expiration to verify against, in UNIX timestamp format (seconds).\n\t */\n\texpires: number | null;\n\t/**\n\t * The signature to verify.\n\t */\n\tsig?: unknown;\n}):\n\t| 'InvalidSignatureError'\n\t| 'ExpiredSignatureError'\n\t| {\n\t\t\tpath: string;\n\t\t\texpires: number;\n\t\t\tsig: string;\n\t  } {\n\tconst expectedSig = generateSignature(secret, path, expires);\n\tconst now = Math.floor(Date.now() / 1000);\n\tconst match =\n\t\ttypeof sig !== 'string'\n\t\t\t? crypto.timingSafeEqual(\n\t\t\t\t\tBuffer.from(JSON.stringify(sig)),\n\t\t\t\t\tBuffer.from(expectedSig)\n\t\t\t\t)\n\t\t\t: sig === expectedSig;\n\n\tif (typeof sig !== 'string' || !match) {\n\t\treturn 'InvalidSignatureError';\n\t}\n\n\tif (expires !== null && (typeof expires !== 'number' || expires < now)) {\n\t\treturn 'ExpiredSignatureError';\n\t}\n\n\treturn {\n\t\tpath,\n\t\texpires: typeof expires === 'number' ? expires : now,\n\t\tsig: expectedSig,\n\t};\n}\n\nexport type VerifySignedUrlFromRequestOptions = {\n\t/** The expected path to verify (must match what was originally signed) */\n\texpectedPath: string;\n\t/** The query object */\n\tquery: SignedUrlSchema | undefined;\n\t/** The secret used to verify the signature */\n\tsecret: string;\n};\n\nexport type SignedAccessError =\n\t| 'MISSING_SIGNATURE'\n\t| 'INVALID_SIGNATURE'\n\t| 'EXPIRED_SIGNATURE';\nexport type SignedAccess =\n\t| {\n\t\t\ttype: 'verified';\n\t\t\tsig: string;\n\t\t\texpires: number | null;\n\t  }\n\t| {\n\t\t\ttype: 'invalid';\n\t\t\terror: SignedAccessError;\n\t  };\n\nexport function verifySignedUrlFromRequest({\n\tsecret,\n\texpectedPath,\n\tquery,\n}: VerifySignedUrlFromRequestOptions): SignedAccess {\n\tconst { expires, sig } = query || {};\n\n\tif (!sig) {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror: 'MISSING_SIGNATURE',\n\t\t};\n\t}\n\n\tlet result: ReturnType<typeof verifySignedUrl>;\n\ttry {\n\t\tresult = verifySignedUrl({\n\t\t\tsecret,\n\t\t\tpath: expectedPath,\n\t\t\texpires: expires ? Number(expires) : null,\n\t\t\tsig,\n\t\t});\n\t} catch {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror: 'INVALID_SIGNATURE',\n\t\t};\n\t}\n\n\tif (typeof result === 'string') {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror:\n\t\t\t\tresult === 'InvalidSignatureError'\n\t\t\t\t\t? 'INVALID_SIGNATURE'\n\t\t\t\t\t: 'EXPIRED_SIGNATURE',\n\t\t};\n\t}\n\n\treturn {\n\t\ttype: 'verified',\n\t\tsig: result.sig,\n\t\texpires: result.expires ?? null,\n\t};\n}\n\nexport function withSignedAccess<T>(\n\tsignedAccess:\n\t\t| SignedAccess\n\t\t| {\n\t\t\t\ttype: 'invalid';\n\t\t\t\terror: string;\n\t\t  },\n\tnoSignedAccessCheck: () => Promise<true | T>\n): Promise<true | T | APIError> {\n\tif (signedAccess.type === 'verified') {\n\t\treturn Promise.resolve(true);\n\t}\n\n\tif (\n\t\tsignedAccess.error === 'MISSING_SIGNATURE' ||\n\t\t(signedAccess.error !== 'INVALID_SIGNATURE' &&\n\t\t\tsignedAccess.error !== 'EXPIRED_SIGNATURE')\n\t) {\n\t\treturn noSignedAccessCheck();\n\t}\n\n\treturn Promise.resolve(\n\t\tnew APIError(statusCodes.FORBIDDEN, {\n\t\t\tcode: signedAccess.error,\n\t\t\tmessage:\n\t\t\t\tsignedAccess.error === 'INVALID_SIGNATURE'\n\t\t\t\t\t? 'The provided signature is invalid.'\n\t\t\t\t\t: 'The provided signature has expired.',\n\t\t\tdetails: {\n\t\t\t\terror: signedAccess.error,\n\t\t\t},\n\t\t})\n\t);\n}\n"],"names":["generateSignature","__name","secret","path","expires","payload","crypto","generateSignedUrl","expiresTs","expiresTsUnix","signature","url","verifySignedUrl","sig","expectedSig","now","match","verifySignedUrlFromRequest","expectedPath","query","result","withSignedAccess","signedAccess","noSignedAccessCheck","APIError","statusCodes"],"mappings":"6MAUA,MAAMA,EAAoBC,EAAA,CACzBC,EACAC,EACAC,IACY,CACZ,MAAMC,EAAUD,IAAY,KAAOD,EAAO,GAAGA,CAAI,IAAIC,CAAO,GAC5D,OAAOE,EACL,WAAW,SAAU,OAAO,KAAKJ,EAAQ,QAAQ,CAAC,EAClD,OAAOG,CAAO,EACd,OAAO,KAAK,CACf,EAV0B,qBAYnB,SAASE,EAAkB,CACjC,OAAAL,EACA,KAAAC,EACA,QAAAC,CACD,EAiBE,CACD,MAAMI,EAAYJ,EAAUA,EAAQ,QAAA,EAAY,KAC1CK,EAAgBD,EAAY,KAAK,MAAMA,EAAY,GAAI,EAAI,KAC3DE,EAAYV,EAAkBE,EAAQC,EAAMM,CAAa,EAE/D,IAAIE,EAAM,GAAGR,CAAI,QAAQO,CAAS,GAElC,OAAID,IAAkB,OACrBE,GAAO,YAAYF,CAAa,IAG1B,CACN,IAAAE,EACA,cAAeF,EACf,IAAKC,CAAA,CAEP,CArCgBT,EAAAM,EAAA,qBAuCT,SAASK,EAAgB,CAC/B,OAAAV,EACA,KAAAC,EACA,QAAAC,EACA,IAAAS,CACD,EAwBK,CACJ,MAAMC,EAAcd,EAAkBE,EAAQC,EAAMC,CAAO,EACrDW,EAAM,KAAK,MAAM,KAAK,IAAA,EAAQ,GAAI,EAClCC,EACL,OAAOH,GAAQ,SACZP,EAAO,gBACP,OAAO,KAAK,KAAK,UAAUO,CAAG,CAAC,EAC/B,OAAO,KAAKC,CAAW,CAAA,EAEvBD,IAAQC,EAEZ,OAAI,OAAOD,GAAQ,UAAY,CAACG,EACxB,wBAGJZ,IAAY,OAAS,OAAOA,GAAY,UAAYA,EAAUW,GAC1D,wBAGD,CACN,KAAAZ,EACA,QAAS,OAAOC,GAAY,SAAWA,EAAUW,EACjD,IAAKD,CAAA,CAEP,CArDgBb,EAAAW,EAAA,mBA+ET,SAASK,EAA2B,CAC1C,OAAAf,EACA,aAAAgB,EACA,MAAAC,CACD,EAAoD,CACnD,KAAM,CAAE,QAAAf,EAAS,IAAAS,CAAA,EAAQM,GAAS,CAAA,EAElC,GAAI,CAACN,EACJ,MAAO,CACN,KAAM,UACN,MAAO,mBAAA,EAIT,IAAIO,EACJ,GAAI,CACHA,EAASR,EAAgB,CACxB,OAAAV,EACA,KAAMgB,EACN,QAASd,EAAU,OAAOA,CAAO,EAAI,KACrC,IAAAS,CAAA,CACA,CACF,MAAQ,CACP,MAAO,CACN,KAAM,UACN,MAAO,mBAAA,CAET,CAEA,OAAI,OAAOO,GAAW,SACd,CACN,KAAM,UACN,MACCA,IAAW,wBACR,oBACA,mBAAA,EAIC,CACN,KAAM,WACN,IAAKA,EAAO,IACZ,QAASA,EAAO,SAAW,IAAA,CAE7B,CA5CgBnB,EAAAgB,EAAA,8BA8CT,SAASI,EACfC,EAMAC,EAC+B,CAC/B,OAAID,EAAa,OAAS,WAClB,QAAQ,QAAQ,EAAI,EAI3BA,EAAa,QAAU,qBACtBA,EAAa,QAAU,qBACvBA,EAAa,QAAU,oBAEjBC,EAAA,EAGD,QAAQ,QACd,IAAIC,EAAAA,SAASC,EAAAA,YAAY,UAAW,CACnC,KAAMH,EAAa,MACnB,QACCA,EAAa,QAAU,oBACpB,qCACA,sCACJ,QAAS,CACR,MAAOA,EAAa,KAAA,CACrB,CACA,CAAA,CAEH,CAjCgBrB,EAAAoB,EAAA"}

package/dist/signed-urls.d.cts

@@ -0,0 +1,72 @@
+import { APIError } from '@md-oss/common/api/errors';
+
+type SignedUrlSchema = {
+    expires?: number | undefined;
+    sig?: string | undefined;
+    ref?: string | undefined;
+};
+declare function generateSignedUrl({ secret, path, expires, }: {
+    secret: string;
+    path: string;
+    expires: Date | null;
+}): {
+    /**
+     * The signed URL.
+     */
+    url: string;
+    /**
+     * The expiration timestamp in UNIX format (seconds).
+     */
+    expiresUnixTs: number | null;
+    /**
+     * The signature used to verify the URL.
+     */
+    sig: string;
+};
+declare function verifySignedUrl({ secret, path, expires, sig, }: {
+    /**
+     * The secret used to generate the signature.
+     */
+    secret: string;
+    /**
+     * The path of the signed URL.
+     */
+    path: string;
+    /**
+     * The expiration to verify against, in UNIX timestamp format (seconds).
+     */
+    expires: number | null;
+    /**
+     * The signature to verify.
+     */
+    sig?: unknown;
+}): 'InvalidSignatureError' | 'ExpiredSignatureError' | {
+    path: string;
+    expires: number;
+    sig: string;
+};
+type VerifySignedUrlFromRequestOptions = {
+    /** The expected path to verify (must match what was originally signed) */
+    expectedPath: string;
+    /** The query object */
+    query: SignedUrlSchema | undefined;
+    /** The secret used to verify the signature */
+    secret: string;
+};
+type SignedAccessError = 'MISSING_SIGNATURE' | 'INVALID_SIGNATURE' | 'EXPIRED_SIGNATURE';
+type SignedAccess = {
+    type: 'verified';
+    sig: string;
+    expires: number | null;
+} | {
+    type: 'invalid';
+    error: SignedAccessError;
+};
+declare function verifySignedUrlFromRequest({ secret, expectedPath, query, }: VerifySignedUrlFromRequestOptions): SignedAccess;
+declare function withSignedAccess<T>(signedAccess: SignedAccess | {
+    type: 'invalid';
+    error: string;
+}, noSignedAccessCheck: () => Promise<true | T>): Promise<true | T | APIError>;
+
+export { generateSignedUrl, verifySignedUrl, verifySignedUrlFromRequest, withSignedAccess };
+export type { SignedAccess, SignedAccessError, VerifySignedUrlFromRequestOptions };

package/dist/signed-urls.d.mts

@@ -0,0 +1,72 @@
+import { APIError } from '@md-oss/common/api/errors';
+
+type SignedUrlSchema = {
+    expires?: number | undefined;
+    sig?: string | undefined;
+    ref?: string | undefined;
+};
+declare function generateSignedUrl({ secret, path, expires, }: {
+    secret: string;
+    path: string;
+    expires: Date | null;
+}): {
+    /**
+     * The signed URL.
+     */
+    url: string;
+    /**
+     * The expiration timestamp in UNIX format (seconds).
+     */
+    expiresUnixTs: number | null;
+    /**
+     * The signature used to verify the URL.
+     */
+    sig: string;
+};
+declare function verifySignedUrl({ secret, path, expires, sig, }: {
+    /**
+     * The secret used to generate the signature.
+     */
+    secret: string;
+    /**
+     * The path of the signed URL.
+     */
+    path: string;
+    /**
+     * The expiration to verify against, in UNIX timestamp format (seconds).
+     */
+    expires: number | null;
+    /**
+     * The signature to verify.
+     */
+    sig?: unknown;
+}): 'InvalidSignatureError' | 'ExpiredSignatureError' | {
+    path: string;
+    expires: number;
+    sig: string;
+};
+type VerifySignedUrlFromRequestOptions = {
+    /** The expected path to verify (must match what was originally signed) */
+    expectedPath: string;
+    /** The query object */
+    query: SignedUrlSchema | undefined;
+    /** The secret used to verify the signature */
+    secret: string;
+};
+type SignedAccessError = 'MISSING_SIGNATURE' | 'INVALID_SIGNATURE' | 'EXPIRED_SIGNATURE';
+type SignedAccess = {
+    type: 'verified';
+    sig: string;
+    expires: number | null;
+} | {
+    type: 'invalid';
+    error: SignedAccessError;
+};
+declare function verifySignedUrlFromRequest({ secret, expectedPath, query, }: VerifySignedUrlFromRequestOptions): SignedAccess;
+declare function withSignedAccess<T>(signedAccess: SignedAccess | {
+    type: 'invalid';
+    error: string;
+}, noSignedAccessCheck: () => Promise<true | T>): Promise<true | T | APIError>;
+
+export { generateSignedUrl, verifySignedUrl, verifySignedUrlFromRequest, withSignedAccess };
+export type { SignedAccess, SignedAccessError, VerifySignedUrlFromRequestOptions };

package/dist/signed-urls.mjs

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var u=(r,e)=>s(r,"name",{value:e,configurable:!0});import l from"node:crypto";import{APIError as S}from"@md-oss/common/api/errors";import{statusCodes as p}from"@md-oss/common/api/status-codes";const a=u((r,e,t)=>{const n=t===null?e:`${e}:${t}`;return l.createHmac("sha256",Buffer.from(r,"base64")).update(n).digest("hex")},"generateSignature");function d({secret:r,path:e,expires:t}){const n=t?t.valueOf():null,i=n?Math.floor(n/1e3):null,o=a(r,e,i);let f=`${e}?sig=${o}`;return i!==null&&(f+=`&expires=${i}`),{url:f,expiresUnixTs:i,sig:o}}u(d,"generateSignedUrl");function I({secret:r,path:e,expires:t,sig:n}){const i=a(r,e,t),o=Math.floor(Date.now()/1e3),f=typeof n!="string"?l.timingSafeEqual(Buffer.from(JSON.stringify(n)),Buffer.from(i)):n===i;return typeof n!="string"||!f?"InvalidSignatureError":t!==null&&(typeof t!="number"||t<o)?"ExpiredSignatureError":{path:e,expires:typeof t=="number"?t:o,sig:i}}u(I,"verifySignedUrl");function m({secret:r,expectedPath:e,query:t}){const{expires:n,sig:i}=t||{};if(!i)return{type:"invalid",error:"MISSING_SIGNATURE"};let o;try{o=I({secret:r,path:e,expires:n?Number(n):null,sig:i})}catch{return{type:"invalid",error:"INVALID_SIGNATURE"}}return typeof o=="string"?{type:"invalid",error:o==="InvalidSignatureError"?"INVALID_SIGNATURE":"EXPIRED_SIGNATURE"}:{type:"verified",sig:o.sig,expires:o.expires??null}}u(m,"verifySignedUrlFromRequest");function E(r,e){return r.type==="verified"?Promise.resolve(!0):r.error==="MISSING_SIGNATURE"||r.error!=="INVALID_SIGNATURE"&&r.error!=="EXPIRED_SIGNATURE"?e():Promise.resolve(new S(p.FORBIDDEN,{code:r.error,message:r.error==="INVALID_SIGNATURE"?"The provided signature is invalid.":"The provided signature has expired.",details:{error:r.error}}))}u(E,"withSignedAccess");export{d as generateSignedUrl,I as verifySignedUrl,m as verifySignedUrlFromRequest,E as withSignedAccess};
+//# sourceMappingURL=signed-urls.mjs.map

package/dist/signed-urls.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-urls.mjs","sources":["../src/signed-urls.ts"],"sourcesContent":["import crypto from 'node:crypto';\nimport { APIError } from '@md-oss/common/api/errors';\nimport { statusCodes } from '@md-oss/common/api/status-codes';\n\ntype SignedUrlSchema = {\n\texpires?: number | undefined;\n\tsig?: string | undefined;\n\tref?: string | undefined;\n};\n\nconst generateSignature = (\n\tsecret: string,\n\tpath: string,\n\texpires: number | null\n): string => {\n\tconst payload = expires === null ? path : `${path}:${expires}`;\n\treturn crypto\n\t\t.createHmac('sha256', Buffer.from(secret, 'base64'))\n\t\t.update(payload)\n\t\t.digest('hex');\n};\n\nexport function generateSignedUrl({\n\tsecret,\n\tpath,\n\texpires,\n}: {\n\tsecret: string;\n\tpath: string;\n\texpires: Date | null;\n}): {\n\t/**\n\t * The signed URL.\n\t */\n\turl: string;\n\t/**\n\t * The expiration timestamp in UNIX format (seconds).\n\t */\n\texpiresUnixTs: number | null;\n\t/**\n\t * The signature used to verify the URL.\n\t */\n\tsig: string;\n} {\n\tconst expiresTs = expires ? expires.valueOf() : null;\n\tconst expiresTsUnix = expiresTs ? Math.floor(expiresTs / 1000) : null;\n\tconst signature = generateSignature(secret, path, expiresTsUnix);\n\n\tlet url = `${path}?sig=${signature}`;\n\n\tif (expiresTsUnix !== null) {\n\t\turl += `&expires=${expiresTsUnix}`;\n\t}\n\n\treturn {\n\t\turl,\n\t\texpiresUnixTs: expiresTsUnix,\n\t\tsig: signature,\n\t};\n}\n\nexport function verifySignedUrl({\n\tsecret,\n\tpath,\n\texpires,\n\tsig,\n}: {\n\t/**\n\t * The secret used to generate the signature.\n\t */\n\tsecret: string;\n\t/**\n\t * The path of the signed URL.\n\t */\n\tpath: string;\n\t/**\n\t * The expiration to verify against, in UNIX timestamp format (seconds).\n\t */\n\texpires: number | null;\n\t/**\n\t * The signature to verify.\n\t */\n\tsig?: unknown;\n}):\n\t| 'InvalidSignatureError'\n\t| 'ExpiredSignatureError'\n\t| {\n\t\t\tpath: string;\n\t\t\texpires: number;\n\t\t\tsig: string;\n\t  } {\n\tconst expectedSig = generateSignature(secret, path, expires);\n\tconst now = Math.floor(Date.now() / 1000);\n\tconst match =\n\t\ttypeof sig !== 'string'\n\t\t\t? crypto.timingSafeEqual(\n\t\t\t\t\tBuffer.from(JSON.stringify(sig)),\n\t\t\t\t\tBuffer.from(expectedSig)\n\t\t\t\t)\n\t\t\t: sig === expectedSig;\n\n\tif (typeof sig !== 'string' || !match) {\n\t\treturn 'InvalidSignatureError';\n\t}\n\n\tif (expires !== null && (typeof expires !== 'number' || expires < now)) {\n\t\treturn 'ExpiredSignatureError';\n\t}\n\n\treturn {\n\t\tpath,\n\t\texpires: typeof expires === 'number' ? expires : now,\n\t\tsig: expectedSig,\n\t};\n}\n\nexport type VerifySignedUrlFromRequestOptions = {\n\t/** The expected path to verify (must match what was originally signed) */\n\texpectedPath: string;\n\t/** The query object */\n\tquery: SignedUrlSchema | undefined;\n\t/** The secret used to verify the signature */\n\tsecret: string;\n};\n\nexport type SignedAccessError =\n\t| 'MISSING_SIGNATURE'\n\t| 'INVALID_SIGNATURE'\n\t| 'EXPIRED_SIGNATURE';\nexport type SignedAccess =\n\t| {\n\t\t\ttype: 'verified';\n\t\t\tsig: string;\n\t\t\texpires: number | null;\n\t  }\n\t| {\n\t\t\ttype: 'invalid';\n\t\t\terror: SignedAccessError;\n\t  };\n\nexport function verifySignedUrlFromRequest({\n\tsecret,\n\texpectedPath,\n\tquery,\n}: VerifySignedUrlFromRequestOptions): SignedAccess {\n\tconst { expires, sig } = query || {};\n\n\tif (!sig) {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror: 'MISSING_SIGNATURE',\n\t\t};\n\t}\n\n\tlet result: ReturnType<typeof verifySignedUrl>;\n\ttry {\n\t\tresult = verifySignedUrl({\n\t\t\tsecret,\n\t\t\tpath: expectedPath,\n\t\t\texpires: expires ? Number(expires) : null,\n\t\t\tsig,\n\t\t});\n\t} catch {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror: 'INVALID_SIGNATURE',\n\t\t};\n\t}\n\n\tif (typeof result === 'string') {\n\t\treturn {\n\t\t\ttype: 'invalid',\n\t\t\terror:\n\t\t\t\tresult === 'InvalidSignatureError'\n\t\t\t\t\t? 'INVALID_SIGNATURE'\n\t\t\t\t\t: 'EXPIRED_SIGNATURE',\n\t\t};\n\t}\n\n\treturn {\n\t\ttype: 'verified',\n\t\tsig: result.sig,\n\t\texpires: result.expires ?? null,\n\t};\n}\n\nexport function withSignedAccess<T>(\n\tsignedAccess:\n\t\t| SignedAccess\n\t\t| {\n\t\t\t\ttype: 'invalid';\n\t\t\t\terror: string;\n\t\t  },\n\tnoSignedAccessCheck: () => Promise<true | T>\n): Promise<true | T | APIError> {\n\tif (signedAccess.type === 'verified') {\n\t\treturn Promise.resolve(true);\n\t}\n\n\tif (\n\t\tsignedAccess.error === 'MISSING_SIGNATURE' ||\n\t\t(signedAccess.error !== 'INVALID_SIGNATURE' &&\n\t\t\tsignedAccess.error !== 'EXPIRED_SIGNATURE')\n\t) {\n\t\treturn noSignedAccessCheck();\n\t}\n\n\treturn Promise.resolve(\n\t\tnew APIError(statusCodes.FORBIDDEN, {\n\t\t\tcode: signedAccess.error,\n\t\t\tmessage:\n\t\t\t\tsignedAccess.error === 'INVALID_SIGNATURE'\n\t\t\t\t\t? 'The provided signature is invalid.'\n\t\t\t\t\t: 'The provided signature has expired.',\n\t\t\tdetails: {\n\t\t\t\terror: signedAccess.error,\n\t\t\t},\n\t\t})\n\t);\n}\n"],"names":["generateSignature","__name","secret","path","expires","payload","crypto","generateSignedUrl","expiresTs","expiresTsUnix","signature","url","verifySignedUrl","sig","expectedSig","now","match","verifySignedUrlFromRequest","expectedPath","query","result","withSignedAccess","signedAccess","noSignedAccessCheck","APIError","statusCodes"],"mappings":"6NAUA,MAAMA,EAAoBC,EAAA,CACzBC,EACAC,EACAC,IACY,CACZ,MAAMC,EAAUD,IAAY,KAAOD,EAAO,GAAGA,CAAI,IAAIC,CAAO,GAC5D,OAAOE,EACL,WAAW,SAAU,OAAO,KAAKJ,EAAQ,QAAQ,CAAC,EAClD,OAAOG,CAAO,EACd,OAAO,KAAK,CACf,EAV0B,qBAYnB,SAASE,EAAkB,CACjC,OAAAL,EACA,KAAAC,EACA,QAAAC,CACD,EAiBE,CACD,MAAMI,EAAYJ,EAAUA,EAAQ,QAAA,EAAY,KAC1CK,EAAgBD,EAAY,KAAK,MAAMA,EAAY,GAAI,EAAI,KAC3DE,EAAYV,EAAkBE,EAAQC,EAAMM,CAAa,EAE/D,IAAIE,EAAM,GAAGR,CAAI,QAAQO,CAAS,GAElC,OAAID,IAAkB,OACrBE,GAAO,YAAYF,CAAa,IAG1B,CACN,IAAAE,EACA,cAAeF,EACf,IAAKC,CAAA,CAEP,CArCgBT,EAAAM,EAAA,qBAuCT,SAASK,EAAgB,CAC/B,OAAAV,EACA,KAAAC,EACA,QAAAC,EACA,IAAAS,CACD,EAwBK,CACJ,MAAMC,EAAcd,EAAkBE,EAAQC,EAAMC,CAAO,EACrDW,EAAM,KAAK,MAAM,KAAK,IAAA,EAAQ,GAAI,EAClCC,EACL,OAAOH,GAAQ,SACZP,EAAO,gBACP,OAAO,KAAK,KAAK,UAAUO,CAAG,CAAC,EAC/B,OAAO,KAAKC,CAAW,CAAA,EAEvBD,IAAQC,EAEZ,OAAI,OAAOD,GAAQ,UAAY,CAACG,EACxB,wBAGJZ,IAAY,OAAS,OAAOA,GAAY,UAAYA,EAAUW,GAC1D,wBAGD,CACN,KAAAZ,EACA,QAAS,OAAOC,GAAY,SAAWA,EAAUW,EACjD,IAAKD,CAAA,CAEP,CArDgBb,EAAAW,EAAA,mBA+ET,SAASK,EAA2B,CAC1C,OAAAf,EACA,aAAAgB,EACA,MAAAC,CACD,EAAoD,CACnD,KAAM,CAAE,QAAAf,EAAS,IAAAS,CAAA,EAAQM,GAAS,CAAA,EAElC,GAAI,CAACN,EACJ,MAAO,CACN,KAAM,UACN,MAAO,mBAAA,EAIT,IAAIO,EACJ,GAAI,CACHA,EAASR,EAAgB,CACxB,OAAAV,EACA,KAAMgB,EACN,QAASd,EAAU,OAAOA,CAAO,EAAI,KACrC,IAAAS,CAAA,CACA,CACF,MAAQ,CACP,MAAO,CACN,KAAM,UACN,MAAO,mBAAA,CAET,CAEA,OAAI,OAAOO,GAAW,SACd,CACN,KAAM,UACN,MACCA,IAAW,wBACR,oBACA,mBAAA,EAIC,CACN,KAAM,WACN,IAAKA,EAAO,IACZ,QAASA,EAAO,SAAW,IAAA,CAE7B,CA5CgBnB,EAAAgB,EAAA,8BA8CT,SAASI,EACfC,EAMAC,EAC+B,CAC/B,OAAID,EAAa,OAAS,WAClB,QAAQ,QAAQ,EAAI,EAI3BA,EAAa,QAAU,qBACtBA,EAAa,QAAU,qBACvBA,EAAa,QAAU,oBAEjBC,EAAA,EAGD,QAAQ,QACd,IAAIC,EAASC,EAAY,UAAW,CACnC,KAAMH,EAAa,MACnB,QACCA,EAAa,QAAU,oBACpB,qCACA,sCACJ,QAAS,CACR,MAAOA,EAAa,KAAA,CACrB,CACA,CAAA,CAEH,CAjCgBrB,EAAAoB,EAAA"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@md-oss/security",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Mirasaki-OSS/monorepo-template.git",
+    "directory": "vendor/security"
+  },
+  "type": "module",
+  "description": "Cryptographic utilities for encryption, signed URLs, and secure streaming",
+  "license": "ISC",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./decryption-stream": {
+      "require": {
+        "types": "./dist/decryption-stream.d.cts",
+        "default": "./dist/decryption-stream.cjs"
+      },
+      "import": {
+        "types": "./dist/decryption-stream.d.mts",
+        "default": "./dist/decryption-stream.mjs"
+      }
+    },
+    "./encryption": {
+      "require": {
+        "types": "./dist/encryption.d.cts",
+        "default": "./dist/encryption.cjs"
+      },
+      "import": {
+        "types": "./dist/encryption.d.mts",
+        "default": "./dist/encryption.mjs"
+      }
+    },
+    "./signed-urls": {
+      "require": {
+        "types": "./dist/signed-urls.d.cts",
+        "default": "./dist/signed-urls.cjs"
+      },
+      "import": {
+        "types": "./dist/signed-urls.d.mts",
+        "default": "./dist/signed-urls.mjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@md-oss/config": "^0.1.0",
+    "@md-oss/common": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "pkgroll": "^2.21.5",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "pkgroll --minify --clean-dist --sourcemap  --define.process.env.NODE_ENV='\"production\"' --define.DEBUG=false",
+    "clean": "git clean -xdf .turbo dist node_modules tsconfig.tsbuildinfo",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}