@rahul_dadhich15/archive-kit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,298 @@
1
+ import { B as BinaryInput } from '../types-CY4dTVyZ.js';
2
+
3
+ /**
4
+ * Metadata and properties of an entry inside a ZIP archive.
5
+ */
6
+ interface ZipEntryInfo {
7
+ /**
8
+ * Relative normalized path inside the archive.
9
+ */
10
+ path: string;
11
+ /**
12
+ * Filename or directory name component.
13
+ */
14
+ name: string;
15
+ /**
16
+ * True if entry is a directory (path ends with '/').
17
+ */
18
+ isDirectory: boolean;
19
+ /**
20
+ * Compressed payload size in bytes.
21
+ */
22
+ compressedSize: number;
23
+ /**
24
+ * Uncompressed payload size in bytes.
25
+ */
26
+ uncompressedSize: number;
27
+ /**
28
+ * Compression method (0 = STORE, 8 = DEFLATE).
29
+ */
30
+ compressionMethod: number;
31
+ /**
32
+ * Last modification timestamp if recorded in archive.
33
+ */
34
+ lastModified?: Date;
35
+ /**
36
+ * CRC-32 checksum from archive header.
37
+ */
38
+ crc32?: number;
39
+ /**
40
+ * Optional entry comment.
41
+ */
42
+ comment?: string;
43
+ /**
44
+ * True if entry is password/AES encrypted.
45
+ */
46
+ encrypted: boolean;
47
+ }
48
+ /**
49
+ * An extracted entry containing decompressed data and helper methods.
50
+ */
51
+ interface ExtractedZipEntry extends ZipEntryInfo {
52
+ /**
53
+ * The decompressed binary content.
54
+ */
55
+ data: Uint8Array;
56
+ /**
57
+ * Decodes entry data as a UTF-8 text string.
58
+ */
59
+ text(): string;
60
+ /**
61
+ * Wraps entry data in a browser-native Blob.
62
+ */
63
+ blob(mimeType?: string): Blob;
64
+ }
65
+ /**
66
+ * Result of extracting an entire ZIP archive or filtered subset.
67
+ */
68
+ interface ExtractedZipArchive {
69
+ /**
70
+ * List of extracted entries.
71
+ */
72
+ entries: ExtractedZipEntry[];
73
+ /**
74
+ * Total number of extracted files.
75
+ */
76
+ totalFiles: number;
77
+ /**
78
+ * Total number of extracted directories.
79
+ */
80
+ totalDirectories: number;
81
+ /**
82
+ * Aggregate compressed size in bytes.
83
+ */
84
+ totalCompressedSize: number;
85
+ /**
86
+ * Aggregate uncompressed size in bytes.
87
+ */
88
+ totalUncompressedSize: number;
89
+ /**
90
+ * Global archive comment, if present.
91
+ */
92
+ comment?: string;
93
+ }
94
+ /**
95
+ * High-level metadata summary of a ZIP archive.
96
+ */
97
+ interface ZipMetadata {
98
+ /**
99
+ * True if archive is structurally valid.
100
+ */
101
+ isValid: boolean;
102
+ /**
103
+ * Total entry count in central directory.
104
+ */
105
+ entryCount: number;
106
+ /**
107
+ * Sum of compressed sizes of all entries.
108
+ */
109
+ totalCompressedSize: number;
110
+ /**
111
+ * Sum of uncompressed sizes of all entries.
112
+ */
113
+ totalUncompressedSize: number;
114
+ /**
115
+ * Global compression ratio (compressed / uncompressed).
116
+ */
117
+ compressionRatio: number;
118
+ /**
119
+ * True if any entry is marked encrypted.
120
+ */
121
+ hasEncryptedEntries: boolean;
122
+ /**
123
+ * Global archive comment.
124
+ */
125
+ comment?: string;
126
+ /**
127
+ * List of all entry summaries without decompression.
128
+ */
129
+ entries: ZipEntryInfo[];
130
+ }
131
+ /**
132
+ * Detailed validation verdict for a ZIP archive.
133
+ */
134
+ interface ZipValidationResult {
135
+ /**
136
+ * True if archive passed all structural and security checks.
137
+ */
138
+ valid: boolean;
139
+ /**
140
+ * List of errors encountered (path traversal, corrupted headers, bombs).
141
+ */
142
+ errors: string[];
143
+ /**
144
+ * Non-critical warnings (e.g. unknown compression methods, unrecognized extra fields).
145
+ */
146
+ warnings: string[];
147
+ /**
148
+ * Number of entries inspected.
149
+ */
150
+ entryCount: number;
151
+ /**
152
+ * Total compressed size.
153
+ */
154
+ totalCompressedSize: number;
155
+ /**
156
+ * Total uncompressed size.
157
+ */
158
+ totalUncompressedSize: number;
159
+ }
160
+ /**
161
+ * Security limits applied during inspection and extraction.
162
+ */
163
+ interface ZipSecurityLimits {
164
+ /**
165
+ * Maximum allowed entry count (default: 10,000).
166
+ */
167
+ maxEntries?: number;
168
+ /**
169
+ * Maximum allowed uncompressed size for any single entry in bytes (default: 250 MB).
170
+ */
171
+ maxEntrySize?: number;
172
+ /**
173
+ * Maximum allowed aggregate uncompressed size for all entries in bytes (default: 1 GB).
174
+ */
175
+ maxTotalSize?: number;
176
+ /**
177
+ * Maximum allowed compression ratio before rejecting as a zip bomb (default: 100:1).
178
+ */
179
+ maxCompressionRatio?: number;
180
+ /**
181
+ * Maximum archive input buffer size in bytes (default: 1 GB).
182
+ */
183
+ maxInputSize?: number;
184
+ }
185
+ /**
186
+ * Options for inspecting archive entries.
187
+ */
188
+ interface ZipInspectionOptions extends ZipSecurityLimits {
189
+ /**
190
+ * Optional AbortSignal to cancel inspection.
191
+ */
192
+ signal?: AbortSignal;
193
+ }
194
+ /**
195
+ * Options for extracting ZIP archives.
196
+ */
197
+ interface ZipExtractOptions extends ZipSecurityLimits {
198
+ /**
199
+ * Optional filter predicate to extract only matching entries.
200
+ */
201
+ filter?: (entry: ZipEntryInfo) => boolean;
202
+ /**
203
+ * Optional AbortSignal to cancel extraction.
204
+ */
205
+ signal?: AbortSignal;
206
+ }
207
+ /**
208
+ * Options for archive validation.
209
+ */
210
+ type ZipValidationOptions = ZipSecurityLimits;
211
+
212
+ declare const SIG_LOC = 67324752;
213
+ declare const SIG_CEN = 33639248;
214
+ declare const SIG_EOCD = 101010256;
215
+ declare function readU16LE(bytes: Uint8Array, offset: number): number;
216
+ declare function readU32LE(bytes: Uint8Array, offset: number): number;
217
+ /**
218
+ * Searches backwards for the End of Central Directory (EOCD) signature.
219
+ */
220
+ declare function findEocd(data: Uint8Array): number;
221
+ interface CentralDirectoryEntry extends ZipEntryInfo {
222
+ localHeaderOffset: number;
223
+ }
224
+ interface ParsedCentralDirectory {
225
+ entries: CentralDirectoryEntry[];
226
+ comment?: string;
227
+ eocdOffset: number;
228
+ totalCompressedSize: number;
229
+ totalUncompressedSize: number;
230
+ }
231
+ /**
232
+ * Parses the Central Directory of a ZIP archive in memory without decompressing file contents.
233
+ */
234
+ declare function parseCentralDirectory(data: Uint8Array, limits?: ZipSecurityLimits): ParsedCentralDirectory;
235
+ interface LocalHeaderInfo {
236
+ dataOffset: number;
237
+ compressedSize: number;
238
+ uncompressedSize: number;
239
+ compressionMethod: number;
240
+ crc32: number;
241
+ }
242
+ /**
243
+ * Reads local file header directly before an entry payload.
244
+ */
245
+ declare function readLocalHeader(data: Uint8Array, localHeaderOffset: number): LocalHeaderInfo;
246
+
247
+ /**
248
+ * Checks synchronously whether the given buffer has valid ZIP archive signatures.
249
+ */
250
+ declare function isZipArchiveSync(data: Uint8Array | ArrayBuffer): boolean;
251
+ /**
252
+ * Checks asynchronously whether the given binary data is a valid ZIP archive.
253
+ */
254
+ declare function isZipArchive(data: BinaryInput): Promise<boolean>;
255
+ /**
256
+ * Lists all entries in a ZIP archive by inspecting central directory metadata
257
+ * without decompressing file contents.
258
+ *
259
+ * @param data - The ZIP archive as Uint8Array, ArrayBuffer, Blob, or File.
260
+ * @param options - Inspection options and security limits.
261
+ * @returns Array of ZipEntryInfo objects.
262
+ */
263
+ declare function listZipEntries(data: BinaryInput, options?: ZipInspectionOptions): Promise<ZipEntryInfo[]>;
264
+ /**
265
+ * Gathers complete metadata and statistics of a ZIP archive without decompression.
266
+ */
267
+ declare function getZipMetadata(data: BinaryInput): Promise<ZipMetadata>;
268
+
269
+ /**
270
+ * Extracts all or filtered entries from a ZIP archive.
271
+ * Enforces strict Zip Slip protection, decompressed size limits, and CRC verification.
272
+ *
273
+ * @param data - ZIP archive as Uint8Array, ArrayBuffer, Blob, or File.
274
+ * @param options - Extraction options including filter, security limits, and cancellation.
275
+ * @returns Resolves to ExtractedZipArchive containing all extracted entries.
276
+ */
277
+ declare function extractZip(data: BinaryInput, options?: ZipExtractOptions): Promise<ExtractedZipArchive>;
278
+ /**
279
+ * Selectively extracts a single entry from a ZIP archive by path without decompressing other entries.
280
+ *
281
+ * @param data - ZIP archive as Uint8Array, ArrayBuffer, Blob, or File.
282
+ * @param path - Path of the target file to extract.
283
+ * @param options - Extraction options.
284
+ * @returns ExtractedZipEntry for the requested file.
285
+ * @throws ArchiveKitError if file is not found or fails decompression.
286
+ */
287
+ declare function extractZipEntry(data: BinaryInput, path: string, options?: ZipExtractOptions): Promise<ExtractedZipEntry>;
288
+
289
+ /**
290
+ * Validates a ZIP archive thoroughly for structural integrity, unsupported features, and security violations.
291
+ *
292
+ * @param data - ZIP archive as Uint8Array, ArrayBuffer, Blob, or File.
293
+ * @param options - Validation limits.
294
+ * @returns Detailed validation result with errors and warnings.
295
+ */
296
+ declare function validateZipArchive(data: BinaryInput, options?: ZipValidationOptions): Promise<ZipValidationResult>;
297
+
298
+ export { type CentralDirectoryEntry, type ExtractedZipArchive, type ExtractedZipEntry, type LocalHeaderInfo, type ParsedCentralDirectory, SIG_CEN, SIG_EOCD, SIG_LOC, type ZipEntryInfo, type ZipExtractOptions, type ZipInspectionOptions, type ZipMetadata, type ZipSecurityLimits, type ZipValidationOptions, type ZipValidationResult, extractZip, extractZipEntry, findEocd, getZipMetadata, isZipArchive, isZipArchiveSync, listZipEntries, parseCentralDirectory, readLocalHeader, readU16LE, readU32LE, validateZipArchive };