{"_id":"@bun-win32/vssapi","_rev":"3-2b0b41d8ddfbf232bbe96dade8e4b302","name":"@bun-win32/vssapi","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@bun-win32/vssapi","version":"1.0.0","keywords":["bun","ffi","win32","windows","vssapi","bindings","typescript","dll"],"author":"Stev Peifer <stev@bell.net>","license":"MIT","_id":"@bun-win32/vssapi@1.0.0","maintainers":[{"name":"obscuritysrl","email":"stev@bell.net"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"aa22f39abdf564fabb648c288f9febb4cb0417ed","tarball":"https://registry.npmjs.org/@bun-win32/vssapi/-/vssapi-1.0.0.tgz","fileCount":6,"integrity":"sha512-zgvuDu+yatMadBiExPK33tX5ICeQ20dcC6a253AcjMP370uRx5HHL/oxbECudJG5heC3cFoh3SZuCR+4YCwsEg==","signatures":[{"sig":"MEUCIGBcqSUbPRuGDBICgcWdga+I26rtEZey7kT6YHu52nrxAiEA996J/GN1XV7mAovw8lzbzwfzv45405FXpq9Sl4bXFT4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15825},"main":"./index.ts","type":"module","module":"index.ts","shasum":"aa22f39abdf564fabb648c288f9febb4cb0417ed","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:vss-writer-xray":"bun ./example/vss-writer-xray.ts","example:shadow-copy-inspector":"bun ./example/shadow-copy-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev@bell.net"},"_integrity":"sha512-zgvuDu+yatMadBiExPK33tX5ICeQ20dcC6a253AcjMP370uRx5HHL/oxbECudJG5heC3cFoh3SZuCR+4YCwsEg==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/vssapi"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 VSSAPI (Volume Shadow Copy Service) bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","dependencies":{"@bun-win32/core":"1.1.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/vssapi_1.0.0_1779222163578_0.1578543248344566","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@bun-win32/vssapi","version":"2.0.0","keywords":["bun","ffi","win32","windows","vssapi","bindings","typescript","dll"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/vssapi@2.0.0","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"a7b43435eea0b10696208371f7f0f4127d72c1aa","tarball":"https://registry.npmjs.org/@bun-win32/vssapi/-/vssapi-2.0.0.tgz","fileCount":6,"integrity":"sha512-u3EzA5Fk6k9dLCiiE9QXiS/DGmXbEeHDCcJdFcs8imbmEQecQGqEqdkWOlXOCDkPkmdYwmYNleAlQCnyDKiSRw==","signatures":[{"sig":"MEYCIQCy82i2YAAecBCYzdwjmvOwL57OxRq9UPJMsxyVTptjigIhAMPNdhyJg1Vi2RUMOiHntK4FVMoP0dDZj5+tV4FwMRTg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17142},"main":"./index.ts","type":"module","module":"index.ts","shasum":"a7b43435eea0b10696208371f7f0f4127d72c1aa","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:vss-writer-xray":"bun ./example/vss-writer-xray.ts","example:shadow-copy-inspector":"bun ./example/shadow-copy-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"_integrity":"sha512-u3EzA5Fk6k9dLCiiE9QXiS/DGmXbEeHDCcJdFcs8imbmEQecQGqEqdkWOlXOCDkPkmdYwmYNleAlQCnyDKiSRw==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/vssapi"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 VSSAPI (Volume Shadow Copy Service) bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.0","dependencies":{"@bun-win32/core":"2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/vssapi_2.0.0_1782435981327_0.9476625302775779","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"author":"Stev Peifer <stev.p@outlook.com>","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dependencies":{"@bun-win32/core":"2.0.1"},"description":"Zero-dependency, zero-overhead Win32 VSSAPI (Volume Shadow Copy Service) bindings for Bun (FFI) on Windows.","devDependencies":{"@types/bun":"latest"},"exports":{".":"./index.ts"},"license":"MIT","module":"index.ts","name":"@bun-win32/vssapi","peerDependencies":{"typescript":"^5"},"private":false,"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/vssapi"},"type":"module","version":"2.0.1","main":"./index.ts","keywords":["bun","ffi","win32","windows","vssapi","bindings","typescript","dll"],"sideEffects":false,"engines":{"bun":">=1.1.0"},"scripts":{"example:shadow-copy-inspector":"bun ./example/shadow-copy-inspector.ts","example:vss-writer-xray":"bun ./example/vss-writer-xray.ts"},"_id":"@bun-win32/vssapi@2.0.1","_integrity":"sha512-tGnR1WjF/SRWn2mkOr4wmcXIDPCgixJKToaXlBDXRs4a0+83gtDdotYhfUrLgb7vF+fko8zkeKPgafpR58cTmw==","_nodeVersion":"26.3.0","_npmVersion":"10.8.3","shasum":"9a368f48f28181b0b0195fa599a3d4ca17128607","dist":{"integrity":"sha512-tGnR1WjF/SRWn2mkOr4wmcXIDPCgixJKToaXlBDXRs4a0+83gtDdotYhfUrLgb7vF+fko8zkeKPgafpR58cTmw==","shasum":"9a368f48f28181b0b0195fa599a3d4ca17128607","tarball":"https://registry.npmjs.org/@bun-win32/vssapi/-/vssapi-2.0.1.tgz","fileCount":6,"unpackedSize":17142,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC8dlSYUTmKoEIgw5trvPHko/hdJGWk1d73rkTI2OZOlgIgCI3gNtIonIAaZh6APZ/AEqIk9KVnz85K4KM/G23wyMc="}]},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"directories":{},"maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vssapi_2.0.1_1782438206613_0.1590877205413379"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T20:22:43.423Z","modified":"2026-06-26T01:43:26.871Z","1.0.0":"2026-05-19T20:22:43.736Z","2.0.0":"2026-06-26T01:06:21.463Z","2.0.1":"2026-06-26T01:43:26.749Z"},"bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","homepage":"https://github.com/ObscuritySRL/bun-win32#readme","keywords":["bun","ffi","win32","windows","vssapi","bindings","typescript","dll"],"repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/vssapi"},"description":"Zero-dependency, zero-overhead Win32 VSSAPI (Volume Shadow Copy Service) bindings for Bun (FFI) on Windows.","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"readme":"# @bun-win32/vssapi\n\nZero-dependency, zero-overhead Win32 VSSAPI bindings for [Bun](https://bun.sh) on Windows.\n\n## Overview\n\n`@bun-win32/vssapi` exposes the `vssapi.dll` exports — the Volume Shadow Copy Service (VSS) backup engine — using [Bun](https://bun.sh)'s FFI. It provides a single class, `Vssapi`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.\n\nVSS is how Windows takes point-in-time, application-consistent snapshots of live volumes (it is what `vssadmin`, Windows Backup, and every serious backup product sit on top of). This package binds the documented flat C entry points: spin up the COM backup engine with `CreateVssBackupComponents`, examine writer metadata with `CreateVssExamineWriterMetadata`, ask whether a volume already has shadow copies with `IsVolumeSnapshotted`, check the revert-blocking policy with `ShouldBlockRevert`, and free snapshot-property memory with `VssFreeSnapshotProperties`. The real backup/restore surface is the COM `IVssBackupComponents` interface, reached by invoking its vtable on the pointer `CreateVssBackupComponents` hands back.\n\nThe bindings are strongly typed for a smooth DX in TypeScript.\n\n## Features\n\n- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.\n- Direct FFI to `vssapi.dll` (VSS backup engine, writer-metadata examination, volume snapshot status, revert-block policy, snapshot-property cleanup).\n- The documented `vsbackup.h` flat exports (under their real `*Internal` export names) plus the standard `DllCanUnloadNow` / `DllGetClassObject` COM-server entries.\n- In-source docs in `structs/Vssapi.ts` with links to Microsoft Docs.\n- Lazy binding on first call; optional eager preload (`Vssapi.Preload()`).\n- No wrapper overhead; calls map 1:1 to native APIs.\n- Strongly-typed Win32 aliases plus the `VSS_SNAPSHOT_STATE`, `VSS_SNAPSHOT_COMPATIBILITY`, and `VSS_VOLUME_SNAPSHOT_ATTRIBUTES` enums (see `types/Vssapi.ts`).\n\n## Requirements\n\n- [Bun](https://bun.sh) runtime\n- Windows 10 or later\n- Most VSS operations require an elevated (Administrator) process.\n\n## Installation\n\n```sh\nbun add @bun-win32/vssapi\n```\n\n## Quick Start\n\n```ts\nimport Vssapi from '@bun-win32/vssapi';\nimport Ole32 from '@bun-win32/ole32';\n\n// VSS requires COM to be initialized first.\nOle32.CoInitialize(null);\n\n// Does the C: volume already have any shadow copies?\nconst volume = Buffer.from('C:\\\\\\0', 'utf16le');\nconst present = Buffer.alloc(4);\nconst capability = Buffer.alloc(4);\n\nconst hr = Vssapi.IsVolumeSnapshotted(volume.ptr!, present.ptr!, capability.ptr!);\nif (hr === 0) {\n  console.log('Shadow copies present:', present.readInt32LE(0) !== 0);\n  console.log('Snapshot compatibility bitmask:', capability.readInt32LE(0));\n} else {\n  // 0x80070005 = E_ACCESSDENIED — run elevated.\n  console.log('IsVolumeSnapshotted → 0x' + (hr >>> 0).toString(16));\n}\n```\n\n> [!NOTE]\n> AI agents: see `AI.md` for the package binding contract and source-navigation guidance. It explains how to use the package without scanning the entire implementation.\n\n## Examples\n\nRun the included examples:\n\n```sh\nbun run example:shadow-copy-inspector\nbun run example:vss-writer-xray\n```\n\n- **shadow-copy-inspector** — a thorough diagnostic: enumerates every fixed volume on the system, then for each one decodes `IsVolumeSnapshotted` (shadow copies present? which volume-control operations are disabled via the `VSS_SNAPSHOT_COMPATIBILITY` bitmask) and `ShouldBlockRevert`, all rendered as an aligned report with every HRESULT decoded by name and graceful E_ACCESSDENIED handling.\n- **vss-writer-xray** — a live, animated reveal driven entirely over the COM vtable: `CreateVssBackupComponents` boots the VSS backup engine, `InitializeForBackup` + `GatherWriterMetadata` (awaited through an `IVssAsync`) gathers every registered VSS writer, and `GetWriterMetadataCount` / `GetWriterMetadata` / `IVssExamineWriterMetadata::GetIdentity` X-rays each writer's name, class/instance GUID, usage and source type — strict `IUnknown::Release` teardown throughout.\n\n## Notes\n\n- Call `Ole32.CoInitialize` (or `CoInitializeEx`) before using any VSS export.\n- The documented functions are exported under `*Internal` names (e.g. `CreateVssBackupComponentsInternal`); the SDK header `#define`s the documented name to the `*Internal` export. This package binds the real export names.\n- `CreateVssBackupComponents` returns an `IVssBackupComponents*` as an opaque `bigint`; drive the backup/restore surface by invoking its vtable, and always `IUnknown::Release` it when done.\n- Nearly all VSS calls require an elevated process and the backup privilege; without it expect `E_ACCESSDENIED` (`0x80070005`).\n- Either rely on lazy binding or call `Vssapi.Preload()`.\n- Windows only. Bun runtime required.\n- **SAL types & naming:** nullability is in the **type** — `Optional<T>` (formally optional, SAL `_*opt_`) and `Nullable<T>` (plain `[in]`/`[out]` the docs say can be NULL), the null sentinel derived from `T` (`null` for pointers `LP*`/`P*`, `0n` for handles/by-value addresses); direction is in the **parameter name** — `_out` (`_Out_`), `_in_out` (`_Inout_`), `_In_` bare. See `AI.md` and the repo `AGENTS.md`.\n","readmeFilename":"README.md"}