@sesamy/capsule-server 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,729 @@
+/**
+ * Type definitions for Capsule server-side encryption.
+ */
+/** Bucket key information */
+interface BucketKey {
+    /** Bucket identifier (TOTP counter value) */
+    bucketId: string;
+    /** 256-bit AES key for this bucket */
+    key: Buffer;
+    /** When this bucket expires */
+    expiresAt: Date;
+}
+/** Key wrapping entry - DEK wrapped with a specific key */
+interface WrappedKey {
+    /** The key ID used to wrap (e.g., "premium:123456" or "article:crypto-guide") */
+    keyId: string;
+    /** Base64-encoded wrapped DEK */
+    wrappedDek: string;
+    /** When this wrapped key expires (for time-bucket keys) - ISO string */
+    expiresAt?: string;
+}
+/** Encrypted article with envelope encryption */
+interface EncryptedArticle {
+    /** Unique article identifier */
+    articleId: string;
+    /** Base64-encoded encrypted content (AES-256-GCM ciphertext + auth tag) */
+    encryptedContent: string;
+    /** Base64-encoded IV used for encryption */
+    iv: string;
+    /** Multiple wrapped versions of the content DEK for different unlock paths */
+    wrappedKeys: WrappedKey[];
+}
+/** Configuration for key wrapping */
+interface KeyWrapConfig {
+    /** Key ID (e.g., "premium", "article:crypto-guide") */
+    keyId: string;
+    /** 256-bit AES key-wrapping key */
+    key: Buffer;
+    /** Expiration time (for time-bucket keys) */
+    expiresAt?: Date;
+}
+/** Options for the CMS encryptor */
+interface CmsEncryptorOptions {
+    /** Subscription server URL (for API mode) */
+    subscriptionServerUrl?: string;
+    /** API key for subscription server authentication */
+    apiKey?: string;
+    /** Master secret for TOTP mode (base64 encoded) */
+    masterSecret?: string;
+    /** Bucket period in seconds (default: 30) */
+    bucketPeriodSeconds?: number;
+}
+/** Subscription server client options */
+interface SubscriptionClientOptions {
+    /** Subscription server base URL */
+    serverUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+}
+/** Response from subscription server for bucket keys */
+interface BucketKeysResponse {
+    /** Current bucket key */
+    current: BucketKey;
+    /** Next bucket key (for clock drift handling) */
+    next: BucketKey;
+}
+/** Response from unlocking with a user's public key */
+interface UnlockResponse {
+    /** Base64-encoded RSA-OAEP wrapped DEK */
+    encryptedDek: string;
+    /** Key ID that was used */
+    keyId: string;
+    /** Bucket ID (for time-bucket keys) */
+    bucketId?: string;
+    /** When the client should re-request (bucket expiration) */
+    expiresAt: string;
+}
+
+/**
+ * Capsule CMS Server - High-Level API
+ *
+ * Provides a simple interface for server-side content encryption.
+ * The CMS just works with key IDs - it doesn't know or care about
+ * tiers, subscriptions, or how keys are derived.
+ *
+ * Keys are fetched via an async `getKeys` function that you provide.
+ * This could:
+ * - Fetch from your subscription server
+ * - Use TOTP derivation (see `createTotpKeyProvider`)
+ * - Return hardcoded/cached keys
+ *
+ * @example Basic Usage with Custom Key Provider
+ * ```typescript
+ * import { createCmsServer } from '@sesamy/capsule-server';
+ *
+ * const cms = createCmsServer({
+ *   getKeys: async (keyIds) => {
+ *     // Fetch keys from your subscription server
+ *     const response = await fetch('/api/keys', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ keyIds }),
+ *     });
+ *     return response.json();
+ *   },
+ * });
+ *
+ * // Encrypt with specific key IDs
+ * const encrypted = await cms.encrypt('article-123', content, {
+ *   keyIds: ['premium', 'enterprise'],
+ * });
+ * ```
+ *
+ * @example Using TOTP Key Provider
+ * ```typescript
+ * import { createCmsServer, createTotpKeyProvider } from '@sesamy/capsule-server';
+ *
+ * const totp = createTotpKeyProvider({
+ *   masterSecret: process.env.MASTER_SECRET,
+ *   bucketPeriodSeconds: 30,
+ * });
+ *
+ * const cms = createCmsServer({
+ *   getKeys: (keyIds) => totp.getKeys(keyIds),
+ * });
+ *
+ * const encrypted = await cms.encrypt('article-123', content, {
+ *   keyIds: ['premium', 'enterprise'],
+ * });
+ * ```
+ */
+
+/**
+ * A key entry returned by the key provider.
+ */
+interface KeyEntry {
+    /** Unique key identifier */
+    keyId: string;
+    /** 256-bit AES key (Buffer or base64 string) */
+    key: Buffer | string;
+    /** Optional expiration time (for time-bucket keys) */
+    expiresAt?: Date | string;
+}
+/**
+ * Async function to fetch keys for given key IDs.
+ *
+ * The CMS calls this with the key IDs it needs, and you return
+ * the actual keys. This decouples key management from encryption.
+ *
+ * @param keyIds - Array of key IDs to fetch
+ * @returns Array of key entries with the actual keys
+ */
+type KeyProvider = (keyIds: string[]) => Promise<KeyEntry[]>;
+/**
+ * Options for creating a CMS server.
+ */
+interface CmsServerOptions {
+    /**
+     * Async function to fetch keys for given key IDs.
+     *
+     * @example Fetch from subscription server
+     * ```typescript
+     * getKeys: async (keyIds) => {
+     *   const response = await fetch('/api/keys', {
+     *     method: 'POST',
+     *     body: JSON.stringify({ keyIds }),
+     *   });
+     *   return response.json();
+     * }
+     * ```
+     *
+     * @example Use TOTP provider
+     * ```typescript
+     * const totp = createTotpKeyProvider({ masterSecret: '...' });
+     * getKeys: (keyIds) => totp.getKeys(keyIds)
+     * ```
+     */
+    getKeys: KeyProvider;
+    /**
+     * Optional logger function for debugging.
+     */
+    logger?: (message: string, level: "info" | "warn" | "error") => void;
+}
+/**
+ * Options for the encrypt() method.
+ */
+interface EncryptOptions {
+    /**
+     * Key IDs to encrypt with. The DEK will be wrapped with each key.
+     *
+     * @example
+     * ```typescript
+     * keyIds: ['premium', 'enterprise', 'promo-2024']
+     * ```
+     */
+    keyIds: string[];
+    /**
+     * Output format:
+     * - 'json': Returns EncryptedArticle object (default)
+     * - 'html': Returns HTML element with data-capsule attribute
+     * - 'html-template': Returns just the JSON for templates
+     */
+    format?: "json" | "html" | "html-template";
+    /** HTML element tag when format is 'html'. Default: 'div' */
+    htmlTag?: string;
+    /** HTML element class when format is 'html'. */
+    htmlClass?: string;
+    /** Placeholder content shown before unlock when format is 'html'. */
+    placeholder?: string;
+}
+/** Result type based on format option */
+type EncryptResult<T extends EncryptOptions["format"]> = T extends "html" ? string : T extends "html-template" ? string : EncryptedArticle;
+/**
+ * CMS Server for content encryption.
+ *
+ * Encrypts content with envelope encryption - the content is encrypted
+ * once with a unique DEK (Data Encryption Key), then the DEK is wrapped
+ * with multiple key-wrapping keys so different users can unlock it.
+ *
+ * @see createCmsServer for the recommended way to create an instance
+ */
+declare class CmsServer {
+    private getKeys;
+    private logger;
+    constructor(options: CmsServerOptions);
+    /**
+     * Encrypt content with envelope encryption.
+     *
+     * The content is encrypted once with a unique DEK, then the DEK is wrapped
+     * with multiple key-wrapping keys (one for each keyId).
+     *
+     * @param articleId - Unique article identifier
+     * @param content - Plaintext content to encrypt
+     * @param options - Encryption options
+     * @returns Encrypted article data
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await cms.encrypt('article-123', '<p>Premium content...</p>', {
+     *   keyIds: ['premium', 'enterprise'],
+     * });
+     * ```
+     *
+     * Returns (format: 'json'):
+     * ```json
+     * {
+     *   "articleId": "article-123",
+     *   "encryptedContent": "base64...",  // AES-256-GCM encrypted content
+     *   "iv": "base64...",                 // 12-byte initialization vector
+     *   "wrappedKeys": [
+     *     {
+     *       "keyId": "premium:1737158400",
+     *       "wrappedDek": "base64...",     // DEK wrapped with this key
+     *       "expiresAt": "2025-01-18T01:00:00.000Z"
+     *     },
+     *     {
+     *       "keyId": "premium:1737158430",
+     *       "wrappedDek": "base64...",
+     *       "expiresAt": "2025-01-18T01:00:30.000Z"
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    encrypt<T extends EncryptOptions["format"] = "json">(articleId: string, content: string, options: EncryptOptions & {
+        format?: T;
+    }): Promise<EncryptResult<T>>;
+    /**
+     * Encrypt and return data in multiple formats for templates.
+     *
+     * @returns Object with all template formats:
+     * - data: The EncryptedArticle object
+     * - json: JSON string
+     * - attribute: HTML-escaped JSON for data attributes
+     * - html: Complete HTML element
+     */
+    encryptForTemplate(articleId: string, content: string, options: Omit<EncryptOptions, "format">): Promise<{
+        data: EncryptedArticle;
+        json: string;
+        attribute: string;
+        html: string;
+    }>;
+    /**
+     * Escape HTML special characters for safe attribute embedding.
+     */
+    private escapeHtml;
+}
+/**
+ * Create a CMS server for content encryption.
+ *
+ * @example With subscription server
+ * ```typescript
+ * const cms = createCmsServer({
+ *   getKeys: async (keyIds) => {
+ *     const response = await fetch('/api/keys', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ keyIds }),
+ *     });
+ *     return response.json();
+ *   },
+ * });
+ * ```
+ *
+ * @example With TOTP key provider
+ * ```typescript
+ * const totp = createTotpKeyProvider({ masterSecret: process.env.MASTER_SECRET });
+ * const cms = createCmsServer({
+ *   getKeys: (keyIds) => totp.getKeys(keyIds),
+ * });
+ * ```
+ */
+declare function createCmsServer(options: CmsServerOptions): CmsServer;
+/**
+ * Options for the TOTP key provider.
+ */
+interface TotpKeyProviderOptions {
+    /**
+     * Master secret for key derivation.
+     * Can be a Buffer or base64-encoded string.
+     */
+    masterSecret: Buffer | string;
+    /**
+     * Bucket period in seconds.
+     * Default: 30 seconds.
+     */
+    bucketPeriodSeconds?: number;
+}
+/**
+ * TOTP-based key provider.
+ *
+ * Derives time-bucket keys from a master secret using HKDF.
+ * For each key ID, returns BOTH current and next bucket keys
+ * to handle clock drift between CMS and subscription server.
+ */
+declare class TotpKeyProvider {
+    private masterSecret;
+    private bucketPeriodSeconds;
+    constructor(options: TotpKeyProviderOptions);
+    /**
+     * Get keys for the given key IDs.
+     *
+     * For each keyId, returns two keys:
+     * - Current bucket key (e.g., "premium:1737158400")
+     * - Next bucket key (e.g., "premium:1737158430")
+     *
+     * This ensures content encrypted near a bucket boundary
+     * can still be decrypted after the bucket rotates.
+     */
+    getKeys(keyIds: string[]): Promise<KeyEntry[]>;
+    /**
+     * Derive a static key for an article (no time bucket).
+     * Useful for per-article purchase access.
+     */
+    getArticleKey(articleId: string): Promise<KeyEntry>;
+}
+/**
+ * Create a TOTP key provider for deriving time-bucket keys.
+ *
+ * Use this with CmsServer when you want to derive keys locally
+ * from a shared master secret (no API calls needed).
+ *
+ * @example
+ * ```typescript
+ * const totp = createTotpKeyProvider({
+ *   masterSecret: process.env.MASTER_SECRET,
+ *   bucketPeriodSeconds: 30,
+ * });
+ *
+ * const cms = createCmsServer({
+ *   getKeys: (keyIds) => totp.getKeys(keyIds),
+ * });
+ *
+ * // Or combine with article keys:
+ * const cms = createCmsServer({
+ *   getKeys: async (keyIds) => {
+ *     const keys = await totp.getKeys(keyIds);
+ *     // Add article key if requested
+ *     if (keyIds.some(id => id.startsWith('article:'))) {
+ *       const articleId = keyIds.find(id => id.startsWith('article:'))!.slice(8);
+ *       keys.push(await totp.getArticleKey(articleId));
+ *     }
+ *     return keys;
+ *   },
+ * });
+ * ```
+ */
+declare function createTotpKeyProvider(options: TotpKeyProviderOptions): TotpKeyProvider;
+/** @deprecated Use CmsServer instead */
+declare const CapsuleServer: typeof CmsServer;
+/** @deprecated Use CmsServerOptions instead */
+type CapsuleServerOptions = CmsServerOptions;
+/** @deprecated Use createCmsServer instead */
+declare const createCapsule: typeof createCmsServer;
+
+/**
+ * CMS Content Encryptor
+ *
+ * Provides envelope encryption for article content:
+ * 1. Content is encrypted ONCE with a unique DEK (AES-256-GCM)
+ * 2. The DEK is wrapped with MULTIPLE key-wrapping keys for different unlock paths
+ *
+ * Supports two modes for obtaining bucket keys:
+ * - TOTP: Derive keys locally from master secret (no network calls)
+ * - API: Fetch keys from subscription server
+ */
+
+/**
+ * CMS Content Encryptor for Capsule.
+ *
+ * Use this in your CMS to encrypt article content with envelope encryption.
+ */
+declare class CmsEncryptor {
+    private masterSecret;
+    private subscriptionServerUrl;
+    private apiKey;
+    private bucketPeriodSeconds;
+    constructor(options?: CmsEncryptorOptions);
+    /**
+     * Get bucket keys for a key ID.
+     *
+     * In TOTP mode: derives from master secret locally.
+     * In API mode: fetches from subscription server.
+     */
+    getBucketKeys(keyId: string): Promise<{
+        current: BucketKey;
+        next: BucketKey;
+    }>;
+    /**
+     * Encrypt article content with envelope encryption.
+     *
+     * The content is encrypted once with a unique DEK, then the DEK is wrapped
+     * with multiple key-wrapping keys for different unlock paths.
+     *
+     * @param articleId - Unique article identifier
+     * @param content - Plaintext content to encrypt
+     * @param keyConfigs - Array of key-wrapping configurations
+     * @returns Encrypted article with wrapped keys
+     */
+    encryptArticle(articleId: string, content: string, keyConfigs: KeyWrapConfig[]): EncryptedArticle;
+    /**
+     * Encrypt article with tier-based time-bucket keys.
+     *
+     * Automatically gets current and next bucket keys for the specified tier,
+     * plus any additional static keys (e.g., per-article keys).
+     *
+     * @param articleId - Unique article identifier
+     * @param content - Plaintext content to encrypt
+     * @param tier - Subscription tier (e.g., "premium")
+     * @param additionalKeys - Optional additional key configurations (e.g., per-article keys)
+     */
+    encryptArticleWithTier(articleId: string, content: string, tier: string, additionalKeys?: KeyWrapConfig[]): Promise<EncryptedArticle>;
+}
+/**
+ * Create a simple encryptor for TOTP mode.
+ */
+declare function createTotpEncryptor(masterSecret: string | Buffer, bucketPeriodSeconds?: number): CmsEncryptor;
+/**
+ * Create an encryptor that fetches keys from subscription server.
+ */
+declare function createApiEncryptor(subscriptionServerUrl: string, apiKey: string): CmsEncryptor;
+
+/**
+ * Subscription Server Utilities
+ *
+ * For building subscription server endpoints that:
+ * 1. Provide bucket keys to CMS (for encryption)
+ * 2. Unwrap DEKs for authenticated users (for decryption)
+ *
+ * @example
+ * ```typescript
+ * import { createSubscriptionServer } from '@sesamy/capsule-server';
+ *
+ * const server = createSubscriptionServer({
+ *   masterSecret: process.env.MASTER_SECRET,
+ *   bucketPeriodSeconds: 30,
+ * });
+ *
+ * // Endpoint for users to unlock content
+ * app.post('/api/unlock', async (req, res) => {
+ *   const { keyId, wrappedDek, publicKey } = req.body;
+ *   const result = await server.unlockForUser({ keyId, wrappedDek }, publicKey);
+ *   res.json(result);
+ * });
+ * ```
+ */
+
+/** Options for creating a subscription server */
+interface SubscriptionServerOptions {
+    /** Master secret for deriving bucket keys (base64 encoded string or Buffer) */
+    masterSecret: string | Buffer;
+    /** Bucket period in seconds (default: 30) */
+    bucketPeriodSeconds?: number;
+}
+/**
+ * Subscription Server for Capsule.
+ *
+ * Manages master secret and provides:
+ * - Bucket keys for CMS (time-limited)
+ * - DEK unwrapping for authenticated users
+ *
+ * @see createSubscriptionServer for the recommended way to create an instance
+ */
+declare class SubscriptionServer {
+    private masterSecret;
+    private bucketPeriodSeconds;
+    constructor(options: SubscriptionServerOptions);
+    /**
+     * Get bucket keys for a key ID (for CMS).
+     *
+     * Returns current and next bucket keys so CMS can encrypt
+     * content that works across bucket boundaries.
+     */
+    getBucketKeysForCms(keyId: string): {
+        current: BucketKey;
+        next: BucketKey;
+    };
+    /**
+     * Get bucket keys formatted for API response.
+     */
+    getBucketKeysResponse(keyId: string): {
+        current: {
+            bucketId: string;
+            key: string;
+            expiresAt: string;
+        };
+        next: {
+            bucketId: string;
+            key: string;
+            expiresAt: string;
+        };
+    };
+    /**
+     * Validate that a bucket ID is current or adjacent.
+     */
+    isBucketValid(bucketId: string): boolean;
+    /**
+     * Unwrap a DEK and re-wrap it with a user's RSA public key.
+     *
+     * This is the core unlock operation:
+     * 1. Parse the wrapped key to extract keyId and bucket info
+     * 2. Derive the key-wrapping key from master secret
+     * 3. Unwrap the DEK
+     * 4. Re-wrap with user's RSA public key
+     *
+     * @param wrappedKey - The wrapped key entry from the article
+     * @param userPublicKeyB64 - User's RSA public key (Base64 SPKI format)
+     * @param staticKeyLookup - Optional function to look up static keys (for per-article keys). Can be sync or async.
+     */
+    unlockForUser(wrappedKey: WrappedKey, userPublicKeyB64: string, staticKeyLookup?: (keyId: string) => Buffer | null | Promise<Buffer | null>): Promise<UnlockResponse>;
+    /**
+     * Internal helper to unwrap DEK and re-wrap with user's public key.
+     */
+    private unwrapAndRewrap;
+    /**
+     * Simple unlock when you already have the key-wrapping key.
+     * Used when the unlock logic is separate from bucket key derivation.
+     */
+    wrapDekForUser(dek: Buffer, userPublicKeyB64: string, keyId: string, expiresAt: Date): UnlockResponse;
+    /**
+     * Get the key-wrapping key for a bucket key ID.
+     * Useful when you need the raw key for custom logic.
+     */
+    getBucketKey(keyId: string, bucketId: string): Buffer;
+    /**
+     * Get the key-wrapping key for a tier, wrapped with user's RSA public key.
+     *
+     * This enables "unlock once, access all" for tier content:
+     * - Client receives the AES-KW key (not the DEK)
+     * - Client can unwrap any article's DEK locally
+     * - No per-article unlock requests needed
+     *
+     * @param tier - The tier name (e.g., "premium")
+     * @param bucketId - The bucket ID to get the key for
+     * @param userPublicKeyB64 - User's RSA public key (Base64 SPKI format)
+     */
+    getTierKeyForUser(tier: string, bucketId: string, userPublicKeyB64: string): UnlockResponse;
+    /**
+     * Convert Base64 SPKI to PEM format for Node.js crypto.
+     */
+    private convertToPem;
+}
+/**
+ * Create a subscription server for handling unlock requests.
+ *
+ * @example
+ * ```typescript
+ * const server = createSubscriptionServer({
+ *   masterSecret: process.env.MASTER_SECRET,
+ *   bucketPeriodSeconds: 30,
+ * });
+ *
+ * app.post('/api/unlock', async (req, res) => {
+ *   const { keyId, wrappedDek, publicKey } = req.body;
+ *   const result = await server.unlockForUser({ keyId, wrappedDek }, publicKey);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function createSubscriptionServer(options: SubscriptionServerOptions): SubscriptionServer;
+/**
+ * Create a subscription server (legacy signature).
+ * @deprecated Use createSubscriptionServer({ masterSecret, bucketPeriodSeconds }) instead
+ */
+declare function createSubscriptionServer(masterSecret: string | Buffer, bucketPeriodSeconds?: number): SubscriptionServer;
+
+/**
+ * AES-256-GCM encryption utilities.
+ *
+ * Provides content encryption with unique DEKs and key wrapping.
+ */
+/** GCM IV size in bytes (96 bits as recommended by NIST) */
+declare const GCM_IV_SIZE = 12;
+/** GCM authentication tag length in bytes */
+declare const GCM_TAG_LENGTH = 16;
+/** AES-256 key size in bytes */
+declare const AES_KEY_SIZE = 32;
+/**
+ * Generate a random 256-bit AES key (DEK).
+ */
+declare function generateDek(): Buffer;
+/**
+ * Generate a random IV for AES-GCM.
+ */
+declare function generateIv(): Buffer;
+/**
+ * Encrypt content with AES-256-GCM.
+ *
+ * @param content - Plaintext content to encrypt
+ * @param dek - 256-bit AES key
+ * @param iv - 96-bit initialization vector (generated if not provided)
+ * @returns Encrypted content (ciphertext + auth tag) and IV
+ */
+declare function encryptContent(content: string | Buffer, dek: Buffer, iv?: Buffer): {
+    encryptedContent: Buffer;
+    iv: Buffer;
+};
+/**
+ * Decrypt content with AES-256-GCM.
+ *
+ * @param encryptedContent - Ciphertext + auth tag
+ * @param dek - 256-bit AES key
+ * @param iv - Initialization vector used for encryption
+ * @returns Decrypted plaintext
+ */
+declare function decryptContent(encryptedContent: Buffer, dek: Buffer, iv: Buffer): Buffer;
+/**
+ * Wrap (encrypt) a DEK with a key-wrapping key using AES-256-GCM.
+ *
+ * This is used to create multiple wrapped versions of the same DEK,
+ * each encrypted with a different key-wrapping key.
+ *
+ * @param dek - The data encryption key to wrap
+ * @param wrappingKey - The key-wrapping key (256-bit AES)
+ * @returns Wrapped DEK (IV + ciphertext + auth tag)
+ */
+declare function wrapDek(dek: Buffer, wrappingKey: Buffer): Buffer;
+/**
+ * Unwrap (decrypt) a DEK with a key-wrapping key.
+ *
+ * @param wrappedDek - The wrapped DEK (IV + ciphertext + auth tag)
+ * @param wrappingKey - The key-wrapping key used to wrap
+ * @returns The unwrapped DEK
+ */
+declare function unwrapDek(wrappedDek: Buffer, wrappingKey: Buffer): Buffer;
+
+/**
+ * Time-bucket key derivation using HKDF (TOTP-style).
+ *
+ * Derives deterministic AES-256 keys from a master secret and time bucket ID.
+ * Keys rotate every `bucketPeriodSeconds` (default: 30 seconds like TOTP).
+ */
+
+/** Default bucket period in seconds (30s like TOTP) */
+declare const DEFAULT_BUCKET_PERIOD_SECONDS = 30;
+/**
+ * HKDF key derivation function (RFC 5869).
+ * Derives a key from input keying material using HMAC-SHA256.
+ */
+declare function hkdf(ikm: Buffer, salt: Buffer | string, info: Buffer | string, length: number): Buffer;
+/**
+ * Get the bucket ID for a given timestamp.
+ */
+declare function getBucketId(timestampMs?: number, bucketPeriodSeconds?: number): string;
+/**
+ * Get the current bucket ID.
+ */
+declare function getCurrentBucket(bucketPeriodSeconds?: number): string;
+/**
+ * Get the next bucket ID.
+ */
+declare function getNextBucket(bucketPeriodSeconds?: number): string;
+/**
+ * Get the previous bucket ID.
+ */
+declare function getPreviousBucket(bucketPeriodSeconds?: number): string;
+/**
+ * Get when a bucket expires.
+ */
+declare function getBucketExpiration(bucketId: string, bucketPeriodSeconds?: number): Date;
+/**
+ * Check if a bucket is currently valid (current, next, or previous for grace period).
+ */
+declare function isBucketValid(bucketId: string, bucketPeriodSeconds?: number): boolean;
+/**
+ * Derive a bucket key from master secret + bucket ID using HKDF.
+ *
+ * @param masterSecret - The master secret (256-bit)
+ * @param keyId - The key identifier (e.g., tier name like "premium")
+ * @param bucketId - The bucket identifier
+ * @returns 256-bit AES key
+ */
+declare function deriveBucketKey(masterSecret: Buffer, keyId: string, bucketId: string): Buffer;
+/**
+ * Get bucket key with metadata.
+ */
+declare function getBucketKey(masterSecret: Buffer, keyId: string, bucketId: string, bucketPeriodSeconds?: number): BucketKey;
+/**
+ * Get current and next bucket keys for a key ID.
+ * Used by CMS to wrap content DEKs for both time windows.
+ */
+declare function getBucketKeys(masterSecret: Buffer, keyId: string, bucketPeriodSeconds?: number): {
+    current: BucketKey;
+    next: BucketKey;
+};
+/**
+ * Generate a new master secret (256-bit random).
+ */
+declare function generateMasterSecret(): Buffer;
+
+export { AES_KEY_SIZE, type BucketKey, type BucketKeysResponse, CapsuleServer, type CapsuleServerOptions, CmsEncryptor, type CmsEncryptorOptions, CmsServer, type CmsServerOptions, DEFAULT_BUCKET_PERIOD_SECONDS, type EncryptOptions, type EncryptedArticle, GCM_IV_SIZE, GCM_TAG_LENGTH, type KeyEntry, type KeyProvider, type KeyWrapConfig, type SubscriptionClientOptions, SubscriptionServer, TotpKeyProvider, type TotpKeyProviderOptions, type UnlockResponse, type WrappedKey, createApiEncryptor, createCapsule, createCmsServer, createSubscriptionServer, createTotpEncryptor, createTotpKeyProvider, decryptContent, deriveBucketKey, encryptContent, generateDek, generateIv, generateMasterSecret, getBucketExpiration, getBucketId, getBucketKey, getBucketKeys, getCurrentBucket, getNextBucket, getPreviousBucket, hkdf, isBucketValid, unwrapDek, wrapDek };