@lifestreamdynamics/vault-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,26 @@
+export { LifestreamVaultClient } from './client.js';
+export { VaultsResource } from './resources/vaults.js';
+export { DocumentsResource } from './resources/documents.js';
+export { SearchResource } from './resources/search.js';
+export { AiResource } from './resources/ai.js';
+export { ApiKeysResource } from './resources/api-keys.js';
+export { UserResource } from './resources/user.js';
+export { SubscriptionResource } from './resources/subscription.js';
+export { TeamsResource } from './resources/teams.js';
+export { SharesResource } from './resources/shares.js';
+export { PublishResource } from './resources/publish.js';
+export { ConnectorsResource } from './resources/connectors.js';
+export { HooksResource } from './resources/hooks.js';
+export { WebhooksResource } from './resources/webhooks.js';
+export { AdminResource } from './resources/admin.js';
+// Request signing
+export { signRequest, buildSignaturePayload, signPayload, generateNonce, SIGNATURE_HEADER, SIGNATURE_TIMESTAMP_HEADER, SIGNATURE_NONCE_HEADER, MAX_TIMESTAMP_AGE_MS, } from './lib/signature.js';
+// Audit logging
+export { AuditLogger } from './lib/audit-logger.js';
+// Encryption
+export { generateVaultKey, encrypt as encryptContent, decrypt as decryptContent, isEncryptedEnvelope, } from './lib/encryption.js';
+// Token management
+export { TokenManager, decodeJwtPayload, isTokenExpired, } from './lib/token-manager.js';
+// Error classes
+export { SDKError, ValidationError, AuthenticationError, AuthorizationError, NotFoundError, ConflictError, RateLimitError, NetworkError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAsB,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAY/D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAerD,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAA4C,MAAM,uBAAuB,CAAC;AAE9F,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,OAAO,IAAI,cAAc,EACzB,OAAO,IAAI,cAAc,EACzB,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAE7B,mBAAmB;AACnB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,GAKf,MAAM,wBAAwB,CAAC;AAEhC,gBAAgB;AAChB,OAAO,EACL,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC"}

package/dist/lib/audit-logger.d.ts

@@ -0,0 +1,29 @@
+export interface AuditEntry {
+    timestamp: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+}
+export interface AuditLoggerOptions {
+    logPath?: string;
+    maxSize?: number;
+    maxFiles?: number;
+}
+export declare class AuditLogger {
+    private readonly logPath;
+    private readonly maxSize;
+    private readonly maxFiles;
+    constructor(options?: AuditLoggerOptions);
+    getLogPath(): string;
+    log(entry: AuditEntry): void;
+    private rotateIfNeeded;
+    readEntries(options?: {
+        tail?: number;
+        status?: number;
+        since?: string;
+        until?: string;
+    }): AuditEntry[];
+    exportCsv(entries: AuditEntry[]): string;
+}
+//# sourceMappingURL=audit-logger.d.ts.map

package/dist/lib/audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.d.ts","sourceRoot":"","sources":["../../src/lib/audit-logger.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,GAAE,kBAAuB;IAM5C,UAAU,IAAI,MAAM;IAIpB,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAY5B,OAAO,CAAC,cAAc;IA+BtB,WAAW,CAAC,OAAO,GAAE;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GAAG,UAAU,EAAE;IAiCrB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM;CAOzC"}

package/dist/lib/audit-logger.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_LOG_DIR = path.join(os.homedir(), '.lsvault');
+const DEFAULT_LOG_FILE = 'audit.log';
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_ROTATED_FILES = 5;
+export class AuditLogger {
+    logPath;
+    maxSize;
+    maxFiles;
+    constructor(options = {}) {
+        this.logPath = options.logPath || path.join(DEFAULT_LOG_DIR, DEFAULT_LOG_FILE);
+        this.maxSize = options.maxSize || MAX_LOG_SIZE;
+        this.maxFiles = options.maxFiles || MAX_ROTATED_FILES;
+    }
+    getLogPath() {
+        return this.logPath;
+    }
+    log(entry) {
+        const dir = path.dirname(this.logPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        this.rotateIfNeeded();
+        const line = JSON.stringify(entry) + '\n';
+        fs.appendFileSync(this.logPath, line, 'utf-8');
+    }
+    rotateIfNeeded() {
+        if (!fs.existsSync(this.logPath))
+            return;
+        let stat;
+        try {
+            stat = fs.statSync(this.logPath);
+        }
+        catch {
+            return;
+        }
+        if (stat.size < this.maxSize)
+            return;
+        // Delete oldest rotated file if it exists
+        const oldest = `${this.logPath}.${this.maxFiles}`;
+        if (fs.existsSync(oldest)) {
+            fs.unlinkSync(oldest);
+        }
+        // Shift existing rotated files: .4 -> .5, .3 -> .4, etc.
+        for (let i = this.maxFiles - 1; i >= 1; i--) {
+            const src = `${this.logPath}.${i}`;
+            const dest = `${this.logPath}.${i + 1}`;
+            if (fs.existsSync(src)) {
+                fs.renameSync(src, dest);
+            }
+        }
+        // Rotate current log to .1
+        fs.renameSync(this.logPath, `${this.logPath}.1`);
+    }
+    readEntries(options = {}) {
+        if (!fs.existsSync(this.logPath))
+            return [];
+        const content = fs.readFileSync(this.logPath, 'utf-8');
+        const lines = content.split('\n').filter(Boolean);
+        let entries = [];
+        for (const line of lines) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        if (options.status !== undefined) {
+            entries = entries.filter(e => e.status === options.status);
+        }
+        if (options.since) {
+            const sinceDate = new Date(options.since);
+            entries = entries.filter(e => new Date(e.timestamp) >= sinceDate);
+        }
+        if (options.until) {
+            const untilDate = new Date(options.until);
+            entries = entries.filter(e => new Date(e.timestamp) <= untilDate);
+        }
+        if (options.tail !== undefined) {
+            entries = entries.slice(-options.tail);
+        }
+        return entries;
+    }
+    exportCsv(entries) {
+        const header = 'timestamp,method,path,status,durationMs';
+        const rows = entries.map(e => `${e.timestamp},${e.method},${csvEscape(e.path)},${e.status},${e.durationMs}`);
+        return [header, ...rows].join('\n') + '\n';
+    }
+}
+function csvEscape(value) {
+    if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+//# sourceMappingURL=audit-logger.js.map

package/dist/lib/audit-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.js","sourceRoot":"","sources":["../../src/lib/audit-logger.ts"],"names":[],"mappings":"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"}

package/dist/lib/encryption.d.ts

@@ -0,0 +1,34 @@
+/** Envelope format for encrypted document content. */
+export interface EncryptedEnvelope {
+    version: 1;
+    algorithm: 'aes-256-gcm';
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+}
+/**
+ * Generate a random 256-bit encryption key.
+ * Returns the key as a hex string (64 characters).
+ */
+export declare function generateVaultKey(): string;
+/**
+ * Encrypt plaintext content using AES-256-GCM.
+ *
+ * @param plaintext - The plaintext string to encrypt
+ * @param keyHex - The 256-bit key as a hex string
+ * @returns The encrypted envelope as a JSON string
+ */
+export declare function encrypt(plaintext: string, keyHex: string): string;
+/**
+ * Decrypt content from an encrypted envelope using AES-256-GCM.
+ *
+ * @param envelopeJson - The encrypted envelope as a JSON string
+ * @param keyHex - The 256-bit key as a hex string
+ * @returns The decrypted plaintext string
+ */
+export declare function decrypt(envelopeJson: string, keyHex: string): string;
+/**
+ * Check if a string is an encrypted envelope (basic structure check).
+ */
+export declare function isEncryptedEnvelope(content: string): boolean;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/lib/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"AAOA,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,aAAa,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAwBjE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA4BpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAa5D"}

package/dist/lib/encryption.js

@@ -0,0 +1,87 @@
+import crypto from 'node:crypto';
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 12; // 96 bits (recommended for GCM)
+const AUTH_TAG_LENGTH = 16; // 128 bits
+/**
+ * Generate a random 256-bit encryption key.
+ * Returns the key as a hex string (64 characters).
+ */
+export function generateVaultKey() {
+    return crypto.randomBytes(KEY_LENGTH).toString('hex');
+}
+/**
+ * Encrypt plaintext content using AES-256-GCM.
+ *
+ * @param plaintext - The plaintext string to encrypt
+ * @param keyHex - The 256-bit key as a hex string
+ * @returns The encrypted envelope as a JSON string
+ */
+export function encrypt(plaintext, keyHex) {
+    const key = Buffer.from(keyHex, 'hex');
+    if (key.length !== KEY_LENGTH) {
+        throw new Error(`Invalid key length: expected ${KEY_LENGTH} bytes, got ${key.length}`);
+    }
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    const authTag = cipher.getAuthTag();
+    const envelope = {
+        version: 1,
+        algorithm: ALGORITHM,
+        iv: iv.toString('hex'),
+        authTag: authTag.toString('hex'),
+        ciphertext: encrypted.toString('hex'),
+    };
+    return JSON.stringify(envelope);
+}
+/**
+ * Decrypt content from an encrypted envelope using AES-256-GCM.
+ *
+ * @param envelopeJson - The encrypted envelope as a JSON string
+ * @param keyHex - The 256-bit key as a hex string
+ * @returns The decrypted plaintext string
+ */
+export function decrypt(envelopeJson, keyHex) {
+    const key = Buffer.from(keyHex, 'hex');
+    if (key.length !== KEY_LENGTH) {
+        throw new Error(`Invalid key length: expected ${KEY_LENGTH} bytes, got ${key.length}`);
+    }
+    const envelope = JSON.parse(envelopeJson);
+    if (envelope.version !== 1) {
+        throw new Error(`Unsupported encryption envelope version: ${envelope.version}`);
+    }
+    if (envelope.algorithm !== ALGORITHM) {
+        throw new Error(`Unsupported encryption algorithm: ${envelope.algorithm}`);
+    }
+    const iv = Buffer.from(envelope.iv, 'hex');
+    const authTag = Buffer.from(envelope.authTag, 'hex');
+    const ciphertext = Buffer.from(envelope.ciphertext, 'hex');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+}
+/**
+ * Check if a string is an encrypted envelope (basic structure check).
+ */
+export function isEncryptedEnvelope(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return (parsed.version === 1
+            && parsed.algorithm === ALGORITHM
+            && typeof parsed.iv === 'string'
+            && typeof parsed.authTag === 'string'
+            && typeof parsed.ciphertext === 'string');
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=encryption.js.map

package/dist/lib/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"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"}

package/dist/lib/signature.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Headers used for HMAC request signing.
+ */
+export declare const SIGNATURE_HEADER = "x-signature";
+export declare const SIGNATURE_TIMESTAMP_HEADER = "x-signature-timestamp";
+export declare const SIGNATURE_NONCE_HEADER = "x-signature-nonce";
+/**
+ * Maximum age (in milliseconds) for a signed request timestamp.
+ * Requests older than this are rejected to prevent replay attacks.
+ */
+export declare const MAX_TIMESTAMP_AGE_MS: number;
+/**
+ * Constructs the canonical payload string for HMAC signing.
+ *
+ * Format: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY_HASH
+ *
+ * @param method - HTTP method (uppercase)
+ * @param path - Request path (no query string)
+ * @param timestamp - ISO-8601 timestamp
+ * @param nonce - 16-byte hex nonce
+ * @param body - Request body string (empty string if no body)
+ * @returns The canonical payload string
+ */
+export declare function buildSignaturePayload(method: string, path: string, timestamp: string, nonce: string, body: string): string;
+/**
+ * Generates an HMAC-SHA256 signature for a request.
+ *
+ * @param secret - The API key used as the HMAC secret
+ * @param payload - The canonical payload string
+ * @returns Hex-encoded HMAC signature
+ */
+export declare function signPayload(secret: string, payload: string): string;
+/**
+ * Generates a cryptographically secure 16-byte hex nonce.
+ */
+export declare function generateNonce(): string;
+/**
+ * Signs a request and returns the headers to attach.
+ *
+ * @param apiKey - The full API key (used as HMAC secret)
+ * @param method - HTTP method
+ * @param path - Request path (without query string)
+ * @param body - Request body string (empty string for no body)
+ * @returns Object containing the three signature headers
+ */
+export declare function signRequest(apiKey: string, method: string, path: string, body?: string): Record<string, string>;
+//# sourceMappingURL=signature.d.ts.map

package/dist/lib/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/lib/signature.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAC9C,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAgB,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAW,GAChB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}

package/dist/lib/signature.js

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto';
+/**
+ * Headers used for HMAC request signing.
+ */
+export const SIGNATURE_HEADER = 'x-signature';
+export const SIGNATURE_TIMESTAMP_HEADER = 'x-signature-timestamp';
+export const SIGNATURE_NONCE_HEADER = 'x-signature-nonce';
+/**
+ * Maximum age (in milliseconds) for a signed request timestamp.
+ * Requests older than this are rejected to prevent replay attacks.
+ */
+export const MAX_TIMESTAMP_AGE_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Constructs the canonical payload string for HMAC signing.
+ *
+ * Format: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY_HASH
+ *
+ * @param method - HTTP method (uppercase)
+ * @param path - Request path (no query string)
+ * @param timestamp - ISO-8601 timestamp
+ * @param nonce - 16-byte hex nonce
+ * @param body - Request body string (empty string if no body)
+ * @returns The canonical payload string
+ */
+export function buildSignaturePayload(method, path, timestamp, nonce, body) {
+    const bodyHash = crypto
+        .createHash('sha256')
+        .update(body)
+        .digest('hex');
+    return `${method.toUpperCase()}\n${path}\n${timestamp}\n${nonce}\n${bodyHash}`;
+}
+/**
+ * Generates an HMAC-SHA256 signature for a request.
+ *
+ * @param secret - The API key used as the HMAC secret
+ * @param payload - The canonical payload string
+ * @returns Hex-encoded HMAC signature
+ */
+export function signPayload(secret, payload) {
+    return crypto
+        .createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+}
+/**
+ * Generates a cryptographically secure 16-byte hex nonce.
+ */
+export function generateNonce() {
+    return crypto.randomBytes(16).toString('hex');
+}
+/**
+ * Signs a request and returns the headers to attach.
+ *
+ * @param apiKey - The full API key (used as HMAC secret)
+ * @param method - HTTP method
+ * @param path - Request path (without query string)
+ * @param body - Request body string (empty string for no body)
+ * @returns Object containing the three signature headers
+ */
+export function signRequest(apiKey, method, path, body = '') {
+    const timestamp = new Date().toISOString();
+    const nonce = generateNonce();
+    const payload = buildSignaturePayload(method, path, timestamp, nonce, body);
+    const signature = signPayload(apiKey, payload);
+    return {
+        [SIGNATURE_HEADER]: signature,
+        [SIGNATURE_TIMESTAMP_HEADER]: timestamp,
+        [SIGNATURE_NONCE_HEADER]: nonce,
+    };
+}
+//# sourceMappingURL=signature.js.map

package/dist/lib/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/lib/signature.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAC9C,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AAClE,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,IAAY,EACZ,SAAiB,EACjB,KAAa,EACb,IAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM;SACpB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,IAAI,CAAC;SACZ,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,KAAK,IAAI,KAAK,SAAS,KAAK,KAAK,KAAK,QAAQ,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAAe;IACzD,OAAO,MAAM;SACV,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC5B,MAAM,CAAC,OAAO,CAAC;SACf,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,MAAc,EACd,IAAY,EACZ,OAAe,EAAE;IAEjB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5E,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C,OAAO;QACL,CAAC,gBAAgB,CAAC,EAAE,SAAS;QAC7B,CAAC,0BAA0B,CAAC,EAAE,SAAS;QACvC,CAAC,sBAAsB,CAAC,EAAE,KAAK;KAChC,CAAC;AACJ,CAAC"}

package/dist/lib/token-manager.d.ts

@@ -0,0 +1,80 @@
+import type { KyInstance } from 'ky';
+/** Decoded JWT payload with standard claims. */
+export interface JwtPayload {
+    exp: number;
+    iat?: number;
+    sub?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+/** Authentication tokens returned from login/refresh. */
+export interface AuthTokens {
+    accessToken: string;
+    user: {
+        id: string;
+        email: string;
+        name?: string;
+        role: string;
+        [key: string]: unknown;
+    };
+}
+/** Callback invoked when tokens are refreshed. */
+export type OnTokenRefresh = (tokens: AuthTokens) => void;
+/** Options for configuring the TokenManager. */
+export interface TokenManagerOptions {
+    /** How many milliseconds before expiry to trigger a proactive refresh. Default: 60000 (1 min). */
+    refreshBufferMs?: number;
+    /** Called after a successful token refresh. */
+    onTokenRefresh?: OnTokenRefresh;
+}
+/**
+ * Decode a JWT payload without verification.
+ * Only decodes the payload section (second segment) from base64url.
+ */
+export declare function decodeJwtPayload(token: string): JwtPayload | null;
+/**
+ * Check if a JWT token is expired or will expire within the given buffer.
+ *
+ * @param token - The JWT access token
+ * @param bufferMs - Milliseconds before actual expiry to consider it "expired"
+ * @returns true if the token is expired or will expire within bufferMs
+ */
+export declare function isTokenExpired(token: string, bufferMs?: number): boolean;
+/**
+ * Manages JWT access token lifecycle with automatic refresh.
+ *
+ * Handles:
+ * - Proactive refresh before token expiry (beforeRequest hook)
+ * - Reactive refresh on 401 responses (afterResponse hook)
+ * - Infinite retry prevention via X-Retry-After-Refresh header
+ * - Deduplication of concurrent refresh requests
+ */
+export declare class TokenManager {
+    private accessToken;
+    private refreshToken;
+    private refreshPromise;
+    private readonly refreshBufferMs;
+    private readonly onTokenRefresh?;
+    constructor(accessToken: string, refreshToken: string | null, options?: TokenManagerOptions);
+    /** Get the current access token. */
+    getAccessToken(): string;
+    /** Get the current refresh token. */
+    getRefreshToken(): string | null;
+    /** Update the access token (e.g., after external login). */
+    setAccessToken(token: string): void;
+    /** Update the refresh token. */
+    setRefreshToken(token: string | null): void;
+    /** Check whether the current access token needs refreshing. */
+    needsRefresh(): boolean;
+    /**
+     * Perform a token refresh using the API's /auth/refresh endpoint.
+     * Deduplicates concurrent calls so only one HTTP request is made.
+     *
+     * @param http - The ky instance to use for the refresh request (should NOT have auth hooks)
+     * @returns The new access token
+     * @throws If refresh fails (no refresh token, network error, etc.)
+     */
+    refresh(http: KyInstance): Promise<string>;
+    private performRefresh;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/lib/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/lib/token-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAErC,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAE1D,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAoBjE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAe,GAAG,OAAO,CAMhF;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;gBAG/C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,mBAAwB;IAQnC,oCAAoC;IACpC,cAAc,IAAI,MAAM;IAIxB,qCAAqC;IACrC,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,4DAA4D;IAC5D,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAInC,gCAAgC;IAChC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI3C,+DAA+D;IAC/D,YAAY,IAAI,OAAO;IAIvB;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;YAmBlC,cAAc;CAa7B"}

package/dist/lib/token-manager.js

@@ -0,0 +1,116 @@
+/**
+ * Decode a JWT payload without verification.
+ * Only decodes the payload section (second segment) from base64url.
+ */
+export function decodeJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = parts[1];
+        // Base64url to base64
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        // Pad if needed
+        const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+        // Decode - works in both Node.js and browser
+        const decoded = typeof atob === 'function'
+            ? atob(padded)
+            : Buffer.from(padded, 'base64').toString('utf-8');
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a JWT token is expired or will expire within the given buffer.
+ *
+ * @param token - The JWT access token
+ * @param bufferMs - Milliseconds before actual expiry to consider it "expired"
+ * @returns true if the token is expired or will expire within bufferMs
+ */
+export function isTokenExpired(token, bufferMs = 60_000) {
+    const payload = decodeJwtPayload(token);
+    if (!payload || !payload.exp)
+        return true;
+    const expiresAtMs = payload.exp * 1000;
+    return Date.now() > expiresAtMs - bufferMs;
+}
+/**
+ * Manages JWT access token lifecycle with automatic refresh.
+ *
+ * Handles:
+ * - Proactive refresh before token expiry (beforeRequest hook)
+ * - Reactive refresh on 401 responses (afterResponse hook)
+ * - Infinite retry prevention via X-Retry-After-Refresh header
+ * - Deduplication of concurrent refresh requests
+ */
+export class TokenManager {
+    accessToken;
+    refreshToken;
+    refreshPromise = null;
+    refreshBufferMs;
+    onTokenRefresh;
+    constructor(accessToken, refreshToken, options = {}) {
+        this.accessToken = accessToken;
+        this.refreshToken = refreshToken;
+        this.refreshBufferMs = options.refreshBufferMs ?? 60_000;
+        this.onTokenRefresh = options.onTokenRefresh;
+    }
+    /** Get the current access token. */
+    getAccessToken() {
+        return this.accessToken;
+    }
+    /** Get the current refresh token. */
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    /** Update the access token (e.g., after external login). */
+    setAccessToken(token) {
+        this.accessToken = token;
+    }
+    /** Update the refresh token. */
+    setRefreshToken(token) {
+        this.refreshToken = token;
+    }
+    /** Check whether the current access token needs refreshing. */
+    needsRefresh() {
+        return isTokenExpired(this.accessToken, this.refreshBufferMs);
+    }
+    /**
+     * Perform a token refresh using the API's /auth/refresh endpoint.
+     * Deduplicates concurrent calls so only one HTTP request is made.
+     *
+     * @param http - The ky instance to use for the refresh request (should NOT have auth hooks)
+     * @returns The new access token
+     * @throws If refresh fails (no refresh token, network error, etc.)
+     */
+    async refresh(http) {
+        if (!this.refreshToken) {
+            throw new Error('No refresh token available');
+        }
+        // Deduplicate concurrent refresh requests
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.performRefresh(http);
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async performRefresh(http) {
+        const response = await http.post('auth/refresh', {
+            headers: {
+                'X-Requested-With': 'LifestreamVaultSDK',
+                'Cookie': `lsv_refresh=${this.refreshToken}`,
+            },
+        }).json();
+        this.accessToken = response.accessToken;
+        this.onTokenRefresh?.(response);
+        return this.accessToken;
+    }
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/lib/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../../src/lib/token-manager.ts"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,sBAAsB;QACtB,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7D,gBAAgB;QAChB,MAAM,MAAM,GAAG,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAElE,6CAA6C;QAC7C,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,UAAU;YACxC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;YACd,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEpD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,WAAmB,MAAM;IACrE,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,GAAG,QAAQ,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IACf,WAAW,CAAS;IACpB,YAAY,CAAgB;IAC5B,cAAc,GAA2B,IAAI,CAAC;IACrC,eAAe,CAAS;IACxB,cAAc,CAAkB;IAEjD,YACE,WAAmB,EACnB,YAA2B,EAC3B,UAA+B,EAAE;QAEjC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,MAAM,CAAC;QACzD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAC/C,CAAC;IAED,oCAAoC;IACpC,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,qCAAqC;IACrC,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,4DAA4D;IAC5D,cAAc,CAAC,KAAa;QAC1B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED,gCAAgC;IAChC,eAAe,CAAC,KAAoB;QAClC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED,+DAA+D;IAC/D,YAAY;QACV,OAAO,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,IAAgB;QAC5B,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QAED,0CAA0C;QAC1C,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,cAAc,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAEhD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC;QACnC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,IAAgB;QAC3C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;YAC/C,OAAO,EAAE;gBACP,kBAAkB,EAAE,oBAAoB;gBACxC,QAAQ,EAAE,eAAe,IAAI,CAAC,YAAY,EAAE;aAC7C;SACF,CAAC,CAAC,IAAI,EAAc,CAAC;QAEtB,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC;QACxC,IAAI,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,CAAC;QAEhC,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}