llmtxt 2026.4.0

package/dist/sdk/storage.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Storage content reference types.
+ *
+ * Abstracts where document content lives -- inline in a database column
+ * or in an external object store (S3-compatible). Platform implementations
+ * provide the actual storage backend; llmtxt defines the portable types.
+ */
+/** How document content is stored. */
+export type StorageType = 'inline' | 'object-store';
+/** Compression method used for stored content. */
+export type CompressionMethod = 'deflate' | 'none';
+/**
+ * Reference to where a document's compressed content lives.
+ *
+ * Inline: content is stored directly in the database (small documents).
+ * Object-store: content is stored in S3-compatible storage, referenced by key.
+ */
+export interface ContentRef {
+    /** Storage backend type. */
+    type: StorageType;
+    /**
+     * Location of the content.
+     * - For `inline`: not used (content is in the database row).
+     * - For `object-store`: the object key (e.g. `attachments/xK9mP2nQ/v3.zlib`).
+     */
+    storageKey?: string;
+    /** SHA-256 hash of the uncompressed content for integrity verification. */
+    contentHash: string;
+    /** Size of the uncompressed content in bytes. */
+    originalSize: number;
+    /** Size of the compressed content in bytes. */
+    compressedSize: number;
+    /** Compression method used. */
+    compression: CompressionMethod;
+}
+/** Metadata about a stored document blob. */
+export interface StorageMetadata {
+    /** Content reference. */
+    ref: ContentRef;
+    /** When the content was first stored (ms since epoch). */
+    createdAt: number;
+    /** When the content was last accessed (ms since epoch). */
+    lastAccessedAt: number;
+    /** Number of times the content has been accessed. */
+    accessCount: number;
+}
+/**
+ * Create a content reference for inline storage.
+ *
+ * @param contentHash - SHA-256 hash of the uncompressed content.
+ * @param originalSize - Size of the uncompressed content in bytes.
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @returns An inline content reference.
+ */
+export declare function inlineRef(contentHash: string, originalSize: number, compressedSize: number): ContentRef;
+/**
+ * Create a content reference for object-store storage.
+ *
+ * @param storageKey - The object key in the store.
+ * @param contentHash - SHA-256 hash of the uncompressed content.
+ * @param originalSize - Size of the uncompressed content in bytes.
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @returns An object-store content reference.
+ */
+export declare function objectStoreRef(storageKey: string, contentHash: string, originalSize: number, compressedSize: number): ContentRef;
+/**
+ * Generate a storage key for a document version.
+ *
+ * Convention: `attachments/{slug}/v{version}.zlib`
+ *
+ * @param slug - Document slug.
+ * @param version - Version number.
+ * @returns The object storage key.
+ */
+export declare function versionStorageKey(slug: string, version: number): string;
+/**
+ * Determine whether content should be stored in object-store vs inline.
+ *
+ * Threshold: content larger than 64KB compressed goes to object-store.
+ *
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @param threshold - Size threshold in bytes. Defaults to 65536 (64KB).
+ * @returns `true` if the content should use object-store.
+ */
+export declare function shouldUseObjectStore(compressedSize: number, threshold?: number): boolean;
+//# sourceMappingURL=storage.d.ts.map

package/dist/sdk/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/sdk/storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEpD,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,WAAW,EAAE,iBAAiB,CAAC;CAChC;AAID,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,GAAG,EAAE,UAAU,CAAC;IAChB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,UAAU,CAQZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,UAAU,CASZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAEvF"}

package/dist/sdk/storage.js

@@ -0,0 +1,69 @@
+/**
+ * Storage content reference types.
+ *
+ * Abstracts where document content lives -- inline in a database column
+ * or in an external object store (S3-compatible). Platform implementations
+ * provide the actual storage backend; llmtxt defines the portable types.
+ */
+// ── Helpers ────────────────────────────────────────────────────
+/**
+ * Create a content reference for inline storage.
+ *
+ * @param contentHash - SHA-256 hash of the uncompressed content.
+ * @param originalSize - Size of the uncompressed content in bytes.
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @returns An inline content reference.
+ */
+export function inlineRef(contentHash, originalSize, compressedSize) {
+    return {
+        type: 'inline',
+        contentHash,
+        originalSize,
+        compressedSize,
+        compression: 'deflate',
+    };
+}
+/**
+ * Create a content reference for object-store storage.
+ *
+ * @param storageKey - The object key in the store.
+ * @param contentHash - SHA-256 hash of the uncompressed content.
+ * @param originalSize - Size of the uncompressed content in bytes.
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @returns An object-store content reference.
+ */
+export function objectStoreRef(storageKey, contentHash, originalSize, compressedSize) {
+    return {
+        type: 'object-store',
+        storageKey,
+        contentHash,
+        originalSize,
+        compressedSize,
+        compression: 'deflate',
+    };
+}
+/**
+ * Generate a storage key for a document version.
+ *
+ * Convention: `attachments/{slug}/v{version}.zlib`
+ *
+ * @param slug - Document slug.
+ * @param version - Version number.
+ * @returns The object storage key.
+ */
+export function versionStorageKey(slug, version) {
+    return `attachments/${slug}/v${version}.zlib`;
+}
+/**
+ * Determine whether content should be stored in object-store vs inline.
+ *
+ * Threshold: content larger than 64KB compressed goes to object-store.
+ *
+ * @param compressedSize - Size of the compressed content in bytes.
+ * @param threshold - Size threshold in bytes. Defaults to 65536 (64KB).
+ * @returns `true` if the content should use object-store.
+ */
+export function shouldUseObjectStore(compressedSize, threshold = 65536) {
+    return compressedSize > threshold;
+}
+//# sourceMappingURL=storage.js.map

package/dist/sdk/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/sdk/storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiDH,kEAAkE;AAElE;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACvB,WAAmB,EACnB,YAAoB,EACpB,cAAsB;IAEtB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW;QACX,YAAY;QACZ,cAAc;QACd,WAAW,EAAE,SAAS;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAkB,EAClB,WAAmB,EACnB,YAAoB,EACpB,cAAsB;IAEtB,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,UAAU;QACV,WAAW;QACX,YAAY;QACZ,cAAc;QACd,WAAW,EAAE,SAAS;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe;IAC7D,OAAO,eAAe,IAAI,KAAK,OAAO,OAAO,CAAC;AAChD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,cAAsB,EAAE,SAAS,GAAG,KAAK;IAC5E,OAAO,cAAc,GAAG,SAAS,CAAC;AACpC,CAAC"}

package/dist/sdk/versions.d.ts

@@ -0,0 +1,107 @@
+/** A single version entry in a document's patch stack. */
+export interface VersionEntry {
+    /** Sequential version number (1-based). */
+    versionNumber: number;
+    /** Unified diff patch text. */
+    patchText: string;
+    /** Agent that authored this version. */
+    createdBy: string;
+    /** One-line description of the change. */
+    changelog: string;
+    /** SHA-256 hash of the resulting content after applying this patch. */
+    contentHash: string;
+    /** Timestamp of creation (ms since epoch). */
+    createdAt: number;
+}
+/** Result of reconstructing a document at a specific version. */
+export interface ReconstructionResult {
+    /** The document content at the requested version. */
+    content: string;
+    /** The version number that was reconstructed. */
+    version: number;
+    /** Number of patches applied to reach this version. */
+    patchesApplied: number;
+    /** SHA-256 hash of the reconstructed content. */
+    contentHash: string;
+    /** Token count of the reconstructed content. */
+    tokenCount: number;
+}
+/** Result of validating whether a patch applies cleanly. */
+export interface PatchValidationResult {
+    /** Whether the patch can be applied without conflicts. */
+    applies: boolean;
+    /** Error message if the patch does not apply. */
+    error?: string;
+    /** The content that would result if the patch applies. */
+    resultContent?: string;
+}
+/**
+ * Reconstruct a document at a specific version by applying patches
+ * sequentially from the base content.
+ *
+ * @param baseContent - The original document content (version 0).
+ * @param patches - Ordered array of version entries.
+ * @param targetVersion - The version to reconstruct. Defaults to latest.
+ * @returns The reconstructed document content and metadata.
+ * @throws If a patch in the sequence fails to apply.
+ */
+export declare function reconstructVersion(baseContent: string, patches: VersionEntry[], targetVersion?: number): ReconstructionResult;
+/**
+ * Check whether a patch applies cleanly to the given content.
+ *
+ * @param content - The current document content.
+ * @param patchText - The unified diff to test.
+ * @returns Whether the patch applies and the resulting content.
+ */
+export declare function validatePatchApplies(content: string, patchText: string): PatchValidationResult;
+/**
+ * Squash a sequence of patches into a single unified diff.
+ *
+ * Applies all patches sequentially to the base content, then produces
+ * one diff from base to final state.
+ *
+ * @param baseContent - The content before the first patch.
+ * @param patches - Ordered array of version entries to squash.
+ * @returns A single patch text and the final content hash.
+ */
+export declare function squashPatches(baseContent: string, patches: VersionEntry[]): {
+    patchText: string;
+    contentHash: string;
+    tokenCount: number;
+};
+/**
+ * Compute a reverse patch that undoes a version's changes.
+ *
+ * @param contentBefore - Document content before the patch was applied.
+ * @param contentAfter - Document content after the patch was applied.
+ * @returns A unified diff that reverts `contentAfter` back to `contentBefore`.
+ */
+export declare function computeReversePatch(contentBefore: string, contentAfter: string): string;
+/** Summary of changes between two versions. */
+export interface VersionDiffSummary {
+    /** Source version number. */
+    fromVersion: number;
+    /** Target version number. */
+    toVersion: number;
+    /** Lines added between versions. */
+    addedLines: number;
+    /** Lines removed between versions. */
+    removedLines: number;
+    /** Tokens added between versions. */
+    addedTokens: number;
+    /** Tokens removed between versions. */
+    removedTokens: number;
+    /** Unified diff text. */
+    patchText: string;
+}
+/**
+ * Compute a diff summary between two versions of a document.
+ *
+ * @param baseContent - The original document content (version 0).
+ * @param patches - Full ordered patch stack.
+ * @param fromVersion - Start version.
+ * @param toVersion - End version.
+ * @returns Diff statistics and patch text between the two versions.
+ */
+export declare function diffVersions(baseContent: string, patches: VersionEntry[], fromVersion: number, toVersion: number): VersionDiffSummary;
+//# sourceMappingURL=versions.d.ts.map

package/dist/sdk/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/sdk/versions.ts"],"names":[],"mappings":"AAYA,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EAAE,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,oBAAoB,CA4BtB;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,qBAAqB,CAavB;AAID;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EAAE,GACtB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAchE;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,MAAM,CAER;AAID,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAepB"}

package/dist/sdk/versions.js

@@ -0,0 +1,129 @@
+/**
+ * Version stack management for collaborative documents.
+ *
+ * Provides helpers to reconstruct any version from a base document
+ * plus a sequence of patches, validate patch applicability, squash
+ * consecutive patches, and compute reverse patches for rollback.
+ */
+import { createPatch, applyPatch, reconstructVersion as wasmReconstruct, squashPatchesWasm } from '../patch.js';
+import { calculateTokens, hashContent, computeDiff } from '../compression.js';
+// ── Reconstruction ─────────────────────────────────────────────
+/**
+ * Reconstruct a document at a specific version by applying patches
+ * sequentially from the base content.
+ *
+ * @param baseContent - The original document content (version 0).
+ * @param patches - Ordered array of version entries.
+ * @param targetVersion - The version to reconstruct. Defaults to latest.
+ * @returns The reconstructed document content and metadata.
+ * @throws If a patch in the sequence fails to apply.
+ */
+export function reconstructVersion(baseContent, patches, targetVersion) {
+    const sorted = [...patches].sort((a, b) => a.versionNumber - b.versionNumber);
+    const target = targetVersion ?? (sorted.length > 0 ? sorted[sorted.length - 1].versionNumber : 0);
+    if (target === 0) {
+        return {
+            content: baseContent,
+            version: 0,
+            patchesApplied: 0,
+            contentHash: hashContent(baseContent),
+            tokenCount: calculateTokens(baseContent),
+        };
+    }
+    // Delegate to Rust for N patch applications in a single WASM call
+    const patchTexts = sorted
+        .filter(e => e.versionNumber <= target)
+        .map(e => e.patchText);
+    const patchesJson = JSON.stringify(patchTexts);
+    const content = wasmReconstruct(baseContent, patchesJson, patchTexts.length);
+    return {
+        content,
+        version: target,
+        patchesApplied: patchTexts.length,
+        contentHash: hashContent(content),
+        tokenCount: calculateTokens(content),
+    };
+}
+// ── Validation ─────────────────────────────────────────────────
+/**
+ * Check whether a patch applies cleanly to the given content.
+ *
+ * @param content - The current document content.
+ * @param patchText - The unified diff to test.
+ * @returns Whether the patch applies and the resulting content.
+ */
+export function validatePatchApplies(content, patchText) {
+    try {
+        const result = applyPatch(content, patchText);
+        if (result === content && patchText.trim().length > 0) {
+            return { applies: false, error: 'Patch did not modify content (possible conflict)' };
+        }
+        return { applies: true, resultContent: result };
+    }
+    catch (err) {
+        return {
+            applies: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// ── Squashing ──────────────────────────────────────────────────
+/**
+ * Squash a sequence of patches into a single unified diff.
+ *
+ * Applies all patches sequentially to the base content, then produces
+ * one diff from base to final state.
+ *
+ * @param baseContent - The content before the first patch.
+ * @param patches - Ordered array of version entries to squash.
+ * @returns A single patch text and the final content hash.
+ */
+export function squashPatches(baseContent, patches) {
+    const sorted = [...patches].sort((a, b) => a.versionNumber - b.versionNumber);
+    const patchesJson = JSON.stringify(sorted.map(e => e.patchText));
+    // Single WASM call: apply all patches then diff base vs final
+    const patchText = squashPatchesWasm(baseContent, patchesJson);
+    // Reconstruct final content to compute hash and tokens
+    const finalContent = wasmReconstruct(baseContent, patchesJson, sorted.length);
+    return {
+        patchText,
+        contentHash: hashContent(finalContent),
+        tokenCount: calculateTokens(finalContent),
+    };
+}
+// ── Reverse Patch ──────────────────────────────────────────────
+/**
+ * Compute a reverse patch that undoes a version's changes.
+ *
+ * @param contentBefore - Document content before the patch was applied.
+ * @param contentAfter - Document content after the patch was applied.
+ * @returns A unified diff that reverts `contentAfter` back to `contentBefore`.
+ */
+export function computeReversePatch(contentBefore, contentAfter) {
+    return createPatch(contentAfter, contentBefore);
+}
+/**
+ * Compute a diff summary between two versions of a document.
+ *
+ * @param baseContent - The original document content (version 0).
+ * @param patches - Full ordered patch stack.
+ * @param fromVersion - Start version.
+ * @param toVersion - End version.
+ * @returns Diff statistics and patch text between the two versions.
+ */
+export function diffVersions(baseContent, patches, fromVersion, toVersion) {
+    const fromContent = reconstructVersion(baseContent, patches, fromVersion).content;
+    const toContent = reconstructVersion(baseContent, patches, toVersion).content;
+    const diff = computeDiff(fromContent, toContent);
+    const patchText = createPatch(fromContent, toContent);
+    return {
+        fromVersion,
+        toVersion,
+        addedLines: diff.addedLines,
+        removedLines: diff.removedLines,
+        addedTokens: diff.addedTokens,
+        removedTokens: diff.removedTokens,
+        patchText,
+    };
+}
+//# sourceMappingURL=versions.js.map

package/dist/sdk/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/sdk/versions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,IAAI,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA4C9E,kEAAkE;AAElE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,OAAuB,EACvB,aAAsB;IAEtB,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElG,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QACjB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,CAAC;YACV,cAAc,EAAE,CAAC;YACjB,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC;YACrC,UAAU,EAAE,eAAe,CAAC,WAAW,CAAC;SACzC,CAAC;IACJ,CAAC;IAED,kEAAkE;IAClE,MAAM,UAAU,GAAG,MAAM;SACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,MAAM,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACzB,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE7E,OAAO;QACL,OAAO;QACP,OAAO,EAAE,MAAM;QACf,cAAc,EAAE,UAAU,CAAC,MAAM;QACjC,WAAW,EAAE,WAAW,CAAC,OAAO,CAAC;QACjC,UAAU,EAAE,eAAe,CAAC,OAAO,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,kEAAkE;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kDAAkD,EAAE,CAAC;QACvF,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kEAAkE;AAElE;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,WAAmB,EACnB,OAAuB;IAEvB,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC;IAC9E,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAEjE,8DAA8D;IAC9D,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAE9D,uDAAuD;IACvD,MAAM,YAAY,GAAG,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9E,OAAO;QACL,SAAS;QACT,WAAW,EAAE,WAAW,CAAC,YAAY,CAAC;QACtC,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,kEAAkE;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,aAAqB,EACrB,YAAoB;IAEpB,OAAO,WAAW,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAsBD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAmB,EACnB,OAAuB,EACvB,WAAmB,EACnB,SAAiB;IAEjB,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,OAAO,CAAC;IAClF,MAAM,SAAS,GAAG,kBAAkB,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC;IAC9E,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAEtD,OAAO;QACL,WAAW;QACX,SAAS;QACT,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/signed-url.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Parameters that uniquely identify a signed URL access grant.
+ */
+export interface SignedUrlParams {
+    slug: string;
+    agentId: string;
+    conversationId: string;
+    expiresAt: number;
+}
+/**
+ * Configuration for generating and verifying signed URLs.
+ */
+export interface SignedUrlConfig {
+    secret: string;
+    baseUrl: string;
+    /** Optional path prefix like `/attachments`. Default: root path. */
+    pathPrefix?: string;
+    /** Signature length in hex chars. Default: 16. */
+    signatureLength?: number;
+}
+/**
+ * Outcome of verifying a signed URL.
+ */
+export interface VerifyResult {
+    valid: boolean;
+    reason?: 'missing_params' | 'expired' | 'invalid_signature';
+    params?: SignedUrlParams;
+}
+/**
+ * Compute the HMAC-SHA256 signature for signed URL parameters.
+ * Delegates to the Rust WASM module.
+ */
+export declare function computeSignature(params: SignedUrlParams, secret: string): string;
+/**
+ * Compute signature with configurable length.
+ * Use 16 for short-lived URLs (default), 32 for long-lived URLs (128 bits).
+ */
+export declare function computeSignatureWithLength(params: SignedUrlParams, secret: string, sigLength: number): string;
+/**
+ * Generate a signed URL for accessing a document.
+ */
+export declare function generateSignedUrl(params: SignedUrlParams, config: SignedUrlConfig): string;
+/**
+ * Verify a signed URL's signature and expiration.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+export declare function verifySignedUrl(url: string | URL, secret: string): VerifyResult;
+/**
+ * Parameters for org-scoped signed URLs (Phase 5 enterprise).
+ * Extends conversation-scoped params with an organization ID.
+ */
+export interface OrgSignedUrlParams extends SignedUrlParams {
+    orgId: string;
+}
+/**
+ * Compute the HMAC-SHA256 signature for org-scoped signed URL parameters.
+ * Includes orgId in the HMAC payload for organization-level access control.
+ * Returns 32 hex characters (128 bits) by default.
+ */
+export declare function computeOrgSignature(params: OrgSignedUrlParams, secret: string): string;
+/**
+ * Compute org-scoped signature with configurable length.
+ */
+export declare function computeOrgSignatureWithLength(params: OrgSignedUrlParams, secret: string, sigLength: number): string;
+/**
+ * Generate an org-scoped signed URL for accessing a document.
+ * The URL includes the org parameter for organization-level access verification.
+ */
+export declare function generateOrgSignedUrl(params: OrgSignedUrlParams, config: SignedUrlConfig): string;
+/**
+ * Verify an org-scoped signed URL's signature and expiration.
+ */
+export declare function verifyOrgSignedUrl(url: string | URL, secret: string): VerifyResult & {
+    orgId?: string;
+};
+/**
+ * Generate a signed URL that expires after the given duration.
+ */
+export declare function generateTimedUrl(params: Omit<SignedUrlParams, 'expiresAt'>, config: SignedUrlConfig, ttlMs?: number): string;
+/**
+ * Derive a per-agent signing key from their API key.
+ * Delegates to the Rust WASM module.
+ */
+export declare function deriveSigningKey(apiKey: string): string;
+/**
+ * Check whether a timestamp has expired.
+ * Returns false for null/undefined (no expiration set).
+ */
+export declare function isExpired(expiresAt: number | null | undefined): boolean;
+//# sourceMappingURL=signed-url.d.ts.map

package/dist/signed-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-url.d.ts","sourceRoot":"","sources":["../src/signed-url.ts"],"names":[],"mappings":"AAmBA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,mBAAmB,CAAC;IAC5D,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQhF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CASR;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAS1F;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CA8B/E;AAOD;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAStF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAUhG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA8BvG;AAID;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,EAC1C,MAAM,EAAE,eAAe,EACvB,KAAK,SAAiB,GACrB,MAAM,CAKR;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAcD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGvE"}

package/dist/signed-url.js

@@ -0,0 +1,159 @@
+/**
+ * Signed URL generation and verification for conversation-scoped,
+ * time-limited access to llmtxt content.
+ *
+ * HMAC computation and key derivation delegate to the Rust WASM module.
+ * URL construction and verification logic stays in TypeScript (URL parsing
+ * is complex in WASM and not needed in the Rust native crate).
+ */
+import { computeSignature as wasmComputeSignature, computeSignatureWithLength as wasmComputeSignatureWithLength, computeOrgSignature as wasmComputeOrgSignature, computeOrgSignatureWithLength as wasmComputeOrgSignatureWithLength, deriveSigningKey as wasmDeriveSigningKey, isExpired as wasmIsExpired, } from './wasm.js';
+// ── Signature (WASM-backed) ─────────────────────────────────────
+/**
+ * Compute the HMAC-SHA256 signature for signed URL parameters.
+ * Delegates to the Rust WASM module.
+ */
+export function computeSignature(params, secret) {
+    return wasmComputeSignature(params.slug, params.agentId, params.conversationId, params.expiresAt, secret);
+}
+/**
+ * Compute signature with configurable length.
+ * Use 16 for short-lived URLs (default), 32 for long-lived URLs (128 bits).
+ */
+export function computeSignatureWithLength(params, secret, sigLength) {
+    return wasmComputeSignatureWithLength(params.slug, params.agentId, params.conversationId, params.expiresAt, secret, sigLength);
+}
+// ── Generate ────────────────────────────────────────────────────
+/**
+ * Generate a signed URL for accessing a document.
+ */
+export function generateSignedUrl(params, config) {
+    const signatureLength = config.signatureLength ?? 16;
+    const signature = computeSignatureWithLength(params, config.secret, signatureLength);
+    const url = new URL(buildSignedUrlPath(params.slug, config.pathPrefix), config.baseUrl);
+    url.searchParams.set('agent', params.agentId);
+    url.searchParams.set('conv', params.conversationId);
+    url.searchParams.set('exp', String(params.expiresAt));
+    url.searchParams.set('sig', signature);
+    return url.toString();
+}
+// ── Verify ──────────────────────────────────────────────────────
+/**
+ * Verify a signed URL's signature and expiration.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+export function verifySignedUrl(url, secret) {
+    const parsed = typeof url === 'string' ? new URL(url) : url;
+    const slug = getSignedUrlSlug(parsed);
+    const agent = parsed.searchParams.get('agent');
+    const conv = parsed.searchParams.get('conv');
+    const exp = parsed.searchParams.get('exp');
+    const sig = parsed.searchParams.get('sig');
+    if (!slug || !agent || !conv || !exp || !sig) {
+        return { valid: false, reason: 'missing_params' };
+    }
+    const expiresAt = parseInt(exp, 10);
+    if (isNaN(expiresAt) || isExpired(expiresAt)) {
+        return { valid: false, reason: 'expired' };
+    }
+    const params = { slug, agentId: agent, conversationId: conv, expiresAt };
+    const expected = computeSignatureWithLength(params, secret, sig.length);
+    // Timing-safe comparison
+    const sigBuf = Buffer.from(sig, 'utf-8');
+    const expBuf = Buffer.from(expected, 'utf-8');
+    if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+        return { valid: false, reason: 'invalid_signature' };
+    }
+    return { valid: true, params };
+}
+// Keep timing-safe from Node.js crypto for the URL verification step
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Compute the HMAC-SHA256 signature for org-scoped signed URL parameters.
+ * Includes orgId in the HMAC payload for organization-level access control.
+ * Returns 32 hex characters (128 bits) by default.
+ */
+export function computeOrgSignature(params, secret) {
+    return wasmComputeOrgSignature(params.slug, params.agentId, params.conversationId, params.orgId, params.expiresAt, secret);
+}
+/**
+ * Compute org-scoped signature with configurable length.
+ */
+export function computeOrgSignatureWithLength(params, secret, sigLength) {
+    return wasmComputeOrgSignatureWithLength(params.slug, params.agentId, params.conversationId, params.orgId, params.expiresAt, secret, sigLength);
+}
+/**
+ * Generate an org-scoped signed URL for accessing a document.
+ * The URL includes the org parameter for organization-level access verification.
+ */
+export function generateOrgSignedUrl(params, config) {
+    const signatureLength = config.signatureLength ?? 32;
+    const signature = computeOrgSignatureWithLength(params, config.secret, signatureLength);
+    const url = new URL(buildSignedUrlPath(params.slug, config.pathPrefix), config.baseUrl);
+    url.searchParams.set('agent', params.agentId);
+    url.searchParams.set('conv', params.conversationId);
+    url.searchParams.set('org', params.orgId);
+    url.searchParams.set('exp', String(params.expiresAt));
+    url.searchParams.set('sig', signature);
+    return url.toString();
+}
+/**
+ * Verify an org-scoped signed URL's signature and expiration.
+ */
+export function verifyOrgSignedUrl(url, secret) {
+    const parsed = typeof url === 'string' ? new URL(url) : url;
+    const slug = getSignedUrlSlug(parsed);
+    const agent = parsed.searchParams.get('agent');
+    const conv = parsed.searchParams.get('conv');
+    const org = parsed.searchParams.get('org');
+    const exp = parsed.searchParams.get('exp');
+    const sig = parsed.searchParams.get('sig');
+    if (!slug || !agent || !conv || !org || !exp || !sig) {
+        return { valid: false, reason: 'missing_params' };
+    }
+    const expiresAt = parseInt(exp, 10);
+    if (isNaN(expiresAt) || isExpired(expiresAt)) {
+        return { valid: false, reason: 'expired' };
+    }
+    const params = { slug, agentId: agent, conversationId: conv, orgId: org, expiresAt };
+    const expected = computeOrgSignatureWithLength(params, secret, sig.length);
+    const sigBuf = Buffer.from(sig, 'utf-8');
+    const expBuf = Buffer.from(expected, 'utf-8');
+    if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+        return { valid: false, reason: 'invalid_signature' };
+    }
+    return { valid: true, params, orgId: org };
+}
+// ── Convenience ─────────────────────────────────────────────────
+/**
+ * Generate a signed URL that expires after the given duration.
+ */
+export function generateTimedUrl(params, config, ttlMs = 60 * 60 * 1000) {
+    return generateSignedUrl({ ...params, expiresAt: Date.now() + ttlMs }, config);
+}
+// ── Key Derivation (WASM-backed) ────────────────────────────────
+/**
+ * Derive a per-agent signing key from their API key.
+ * Delegates to the Rust WASM module.
+ */
+export function deriveSigningKey(apiKey) {
+    return wasmDeriveSigningKey(apiKey);
+}
+function buildSignedUrlPath(slug, pathPrefix = '') {
+    const normalizedPrefix = pathPrefix.replace(/\/+$/, '').replace(/^([^/])/, '/$1');
+    return normalizedPrefix ? `${normalizedPrefix}/${slug}` : `/${slug}`;
+}
+function getSignedUrlSlug(url) {
+    const segments = url.pathname.split('/').filter(Boolean);
+    return segments.at(-1) ?? '';
+}
+// ── Expiration (WASM-backed) ────────────────────────────────────
+/**
+ * Check whether a timestamp has expired.
+ * Returns false for null/undefined (no expiration set).
+ */
+export function isExpired(expiresAt) {
+    if (expiresAt == null)
+        return false;
+    return wasmIsExpired(expiresAt);
+}
+//# sourceMappingURL=signed-url.js.map